Tài liệu trình bày đa bên liên quan
Chức năng, luồng nghiệp vụ và kế hoạch nâng cấp LapVIP
Tài liệu được tổng hợp trực tiếp từ source dự án, tài liệu kiến trúc, sơ đồ quyền, kế hoạch UI/UX và hồ sơ kiểm thử hiện có. Mục tiêu là giúp chủ doanh nghiệp, kế toán, kho, bán hàng, chăm sóc khách hàng và đội kỹ thuật cùng nhìn một hệ thống theo một ngôn ngữ chung.
Tóm tắt điều hành
Hệ thống đã có nền vận hành rộng và nhiều lớp bảo vệ. Giai đoạn tiếp theo không nên là viết lại toàn bộ, mà là tiếp tục chuẩn hóa ownership, hoàn thiện vận hành production và tối ưu trải nghiệm theo từng vai trò.
Đã bao phủ chuỗi vận hành chính
Danh mục, nhập kho, serial, chuyển kho, POS, thanh toán, khách hàng, bảo hành, công nợ, quỹ, tài chính, báo cáo, hoa hồng, phân quyền và nhật ký đã có luồng riêng.
Đã có audit, conflict và realtime
Mutation quan trọng có revision/conflict, audit log, notification/outbox và cơ chế đồng bộ nhiều tài khoản; các quyền tài chính và chi nhánh được tách theo scope.
Production promotion còn điều kiện
Candidate hiện tại đã có bằng chứng Final Mega Gate và staging, nhưng production promotion mới vẫn chờ phê duyệt; một số công việc bảo trì hạ tầng cần cửa sổ kiểm soát.
Cách đọc trạng thái“Code complete”, “integration verified”, “staging verified” và “production released” là bốn mức khác nhau. Tài liệu này không coi một tính năng đã phát hành chỉ vì source hoặc test cục bộ đã hoàn thành.
Giá trị đối với từng bên
Mỗi bên nhìn cùng một dữ liệu nhưng có mục tiêu kiểm soát khác nhau.
Chủ doanh nghiệp
Nhìn được doanh thu, lợi nhuận, tồn, dòng tiền, công nợ, hiệu suất nhân viên và rủi ro vận hành theo chi nhánh.
Kế toán & kiểm soát
Truy ngược số liệu về chứng từ, kiểm tra ngày nghiệp vụ, thanh toán, void, hoàn tiền, công nợ, quỹ và lịch sử điều chỉnh.
Đội cửa hàng
Tìm hàng nhanh, chọn đúng serial, giữ nháp, bán/thu tiền/in phiếu, nhận bảo hành và xử lý kho mà không cần làm việc trên nhiều hệ thống rời.
Quản lý kho
Biết hàng đang ở đâu, trạng thái gì, đã xuất hay đang chuyển, nhận thiếu hay khớp, và có thể đối soát theo exact stock ID.
Nhân sự & quản lý
Theo dõi doanh số, chỉ tiêu, hoa hồng, phạm vi chi nhánh và hiệu lực tài khoản theo chính sách rõ ràng.
Đội kỹ thuật
Có test, release guard, staging, backup/restore, performance budgets và cấu trúc module để nâng cấp theo package thay vì sửa dồn vào God File.
Bản đồ hệ thống
Từ danh mục tới báo cáo quản trị
Luồng dữ liệu cốt lõi đi từ dữ liệu nền, phát sinh chứng từ, thay đổi tồn và tiền, sau đó được đối soát, báo cáo và ghi nhật ký.
Danh mục
Sản phẩm · chi nhánh · NCC
Sản phẩm · chi nhánh · NCC
→
Nhập kho
Phiếu nhập · serial · công nợ NCC
Phiếu nhập · serial · công nợ NCC
→
Tồn kho
Stock item · trạng thái · cảnh báo
Stock item · trạng thái · cảnh báo
Chuyển kho
Xuất · nhận một phần · đối soát
Xuất · nhận một phần · đối soát
→
POS / Đơn hàng
Giỏ · khuyến mãi · hàng tặng
Giỏ · khuyến mãi · hàng tặng
→
Thanh toán
Tiền mặt · ngân hàng · hỗn hợp
Tiền mặt · ngân hàng · hỗn hợp
→
Công nợ & Quỹ
Phải thu · phải trả · sổ quỹ
Phải thu · phải trả · sổ quỹ
→
Tài chính & Báo cáo
P&L · cashflow · tồn · hoa hồng
P&L · cashflow · tồn · hoa hồng
→
Điều hành
Quyết định · cảnh báo · đối soát
Quyết định · cảnh báo · đối soát
Các lớp kiểm soát bao quanh
Những lớp này không tạo chứng từ chính nhưng bảo đảm hệ thống đúng, an toàn và có thể truy vết.
Phân quyền
Role, permission, sale scope, stock scope, branch/warehouse scope và quyền nhạy cảm như cost:read.
Audit & đối soát
Ghi actor, entity, revision, thao tác và bằng chứng; reconciliation phát hiện lệch tiền, nợ, quỹ và kho.
Realtime & notification
Event có cursor, branch scope, dedupe, reconnect, targeted invalidation và thông báo theo người nhận.
Draft & conflict
Giữ dữ liệu chưa lưu, chống ghi đè, hiện diff khi revision cũ và cho người dùng quyết định cách xử lý.
Luồng kỹ thuật một thao tác ghi
1Người dùng thao tácForm, modal hoặc table action
2Kiểm tra quyềnCapability + branch/warehouse scope
3Validate nghiệp vụDTO, invariant, revision, lock
4Transaction PostgreSQLDomain rows + audit + outbox
5Commit & phản hồiPayload, error contract hoặc 409
6Đồng bộ giao diệnInvalidate đúng query, giữ draft/focus
Danh mục chức năng
16 không gian vận hành chính
Các tab dưới đây bám theo cấu hình điều hướng thật của dự án. Có thể tìm nhanh theo tên chức năng, vai trò hoặc nghiệp vụ.
Luồng bán hàng
POS, đơn hàng, thanh toán và phiếu bán
Điểm kiểm soát chính là chọn đúng hàng tại đúng chi nhánh, giữ identity của serial/hàng tặng, ghi tiền đúng một lần và tạo chứng từ có thể truy vết.
1Chọn chi nhánh bánBackend kiểm tra sale scope
2Tìm/quét sản phẩmSearch nhóm hoặc exact serial lookup
3Chọn stock itemSerial exact ID; hàng thường theo số lượng
4Khách hàng & ưu đãiKhách, khuyến mãi, quà tặng
5Tính tiềnGiá, giảm, VAT, đặt cọc, còn lại
6Thanh toánTiền mặt, ngân hàng hoặc hỗn hợp
7Ghi nhậnSale + lines + payments + stock movement
8Phiếu & đồng bộReceipt, audit, notification, realtime
Business invariants bắt buộc
- Một serial chỉ được bán một lần và phải thuộc chi nhánh được phép.
- Hàng tặng dùng identity
is_gift, không suy ra chỉ từ giá bằng 0. - Quà tặng không mang warranty/return policy như hàng bán thông thường nếu contract quy định bằng 0.
- Tổng payment lines không vượt số tiền cần thu; đặt cọc và còn lại phải có nguồn tiền rõ ràng.
- Ngày chứng từ không được sau ngày hóa đơn/thu tiền theo invariant hiện hành.
- Preview phiếu và phiếu đã lưu phải lấy cùng nguồn dữ liệu.
Điểm dễ phát sinh lỗi
- Hai nhân viên cùng chọn một serial.
- Payment timestamp không được normalize trước khi so sánh.
- Khuyến mãi có quan hệ cũ/inactive bị xóa khi edit.
- Refresh nền làm mất khách hàng, giỏ, focus hoặc payment draft.
- Row click và nút “Chọn bán” dùng chung event, mở sai modal.
- Chứng từ đã tạo nhưng audit/outbox không cùng transaction.
| Tình huống | Kết quả mong đợi | Bằng chứng cần có | Owner kiểm soát |
|---|---|---|---|
| Bán thu đủ | Sale, payment và stock movement khớp; công nợ bằng 0 | DB state + receipt + audit | Sales / payment destination / receipt |
| Bán đặt cọc | Phần thu và phần còn nợ tách rõ, QR dùng số còn lại | Payment allocations + debt report | POS payment model / backend sales |
| Thanh toán hỗn hợp | Mỗi dòng tiền đúng tài khoản, tổng bằng tiền thu | Payment lines + funds ledger | Payment line contract |
| Conflict serial | HTTP 409, giữ draft, hiện server revision và cho retry | Concurrent test + browser flow | Revision check / conflict modal |
| Trả hàng | Đảo đúng tồn, doanh thu, tiền/công nợ và hoa hồng | Return domain + reconciliation | Returns / finance / commission |
Kho & logistics
Nhập kho, tồn kho, chuyển kho và đối soát
Dự án hỗ trợ cả hàng có serial/IMEI và hàng không serial. Kho phải dựa trên stock item/ledger thật, không dựa vào số đếm tạm trên client.
Luồng nhập kho
1Chọn NCC & chi nhánhKiểm tra stock scope
2Nhập dòng hàngSerial exact hoặc quantity
3Ghi phiếu nhậpReceipt + lines + payment/debt
4Tạo tồnStock items + movements
Luồng chuyển kho
1Chọn kho nguồn/đíchPhân quyền độc lập
2Chọn exact stockQuantity/serial → exact IDs
3Xuất chuyểnTrạng thái transferring/shipped
4Kho nhận xác nhậnNhận đủ, một phần hoặc lệch
5Đối soátKhớp, giải trình, hoàn tất
Serial duy nhất
Một serial/IMEI không được xuất hiện đồng thời ở nhiều vị trí hoặc được bán/chuyển lần thứ hai.
Kho nhận là bên xác nhận
Phiếu chuyển chỉ hoàn tất khi kho nhận có quyền xác nhận và mọi dòng đang chờ đã được xử lý.
Nhận một phần
Không được chuyển phiếu sang hoàn tất khi vẫn còn dòng/quantity chưa nhận hoặc có discrepancy chưa đối soát.
Filter sau pagination
Nếu taxonomy/status lọc ở client sau khi server đã phân trang, số lượng và lựa chọn sẽ sai. Filter phải tham gia resource key và SQL trước count/page.
State hiển thị không đồng nhất
Dashboard, Kho, POS và Chuyển kho phải dùng cùng định nghĩa “available”, “transferring”, “repair”, “sold”.
Đối soát chủ động
Tăng khả năng drill-down từ cảnh báo tồn/transfer discrepancy về exact movement, actor và chứng từ gốc.
Khách hàng & hậu mãi
Hồ sơ khách hàng, bảo hành và sửa chữa
Luồng hậu mãi cần liên kết đúng khách hàng, máy/serial, lịch sử mua, trạng thái xử lý, chi phí và người phụ trách.
1Tìm/tạo khách hàngChuẩn hóa tên, điện thoại, branch scope
2Mở hồ sơMua hàng, thanh toán, nợ, trả hàng
3Tiếp nhận máySerial/sản phẩm, tình trạng, yêu cầu
4Chẩn đoán & sửaTrạng thái, dịch vụ, linh kiện, phụ trách
5Thu phí/cập nhật nợPayment, quỹ và công nợ
6Bàn giaoReceipt, timeline, notification, audit
Kiểm soát dữ liệu khách hàng
- PII chỉ được trả về sau khi kiểm tra quyền và branch scope.
- Timeline dùng payment rows làm nguồn thu tiền; không cộng trùng trường mirror.
- Avatar dùng cùng media pipeline, URL thumbnail gọn, có MIME/content validation.
- Search danh sách khách hàng phải server-owned khi dữ liệu vượt bootstrap cap.
Kiểm soát bảo hành/sửa chữa
- Serial tiếp nhận phải liên kết đúng khách hoặc có lý do tiếp nhận ngoài bảo hành.
- State machine phải chặn chuyển trạng thái không hợp lệ.
- Phí sửa chữa phải phản ánh đồng nhất ở payment, debt, funds và reports.
- Hai tài khoản cập nhật đồng thời phải dùng revision/conflict.
| Vai trò | Việc cần thấy | Hành động chính | Rủi ro cần chặn |
|---|---|---|---|
| CSKH | Hồ sơ, lịch sử mua, liên hệ, tình trạng | Tạo khách, cập nhật hồ sơ, mở ticket | Lộ PII sai chi nhánh |
| Nhân viên bảo hành | Máy, serial, timeline, checklist | Nhận, chẩn đoán, cập nhật, bàn giao | Chuyển trạng thái sai, mất ghi chú |
| Kế toán | Phí, đã thu, còn nợ, tài khoản nhận | Thu/hoàn tiền, đối soát | Cộng trùng payment hoặc sai kỳ |
| Quản lý | Thời gian xử lý, backlog, SLA | Phân công, ưu tiên, xem báo cáo | Không thấy hồ sơ quá hạn |
Tài chính & kế toán
Từ chứng từ nguồn tới số liệu quản trị
Nguyên tắc chính: số liệu phải có nguồn chứng từ, tổng phải theo toàn bộ phạm vi lọc, và nghiệp vụ hủy/trả/void không được làm biến mất lịch sử.
1Chứng từ nguồnBán, nhập, trả, sửa chữa, chi phí
2Dòng tiềnPayment destination + method + date
3Phân bổSale, purchase, repair, advance
4Công nợPhải thu/phải trả, credit/refund
5Sổ quỹOpening + income − expense = closing
6P&L và báo cáoRevenue, COGS, expense, net profit
Doanh thu
Lấy từ chứng từ bán hợp lệ theo ngày nghiệp vụ và filter; phải loại hoặc điều chỉnh đúng chứng từ hủy/trả.
Giá vốn
Chỉ người có cost:read được xem; backend vẫn cần tính đúng cho báo cáo và hoa hồng.
Công nợ
Phải phân biệt nợ, credit, refund và settled; không cho sửa trực tiếp số dư nguồn nếu không có correction evidence.
Quỹ
Opening balance, thu, chi, void và closing balance phải đối soát được theo tài khoản/chi nhánh.
Lợi nhuận
Doanh thu − giá vốn − chi phí ± điều chỉnh; cần giữ snapshot/chính sách theo kỳ khi áp dụng hoa hồng.
Ngày nghiệp vụ
Document date, invoice date, paid_at và return date cần mapping rõ để không ghi sai kỳ.
| Câu hỏi kiểm soát | Rủi ro | Cách xác minh | Vai trò phê duyệt |
|---|---|---|---|
| Payment có bị cộng cả payment rows và sales.paid? | Doanh thu/đã thu bị nhân đôi | Đối chiếu query + test fixture + SQL | Kế toán trưởng |
| Trả hàng có đảo đúng tiền, tồn, nợ và hoa hồng? | Lợi nhuận và tồn sai | Journey xuyên module + reconciliation | Kế toán + Kho + Sales |
| Void có còn xuất hiện trong báo cáo? | Số liệu kỳ sai | SQL filter + report tests | Kế toán |
| Tổng có dựa trên toàn bộ filter hay page hiện tại? | KPI không khớp bảng | Server summary trước pagination | BI/Kế toán |
| Credit/advance có exact source linkage? | Không giải trình được số dư | Settlement allocation + audit trail | Kế toán trưởng |
Nhân sự & quản trị
Nhân viên, doanh số, chỉ tiêu, hoa hồng và báo cáo
Hệ thống cần giữ lịch sử nhân viên/account, scope chi nhánh và chính sách hoa hồng theo thời điểm, không để thay đổi hiện tại làm sai dữ liệu quá khứ.
Luồng nhân sự & account
1Tạo nhân viênDanh tính, liên hệ, trạng thái
2Liên kết accountRole, permission, branch scope
3Vận hànhActor trên sale, audit, assignment
4Ngừng hoạt độngKhóa account, giữ lịch sử
Luồng hoa hồng
1Doanh số hợp lệSale/branch/employee scope
2Áp chính sáchPackage, tier, category, target
3Điều chỉnhReturn, correction, locked period
4Chốt & báo cáoSummary, detail, history
Cơ sở tính hoa hồng
Doanh thu, lợi nhuận, nhóm sản phẩm, gói dịch vụ, chỉ tiêu và mức đạt phải được chủ doanh nghiệp phê duyệt thành chính sách rõ.
Self-only và cross-employee
Tài khoản thông thường chỉ xem chính mình; người có report/permission scope mới xem nhân viên khác trong phạm vi cho phép.
Không sửa ngược quá khứ
Đổi chi nhánh, account hoặc chính sách mới không được làm thay đổi doanh số/hoa hồng đã ghi nhận ở kỳ cũ nếu không có correction batch.
| Báo cáo | Đối tượng | Filter | Drill-down | Quyền nhạy cảm |
|---|---|---|---|---|
| Doanh số nhân viên | Sale/Manager | Ngày, chi nhánh, nhóm hàng | Hóa đơn, khách hàng | reports:sales / reports:finance |
| Hoa hồng | Nhân viên/Quản lý | Kỳ, package, tier | Sale lines, correction | cost:read khi liên quan lợi nhuận |
| Tồn & luân chuyển | Kho/Quản lý | Kho, trạng thái, taxonomy | Stock item, movement | stock:write / cost:read |
| Tài chính | Kế toán/Chủ | Kỳ, chi nhánh, tài khoản | Payment, debt, receipt | reports:finance |
Bảo mật & đồng bộ
Tài khoản, permission, session, MFA, realtime và notification
Ẩn nút trên UI là chưa đủ. Backend phải kiểm tra capability, chi nhánh, kho, actor/target role và MFA tại mọi mutation nhạy cảm.
1Đăng nhậpPassword policy + rate limit
2MFA khi cầnTOTP/recovery, step-up scope
3SessionCookie/Bearer, idle, revoke
4PermissionRole + explicit scope + branch range
5MutationCSRF, validation, revision, audit
6RealtimeScoped events, cursor, catch-up
7NotificationRecipient scope, unread, deep link
Sale và Stock độc lập
Một account có thể bán tại chi nhánh A nhưng chỉ nhập/xuất tại kho B. Không được suy quyền kho từ home branch hoặc quyền bán.
Quản trị theo containment
Manager không được cấp role, permission hoặc branch range vượt phạm vi của chính mình.
Session tự quản
Người dùng chỉ xem/revoke session của mình; global session listing phải ở sau quyền quản trị.
Realtime có scope
Event có event ID/cursor, branch/entity scope, dedupe, out-of-order protection và catch-up sau reconnect.
Dirty form được bảo vệ
Realtime chỉ invalidate/refresh dữ liệu liên quan, không ghi đè form hoặc đóng modal người dùng đang nhập.
Notification có nguồn thật
Backend/outbox là nguồn sự thật; unread count và deep link phải nhất quán giữa tab và thiết bị.
| Actor | Hành động | Điều kiện | Kết quả khi không đủ quyền | Audit |
|---|---|---|---|---|
| Sales | Tạo sale | sale:create + sale branch | 403, không thay đổi dữ liệu | Ghi thành công; denial log theo policy |
| Warehouse | Nhận chuyển kho | transfer:write + stock branch kho nhận | 403, phiếu giữ nguyên | Actor + transition |
| Manager | Sửa account | permissions:write + target containment | 403 nếu target/range vượt quyền | Before/after không chứa secret |
| Account owner | Đổi password | Mật khẩu hiện tại + CSRF + rate limit | Thông báo lỗi an toàn | Security event không chứa password |
| Finance reader | Xem giá vốn | cost:read | Mask ở API và UI | Không bắt buộc cho read thông thường |
Kiến trúc kỹ thuật
Nền hiện tại và hướng modular hóa
Ứng dụng là frontend JavaScript module, backend Python/FastAPI compatibility layer và PostgreSQL. Dự án đã tách nhiều domain nhưng hai file điều phối chính vẫn còn lớn.
Kiến trúc dữ liệu frontend
PageDataRegistry → HydrationCoordinator → QueryClient → ResourceStore → RenderScheduler
Mục tiêu: một owner tải dữ liệu, query key đầy đủ filter, dedupe request, targeted invalidation và render không gọi API.
Kiến trúc mutation backend
Route/Auth → Validation → Domain service → PostgreSQL transaction → Audit/Outbox
Mục tiêu: route mỏng, service sở hữu invariant/transaction, repository sở hữu persistence, error contract ổn định.
| Thành phần | Vai trò hiện tại | Điểm tốt | Nợ kỹ thuật / hướng tiếp theo |
|---|---|---|---|
| server.py | Compatibility/dispatch và một phần orchestration | Đã có nhiều module backend tách riêng | Tiếp tục di chuyển route/business/SQL theo boundary, không tách chỉ để giảm dòng |
| src/app.js | Bootstrap, wiring, event orchestration | Page modules, coordinator, lazy modal và feature modules đã có | Giảm cross-domain conditionals, giữ app.js như adapter mỏng |
| PostgreSQL | Domain truth, ledger, sessions, audit, outbox | Có integration/concurrency/migration tests | Tăng constraint/index/query-plan và restore drill theo từng migration |
| Release pipeline | Build, artifact, staging, smoke, rollback | Final candidate đã qua Mega/Staging | Promotion cần authorization; bảo trì archive_timeout/Docker trong cửa sổ riêng |
| UI system | Tokens, shell, page controls, modal, table, charts | Đã có owner dùng chung và mobile/accessibility tests | Tiếp tục child-page lazy boundary, visual regression và thu hồi bundle headroom |
Nguyên tắc nâng cấpKhông tạo store/API/component thứ hai. Mỗi package phải chỉ ra owner hiện tại, root cause, scope, test, rollback và ảnh hưởng bundle trước khi sửa.
Vấn đề & rủi ro
Những điểm cần kiểm soát trong giai đoạn tiếp theo
Danh sách phân biệt vấn đề đang mở, rủi ro kiến trúc và công việc bảo trì. Các nội dung đã được giảm thiểu không được trình bày như sự cố đang xảy ra.
Production promotion chưa được phê duyệt
Candidate hiện tại đã qua Final Mega Gate và staging, nhưng chưa được chạy deploy production. Cần phê duyệt, kiểm tra rollback, maintenance window và post-deploy gate.
Kế hoạch
- Khóa commit/checksum candidate.
- Xác nhận rollback target và owner.
- Phê duyệt cửa sổ triển khai.
- Smoke, logs, outbox, reconciliation sau deploy.
archive_timeout production còn 1 phút
Repo đã cấu hình 15 phút, nhưng production chưa áp dụng vì cần tái tạo DB container có kiểm soát. WAL retention hiện là lớp bảo vệ tạm thời đã được cài.
Kế hoạch
- Chọn maintenance window.
- Backup/restore plan.
- Recreate container và xác minh archiver.
- Kiểm tra dung lượng sau 24–48 giờ.
God Files còn lớn
server.py và src/app.js vẫn lớn, làm tăng vùng ảnh hưởng và chi phí hiểu code, dù nhiều owner đã tách.
Kế hoạch
- Impact map theo route/domain.
- Tách theo boundary có test.
- Không tăng ngưỡng guard.
- Giữ compatibility cho caller cũ.
Headroom startup cần được bảo vệ
Performance guard yêu cầu tối thiểu 5 KB headroom cho main app. Các package UI mới phải lazy-load hoặc thu hồi bytes thay vì nới budget.
Kế hoạch
- Đo import graph.
- Tách child-page thực sự theo nhu cầu.
- Xóa duplicate helper/CSS.
- Kiểm tra aggregate gzip.
Missing-layer metadata cần cửa sổ bảo trì
Cleanup đã giải phóng dung lượng nhưng inventory Docker có lỗi metadata thiếu layer. Không được xóa thủ công dưới /var/lib/docker.
Kế hoạch
- Chụp inventory và backup cần thiết.
- Đánh giá image/container phụ thuộc.
- Thực hiện maintenance có rollback.
Ledger lịch sử dài và có trạng thái chồng lớp
PLAN-STATUS chứa baseline đã release, candidate hiện tại và follow-up package. Người đọc dễ nhầm “đã code” với “đã production”.
Kế hoạch
- Tạo summary hiện hành một trang.
- Archive các block release cũ.
- Dùng trạng thái chuẩn 5 mức.
| Vấn đề | Xác suất | Ảnh hưởng | Owner | Cách phát hiện | Rollback/Phục hồi |
|---|---|---|---|---|---|
| Sai phân bổ payment/debt | Thấp–TB | Rất cao | Kế toán + Backend | Reconciliation + SQL + journey test | Void/correction có audit; không sửa số dư trực tiếp |
| Concurrent stock conflict | Trung bình | Rất cao | Kho + Backend | PostgreSQL concurrency test | 409, giữ draft, retry với revision mới |
| Lộ dữ liệu ngoài branch | Thấp | Rất cao | Security | Denial matrix + API tests | Fail closed, revoke session, audit incident |
| Regression mobile/modal | Trung bình | Trung bình | UI/QA | 360px browser + overflow/focus checks | Revert scoped package |
| WAL/archive tăng lại | Trung bình | Cao | SRE/DBA | Disk alert + archiver metrics | Bounded retention; maintenance apply 15min timeout |
Kế hoạch nâng cấp
Lộ trình theo package và cổng kiểm soát
Mỗi giai đoạn tạo một kết quả có thể kiểm chứng và hoàn tác. Không dồn toàn bộ UI, backend, database và release vào một commit lớn.
Khóa baseline & bản đồ ownership
Chốt source, routes, API, DB invariant, bundle, test count, current production và candidate. Tạo route → query → store → page và mutation → table → event map.
Rà soát nghiệp vụ đa vai trò
Kế toán, kho, bán hàng, CSKH, HR, security và kỹ thuật cùng xác nhận actor, input/output, trạng thái, tiền, tồn, nợ, quyền và audit.
Tính toàn vẹn dữ liệu & PostgreSQL
Constraint, index, lock, revision, idempotency, migration idempotency, query plan, reconciliation, media backup/restore và forward repair.
Backend ownership & API contract
Route mỏng, service sở hữu transaction/invariant, repository sở hữu persistence; tách tiếp server.py theo boundary có test.
Frontend architecture & child pages
Giữ QueryClient/ResourceStore/HydrationCoordinator là authority; tách page theo nhu cầu, bảo vệ bundle và xóa duplicate owner.
Đại tu UI/UX theo vai trò
Kiểm tra task flow, hierarchy, density, form, table, modal, mobile 360px, keyboard, screen reader và trạng thái loading/error/offline.
Realtime, conflict & notification
Hai tài khoản, event trùng/sai thứ tự, reconnect/catch-up, dirty form, branch scope, notification idempotency và deep link.
Performance & storage hardening
API p95/p99, login, LCP/INP/CLS, bundle headroom, WAL/archive, Docker metadata và deploy timing.
Final Mega Gate & staging soak
Full frontend/backend/PostgreSQL/migration/concurrency/browser/security/release gates; chạy candidate bất biến trên staging và theo dõi.
Production promotion có kiểm soát
Chỉ triển khai khi có authorization, backup/rollback rõ, health/readiness/smoke/log/outbox/reconciliation pass và không còn blocker.
| Package | Phạm vi | Đầu ra | Micro Gate | Điều kiện đóng |
|---|---|---|---|---|
| PKG-01 | Accounting integrity | Data dictionary, formulas, void/return/credit rules | Focused Python + SQL contract | Kế toán phê duyệt, reconciliation khớp |
| PKG-02 | Inventory/serial | State machine và exact-ID contract | Concurrency + transfer browser | Không bán/chuyển trùng, partial receive đúng |
| PKG-03 | POS/payment/receipt | Journey chuẩn và failure recovery | POS Vitest + Chromium | Draft/focus/receipt/payment khớp |
| PKG-04 | Customer/warranty/repair | PII scope, timeline, fee/debt contract | API + browser + DB | Đúng khách/serial/trạng thái/tiền |
| PKG-05 | HR/commission | Policy matrix, locked-period correction | Commission tests + migration | Return/correction không sửa lịch sử mù |
| PKG-06 | Security/account | Permission/branch/MFA denial matrix | 97+ focused security tests | Fail closed, audit không lộ secret |
| PKG-07 | Architecture cleanup | Boundary extraction và duplicate removal | God File + import graph + build | Không tăng guard/budget |
| PKG-08 | Cross-page UI/UX | Screenshot inventory, issues, fixes | Desktop/tablet/mobile/accessibility | Không overflow, focus/draft ổn định |
| PKG-09 | Release readiness | Immutable candidate, rollback, runbook | Final Mega + staging soak | Có authorization và tất cả gate xanh |
Không thuộc phạm vi
Không rewrite framework, không microservices/Kubernetes, không đổi business policy khi chưa được phê duyệt, không tạo hệ thống song song.
Nguyên tắc rollback
Mỗi package có commit, manifest, scope và rollback riêng. Migration ưu tiên additive, rollback app và forward repair thay vì drop dữ liệu.
Cách ghi tiến độ
Luôn tách Code complete → Local integration → PostgreSQL → Staging → Production. Bằng chứng ghi command, result, artifact và rủi ro còn lại.
Quản trị triển khai
RACI và tiêu chí nghiệm thu
R = thực hiện, A = chịu trách nhiệm cuối, C = tham vấn, I = được thông báo.
| Hạng mục | Chủ DN | Kế toán | Bán hàng | Kho | CSKH/BH | HR | Kỹ thuật | QA/SRE |
|---|---|---|---|---|---|---|---|---|
| Chính sách bán/đổi trả | A | C | R | C | C | I | C | I |
| Doanh thu, nợ, quỹ, P&L | A | R | C | C | C | I | C | C |
| Serial, nhập/chuyển/nhận kho | I | C | C | A/R | C | I | C | C |
| Bảo hành/sửa chữa | I | C | I | C | A/R | I | C | C |
| Chỉ tiêu/hoa hồng | A | C | C | I | I | R | C | C |
| Permission & security | A | C | I | I | I | C | R | C |
| UI/UX workflow | A | C | C | C | C | C | R | R |
| Database/migration | I | C | I | I | I | I | A/R | C |
| Final release | A | I | I | I | I | I | R | R |
Definition of Done
Một package hoặc toàn chương trình chỉ đóng khi các điều kiện tương ứng có bằng chứng.
Nghiệp vụ & dữ liệu
- Actor, trạng thái và invariant được xác nhận
- Tiền, tồn, nợ và báo cáo đối soát được
- Audit và rollback/forward repair rõ
- Không có quyết định nghiệp vụ bị AI tự đặt
Frontend & UI/UX
- Desktop, tablet, mobile 360px hoạt động
- Không horizontal overflow
- Keyboard/focus/dialog semantics đúng
- Loading, error, offline, permission đầy đủ
- Draft, scroll, selection không bị mất
Backend & database
- Permission enforce ở server
- Transaction, lock, revision và idempotency đúng
- Migration idempotent, có validation query
- PostgreSQL integration/concurrency pass
- Query plan đạt ngưỡng
Realtime & bảo mật
- Event scoped, dedupe và catch-up đúng
- Conflict giữ draft và server revision
- MFA/session/password flow an toàn
- Không lộ PII/secret qua API, audit, notification
Hiệu năng & vận hành
- Bundle budget và headroom pass
- API/login/LCP/INP/CLS đạt ngân sách
- WAL/storage và Docker health ổn định
- Backup/restore evidence có thật
Release
- Immutable candidate có checksum
- Final Mega Gate xanh
- Staging soak và rollback plan pass
- Có phê duyệt triển khai
- Post-deploy smoke/log/outbox/reconciliation xanh
Quyết định còn cần các bên xác nhậnCông thức hoa hồng và khóa kỳ; chính sách trả/đổi; quyền Manager; cách xử lý credit/advance; quy trình duyệt chi; retention/backup/PITR; thời gian bảo hành và quyền xem giá vốn.