From 7d5223908fd2f73e6dd845982c0066fd813f9da9 Mon Sep 17 00:00:00 2001 From: Thomas Joise Date: Fri, 17 Jul 2026 18:58:44 +0530 Subject: [PATCH] =?UTF-8?q?docs(spec):=20D20=20APEX=20parity=20slice=20?= =?UTF-8?q?=E2=80=94=20ticket=20desk,=20service=20data,=20branches,=20impo?= =?UTF-8?q?rter=20v2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Survey verdicts for all 25 real APEX tables; founder calls locked: full ticket desk (4,567-ticket history), client_module service columns (provider/username/password_enc/details), client_branch, five modules = SMS, RTGS, WhatsApp, Mobile App, ATM. Co-Authored-By: Claude Fable 5 --- .../specs/2026-07-17-apex-parity-design.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-17-apex-parity-design.md diff --git a/docs/superpowers/specs/2026-07-17-apex-parity-design.md b/docs/superpowers/specs/2026-07-17-apex-parity-design.md new file mode 100644 index 0000000..69d3b11 --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-apex-parity-design.md @@ -0,0 +1,67 @@ +# HQ Console — APEX Parity Slice (Ticket Desk, Service Data, Branches, Full Importer) — D20 + +> **STATUS: IN BUILD, started 2026-07-17.** Driven by the real APEX export in `C:\SiMS\hq\Apex` +> (25 tables surveyed). Founder calls locked via review: full ticket desk YES; client_module +> service-data extension YES; client_branch YES; the five modules are **SMS, RTGS, WhatsApp, +> Mobile App, ATM**. + +## 1. What the APEX data taught us (survey verdicts) + +| APEX table (rows) | Verdict | Lands as | +|---|---|---| +| `sims_clients_list` (273) | carry | `client` (all support fields exist); YES/NO service flags → `client_module` rows | +| `sims_client_sector` (30) | carry-lite | sector text + UI suggestions | +| `sims_ho_branch_list` (251) | **new table** | `client_branch` | +| `sims_bill_filed` (269) | carry | `document` history + **payment + allocation rows** from PAYMENT_DATE/AMOUNT | +| `sims_invoices` / `_items` (0) | skip | APEX's unfinished redesign — our schema already is it | +| `sims_invoice_type` / `_billing_head` / `payment_status` / `lov_group` / `app_control` | skip | our CHECK enums / roles cover them | +| `sims_new_ticket` (4,567) | **new feature** | `ticket` table + Tickets page + history import | +| `sims_ticket_trigger_log` (15k) / `ticket_report` (42) | skip | audit_log covers; report is a snapshot | +| `sims_sms_project_list` (636) / `rtgs_project_list` (146) | carry | `client_module` status + descriptions → `interaction` rows | +| `sims_sms_clients_list` (107) | carry | `client_module` service columns + details | +| `sims_sms_client_modules` (255) | carry | active alert types → `client_module.details` | +| `sims_sms_features` (6) / `sms_provider` (4) | carry-lite | settings (`sms.provider..url`) + details vocabulary | +| `sims` (1) / `next_val` (1) | carry-lite | company settings check; INVOICE series seed | +| `sims_calander_event` (13) / `temp_report_data` (1) | skip | demo/scratch rows | + +APEX stores the client DB password AND SMS portal passwords in plaintext; import encrypts both +(AES-256-GCM, HQ_SECRET_KEY) — cutover closes a real hole. + +## 2. Schema (additive, both engines) + +| Change | Notes | +|---|---| +| `ticket` table | `id, client_id, branch_id NULL, module_code NULL ('SMS','RTGS',…), kind, description, status CHECK ('open','in_progress','waiting','closed','dropped'), assigned_to NULL → staff_user, online_offline NULL, opened_on, closed_on NULL, created_by, created_at, source` | +| `client_branch` table | `id, client_id, name, code NULL, active 0/1` | +| `client_module` + | `provider NULL, username NULL, password_enc NULL, details TEXT '[]' (JSON [{label,value}]), remark NULL` | +| sqlite `migrate()` guards + pg migration `002-apex-parity` | same DDL discipline as D19 | + +## 3. Behavior + +- **Tickets page** (WORK nav): chips `Open · In progress · Waiting · Closed`, Mine/All + (managerial), assign dropdown, status actions, new-ticket dialog (client type-ahead, branch + select, module, kind, description). Client 360 gains a Tickets tab. All mutations audited; + honest pagination. Kinds are free text with suggestions from history (config over code). +- **Module card / roster**: service columns (provider/username/•••• password with audited + reveal, gated managerial like the DB password) + editable labeled details. +- **Importer v2** (`import-apex.ts`, staged like v1, owner-only, same UI): reads the xlsx-derived + CSVs — clients (+flags→modules, sector, secretary contact), branches, bill_filed (documents, + QT/PI/INV mapping, GST split by client state, payments+allocations, `SMS/2024/…` legacy numbers, + series seed from numeric tail), tickets (status mapping CLOSED→closed etc.), sms/rtgs service + data → client_module columns+details, project lists → module status + interaction rows. + Every row staged with per-row problems; commit refuses while any problem exists. +- **Numbers**: rupee amounts in APEX (incl. fractional per-unit rates like ₹0.16) convert via + `fromRupees` to integer paise at the staging edge. + +## 4. Non-goals + +TA/leave (HR — permanently out per D16), APEX page-ACL parity, trigger-log import, SMS *sending*. + +## 5. Build order (suite green each phase) + +1. Schema + repos (ticket, branch, module extensions) with tests +2. API routes + gating (tickets CRUD/assign/status; branches; module service data + reveal) +3. Web: Tickets page + nav + Client 360 tab; module card service data; branch list +4. Importer v2 + tests (fixture CSVs cut from the real export shapes) +5. Trial import of the real export into local Postgres; reconciliation report (counts + ₹ totals vs APEX) +6. Docs + D-record