Treatment plan — Từ lập kế hoạch đến hoàn thành & warranty

Bác sĩ khám, phát hiện bệnh, lập kế hoạch điều trị (treatment plan) dưới dạng quote. In phiếu tư vấn cho bệnh nhân xem. Bệnh nhân suy nghĩ, quay lại ký duyệt. Bác sĩ bắt đầu từng giai đoạn (stage), ghi nhận hoàn thành. Thu tiền cọc + hoàn cuối. Hệ thống tự động cấp warranty 5 năm (hoặc tuỳ dịch vụ).

Giao diện treatment plan — Luồng plan: DRAFT → APPROVED (BN ký) → IN_PROGRESS (làm từng stage) → COMPLETED + warranty

Bối cảnh

BN khám, bác sĩ phát hiện 4 cái răng cần trồng implant (giai đoạn 1) + 2 cái cần tẩy trắng (giai đoạn 2). Bác sĩ lập plan DRAFT, tổng giá 15 triệu (cọc 5 triệu). Lễ tân in phiếu tư vấn (Phiếu tư vấn — không hiển thị tiền). BN mang về suy nghĩ. Hôm sau BN quay lại, phê duyệt plan, trả cọc 5 triệu. Bác sĩ bắt đầu giai đoạn 1, hoàn thành implant, lập lab order. Sáu tháng sau, stage 2 xong (tẩy trắng). BN trả phần còn lại 10 triệu. Warranty 5 năm được cấp trên stage 1.

Diễn viên & quyền cần

Vai trò	Quyền	Hành động
Bác sĩ	`diagnosis.manage`, `treatment_plan.manage`, `document.print`	Lập diagnosis, tạo plan, assign doctor per stage, mark stage done, in phiếu tư vấn
Lễ tân	`treatment_plan.read`, `document.print`, `payment.manage`	In phiếu tư vấn, ghi nhận thanh toán, in phiếu thu
Bệnh nhân (không phần mềm)	—	Xem phiếu tư vấn, ký phê duyệt (giấy hoặc digital)
Kế toán	`treatment_plan.read`, `payment.manage`, `document.export`	Xem plan, quản lý tiền cọc + thanh toán cuối, xuất report

Quy trình từng bước

Bác sĩ lập chẩn đoán (diagnosis). Từ visit → tab Tooth Chart → ghi tất cả các phát hiện (decay, missing tooth, root issue, etc.) + suggested services (implant, crown, whitening, etc.). Save diagnosis → gắn visitId.
Bác sĩ tạo plan DRAFT. Từ diagnosis detail hoặc patient detail → "Tạo kế hoạch điều trị". Hệ thống snapshot service catalog + giá hiện tại. Bác sĩ chọn services, chia thành từng stage (stage 1: implant surgery, stage 2: whitening). Nhập tổng giá + cọc (tuỳ chọn). Lưu → plan status = DRAFT, giá chỉ là quote, chưa sinh charge hay outstanding.
Lễ tân in phiếu tư vấn (Phiếu tư vấn). Từ plan detail → "In phiếu tư vấn" (document type TREATMENT_PLAN). PDF hiển thị: tên BN, dịch vụ chi tiết, tổng tiền, ghi chú của bác sĩ, chữ ký. Không hiển thị: tiền cọc, tiền đã trả, tiền còn nợ (vì chưa approved). BN mang phiếu về suy nghĩ.
BN quay lại phê duyệt. BN ký tờ phiếu tư vấn (giấy) hoặc ký digital trong system (nếu clinic dùng). Lễ tân hoặc bác sĩ click "Phê duyệt kế hoạch" → plan status = APPROVED, CRM schedule follow-up task nếu không approve trong 3 ngày.
BN ký duyệt plan (APPROVED). Sau khi BN confirm tiền, lễ tân hoặc bác sĩ click "Duyệt" (APPROVED). Plan status = APPROVED → hệ thống tự động tạo charge line(s) từ stages có `createsCharge=true`. Outstanding hiện tại = total plan price - đã trả cọc.
Ghi nhận cọc (deposit payment). Lễ tân từ Patient 360 → "Ghi nhận thanh toán" → nhập cọc (5 triệu). Phiếu thu tạo, show cọc. Outstanding = 15 triệu - 5 triệu = 10 triệu.
Bác sĩ bắt đầu stage 1. Từ plan detail → stage 1 (Implant surgery) → "Chỉ định bác sĩ" (assign doctor nếu chưa). Chọn răng, ghi ghi chú, click "Bắt đầu làm" → process status = IN_PROGRESS.
Bác sĩ hoàn thành stage 1. Sau surgery, bác sĩ click "Hoàn thành công đoạn" trên process đó → process = COMPLETED. Nếu stage yêu cầu lab order (ví dụ: abutment), hệ thống có thể tạo lab order liên kết với stage này. Warranty snapshot lưu tại thời điểm này (warranty_duration = 5 năm từ ngày complete).
Sáu tháng sau — Stage 2 (Whitening). BN quay lại, bác sĩ bắt đầu stage 2 tương tự: assign doctor, start process. Hoàn thành whitening. Process = COMPLETED.
Ghi nhận thanh toán cuối (final payment). Lễ tân → "Ghi nhận thanh toán" → 10 triệu còn lại. Outstanding = 0. Phiếu thu = full invoice amount.
Mark plan COMPLETED. Bác sĩ hoặc admin click "Đánh dấu hoàn tất plan" → plan status = COMPLETED. Toàn bộ stages vẫn có thể xem, warranty vẫn có hiệu lực.

Kết quả mong đợi

Plan status timeline: DRAFT → APPROVED (ký duyệt) → IN_PROGRESS (làm stage) → COMPLETED.
Charge: Tạo tự động khi plan APPROVED, linked to plan. Charge state = pending payment cho đến khi payment cover toàn bộ charge.
Outstanding: Hiển thị trong Patient 360 tab "Tài chính": 15 triệu lúc approved, 10 triệu sau cọc, 0 sau payment cuối.
Stage process history: Mỗi stage có danh sách process (IN_PROGRESS, COMPLETED). Hệ thống ghi ngày, bác sĩ, giờ hoàn thành.
Warranty: Cấp trên stage COMPLETED, valid 5 năm (hoặc custom). Xem trong Patient 360 tab "Bảo hành".
Lab order: (nếu stage đòi hỏi) Tạo liên kết với stage, track progression (DRAFT → SENT_TO_LAB → IN_PROGRESS → READY → RECEIVED).

Khi nào hỏng & cách xử lý

Triệu chứ	Nguyên nhân	Khôi phục
Plan lập xong nhưng BN không see stage (chỉ see DRAFT)	Bác sĩ tạo plan nhưng chưa chỉ định doctor per stage	Bác sĩ vào plan detail, chọn từng stage → "Chỉ định bác sĩ". Hoặc lệ tân chỉ định bằng quyền treatment_plan.manage. Hiển thị lại.
Phiếu tư vấn hiện charge/payment (sai)	Template in bị lỗi, hiển thị thông tin tài chính	Không in ở phòng khám này. Liên hệ admin để fix template. Theo rule CI-04, phiếu tư vấn TREATMENT_PLAN không được hiển thị tiền cọc/thanh toán/outstanding.
Charge không tạo khi plan APPROVED	Plan status chưa chuyển APPROVED rõ ràng, hoặc service không có `createsCharge=true`	Kiểm tra plan status trong DB (admin query). Nếu status = PROPOSED, click "Duyệt" để convert APPROVED. Nếu status = APPROVED, charge phải tồn tại; nếu không, admin thêm charge manually.
BN trả cọc nhưng Outstanding vẫn full amount	Lễ tân ghi payment nhưng chưa link vào plan charge	Payment tạo từ Patient 360 "Ghi nhận thanh toán" tự động link vào charge sẵn. Nếu outstanding chưa update, admin query charge status hoặc refresh page. Outstanding = charge.amount - sum(payment), tính realtime.
Warranty không cấp (missing trong Patient 360)	Stage không bao giờ mark COMPLETED, hoặc process không hoàn thành	Bác sĩ vào plan detail, stage detail → process list → mark process COMPLETED nếu chưa. Stage phải có ít nhất một process COMPLETED để warranty được cấp. Refresh Patient 360.
Lab order không link stage (sau stage create)	Bác sĩ tạo lab order riêng, không link vào stage	Vào lab order detail → "Liên kết stage" (nếu có option) hoặc admin link trong DB. Lab order và stage vẫn độc lập, nhưng linking giúp track.

Dấu vết để lại (audit & branch ownership)

Audit log ghi: "Plan created (DRAFT)", "Plan proposed", "Plan approved", "Stage 1 started", "Stage 1 completed", "Payment recorded", "Warranty created", "Plan completed". Mỗi action ghi timestamp, user, branch (từ plan.branchId).

Plan status enum (CI-06)

Plan status: DRAFT (quote, no charge) → APPROVED (committed, charge created) → IN_PROGRESS (stage started) → COMPLETED (fulfilled) / CANCELED (nếu hủy trước approve). Hệ thống chặn transitions không hợp lệ (không được jump từ DRAFT sang COMPLETED).

Không fake zero (CI-02)

Outstanding và tiền cọc đều là số thực. Nếu lệ tân không có payment.read, những trường này sẽ show "Dữ liệu bị ẩn do thiếu quyền" — không bao giờ là 0 ₫ giả dù BN đã trả đủ.