Customer-Brain + Flexible Routing — ເອກະສານເຕັກນິກສຳລັບ developer

01 ສະຖາປັດຕະຍະກຳ — North-Star loop 4 ຂັ້ນ ແມັບໂມດູນຈິງ

North Star: "ຄົນຂັບບັນທຶກເທື່ອດຽວຕອນເຮັດວຽກ → ຫຼັງບ້ານເຫັນຄວາມຈິງ real-time → ຮອບຕໍ່ໄປ plan ແມ່ນຂຶ້ນເອງ." ວົງຈอน stage4→1→2 ປັດຈຸບັນ ຂາດ (ບໍ່ persist recency, ບໍ່ເກັບ GPS ຕอนส่ง).

02 Data-model reality

ສະຖານະຈິງຂອງແຕ່ລະ field (verify ກັບ backend/prisma/schema.prisma) ແລະ ສ່ວນທີ່ Block A ກ່ຽວຂ້ອງ.

03 Gap analysis R1–R10

effort: S=ມື້ · M=1-2 ອາທິດ · L=multi-week.

04 Block A — ການແກ້ໂຄ້ດ (schema / migration / diff)

ການແກ້ໃນ branch feat/a0-customer-brain-capture — files + migration + diff ດ້ານລຸ່ມ. (tsc --noEmit ຜ່ານ 0 error · otplib 12 + @sentry/node 10 ຕິດຕັ້ງຄົບ ບໍ່ມີ type/peer conflict — ບໍ່ແມ່ນບັນຫາແລ້ວ)

4.1 · schema diff

// Customer-brain capture (Block A)
  lastReceivedDate    DateTime?
  deliveryCount       Int      @default(0)
  ...
  @@index([tenantId, lastReceivedDate])

  deliveringUserId    String?   @db.Uuid
  ...
  deliveringUser User? @relation("DeliveryRunOrderDeliveredBy", fields: [deliveringUserId], references: [id], onDelete: SetNull)
  ...
  @@index([deliveringUserId])

  deliveredRunOrders DeliveryRunOrder[] @relation("DeliveryRunOrderDeliveredBy")

4.2 · migration SQL

ALTER TABLE "Customer" ADD COLUMN "lastReceivedDate" TIMESTAMP(3);
ALTER TABLE "Customer" ADD COLUMN "deliveryCount" INTEGER NOT NULL DEFAULT 0;
ALTER TABLE "DeliveryRunOrder" ADD COLUMN "deliveringUserId" UUID;

CREATE INDEX "Customer_tenantId_lastReceivedDate_idx" ON "Customer"("tenantId", "lastReceivedDate");
CREATE INDEX "DeliveryRunOrder_deliveringUserId_idx" ON "DeliveryRunOrder"("deliveringUserId");
ALTER TABLE "DeliveryRunOrder" ADD CONSTRAINT "DeliveryRunOrder_deliveringUserId_fkey"
  FOREIGN KEY ("deliveringUserId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;

-- backfill: lastReceivedDate = latest COMPLETED delivery (walk-ins excluded)
UPDATE "Customer" c SET "lastReceivedDate" = sub.maxd
FROM (SELECT "customerId", MAX("deliveredAt") AS maxd FROM "Order"
  WHERE "status"='COMPLETED' AND "deliveredAt" IS NOT NULL AND "customerId" IS NOT NULL
  GROUP BY "customerId") sub WHERE c."id" = sub."customerId";

4.3 · service diff — deliverOrder()

  data: {
    status: DELIVERY_RUN_ORDER_STATUS.DELIVERED,
    deliveredAt: new Date(), attemptedAt: new Date(),
    deliveringUserId: currentUser.sub,                 // who actually delivered
    ...(dto.podPhotoUrl !== undefined ? { podPhotoUrl: dto.podPhotoUrl || null } : {}),
    ...(dto.podSignatureUrl !== undefined ? { podSignatureUrl: dto.podSignatureUrl || null } : {}),
    ...(dto.deliveredLatitude !== undefined ? { deliveredLatitude: dto.deliveredLatitude } : {}),
    ...(dto.deliveredLongitude !== undefined ? { deliveredLongitude: dto.deliveredLongitude } : {}),
  },

  data: {
    totalPurchaseCount: { increment: 1 }, isFirstTimeCustomer: false,
    // FIRST delivery only — re-record (admin correction) ບໍ່ advance/ບໍ່ນັບຊ້ຳ
    ...(isReRecord ? {} : { lastReceivedDate: new Date(), deliveryCount: { increment: 1 } }),
  },

  orderId,
  driverId: order.deliveryRun?.crew?.[0]?.userId ?? null,   // OLD: crew[0]
  driverId: currentUser.sub,                                // NEW: acting user (pay-follows-work)

  @IsOptional() @Type(() => Number) @IsNumber() @Min(-90)  @Max(90)  deliveredLatitude?: number;
  @IsOptional() @Type(() => Number) @IsNumber() @Min(-180) @Max(180) deliveredLongitude?: number;

05 ແຜນ build 4 ອາທິດ (Block A end-to-end + B/C groundwork)

1 ເດືອນ ship Block A + ວາງ data-capture ໃຫ້ B/C. OUT: Service Score engine ເຕັມ, cross-branch rescue, OSRM/OR-Tools optimizer (gate: GPS≥80% + ≥8 verified rounds — ວັນนี้ວັດบ่ได้).

5.1 · task table (master checklist)

ເอกสารแผนเต็ม (migration plan, risk register 22 ข้อ, DoD): docs/FLEXIBLE_ROUTING_BUILD_PLAN.md

5b ตารางรายวัน + เวลา (day-by-day)

ประเมิน ~2 devs เต็มเวลา = ~4 สัปดาห์ (20 วันทำงาน) · 1 dev ≈ 8 สัปดาห์ · L=3–4 วัน · M=2 · S=1 · XS=0.5 · บางวันแยก 2 track (A/B) ขนาน · เวลาเป็นประมาณ

เริ่ม 22/06/2026 · ทำ 7 วัน/สัปดาห์ ไม่มีวันพัก (วันที่ไล่ติดกัน). A0 keystone ของจริงทำ 1 วัน (แผนเดิม 5.5) → นำหน้า ~4 วัน. Track A (มื้ 1-13) จบ ~04/07/2026 · ประเมินตามจริง ไม่บีบ. ทุก PR ผ่าน /loo-check + tsc (CI = tsc+jest+e2e · lint ยังไม่ gate). แอปคนขับ = ทำใหม่ทั้งหมดด้วย Flutter (§5c · เฟสถัดไป).

5c Track B — Driver Mobile App (V2) · ລວມຕາมมติรวมงาน

มติ: ทำแอปคนขับใหม่ทั้งหมดด้วย Flutter (ทิ้งเดโม/โค้ดเก่า Capacitor+React · V2_DRIVER_APP/app.html v0.22 = UX reference เท่านั้น) → scope = เต็มตามเดโมทุกฟีเจอร์ · backend loop ของคนขับมีแล้ว (reuse ได้) · ดู capacity §5c.3.

5c.1 · Reconciliation — เดโมคนขับ ↔ โค้ดจริง (EXISTS / net-new)

เดโม screen (8): login(emp+PIN) → shift/pre-trip 4 ขั้น(check-in→ยิง crew ขึ้นรถ→ตรวจรถ 7 จุด+ไมล์+รูป→โหลดน้ำ) → run(progress ring+เงินสด+ถัง+quickbar) → stop "จบในจอเดียว"(brain chips+stepper+promo+ชำระ 4+ถังคืน+มัดจำ+รูป+ยืนยัน) → POD(recap+ใบเสร็จ QR) → map → money(4 ก้อน drill-down) → me(leaderboard+points+redeem+myPay+ปิดกะ). หลักออกแบบ 3: ① บันทึกครั้งเดียวตอนทำงาน ② จบในจอเดียว ③ มือถือคือ GPS · + offline-first (เส้นตาย) · ปุ่มใหญ่มือเดียว ลาว 100%.

5c.2 · Track B task list (wire-existing + net-new)

18 task · L=3.5 / M=2 / S=1 person-days → Track B (Flutter ทำใหม่ทั้งหมด) ≈ ~45 person-days. โค้ด Capacitor/React เดิมไม่นับ · wire=ต่อ backend ที่มี (เร็ว) · net-new=สร้างโมดูลใหม่ (ช้า). ถ้าต้องตัดเพื่อเฟสแรก → net-new (POS/fuel/leaderboard/mypay/offline/notify) คือกลุ่มที่เลื่อนได้.

5c.3 · capacity reality — 2 track เต็ม / 2 dev / 1 เดือน พอไหม?

GPS ตลอดกะ (จอดับ/ในกระเป๋า) = ต้อง native → Flutter ได้ background-GPS + Bluetooth printer/scanner ดีกว่า PWA. แอปทำใหม่ทั้งหมดด้วย Flutter · backend loop ของคนขับมีแล้ว (reuse endpoint ได้เลย).

06 Demo vs real code — authoritative-truth map

ກฎ: demo = UX target · live repo = law. ຂັດກັນ → ຍຶດ live code. ເດໂມ (V2_DEMO_LOOP/index.html 2.18MB, V2_DRIVER_APP/app.html 271KB) = vanilla JS + Leaflet 1.9.4 + OSRM.

6.2 · เดโม web-loop (V2_DEMO_LOOP) — UX spec + constants ที่ลอกได้

เดโมหลังบ้าน V2_DEMO_LOOP/index.html (2.18MB · 60 รอบ design) = spec ของ ops-map งาน Track A. ลอก: ดีไซน์/สเกล/สี/flow/สูตร · ทำใหม่: ทุกอย่างที่แตะแผนที่ (Leaflet→Google Maps).

6.1 · enum / data-contract (เสี่ยงสูงสุด — ต้อง honor)

07 source_code/ snapshot vs LIVE repo

• snapshot cut ≈ 2026-06-08 (last migration 20260608000000_subscription_product_optional) — same project, additive subset.
• live ahead 25 migrations (20260609 → 20260622100000_driver_pin_auth) + 3 modules: customer-departments, health, stock-counts · zero snapshot-only items.
• Block A lands ONLY in live. deliveredLatitude/Longitude ມีก่อน Block A ใน 4 snapshot files.
• live + @sentry/node + otplib (MFA 20260617120000) · schema 4,048 → 4,359 lines · 96 models · 153 migrations รวม (20260328→20260622) · 70 modules · 87 services · tsc --noEmit ผ่าน 0 error.
• source_code/docs/* ເກ່າກວ່າໂຄ້ดตัวเอง. อ่าน snapshot ເพื่อ orientation · ຢ່າแก้ · build บน live repo.

08 Seed dataset — _SEED_DATA/

• deterministic (random.seed(20260620)) · ~51 tables / ~206k rows / 5,000 ลูกค้าเวียงจันทน์ (พิกัดอาคารจริง) · Apr–Jun 2026.
• big: transactions(31,925), transaction_items(35,361), delivery_run_orders(31,476 + POD), loyalty_transactions(30,885), asset_movements(19,413), payment_collections(18,477), driver_locations(3,871), customer_photos(3,000), settlements(1,297).
• realism: data-mined จาก VARI Drive จริง · products.json = 11 SKU จริง + ราคา/GM%/deposit.
• customers.csv ships last_received_date + total_orders → forward-compatible กับ Block A.
• demo consumes positional JS arrays (LOO_CUSTDATA, LOO_ORD, LOO_CUSTPTS, LOO_DASH) ไม่ใช่ CSV · CSV = standalone fixture, ยังไม่ wired.

09 Landmines / conventions (ต้อง honor)

1. GPS-at-delivery trap: ຂຽນ GPS ໃນ deliverOrder ໂดยตรง · ຢ່าผ่าน updateStopStatus (reject DELIVERED on not-COMPLETED, :398-405).
2. Order.status ບໍ່ມี DELIVERED — DELIVERED อยู่บน DeliveryRunOrder (/loo-check สแกน).
3. AuditInterceptor global (APP_INTERCEPTOR) — ห้าม @UseInterceptors(AuditInterceptor) ต่อ method. path ที่มองไม่เห็น → AuditService.record().
4. tenant+branch isolation ทุก query (TenantScope.whereWithBranch) — R4/R6 cross-branch ต้อง carve-out + audit. เคารพ isCustomerBranchScopeExempt. มี ESLint rule (no-restricted-syntax) บังคับ tenantId ใน service where-clause กัน cross-tenant — แต่ ยังไม่ถูกรันใน CI · ค้าง migrate ~29 จุด (eslint-disable).
5. Prisma 7 nested-create ห้าม scalar FK — ใช้ connect: { id }. (update/top-level create ใส่ scalar ได้ — Block A ทำถูก).
6. broadcastTenant หลังทุก tenant mutation (หลัง $transaction commit).
7. re-record double-count: deliveryCount/lastReceivedDate guard !isReRecord. totalPurchaseCount นับซ้ำอยู่แล้ว (flag in PR).
8. idempotency replay return ก่อน tx → spec assert $transaction ไม่ถูกเรียกตอน replay.
9. walk-in customerId=NULL — write ใน if(order.customerId) · backfill customerId IS NOT NULL.
10. take:20000 cap — corridor query bbox ก่อน take ไม่ใช่ JS-filter หลัง.
11. 3 color systems แยก: semantic colorCode · TERRITORY_PALETTE · route palette · lapse ladder.
12. run-creation uniqueness app-enforced — path ใหม่ copy guard ครบ.
13. Settlement.create แบบ standalone ลบ (Phase 4.3) — ไม่ใช่ "ตารางว่าง": settlement ตอนนี้สร้างใน DriverDayService (delivery-runs Phase 9.1) · SettlementsController ถูกลบ เหลือ read + approve/dispute (ปัจจุบันเรียกโดย test เท่านั้น) · R7 pay design ต้องรู้.
14. delivery-runs = god-service (โตกลับ) — facade 2,033 LOC (เคยแยกเหลือ 729 ใน SPLIT_PLAN.md · ตอนนี้โตกลับ) · delivery-operations.service.ts 2,208 LOC · งาน Block A / Track B ใหม่ ควรลงใน services/ sub-services ไม่ใช่ facade (อย่าซ้ำรอย regression). หมายเหตุ: reports.service.ts = 10,319 LOC คือก้อนใหญ่สุดของ repo.
15. money Decimal (18,2)/(18,4) · re-derive on reverse · 2 ledgers (PaymentCollection vs CustomerPayment) ต้อง union.
16. Lao UI labels บังคับ ผ่าน Xieng QC + lao_corruption_scan.py · mono SVG ห้าม emoji.
17. no persisted recency = hot-path cost — Block A persist + index แก้แล้ว (เดิม getLastDelivered MAX groupBy 3+ ที่).

10 Decisions

build decisions (D1–D13)

Bou ต้องเคาะ (จากแพ็กเกจ)

• payment enum migration (lowercase→uppercase) — parked since 2026-06-15 · canonical method = 3 ค่า (§6.1) → ต้อง resolve.
• optimizer gate = GPS ≥ 80% (~10/30 ตอนนี้) AND ≥ 8 deliveries/customer.
• PWA vs native — blueprint = PWA แต่ Bluetooth printer + scanner อาจบังคับ native.
• VARI stamp/signature — vari-stamp-sig.png = ตรา+ลายเซ็นจริง · ลบก่อน demo ภายนอก.
• VARI price authority — VARI_CATALOG (driver app · KB v1.4) ขัดกับ products.json/DEMO_LOOP (Master Cost · Bou 2026-06-11) ใน 4-5 SKU → เคาะแหล่งราคาจริงก่อน lock catalog.

11 Blueprint constitution + brand tokens

7 Design Principles (00 §3 — ทุก feature ต้องผ่านครบ)

1. 1 page = 1 main job, 3-second grasp.
2. record once while working (driver ไม่มีเอกสารเพิ่ม).
3. real data ก่อน decoration — ทุกเลข click-trace ได้ · no dead-end · totals = line items.
4. one-handed, harsh sunlight, low-skill — big thumb buttons · drive mode strips to essentials.
5. phone IS the GPS, ติดรถ ไม่ใช่ติดคน (driver swappable).
6. Lao-only ผ่าน Xieng QC + lao_corruption_scan.py (zero Thai codepoints) · mono SVG · no emoji.
7. using system = full pay — points/bonus นับเฉพาะ system-verified (photo+GPS) work.

DoD (00 §6): serves the one job · ไม่ละเมิด 7 หลัก · real-data closes loop (traceable, totals match, no dead-end) · Lao QC clean · browser-verified (0 console error + screenshot) · ไม่พังของเดิม (incremental) · design-log recorded.

View/Filter standard (01)

4 modes: List / Board / Calendar / Map · filter registry ~18 ตัว (F_SEARCH, F_DATE, F_BRANCH, F_DRIVER, F_ZONE, F_GRADE, F_PAYSTATUS, F_ORDERSTATUS, F_PAYMENT, F_SHIFT…) · hard rule: filter change → re-render ทุก view + KPI พร้อมกัน. build registry + view-bar ครั้งเดียว แล้ว clone.

Reports reframe (05 · อย่า rebuild)

มี 9 reports แล้ว (Phase 10) → (1) re-skin tokens (no logic change) (2) ยุบเมนู 9→7 via tab-wrapper (route ยังอยู่) (3) GET /reports/daily-summary + cron 19:00 + PDF + auto-WhatsApp (เสี่ยงแค่ gateway → PDF/share fallback).

Brand tokens — ⚠ 2 ชุด ไม่ตรงกัน

LOO Suite framing

LOO = branded-house suite (MS Office): LOO Delivery Business (V1 LIVE ที่ VARI ตั้งแต่ 2026-06-11) + LOO Workplace (HR) + LOO Waste. "LOO Platform" = multi-tenant engine · share Bible/tokens (swap --primary per vertical). domain: loolao.com + app./api./admin. · payroll/checkin/teampoints = link-out stub → LOO Workplace (draft).