# ALL IN Fitness — brief sản phẩm và kiến trúc Web Booking

**Phiên bản:** 2.0 · **Ngày cập nhật:** 12/10/2026 · **Đối tượng:** BOD, chủ sản phẩm, vận hành, DEV, bảo mật/pháp chế  
**Trạng thái:** brief BA về sản phẩm mong muốn để DEV thiết kế app-web mới; chưa phải đặc tả đã phê duyệt.  
**Tài liệu trực quan đi kèm:** `ALLIN_BOOKING_SYSTEM_MAP_V2_2026.html` (mở trực tiếp bằng trình duyệt, không cần máy chủ).

## 1. Kết luận điều hành

Nên phát triển **một nền tảng vận hành booking thống nhất** cho khách hàng (KH), huấn luyện viên (HLV) và nhân sự nội bộ. Lark Base tiếp tục quản lý lead/hợp đồng và HRM theo quyền; ứng dụng booking sở hữu lịch, buổi tập, số buổi còn lại và chứng cứ tính công. “Đồng bộ hai chiều” phải hiểu theo **từng miền dữ liệu/trường dữ liệu và chiều ghi**, không cho cả hai bên tự sửa cùng một giá trị.

Năm yêu cầu nền tảng của sản phẩm đích:

1. **Trải nghiệm và quyền cho 3 nhóm:** KH, HLV và nội bộ có luồng riêng; quyền nội bộ chi tiết theo nhiệm vụ, chi nhánh, quan hệ và trường dữ liệu.
2. **Sổ buổi tập có thể đối soát:** hoàn thành buổi tạo bút toán trừ buổi một lần, có đảo bút toán và lịch sử.
3. **Tách booking, attendance và payroll:** một booking có thể bị hủy/no-show; chỉ một attendance hợp lệ mới được xét trả công; khóa kỳ lương thì không tính lại bằng quy tắc đã đổi.
4. **Định nghĩa quyền theo phạm vi:** quyền `customer.read` chưa đủ; cần giới hạn “KH của tôi”, “KH thuộc chi nhánh”, “trường sức khỏe”, “lương”, “xuất hàng loạt” tại API và truy vấn DB.
5. **Đồng bộ Lark có chủ sở hữu trường và cơ chế hòa giải:** ID map, idempotency, outbox/inbox, retry, cảnh báo lệch và màn hình xử lý xung đột.

### Phạm vi brief và giả định

Brief dựa trên `ADMIN_REPLACEMENT_ARCHITECTURE.md`, `KB_AppBooking_Cap_Tai_Khoan.md` và mục tiêu BOD nêu trong yêu cầu. Đây là **bài toán xây mới**, không đánh giá chất lượng mã phác thảo hay dùng phác thảo làm baseline triển khai. Các file Excel/CSV trong `web-data` **chưa được kiểm toán từng hàng và từng trường**; mapping chỉ là yêu cầu discovery. Chưa kiểm chứng trực tiếp quy tắc kinh doanh trong hệ thống booking cũ hoặc Lark tenant.

## 2. Chuyển ý tưởng BOD thành phạm vi DEV cần thiết kế

| Chủ đề | Mục tiêu BOD / phác thảo BA | Cần làm rõ trong discovery | Yêu cầu sản phẩm đích |
|---|---|---|---|
| Kiến trúc | App-web mới kết nối Lark CRM/HRM | Quy mô chi nhánh, số KH/HLV, SLA, cloud và tích hợp cần thiết | API nghiệp vụ, DB giao dịch, worker đồng bộ, audit, backup |
| Vai trò | KH, HLV, nội bộ nhiều quyền | Ai xem/sửa/duyệt dữ liệu nào, phạm vi chi nhánh và quan hệ KH-HLV | RBAC + policy theo đối tượng/trường; kiểm tra tại API |
| Tài khoản | Cấp tài khoản nhanh sau khi mua gói | Kênh đăng nhập KH, HLV, nhân viên; có SSO/MFA ở đâu | OTP/magic link cho KH, MFA/SSO cho nội bộ; lifecycle tài khoản |
| KH | Hồ sơ, gói, mục tiêu, tình trạng tập | Trường nào cần thu, ai nhập, ai xem, giữ bao lâu | Hồ sơ có phân loại nhạy cảm, consent, retention và quyền chủ thể |
| Booking | PT cá nhân và lớp nhóm | Giờ mở, phòng, capacity, waitlist, hủy/đổi, ngày nghỉ HLV | Availability → Booking → Attendance → SessionCredit |
| Số buổi | Hiển thị còn/đã tập chính xác | Trừ buổi tại checkout hay xác nhận đôi; no-show/hủy muộn | Ledger bất biến, idempotency, hoàn tác có lý do và người duyệt |
| Nhóm | Lớp nhóm có nhiều KH và khung công | Công theo người đã book hay có mặt; giới hạn lớp | ClassOccurrence + Attendance từng KH + show HLV theo buổi |
| Thời lượng | Quản lý thời lượng tập/dạy | Phút chuẩn, phút tối thiểu, ca qua ngày, làm tròn | Giờ đặt và giờ thực tế; rule thời lượng có phiên bản |
| Payroll | Tính công, lương cứng, hoa hồng | Nguồn ngày công, doanh số đủ điều kiện, duyệt và khiếu nại | Snapshot rule/đầu vào; kỳ DRAFT→REVIEW→APPROVED→LOCKED→PAID |
| Lark sync | Đồng bộ hai chiều | Chủ sở hữu từng trường, độ trễ, xung đột, dữ liệu lịch sử | Contract tích hợp, identity map, outbox/inbox, reconciliation |
| AI | Truy vấn/xử lý theo quyền qua MCP/CLI | Use case đầu tiên, mức tự động ghi, model và nơi xử lý | Tool gateway dùng cùng policy, audit và duyệt thao tác nhạy cảm |
| Bảo mật/pháp lý | Bảo vệ dữ liệu theo luật Việt Nam | Loại dữ liệu nhạy cảm, nhà cung cấp, chuyển xuyên biên giới | Privacy by design, hồ sơ pháp lý và kiểm soát kỹ thuật |

## 3. Đối tượng và trải nghiệm cần có

### 3.1 Khách hàng

- Kích hoạt tài khoản bằng OTP/đường dẫn một lần; xem điều khoản, thông báo xử lý dữ liệu và lựa chọn đồng ý riêng cho mục đích tùy chọn.
- Xem gói đang dùng, ngày hết hạn, **số buổi theo sổ giao dịch**, lịch đã đặt và chính sách hủy/no-show áp dụng tại thời điểm đặt.
- Đặt/đổi/hủy PT hoặc lớp nhóm theo khung giờ mở, sức chứa, hạn gói, quyền sử dụng, HLV/chi nhánh phù hợp; nhận xác nhận/nhắc lịch.
- Xem lịch sử buổi tập và yêu cầu đối soát nếu sai số buổi; xem mục tiêu/tiến độ chỉ khi được bật.
- Yêu cầu cập nhật/xóa/hạn chế xử lý dữ liệu qua kênh hỗ trợ, có trạng thái xử lý.

### 3.2 HLV

- Công bố giờ rảnh, ngày nghỉ, chi nhánh phục vụ; xem lịch ngày/tuần, thay đổi và danh sách chờ.
- Xác nhận check-in/checkout theo buổi; ghi thời lượng thực tế, ghi chú chuyên môn đúng phạm vi; xử lý vắng mặt, dạy thay.
- Xem **show được tính công** và khoản dự kiến của bản thân cùng lý do loại trừ/điều chỉnh; gửi yêu cầu đối soát trước khóa kỳ.
- Chỉ xem hồ sơ KH được phân công và thông tin sức khỏe tối thiểu cần cho việc tập an toàn; không xem CCCD, thông tin thanh toán, lương người khác.

### 3.3 Nội bộ

- **Ops chi nhánh:** quản lịch, gói, bảo lưu, chuyển HLV, xử lý ngoại lệ có lý do; xem đúng chi nhánh.
- **Sales:** xem lead/hợp đồng và tiến độ kích hoạt; không sửa số buổi hoặc payroll.
- **Quản lý chi nhánh:** duyệt ngoại lệ lịch, xem KPI chi nhánh, duyệt công theo hạn mức.
- **HR:** hồ sơ nhân sự, chính sách lương, ngày công; không tự duyệt khoản mình nhập.
- **Finance:** đối soát thanh toán, kỳ lương, xuất báo cáo; không sửa chứng cứ attendance.
- **System Admin:** quản cấu hình kỹ thuật/role, không mặc nhiên có quyền xem dữ liệu sức khỏe và lương; quyền khẩn cấp có thời hạn và audit.

## 4. Kiến trúc theo layer

```text
KH web/mobile   HLV web/mobile   Ops/Sales/Manager/HR/Finance portal   AI client (MCP/CLI)
       \              |                         |                         /
        └─────────────┴────────── API gateway + AuthN/AuthZ ──────────┘
                                |
            Booking/Availability | Package/Session Ledger | Attendance | Payroll
                                |
                   PostgreSQL (transaction + audit + outbox)
                         |                         |
                  Integration worker          Notification worker
                         |                         |
           Lark Base CRM/HRM + API          ZNS/SMS/email/push
```

| Layer | Trách nhiệm | Ràng buộc thiết kế |
|---|---|---|
| Kênh giao diện | KH, HLV, nội bộ; responsive, VN timezone | Không tin quyền/giá/số buổi do client gửi |
| Identity & policy | OTP/SSO/MFA, session, role, chi nhánh, quan hệ KH-HLV, field mask | Mọi read/write/export/tool đều qua cùng policy service |
| Nghiệp vụ | Lịch, slot, gói, credit, attendance, payroll, exception | Transaction DB; rule có phiên bản và thời điểm hiệu lực |
| Data | PostgreSQL, audit append-only, object storage mã hóa | ID nội bộ bất biến; immutable evidence; backup và restore drill |
| Tích hợp | Lark API/event/poll, mapping, retry, reconcile | Không ghi trực tiếp Lark trong DB transaction; dùng outbox |
| AI gateway | MCP/CLI tools có schema, scope, policy, audit | Không cấp DB credential/Lark tenant token trực tiếp cho AI |
| Observability | metrics, tracing, cảnh báo sync/payroll/booking | Không đưa PII/secret vào logs và prompt trace |

**Chọn công nghệ:** có thể tiếp tục Next.js/TypeScript cho UI và API nếu đội DEV thành thạo, nhưng ranh giới nghiệp vụ phải tách rõ bằng module/service. PostgreSQL production; queue/worker phù hợp quy mô; object storage cho tệp. Quyết định nhà cung cấp cloud phụ thuộc đánh giá vị trí dữ liệu, hợp đồng xử lý dữ liệu, phục hồi và pháp lý.

## 5. Mô hình dữ liệu đề xuất

### 5.1 Thực thể lõi

| Miền | Thực thể và khóa quan trọng | Chức năng |
|---|---|---|
| Identity | `Account`, `Role`, `Permission`, `RoleAssignment(scope, validFrom, validTo)`, `ConsentRecord` | Đăng nhập, quyền theo phạm vi, bằng chứng đồng ý |
| People | `Customer`, `Coach`, `Branch`, `CoachAssignment`, `SensitiveHealthNote` | Hồ sơ và quan hệ phân công; health note tách riêng |
| Commerce | `Contract`, `Payment`, `PackageTemplate`, `PackageEntitlement` | Điều kiện sử dụng gói; snapshot điều khoản khi mua |
| Capacity | `CoachAvailability`, `TimeOff`, `RoomResource`, `ClassTemplate`, `ClassOccurrence` | Giờ rảnh, phòng, lớp lặp lại và suất thực tế |
| Booking | `Booking`, `WaitlistEntry`, `BookingPolicyVersion` | Slot, trạng thái, cutoff, no-show và lý do ngoại lệ |
| Evidence | `Attendance`, `SessionCreditLedger`, `AdjustmentRequest` | Check-in, xác nhận, trừ/hoàn buổi có thể đối soát |
| Payroll | `PayRuleVersion`, `PayableShow`, `PayrollRun`, `PayrollLine`, `PayrollApproval` | Tính công/lương từ evidence và snapshot rule |
| Integration | `ExternalIdentityMap`, `InboxEvent`, `OutboxEvent`, `SyncConflict`, `ReconciliationRun` | Đồng bộ chống trùng, chống vòng lặp, quan sát lỗi |
| Governance | `AuditEvent`, `DataAccessEvent`, `PrivacyRequest`, `RetentionPolicy` | Truy vết, quyền chủ thể dữ liệu, xóa/ẩn theo hạn |

### 5.2 Những quyết định mô hình bắt buộc

- **KH và HLV:** UUID nội bộ là khóa chính; `customerCode`, `trainerCode`, `legacyId`, Lark `record_id` nằm trong bảng mapping có unique theo nguồn. SĐT là thuộc tính có thể đổi, không là khóa định danh duy nhất.
- **Gói:** `PackageTemplate` là danh mục; `PackageEntitlement` là quyền sử dụng được cấp từ một hợp đồng. Snapshot số buổi, giá, hạn, chính sách tại thời điểm mua.
- **Credit ledger:** mỗi hoàn thành hợp lệ ghi `-1` (hoặc số credit theo quy tắc); hoàn tác ghi `+1` tham chiếu bút toán gốc. `remaining = opening + tổng ledger`; cache tổng phải tái tính được.
- **Thời lượng:** lưu UTC timestamp và timezone `Asia/Ho_Chi_Minh`, thời lượng đặt và thực tế; chính sách tính show có thể khác số credit trừ của KH.
- **Nhóm:** một `ClassOccurrence` có nhiều `Booking/Attendance`, mỗi KH có entitlement riêng. Một show HLV có thể gắn nhiều attendance, không nhân show theo số KH nếu quy tắc lương không yêu cầu.
- **Payroll:** tiền dùng số nguyên VND hoặc DECIMAL; không dùng float cho số tiền. `PayRuleVersion` và tập đầu vào được snapshot/hàm băm khi duyệt. Kỳ `LOCKED/PAID` chỉ điều chỉnh bằng kỳ bổ sung, không sửa lịch sử.
- **Audit:** lưu actor, role/scope, action, object, before/after đã mask, reason, requestId, timestamp; audit log phải được bảo vệ khỏi sửa/xóa tùy tiện.

## 6. Data flow và giao kèo đồng bộ Lark

### 6.1 Nguồn chủ theo miền

| Dữ liệu | Nguồn ghi chính | Chiều đồng bộ | Ghi chú |
|---|---|---|---|
| Lead, cơ hội, hợp đồng đã duyệt, thanh toán xác nhận | Lark CRM/Base | Lark → app | App chỉ nhận trạng thái đủ điều kiện kích hoạt; sửa nguồn tại Lark |
| Hồ sơ KH cơ bản | Lark cho dữ liệu CRM; app cho thông tin tự cập nhật của KH | Theo **field ownership** | Nếu cùng trường cần quy trình đề xuất sửa và duyệt; không last-write-wins mù |
| HLV/nhân sự/chức danh | Lark HRM | Lark → app | Chỉ mirror trường cần vận hành; dữ liệu ngân hàng/lương cách ly |
| Danh mục gói | Chọn một chủ sở hữu trong workshop | Một chiều ra bên còn lại | Không chốt cả Lark và app cùng được sửa giá/gói |
| Entitlement, lịch, attendance, credit ledger | App booking | App → Lark summary | Lark chỉ nhận chỉ số tổng hợp, không sửa sổ buổi |
| Công, payroll | App + HR/Finance duyệt | App → HRM/Finance summary | Không sync dữ liệu lương chi tiết rộng sang CRM |
| Consent/privacy requests | App hoặc DPO workflow được chọn | Đồng bộ trạng thái tối thiểu | Không phát tán dữ liệu sức khỏe sang Base nếu không cần |

### 6.2 Chu trình sự kiện

```text
Lark contract READY → verify event/signature or pull API → inbox dedupe
→ normalize + resolve external ID → validate payment/gói/HLV/chi nhánh
→ DB transaction: Contract + Entitlement + Audit + Outbox
→ worker cập nhật Lark PROVISIONED/ERROR + gửi thông báo
→ reconcile định kỳ số lượng, version, checksum, bản ghi lệch
```

**Yêu cầu kỹ thuật:** dùng `eventId`/`recordId + version` làm khóa idempotency; mỗi sự kiện có trạng thái `received/processing/succeeded/retry/dead-letter`; exponential backoff cho lỗi tạm thời, không lặp vô hạn; version hoặc `lastModified` để phát hiện stale update; ghi `source`, `owner`, `originEventId` để tránh vòng lặp; dashboard có tuổi bản ghi lỗi, nút retry an toàn, lịch sử và người xử lý. Đồng bộ theo batch/rate limit của Lark; API Base hỗ trợ bản ghi và giới hạn batch, cần kiểm tra quota đúng endpoint/tenant ở triển khai. [Tài liệu Lark Base API](https://open.larksuite.com/document/server-docs/docs/bitable-v1/notification).

**SLA đề xuất để DEV ước lượng:** hợp đồng hợp lệ xuất hiện trong app ≤5 phút ở điều kiện bình thường; cảnh báo nếu >15 phút; hòa giải tự động ít nhất hằng ngày. Đây là mục tiêu sản phẩm, chưa phải năng lực đã xác nhận của Lark tenant.

## 7. Quy tắc booking, attendance, tính công và lương

### 7.1 State machine

```text
Booking: REQUESTED → CONFIRMED → CHECKED_IN → COMPLETED
                  ↘ CANCELLED_EARLY / CANCELLED_LATE / NO_SHOW / EXCEPTION
Waitlist: WAITING → OFFERED → CONFIRMED hoặc EXPIRED
Credit: RESERVED (tùy chính sách) → DEBITED khi COMPLETED; REVERSAL khi điều chỉnh
Payroll: DRAFT → REVIEW → APPROVED → LOCKED → PAID; DISPUTED → ADJUSTMENT
```

Không cho nhảy trạng thái tùy ý. Mỗi chuyển trạng thái có actor, thời điểm, rule version và lý do khi ngoại lệ. Policy hủy 6 giờ trong SOP hiện tại là **giả định cần xác nhận** cho từng dịch vụ; rule phải cấu hình theo gói/chi nhánh và có hiệu lực từ ngày xác định. Mốc checkout trước 23:59 cũng cần làm rõ khi ca kết thúc qua nửa đêm hoặc hệ thống mất mạng.

### 7.2 Invariant và edge case cần test

- Một slot PT không thể bị double-book cho cùng HLV, KH hoặc phòng; booking đồng thời phải có transaction/constraint.
- Một KH không được dùng entitlement hết hạn/hết buổi/chưa đủ điều kiện thanh toán; ngoại lệ Ops phải có quyền và log.
- `COMPLETED` một lần chỉ ghi debit một lần; gọi lại API hoặc nhận lại webhook không trừ thêm.
- Hủy sớm hoàn credit giữ chỗ; hủy muộn/no-show áp dụng policy đã công bố và có đường khiếu nại.
- Chuyển HLV sau khi đã hoàn thành buổi không làm đổi người hưởng công của buổi cũ; dạy thay có người duyệt và snapshot.
- Lớp nhóm: capacity, waitlist, điểm danh từng KH, no-show từng KH, số người có mặt là đầu vào khung giá HLV nếu chính sách như vậy.
- Bảo lưu/đóng băng/đổi gói/hoàn tiền/chuyển nhượng cần bút toán và lịch sử, không sửa trực tiếp số dư.
- Ngày lễ, múi giờ, ca qua ngày, DST của khách đi du lịch, mạng chập chờn đều phải có quy tắc hiển thị và đối soát.

### 7.3 Công và payroll

`PayableShow` sinh từ **attendance đã xác nhận** + vai trò HLV thực dạy + loại dịch vụ + thời lượng đủ điều kiện + số KH tham dự (nếu lớp nhóm) + `PayRuleVersion`; loại trừ buổi bị đảo/đang tranh chấp. `PayrollRun` chụp snapshot toàn bộ show, ngày công, doanh số đủ điều kiện, phụ cấp/khấu trừ có chứng từ. HR/Ops soát, người khác duyệt, Finance khóa và ghi nhận thanh toán. Mọi thay đổi sau khóa chuyển thành adjustment ở kỳ sau.

Ví dụ cần chốt với chủ sản phẩm: một lớp 60 phút có 5 người đặt, 4 check-in, 1 no-show. Có **1 show HLV**, 4 attendance hợp lệ; số credit trừ của người no-show theo policy; mức công nhóm tính theo 4 hay 5 phải được ghi trong rule đã phê duyệt. Không được lấy số thành viên cả gói để tính mức công.

## 8. Ma trận quyền mẫu để DEV triển khai

`R` xem, `W` tạo/sửa, `A` duyệt, `E` xuất; dấu `—` không có quyền. Scope phải kiểm tra ở backend cho từng bản ghi và từng trường.

| Tài nguyên/hành động | KH | HLV | Ops chi nhánh | Quản lý CN | Sales | HR | Finance | System Admin |
|---|---|---|---|---|---|---|---|---|
| Lịch và credit bản thân/KH phụ trách | R/W của mình | R/W lịch phân công, checkout | R/W chi nhánh | R/A chi nhánh | R trạng thái | — | R tổng hợp | — |
| Hồ sơ KH cơ bản | R/W phần cho phép | R KH được giao | R/W chi nhánh | R chi nhánh | R lead/contract | — | R phần tài chính | cấu hình quyền |
| Ghi chú sức khỏe | R/W của mình | R/W KH được giao, mục đích tập | R hạn chế | R hạn chế khi cần | — | — | — | — |
| Hợp đồng/thanh toán | R của mình | R điều kiện tập tối thiểu | R chi nhánh | R/A ngoại lệ | R/W tại Lark | — | R/A tài chính | — |
| Công/lương | — | R của mình, khiếu nại | R show chi nhánh, không lương chi tiết | A công chi nhánh | — | R/W rule và payroll draft | R/A/PAID | — |
| Role/config | — | — | — | — | — | — | — | W có phê duyệt |
| Export bulk/AI write | — | — | theo nhu cầu, có lý do | theo chi nhánh | scope CRM | scope HR | scope tài chính | cấp quyền, audit |

**Policy bổ sung:** deny-by-default; cấp quyền theo thời hạn; không tự duyệt việc mình tạo; break-glass có lý do/hạn và cảnh báo; export có giới hạn dòng, watermark, lý do và log; phân quyền AI theo người dùng cuối hoặc service identity hẹp, không mượn quyền SuperAdmin.

## 9. AI qua MCP/CLI

### 9.1 Kiến trúc

MCP server/CLI gọi **tool gateway của ứng dụng**; gateway xác thực user/service, áp policy, lấy dữ liệu tối thiểu, trả kết quả đã mask và ghi audit. AI không truy cập DB, Lark Base hoặc storage bằng token toàn quyền. Nên có catalog tool nhỏ, rõ schema và mục đích:

| Tool mẫu | Quyền | Đầu ra/giới hạn |
|---|---|---|
| `search_customers` | `customer.read` + scope | Chỉ KH được phép; SĐT mask nếu không có quyền |
| `get_customer_schedule` | `booking.read` | Lịch của mình/KH phụ trách; không kèm health note mặc định |
| `get_package_balance` | `credit.read` | Số dư và các bút toán có thể giải thích |
| `summarize_coach_shows` | `show.read` | Số show và lý do loại trừ, không lộ lương người khác |
| `draft_booking_change` | `booking.propose` | Chỉ tạo đề xuất, người dùng xác nhận trên UI |
| `submit_privacy_request` | `privacy.request` | Tiếp nhận yêu cầu, không tự xóa dữ liệu ngay |

**MCP và CLI phải gọi chung API/policy**; prompts, tool outputs và logs cần redaction. Với thao tác ghi hoặc xuất lớn: hiển thị đối tượng, trước/sau, người phê duyệt và idempotency key. Chống prompt injection từ ghi chú KH/Lark: coi đó là dữ liệu, không là lệnh. Đánh giá nhà cung cấp mô hình, nơi xử lý, retention, huấn luyện trên dữ liệu, phụ lục xử lý dữ liệu và chuyển dữ liệu ra nước ngoài trước khi bật dữ liệu thật. Luật Trí tuệ nhân tạo 134/2025 có hiệu lực từ 01/03/2026; phạm vi nghĩa vụ cụ thể của tính năng AI phải được pháp chế phân loại theo use case. [Văn bản luật](https://vanban.chinhphu.vn/?docid=216334&pageid=27160&typegroupid=3).

## 10. Bảo mật và quyền riêng tư theo Việt Nam

**Căn cứ tính tới 12/10/2026:** [Luật Bảo vệ dữ liệu cá nhân 91/2025/QH15](https://vanban.chinhphu.vn/?classid=1&docid=214590&pageid=27160&typegroup=) và [Nghị định 356/2025/NĐ-CP](https://vanban.chinhphu.vn/?classid=1&docid=216387&pageid=27160) cùng có hiệu lực 01/01/2026; [Luật An ninh mạng 116/2025/QH15](https://vanban.chinhphu.vn/?classid=1&docid=216499&orggroupid=1&pageid=27160) có hiệu lực 01/07/2026, [Nghị định 333/2026/NĐ-CP](https://vanban.chinhphu.vn/?docid=219244&orggroupid=2&pageid=27160) và [Nghị định xử phạt 330/2026/NĐ-CP](https://vanban.chinhphu.vn/?classid=1&docid=219266&pageid=27160) có hiệu lực 19/08/2026. Đây là checklist sản phẩm/kỹ thuật, không thay thế ý kiến pháp lý theo mô hình doanh nghiệp cụ thể.

| Kiểm soát cần có | Yêu cầu để đưa vào backlog |
|---|---|
| Inventory/mục đích | Liệt kê trường dữ liệu, nguồn, mục đích, căn cứ xử lý, người nhận, nơi lưu, thời hạn; giảm thu thập CCCD, bệnh lý, tài khoản ngân hàng khi không thật cần |
| Đồng ý và thông báo | Bản thông báo rõ mục đích vận hành và mục đích marketing/AI riêng; lưu phiên bản, thời điểm, kênh và bằng chứng đồng ý/rút lại |
| Dữ liệu nhạy cảm | Phân loại ghi chú bệnh lý/chấn thương, CCCD, tài chính; mã hóa, tách lưu, truy cập tối thiểu, audit đọc; không đưa vào báo cáo/AI mặc định |
| Quyền chủ thể | Luồng tiếp nhận/đối chiếu/xử lý yêu cầu truy cập, chỉnh sửa, rút đồng ý, xóa/hạn chế theo nghĩa vụ áp dụng; giữ phần cần thiết cho hợp đồng/kế toán theo xác định pháp lý |
| Chuyển xuyên biên giới | Lập sơ đồ data flow cho Lark, cloud, email/ZNS, AI, CDN, backup; đánh giá nghĩa vụ hồ sơ và biện pháp theo luật/nghị định trước khi bật chuyển |
| Đánh giá tác động | Pháp chế/DPO xác định hồ sơ đánh giá tác động xử lý và chuyển xuyên biên giới, thời hạn/nơi nộp, các ngoại lệ thực sự áp dụng; lưu chứng cứ cập nhật |
| Bảo vệ kỹ thuật | TLS, mã hóa at rest/key rotation, MFA nhân sự, least privilege, secret manager, session timeout, rate limit, WAF, backup và restore drill, scan dependency, pen test trước go-live |
| Sự cố | Quy trình phát hiện, cô lập, điều tra, thông báo/báo cáo theo nghĩa vụ áp dụng; log đủ để truy nguồn nhưng mask dữ liệu nhạy cảm |
| Nhà cung cấp | DPA, phân vai controller/processor, subprocessor, vị trí xử lý, retention, khả năng xóa và xuất dữ liệu khi chấm dứt |

**Không suy ra rằng cứ đặt server ở Việt Nam là đã tuân thủ đầy đủ, hoặc mọi dữ liệu bắt buộc phải lưu tại Việt Nam.** Nghĩa vụ cụ thể phụ thuộc loại dữ liệu, chủ thể, nơi xử lý và mô hình dịch vụ; DEV cần thiết kế để pháp chế kiểm chứng được.

## 11. Học từ sản phẩm fitness hiện tại

Các sản phẩm sau được dùng làm **tham chiếu tính năng**, không hàm ý ALL IN phải mua hay sao chép nguyên bộ:

| Sản phẩm và nguồn chính thức | Điều quan sát được | Khuyến nghị cho ALL IN | Ưu tiên |
|---|---|---|---|
| [Glofox](https://www.glofox.com/features/scheduling/) | Lịch PT/lớp, capacity, waitlist, nhắc lịch, late cancel/no-show, đa chi nhánh | Thiết kế slot/occurrence/waitlist và policy theo chi nhánh ngay từ đầu | P1 |
| [Mindbody](https://www.mindbodyonline.com/en-gb/business/fitness) | Lịch nhân sự, thay ca, hiệu suất, payroll, booking, báo cáo | Quy trình dạy thay và đối soát công/lương dựa trên lịch/attendance | P1 |
| [ABC Trainerize](https://www.trainerize.com/features/) | Chương trình tập, mục tiêu, thói quen, tiến độ, messaging | Pha sau: mục tiêu/tiến độ của KH để tăng gắn bó; giữ dữ liệu sức khỏe có kiểm soát | P2 |
| [Glofox](https://www.glofox.com/features/) | Hồ sơ hội viên, gói, thanh toán, check-in, báo cáo, đa địa điểm | Dashboard retention: sắp hết gói, vắng tập, tái ký; phân quyền dữ liệu theo chi nhánh | P2 |

**Không ưu tiên đầu kỳ:** marketplace, social/community, nutrition AI, wearable sync và payment tự động nếu chưa có nhu cầu/đối tác chốt. Các tính năng này kéo thêm dữ liệu cá nhân và chi phí vận hành.

## 12. Phân kỳ, nghiệm thu và câu hỏi chốt với DEV

### 12.1 Phân kỳ đề xuất

| Giai đoạn | Bàn giao | Điều kiện ra giai đoạn |
|---|---|---|
| 0 — Discovery & data audit | Workshop rule, data dictionary, field ownership, mapping export/Lark, threat/privacy assessment, wireframe trải nghiệm 3 nhóm | Các câu hỏi quyết định bên dưới có chủ sở hữu và biên bản |
| 1 — Lõi an toàn | Auth/MFA, policy, PostgreSQL, audit, import dry-run, identity map, CI/CD, backup | Mọi API và export có test quyền; restore thành công |
| 2 — Booking & credit | KH/HLV portal, availability, PT/group, attendance, credit ledger, nhắc lịch | Concurrent booking không trùng; retry checkout không trừ đôi; đối soát số dư |
| 3 — Lark & payroll | Sync 2 chiều theo trường, dashboard lệch, rule version, show/payroll approval | Chạy song song 2 kỳ lương; từng sai khác có lý do/điều chỉnh |
| 4 — AI & growth | MCP/CLI read-only, retention dashboard, đề xuất/ghi có duyệt, progress | Red-team quyền và prompt injection; privacy review trước production |

### 12.2 Tiêu chí nghiệm thu bắt buộc

1. KH A/HLV A/Ops chi nhánh A không đọc được KH B, lương người khác hoặc trường sức khỏe ngoài scope qua UI, API, CSV và MCP/CLI.
2. 100 yêu cầu đặt cùng một slot/capacity giới hạn không tạo vượt chỗ; có kết quả idempotent khi retry.
3. Một attendance completed chỉ tạo một debit; reversal có tham chiếu, lý do và người duyệt; số dư đối chiếu được từ ledger.
4. Lark gửi lặp, đảo thứ tự, mất kết nối hoặc sửa xung đột đều có kết quả xác định, alert và hàng xử lý.
5. Payroll của kỳ đã khóa tái xuất giống hệt dù rule sau đó đổi; adjustment kỳ sau truy được nguồn gốc.
6. Phục hồi backup trên môi trường thử, đối soát record/credit/payroll; không dùng dữ liệu thật không mask ở dev/staging.
7. Hồ sơ pháp lý, data inventory, quy trình yêu cầu chủ thể và sự cố được chủ trách nhiệm phê duyệt trước dữ liệu production.

### 12.3 Câu hỏi cần chủ sản phẩm quyết định trước khi DEV báo giá

| Quyết định | Phương án phải chốt | Tác động |
|---|---|---|
| Hợp đồng nào cấp quyền tập? | đã ký, đã thanh toán một phần, payfull; ngưỡng từng loại gói | provisioning và booking eligibility |
| Trừ buổi lúc nào? | check-in, checkout, xác nhận đôi, no-show/hủy muộn | credit ledger và tranh chấp |
| Ai xác nhận attendance? | HLV, KH, Ops; có yêu cầu 2 bên với trường hợp nào | UX và kiểm soát gian lận |
| Hủy muộn/bảo lưu/đổi HLV | cutoff từng gói, hạn mức ngoại lệ, cấp duyệt | state machine và policy version |
| Công PT/nhóm | tính theo show, phút thực dạy, số KH check-in hay booked, dạy thay | pay rule và input evidence |
| Ngày công/lương cứng | lấy từ HRM/chấm công nào, cách prorate, nghỉ lễ | payroll đúng thực tế |
| Field ownership | gói/giá, hồ sơ KH, thông tin HLV, kết quả thanh toán | tránh sync xung đột |
| AI | use case đầu tiên, ai dùng, model/cloud ở đâu, có dữ liệu sức khỏe hay không | phạm vi pháp lý và bảo mật |
| Dữ liệu cũ | ngày cutover, dữ liệu lịch sử cần nhập, số dư mở đầu, nguồn đối soát | thời gian triển khai và migration |

## 13. Nguồn và dấu vết rà soát

**Nội bộ:** `ADMIN_REPLACEMENT_ARCHITECTURE.md` và `KB_AppBooking_Cap_Tai_Khoan.md` trong thư mục người dùng cung cấp; định hướng BOD trong brief. Không đánh giá mã phác thảo ở v2.  
**Tham chiếu ngoài:** liên kết chính thức đã đặt sát từng nhận định ở mục 6, 9, 10, 11. Ngày kiểm tra 12/10/2026. Tính năng và luật có thể thay đổi; rà soát lại trước ký hợp đồng triển khai.