Appearance
Tóm tắt quyết định (Decision Brief) — Hồ sơ bệnh án v2.3.0
Phiên bản: 2.1.0 Ngày: 30/04/2026 Độ phức tạp: L Module: Phòng khám / CRM / POS / Clinical / Settings Trạng thái package: Sẵn sàng review trước handoff. Team có thể kickoff và chạy C11-PREREQ-001..006; Phase 1/full build chỉ bắt đầu sau khi Tech Lead + QA Lead sign-off + P0 nullability/permission gates có người phụ trách + không còn blocker clarification
File này dùng để làm gì: đây là cửa vào của package. PO, Sếp, Tech Lead và nhóm delivery đọc file này trước để nắm phạm vi, quyết định, ảnh hưởng, rủi ro và biết nên đọc file nào tiếp theo.
Canonical rule: nếu brief này xung đột với
SOURCE_OF_TRUTH.md, ưu tiênSOURCE_OF_TRUTH.md. Brief chỉ tóm tắt và trỏ sang file owner; không duplicate API, SQL, ca kiểm thử hoặc toàn bộ Nhật ký quyết định.
Tài liệu đầu vào chuẩn
| File | Vai trò |
|---|---|
SOURCE_OF_TRUTH.md | Nguồn sự thật chuẩn, quyết định đã khóa và Phương án đã chốt |
EVIDENCE_PACK.md | Bằng chứng codebase, UI hiện tại, fact DB và rủi ro suy đoán |
prd.md | Quy ước nghiệp vụ: DEC, FR/AC, vòng đời, công thức, rủi ro |
ui-spec.md | Quy ước màn hình, luồng, copy, tooltip, trạng thái và trường hợp cá biệt |
dev-spec.md | Quy ước dữ liệu, API, migration, bảo mật, quan sát vận hành và việc triển khai |
qa-test-plan.md | Phạm vi kiểm thử, dữ liệu seed, ca kiểm thử, tiêu chí vào/ra |
permission-spec.md | Canonical owner phân quyền — 22 action / default seed / resolver / branch_mode / portal / cache / migration / masking / emergency / Compliance UI / 44 TC-PERM-* |
print-design-spec.md | Canonical owner thiết kế bản in — A4 mockup 7 biểu mẫu + header/footer/signature/watermark/versioning/retention |
user-guide.md | Hướng dẫn vận hành end-user — 7 role + KH + FAQ + hotline + onboarding tour |
go-live-checklist.md | Sẵn sàng vận hành, rollout, rollback và sign-off |
handoff.md | Timeline, RACI, blocker và thứ tự bàn giao cho team |
_consistency-matrix.md | Ma trận nhất quán cross-spec (FR/Field/DEC/Trạng thái/Permission/Notification/Export) |
_review-report.md | Kết quả Phase 5 VALIDATE: findings, đạt/gate và điều kiện go-live |
1) Tóm tắt 5 phút
- Tính năng số hóa hồ sơ bệnh án cho các chi nhánh có giấy phép phòng khám Da liễu hoặc Phẫu thuật Thẩm mỹ; chi nhánh spa thuần không bị ảnh hưởng và không thấy menu/module mới (DEC-001).
- Bản giấy in từ phần mềm, được BS/KH ký tay rồi tải bản scan đã ký lên hệ thống vẫn là gốc pháp lý (DEC-007). Phase 1 không làm bệnh án điện tử đầy đủ theo TT46/2018 như chữ ký số hoặc liên thông Sở Y tế.
- Giải pháp khóa theo mô hình
clinical_profile(Hồ sơ bệnh án chính, ổn định theo KH/CN/loại PK) vàclinical_record(Bệnh án lượt khám theoappointment + form_type); dữ liệu phiếu biểu mẫu lưu bằngclinical_form_instancetheo JSON Schema (DEC-002, DEC-005). - Day-1 phải có setup an toàn theo CN: bật module, giấy phép, danh mục kỹ thuật, phân loại dịch vụ — kỹ thuật, phân quyền, kiểm tra sẵn sàng và an toàn phát hành trước khi đang hoạt động (DEC-031).
- Package mở rộng cho vận hành thật: Trang xem an toàn (Sale), Bàn việc bác sĩ, Phiếu khách tự khai, Trang điều phối phòng khám và Chốt ngày phòng khám.
- v2.0 khóa thuật ngữ chuẩn (34 thuật ngữ canonical A1–E34); v2.1 làm sạch ngôn ngữ và bổ sung UI Spec chi tiết, không đổi DEC/FR/AC. Permission v2 vẫn là quy ước vận hành (DEC-043) — vai trò chỉ là cấu hình mẫu ban đầu, vận hành theo
role_module.actions + portal + branch_mode + backend enforcement, API trả dữ liệu tối thiểu, QA test grant/revoke/portal split. - v2.0 khóa Ma trận ranh giới ảnh hưởng (Impact Boundary Matrix) (DEC-044): module trực tiếp có người phụ trách/việc/test; module gián tiếp có guard; module không ảnh hưởng phải có smoke regression chứng minh không bị đổi menu, permission, dữ liệu hoặc job.
2) Bản đồ package
| File | Đọc khi cần | Phụ trách nội dung |
|---|---|---|
decision-brief.md | Cần nắm nhanh phạm vi, quyết định, rủi ro và đường đọc tiếp | PO/BA + Delivery Lead |
SOURCE_OF_TRUTH.md | Cần đối chiếu canonical truth hoặc xử lý conflict giữa docs | PO/BA + Tech Lead |
EVIDENCE_PACK.md | Cần xem bằng chứng code/màn hình/db/config trước khi thiết kế hoặc code | PO/BA + Tech Lead |
prd.md | Cần duyệt nghiệp vụ, DEC, FR/AC, vòng đời và công thức | PO/BA |
ui-spec.md | Cần thiết kế hoặc triển khai màn hình, trạng thái, copy, tooltip, trường hợp cá biệt; bản v2.1.0 đã đủ SCR-01..17 | UI/UX + FE |
dev-spec.md | Cần triển khai data/API/migration/security/tasks | Tech Lead + BE/FE |
qa-test-plan.md | Cần viết/rà ca kiểm thử và phạm vi regression | QA |
go-live-checklist.md | Cần cổng phát hành, rollout, rollback, sign-off vận hành | Ops + Tech Lead |
handoff.md | Cần chia việc, timeline, RACI, blocker và thứ tự bàn giao | Delivery Lead + Tech Lead |
_consistency-matrix.md | Đã đạt matrix v2.1.0; dùng để review cross-spec trước phát hành | PO/BA + Tech Lead + QA |
_review-report.md | Cần xem kết quả Phase 5 và điều kiện go-live còn mở | PO/BA + Tech Lead + QA + Ops |
3) Khóa phạm vi
Trong phạm vi
| # | Nội dung | Tham chiếu |
|---|---|---|
| 1 | Bật/tắt module Phòng khám theo CN; mặc định tắt với CN spa thuần | PRD FR-001, DEC-001 |
| 2 | Cấu hình 5 bước: loại phòng khám / giấy phép / danh mục kỹ thuật / phân loại dịch vụ — kỹ thuật / phân quyền nhân sự | PRD FR-002, FR-003 |
| 3 | Tạo lượt khám từ appointment hoặc walk-in; sau đó tạo bệnh án lượt khám theo appointment + form_type; visit-only log không tạo bộ BA đầy đủ | PRD FR-004, DEC-002, DEC-003 |
| 4 | Điền 7 biểu mẫu thực tế: BA Da liễu, BA Thẩm mỹ, cam đoan, cam kết, đơn thuốc, phiếu tiền sử dị ứng, phiếu theo dõi điều trị | PRD FR-005..FR-007 |
| 5 | Tự lưu nháp 30 giây, in bộ hồ sơ, tải bản scan đã ký + ảnh trước-sau điều trị | PRD FR-008, FR-009 |
| 6 | An toàn dị ứng, phân quyền dữ liệu 3 tầng theo Permission v2, audit tầng 3 và Mở quyền khẩn cấp | PRD FR-010, FR-011 |
| 7 | Sổ khám bệnh, sổ thủ thuật, thông báo nhắc BA, sequence generator | PRD FR-012..FR-014 |
| 8 | Kiểm tra sẵn sàng / an toàn phát hành, Trang xem an toàn (Sale), Bàn việc bác sĩ, Phiếu khách tự khai, Trang điều phối phòng khám, Chốt ngày phòng khám | PRD FR-015..FR-019 |
Ngoài phạm vi
| # | Không làm trong phase này | Lý do | Tham chiếu |
|---|---|---|---|
| 1 | Chữ ký số, QR pháp lý, bệnh án điện tử đầy đủ, liên thông Sở Y tế | Scope pháp lý + kỹ thuật vượt Day-1 | PRD A2; SoT mục 7 |
| 2 | Hồi cứu toàn bộ bệnh án giấy cũ trước khi bật module | Chi phí làm sạch quá lớn | DEC-028 |
| 3 | Luồng xin quyền + đồng ý xem tầng 3 cross-branch trong app | Cần legal sign-off riêng; Day-1 dùng Mở quyền khẩn cấp có audit | DEC-010 |
| 4 | Portal/mobile để KH tự khai từ xa ngoài chi nhánh | Phase này dùng tablet/quầy nội bộ để giảm rủi ro auth/OTP/consent | SoT mục 6 |
| 5 | Sale xem chẩn đoán, phiếu biểu mẫu BA, bản scan đã ký hoặc ảnh y tế tầng 3 | Quy định cứng không được override qua Permission v2 | DEC-009, DEC-032 |
4) Quyết định đã khóa
| Quyết định | Ý nghĩa nghiệp vụ / bàn giao | Tham chiếu |
|---|---|---|
| Module Phòng khám bật theo CN, mặc định tắt | Rollout không ảnh hưởng CN spa thuần; FE phải ẩn menu/CTA khi CN không đang hoạt động | DEC-001 |
Tách clinical_profile (Hồ sơ bệnh án chính) và clinical_record (Bệnh án lượt khám) | Dev không được dùng 1 bảng để vừa đại diện hồ sơ KH vừa đại diện từng lượt khám | DEC-002 |
Walk-in tạo appointment không có order_item_id; link muộn bằng order.reference_appointment_id | Bắt buộc refactor Appointment.OrderItemID → *uuid.UUID + null-guard 5 call site | DEC-003 |
Dịch vụ đang bán phải có phân loại 3 trạng thái; unclassified chặn phát hành | Không được suy luận dịch vụ chưa phân loại là không cần BA | DEC-006 |
| Bản giấy ký tay là gốc pháp lý; phần mềm lưu bản scan đối chiếu | UI/Go-live phải giữ luồng in, ký, scan; không thay bằng e-signature | DEC-007 |
| Phân quyền 3 tầng; Sale không xem tầng 3 | UI/API phải dùng Permission v2; mask dữ liệu nhạy cảm; log access tầng 3; vai trò chỉ là cấu hình mẫu ban đầu | DEC-008, DEC-009, DEC-043 |
Allergy risk unknown và high đều chặn hoàn thành BA cho thủ thuật | Phân loại thiếu dữ liệu là lỗi an toàn; không fallback confirm-skip | DEC-011 |
Bàn việc bác sĩ có 6 nhóm việc; need_record chỉ sinh khi dịch vụ thật sự cần BA | Tránh việc giả làm BS mất niềm tin vào danh sách việc | DEC-033 |
| Phiếu khách tự khai dùng one-time token; BS nhận mới ghi vào phiếu biểu mẫu BA | KH không gửi tự do customer_id/branch_id; server phải validate đúng KH/CN/appointment/record | DEC-034 |
| Chốt ngày phòng khám theo cấu hình CN; mặc định 20:00 Asia/Ho_Chi_Minh | Ops/QL CN có gate cuối ngày cho BA nháp, bản in chưa scan và escalation | DEC-036 |
Clinical tables đặt ở Hasura source ecommerce; account id lưu dạng TEXT/remote_relationship | Dev không được viết FK từ bảng clinical sang default.account nếu nằm khác source | DEC-037 |
Hasura action/event/scheduler dùng endpoint chung /actions /events /schedulers | Metadata không cấu hình webhook /actions/foo nếu Gin vận hành không expose đường dẫn đó | DEC-038 |
Raw clinical tables không expose cho vận hành role user | FE/vận hành đọc qua secure view/action có business permission; Sale không suy luận tầng 3 từ raw record/form | DEC-040 |
Runtime live gate theo clinic_module_publication.status='live' AND effective_at<=now() | branch.features.clinic_enabled=true chỉ là setup flag, không được dùng một mình để mở action/scheduler/UI đang hoạt động | DEC-041 |
Trạng thái Đã ký + scan đủ chỉ khi checklist scan bắt buộc đủ theo case | Không được xem 1 file bất kỳ là đủ pháp lý/vận hành | DEC-022 |
5) Bản đồ ảnh hưởng
| Khu vực | Tái sử dụng / mở rộng / xây mới | Điều team cần chú ý | Tham chiếu |
|---|---|---|---|
| UI — Settings (Branch Detail), Customer Detail (CRM), Appointment, POS Order | 🔧 Mở rộng các màn lõi và quy ước hiện có | Bắt buộc người phụ trách, việc triển khai và test; mọi UI guard theo action/portal/branch_mode, không hard-code role; walk-in/nullability và late-link là P0 | ui-spec.md, EvidencePack 2.1 |
| UI — Bàn việc bác sĩ, Trang xem an toàn (Sale), Phiếu khách tự khai, Trang điều phối phòng khám | 🆕 Xây mới các màn vận hành | Danh sách việc không sinh giả; Sale không thấy tầng 3; intake token 15 phút kiểm tra đúng KH/CN/appointment; chốt ngày không cho đóng nếu còn P0 | ui-spec.md |
| Backend / API — clinical handlers, services, structs | 🆕 Xây mới clinical layer (5–10 action + 8–12 event + 2–3 scheduler) + 🔧 refactor Appointment.OrderItemID | Tái sử dụng pattern dispatch /actions /events /schedulers; không expose raw form_data; print chỉ là bản tham chiếu, bản giấy ký tay + scan checklist mới đủ pháp lý | dev-spec.md C2/C5 |
| Database / Hasura | 🆕 Xây mới 18 bảng clinical ở source ecommerce + 🔧 ALTER branch ADD features JSONB + insert 8 module + 22 action mới vào Permission v2 | Cross-source FK qua remote_relationships (không FK cứng cross-DB); Hasura permission cho role user trên clinical tables phải là deny (DEC-040) | dev-spec.md C4/C7/C8 |
| Notification / Export | 🔧 Mở rộng (thêm 7 trigger clinical mới, tái sử dụng pattern notification_queue) + 🆕 xây mới sổ khám / sổ thủ thuật / audit export | Push chỉ deeplink/text an toàn, không gửi chẩn đoán/form/scan; export tầng 3 cần view_medical_detail | ui-spec.md B4/B5, dev-spec.md C5 |
| QA / Regression | Mở rộng theo Ma trận ranh giới ảnh hưởng | 99 core TC + regression boundary D6 (trực tiếp + gián tiếp + smoke không ảnh hưởng) | qa-test-plan.md D5/D6 |
6) Rủi ro và blocker
| Mức | Rủi ro / blocker | Phụ trách | Cách xử lý | Tham chiếu |
|---|---|---|---|---|
| Cao | appointment.order_item_id đã NULL ở DB nhưng Go struct Appointment.OrderItemID không nullable | BE Dev | Refactor *uuid.UUID, audit/null-guard 5 call site (appointment_update.go:191, appointment_insert.go:81/176/202, ticket.go:526), test walk-in | Dev Spec C2, C11 |
| Cao | Thiết kế DB/API sai source hoặc sai webhook đường dẫn làm migration/metadata deploy thất bại | Tech Lead + BE | Clinical tables ở ecommerce, account id dạng TEXT/remote_relationship; webhook dùng đường dẫn chung /actions /events /schedulers | DEC-037, DEC-038 |
| Cao | Sai phân quyền tầng 3 làm Sale/role không y tế xem được chẩn đoán hoặc bản scan | TL + QA | Permission v2 action seed; backend resolver least-data; masked view; medical_record_access_log; QA test grant/revoke/portal split | PRD FR-011, QA D2.11 |
| Cao | Raw clinical_record/clinical_form_instance lỡ expose cho vận hành user làm bypass permission 3 tầng | TL + BE + QA | Không cấp raw select/mutation cho user; dùng secure view/action; security test metadata | DEC-040, Dev C5.14 |
| Cao | Dịch vụ đang bán chưa phân loại, thiếu tài liệu Legal/SYT hoặc thiết bị scan/print chưa đạt nhưng hệ thống vẫn đang hoạt động | Ops + PO | Kiểm tra sẵn sàng R-01..R-10 chặn phát hành; không cho đang hoạt động CN khi còn blocker | PRD FR-015, Go-live E1 |
| Cao | Allergy risk unknown bị hiểu là medium hoặc bỏ qua | Medical Lead + BE | Trạng thái mặc định block; bắt Medical Lead phân loại trước khi đang hoạt động | PRD FR-010 |
| Cao | Trạng thái Đã ký + scan đủ bị hiểu là chỉ cần 1 scan file | PO + QA + BE | Bắt checklist scan theo case trước khi chuyển trạng thái; QA phủ refusal evidence | PRD FR-009, QA TC-041 |
| Cao | Legal/SYT và hỗ trợ D0 chưa có tài liệu/người phụ trách rõ | PO + Ops + Legal | Go-live NO-GO nếu thiếu văn bản xác nhận legal/SYT, roster D0, hotline, thiết bị scan/print | Go-live E1-E5 |
| Cao | Scope creep / regression lan sang module không liên quan | PO + TL + QA | Dùng Ma trận ranh giới ảnh hưởng v2.0 làm khóa phạm vi: module trực tiếp có người phụ trách/việc/test, module gián tiếp có guard, module không ảnh hưởng có smoke regression D6 | DEC-044, PRD A12, QA D6 |
| Trung bình | BS không dùng Bàn việc bác sĩ nếu danh sách việc có việc giả hoặc thiếu người phụ trách | FE + BE | Người phụ trách queue rõ; need_record chỉ join dịch vụ cần BA; QA test false-positive | DEC-033, QA TC |
| Trung bình | Bản scan đã ký bị trễ → hồ sơ pháp lý chưa hoàn chỉnh | QL CN + Ops | Chốt ngày phòng khám; reminder theo CN; escalation sau cutoff | DEC-036 |
| Trung bình | Legal/retention chưa chốt đủ cho pilot | Legal + Infra | Dùng Go-live gate; không mở rộng ngoài pilot nếu chưa đạt | Go-live E1 |
| Trung bình | Rollback production chạy down migration sau khi đã có BA thật | TL + DBA + Ops | D0+ chỉ pause/code rollback giữ DB; down migration chỉ dev/staging/pre-D0 | Go-live E4 |
7) Tóm tắt bàn giao
| Nhóm | Việc chính | File cần đọc |
|---|---|---|
| PO/BA | Chốt phạm vi, non-goal, DEC, công thức và quyết định còn mở | decision-brief.md, SOURCE_OF_TRUTH.md, prd.md |
| UI/UX | Thiết kế màn hình theo delta/reuse, copy, tooltip, trạng thái | ui-spec.md |
| FE | Triển khai shell, Bàn việc bác sĩ, Phiếu khách tự khai, masked view, wizard setup | ui-spec.md, dev-spec.md |
| BE | Triển khai migration, action, secure view, event, scheduler, permission | dev-spec.md |
| QA | Test P0 theo risk: nullability, allergy, permission, scan, Bàn việc bác sĩ, intake | qa-test-plan.md |
| Ops / TL | Điều phối pilot, kiểm tra sẵn sàng, rollback, sign-off | go-live-checklist.md, handoff.md |
8) Điểm còn mở
| ID | Câu hỏi còn mở | Phụ trách | Hạn chót | Nếu chưa chốt thì ảnh hưởng |
|---|---|---|---|---|
| PD-LEGAL-001 | Retention 10 năm: hot MinIO 1 năm + cold archive 9 năm — Legal/Infra duyệt? | Legal + Infra | Trước pilot T-7 | Block mở rộng production sau pilot |
| PD-LEGAL-002 | Cán bộ quản lý phòng khám/Sở Y tế chấp nhận luồng giấy ký tay + scan reference? | PO + Legal | Trước pilot T-7 | Block go-live nếu yêu cầu thay đổi form/quy trình |
| PD-LEGAL-003 | Văn bản xác nhận mẫu giấy + retention + scan reference + trách nhiệm ký tay cho pilot? | Legal + PO | Trước pilot T-7 | NO-GO nếu chỉ xác nhận miệng |
| PD-OPS-000 | D0 support owner, hotline, escalation roster, scanner/printer/account test của từng CN pilot? | Ops + QL CN | Trước UAT | NO-GO nếu còn TBD |
| PD-OPS-001 | Mỗi CN pilot dùng cutoff/reminder nào nếu khác mặc định 20:00? | Ops + QL CN | Trước UAT | Nếu chưa chốt, dùng mặc định + theo dõi lệch cấu hình |
| PD-DATA-001 | Có cần import ICD-10 mới hơn bản BYT 2015 trước pilot? | Medical Lead + BE | Trước migration staging | Không chặn spec; ảnh hưởng seed data + test search ICD-10 |