Mobile App — Feature Plan

Bối cảnh: booking-mobile/ là React Native + Expo app, chạy WatermelonDB offline-first, OpenAPI codegen cùng API contract với web. Phục vụ Owner + Staff trong 1 app duy nhất (role-based UI switch). Khách hàng dùng web customer portal (/b/:slug), KHÔNG nằm trong scope mobile.

Đọc trước:

• docs/mobile/admin-settings-inventory.md — inventory cài đặt admin
• docs/product/prd.md — user stories (US-2.4, US-4.4, US-4.5, US-5.2, US-7.3 là mobile-first)
• docs/flows/booking-flow.md — booking rules
• docs/progress/features.md — trạng thái backend hiện tại

0. Prerequisite — Role audit + harden (BLOCKER, làm TRƯỚC mobile)

⚠️ Mobile không build được trước khi fix điểm này. Hiện tại role-based permissions chưa được verify end-to-end trên web + API, nhiều endpoint chặn STAFF khiến flow mobile thiết yếu (walk-in, xem resources, đọc settings) sẽ gãy.

0.0.1 Hiện trạng (phát hiện khi viết plan này)

0.0.2 Sprint "Role audit & harden" (1–1.5 tuần)

Deliverables:

1. Ma trận quyền — file mới docs/architecture/role-matrix.md với bảng endpoint × [ADMIN|OWNER|STAFF|CUSTOMER] × [read|create|update|delete]. Decide dứt khoát từng ô.
2. Mở quyền STAFF cho read-only endpoint cần thiết: GET /services, GET /resources, GET /tenants/me, GET /loyalty/cards, GET /tenant-customers/:customerId.
3. Resource-scoping trong service layer:
   • BookingService.list() — nếu role=STAFF → WHERE resourceId = user.resource.id OR resourceId IS NULL (cho self-pick).
   • BookingService.update/updateStatus() — STAFF chỉ được sửa booking mình đang đảm nhận, trừ unassigned → self-pick.
   • TenantCustomerService — staff sửa được notes/tags nhưng không sửa được metrics.
4. Mở /admin cho STAFF trên web — đổi AuthGuard allowedRoles={["ADMIN","OWNER","STAFF"]}, sidebar filter theo role (staff không thấy Settings/Tax/Payment/Loyalty management), bookings page filter tự động theo resourceId.
5. E2E test role boundary (Playwright) — tối thiểu:
   • STAFF không list được all resources/services khi endpoint chưa mở.
   • STAFF đã mở quyền thì GET được nhưng không DELETE.
   • STAFF không PATCH được booking của resource khác (403).
   • STAFF self-pick unassigned booking khi có skill matching → OK.
   • STAFF self-pick unassigned booking khi KHÔNG có skill → 403.
   • OWNER override được conflict / double-booking.
   • CUSTOMER token bị reject ở admin endpoints (type claim check).
6. Unit test role-scoping cho BookingService + TenantCustomerService (happy + 403 path).

Done criteria:

• docs/architecture/role-matrix.md merged vào docs index.
• Web /admin login được bằng STAFF account, sidebar đúng, booking list đã filter.
• 7+ E2E scenarios pass.
• 0 endpoint còn chặn STAFF nhầm (whitelist đã review toàn bộ controllers).
• OpenAPI spec regen, booking-web + booking-mobile types sync.

Sau khi xong: mobile copy pattern role switch y hệt web (cùng permission logic, cùng sidebar filter), giảm rủi ro.

0. Nguyên tắc thiết kế

0.1 Role-based, single app

Đăng nhập → JWT trả về role (OWNER/STAFF/ADMIN). App swap navigation stack:

• OWNER → full access (dashboard, staff, services, settings, payments, reports).
• STAFF → schedule cá nhân, booking của mình, walk-in, self-pick, check-in, customer quick view. KHÔNG thấy settings, tax, payment config, không sửa được booking của staff khác (trừ khi owner cho).
• ADMIN (superadmin) → KHÔNG phục vụ trên mobile (memory đã note: admin cần "login as tenant" — dùng web).

0.2 Offline-first (critical cho salon thật)

Salon ở Na Uy nhiều chỗ wifi/signal kém, thao tác mid-appointment cần mượt. WatermelonDB sync cho entities dưới đây:

0.3 Các ràng buộc bắt buộc

• KHÔNG fallback settings — nếu chưa sync TenantSettings, chặn tạo booking (screen "Đang sync dữ liệu salon, vui lòng đợi").
• Timezone — mọi so sánh giờ làm việc dùng salon timezone (từ tenant.settings.timezone), KHÔNG device local.
• Money — minor units (øre), format qua shared helper.
• Error codes — translate từ error.code (domain prefix), KHÔNG show message thô.
• Zero tolerance — lint + build + type sạch; React Compiler rules như web (memory có feedback_react_compiler).

0.4 Tech stack xác nhận

1. Phân lớp MVP

Phase 1 — MVP (cho owner + staff xử lý vận hành hàng ngày)

Mục tiêu: Một salon có thể chạy full-day operation trên mobile mà không cần mở desktop (trừ setup ban đầu + payment config + tax).

Owner

1. Đăng nhập, xem dashboard (metrics hôm nay + today timeline + upcoming bookings).
2. Xem full calendar (day view) all staff, booking của tất cả.
3. Tạo / sửa / cancel booking (multi-service, assign staff, walk-in, from-phone).
4. Quản lý status (CONFIRMED → ARRIVED → IN_PROGRESS → COMPLETED / CANCELLED / NO_SHOW).
5. Xem + sửa customer (profile, notes, tags, booking history, loyalty balance).
6. Xem staff work schedule + approve time-off.
7. Quick-add / quick-edit service (P0 — name + duration + price + category).
8. Xem payment list (read-only) + capture/refund basic.
9. Settings read-only + sửa được: booking policy (toggle walkIn/autoConfirm/bookingMode/cancellationHours), business hours, branding colors.
10. Push notifications: new online booking, customer check-in, staff self-pick, payment success/failure.

Staff

1. Đăng nhập → thấy schedule CÁ NHÂN ngày hôm nay.
2. Xem booking chi tiết (customer, service, notes, giờ, status, payment status).
3. Update status booking của chính mình (CONFIRMED → ARRIVED khi khách đến, → IN_PROGRESS khi bắt đầu, → COMPLETED khi xong).
4. Scan QR của khách để mở booking (QR do customer portal gen ở /b/:slug/bookings/:id).
5. Walk-in quick create (chọn service, auto-assign bản thân, start=now).
6. Self-pick booking unassigned (nếu bookingMode=allow_unassigned và có skill phù hợp).
7. Customer quick view (profile, tags, notes, lịch sử booking, loyalty).
8. Request time-off (owner approve qua notification).
9. Profile cá nhân — đổi password, phone.
10. Push notifications: booking mới assign cho mình, walk-in notify owner, schedule change.

Phase 2 — V1 (sau MVP chạy ổn định)

Owner

• Drag-drop reschedule trên calendar (long-press + drag).
• Week view calendar (scroll ngang).
• Staff management: CRUD resource, assign skills, upload avatar.
• Service management: full CRUD + category + accounting link + metadata + image.
• Branding upload logo / cover (camera + gallery).
• Multi-service booking (add item ngay trong drawer).
• Payment drawer: event log, capture/refund/void/collect remaining.
• Deposit flow (enable + type + value).
• Location edit (pin trên map + reverse geocode).
• TimeOff approve/reject với reason.
• Onboarding wizard đầu tiên qua mobile (cho user download app trước khi login web).
• Export booking/revenue report CSV (share qua email/drive).

Staff

• Self service: xin đổi lịch, xem lương/commission nếu metadata có.
• Multi-day schedule view (tuần tới).
• Chat với khách hàng (link về booking) — defer nếu chưa có API.
• Notifications settings — mute hours.

Phase 3 — V2+ (roadmap xa)

• Online payment via Vipps (Na Uy native — rất phổ biến).
• Tap-to-pay (smartphone-as-POS, Apple/Android Tap to Pay SDK).
• Waitlist (khách đăng ký khi full, staff gọi khi có slot).
• Review system post-booking.
• Marketing campaigns (SMS/push cho inactive customers).
• Calendar sync (iOS/Android native calendar, Google Calendar).
• Analytics dashboard (booking trends, staff utilization heatmap).
• Multi-location: swap location trong app (khi có Organization layer).
• Superadmin "login as tenant" — vẫn không nên đưa lên mobile.

2. Information architecture (IA)

2.1 Navigation — Owner

Tabs (bottom):
├── 🏠 Home              (dashboard)
├── 📅 Calendar          (day view, swap staff filter)
├── ➕ New Booking       (FAB trung tâm, full-screen modal)
├── 👥 Customers
└── ⋯ More
    ├── Staff & Schedule
    ├── Services
    ├── Payments
    ├── Loyalty (view-only)
    ├── Settings
    └── Profile / Logout

2.2 Navigation — Staff

Tabs (bottom):
├── 📅 My Schedule       (today default, swipe cho ngày khác)
├── ➕ Walk-in           (FAB trung tâm, quick-create)
├── 👥 Customers         (read + quick edit notes/tags)
└── ⋯ More
    ├── Unassigned Queue (nếu bookingMode = allow_unassigned)
    ├── Scan QR
    ├── Time-off Request
    └── Profile / Logout

2.3 Screen inventory (ước lượng)

3. Đặc tả chi tiết một số flow mobile-first

3.1 Staff check-in khi khách đến (P0)

[Home / Calendar]
    └─ tap booking → Booking Detail
        ├─ Status badge: CONFIRMED
        ├─ Button "Khách đến" (primary)
        │   └─ Tap → PATCH /bookings/:id/status/ARRIVED → success toast
        │       └─ Refetch booking, animate status badge
        └─ Button "Bắt đầu" (sau ARRIVED)
            └─ PATCH → IN_PROGRESS

Biến thể: Scan QR khách đưa điện thoại → mở trực tiếp Booking Detail → nút "Khách đến" ngay tay.

3.2 Walk-in (P0)

[Walk-in FAB]
    ├─ Chọn service (grid lớn — tap size ≥ 48×48)
    ├─ (nếu owner) chọn staff, (nếu staff) tự gán mình
    ├─ (optional) nhập tên khách + phone — hoặc skip
    └─ Tap "Bắt đầu ngay"
        └─ POST /bookings { source: WALK_IN, startTime: now, status: IN_PROGRESS }
            └─ Toast + push notif owner

Yêu cầu offline: lưu vào WatermelonDB, queue sync, UI hiện ngay trên calendar với badge "⋯ đang đồng bộ".

3.3 Self-pick unassigned (P0 — theo US-4.5)

[Tab More → Unassigned Queue]
    ├─ List bookings resourceId=null, filter theo skill của staff
    ├─ Mỗi card: service + time + customer + duration
    └─ Tap "Nhận" (swipe-right action)
        └─ PATCH /bookings/:id { resourceId: myResourceId }
            ├─ Nếu 409 (ai đó vừa nhận) → toast "Người khác đã nhận rồi"
            └─ Nếu 200 → remove khỏi list + add vào My Schedule

3.4 Owner approve TimeOff (P0)

Push notif "Staff A xin nghỉ 20–22/5" (tap) →
[TimeOff detail] →
    ├─ Hiển thị: staff, range, reason, impact (bookings bị ảnh hưởng)
    └─ 2 button: Approve / Reject + note
        └─ PATCH /time-offs/:id { isApproved: true/false }
            └─ Trigger re-check bookings trong range → hiện danh sách nếu có conflict

3.5 Owner sửa business hours nhanh (P0)

[More → Settings → Business hours]
    ├─ 7 rows (thứ 2 → chủ nhật), mỗi row: toggle mở/đóng + slots list
    ├─ Tap slot → native time picker (start/end)
    ├─ "+ Thêm slot" cho break giữa ngày
    └─ Save → PATCH /tenants/:id { settings: { businessHours } }
        └─ Hỏi: "Áp dụng cho lịch staff?" (applyToStaff boolean)

3.6 Dashboard metrics (P0)

Widgets:

• Today bookings count (tap → filter calendar hôm nay).
• Revenue today (tổng paidAmount của booking COMPLETED).
• Customers new today.
• Pending bookings (cần confirm thủ công nếu autoConfirm=false).
• No-show rate 7 ngày.

4. Notifications (push)

4.1 Registration

1. App khởi động → lấy Expo push token qua expo-notifications.
2. POST /api/auth/devices với { token, platform, appVersion }.
3. Lưu localStorage + invalidate khi logout.

4.2 Events (source: domain events từ backend)

4.3 Backend changes cần thiết

• DeviceToken model (chưa có): { userId, token, platform, lastSeenAt }.
• NotificationService publish Expo push qua BullMQ queue (infra đã có).
• Wire vào domain events hiện có (BookingCreated, BookingConfirmed, BookingCancelled, PaymentCaptured, ...).
• Cron daily summary (end-of-day per tenant timezone).

5. Security & session

6. Sync strategy (offline-first)

Nguyên tắc: dùng lại 100% REST API hiện có cho web admin. Mobile KHÔNG cần endpoints /api/sync/* riêng. Chỉ bổ sung 2–3 thứ nhỏ (device token, idempotency key) để hỗ trợ retry & push.

6.1 Hướng tiếp cận — Hướng A (recommended cho MVP)

Read path — cache response REST hiện có:

• Login / mở app → gọi song song các list API (GET /bookings?date=today, /resources, /services, /customers, /tenants/me) → lưu WatermelonDB.
• Refetch định kỳ (30s foreground, expo-background-fetch 15 phút min khi background).
• Offline: đọc trực tiếp từ WatermelonDB.

Write path — queue + idempotent retry:

• Mutation offline → lưu pending record trong WatermelonDB + gen idempotencyKey (UUID v7 client-side).
• Khi online → flush queue bằng chính REST endpoint gốc (POST /bookings, PATCH /bookings/:id/status/:status, ...) kèm header Idempotency-Key.
• Retry với backoff (1s → 2s → 4s → 8s → 16s → drop + toast).

Tại sao đủ: 1 salon trung bình ~50–200 bookings/ngày → full list pull <200KB, mỗi request ~100ms. Overhead nhỏ, code backend phải viết cũng nhỏ. Incremental sync chỉ đáng đầu tư khi dataset >1000 records/ngày.

6.2 Bổ sung tối thiểu ở backend

6.3 Conflict resolution (minimal)

Dùng updatedAt + If-Unmodified-Since hoặc ETag (API đã có updatedAt):

• Client gửi If-Unmodified-Since: <cached_updatedAt> khi PATCH.
• Server trả 409 nếu bản ghi đã bị sửa sau thời điểm đó.
• Client → toast "Dữ liệu đã thay đổi, refetch" → refetch + cho user thao tác lại.

Default rule: server always wins. Client không tự merge — refetch + show lại.

Ngoại lệ: Customer.notes, TenantCustomer.tags → client merge last-write-wins vì ít conflict thực tế.

6.4 Background sync

• Foreground: React Query refetchInterval: 30_000 cho danh sách chính.
• Backgrounded: expo-background-fetch 15 phút (iOS min).
• Kết nối lại sau offline: NetInfo listener → flush pending queue + invalidate queries.

6.5 Sơ đồ dòng dữ liệu

[Mobile UI]
    │  write
    ▼
[Mutation] ──online?── yes ─► [POST /api/bookings + Idempotency-Key]
    │                             │
    │ no                          └─ 200 → update cache
    ▼                             └─ 409 → refetch + retry
[WatermelonDB queue]
    │
    │  NetInfo → online
    ▼
[Flush loop] → same POST với cùng Idempotency-Key

7. Gate / chặn hành động

8. Test strategy

8.1 Test pyramid

• Unit: utility functions (format, tz conversion, sync conflict logic). Vitest hoặc Jest + React Native Testing Library.
• Integration: navigation flows + API mocks. MSW (mock service worker).
• E2E: Detox hoặc Maestro — smoke test critical flows (login → new booking → status change).

8.2 Offline tests

• Simulated airplane mode khi walk-in → sync → verify.
• Conflict simulation: 2 devices self-pick cùng lúc.

8.3 Coverage target

80%+ như web (memory: feedback_commit_checklist).

9. Milestone / timeline ước lượng

Tổng MVP: ~7–9.5 tuần solo developer (role audit 1–1.5 tuần + mobile 6–8 tuần), song song với backend enhancements (device token, push worker, idempotency key).

10. Backend dependencies (cần chuẩn bị trước khi mobile build)

Tin tốt: 90% REST API hiện tại của web admin reuse được nguyên cho mobile (cùng OpenAPI, cùng auth, cùng tenant scope). Chỉ cần bổ sung những mục dưới đây.

11. Tham khảo pattern có sẵn trên web để port

💡 Một số helper có thể extract thành package shared (@booking/shared) nếu monorepo. Hiện là multi-repo nên copy + cùng DTO types qua OpenAPI codegen là đủ.

12. Câu hỏi mở — cần decision trước khi bắt đầu

1. Auth login: chỉ email/password, hay cho phép staff login bằng phone + OTP? PRD không nói rõ.
2. Walk-in customer: bắt buộc nhập phone hay optional? Hiện public flow là optional.
3. Self-pick race: backend đã có optimistic lock? Nếu chưa → cần thêm If-Match / version check trên PATCH booking.
4. Notification sound/vibration: có cần per-event preference không? P1 là đủ.
5. Dark mode: salon hay sáng sủa, nhưng đêm staff xử lý booking có thể tối. Theme system nên follow branding primaryColor.
6. Min OS: iOS 14+ / Android 8+? Tuỳ Expo SDK version (SDK 51+ yêu cầu iOS 13.4+ / Android 7+).
7. Payment in mobile: có ý định cho owner nhập credentials KHÔNG BAO GIỜ trên mobile (confirmed). Nhưng capture / refund / void từ mobile nên cho, vì thường xử lý ngay khi khách trả tiền.
8. Admin impersonate (login as tenant): defer, chỉ desktop.
9. Waitlist / prepaid packages: roadmap (docs/progress) nói "Long-term". Mobile nhận lịch scope V2.
10. Commission tracking: Resource.metadata.commission đã có. Có show cho staff xem tiền hoa hồng không? → đề xuất P1 kèm toggle owner bật/tắt per-tenant.

13. Tóm tắt — bắt đầu từ đâu?

Đề xuất sprint 1 (2 tuần) để chứng minh vòng khép kín:

1. Backend: DeviceToken + POST /api/auth/devices; 1 BullMQ worker gửi Expo push; listen 1 event (BookingCreated); thêm Idempotency-Key cho POST /bookings.
2. Mobile: login + SecureStore + codegen + WatermelonDB 2 model (Booking, Resource).
3. Mobile: gọi GET /api/bookings?date=today → cache WatermelonDB → My Schedule đọc offline được.
4. Mobile: offline walk-in → queue POST với idempotency key → flush khi online.
5. Mobile: nhận push khi booking mới → deep link vào Booking Detail.

Xong sprint 1 → có framework để mở rộng nhanh. Các phase sau chủ yếu là thêm UI + lặp lại pattern read/write này cho entities khác.

14. Keep in sync

Doc này update song song khi:

• Thêm/sửa TenantSettings field mới (link admin-settings-inventory.md).
• Backend thêm domain event cần push.
• Thay đổi sync protocol.
• Release mobile version (ghi trong docs/progress/changelog.md).