Go-Live Checklist: Kho vật tư

Feature slug: material-warehouseVersion: 3.0 Ngày: 2026-03-27 Complexity: L (Large)

---

E1) Deploy Gates

Database Migrations (6 bảng mới + 1 ALTER)

#	Migration	Mô tả	Verify	Status
MIG-01	XXXXXX_create_material_warehouse	Bảng kho vật tư per branch + UNIQUE(branch_id)	SELECT count(*) FROM material_warehouse → 0	[ ]
MIG-02	XXXXXX_create_material_price_config	Bảng cấu hình giá + unique indexes (active global/branch)	\d material_price_config — verify indexes	[ ]
MIG-03	XXXXXX_create_material_usage_unit	Bảng đơn vị sử dụng + UNIQUE(config_id, usage_unit_name)	\d material_usage_unit	[ ]
MIG-04	XXXXXX_create_material_stock_movement	Bảng nhập/xuất + indexes + VIEW material_stock_balance	SELECT * FROM material_stock_balance LIMIT 1 → OK	[ ]
MIG-05	XXXXXX_create_material_batch	Bảng lô vật tư (batch) + indexes (warehouse_id, product_id, status, expiry_date)	\d material_batch — verify indexes, CHECK (status IN ('active','depleted','locked','disposed'))	[ ]
MIG-06	XXXXXX_alter_project_task_material_add_price	ALTER thêm 10 cột (usage_unit, unit_price, amount, ...)	\d project_task_material — verify 10 cột mới	[ ]

Hasura Metadata

#	File	Mô tả	Verify	Status
HAS-01	public_material_warehouse.yaml	Track table + permissions (Admin: full, Manager: branch select/insert)	Hasura Console → material_warehouse → Permissions tab	[ ]
HAS-02	public_material_price_config.yaml	Track + permissions (Admin: full, Manager: select only)	Hasura Console → material_price_config	[ ]
HAS-03	public_material_usage_unit.yaml	Track + permissions (Admin: full, Manager: select only)	Hasura Console → material_usage_unit	[ ]
HAS-04	public_material_stock_movement.yaml	Track + permissions (Admin/Manager: insert+select, NO update/delete — immutable)	Verify: NO update_permissions	[ ]
HAS-05	public_material_stock_balance.yaml	Track view + select permissions	Hasura Console → material_stock_balance	[ ]
HAS-06	public_material_batch.yaml	Track table + permissions (Admin: full, Manager: branch select/insert/update status)	Hasura Console → material_batch → Permissions tab	[ ]
HAS-07	public_project_task_material.yaml	Updated — thêm permissions cho 10 cột mới	Verify cột mới visible trong select/insert	[ ]
HAS-08	tables.yaml	Updated — include 6 bảng mới + view	Verify all tables tracked	[ ]

Hasura Actions (v3.0)

#	Action	Service	Verify	Status
ACT-01	transferToMaterialWarehouse	ecommerce-api	Hasura Console → Actions → verify registered + test on staging	[ ]

Event Triggers

#	Trigger	Handler	Verify	Status
EVT-01	subtask_status_change (hoặc extend existing)	materialAutoDeduct — Go handler	Test: subtask done → movement created (< 5s)	[ ]
EVT-02	(same trigger, condition check)	materialAutoReverse — Go handler	Test: undo done → reverse movement created	[ ]
EVT-03	inventory_document_material_warehouse (fires on inventory_document status change cho kho vật tư)	Go handler — xử lý behaviors export_material_warehouse, import_material_warehouse	Test: transfer confirm → trigger fires → material_batch created	[ ]

Scheduler (Cron Jobs)

#	Cron	Schedule	Handler	Verify	Status
CRON-01	material_batch_expiry_check	Daily 01:00 AM (Asia/Ho_Chi_Minh)	batchExpiryCheck — Go handler: lock lô hết hạn + cảnh báo 90 ngày	Test: tạo lô HSD = yesterday → cron chạy → status = locked + notification sent	[ ]

Env Vars / Feature Flags

#	Biến	Giá trị	Service	Status
ENV-01	MATERIAL_WAREHOUSE_ENABLED	true	diva-admin (FE)	[ ]
ENV-02	LOW_STOCK_NOTIFICATION_ENABLED	true	notification-api	[ ]
ENV-03	MATERIAL_STOCK_IMPORT_MAX_ROWS	500	export-api (Excel import)	[ ]
ENV-04	MATERIAL_AUTO_DEDUCT_ENABLED	true	crm-api (BE event handler)	[ ]

Transfer Deploy Gates (v3.0)

• [ ] master_data entries đã tạo: behaviors export_material_warehouse, import_material_warehouse
• [ ] Hasura Action transferToMaterialWarehouse đã registered và tested trên staging
• [ ] Event trigger inventory_document_material_warehouse đã tạo trong Hasura metadata
• [ ] Verify các flow inventory_document hiện tại KHÔNG bị ảnh hưởng (regression: transfer/check/return vẫn hoạt động)
• [ ] Verify component ProductLotNumberSelect load đúng trong context kho vật tư
• [ ] Ít nhất 1 chi nhánh có data kho chính sạch để pilot transfer

---

E2) Pre-checks

Staging Verification

#	Check	Steps	Expected	Status
STG-01	DB migration thành công	SSH staging → psql → \dt material_* (5 bảng: material_warehouse, material_price_config, material_usage_unit, material_stock_movement, material_batch) + \dv material_* (1 view: material_stock_balance)	\dt → 5 bảng listed, \dv → 1 view listed	[ ]
STG-01b	material_batch indexes verified	\di idx_mb_* hoặc \di+ material_batch*	Indexes on (warehouse_id, product_id), (status), (expiry_date) listed	[ ]
STG-02	Hasura metadata reload	Hasura Console → Settings → Reload Metadata	"Metadata reloaded successfully"	[ ]
STG-03	FE build pass	pnpm codegen && pnpm build trên staging branch	Build thành công, không error	[ ]
STG-04	SCR-01 render	Login Admin → Kho > Kho vật tư	Trang hiện, không crash, table trống	[ ]
STG-05	Event trigger registered	Hasura Console → Events → subtask_status_change	Trigger active, handler URL đúng	[ ]
STG-06	Cron material_batch_expiry_check registered	Hasura Console → Events → Cron Triggers	Cron active, schedule = 0 1 * * *, handler URL đúng	[ ]
STG-07	Cron tested trên staging	Tạo lô với HSD = yesterday → trigger cron manually	Lô chuyển locked + disposal movement + notification sent	[ ]

Data Validation

#	Check	Query	Expected	Status
DV-01	Không có data rác	SELECT count(*) FROM material_warehouse	0 (chưa ai tạo kho)	[ ]
DV-02	project_task_material cũ không bị ảnh hưởng	SELECT count(*) FROM project_task_material WHERE usage_unit IS NOT NULL	0 (cột mới, chưa có data)	[ ]
DV-03	Indexes tạo đúng	\di idx_mpc_product_active_*	2 partial unique indexes listed	[ ]
DV-04	View hoạt động	SELECT * FROM material_stock_balance LIMIT 1	Empty result (OK) hoặc error-free	[ ]
DV-05	material_batch table sạch	SELECT count(*) FROM material_batch	0 (chưa ai nhập kho)	[ ]
DV-06	material_batch permissions	Hasura Console → material_batch → Permissions	Admin: full, Manager: branch-scoped select/insert/update	[ ]

Performance Test

#	Test	Steps	Expected	Status
PF-01	Danh sách kho vật tư	Tạo 100 vật tư config → load SCR-01	Response < 500ms	[ ]
PF-02	Auto-deduct event trigger	Subtask done với 5 materials → measure	All 5 movements created < 5s total	[ ]
PF-03	Aggregate view task cha	Task cha có 10 subtask x 5 materials = 50 records → load	Render < 500ms	[ ]
PF-04	Stock movement history	1000 movements per product → load SCR-03	Page load < 1s (with pagination)	[ ]

Transfer Smoke Tests (v3.0)

• [ ] Smoke: Manager tạo transfer → chọn lot → confirm → tồn kho chi nhánh giảm + material_batch được tạo
• [ ] Smoke: Transfer với cost_price=0 → warning hiển thị nhưng cho phép tiếp tục
• [ ] Smoke: Transfer không có cấu hình quy đổi đơn vị → bị chặn với thông báo lỗi rõ ràng
• [ ] Smoke: Hủy transfer (batch chưa sử dụng) → cả 2 phía được reversed
• [ ] Smoke: Hủy transfer (batch đã dùng bởi auto_deduct) → bị chặn
• [ ] Smoke: Flow transfer request hiện tại (kho tổng → kho chi nhánh) vẫn hoạt động sau deploy

---

E3) Day-0 / Day-1

Day-0: Deploy Steps

#	Bước	Ai	Thời gian	Chi tiết	Status
D0-01	Backup DB production	DevOps	T-30min	pg_dump project database	[ ]
D0-02	Apply migrations (MIG-01 → MIG-06)	DevOps	T-20min	Chạy tuần tự, verify mỗi migration (bao gồm material_batch)	[ ]
D0-03	Apply Hasura metadata	DevOps	T-10min	hasura metadata apply + reload	[ ]
D0-04	Deploy BE services	DevOps	T-5min	Deploy crm-api (hoặc service chứa handlers)	[ ]
D0-05	Deploy FE (diva-admin)	DevOps	T+0	Deploy với MATERIAL_WAREHOUSE_ENABLED=true	[ ]
D0-06	Verify event trigger	DevOps + QA	T+5min	Tạo 1 subtask test → done → verify movement	[ ]
D0-07	Smoke test SCR-01	QA	T+10min	Login Admin → Kho vật tư → tạo kho → thêm vật tư	[ ]
D0-08	Verify cron job active	DevOps	T+12min	Hasura Console → Cron Triggers → material_batch_expiry_check → Active	[ ]
D0-09	Verify batch table permissions	DevOps + QA	T+15min	Hasura Console → material_batch → test insert/select as Manager	[ ]

Day-0: Transfer Deploy (v3.0)

#	Bước	Ai	Thời gian	Chi tiết	Status
D0-T01	Deploy master_data entries	DevOps	T+16min	Tạo entries export_material_warehouse, import_material_warehouse TRƯỚC action/trigger	[ ]
D0-T02	Deploy BE action + event trigger	DevOps	T+18min	Deploy transferToMaterialWarehouse action + inventory_document_material_warehouse trigger	[ ]
D0-T03	Deploy FE với SCR-08	DevOps	T+20min	Deploy FE bao gồm trang Transfer form (SCR-08)	[ ]
D0-T04	Enable transfer cho pilot branch(es)	Admin + PO	T+22min	Chỉ bật cho chi nhánh pilot (DEC-D35: cần data cleanup trước)	[ ]
D0-T05	Monitor transfer action	DevOps	T+25min	Theo dõi: tỉ lệ tạo inventory_document, error rate trên transferToMaterialWarehouse action	[ ]

Day-0: Monitoring (T+0 → T+2h)

#	Metric	Tool	Ngưỡng cảnh báo	Status
MON-01	Error rate diva-admin	Sentry/Grafana	> 1% → investigate	[ ]
MON-02	Event trigger failure	Hasura Console → Events → Invocation Logs	Bất kỳ failure → investigate	[ ]
MON-03	DB connection pool	Grafana	> 80% usage → alert	[ ]
MON-04	Response time SCR-01	APM	p99 > 2s → investigate	[ ]
MON-05	Disk usage material_stock_movement	SELECT pg_size_pretty(pg_total_relation_size('material_stock_movement')) / Grafana	> 2GB → alert, review partition strategy	[ ]
MON-06	material_batch table size	SELECT pg_size_pretty(pg_total_relation_size('material_batch')) / Grafana	> 500MB → alert	[ ]
MON-07	Cron job success/failure rate	Hasura Console → Cron Triggers → material_batch_expiry_check → Invocation Logs	Bất kỳ failure → investigate immediately	[ ]
MON-08	Lô hết hạn bị lock count	SELECT count(*) FROM material_batch WHERE status = 'locked' AND updated_at > now() - interval '24h'	Track daily — spike bất thường → verify cron logic	[ ]

Day-1: Post-deploy

#	Task	Ai	Chi tiết	Status
D1-01	Smoke test full flow	QA	Tạo kho → thêm config → nhập kho → subtask done → verify tồn kho	[ ]
D1-02	Verify backward compat	QA	Mở 3 đơn cũ có inventory_document → sidebar tài chính hiện đúng	[ ]
D1-03	Verify tiền tour không ảnh hưởng	QA	Mở 1 subtask có materials + tour_money → verify tour_money giữ nguyên	[ ]
D1-04	Admin tạo kho chi nhánh đầu tiên	Admin user	Hướng dẫn Admin tạo kho + config vật tư thực tế	[ ]
D1-05	Collect feedback	PO	Hỏi Admin/Manager về UX: form cấu hình, nhập kho, kiểm kê	[ ]
D1-06	Monitor low stock notifications	DevOps	Verify notification gửi đúng khi tồn <= min_stock	[ ]

Day-1: Transfer Verification (v3.0)

#	Task	Ai	Chi tiết	Status
D1-T01	Verify pilot branch transfer data	QA + PO	material_batch được tạo đúng, giá khớp với source lot	[ ]
D1-T02	Verify auto-deduct trên transferred batches	QA	Subtask done sử dụng batch từ transfer → auto_deduct hoạt động đúng	[ ]
D1-T03	Check inventory_document audit trail	QA	Verify behavior = export_material_warehouse xuất hiện trong inventory_document	[ ]
D1-T04	Monitor low stock alerts từ transferred batches	DevOps	Theo dõi cảnh báo tồn kho thấp từ các batch được transfer	[ ]

---

E4) Rollback Plan

Khi nào rollback

• Migration fail ở bước nào → rollback tất cả bước từ đó
• P1 bug trên production ảnh hưởng flow hiện có (tiền tour, commission, order)
• Event trigger gây load bất thường (> 100 invocations/s)

Steps to Rollback

#	Bước	Command / Action	Lưu ý
RB-01	Tắt feature flag FE	Set MATERIAL_WAREHOUSE_ENABLED=false → redeploy FE	FE ẩn menu Kho vật tư, MaterialForm mới không render
RB-02	Disable event trigger	Hasura Console → Events → subtask_status_change → Disable (hoặc remove handler URL)	Ngăn auto-deduct chạy
RB-03	Rollback Hasura metadata	hasura metadata apply từ backup metadata (pre-deploy)	Untrack 5 bảng mới
RB-03b	Backup cột mới trước DROP	CREATE TABLE project_task_material_backup_v1 AS SELECT id, usage_unit, unit_price, amount, to_stock_factor, stock_equivalent, total_stock_equivalent, config_version_id, price_snapshot_at, wastage_quantity FROM project_task_material WHERE usage_unit IS NOT NULL;	Giữ backup để restore nếu cần
RB-04	Rollback migration MIG-05 (ALTER)	ALTER TABLE project_task_material DROP COLUMN usage_unit, DROP COLUMN unit_price, ... (10 cột)	Data trong cột mới sẽ mất (đã backup ở RB-03b)
RB-05	Rollback migration MIG-04	DROP VIEW material_stock_balance; DROP TABLE material_stock_movement;	Movement data mất
RB-06	Rollback migration MIG-03	DROP TABLE material_usage_unit;	Config data mất
RB-07	Rollback migration MIG-02	DROP TABLE material_price_config;	Config data mất
RB-08	Rollback migration MIG-01	DROP TABLE material_warehouse;	Warehouse data mất
RB-09	Deploy BE services (rollback version)	Redeploy previous BE version	Handlers cũ không có materialAutoDeduct
RB-10	Verify	Mở 1 đơn cũ + 1 subtask → verify flow bình thường	Tiền tour, commission không ảnh hưởng

Transfer Rollback (v3.0)

• [ ] Nếu transferToMaterialWarehouse action lỗi: disable action trong Hasura, các flow hiện tại không bị ảnh hưởng
• [ ] Nếu event trigger inventory_document_material_warehouse fire sai: disable trigger, review thủ công các inventory_documents bị ảnh hưởng
• [ ] Nếu tồn kho chi nhánh bị trừ sai: sử dụng flow kiểm kê (inventory adjustment) hiện tại để điều chỉnh
• [ ] Nếu material_batch được tạo với data sai: sử dụng flow thanh lý (disposal) để dispose batch + nhập lại thủ công
• [ ] QUAN TRỌNG: KHÔNG rollback master_data entries nếu đã có transfers được tạo — đảm bảo data integrity

Rollback nhanh (không mất data cũ)

Nếu chỉ cần ẩn feature mà KHÔNG rollback migration:

1. RB-01: Tắt feature flag FE
2. RB-02: Disable event trigger
3. RB-02b (v3.0): Disable transferToMaterialWarehouse action + inventory_document_material_warehouse trigger
4. Data bảng mới vẫn giữ → khi fix xong, bật lại

---

E5) Sign-off

Domain	Reviewer	Role	Status	Date
PRD & Business Rules	PO/BA	Product Owner	[ ] Pending	—
Frontend (UI/UX)	FE Lead	Frontend Dev	[ ] Pending	—
Backend (DB + Triggers)	BE Lead	Backend Dev	[ ] Pending	—
Hasura Metadata & Permissions	BE Lead	Backend Dev	[ ] Pending	—
QA Test Plan	QA Lead	QA	[ ] Pending	—
QA Execution (Exit Criteria met)	QA Lead	QA	[ ] Pending	—
DevOps (Migration + Deploy)	DevOps	DevOps	[ ] Pending	—
Security (RBAC verified)	Tech Lead	Tech Lead	[ ] Pending	—
Go-Live Approval	PO/BA + Tech Lead	Final Sign-off	[ ] Pending	—

Transfer Sign-off (v3.0)

• [ ] Transfer smoke test passed trên staging (Manager + Admin)
• [ ] Regression các flow inventory hiện tại passed
• [ ] Chi nhánh pilot đã xác định và data cleanup đã verified (DEC-D35)

---

Changelog

Version	Ngày	Thay đổi	Tác giả
1.0	2026-03-26	Khởi tạo Go-Live Checklist: 5 migrations, 7 Hasura files, 2 event triggers, 3 env vars, staging verification, day-0/day-1 plan, rollback plan, sign-off	PO/BA + AI
1.1	2026-03-27	MIG-05: sửa "9 cột" → "10 cột". STG-01: tách \dt (4 bảng) + \dv (1 view). +MON-05 disk usage monitoring material_stock_movement (alert > 2GB). +ENV-04 MATERIAL_AUTO_DEDUCT_ENABLED. Rollback: +RB-03b backup step trước DROP COLUMN.	PO/BA + AI
2.0	2026-03-27	Design v2 — Batch-based FIFO. E1: +MIG-05 material_batch table, renumber MIG-06. +HAS-06 material_batch.yaml, renumber HAS-07/08. +CRON-01 material_batch_expiry_check (daily 01:00). E2: STG-01 sửa 4→5 bảng. +STG-01b batch indexes. +STG-06/07 cron registered + tested. +DV-05/06 batch table validation. E3: +D0-08 verify cron active, +D0-09 verify batch permissions. Monitoring: +MON-06 batch table size, +MON-07 cron success/failure, +MON-08 locked batch count.	PO/BA + AI
2.1	2026-03-27	Version header bump đồng bộ với các spec files khác. Không có thay đổi nội dung.	PO/BA
3.0	2026-03-27	Design v3 — Transfer kho chi nhánh → kho vật tư. E1: +ACT-01 transferToMaterialWarehouse action (ecommerce-api). +EVT-03 inventory_document_material_warehouse trigger. +Transfer Deploy Gates (master_data entries, regression check, pilot branch). E2: +Transfer Smoke Tests (6 items: create/cancel/regression). E3: +Day-0 Transfer Deploy (D0-T01→T05: master_data → action/trigger → FE SCR-08 → pilot enable → monitor). +Day-1 Transfer Verification (D1-T01→T04: pilot data, auto-deduct, audit trail, low stock). E4: +Transfer Rollback (5 items: action disable, trigger disable, kiểm kê adjust, disposal, master_data integrity). Rollback nhanh: +RB-02b. E5: +Transfer Sign-off (3 items: smoke test, regression, pilot verified).	PO/BA + AI