Chỉ mục bàn giao (Delivery Index) — Tích hợp Pancake CRM (Pancake CRM Integration)

Mục đích: Cho team biết đọc file nào, ai làm gì, thứ tự triển khai, blocker còn mở, mức sẵn sàng đến đâu. Đọc trước: decision-brief.md → §Danh sách file → §Timeline → §Điểm còn mở. Canonical owner: handoff.md là canonical cho timeline, RACI, open items, blocker. PRD/UI/Dev/QA chỉ tham chiếu, không giữ version khác.

Đầu vào chuẩn (Canonical Inputs)

File	Vai trò	Nếu conflict
SOURCE_OF_TRUTH.md	Nguồn sự thật chuẩn + Solution Lock (25 DEC)	Ưu tiên cao nhất
decision-brief.md	Cửa vào package, tóm tắt 5 phút	Handoff giữ timeline/RACI chi tiết
prd.md / ui-spec.md / dev-spec.md / qa-test-plan.md	Hợp đồng chi tiết	Handoff chỉ tổng hợp
go-live-checklist.md	Readiness Pilot W1-W4, deploy gates	Không duplicate chi tiết

Trường	Giá trị
Tính năng	Tích hợp Pancake CRM (Pancake CRM Integration) — MVP-1 inbound webhook
Phiên bản	1.0
Ngày	15/05/2026
Độ phức tạp	L (Lớn)
Module	webhook, crm-api, notification-v2-api (BE) + crm, settings (FE)
Effort	~37 dev-days
Calendar	5.5-6 tuần (W1-W4 pilot + 1.5-2 tuần dev đầu)
Team	2 BE + 1 FE + 1 QA + 1 Ops (parallel)

---

1) Danh sách file deliverable

#	File	Người đọc chính	Ghi chú
1	Tóm tắt quyết định	PO, Sếp, Tech Lead, nhóm delivery	Đọc đầu tiên — 5 phút nắm scope/DEC/impact/risk
2	Nguồn sự thật chuẩn	PO/BA, Tech Lead, subagent generation	Canonical truth — 25 DEC + 19 Solution Lock
3	Gói bằng chứng	PO/BA, Tech Lead	Phase 3 evidence + 12 critical gaps vs design doc
4	PRD	PO, Tech Lead, BE/FE/QA	Z (Nhật ký quyết định) + A0-A12 + LIFECYCLE-001/002 + 6 FORMULA
5	Đặc tả UI	FE Dev, UI/UX	B-PRE → B0-B9 → B-Extensions → 12-group edge cases. 5 SCR + 1 delta
6	Đặc tả kỹ thuật	BE Dev, FE Dev, Tech Lead	C1-C12 + 5 bảng + 8 migration + 6 cron + 15-step handler
7	Kế hoạch kiểm thử	QA	D1-D5 + TC-001..018 + chaos test outage + load 100k/tháng
8	Checklist phát hành	Ops, Tech Lead	Pilot W1-W4 gates + rollback + monitoring

---

2) Bộ đọc trước cho từng vai trò

Vai trò	Thứ tự đọc	Thời lượng dự kiến
PO/BA	decision-brief → prd Z+A0+A5+A10 → SOURCE_OF_TRUTH §1+§8	30-45 phút
Sếp/Business Lead	decision-brief (toàn bộ) → prd A2+A3+A8	15 phút
Tech Lead	decision-brief → prd Z+A0 → dev-spec C1-C5 → SOURCE_OF_TRUTH §3+§4	60-90 phút
BE Dev	decision-brief → prd A5+A10 → dev-spec C1-C12 → EVIDENCE_PACK §4+§7	90-120 phút
FE Dev	decision-brief → prd A5 → ui-spec (full) → dev-spec C2+C6	60-90 phút
QA	decision-brief → prd A5+A7 → qa-test-plan → dev-spec C12 traceability	60-90 phút
Ops + DevOps	decision-brief → dev-spec C7+C8+C10 → go-live-checklist	45-60 phút
UI/UX Designer	decision-brief → ui-spec B-PRE+B0+B1+B2+B7+B9 → EVIDENCE_PACK §2+§3	45-60 phút

---

3) RACI

Hạng mục bàn giao	PO/BA	Tech Lead	BE Dev	FE Dev	QA	Ops/DevOps
Phê duyệt scope MVP-1	A	C	I	I	I	I
PRD (Z + A1-A12)	A	R	C	C	C	I
UI Spec (B-PRE → B-EXT)	C	C	I	R	C	I
Dev Spec (C1-C12)	I	A	R	C	C	C
Schema migration (4 bảng + 2 ALTER + 8 sequence)	I	A	R	—	C	C
Hasura metadata YAML + permission	I	A	R	—	C	C
Webhook handler pancake.go	I	C	R	—	C	I
Event handler 15-step event_pancake_process_record.go	I	A	R	—	C	I
Refactor GetTicketUpdates public helper	I	A	R	—	C	I
7 cron handlers (pancake_*)	I	A	R	—	C	I
REST client + circuit breaker pkg/pancake/	I	A	R	—	C	I
FE Settings UI 4 tabs + 1 container	C	I	—	R	C	I
FE delta dropdown source slot 9 (3 file)	I	I	—	R	C	I
3 notification template seed	C	I	R	—	C	I
Permission module pancake_crm_integration (6 actions)	C	A	R	C	C	I
QA Test Plan + TC-001..018	C	I	C	C	R	I
Chaos test outage + duplicate stress	I	C	C	C	R	C
Load test 100k events/tháng	I	C	C	I	R	C
PD-001/002 Pancake support verification	C	I	I	—	I	R/A
PD-003 customer_consent.marketing key confirm	A	I	R	—	I	I
PD-008 Pilot source list (W1-W4)	A	C	I	I	C	I
PD-011 KPI baseline manual workflow đo 1 tuần	A	I	I	I	C	I
Prometheus metrics + alertmanager rules	I	A	C	—	I	R
Grafana dashboard (post-MVP-1)	I	C	I	—	I	R
Pilot W1 launch + bug fix	A	R	C	C	C	C
Pilot W2-W4 rollout	A	R	C	C	C	C
Sign-off Go-Live	A	R	I	I	C	C

R = Responsible (làm), A = Accountable (chốt), C = Consulted (hỏi ý kiến), I = Informed (báo).

---

4) Timeline / kế hoạch 5.5-6 tuần calendar

Sprint 2 tuần. Tuần 0 = pre-work / out-of-band. Tuần 1-4 = Pilot rollout với feature flag 3 mức.

Tuần 0 — Pre-work (parallel với W1 dev)

Mốc	Mục tiêu	Phụ trách	Phụ thuộc
0.1 PD-001 + PD-002: gọi Pancake support 0972273341 xin HMAC + IP whitelist	21/05/2026	Ops	—
0.2 PD-003: PO confirm customer_consent.consent_data key opt-out marketing	22/05/2026	PO + BE	—
0.3 PD-011: Manager đo baseline manual workflow response time 1 tuần	21/05/2026	PO + Manager	—
0.4 PD-008: PO chọn 1 source low-volume cho W1	28/05/2026	PO + Marketing	—
0.5 PD-009: TL verify Hasura concurrency: 1 cron support	22/05/2026	Tech Lead	—

Sprint 1 (Tuần 1-2): Foundation BE + UI shell

Mốc	Mục tiêu	Owner	Effort	Phụ thuộc
1.1 Migration 8 file (4 ALTER + 4 CREATE + master data + permission + template + app_setting)	BE	1.5d	—
1.2 Backfill normalized_phone script PL/pgSQL batch 10k row/tx	BE	0.5d	1.1
1.3 services/webhook/handler/pancake.go (fail-open + verify + dedup)	BE	2d	1.1
1.4 services/crm-api/event/event_pancake_process_record.go (15 STEP)	BE	3.5d	1.1, 1.3
1.5 pkg/pancake/ (REST client + phone_normalize + advisory lock)	BE	1.5d	1.1
1.6 Refactor GetTicketUpdates thành public helper	BE	1d	—
1.7 Pancake handler call helper sau INSERT ticket (STEP 9-10)	BE	0.5d	1.4, 1.6
1.8 Hasura event trigger + 4 YAML metadata + permission Admin	BE	0.5d	1.1
1.9 3 notification template seed + handler call STEP 12	BE	1.5d	1.1
1.10 customer_consent Go struct build	BE	0.25d	—
1.11 FE delta dropdown source (3 file: types.ts + vi.ts + sourceDescriptions)	FE	1d	1.1
1.12 FE Settings container + tab routing skeleton	FE	0.5d	—
End of Sprint 1: BE webhook receiver + handler + ticket creation ready cho W1 pilot

Sprint 2 (Tuần 3-4): Outage recovery + Settings UI full + Pilot W1-W3

Mốc	Mục tiêu	Owner	Effort	Phụ thuộc
2.1 Cron 3 sources sync hourly	BE	1d	1.5
2.2 Cron 4 outage detect (state machine)	BE	1d	1.1
2.3 Cron 6 adaptive polling fallback	BE	3d	2.1, 2.2
2.4 Cron 7 daily reconciliation 25h window	BE	2d	1.5, 2.1
2.5 Cron pancake_test_event_cleanup + pancake_dlq_retry	BE	1d	1.1
2.6 DLQ Replay UI Tab 3 (panel + detail + replay action + bulk) + Hasura action pancake_replay_event	BE + FE	3d	1.4
2.7 SCR-01 Tab Kết nối Pancake (form + kiểm tra kết nối button)	FE	1d	1.12
2.8 SCR-02 Tab Map source → branch (inline-edit + manual sync button)	FE	1.5d	2.1
2.9 SCR-03 Tab Audit + DLQ replay UI	FE	1.5d	2.6
2.10 SCR-04 Tab Sức khỏe (metrics + outage history)	FE	0.5d	2.2
2.11 Backfill custom window endpoint + UI modal	BE+FE	1.5d	2.4
2.12 Circuit breaker REST sony/gobreaker integration + tests	BE	1d	1.5
2.13 Advisory lock + dedup race fix integration test	BE	1d	1.4
2.14 Prometheus metrics + alertmanager rules	BE + DevOps	2.5d	—
2.15 Pilot W1 launch 1 source low-volume + bug fix	All	2d	1.1-1.12
2.16 Pilot W2 5 source mid-volume	All	1d	2.15
2.17 Pilot W3 15 source high-volume (load test 100 req/s)	All	3d	2.16
End of Sprint 2: Production-ready cho W4 launch

Sprint 3 (Tuần 5-6): Production launch + monitoring

Mốc	Mục tiêu	Owner	Effort	Phụ thuộc
3.1 Pilot W4 production launch 40+ source	All	4d	2.17
3.2 PD-001 HMAC signature deployment (nếu Pancake support response trước W4)	Ops + BE	0.5d	0.1
3.3 PD-002 IP whitelist enforcement	Ops + BE	0.5d	0.1
3.4 Chaos test outage simulation + duplicate retry stress	QA	2d	2.3, 2.4, 2.6
3.5 KPI baseline measurement post-launch (so sánh với PD-011)	PO + Manager	1 tuần (passive)	3.1
3.6 Grafana dashboard (5 KPI section)	DevOps	2d	2.14, 3.1
3.7 Sign-off Go-Live	PO + TL	0.5d	3.1, 3.4
3.8 Phase 7 AUTO-PUBLISH /publish-doc pancake-crm-integration	PO/BA	0.5d	3.7
End of Sprint 3: Production live + full observability + signed off

---

5) Điểm còn mở / blocker (12 PD + risks)

ID	Loại	Nội dung	Phụ trách	Hạn chót	Trạng thái	Block
PD-001	PD-block-launch	Pancake webhook HMAC signature header tên gì (X-Pancake-Signature?)	Ops	25/06/2026 (W4)	Open	Launch W4
PD-002	PD-block-launch	Pancake IP whitelist range	Ops + Dev	25/06/2026	Open	Launch W4
PD-003	PD-block-phase	customer_consent.consent_data key opt-out marketing	BE + PO	22/05/2026	Open	Phase 4 FR-017
PD-004	PD-non-block	VIP tag IDs initial seed	PO	04/06/2026 (W2)	Open	Non-block
PD-005	PD-non-block	Pancake retry policy chi tiết	QA	W1 test	Open	Non-block
PD-006	PD-non-block	Pancake REST /sources rate limit	QA	W1 test	Open	Non-block
PD-008	PD-non-block	Pilot 4 tuần exact source list	PO + Marketing	28/05/2026 (W1)	Open	W1 setup
PD-009	PD-non-block	Hasura concurrency: 1 cron supported?	TL	22/05/2026	Open	Non-block (fallback advisory lock)
PD-011	PD-block-measure	KPI baseline manual workflow response time	PO + Manager	21/05/2026 (trước W1)	Open	KPI measurement
PD-012	PD-non-block	Notification noti_pancake_outage kênh	PO	W1	Open	Non-block (default push admin)
RSK-001	Risk-cao	Pancake auto-suspend webhook (80% error / 30 phút)	BE + Ops	Mitigated by DEC-003 + DEC-015	Mitigated	—
RSK-002	Risk-cao	Race tạo account trùng cùng phone	BE	Mitigated by DEC-020 advisory lock	Mitigated	—
RSK-005	Risk-tb	FE delta hardcode source slot ngoài TicketSources (report module)	FE	Grep audit W1	Open	Phase 4 FR-018
DEP-001	Dep-external	Pancake support phản hồi PD-001/002	Ops	25/06/2026	Pending	Launch W4
DEP-002	Dep-internal	Backfill normalized_phone ~1M account chạy ~8 phút	BE + DevOps	Sprint 1	Pending	Migration 1.1
DEP-003	Dep-internal	DevOps deploy public HTTPS endpoint cho webhook (TLS termination reverse proxy)	DevOps	Sprint 1	Pending	1.3
DEP-004	Dep-internal	Notification-v2-api template seed phải apply trước handler call	BE	Sprint 1	Pending	1.9 → 1.4

Quy tắc severity:

• Block-launch: PHẢI resolve trước W4 production
• Block-phase: Block phase tiếp theo của workflow
• Block-measure: Block KPI measurement post-launch
• Non-block: Parallel ok, có default tạm thời
• Mitigated: Đã có DEC + implementation plan
• Risk-cao/tb/thấp: Theo PRD A7

---

6) Thứ tự deploy production

KHÔNG được skip thứ tự — risk DB corruption hoặc Hasura metadata drift.

Thứ tự	Bước	Owner	Verify
1	Apply 8 migration sequence (1777870069928..935) — schema + master data + permission + template + app_setting	BE	Hasura console schema view
2	Apply Hasura metadata: 4 bảng pancake_* YAML + permission Admin + event trigger + cron triggers	BE	hasura metadata apply success
3	Deploy services/webhook (PR 1: pancake handler)	DevOps	Health check /healthz
4	Deploy services/crm-api (PR 2: event handler + 7 cron + REST client + refactor distribute_ticket)	DevOps	Health check + cron list verify
5	Deploy diva-admin FE (PR 3: 3 file delta + 5 Settings pages mới + routes + menu + permission)	DevOps	Smoke test admin login → Settings/Pancake menu visible
6	Setup Pancake admin: nhập webhook URL https://diva.com.vn/api/pancake/record/{token} + api_key	Ops	Tab 1 button "Kiểm tra kết nối" pass
7	Enable W1 pilot: 1 source is_active=true (kill switch off để dev mode)	PO + Ops	Tab 3 audit log có event đầu tiên
8	Sau 24h W1 stable: enable kill switch ON + W2 5 source	PO + Ops	KPI dashboard event success ≥ 99.5%
9	W3 15 source + load test verify	QA	Latency p95 ≤ 30s
10	W4 40+ source production launch	PO + TL	Sign-off Go-Live

Rollback plan: xem go-live-checklist.md E3.

---

7) Bộ tài liệu liên quan

• Design doc Mode A nguồn: docs/superpowers/specs/2026-05-04-pancake-crm-record-webhook-design.md (v2.2 — base cho PRD này)
• Pancake CRM API docs: /Users/st/Downloads/document.yaml (Swagger 2.0) + document webhook.yaml (OpenAPI 3.0)
• CLAUDE.md project rules: đặc biệt Diva Common Pitfalls Map (4 traps migration safety, REPLACE silent no-op)
• SKILL.md po-ba-workflow: workflow 7 phase + HARD-GATEs
• Diva Permission Model: references/diva-permission-model.md (default seed + dynamic override)

---

8) Lien hệ + escalation

Vấn đề	Liên hệ chính	Backup
Pancake support (PD-001/002)	Ops lead	Zalo 0972273341
PD-003 customer_consent key	PO/BA	BE Lead
Schema migration sự cố	Tech Lead	DevOps lead
Hasura metadata drift	Tech Lead	BE Lead
Webhook endpoint DDoS	DevOps lead	Tech Lead
Production outage Pancake	Ops lead	PO/BA
KPI/Conversion data	PO/BA	Manager

---

Hết Delivery Index v1.0. Sẵn sàng bàn giao team. Phase 7 AUTO-PUBLISH sẽ chạy sau khi PO sign-off.

---

9) Pass 1 Resolutions v1.1 (Phase 5.2 Multi-Perspective Review)

Date: 15/05/2026 | Trigger: 4 reviewer feedback (PO/BA + Tech Lead BLOCK + QA/DevOps + FE/UX).

9.1) Effort + timeline updates

Item	Cũ	Mới	Δ
Total dev-days	37d	44.25d	+7.25d
Calendar	5.5-6 tuần	6 tuần (tight)	+0.5 tuần
BE allocation	2 BE × 14d	2 BE × ~16.5d each	+2.5d each BE
FE allocation	1 FE × 7d	1 FE × ~9.5d	+2.5d FE
QA allocation	1 QA × 6d	1 QA × 8d (+2d new TC)	+2d QA
DevOps allocation	(chưa explicit)	1 Ops × 3d explicit	NEW

9.2) RACI updates cho new conditions

Hạng mục bàn giao mới	PO/BA	Tech Lead	BE Dev	FE Dev	QA	Ops/DevOps
pkg/pancake/db.go pgxpool foundation (DEC-028)	I	A	R	—	C	C
External backfill Go job	I	C	R	—	I	C
Migration #3 contact_book cleanup + verify duplicate	I	A	R	—	C	C
F18 4-file delta (CustomerTicketManager.tsx thêm)	I	I	—	R	C	I
XJsonViewer + XMetricCard build new	I	C	—	R	C	I
3 alertmanager rules thêm	I	A	—	—	C	R
Deploy step 9a/9b split	I	A	C	—	C	R
HMAC verification path spec (post PD-001)	I	A	C	—	C	R
Permission audit lint script	I	R	C	C	C	I
Rollback drill staging rehearsal	I	C	R	I	C	R
DEC-026/027/028 sign-off	A	R	C	C	C	C
PD-013 resolution (ticket.first_response_at)	A	C	R	—	I	I
PD-014 resolution (Pancake /records endpoint verify)	C	I	I	—	A	R

9.3) Blocker severity updates

ID	Cũ	Mới	Lý do
PD-003	Phase-block FR-017	Phase-block + audit data coverage AC	Compliance risk thực
PD-008	Non-block	Block-W1-start	QA setup data
PD-011	Mismatch (Non-block decision-brief / Block-pilot handoff)	Block-pilot-start consistent 3 file
PD-013 NEW	—	Block-KPI-measure	first_response_at field cho FORMULA-002
PD-014 NEW	—	Block-Cron-7	Pancake /records?modified_since endpoint verify

9.4) Sprint plan revised

Sprint 1 (Tuần 1-2) — Foundation + critical infra:

• W1 day 1-3: DEC-028 pgxpool foundation (BE-1 + Tech Lead pair) — block other tasks
• W1 day 4-7: Migration 1-8 (with revisions C13.3) + Hasura YAML conventions sweep
• W1 day 8-10: 15-step handler implementation theo pgxpool architecture
• W2: Settings UI 4 tabs + 7 cron handlers + DLQ replay

Sprint 2 (Tuần 3-4) — Outage recovery + Pilot W1-W3:

• W3 day 1: 3 alertmanager rules thêm + HMAC spec
• W3 day 2-3: Rollback drill rehearsal staging
• Pilot W1-W3 execute

Sprint 3 (Tuần 5-6) — Production launch W4 + monitoring + publish:

• W4 production launch
• Phase 6 finalize + Phase 7 publish dva-doc + GitHub push

9.5) Document index updates

File	Update
REVIEW_REPORT.md (NEW)	Tổng hợp 4 reviewer feedback + 22 P0 + 15 P1 + 3 DEC mới + 2 PD mới
EVIDENCE_PACK.md	§11 Pass 1 Resolutions — contact_book truth + architecture mismatch + F18 = 4 file
SOURCE_OF_TRUTH.md	§10 Pass 1 Resolutions — DEC-006 revised + DEC-026..028 mới + PD-013..014
prd.md	Z' Decision Log v1.1 — DEC updates + new DEC + new PD + new RSK + FR corrections
dev-spec.md	C13 Pass 1 Resolutions — direct pgxpool architecture + migration revisions + 13 new tasks
ui-spec.md	(pending) B-Resolutions — F18 4 file + component audit + B-Voice banner outage
qa-test-plan.md	D7 Pass 1 Resolutions — 11 new TC + DS-002 v2 + entry/exit updates
handoff.md	Section §9 này
go-live-checklist.md	(pending) E7 Pass 1 Resolutions — 3 alert rules + HMAC spec + step 9a/9b split
decision-brief.md	(pending) §9 PD severity sync

9.6) Sign-off conditions cho Phase 6

Trước khi Phase 6 DELIVER finalize, các điều kiện sau phải pass:

1. ✅ Pass 1 fix applied (4 file critical + tracking)
2. ⏳ ui-spec + go-live + decision-brief sync (sẽ làm tiếp)
3. ⏳ Re-run 4 lint scripts → 0 ERROR
4. ⏳ Optional Pass 2 verification re-review (Tech Lead confirm DEC-028 architecture)
5. ⏳ PO confirm DEC-026, DEC-027, DEC-028 (3 new decision)
6. ⏳ PO confirm PD-013, PD-014 (2 new pending decision)

Sau khi all condition pass → Phase 7 AUTO-PUBLISH + GitHub push.