SRV-24 — Support module — tickets & announcements
Tickets with types, related order and items, messages and internal notes, assignment and statuses; announcements with targeting; support contacts/FAQ; support regions with WhatsApp numbers resolved from the declared region or device location.
| Field | Details |
|---|---|
| Task code | SRV-24 |
| Phase | P1 — V1 build & integration |
| Product scope | V1 |
| Status | Done (Mon 19 Oct 2026) |
| Start | Mon 19 Oct 2026 |
| Due | Mon 19 Oct 2026 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | — |
| Effort | 0.75 person-day(s) planned · 3 from scratch · size S |
| Area · app | Server · server |
| Depends on | SRV-08 |
| Unblocks | SRV-20, DSH-10, MOB-12, SRV-40 |
| Milestones | — |
Summary
Tickets with types, related order and items, messages and internal notes, assignment and statuses; announcements with targeting; support contacts/FAQ; support regions with WhatsApp numbers resolved from the declared region or device location.
Description
Support replaces informal WhatsApp exchanges with traceable tickets while keeping WhatsApp as the human channel (cahier §2.1, §5, §6.1; SUP-01…SUP-03, SUP-05, NOT-07, ADM-08). This task implements tickets (TKT-YYYY-NNNNNN) with TicketType (including AFTER_SALES claims carrying TicketItem order lines, quantities, AfterSalesIssue and photos), the TicketStatus lifecycle, messages with attachments and staff-only internal notes, assignment and the support.autoClose job; announcements with targeting and read tracking; support contacts and FAQ; and the regional WhatsApp support of decision 8: SupportRegion (WhatsApp number, hours, default flag) grouping wilayas through SupportRegionWilaya, admin.supportRegions.crud, and support.whatsapp (auth: optional) that resolves the region from the signed-in user's declared wilaya, otherwise from device coordinates (nearest commune → wilaya → region), otherwise from a chosen wilaya or the default region. Out of scope: after-sales resolution (SRV-20) and support pages (DSH-10).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Ticket model service: tickets.create (type, related order, items for AFTER_SALES, issue, attachments), list, get, reply, close; TKT numbering | Anis |
| 2 | AFTER_SALES validation: order belongs to the reseller, items and quantities within the order, at least one photo when the issue is DEFECTIVE or DAMAGED | Anis |
| 3 | Back-office handling admin.tickets.list/get/reply/update: assignment, internal notes, status transitions, notifications | Anis |
| 4 | Job support.autoClose after support.autoCloseDays (default 7) with reminder at half the delay | Anis |
| 5 | Announcements: admin.announcements.crud/send with audience (delegates, resellers, zone, wilaya, segment, customer type) and schedule; announcements.list/markRead | Anis |
| 6 | support.contacts and FAQ content (editable reference content) | Anis |
| 7 | SupportRegion and SupportRegionWilaya services with admin.supportRegions.crud (each wilaya in exactly one region, one default region) | Anis |
| 8 | support.whatsapp resolver: declared wilaya → device lat/lng (nearest commune) → wilayaCode param → default; returns number, wa.me link with prefilled message, hours and isOpenNow | Anis |
| 9 | Ticket and announcement events to the reseller and back-office streams and notifications | Anis |
Deliverables
- apps/server/src/modules/support/{tickets,announcements,contacts,regions,whatsapp}.{service,router}.ts and jobs.ts
- packages/contracts/src/{support.ts,admin/support.ts}
- Default support region seed and FAQ seed content
Acceptance criteria
- An AFTER_SALES ticket on another reseller's order returns 404 NOT_FOUND; quantities above the ordered quantity return 422 VALIDATION_FAILED (SUP-04)
- Internal notes are never returned by reseller endpoints (SUP-02)
- A signed-in reseller whose declared wilaya is in region West receives the West WhatsApp number regardless of device location (SUP-05)
- A guest sending coordinates in Constantine gets the East region number; without coordinates or wilaya the default number is returned (SUP-05)
- Saving a region map that leaves a wilaya unassigned or assigns it twice returns 422 VALIDATION_FAILED (ADM-08)
- An announcement targeted to delegates of one zone appears only in their announcements.list (NOT-07)
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| SUP-01 | Reseller tickets: type, related order, message, attachments, conversation, statuses | V1 |
| SUP-02 | Back-office ticket handling: assignment, internal notes, replies, statuses, notifications | V1 |
| SUP-03 | Support contacts and FAQ | V1 |
| NOT-07 | Announcements from the back-office to delegates or resellers by target ('Messages') | V1 |
| SUP-05 | Regional WhatsApp support: a fixed WhatsApp button in both reseller apps opens the support number of the user's region — declared region when signed in, device location otherwise | V1 |
| ADM-08 | Support regions: wilayas grouped into regions, each with its WhatsApp support number and hours | V1 |
Screens
API surface
| Endpoint group | Operations |
|---|---|
| Support tickets | 7 |
| Notifications & announcements | 10 |
| Support & communication | 10 |
Test measures
- Unit tests for the WhatsApp resolution order with fixtures per case
- DB tests for ticket lifecycle and auto-close with a fake clock
- Contract test that reseller ticket schemas have no internal-note fields
Risks
- Regional numbers change often — regions editable in BO-70 and support.whatsapp responses cached for at most 5 minutes
KPI
- Delivered by Mon 19 Oct 2026 within 0.75 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
SRV-18 — Billing V1 — invoices, payments, declarations, credit control
Invoices with legal mentions and statuses, payment recording and reseller declarations with proof, allocations, credit limit/exposure used at checkout, reseller finance summary.
SRV-20 — Returns & after-sales (SAV) module
Return requests on delivered orders, approval, reception with automatic RETURN stock movements, credit notes; after-sales claims as tickets on order items with photos, resolved by replacement order, return, credit note, repair or rejection.