Use case: Select branch

Trạng thái

Đã đóng trong checkpoint Go Gateway + Go Identity.

Service sở hữu

Identity Service.

API Gateway yêu cầu account token context cho route này.

Endpoint

Yêu cầu xác thực

Bearer accountAccessToken.

Không dùng refreshToken hoặc branch-scoped accessToken cho use case này.

Mục tiêu

Đổi account-scoped token + branchId thành branch-scoped accessToken.

Luồng request

Client
→ API Gateway
→ Identity Service
→ Database / token service
→ Response

Contract API

Request

{
  "branchId": "00000000-0000-0000-0000-000000000000"
}

Success response

{
  "success": true,
  "code": "AUTH_SELECT_BRANCH_SUCCESS",
  "data": {
    "workspace": {},
    "member": {},
    "branch": {},
    "auth": {
      "tokenType": "Bearer",
      "accessToken": "branch-scoped token",
      "expiresIn": 900
    },
    "nextAction": {
      "type": "load_current_context"
    }
  }
}

Error response

• VALIDATION_ERROR: branchId missing/null.
• TOKEN_MISSING: thiếu Bearer token.
• TOKEN_INVALID: token sai loại, sai chữ ký, revoked, hoặc không phải accountAccessToken.
• TOKEN_EXPIRED.
• WORKSPACE_DISABLED, MEMBER_DISABLED.
• BRANCH_NOT_FOUND, BRANCH_DISABLED, BRANCH_ACCESS_DENIED.
• JWT_KEY_NOT_CONFIGURED.

Hành vi database

Read:

• identity.auth_session: load session từ token.
• identity.account: check account active.
• identity.workspace_member: xác nhận một active customer member.
• identity.branch: lookup branchId, check workspace/status.
• identity.branch_member: check active membership.
• identity.member_role, identity.branch_member_role, identity.role: lấy roles.

Write:

• identity.auth_session: update workspace_id, member_id, active_branch_id.

Hành vi token/session

• Identity verify accountAccessToken.
• branchId phải thuộc cùng workspace và active membership.
• Issue branch-scoped accessToken.
• Không rotate refreshToken trong select branch response.

Logs và observability

• Gateway access log expected: route_id=identity-auth, service_name=identity-service.
• Identity log có path=/api/auth/select-branch.
• Log không chứa token hoặc request body.

Tiêu chí nghiệm thu

• Happy path pass.
• Error path pass.
• Logs có request/correlation id nếu đi qua Gateway.
• Bruno/local smoke test pass nếu có.

TODO

• Chưa đóng: switch branch UX contract ngoài login/select flow hiện tại.