# client-token-management Specification

## Purpose
TBD - created by archiving change client-auth-system. Update Purpose after archive.
## Requirements
### Requirement: 登录 JWT 签发与 Redis 状态存储

系统 MUST 在 A2/A3 登录成功后签发个人客户 JWT，并将 token 状态写入 Redis。

- JWT payload 字段：
  - `customer_id` uint，MUST
  - `exp` int64，MUST
- Redis Key：`RedisPersonalCustomerTokenKey(customerID)`
- Redis Value：当前有效 token（或 token 集合，取决于实现）
- TTL：MUST 与 JWT 过期时间一致

#### Scenario: 登录成功写入 Redis
- **WHEN** 客户完成微信登录
- **THEN** 系统 SHALL 签发 JWT
- **THEN** 系统 SHALL 将 token 写入 Redis 并设置 TTL

### Requirement: PersonalAuthMiddleware 双重校验

系统 SHALL 在个人客户认证中间件执行双重校验：JWT 解析校验 + Redis 状态校验。

#### Scenario: JWT 与 Redis 均有效
- **WHEN** 请求携带有效 JWT 且 Redis 中存在有效状态
- **THEN** 中间件 SHALL 放行并写入 `customer_id` 到上下文

#### Scenario: JWT 有效但 Redis 不存在
- **WHEN** JWT 仍在有效期但 Redis 中不存在该客户 token 状态
- **THEN** 中间件 MUST 返回未认证错误 `1002`

### Requirement: A7 退出登录接口

系统 MUST 提供需认证接口 `POST /api/c/v1/auth/logout`，用于删除 Redis token 状态。

- HTTP Method + Path: `POST /api/c/v1/auth/logout`
- 请求体字段：无
- 响应体字段：
  - `success` bool，MUST
- 错误码：
  - `1001` 缺失认证令牌
  - `1002` 认证令牌无效

#### Scenario: 退出登录成功
- **WHEN** 登录客户调用 A7
- **THEN** 系统 SHALL 删除 `RedisPersonalCustomerTokenKey(customerID)`
- **THEN** 系统 SHALL 返回成功

### Requirement: 服务端主动失效能力

系统 MUST 支持服务端主动使 token 失效（如封禁/强制下线），且无需等待 JWT 自然过期。

#### Scenario: 服务端主动踢出
- **WHEN** 管理动作触发客户强制下线
- **THEN** 系统 SHALL 删除对应 Redis token 状态
- **THEN** 该客户后续请求 MUST 被中间件拒绝