Viết PRD và spec mà cả người lẫn AI đều hiểu

# PRD — Mộc OMS (giai đoạn 1: MVP)

- Phiên bản: 1.2 | Cập nhật: 2026-01-19 | Chủ sở hữu: Nguyễn Thị Lan (owner)
- Trạng thái: Đã duyệt

## 1. Tóm tắt
Mộc OMS là hệ thống quản lý đơn nội bộ cho chuỗi 3 tiệm Bánh Mộc (Phú Nhuận, Thảo Điền, Gò Vấp)
và bếp trung tâm. Mục tiêu giai đoạn 1: mọi đơn đặt trước được nhập MỘT LẦN tại nguồn,
bếp và chi nhánh đọc từ cùng một chỗ, tiền cọc gắn với đơn.

## 2. Vấn đề
Xem problem statement đầy đủ ở phần Phụ lục A. Tóm tắt: đơn bị chép lại 2–3 lần qua Sheet, sổ tay,
ảnh chụp Zalo; ước tính thiệt hại trực tiếp 13–24 triệu đồng/tháng (giả định, đang đo baseline).

## 3. Mục tiêu và chỉ số thành công (sau 3 tháng dùng ở cả 3 tiệm)
- Tỷ lệ bánh kem làm lại do sai thông tin giảm ≥ 50% so với baseline.
- Thời gian đối soát cuối ngày ≤ 30 phút/tiệm.
- ≥ 95% đơn đặt trước được tạo trong Mộc OMS (không còn đơn chỉ nằm trên Sheet/Zalo).
- Chỉ số định hướng và kế hoạch đo: docs/metrics.md.

## 4. Người dùng
- staff: Hà (bán hàng online), nhân viên quầy — tạo, sửa đơn; ghi cọc.
- manager: quản lý chi nhánh, anh Tuấn (bếp trung tâm) — như staff + hủy đơn đang làm, sửa giá, tạo đơn gấp.
- owner: chị Lan — xem toàn chuỗi, quản lý nhân viên và danh mục.
- Persona chi tiết: docs/research/personas.md.

## 5. Phạm vi MVP
| Mã | Tính năng | Story | Spec |
|---|---|---|---|
| F1 | Tạo đơn hàng (kèm tìm/tạo khách, ghi cọc khi tạo) | US-01, US-02, US-03 | specs/tao-don-hang.md |
| F2 | Sửa, hủy đơn; chuyển trạng thái | US-03, US-05 | specs/cap-nhat-don.md |
| F3 | Màn hình bếp theo chuyến xe | US-04 | specs/man-hinh-bep.md |
| F4 | Khách hàng và lịch sử mua | US-02 | specs/khach-hang.md |
| F5 | Danh mục sản phẩm, bánh kem tùy chỉnh | — | specs/san-pham.md |
| F6 | Đăng nhập theo vai trò, phân quyền theo chi nhánh | — | specs/phan-quyen.md |
| F7 | Dashboard đơn hôm nay | US-06 | specs/dashboard.md |

## 6. Ngoài phạm vi (non-goals)
Website cho khách tự đặt; chatbot/trợ lý AI; thay máy tính tiền, hóa đơn điện tử; tự xác nhận chuyển khoản;
thông báo tự động cho khách; kho nguyên liệu; tích điểm, khuyến mãi; app di động cài đặt;
tự tính phí giao hàng; multi-tenant. Lý do và thời điểm xem lại: Phụ lục B.

## 7. Ràng buộc và giả định
- Stack: Next.js + TypeScript + Supabase (PostgreSQL, Auth) + Drizzle + Zod; host Vercel.
- Tiền lưu số nguyên VNĐ; thời gian lưu timestamptz, hiển thị Asia/Ho_Chi_Minh.
- Dữ liệu cá nhân khách (tên, SĐT, địa chỉ, sinh nhật) chỉ dùng cho mục đích phục vụ đơn hàng;
  tuân thủ quy định bảo vệ dữ liệu cá nhân hiện hành (cần tư vấn pháp lý khi mở rộng sử dụng).
- Thiết bị: laptop ở quầy, máy tính bảng ở bếp, điện thoại của người giao. Chỉ tiếng Việt.
- Nguồn lực: chị Lan ~8–10 giờ/tuần cùng coding agent; review bảo mật thuê ngoài trước khi ra mắt.

## 8. Rủi ro chính
- Nhân viên quay lại Sheet nếu tạo đơn chậm hơn cách cũ -> mục tiêu tạo đơn ≤ 90 giây.
- Sai phân quyền làm lộ dữ liệu khách giữa chi nhánh -> test phân quyền bắt buộc.
- Ngày lễ quá tải -> chạy thử trước mùa cao điểm ít nhất 2 tuần.

## 9. Mốc
- Lát 1 chạy thử ở Phú Nhuận + bếp trung tâm: 2 tuần.
- Lát 2, mở cho 3 tiệm: sau khi lát 1 đạt tiêu chí go/no-go.

## 10. Câu hỏi mở
- Bánh nhận trước 08:00 đi chuyến nào? (chờ anh Tuấn xác nhận)

## 11. Lịch sử thay đổi
- 1.2 (2026-01-19): thêm quy tắc chuyến xe QT-07 sau shadowing bếp.
- 1.1: thêm F4 lịch sử mua vào lát 2 theo kết quả phỏng vấn khách.

# Spec: Tạo đơn hàng
- Mã: SPEC-001 | Trạng thái: Đã duyệt | Phiên bản: 1.1
- Cập nhật: 2026-01-26 | Người phụ trách: Nguyễn Thị Lan
- Liên quan: docs/PRD.md (F1); docs/specs/user-stories.md (US-01, US-02, US-03 phần ghi cọc khi tạo)

## 1. Mục tiêu
Cho phép nhân viên ghi một đơn (đặc biệt đơn bánh kem tùy chỉnh) MỘT LẦN, đầy đủ thông tin bếp cần,
trong ≤ 90 giây với khách đã có. Thay thế việc gõ Google Sheet và chụp màn hình gửi bếp.

## 2. Người dùng và quyền
- staff (Hà, nhân viên quầy): tạo đơn cho chi nhánh của mình; KHÔNG sửa đơn giá; KHÔNG tạo đơn gấp.
- manager: như staff + sửa đơn giá + tạo đơn gấp (bắt buộc lý do).
- owner: như manager, cho mọi chi nhánh.
- Thiết bị chính: laptop ở quầy (màn hình ≥ 1280px); phải dùng được trên máy tính bảng.

## 3. Trong phạm vi
- Tìm khách theo số điện thoại; tạo khách mới (họ tên, SĐT bắt buộc; địa chỉ, sinh nhật tùy chọn).
- Thêm 1..n dòng sản phẩm; với sản phẩm is_custom_cake: chọn vị, chữ trên bánh (hoặc "không chữ"), ghi chú cho bếp.
- Chọn kênh (facebook | zalo | phone | walk_in | website), chi nhánh nhận, nhận tại tiệm hoặc giao hàng,
  giờ nhận/giao, địa chỉ giao (nếu giao), phí giao (nhập tay), ghi chú đơn.
- Ghi nhận tiền cọc ngay khi tạo (tùy chọn): phương thức, số tiền, mã giao dịch.
- Sinh mã đơn; lưu đơn ở trạng thái moi; ghi dòng đầu tiên vào lịch sử trạng thái.
- Sau khi tạo: hiển thị mã đơn và nút "Sao chép tóm tắt" để gửi khách xác nhận.

## 4. Ngoài phạm vi
- Sửa, hủy, chuyển trạng thái đơn (SPEC-002).
- Hiển thị ở màn hình bếp (SPEC-003) — spec này chỉ cần đảm bảo dữ liệu đủ cho bếp.
- Gửi tin nhắn/email/Zalo tự động cho khách; tạo mã VietQR; xác nhận chuyển khoản tự động.
- Tự tính phí giao hàng; mã giảm giá; tích điểm; xuất hóa đơn.
- Trang quản trị danh mục sản phẩm (dùng dữ liệu seed).
- KHÔNG tự thêm tính năng ngoài danh sách trên; đề xuất ghi vào mục 13.

## 5. Luồng chính
1. Nhân viên mở /orders/new.
2. Nhập SĐT -> hệ thống chuẩn hóa và tìm khách. Thấy: hiện tên + 3 đơn gần nhất. Không thấy: form khách mới, SĐT điền sẵn.
3. Thêm sản phẩm. Nếu là bánh kem tùy chỉnh: hiện thêm trường vị, chữ trên bánh, ghi chú bếp.
4. Chọn kênh, chi nhánh (mặc định chi nhánh của nhân viên), nhận/giao, giờ nhận.
5. (Tùy chọn) ghi nhận cọc.
6. Xem tóm tắt: tạm tính, phí giao, tổng, đã cọc, còn lại. Bấm "Tạo đơn".
7. Thành công: hiện mã đơn, tóm tắt; nút "Sao chép tóm tắt", "Tạo đơn mới".

## 6. Quy tắc nghiệp vụ
- QT-01: bánh kem tùy chỉnh bắt buộc vị; size xác định bởi sản phẩm (ví dụ "Bánh kem tùy chỉnh 20cm");
  chữ trên bánh tối đa 40 ký tự, giữ nguyên dấu; không chấp nhận emoji (bếp không viết được);
  nếu khách không muốn chữ: chọn "Không chữ" (cake_message = null).
- QT-02: bánh kem tùy chỉnh: delivery_at ≥ thời điểm tạo + 24 giờ. staff bị chặn.
  manager/owner được tạo "đơn gấp" khi nhập lý do; lý do lưu đầu trường note dạng "[ĐƠN GẤP] <lý do>".
- QT-03: delivery_at trong khung 07:00–21:00 giờ Việt Nam, không ở quá khứ.
- QT-05: SĐT chuẩn hóa về 10 chữ số bắt đầu bằng 0 trước khi tìm/lưu; customers.phone là UNIQUE.
- QT-06: unit_price lấy từ products.price tại thời điểm tạo; chỉ manager/owner sửa được.
- QT-09: mã đơn dạng BM-YYMMDD-XXX theo NGÀY TẠO giờ Việt Nam; XXX tăng dần từ 001 trong ngày, toàn chuỗi;
  không bao giờ trùng, kể cả khi nhiều người tạo cùng lúc.
- QT-10: tiền là số nguyên VNĐ. subtotal = tổng(quantity × unit_price); total = subtotal + shipping_fee.
- QT-11: cọc khi tạo: 0 < số tiền ≤ total. Nếu số tiền = total -> payment_status = paid; nếu > 0 -> deposit;
  không cọc -> unpaid. Ghi một dòng vào payments.
- QT-12: delivery_type = delivery thì bắt buộc delivery_address.
- QT-13: bấm "Tạo đơn" nhiều lần (hoặc gửi lại do mạng) chỉ tạo đúng một đơn.

## 7. Dữ liệu
- Đọc: customers (tìm theo phone), products (is_active = true), staff (vai trò, branch_id của người dùng).
- Ghi trong MỘT giao dịch (tất cả hoặc không gì cả):
  - customers: tạo mới nếu chưa có.
  - orders: code, customer_id, branch_id, channel, status = 'moi', delivery_type, delivery_at, delivery_address,
    subtotal, shipping_fee, total, deposit (tổng đã cọc), payment_status, note, created_by = staff.id.
  - order_items: product_id, quantity, unit_price, cake_message,
    options JSONB ví dụ {"flavor": "chanh_day", "kitchen_note": "ít ngọt"}.
  - payments (nếu có cọc): method (cash | bank_transfer | vietqr), amount, paid_at, reference.
  - order_status_history: from_status = null, to_status = 'moi', changed_by, changed_at.
- Không thay đổi schema trong spec này. Nếu thấy cần, dừng lại và ghi vào mục 13.

## 8. Giao diện
- Đường dẫn: /orders/new. Một trang, chia 4 khối theo thứ tự: Khách hàng -> Sản phẩm -> Nhận hàng -> Thanh toán,
  bên phải là khối Tóm tắt luôn hiển thị.
- Thứ tự trường bánh kem theo mẫu tin nhắn Hà đang dùng: Sản phẩm (size) -> Vị -> Chữ trên bánh -> Ghi chú bếp.
- Bộ đếm ký tự cho chữ trên bánh (x/40).
- Trạng thái: đang tìm khách; không tìm thấy; đang lưu (nút bị vô hiệu hóa, chữ "Đang tạo đơn..."); lỗi; thành công.
- Lỗi hiện ngay dưới trường liên quan; không xóa dữ liệu đã nhập khi lỗi.
- Dùng component có sẵn trong src/components/ui (shadcn/ui); không thêm thư viện giao diện mới.

## 9. Hợp đồng phía máy chủ
- Server action createOrder(input) trong src/features/orders/actions.ts.
- Schema Zod createOrderSchema trong src/features/orders/schema.ts, dùng chung cho client và server.
- Quy tắc thuần (QT-02, QT-03, QT-10, QT-11) đặt trong src/features/orders/rules.ts, có unit test.
- normalizePhone đã có ở src/lib/phone.ts — tái sử dụng, không viết lại.
- Đầu vào: thông tin khách (customerId hoặc khách mới), danh sách dòng, kênh, chi nhánh, nhận/giao, giờ nhận,
  phí giao, ghi chú, cọc (tùy chọn), rushReason (tùy chọn), idempotencyKey (chuỗi do client sinh mỗi lần mở form).
- Đầu ra thành công: { ok: true, order: { id, code } }.
- Đầu ra lỗi: { ok: false, code, fieldErrors? } với code thuộc:
  VALIDATION_ERROR | LEAD_TIME_TOO_SHORT | OUTSIDE_OPENING_HOURS | DEPOSIT_EXCEEDS_TOTAL | FORBIDDEN | UNKNOWN.
- Mọi kiểm tra quyền và quy tắc thực hiện ở máy chủ; kiểm tra phía client chỉ để phản hồi nhanh.

## 10. Lỗi và thông báo
| Tình huống | Thông báo |
|---|---|
| Thiếu vị bánh | "Vui lòng chọn vị bánh." |
| Chữ > 40 ký tự | "Chữ trên bánh tối đa 40 ký tự (hiện có N)." |
| Chữ có emoji | "Chữ trên bánh không dùng được biểu tượng cảm xúc." |
| Đặt trước < 24 giờ (staff) | "Bánh kem tùy chỉnh cần đặt trước ít nhất 24 giờ. Liên hệ quản lý để tạo đơn gấp." |
| Ngoài giờ mở cửa | "Giờ nhận cần trong khoảng 07:00–21:00." |
| SĐT sai | "Số điện thoại cần 10 chữ số, bắt đầu bằng 0." |
| Cọc > tổng | "Tiền cọc không được lớn hơn tổng đơn." |
| Mất kết nối | "Chưa tạo được đơn do mất kết nối. Thông tin vẫn được giữ, vui lòng thử lại." |

## 11. Tiêu chí chấp nhận
Toàn bộ kịch bản US-01, US-02 trong docs/specs/user-stories.md, cộng thêm:
- Given hai nhân viên bấm "Tạo đơn" cùng lúc, Then hai đơn có mã khác nhau.
- Given đơn tạo lúc 23:59 ngày 12/10 và 00:01 ngày 13/10 (giờ VN), Then mã lần lượt BM-261012-xxx và BM-261013-001 (nếu là đơn đầu ngày).
- Given staff chi nhánh Gò Vấp, When gửi createOrder với branch_id của Phú Nhuận, Then nhận FORBIDDEN.

## 12. Kiểm chứng end-to-end
- Chạy: npm run lint, npm run typecheck, npm test (unit), npm run test:e2e (Playwright).
- Unit test bắt buộc: QT-01, QT-02, QT-03, QT-05, QT-10, QT-11, QT-13 (mỗi test bắt đầu bằng mã quy tắc).
- E2E bắt buộc: luồng chính US-01; khách mới US-02; staff bị chặn đơn gấp.
- Kiểm thử thủ công trên máy tính bảng: tạo 1 đơn bánh kem có chữ "Mừng sinh nhật Mẹ Ánh", chụp màn hình kết quả.
- Bằng chứng nộp kèm PR: output các lệnh trên, 2 ảnh chụp (form đầy đủ, màn hình thành công), danh sách file đã đổi.

## 13. Câu hỏi mở
- [CẦN XÁC NHẬN] Có nên tách lý do đơn gấp thành cột riêng thay vì tiền tố trong note? (ảnh hưởng báo cáo sau này)
- [CẦN XÁC NHẬN] Khách chỉ có Zalo, không cung cấp SĐT: MVP bắt buộc SĐT; xem lại ở giai đoạn trợ lý AI.

## 14. Lịch sử thay đổi
- 1.1 (2026-01-26): thêm QT-13 (chống tạo trùng) và cấm emoji trong chữ trên bánh sau buổi đọc spec với Hà.
- 1.0: bản đầu tiên, viết sau phiên agent phỏng vấn.