Admin Settings Inventory — Mobile Planning

Mục đích: liệt kê toàn bộ cấu hình / dữ liệu mà salon owner đang quản lý trên booking-web/admin để lên plan mobile app (owner + staff). Mỗi mục ghi rõ: nguồn dữ liệu, API endpoint, đang/không enforce ở đâu, mức ưu tiên khi đưa lên mobile.

Đọc cùng:

• docs/flows/booking-flow.md — settings nào enforce ở đâu
• booking-api/prisma/schema.prisma — DB source of truth
• booking-api/src/core/tenant/tenant.dto.ts — DTO contract
• docs/mobile/feature-plan.md — plan feature mobile

Quy ước ưu tiên:

• P0 — MVP mobile (phải có trong bản đầu tiên)
• P1 — V1 (có sau 1–2 sprint, sau khi MVP chạy)
• P2 — V2+ (để sau, desktop admin vẫn phục vụ được)
• ❌ Desktop-only (không nên đưa lên mobile, quá phức tạp hoặc ít dùng)

0. Tổng quan tầng cài đặt

Hệ thống có 4 tầng cấu hình, tất cả thuộc booking-web/admin:

UI entry: /admin/settings (8 tabs), /admin/staff, /admin/services, /admin/loyalty, /admin/work-schedule.

1. Settings — General tab

Route: /admin/settings?tab=general Component: booking-web/src/components/settings/GeneralSection.tsx API: GET /api/tenants/me, PATCH /api/tenants/:id

💡 Lưu ý mobile: slug, currency, timezone là critical data — không nên cho đổi trên mobile vì breaking change với bookings cũ. Chỉ cho xem.

2. Settings — Booking tab (Booking Policy)

Route: /admin/settings?tab=booking Component: booking-web/src/components/settings/BookingSection.tsx + BookingPolicyEditor API: PATCH /api/tenants/:id (nested trong settings)

Enforce matrix (đã document chi tiết trong docs/flows/booking-flow.md):

• autoConfirm → public booking API set status
• bookingMode → public booking validate resourceId
• cancellationHours → customer cancel endpoint
• maxBookingDaysInAdvance → availability API + create booking
• depositEnabled/type/value → payment flow (dispatch deposit command)

⚠️ Cảnh báo chéo: Nếu depositEnabled=true nhưng chưa có TenantPaymentConfig active → onboarding đã cảnh báo. Mobile cũng phải show cảnh báo này.

3. Settings — Business Hours tab

Route: /admin/settings?tab=businessHours Component: booking-web/src/components/settings/BusinessHoursSection.tsx + shared business-hours editor API: PATCH /api/tenants/:id (settings.businessHours)

Schema (lưu trong Tenant.settings.businessHours):

[
  {
    "dayOfWeek": 1,       // 0=Sunday, 6=Saturday
    "isOpen": true,
    "slots": [
      { "startTime": "09:00", "endTime": "12:00" },
      { "startTime": "13:00", "endTime": "17:00" }  // multi-slot, break giữa trưa
    ]
  }
]

💡 Editor pattern: đã có shared editor ở booking-web/src/components/business-hours/. Mobile nên thiết kế native picker tối ưu cho ngón tay (tap & hold range slider).

4. Settings — Branding tab

Route: /admin/settings?tab=branding Component: booking-web/src/components/settings/BrandingSection.tsx API: PATCH /api/tenants/:id (branding)

💡 Upload: API đã có upload endpoint qua MinIO. Mobile cần expo-image-picker + resize trước khi POST.

5. Settings — About tab

Route: /admin/settings?tab=about Component: booking-web/src/components/settings/AboutSection.tsx API: PATCH /api/tenants/:id (description, HTML)

• description (HTML, rich text via Tiptap, sanitize-html ở backend).
• Mobile: P2. Rich text editor trên mobile phức tạp — tạm thời cho nhập plain text + markdown hoặc defer.

6. Settings — Location tab

Route: /admin/settings?tab=location Component: booking-web/src/components/settings/LocationSection.tsx + AddressSearch, LocationMap API: PATCH /api/tenants/:id (address)

• Desktop dùng Nominatim (OpenStreetMap) geocoding + pigeon-maps interactive map.
• Mobile: có thể tận dụng native map (react-native-maps) + location picker. P1 cho edit, P0 cho hiển thị.

7. Settings — Tax & Accounting tab

Route: /admin/settings?tab=tax Components: TaxSettings.tsx, AccountingSettings.tsx, TaxFormModal.tsx, AccountFormModal.tsx API: GET/POST/PATCH/DELETE /api/taxes, /api/accounting-accounts

7.1 Tax rates

Seed mặc định (Na Uy): 25% (default), 15%, 0% — xem booking-api/src/core/tenant/tenant-defaults.ts.

7.2 Accounting accounts

❌ Đánh giá: Tax + Accounting là accountant territory, owner thường setup 1 lần rồi quên. Mobile không cần trừ khi đưa vào flow "tạo service" (cần chọn accounting account).

8. Settings — Payment tab

Route: /admin/settings?tab=payment Components: PaymentSettings.tsx, ProviderCard, ProviderConfigDrawer, BamboraConfigForm, HealthCheckBadge API: GET/POST/PATCH/DELETE /api/admin/payment-configs, POST .../:id/rotate, POST .../:id/activate, POST .../:id/health-check

⚠️ Security: credentials chỉ nhập từ desktop (đã có khuyến nghị trong memory "Payment Implementation"). Mobile chỉ nên: xem status, toggle active, health check.

9. Services & Categories (Catalog)

Route: /admin/services Components: ServicesContent.tsx, ServiceList.tsx, ServiceFormModal.tsx, CategoryManager.tsx, AddCategoryModal.tsx API: /api/services, /api/service-categories

9.1 Service

9.2 ServiceCategory

💡 Mobile nên có quick-create service ngay từ booking drawer (khi staff/owner tạo booking và chưa có dịch vụ trong catalog).

10. Staff / Resources

Route: /admin/staff Components: StaffContent.tsx, StaffList.tsx, StaffFormModal.tsx, MetadataFields.tsx API: /api/resources, /api/resources/:id/skills

💡 Industry-aware label: hiển thị "Barbers" / "Therapists" / "Staff" theo industryType. Dùng useResourceLabel() hook ở web — mobile cần port logic tương đương.

11. Work Schedule (Staff lịch làm việc)

Route: /admin/work-schedule Components: WorkScheduleContent.tsx, ScheduleGrid.tsx, ScheduleCellEditor.tsx, RecurringScheduleModal.tsx, TimeOffModal.tsx API: /api/resources/:id/schedules, /api/resources/:id/schedule-overrides, /api/time-offs

11.1 ResourceSchedule (weekly recurring)

• 1 staff × 7 ngày × multi-slot ({ dayOfWeek, startTime, endTime, isActive }).
• Mobile P0 — staff cần xem & owner cần sửa nhanh.

11.2 ResourceScheduleOverride (override 1 ngày cụ thể)

• { resourceId, date, startTime?, endTime?, reason? } — null = ngày nghỉ đặc biệt.
• Mobile P0 — ví dụ owner duyệt nghỉ cho 1 staff trong ngày.

11.3 TimeOff (vacation / sick)

💡 Staff request → Owner approve là flow rất tự nhiên trên mobile. Nên làm sớm.

12. Loyalty Programs

Route: /admin/loyalty Components: LoyaltyContent.tsx, LoyaltyList.tsx, LoyaltyFormModal.tsx API: /api/loyalty/cards, /api/loyalty/stamps, /api/loyalty/redemptions, /api/loyalty/points

❌ Setup loyalty chỉ cần làm 1 lần — defer mobile. Nhưng xem tình trạng stamps/points của khách khi tra profile → P0.

13. Customers

Route: /admin/customers Components: CustomersContent.tsx, CustomerList.tsx, CustomerFormModal.tsx API: /api/customers, /api/tenant-customers

💡 Customer profile trên mobile = màn hình quan trọng cho staff (check lịch sử trước cuộc hẹn, ghi note sau).

14. Bookings

Route: /admin/bookings Components: Calendar (BookingCalendar.tsx, StaffColumn.tsx, BookingBlock.tsx, useDragBooking.ts), List (BookingList.tsx), Drawer (BookingDrawer.tsx, ServicePicker.tsx, AddedServiceCard.tsx) API: /api/bookings, /api/availability, /api/bookings/:id/status/:status

Tính năng đã có (desktop)

• Day/Week calendar view, drag-drop reschedule, staff column layout.
• Multi-service booking (1 booking nhiều items với staff riêng, thời gian riêng).
• Status machine: PENDING → CONFIRMED → ARRIVED → IN_PROGRESS → COMPLETED / CANCELLED / NO_SHOW.
• Conflict detection (409 on overlap).
• Audit log (ai làm gì khi nào).
• Payment summary card (deposit, remaining, refund).
• Loyalty redemption apply.

📱 Chi tiết phân rã cho mobile ở feature-plan.md.

15. Payments (Transactions)

Route: /admin/payments Components: PaymentsContent.tsx, PaymentList.tsx, PaymentDetailDrawer.tsx, CaptureDialog.tsx, CollectRemainingModal.tsx, RefundDialog.tsx, VoidDialog.tsx API: /api/admin/payments/*

• List + filter by status (INITIATED, AUTHORIZED, CAPTURED, ...).
• Detail drawer: events, state machine, provider refs.
• Actions: capture, void, refund (partial), collect remaining.
• Mobile: P1 (xem list + capture/refund common cases), action chi tiết ưu tiên desktop.

16. Onboarding Wizard

Route: /admin/onboarding (full-page, guards OWNER nếu tenant.onboardedAt == null) Spec: 7 bước — Welcome → Salon info → Business hours → Services → Staff → Booking policy → Review & Launch.

💡 Mobile: mobile app cũng cần support onboarding cho owner lần đầu đăng ký qua app (ví dụ download app trên store, tạo tài khoản). P1 — MVP có thể force onboard qua web.

17. Dashboard

Route: /admin (default) Components: DashboardContent.tsx, DashboardMetrics.tsx, MetricCard.tsx, TodayTimeline.tsx, UpcomingBookings.tsx, QuickActions.tsx.

18. Profile (Admin user settings)

Route: /admin/profile API: /api/auth/me, /api/auth/change-password

• Email, phone, password. P0 cho mobile.

19. Ma trận ưu tiên — cheatsheet

20. Gaps / câu hỏi cần trả lời trước khi build mobile

1. Owner vs Staff UI split — cùng app hay 2 app? Hiện tại README nói "role-based UI switching within a single app" → đi theo hướng này.
2. Offline-first scope — WatermelonDB sync cho những entity nào? Đề xuất: Booking, Resource, Service, Customer, TenantSettings snapshot. Payment KHÔNG offline (phải online để gọi provider).
3. Push notification — Expo push hay FCM trực tiếp? PRD nêu Expo push (US-7.3). Cần chuẩn bị expo-notifications + device token endpoint ở API.
4. Subdomain routing — web dùng {slug}.app.no, mobile dùng API trực tiếp → không lệ thuộc, ok.
5. Deep link từ QR code — /b/:slug/bookings/:id đã gen sẵn. Mobile staff cần scan QR → open booking detail. Cần expo-linking + deep link scheme.
6. Payment credential — confirm dứt khoát: nhập credentials chỉ qua web admin, mobile chỉ view + toggle.
7. Rich text (description, service description) — dùng markdown thay vì HTML trên mobile để tránh Tiptap phức tạp.
8. Language — Norwegian Bokmål (nb-NO) primary, chuẩn bị i18n từ đầu (expo-localization + i18n-js hoặc react-intl).
9. Admin "login as tenant" (impersonate) — chưa có, cả web cũng chưa. Mobile có cần không? → Không cho MVP, dùng desktop.

21. Sync với existing docs

Khi thêm/sửa setting mới trên mobile, phải update đồng thời:

• docs/flows/booking-flow.md — nếu setting ảnh hưởng booking logic.
• docs/flows/payment-flow.md — nếu liên quan payment.
• booking-api/src/core/tenant/tenant.dto.ts — DTO contract.
• booking-api/src/core/tenant/tenant-settings.constants.ts — default values per industry.
• booking-web/src/types/api.generated.ts — regen sau khi đổi DTO.
• booking-mobile/src/types/api.generated.ts — regen qua OpenAPI codegen.

Quy tắc "KHÔNG fallback settings" áp dụng cho mobile như backend — data phải complete trong DB, UI không được silent default.