# Client Detail Redesign — Backend & Data Foundation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the data + repo layer the redesigned Client Detail page needs — per-module onboarding templates, a milestone→status auto-drive, milestone↔payment links, an extended ledger (outstanding + allocations), and a bulk-SMS-purchase document path — with a one-time migration that moves existing SMS/RTGS/Mobile-App projects onto their new step lists without losing ticks.

**Architecture:** Everything is a plain exported function taking the `DB` handle first (portable-repo pattern). Onboarding step lists are DB `setting` rows resolved by module code (config over code). Schema changes are additive `ALTER TABLE` in `migrate()` (SQLite) mirrored in `migrations-pg.ts` (Postgres). No money math changes — the ledger extension only *reads* existing `payment_allocation` / `document` rows. Every mutation writes an audit row in the same transaction.

**Tech Stack:** TypeScript (strict), `better-sqlite3` (dev) / Postgres (prod), Express, Vitest.

## Global Constraints

- Money is integer paise; never introduce floats. This plan touches **no** billing math (`computeBill`, allocation) — the ledger extension reads existing columns only.
- Config over code, dated: onboarding step lists are `setting` rows, never code constants (the code default is a fallback only).
- Append-only audit: every mutation calls `writeAudit(db, userId, action, entity, id, before, after)` in the same `db.transaction`.
- Portable SQL: no engine-specific SQL beyond the existing `ON CONFLICT … DO NOTHING` upsert idiom already used in `seed.ts`. Schema changes land in BOTH `apps/hq/src/db.ts` (`migrate()`, SQLite) and `apps/hq/src/migrations-pg.ts` (Postgres).
- Strict TS, green before landing: `npm run typecheck` and `npm test` clean before anything lands.
- Run all commands from the repo root `C:/SiMS/hq`. Tests: `npm test --workspace @sims/hq` (vitest). Typecheck: `npm run typecheck`.

---

## File Structure

- `apps/hq/src/repos-milestones.ts` — MODIFY: per-module template resolution; step→status auto-drive; `payment_id` on tick; stalled-projects query.
- `apps/hq/src/repos-modules.ts` — MODIFY: `ensureProjectMilestones` call site already lives here (assignment); no change unless noted.
- `apps/hq/src/seed.ts` — MODIFY: seed per-module template settings (SMS / RTGS / Mobile App).
- `apps/hq/src/db.ts` — MODIFY: `project_milestone.payment_id` column (SQLite `migrate()`); `client_module` module-code lookup helper if needed.
- `apps/hq/src/migrations-pg.ts` — MODIFY: mirror the `payment_id` column for Postgres.
- `apps/hq/src/migrate-onboarding-templates.ts` — CREATE: the one-time, idempotent milestone-swap migration function.
- `apps/hq/scripts/migrate-onboarding-templates.ts` — CREATE: thin CLI wrapper that opens the DB and runs the migration (mirrors `scripts/apply-name-fixes.ts`).
- `apps/hq/src/repos-payments.ts` — MODIFY: extend `clientLedger` with `outstanding` + per-payment `allocations`.
- `apps/hq/src/repos-documents.ts` — MODIFY: make `source` a settable draft field (default unchanged).
- `apps/hq/src/repos-renewals.ts` — MODIFY: tag the renewal proforma `source='module_renewal'`; ADD `generateBulkSmsPurchaseQuote`.
- `apps/hq/src/api.ts` — MODIFY: route for bulk-SMS-purchase; ledger route already returns `clientLedger` (shape widens automatically).
- Tests under `apps/hq/test/` — one file per task as noted.

---

## Task 1: Per-module onboarding template resolution

**Files:**
- Modify: `apps/hq/src/repos-milestones.ts`
- Test: `apps/hq/test/milestones-templates.test.ts`

**Interfaces:**
- Produces: `milestoneTemplate(db: DB, moduleCode?: string): Promise<TemplateEntry[]>` — resolves `project.milestone_template:<CODE>` → `project.milestone_template` → `FALLBACK_TEMPLATE`.
- Produces: `ensureProjectMilestones(db: DB, clientModuleId: string): Promise<void>` — now resolves the template by the client_module's module code.

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/milestones-templates.test.ts`:

```ts
import { describe, it, expect, beforeEach } from 'vitest'
import { openDb, type DB } from '../src/db'
import { milestoneTemplate } from '../src/repos-milestones'

describe('per-module milestone templates', () => {
  let db: DB
  beforeEach(async () => { db = await openDb(':memory:') })

  it('falls back to the global template when no module-specific one exists', async () => {
    await db.run(`INSERT INTO setting (key, value) VALUES ('project.milestone_template', ?)`,
      JSON.stringify([{ key: 'a', label: 'A' }]))
    expect(await milestoneTemplate(db, 'SMS')).toEqual([{ key: 'a', label: 'A' }])
  })

  it('prefers the module-specific template over the global one', async () => {
    await db.run(`INSERT INTO setting (key, value) VALUES ('project.milestone_template', ?)`,
      JSON.stringify([{ key: 'a', label: 'A' }]))
    await db.run(`INSERT INTO setting (key, value) VALUES ('project.milestone_template:SMS', ?)`,
      JSON.stringify([{ key: 'doc', label: 'Document collection' }]))
    expect(await milestoneTemplate(db, 'SMS')).toEqual([{ key: 'doc', label: 'Document collection' }])
    // A different module still gets the global one.
    expect(await milestoneTemplate(db, 'RTGS')).toEqual([{ key: 'a', label: 'A' }])
  })

  it('falls back to the code default when nothing is seeded', async () => {
    const t = await milestoneTemplate(db, 'SMS')
    expect(t.map((e) => e.key)).toContain('go_live')
  })
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- milestones-templates`
Expected: FAIL — `milestoneTemplate` does not accept a module code / does not read the `:CODE` key.

- [ ] **Step 3: Implement the resolution**

In `apps/hq/src/repos-milestones.ts`, replace `milestoneTemplate` and update `ensureProjectMilestones`:

```ts
/** The checklist for a module (owner-editable per module via setting; global default; code fallback). */
export async function milestoneTemplate(db: DB, moduleCode?: string): Promise<TemplateEntry[]> {
  const parse = (value: string): TemplateEntry[] | undefined => {
    try {
      const p = JSON.parse(value) as TemplateEntry[]
      return Array.isArray(p) && p.length > 0 ? p : undefined
    } catch { return undefined }
  }
  if (moduleCode !== undefined && moduleCode !== '') {
    const perModule = await db.get<{ value: string }>(
      `SELECT value FROM setting WHERE key=?`, `project.milestone_template:${moduleCode}`)
    const parsed = perModule !== undefined ? parse(perModule.value) : undefined
    if (parsed !== undefined) return parsed
  }
  const row = await db.get<{ value: string }>(`SELECT value FROM setting WHERE key='project.milestone_template'`)
  const parsedGlobal = row !== undefined ? parse(row.value) : undefined
  return parsedGlobal ?? FALLBACK_TEMPLATE
}
```

Then update `ensureProjectMilestones` to resolve by module code:

```ts
export async function ensureProjectMilestones(db: DB, clientModuleId: string): Promise<void> {
  const cm = await db.get<{ module_code: string }>(
    `SELECT m.code AS module_code FROM client_module cm JOIN module m ON m.id = cm.module_id WHERE cm.id=?`,
    clientModuleId)
  const template = await milestoneTemplate(db, cm?.module_code)
  const existing = new Set(
    (await db.all<{ key: string }>(`SELECT key FROM project_milestone WHERE client_module_id=?`, clientModuleId))
      .map((r) => r.key),
  )
  await db.transaction(async () => {
    let sort = 0
    for (const t of template) {
      if (!existing.has(t.key)) {
        await db.run(
          `INSERT INTO project_milestone (id, client_module_id, key, label, done, done_on, sort)
           VALUES (?, ?, ?, ?, 0, NULL, ?)`,
          uuidv7(), clientModuleId, t.key, t.label, sort,
        )
      }
      sort++
    }
  })
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- milestones-templates`
Expected: PASS (3 tests).

- [ ] **Step 5: Typecheck + commit**

```bash
npm run typecheck
git add apps/hq/src/repos-milestones.ts apps/hq/test/milestones-templates.test.ts
git commit -m "feat(onboarding): resolve milestone template per module (config over code)"
```

---

## Task 2: Seed per-module onboarding templates

**Files:**
- Modify: `apps/hq/src/seed.ts`
- Test: `apps/hq/test/seed-templates.test.ts`

**Interfaces:**
- Consumes: `milestoneTemplate` (Task 1).
- Produces: seeded settings `project.milestone_template:SMS|RTGS|MOBILEAPP`. (Confirm the Mobile App module code with `SELECT code FROM module` during Step 3; the mockup assumes `MOBILEAPP` — adjust the key to the real code.)

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/seed-templates.test.ts`:

```ts
import { describe, it, expect, beforeEach } from 'vitest'
import { openDb, type DB } from '../src/db'
import { seedIfEmpty } from '../src/seed'
import { milestoneTemplate } from '../src/repos-milestones'

describe('seed per-module onboarding templates', () => {
  let db: DB
  beforeEach(async () => { db = await openDb(':memory:'); await seedIfEmpty(db) })

  it('seeds the SMS 9-step list', async () => {
    const keys = (await milestoneTemplate(db, 'SMS')).map((e) => e.key)
    expect(keys).toEqual([
      'document_collection', 'dlt_registration', 'account_creation', 'installation',
      'testing', 'training', 'go_live', 'advance_payment', 'balance_payment',
    ])
  })

  it('seeds the RTGS list ending in payment steps', async () => {
    const keys = (await milestoneTemplate(db, 'RTGS')).map((e) => e.key)
    expect(keys).toEqual([
      'document_collection', 'server_checkup', 'setup_configuration', 'installation',
      'testing', 'training', 'go_live', 'advance_payment', 'balance_payment',
    ])
  })
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- seed-templates`
Expected: FAIL — per-module templates not seeded (falls back to global keys).

- [ ] **Step 3: Add the seed block**

In `apps/hq/src/seed.ts`, after the existing `project.milestone_template` seed (line ~101), add:

```ts
  // Per-module onboarding templates (config over code). SMS/RTGS/Mobile App differ; each ends
  // with advance + balance payment so a payment tick maps cleanly on migration.
  const PER_MODULE_TEMPLATES: Record<string, { key: string; label: string }[]> = {
    SMS: [
      { key: 'document_collection', label: 'Document collection' },
      { key: 'dlt_registration', label: 'DLT registration' },
      { key: 'account_creation', label: 'Account creation & registration' },
      { key: 'installation', label: 'Installation' },
      { key: 'testing', label: 'Testing' },
      { key: 'training', label: 'Training' },
      { key: 'go_live', label: 'Go-live' },
      { key: 'advance_payment', label: 'Advance payment' },
      { key: 'balance_payment', label: 'Balance payment' },
    ],
    RTGS: [
      { key: 'document_collection', label: 'Document collection' },
      { key: 'server_checkup', label: 'Server checkup' },
      { key: 'setup_configuration', label: 'Setup & configuration' },
      { key: 'installation', label: 'Installation' },
      { key: 'testing', label: 'Testing' },
      { key: 'training', label: 'Training' },
      { key: 'go_live', label: 'Go-live' },
      { key: 'advance_payment', label: 'Advance payment' },
      { key: 'balance_payment', label: 'Balance payment' },
    ],
    MOBILEAPP: [
      { key: 'requirement_setup', label: 'Requirement & setup' },
      { key: 'configuration', label: 'Configuration' },
      { key: 'data_import', label: 'Data import' },
      { key: 'installation', label: 'Installation' },
      { key: 'testing', label: 'Testing' },
      { key: 'training', label: 'Training' },
      { key: 'go_live', label: 'Go-live' },
      { key: 'advance_payment', label: 'Advance payment' },
      { key: 'balance_payment', label: 'Balance payment' },
    ],
  }
  let seededPerModule = 0
  for (const [code, list] of Object.entries(PER_MODULE_TEMPLATES)) {
    seededPerModule += (await db.run(
      INSERT_SETTING_SQL, `project.milestone_template:${code}`, JSON.stringify(list))).changes
  }
  if (seededPerModule > 0) {
    await writeAudit(db, 'system', 'seed', 'setting', 'project.milestone_template:*', undefined,
      { modules: Object.keys(PER_MODULE_TEMPLATES) })
  }
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- seed-templates`
Expected: PASS. Also run `npm test --workspace @sims/hq -- milestones-templates` — still green.

- [ ] **Step 5: Commit**

```bash
npm run typecheck
git add apps/hq/src/seed.ts apps/hq/test/seed-templates.test.ts
git commit -m "feat(onboarding): seed SMS/RTGS/MobileApp onboarding templates"
```

---

## Task 3: Milestone→status auto-drive + go-live

**Files:**
- Modify: `apps/hq/src/repos-milestones.ts` (`setMilestone`)
- Test: `apps/hq/test/milestone-status.test.ts`

**Interfaces:**
- Consumes: `setMilestone(db, userId, clientModuleId, key, done, doneOn?)` (existing signature unchanged).
- Produces: a module-status advance side-effect keyed by a `STEP_STATUS` map, written in the same transaction and audited.

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/milestone-status.test.ts`. Use the existing test helpers to create a client + module + client_module (copy the setup from `apps/hq/test/tickets.test.ts` which already builds a `client_module`). Assert:

```ts
// after seeding milestones for an SMS client_module at status 'quoted':
it('ticking installation advances status to installed', async () => {
  await setMilestone(db, 'u1', cmId, 'installation', true)
  const cm = await getClientModule(db, cmId)
  expect(cm!.status).toBe('installed')
})

it('ticking go_live advances status to live', async () => {
  await setMilestone(db, 'u1', cmId, 'go_live', true)
  expect((await getClientModule(db, cmId))!.status).toBe('live')
})

it('unticking never downgrades status', async () => {
  await setMilestone(db, 'u1', cmId, 'go_live', true)
  await setMilestone(db, 'u1', cmId, 'go_live', false)
  expect((await getClientModule(db, cmId))!.status).toBe('live')
})

it('a lower step never downgrades a higher status', async () => {
  await setMilestone(db, 'u1', cmId, 'go_live', true)      // live
  await setMilestone(db, 'u1', cmId, 'installation', true) // still live
  expect((await getClientModule(db, cmId))!.status).toBe('live')
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- milestone-status`
Expected: FAIL — status stays `quoted`.

- [ ] **Step 3: Implement the auto-drive**

In `apps/hq/src/repos-milestones.ts`, add the map and fold the advance into `setMilestone`'s transaction (after the `UPDATE project_milestone` and its audit, before `return`):

```ts
/** Ticking a step can advance the coarse client_module.status — never downgrade. Ranks match
 *  the status CHECK order: quoted<ordered<installing<installed<trained<live<expired<cancelled. */
const STATUS_RANK: Record<string, number> = {
  quoted: 0, ordered: 1, installing: 2, installed: 3, trained: 4, live: 5, expired: 6, cancelled: 7,
}
const STEP_STATUS: Record<string, string> = {
  installation: 'installed', training: 'trained', go_live: 'live',
}

async function advanceStatusForStep(db: DB, userId: string, clientModuleId: string, key: string): Promise<void> {
  const target = STEP_STATUS[key]
  if (target === undefined) return
  const cm = await db.get<{ status: string }>(`SELECT status FROM client_module WHERE id=?`, clientModuleId)
  if (cm === undefined) return
  if ((STATUS_RANK[cm.status] ?? 0) >= (STATUS_RANK[target] ?? 0)) return // never downgrade
  await db.run(`UPDATE client_module SET status=? WHERE id=?`, target, clientModuleId)
  await writeAudit(db, userId, 'update', 'client_module', clientModuleId, { status: cm.status }, { status: target })
}
```

Inside `setMilestone`, after the milestone `writeAudit` and before `return listProjectMilestones(...)`, add:

```ts
    if (done) await advanceStatusForStep(db, userId, clientModuleId, key)
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- milestone-status`
Expected: PASS (4 tests).

- [ ] **Step 5: Commit**

```bash
npm run typecheck
git add apps/hq/src/repos-milestones.ts apps/hq/test/milestone-status.test.ts
git commit -m "feat(onboarding): status line auto-drives client_module.status (never downgrades)"
```

---

## Task 4: `payment_id` on milestone + link on payment-step tick

**Files:**
- Modify: `apps/hq/src/db.ts` (`migrate()` SQLite) and `apps/hq/src/migrations-pg.ts` (Postgres)
- Modify: `apps/hq/src/repos-milestones.ts` (`Milestone` type, `listProjectMilestones`, `setMilestone` optional `paymentId`)
- Modify: `apps/hq/src/api.ts` (accept `paymentId` in the milestone POST body)
- Test: `apps/hq/test/milestone-payment.test.ts`

**Interfaces:**
- Produces: `setMilestone(db, userId, clientModuleId, key, done, doneOn?, paymentId?)` — when a payment step is ticked with a `paymentId`, stores it and mirrors the payment's `received_on` into `done_on`.
- Produces: `Milestone` gains `paymentId: string | null`.

- [ ] **Step 1: Add the column (schema, both engines)**

In `apps/hq/src/db.ts` `migrate()`, alongside the other `PRAGMA table_info` blocks, add:

```ts
  const milestoneCols = db.prepare(`PRAGMA table_info(project_milestone)`).all() as { name: string }[]
  if (!milestoneCols.some((c) => c.name === 'payment_id')) {
    db.exec(`ALTER TABLE project_milestone ADD COLUMN payment_id TEXT`)
  }
```

In `apps/hq/src/migrations-pg.ts`, mirror it (follow the file's existing additive-migration idiom — an `ALTER TABLE project_milestone ADD COLUMN IF NOT EXISTS payment_id text`).

- [ ] **Step 2: Write the failing test**

Create `apps/hq/test/milestone-payment.test.ts` (reuse the client_module setup + record a payment via `recordPayment`):

```ts
it('linking a payment to advance_payment stores payment_id and mirrors received_on', async () => {
  const pay = await recordPayment(db, 'u1', {
    clientId, receivedOn: '2026-05-01', mode: 'bank', amountPaise: 1000_00,
  })
  await setMilestone(db, 'u1', cmId, 'advance_payment', true, undefined, pay.payment.id)
  const ms = (await listProjectMilestones(db, cmId)).find((m) => m.key === 'advance_payment')!
  expect(ms.done).toBe(true)
  expect(ms.doneOn).toBe('2026-05-01')
  expect(ms.paymentId).toBe(pay.payment.id)
})
```

- [ ] **Step 3: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- milestone-payment`
Expected: FAIL — `setMilestone` has no `paymentId` param; `Milestone` has no `paymentId`.

- [ ] **Step 4: Implement**

In `repos-milestones.ts`:
- Add `paymentId: string | null` to `interface Milestone` and to `MilestoneRow` (`payment_id: string | null`).
- Include `payment_id` in the `SELECT` of `listProjectMilestones` and map it: `paymentId: r.payment_id`.
- Extend `setMilestone` signature with a trailing `paymentId?: string`. When `done` and `paymentId` is provided, resolve the payment's `received_on` and use it as the stamp, and set `payment_id`:

```ts
export async function setMilestone(
  db: DB, userId: string, clientModuleId: string, key: string, done: boolean,
  doneOn?: string, paymentId?: string,
): Promise<Milestone[]> {
  return db.transaction(async () => {
    const before = await db.get<MilestoneRow>(
      `SELECT key, label, done, done_on, sort, payment_id FROM project_milestone WHERE client_module_id=? AND key=?`,
      clientModuleId, key)
    if (before === undefined) throw new Error('Milestone not found on this project')
    if (done && doneOn !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(doneOn)) {
      throw new Error('doneOn must be YYYY-MM-DD')
    }
    let stamp = done ? (doneOn ?? new Date().toISOString().slice(0, 10)) : null
    let linkedPayment: string | null = null
    if (done && paymentId !== undefined && paymentId !== '') {
      const pay = await db.get<{ received_on: string }>(
        `SELECT received_on FROM payment WHERE id=? AND client_id=(SELECT client_id FROM client_module WHERE id=?)`,
        paymentId, clientModuleId)
      if (pay === undefined) throw new Error('Payment not found for this client')
      linkedPayment = paymentId
      if (doneOn === undefined) stamp = pay.received_on // link date wins unless caller forced one
    }
    await db.run(
      `UPDATE project_milestone SET done=?, done_on=?, payment_id=? WHERE client_module_id=? AND key=?`,
      done ? 1 : 0, stamp, done ? linkedPayment : null, clientModuleId, key)
    await writeAudit(db, userId, 'set_milestone', 'client_module', clientModuleId, undefined,
      { key, done, doneOn: stamp, paymentId: linkedPayment })
    if (done) await advanceStatusForStep(db, userId, clientModuleId, key)
    return listProjectMilestones(db, clientModuleId)
  })
}
```

In `api.ts` milestone POST route, read `paymentId` from the body and pass it through:

```ts
      const milestones = await setMilestone(db, staffId(res), id, body.key, body.done,
        typeof body.doneOn === 'string' ? body.doneOn : undefined,
        typeof (body as { paymentId?: unknown }).paymentId === 'string' ? (body as { paymentId?: string }).paymentId : undefined)
```

- [ ] **Step 5: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- milestone-payment milestone-status milestones-templates`
Expected: PASS (all).

- [ ] **Step 6: Commit**

```bash
npm run typecheck
git add apps/hq/src/db.ts apps/hq/src/migrations-pg.ts apps/hq/src/repos-milestones.ts apps/hq/src/api.ts apps/hq/test/milestone-payment.test.ts
git commit -m "feat(onboarding): link advance/balance payment steps to real payments"
```

---

## Task 5: One-time migration — swap seeded modules onto new templates, preserve ticks

**Files:**
- Create: `apps/hq/src/migrate-onboarding-templates.ts`
- Create: `apps/hq/scripts/migrate-onboarding-templates.ts`
- Test: `apps/hq/test/migrate-onboarding-templates.test.ts`

**Interfaces:**
- Produces: `migrateOnboardingTemplates(db: DB): Promise<{ projects: number; carried: number; dropped: number }>` — idempotent; for every client_module whose module has a per-module template setting, replaces the old rows with the module's template, carrying mapped ticks (`done` + `done_on` + `payment_id`).

**Mapping (old generic key → new key):** `installed→installation`, `go_live→go_live`, `advance_paid→advance_payment`, `balance_paid→balance_payment`, `setup_done→setup_configuration` (only if the new template has that key). Old keys with no mapped target (e.g. `amc_start`, or `setup_done` for SMS) are dropped and counted.

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/migrate-onboarding-templates.test.ts`:

```ts
import { describe, it, expect, beforeEach } from 'vitest'
import { openDb, type DB } from '../src/db'
import { seedIfEmpty } from '../src/seed'
import { migrateOnboardingTemplates } from '../src/migrate-onboarding-templates'
import { listProjectMilestones } from '../src/repos-milestones'
// + helpers to create an SMS client_module and seed the OLD generic milestones on it

describe('onboarding template migration', () => {
  let db: DB
  beforeEach(async () => { db = await openDb(':memory:'); await seedIfEmpty(db) })

  it('swaps an SMS project to the 9-step list carrying installed+go_live ticks', async () => {
    const cmId = /* create SMS client_module */ ''
    // seed OLD generic rows with two ticked:
    for (const [i, r] of [
      ['advance_paid', 0, null], ['setup_done', 0, null], ['installed', 1, '2026-03-25'],
      ['go_live', 1, '2026-04-02'], ['balance_paid', 0, null], ['amc_start', 0, null],
    ].entries()) {
      await db.run(`INSERT INTO project_milestone (id,client_module_id,key,label,done,done_on,sort)
        VALUES (?,?,?,?,?,?,?)`, `m${i}`, cmId, r[0], String(r[0]), r[1], r[2], i)
    }
    const res = await migrateOnboardingTemplates(db)
    expect(res.projects).toBe(1)
    const ms = await listProjectMilestones(db, cmId)
    expect(ms.map((m) => m.key)).toEqual([
      'document_collection','dlt_registration','account_creation','installation',
      'testing','training','go_live','advance_payment','balance_payment'])
    const installation = ms.find((m) => m.key === 'installation')!
    expect(installation.done).toBe(true)
    expect(installation.doneOn).toBe('2026-03-25')
    expect(ms.find((m) => m.key === 'go_live')!.done).toBe(true)
    // old setup_done / amc_start gone:
    expect(ms.some((m) => m.key === 'setup_done' || m.key === 'amc_start')).toBe(false)
  })

  it('is idempotent (second run changes nothing new)', async () => {
    /* run twice; assert the milestone set is identical after each */
  })

  it('leaves a module without a per-module template untouched', async () => {
    /* create a client_module for a module with NO :CODE setting; assert its rows unchanged */
  })
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- migrate-onboarding-templates`
Expected: FAIL — module `migrate-onboarding-templates` does not exist.

- [ ] **Step 3: Implement the migration**

Create `apps/hq/src/migrate-onboarding-templates.ts`:

```ts
import { uuidv7 } from '@sims/domain'
import { writeAudit } from './audit'
import { milestoneTemplate } from './repos-milestones'
import type { DB } from './db'

/** old generic key → new template key (only applied if the new template has that key). */
const KEY_MAP: Record<string, string> = {
  installed: 'installation', go_live: 'go_live',
  advance_paid: 'advance_payment', balance_paid: 'balance_payment',
  setup_done: 'setup_configuration',
}

interface OldRow { key: string; done: number; done_on: string | null; payment_id: string | null }

/**
 * Idempotent: for every client_module whose module has a per-module onboarding template,
 * rebuild its milestone rows from that template, carrying mapped ticks (done/done_on/payment_id).
 * Unmapped old ticks are dropped (counted). Modules with no per-module template are untouched.
 */
export async function migrateOnboardingTemplates(db: DB): Promise<{ projects: number; carried: number; dropped: number }> {
  // Which module codes have a per-module template setting?
  const codes = (await db.all<{ key: string }>(
    `SELECT key FROM setting WHERE key LIKE 'project.milestone_template:%'`))
    .map((r) => r.key.slice('project.milestone_template:'.length))
  let projects = 0, carried = 0, dropped = 0
  for (const code of codes) {
    const template = await milestoneTemplate(db, code)
    const templateKeys = new Set(template.map((t) => t.key))
    const cms = await db.all<{ id: string }>(
      `SELECT cm.id FROM client_module cm JOIN module m ON m.id = cm.module_id WHERE m.code=?`, code)
    for (const { id: cmId } of cms) {
      const oldRows = await db.all<OldRow>(
        `SELECT key, done, done_on, payment_id FROM project_milestone WHERE client_module_id=?`, cmId)
      // Build the carried tick-state keyed by NEW key.
      const carriedState = new Map<string, OldRow>()
      let alreadyNew = true
      for (const r of oldRows) {
        if (!templateKeys.has(r.key)) alreadyNew = false
        const target = templateKeys.has(r.key) ? r.key : KEY_MAP[r.key]
        if (target !== undefined && templateKeys.has(target)) {
          if (r.done === 1) carriedState.set(target, r)
        } else if (r.done === 1) {
          dropped++
        }
      }
      // Idempotency: if the project's keys already ARE exactly the template, skip.
      const oldKeySet = new Set(oldRows.map((r) => r.key))
      const identical = alreadyNew && oldKeySet.size === templateKeys.size
        && [...templateKeys].every((k) => oldKeySet.has(k))
      if (identical) continue
      projects++
      await db.transaction(async () => {
        await db.run(`DELETE FROM project_milestone WHERE client_module_id=?`, cmId)
        let sort = 0
        for (const t of template) {
          const c = carriedState.get(t.key)
          await db.run(
            `INSERT INTO project_milestone (id, client_module_id, key, label, done, done_on, payment_id, sort)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
            uuidv7(), cmId, t.key, t.label,
            c !== undefined ? 1 : 0, c?.done_on ?? null, c?.payment_id ?? null, sort)
          if (c !== undefined) carried++
          sort++
        }
        await writeAudit(db, 'system', 'migrate_onboarding', 'client_module', cmId, undefined,
          { module: code, carried: [...carriedState.keys()] })
      })
    }
  }
  return { projects, carried, dropped }
}
```

- [ ] **Step 4: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- migrate-onboarding-templates`
Expected: PASS (3 tests).

- [ ] **Step 5: Create the CLI wrapper**

Create `apps/hq/scripts/migrate-onboarding-templates.ts` (mirror `scripts/apply-name-fixes.ts` open-DB pattern):

```ts
import { openDb } from '../src/db'
import { migrateOnboardingTemplates } from '../src/migrate-onboarding-templates'

async function main(): Promise<void> {
  const db = await openDb(process.env['HQ_DB_PATH'] ?? 'data/hq.db')
  const res = await migrateOnboardingTemplates(db)
  console.log(`onboarding migration: ${res.projects} project(s) rebuilt, ${res.carried} tick(s) carried, ${res.dropped} dropped`)
}
main().catch((e) => { console.error(e); process.exit(1) })
```

- [ ] **Step 6: Commit**

```bash
npm run typecheck
git add apps/hq/src/migrate-onboarding-templates.ts apps/hq/scripts/migrate-onboarding-templates.ts apps/hq/test/migrate-onboarding-templates.test.ts
git commit -m "feat(onboarding): one-time migration swapping seeded modules to new templates (ticks preserved)"
```

---

## Task 6: Extend the ledger with outstanding + per-payment allocations

**Files:**
- Modify: `apps/hq/src/repos-payments.ts` (`ClientLedger`, `clientLedger`)
- Modify: `apps/hq-web/src/api.ts` (`Ledger`, `Payment` types — web mirror)
- Test: `apps/hq/test/ledger-outstanding.test.ts`

**Interfaces:**
- Produces: `ClientLedger` gains
  `outstanding: { docId: string; docNo: string | null; docType: string; label: string; outstandingPaise: number }[]`
  and each `Payment` in the ledger gains `allocations: { docNo: string; amountPaise: number }[]`.
- Consumes: existing `outstandingPaise(db, docId)` (already exported in `repos-payments.ts`).

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/ledger-outstanding.test.ts`. Build a client with one issued INVOICE (partly paid) and one open PROFORMA; record a payment; then:

```ts
it('reports outstanding open documents oldest-first with correct due amounts', async () => {
  const led = await clientLedger(db, clientId)
  expect(led.outstanding.map((o) => o.docNo)).toEqual(['INV-0001']) // proforma optional; see label rule
  expect(led.outstanding[0]!.outstandingPaise).toBe(/* payable - allocated - credited */ 0)
})

it('attaches allocations to each payment', async () => {
  const led = await clientLedger(db, clientId)
  const p = led.payments[0]!
  expect(p.allocations.reduce((s, a) => s + a.amountPaise, 0)).toBeLessThanOrEqual(p.amountPaise + p.tdsPaise)
})
```

(Fill in exact expected paise from the fixture you build — pick round amounts so the assertions are concrete.)

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- ledger-outstanding`
Expected: FAIL — `outstanding` / `allocations` undefined.

- [ ] **Step 3: Implement the extension**

In `apps/hq/src/repos-payments.ts`, widen the interface and `clientLedger`:

```ts
export interface LedgerOutstanding {
  docId: string; docNo: string | null; docType: string; label: string; outstandingPaise: number
}
export interface LedgerPayment extends Payment { allocations: { docNo: string; amountPaise: number }[] }
export interface ClientLedger {
  documents: Doc[]; payments: LedgerPayment[]; advancePaise: number; outstanding: LedgerOutstanding[]
}
```

In `clientLedger`, after building `documents`:

```ts
  // Per-payment allocations (docNo + amount) for the "Settled → document" column.
  const allocRows = await db.all<{ payment_id: string; doc_no: string | null; amount_paise: number }>(
    `SELECT a.payment_id, d.doc_no, a.amount_paise
     FROM payment_allocation a JOIN document d ON d.id = a.document_id
     JOIN payment p ON p.id = a.payment_id WHERE p.client_id=?`, clientId)
  const allocByPayment = new Map<string, { docNo: string; amountPaise: number }[]>()
  for (const r of allocRows) {
    const list = allocByPayment.get(r.payment_id) ?? []
    list.push({ docNo: r.doc_no ?? '—', amountPaise: r.amount_paise })
    allocByPayment.set(r.payment_id, list)
  }
  const ledgerPayments: LedgerPayment[] = payments.map((p) => ({ ...p, allocations: allocByPayment.get(p.id) ?? [] }))

  // Open documents with money still owed — issued invoices (outstanding > 0) + open proformas.
  const moduleName = async (doc: Doc): Promise<string> =>
    doc.payload.lines.map((l) => l.name).filter((n) => n !== '').join(', ')
  const outstanding: LedgerOutstanding[] = []
  for (const d of documents) {
    if (d.status === 'cancelled' || d.status === 'paid' || d.status === 'lost') continue
    if (d.docType === 'INVOICE' && d.docNo !== null) {
      const out = await outstandingPaise(db, d.id)
      if (out > 0) outstanding.push({ docId: d.id, docNo: d.docNo, docType: d.docType, label: await moduleName(d), outstandingPaise: out })
    } else if (d.docType === 'PROFORMA' && (d.status === 'sent' || d.status === 'accepted' || d.status === 'draft')) {
      outstanding.push({ docId: d.id, docNo: d.docNo, docType: d.docType, label: await moduleName(d), outstandingPaise: d.payablePaise })
    }
  }
  outstanding.sort((a, b) => (a.docNo ?? '').localeCompare(b.docNo ?? ''))
```

Return `{ documents, payments: ledgerPayments, advancePaise: settling - row.total, outstanding }`.

- [ ] **Step 4: Mirror the web types**

In `apps/hq-web/src/api.ts`, update `Payment` (add `allocations: { docNo: string; amountPaise: number }[]`) and `Ledger` (add `outstanding: { docId: string; docNo: string | null; docType: string; label: string; outstandingPaise: number }[]`).

- [ ] **Step 5: Run tests + typecheck**

Run: `npm test --workspace @sims/hq -- ledger-outstanding` → PASS.
Run: `npm test --workspace @sims/hq` (full suite — confirm the 416 existing tests stay green; the ledger shape only widened). `npm run typecheck` clean.

- [ ] **Step 6: Commit**

```bash
git add apps/hq/src/repos-payments.ts apps/hq-web/src/api.ts apps/hq/test/ledger-outstanding.test.ts
git commit -m "feat(payments): ledger exposes outstanding docs + per-payment allocations"
```

---

## Task 7: Bulk-SMS-purchase document + source tagging

**Files:**
- Modify: `apps/hq/src/repos-documents.ts` (`DraftInput.source?`, `insertDocRow` source, INSERT column)
- Modify: `apps/hq/src/repos-renewals.ts` (`source='module_renewal'`; ADD `generateBulkSmsPurchaseQuote`)
- Modify: `apps/hq/src/api.ts` (POST route for bulk SMS purchase)
- Test: `apps/hq/test/bulk-sms-purchase.test.ts`

**Interfaces:**
- Produces: `generateBulkSmsPurchaseQuote(db, userId, clientModuleId, smsQty): Promise<Doc>` — a PROFORMA priced via the usage rate card for `smsQty` SMS, `source='bulk_sms_topup'`.
- Produces: `createDraft` accepts optional `source` (default preserves current behaviour); documents carry it for the frontend's Quote/Renewal/Bulk-top-up label.

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/bulk-sms-purchase.test.ts`. Set up an SMS module with a usage rate card (copy the rate-card setup from an existing rate-card test), an SMS client_module, then:

```ts
it('raises a proforma tagged bulk_sms_topup for the given SMS quantity', async () => {
  const doc = await generateBulkSmsPurchaseQuote(db, 'u1', cmId, 100000)
  expect(doc.docType).toBe('PROFORMA')
  expect(doc.source).toBe('bulk_sms_topup')
  expect(doc.payload.lines[0]!.qty).toBe(100000)
  expect(doc.payablePaise).toBeGreaterThan(0)
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- bulk-sms-purchase`
Expected: FAIL — `generateBulkSmsPurchaseQuote` not exported.

- [ ] **Step 3: Make `source` settable on a draft**

In `apps/hq/src/repos-documents.ts`:
- Add `source?: string` to `interface DraftInput`.
- Thread it into `insertDocRow`: add `source?: string` to its param object, add `source` to the INSERT column list + a `?` placeholder, and pass `a.source ?? 'manual'` (confirm the schema default; keep current behaviour when omitted). In `createDraft`, pass `source: input.source` into `insertDocRow`.

```ts
// insertDocRow INSERT — add `source` column:
`INSERT INTO document (id, doc_type, doc_no, fy, client_id, doc_date, due_date, status, ref_doc_id,
   taxable_paise, cgst_paise, sgst_paise, igst_paise, round_off_paise, payable_paise,
   payload, source, created_by, created_at)
 VALUES (?, ?, NULL, ?, ?, ?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
// ...bind a.source ?? 'manual' in the source position.
```

- [ ] **Step 4: Add the generator + tag the renewal**

In `apps/hq/src/repos-renewals.ts`, tag the existing renewal proforma and add the bulk generator:

```ts
export async function generateModuleRenewalQuote(db: DB, userId: string, clientModuleId: string): Promise<Doc> {
  const cm = await getClientModule(db, clientModuleId)
  if (cm === null) throw new Error('Client module not found')
  return createDraft(db, userId, {
    docType: 'PROFORMA', clientId: cm.clientId, source: 'module_renewal',
    lines: [{ moduleId: cm.moduleId, qty: 1, kind: cm.kind, edition: cm.edition }],
  })
}

/** Ad-hoc bulk SMS credit purchase — a PROFORMA priced by the usage rate card for `smsQty` units. */
export async function generateBulkSmsPurchaseQuote(
  db: DB, userId: string, clientModuleId: string, smsQty: number,
): Promise<Doc> {
  if (!Number.isInteger(smsQty) || smsQty <= 0) throw new Error('SMS quantity must be a positive integer')
  const cm = await getClientModule(db, clientModuleId)
  if (cm === null) throw new Error('Client module not found')
  return createDraft(db, userId, {
    docType: 'PROFORMA', clientId: cm.clientId, source: 'bulk_sms_topup',
    lines: [{ moduleId: cm.moduleId, qty: smsQty, kind: cm.kind, edition: cm.edition }],
  })
}
```

- [ ] **Step 5: Add the API route**

In `apps/hq/src/api.ts`, near the other document routes, add:

```ts
  r.post('/client-modules/:id/bulk-sms-quote', requireAuth, async (req, res) => {
    try {
      const qty = Number((req.body as { smsQty?: unknown }).smsQty)
      const doc = await generateBulkSmsPurchaseQuote(db, staffId(res), String(req.params['id'] ?? ''), qty)
      res.json({ ok: true, document: doc })
    } catch (err) {
      res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) })
    }
  })
```

Import `generateBulkSmsPurchaseQuote` alongside `generateModuleRenewalQuote`.

- [ ] **Step 6: Run tests + full suite**

Run: `npm test --workspace @sims/hq -- bulk-sms-purchase` → PASS.
Run: `npm test --workspace @sims/hq` → all green (source default preserved the existing document tests). `npm run typecheck` clean.

- [ ] **Step 7: Commit**

```bash
git add apps/hq/src/repos-documents.ts apps/hq/src/repos-renewals.ts apps/hq/src/api.ts apps/hq/test/bulk-sms-purchase.test.ts
git commit -m "feat(sms): bulk SMS purchase proforma + document source tagging (renewal vs top-up)"
```

---

## Task 8: Stalled-onboarding query

**Files:**
- Modify: `apps/hq/src/repos-milestones.ts`
- Modify: `apps/hq/src/api.ts` (route)
- Test: `apps/hq/test/stalled-onboarding.test.ts`

**Interfaces:**
- Produces: `stalledProjects(db: DB, olderThanDays: number, today: string): Promise<PendingProject[]>` — active projects whose earliest pending step's most recent done_on (or module creation) is older than N days, i.e. parked. Reuses the `PendingProject` shape.

- [ ] **Step 1: Write the failing test**

Create `apps/hq/test/stalled-onboarding.test.ts`: build an active SMS project with early steps done on an old date and later steps pending; assert it appears for a small `olderThanDays` and not for a large one.

```ts
it('lists a project parked past the threshold', async () => {
  // last done_on = 2026-03-01, today = 2026-07-19 → ~140 days
  const stalled = await stalledProjects(db, 30, '2026-07-19')
  expect(stalled.map((p) => p.clientModuleId)).toContain(cmId)
})
it('excludes a recently-progressed project', async () => {
  const stalled = await stalledProjects(db, 365, '2026-07-19')
  expect(stalled).toHaveLength(0)
})
```

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test --workspace @sims/hq -- stalled-onboarding`
Expected: FAIL — `stalledProjects` not exported.

- [ ] **Step 3: Implement**

In `apps/hq/src/repos-milestones.ts`:

```ts
/** Active projects with at least one pending step whose progress last moved > olderThanDays ago. */
export async function stalledProjects(db: DB, olderThanDays: number, today: string): Promise<PendingProject[]> {
  const rows = await db.all<PendingProject & { last_done: string | null }>(
    `SELECT pm.client_module_id AS "clientModuleId", cm.client_id AS "clientId",
            c.name AS "clientName", m.code AS "moduleCode", m.name AS "moduleName",
            MAX(pm.done_on) AS last_done
     FROM project_milestone pm
     JOIN client_module cm ON cm.id = pm.client_module_id
     JOIN client c ON c.id = cm.client_id
     JOIN module m ON m.id = cm.module_id
     WHERE cm.active = 1 AND cm.status NOT IN ('live','expired','cancelled')
     GROUP BY pm.client_module_id
     HAVING SUM(CASE WHEN pm.done = 0 THEN 1 ELSE 0 END) > 0`,
  )
  const cutoff = new Date(Date.parse(today) - olderThanDays * 86400_000).toISOString().slice(0, 10)
  return rows
    .filter((r) => (r.last_done ?? '0000-00-00') < cutoff)
    .map(({ last_done: _l, ...rest }) => rest)
}
```

In `api.ts` add a route: `r.get('/projects/stalled', requireAuth, …)` reading an `?days=` query (default from a `project.stall_days` setting, fallback 30) and `new Date().toISOString().slice(0,10)` for today.

- [ ] **Step 4: Run tests to verify they pass**

Run: `npm test --workspace @sims/hq -- stalled-onboarding` → PASS.

- [ ] **Step 5: Commit**

```bash
npm run typecheck
git add apps/hq/src/repos-milestones.ts apps/hq/src/api.ts apps/hq/test/stalled-onboarding.test.ts
git commit -m "feat(onboarding): stalled-project query for the dashboard/MIS tile"
```

---

## Backend plan self-review

- **Spec coverage:** §2 templates → T1/T2; §3 migration → T5; §7.1 status auto-drive → T3; §7.2 payment link → T4; §5 ledger → T6; §4a bulk SMS + §7.3 doc source → T7; §7.4 stalled → T8. Per-module Documents (§4) is pure frontend (client-side filter) — no backend task, handled in Plan 2.
- **Type consistency:** `milestoneTemplate(db, moduleCode?)`, `setMilestone(..., doneOn?, paymentId?)`, `ClientLedger.outstanding` / `LedgerPayment.allocations`, `generateBulkSmsPurchaseQuote(db, userId, cmId, smsQty)`, `stalledProjects(db, days, today)` — names used consistently across tasks and into Plan 2.
- **Placeholder scan:** test fixtures marked "fill in exact paise" (T6) and the client_module setup helpers (T3–T8) reference the existing `apps/hq/test/tickets.test.ts` setup — the implementer copies that concrete setup; not a code placeholder in shipped source.
- **Verify before done:** every task ends with `npm test` for its file plus `npm run typecheck`; T6 and T7 additionally run the full suite because they touch shared read/write paths.

**Confirm before building:** the Mobile App module `code` (assumed `MOBILEAPP`) — check `SELECT code, name FROM module` and set the seed key + migration to the real code.