SYSTEM OF RECORD
App booking
Slot, booking, check-in, xác nhận, credit ledger, show, payroll evidence. Mỗi thay đổi có actor và thời điểm.
01 / Quyết định kiến trúc
Một lõi giao dịch, nhiều kênh sử dụng
Lark là nguồn CRM/HRM theo trường được chỉ định. Ứng dụng booking là nguồn cho lịch, số buổi, attendance và công. Hai chiều đồng bộ thông qua hợp đồng dữ liệu rõ ràng.
UPSTREAM / DOWNSTREAM
Lark Base
Lead, hợp đồng đã duyệt, thông tin nhân sự → app. App trả trạng thái kích hoạt, số dư tóm tắt và kết quả công/lương theo phạm vi.
CONTROL PLANE
Identity & policy
UI, API, export, MCP và CLI đều kiểm tra cùng một quyền theo role, chi nhánh, quan hệ KH-HLV và mức nhạy cảm.
MỤC TIÊU BOD
Một trải nghiệm cho 3 nhóm
KH tự đặt lịch và xem quyền sử dụng; HLV quản ca dạy và công; nội bộ điều hành theo quyền chi tiết. Cùng một lõi dữ liệu nhưng giao diện theo nhiệm vụ.
NGUYÊN TẮC NGHIỆP VỤ
Sổ buổi là chứng cứ tài chính
Một attendance hợp lệ sinh debit một lần; điều chỉnh bằng bút toán đảo. Show tính công dựa trên buổi thực dạy, không suy từ số thành viên gói.
02 / Layer map
Hệ thống theo 6 lớp
Mỗi lớp có một trách nhiệm rõ để DEV ước lượng, thiết kế và kiểm thử độc lập.
LAYER 01Trải nghiệmKH đặt/đổi/hủy · HLV lịch và checkout · Ops/HR/Finance điều hành · AI client truy vấn
↓
LAYER 02Identity & APIOTP/SSO/MFA · session · API gateway · policy theo role + scope + field · rate limit
↓
LAYER 03Nghiệp vụAvailability → Booking → Attendance → Session credit → Payable show → Payroll
↓
LAYER 04Dữ liệu lõiPostgreSQL transaction · ledger bất biến · rule version · audit · outbox · storage mã hóa
↕
LAYER 05Tích hợpWorker / queue / inbox / outbox / identity map / retry / reconcile ↔ Lark CRM & HRM; notifications
↕
LAYER 06Giám sát & quản trịSync dashboard · audit access · backup/restore · privacy requests · incident response · metrics
03 / Functional view
Chức năng theo người dùng
Chọn vai trò để xem phạm vi sản phẩm. Danh sách quyền chi tiết nằm ở phần “Quyền”.
ROLE 01
Khách hàng
Tự phục vụ, hiểu rõ quyền sử dụng gói và trạng thái lịch.
- Kích hoạt tài khoản bằng OTP/đường dẫn một lần; quản lý đồng ý và thông báo dữ liệu.
- Xem gói, hạn, số dư từ credit ledger và lịch sử từng bút toán.
- Đặt/đổi/hủy PT hoặc lớp nhóm theo giờ rảnh, capacity, chính sách hủy.
- Nhắc lịch, waitlist, xem buổi đã hoàn thành và gửi yêu cầu đối soát.
- Pha sau: mục tiêu, tiến độ và kế hoạch tập có kiểm soát dữ liệu sức khỏe.
ROLE 02
Huấn luyện viên
Lịch dạy, xác nhận thực dạy và đối soát show.
- Thiết lập availability, nghỉ phép, chi nhánh, xem lịch ngày/tuần và dạy thay.
- Check-in/checkout, thời lượng thực tế, attendance từng KH trong lớp nhóm.
- Ghi chú chuyên môn với KH được phân công; chỉ xem thông tin sức khỏe cần thiết.
- Xem show được/không được tính công, lý do, gửi khiếu nại trước khóa kỳ.
- Không truy cập tài chính KH, CCCD hoặc lương người khác.
ROLE 03
Nội bộ
Quyền phân theo Ops, quản lý chi nhánh, Sales, HR, Finance, System Admin.
- Ops: lịch, gói, bảo lưu, chuyển HLV, ngoại lệ có lý do trong chi nhánh.
- Quản lý: duyệt ngoại lệ và show chi nhánh; xem KPI theo phạm vi.
- Sales: lead/hợp đồng và tiến độ kích hoạt từ Lark; HR: ngày công và rule lương.
- Finance: đối soát thanh toán, duyệt/khóa/chi kỳ lương.
- System Admin: cấu hình kỹ thuật và quyền; không mặc nhiên đọc sức khỏe/lương.
04 / Transaction flows
5 luồng dữ liệu trọng yếu
Mỗi luồng cho thấy dữ liệu đi qua đâu, ai sở hữu, và điểm phải ghi chứng cứ.
01 · LARKHợp đồng READYChỉ hợp đồng đủ điều kiện thanh toán/chữ ký theo rule mới kích hoạt.
02 · INBOXNhận và chống trùngXác minh nguồn, event ID, version, chuẩn hóa mã KH/HLV/gói.
03 · APP DBTạo entitlementTransaction ghi Contract, gói đã mua, opening credit, audit, outbox.
04 · WORKERThông báoGửi mời kích hoạt, cập nhật PROVISIONED/ERROR về Lark.
05 · CONTROLĐối soátRecord lệch/lỗi vào dashboard để Ops xử lý và retry an toàn.
Chốt trong workshop: điều kiện tạo quyền tập cho trả một phần, payfull, gia hạn và hợp đồng sửa/hủy.
01 · DISCOVERYSlot khả dụngHLV, phòng, chi nhánh, lớp, capacity, thời gian và chính sách.
02 · POLICYKiểm tra quyền tậpGói còn hạn/credit, thanh toán, cửa sổ book, không trùng lịch.
03 · TRANSACTIONGiữ chỗKhóa slot/capacity, idempotency key; tránh đặt đồng thời vượt chỗ.
04 · EVENTXác nhận/nhắcThông báo KH và HLV, hiện lịch mới nhất.
05 · EXCEPTIONĐổi/hủy/waitlistPolicy version, cutoff, lý do và hoàn chỗ/credit theo rule.
Một booking chưa phải buổi được tính công. Cần phân biệt booked, checked-in, completed, late cancel và no-show.
01 · ATTENDANCEAi thực dạy?HLV thực tế, KH có mặt, giờ bắt đầu/kết thúc, dạy thay.
02 · VALIDATEĐiều kiện hoàn thànhĐúng trạng thái, thời lượng và quyền xác nhận.
03 · LEDGERTrừ credit 1 lầnDebit tham chiếu attendance; retry không tạo bút toán mới.
04 · SHOWSinh công dự kiếnRule theo loại buổi, phút, số KH có mặt nếu lớp nhóm.
05 · REVIEWĐối soátKH/HLV khiếu nại; đảo bút toán và adjustment có phê duyệt.
Ví dụ nhóm: 5 người đặt, 4 check-in, 1 no-show → 1 show HLV và 4 attendance hợp lệ; credit no-show theo chính sách đã công bố.
01 · SNAPSHOTChốt đầu vàoPayable shows, ngày công, doanh số, phụ cấp/khấu trừ.
02 · VERSIONÁp rule hiệu lựcSnapshot pay rule và cách tính VND, không dùng rule hiện tại hồi tố.
03 · REVIEWHLV & HR soátChi tiết mỗi show, ngoại lệ, bằng chứng.
04 · APPROVEQuản lý/Finance duyệtMaker-checker và hạn mức phân quyền.
05 · LOCK / PAIDKhóa kỳKỳ sau chỉ có adjustment; tổng đã khóa tái xuất y hệt.
Yêu cầu nghiệm thu: kỳ lương đã khóa phải tái xuất nguyên kết quả, dù quy tắc lương sau đó thay đổi. Điều chỉnh được ghi vào kỳ bổ sung có nguồn gốc rõ.
01 · OWNERChủ sở hữu trườngCRM/HRM hay app; một trường có một đường ghi chính.
02 · MAPIdentity mapUUID nội bộ ↔ Lark record ID ↔ legacy ID; không dùng SĐT làm khóa.
03 · QUEUEInbox/outboxIdempotent, version, retry/backoff, dead-letter.
04 · WRITEBACKĐẩy tóm tắtProvisioning, số dư, ngày hết hạn, payroll summary đúng nơi.
05 · RECONCILEHòa giảiPhát hiện lệch, xung đột và vòng lặp; có người chịu trách nhiệm.
“Hai chiều” là nhiều luồng một chiều theo miền dữ liệu. Không dùng last-write-wins cho số buổi, tiền, hợp đồng hay lương.
05 / Data & source of truth
Mô hình dữ liệu từ lõi tới tích hợp
Các thực thể tối thiểu để hệ thống trả lời được: ai đặt, ai tập, ai dạy, trừ bao nhiêu buổi, được trả bao nhiêu và vì sao.
ContractLark CRM được duyệt
→
EntitlementGói & credit ban đầu
→
BookingSlot/lớp được giữ
→
AttendanceThực tế tập/dạy
→
Credit ledgerDebit/reversal
→
Payable showEvidence + rule
→
Payroll runSnapshot + duyệt
| Nhóm dữ liệu | Thực thể cần có | Nguyên tắc |
|---|---|---|
| Danh tính | Account, RoleAssignment, Customer, Coach, Branch, ConsentRecord | ID nội bộ bất biến; role có scope và thời hạn |
| Gói & lịch | PackageTemplate, PackageEntitlement, CoachAvailability, RoomResource, ClassOccurrence, Booking, WaitlistEntry | Điều khoản gói và policy được snapshot; slot có capacity |
| Chứng cứ | Attendance, SessionCreditLedger, PayableShow, AdjustmentRequest | Không sửa/xóa âm thầm; debit/reversal có tham chiếu |
| Lương | PayRuleVersion, PayrollRun, PayrollLine, PayrollApproval | Tiền VND số nguyên/DECIMAL; kỳ khóa bất biến |
| Tích hợp & quản trị | ExternalIdentityMap, InboxEvent, OutboxEvent, SyncConflict, AuditEvent, PrivacyRequest | Idempotency, retry, reconcile, truy vết và privacy |
Nguồn chủ theo miền
| Miền dữ liệu | Nguồn ghi chính | Đầu ra phía còn lại |
|---|---|---|
| Lead/hợp đồng/thanh toán xác nhận | Lark CRM/Base | App nhận điều kiện tạo gói |
| Nhân sự/HLV | Lark HRM | App mirror trường cần đặt lịch |
| Lịch, attendance, credit, công | App booking | Lark nhận summary theo quyền |
| Danh mục gói/giá | Cần chốt một nguồn | Đồng bộ một chiều sau khi duyệt |
| Hồ sơ KH | Chủ sở hữu theo từng trường | Xung đột đưa vào review, không ghi đè mù |
06 / Access control
Quyền phải bám theo dữ liệu, không chỉ menu
Một quyền gồm hành động + tài nguyên + phạm vi + trường dữ liệu + điều kiện. Cùng policy áp cho màn hình, API, export và AI.
ACTION
Được làm gì?
read / create / update / approve / export / administer
SCOPE
Với ai?
Bản thân, KH được giao, chi nhánh, toàn hệ thống có ủy quyền.
FIELD
Thấy trường nào?
Thông tin liên hệ, sức khỏe, CCCD, thanh toán, lương tách riêng.
CONDITION
Khi nào?
Đúng kỳ, hạn mức, quan hệ còn hiệu lực, có lý do và người duyệt.
| Vai trò | KH/lịch | Sức khỏe | Hợp đồng | Công/lương | Export/AI |
|---|---|---|---|---|---|
| KH | Của mình | Của mình | Của mình | — | Truy vấn của mình |
| HLV | KH được giao và lịch dạy | Tối thiểu cần cho tập | Điều kiện tập tối thiểu | Show/lương của mình | Scope được giao |
| Ops chi nhánh | Chi nhánh, sửa ngoại lệ | Hạn chế | Trạng thái cần vận hành | Show chi nhánh | Có lý do, giới hạn |
| HR / Finance | Theo nhu cầu nghiệp vụ | — | Finance xem tài chính | HR rule; Finance duyệt/chi | Riêng miền và audit |
| System Admin | Quản cấu hình | — mặc định | — mặc định | — mặc định | Break-glass có hạn |
Ma trận là đề xuất khởi đầu; brief Markdown có bảng đầy đủ hơn và các điều kiện maker-checker, export bulk, break-glass.
07 / AI, security & privacy
AI làm việc qua cổng quyền của ứng dụng
Người dùng / MCP / CLIIdentity + use case
→
Tool gatewaySchema + policy + rate limit
→
App APITruy vấn tối thiểu / đề xuất thay đổi
→
Audit & approvalGhi dấu vết, duyệt thao tác ghi
READ TOOLS
Truy vấn theo quyền
Tìm KH, lịch, số dư, show của mình; mask trường nhạy cảm và giới hạn số dòng.
WRITE TOOLS
Đề xuất rồi xác nhận
Đổi lịch/điều chỉnh credit/payroll tạo bản nháp, hiển thị trước/sau và người duyệt.
PROMPT SAFETY
Kiểm soát dữ liệu
Ghi chú từ KH/Lark là dữ liệu, không phải lệnh. Redact log/prompt, kiểm tra nơi xử lý và retention.
Checklist bảo vệ dữ liệu
Thiết kế sản phẩm
Data inventory, mục đích và căn cứ xử lý; đồng ý riêng cho marketing/AI; quyền truy cập/chỉnh sửa/rút lại/xóa theo nghĩa vụ áp dụng; retention và xử lý yêu cầu.
Kỹ thuật & nhà cung cấp
MFA, mã hóa, secret manager, audit đọc dữ liệu nhạy cảm, backup/restore, ứng phó sự cố; đánh giá Lark/cloud/AI/CDN về xử lý và chuyển dữ liệu xuyên biên giới.
Pháp chế cần xác định hồ sơ đánh giá tác động xử lý dữ liệu, chuyển xuyên biên giới và nghĩa vụ an ninh mạng theo mô hình triển khai thực tế. Không thể kết luận tuân thủ chỉ từ sơ đồ kiến trúc.
08 / Fitness product benchmarks
Học gì từ các app đang dùng rộng rãi?
Chọn tính năng phù hợp với bài toán ALL IN; thứ tự dưới đây là ưu tiên đề xuất, không phải danh sách phải sao chép.
P1 · GLOFOX
Slot, waitlist, no-show
Glofox hỗ trợ lịch PT/lớp, giới hạn chỗ, waitlist, nhắc lịch và chính sách hủy muộn. ALL IN nên thiết kế ngay vào lõi booking.
P1 · MINDBODY
Lịch nhân sự & payroll
Mindbody gắn lịch nhân sự, thay ca, hiệu suất và payroll. ALL IN cần ghi dạy thay và evidence công ngay ở từng buổi.
P2 · TRAINERIZE
Tiến độ & gắn bó KH
Trainerize nhấn mạnh chương trình tập, mục tiêu và thói quen. ALL IN có thể thêm ở pha sau với quyền xem dữ liệu sức khỏe được kiểm soát.
09 / Delivery plan
Lộ trình và cổng nghiệm thu
PHASE 0
DiscoveryData audit, rule workshop, nguồn chủ theo trường, threat/privacy review.
PHASE 1
Lõi an toànAuth, policy, PostgreSQL, import dry-run, audit, backup/restore.
PHASE 2
BookingPT/lớp nhóm, capacity, attendance, credit ledger, KH/HLV portal.
PHASE 3
Lark & lươngSync hai chiều theo trường, reconcile, pay rule version, chạy song song.
PHASE 4
AI & tăng trưởngMCP/CLI read-only, báo cáo retention, đề xuất có duyệt.
Gate bảo mật
Không password rõ; mọi API, export, MCP/CLI đều test cross-role và cross-branch.
Gate nghiệp vụ
Concurrent booking không vượt chỗ; retry checkout không trừ hai lần; số dư đối soát từ ledger.
Gate tài chính
Hai kỳ lương chạy song song; kỳ khóa tái xuất nguyên số dù rule mới thay đổi.
Những quyết định cần chốt trước báo giá
| Quyết định | Cần trả lời |
|---|---|
| Điều kiện tập | Hợp đồng ký/đã trả một phần/payfull; giới hạn buổi cho mỗi loại gói? |
| Trừ buổi | Check-in hay completed? No-show, hủy muộn, ngoại lệ được tính ra sao? |
| Công HLV | Một show là gì? Nhóm tính theo booked hay check-in? Dạy thay/ca qua ngày? |
| Lương cứng/ngày công | Nguồn chấm công nào? Ai phê duyệt rule và adjustment? |
| Field ownership | Ai được sửa gói/giá, hồ sơ KH, payment status ở Lark hay app? |
| AI và dữ liệu | Use case đầu tiên; có health data không; model/cloud ở đâu? |
| Migration | Ngày cutover, số dư mở đầu, lịch sử cần giữ và nguồn đối soát? |
10 / Evidence
Nguồn tham chiếu
Rà soát ngày 12/10/2026. Nguồn nội bộ là phác thảo BA và SOP; tham chiếu ngoài là trang chính thức của nhà cung cấp/cơ quan ban hành.
Đầu vào nghiệp vụ
ADMIN_REPLACEMENT_ARCHITECTURE.mdKB_AppBooking_Cap_Tai_Khoan.md- Định hướng BOD: 3 nhóm người dùng, Lark hai chiều, lịch/công/lương, AI theo quyền, bảo vệ dữ liệu.
Các file Excel/CSV mẫu chưa được kiểm toán từng dòng.