Roles & Permissions

Tài liệu này mô tả hệ thống roles & permissions trong Cohost, cách backend kiểm tra quyền và cách FE/bên thứ 3 cần gửi context khi gọi API.

---

1. Team Member Roles

Trong phạm vi team, Cohost sử dụng các role sau:

Role	Mô tả	Quyền
OWNER	Chủ team	Toàn quyền (listing, booking, financial, members, settings)
HOST	Người quản lý chính	Tạo/sửa listing, quản lý booking, xem financial
COHOST	Người hỗ trợ	Hỗ trợ HOST/OWNER quản lý listing và booking
GUEST	Khách	Không tham gia quản lý team

Enum: TeamMemberRoleEnum

---

2. Team Member States

Mỗi member có trạng thái (state) trong team:

State	Mô tả
INVITED	Đã được mời nhưng chưa tham gia
JOINED	Đã tham gia team
LEFT	Đã rời team
REMOVED	Bị xóa khỏi team

Enum: TeamMemberStateEnum

Quan trọng: Để truy cập API, user phải có state JOINED.

---

3. Team Status

Team cũng có trạng thái riêng:

Status	Mô tả
ACTIVE	Team đang hoạt động
SUSPENDED	Team bị tạm dừng
DELETED	Team đã bị xóa

Quan trọng: Để truy cập API, team phải có status ACTIVE.

---

4. X-Team-ID Header

Đa số API quản trị (listing, booking, financial, members, settings...) là team-scoped:

Authorization: Bearer <jwt_token>
X-Team-ID: <team_id>

Backend validate:

• Team tồn tại và có status ACTIVE
• User là owner HOẶC member với state JOINED

Chi tiết xem thêm: X-Team-ID Guide

---

5. Role Validation trong Backend

Backend sử dụng các dependency để kiểm tra quyền:

5.1. get_current_team

Validate team context:

• Team tồn tại và status ACTIVE
• User là owner HOẶC member với state JOINED

5.2. get_current_team_member

Lấy bản ghi TeamMember hiện tại (bao gồm role và state).

5.3. require_team_role(*roles)

Dependency factory để kiểm tra role cụ thể:

@router.get(“/financial”)
async def get_financial(
    current_team: Team = Depends(get_current_team),
    _: TeamMember = Depends(require_team_role(TeamMemberRoleEnum.OWNER, TeamMemberRoleEnum.HOST)),
):
    # Chỉ OWNER hoặc HOST mới truy cập được
    ...

---

6. Ví dụ API Authorization

Endpoint	Required Role
GET /api/v1/listings	OWNER, HOST, COHOST, GUEST
POST /api/v1/listings	OWNER, HOST
PATCH /api/v1/listings/{id}	OWNER, HOST
DELETE /api/v1/listings/{id}	OWNER, HOST
GET /api/v1/financial	OWNER, HOST
POST /api/v1/teams/members	OWNER, HOST
PATCH /api/v1/teams/members/{id}	OWNER

---

7. Hướng dẫn cho FE

• Duy trì selectedTeamId trong state/context
• Interceptor API phải luôn gắn X-Team-ID header
• Khi đổi team:
  • Cập nhật selectedTeamId
  • Invalidate cache các query liên quan team