Tổ chức & Chi nhánh Phase 1 In-progress

Tổ chức & Chi nhánh là lớp cấu trúc doanh nghiệp của chuỗi sân pickleball: một Tổ chức (cơ sở chủ sân) sở hữu nhiều Chi nhánh, mỗi chi nhánh có sân, nhân sự, kho và kênh bán riêng. Module cho phép Chủ sân mở thêm chi nhánh, phân quyền Quản lý ca theo từng chi nhánh, và xem dashboard HQ so sánh hiệu suất toàn hệ thống. Mọi dữ liệu khác (sân, kho, báo cáo) đều móc vào chi nhánh mà nó tạo.

1. Định danh

Thuộc tính	Giá trị
Module ID	OW-09
Hạng	Core
Trạng thái	In-progress
Giai đoạn	P1 (chi nhánh đầu khi onboarding) · P2 (đa chi nhánh đầy đủ)
Ưu tiên	HIGH
Người dùng chính	Chủ sân · Quản lý ca · (quyền đọc cho Thu ngân / Xem báo cáo)

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Tổ chức chủ sân + nhiều chi nhánh (cơ sở pickleball)	Vòng đời & đăng nhập nhân viên (→ Xác thực)
Tạo/sửa/bật-tắt chi nhánh, thông tin địa điểm, ảnh	Định nghĩa vai trò/quyền chi tiết (→ Phân quyền)
Kênh bán: POS quầy / app khách	Quản lý sân & slot (→ Quản lý Sân)
Phân công Manager & Cashier theo chi nhánh	Nội dung kho theo chi nhánh (→ Kho Hàng)
Cấu hình riêng từng chi nhánh (giờ, chính sách, MST)	Tổng hợp số liệu báo cáo (→ Doanh thu & Báo cáo)
Dashboard HQ so sánh hiệu suất chi nhánh	Đồng bộ địa điểm lên app khách (sở hữu bởi app)
Branch scope: cô lập dữ liệu giữa các chi nhánh

Tổ chức vs Chi nhánh. Tổ chức là cơ sở chủ sân (thương hiệu chuỗi) sở hữu toàn hệ thống. Chi nhánh là cơ sở pickleball vật lý - nắm sân, nhân sự, kho, MST và hồ sơ hoá đơn riêng, và là nơi giao dịch thực sự diễn ra. Chi nhánh đầu tiên được tạo tự động trong quá trình onboarding.

3. Năng lực

Năng lực	Người dùng làm được gì
Danh sách chi nhánh	Xem tất cả chi nhánh: tên, địa chỉ, số sân, số nhân viên, trạng thái
Thêm chi nhánh	Tạo cơ sở mới: tên, địa chỉ, SĐT, email, giờ hoạt động, ảnh
Sửa & bật/tắt chi nhánh	Cập nhật thông tin; tạm đóng một chi nhánh không ảnh hưởng chi nhánh khác
Kênh bán	Quản lý kênh POS quầy (thu ngân) và app khách (khách tự đặt) theo chi nhánh
Phân công nhân sự	Gán Manager/Cashier vào chi nhánh; một nhân viên có thể thuộc nhiều chi nhánh
Chọn chi nhánh khi đăng nhập	Nhân viên đa chi nhánh chọn chi nhánh làm việc; đổi qua dropdown header
Cấu hình riêng	Mỗi chi nhánh có giờ hoạt động, chính sách huỷ, MST và hồ sơ hoá đơn riêng
Dashboard HQ	Chủ sân xem KPI tổng và so sánh doanh thu/lấp đầy giữa các chi nhánh
Branch scope	Hệ thống lọc dữ liệu theo branch_id trong JWT; cô lập dữ liệu chi nhánh

4. Phụ thuộc Module

Phụ thuộc vào	Lý do
Onboarding	Chi nhánh đầu tiên được tạo tự động trong luồng onboarding
Xác thực & Phân quyền	JWT chứa branch_id; middleware enforce branch scope ở mọi endpoint

Được phụ thuộc bởi	Lý do
Quản lý Sân	Mỗi sân thuộc về một chi nhánh
Nhân Sự	Nhân viên được phân công theo chi nhánh
Doanh thu & Báo cáo	Báo cáo lọc theo chi nhánh; dashboard HQ tổng hợp đa chi nhánh
Kho Hàng	Kho được phân vùng riêng theo từng chi nhánh

5. Backend Packages

Chi tiết triển khai nằm trong tài liệu lập trình viên - mục này chỉ ánh xạ module tới service vận hành nó.

Package	Vai trò	Tài liệu lập trình viên
@nx/commerce	Sở hữu tổ chức, chi nhánh, kênh bán, phân công nhân sự, cấu hình chi nhánh và branch scope	commerce

6. Luồng người dùng chính

Tạo chi nhánh mới

Đăng nhập đa chi nhánh - chọn chi nhánh

7. Vai trò & Phân quyền

Vai trò	Được phép	Không được phép
Chủ sân	Tạo/sửa/tắt mọi chi nhánh, phân công nhân sự, xem dashboard HQ & so sánh chi nhánh	-
Quản lý ca	Xem chi nhánh mình, gán Cashier, sửa thông tin hiển thị (nếu được uỷ quyền)	Tạo/tắt chi nhánh, xem dashboard HQ, so sánh chi nhánh
Thu ngân	Xem thông tin chi nhánh đang làm việc	Mọi thao tác chỉnh sửa cấu trúc
Xem báo cáo	Read-only chi nhánh được phân công	Mọi thao tác chỉnh sửa

8. Trạng thái & Lộ trình

Giai đoạn	Năng lực
P1	Chi nhánh đầu tiên qua onboarding, branch scope trong JWT, lọc dữ liệu theo chi nhánh
P2	Đa chi nhánh đầy đủ: tạo/sửa/tắt, kênh bán POS & app khách, phân công nhân sự, cấu hình riêng, dashboard HQ so sánh hiệu suất
P3	Mô hình franchise, cấu trúc tập đoàn/group, loyalty xuyên chi nhánh

9. Trang liên quan

• Doanh thu & Báo cáo · Kho Hàng · Bán hàng
• Tài liệu lập trình viên: Commerce Service