# Roadmap：QY LTY Backend

## 概览

本路线图聚焦 **Milestone v1.0「通用凭据槽位（APP ID + Access Token）」**：在后端落地一组全局单例的通用凭据存储槽位，让 Web 管理后台可写入、手机端 + 设备端可读取，且 Access Token 不会落入生产日志。粒度为 coarse（3-5 phase），按"数据层 → 管理端读写 → 客户端读取 + 日志脱敏"自下而上推进，三个 phase 串行依赖。

## Milestones

- ✅ **v1.0 通用凭据槽位** — Phase 1-3 全部交付（2026-05-07 启动 / 2026-05-08 完结，CRED-01 至 CRED-06 全 Done）

## Phases

**Phase 编号说明：**
- 整数 phase（1、2、3）：当期 milestone 计划工作
- 小数 phase（2.1、2.2）：紧急插入工作（标记 INSERTED）

小数 phase 在数值序内夹在前后整数之间执行。

- [x] **Phase 1: 凭据槽位数据层** — 落地 `CredentialSlot` 单例模型 + 迁移 + Django Admin 注册（脱敏 + 隐藏新增按钮）✓ 2026-05-07 完成（Plan 01-01 + 01-02）
- [x] **Phase 2: 管理端读写接口** — 在 `/api/v1/admin/` 暴露凭据槽位 GET（脱敏）/ PUT（覆写）端点，admin token 鉴权 ✓ 2026-05-07 完成（Plan 02-01 + 02-02）
- [x] **Phase 3: 客户端读取与日志脱敏** — 在 `/api/credential-slot/` 暴露明文读取端点（user token 鉴权），并在阿里云日志链路过滤 `access_token` ✓ 2026-05-08 完成（Plan 03-01 + 03-02）

## Phase Details

### Phase 1: 凭据槽位数据层
**Goal**: 在数据库层落地全局单例的凭据槽位，并通过 Django Admin 提供受控录入入口（写入态可见、查看态脱敏、不可新增多条）
**Depends on**: Nothing（首个 phase）
**Requirements**: CRED-01, CRED-02
**Success Criteria**（必须为真）:
  1. 在 Django shell / Admin 中尝试创建第二条 `CredentialSlot` 记录会被 DB 层或模型层拒绝（DB 中最多一条）
  2. 运行 `python manage.py migrate` 后，schema 中存在 `app_id`、`access_token`、`updated_at` 三个字段，且首次访问时通过 `get_or_create(pk=1)` 拿到一条空记录
  3. 登录 Django Admin（SimpleUI 主题）打开凭据槽位页面：列表态/查看态下 `access_token` 显示为脱敏掩码（仅末 4 位），编辑态下显示明文供运营录入
  4. Admin 列表页**不显示**「新增」按钮（强制单例语义，避免运营误建第二条）
**Plans:** 2 plans
  - [x] 01-01-PLAN.md — 凭据槽位单例模型 + 迁移 + mask_token 工具（CRED-01）✓ 2026-05-07 完成（commits a9c25eb / 30c7caf / a475fe4）
  - [x] 01-02-PLAN.md — Django Admin 注册（脱敏/单例新增/禁删）+ 修改记录两条（CRED-02）✓ 2026-05-07 完成（commits 653f057 / ddbcb7d；Task 2 checkpoint 由 orchestrator Django test client 程序化验收 10/10 PASS）

### Phase 2: 管理端读写接口
**Goal**: Web 管理后台（qy-lty-admin）能通过 `/api/v1/admin/credential-slot/` 读取脱敏后的凭据槽位、并以全字段覆写方式更新它
**Depends on**: Phase 1
**Requirements**: CRED-03, CRED-04
**Success Criteria**（必须为真）:
  1. 携带有效 `admin_token:{token}` 调用 `GET /api/v1/admin/credential-slot/`，返回 `{ success, code, message, data: { app_id, access_token: <masked>, updated_at } }`，其中 `access_token` 仅暴露末 4 位掩码
  2. 携带有效 `admin_token:{token}` 调用 `PUT /api/v1/admin/credential-slot/` 提交 `{ app_id, access_token }`，记录被全字段覆写、`updated_at` 自动刷新；空记录场景自动 `get_or_create`，不报 404
  3. 不携带 admin token、或仅携带普通 user token 调用上述两个端点均被拒绝（401 / 403），错误响应同样符合 `StandardResponseMiddleware` 壳层
  4. 接口出现在 `/swagger/` 与 `/redoc/` 中，请求/响应 schema 与实际行为一致（drf-yasg 自动生成）
**Plans:** 2 plans
  - [x] 02-01-PLAN.md — CredentialSlot serializer + view（GET 脱敏 / PUT 覆写 + admin 二次校验）+ admin_urls 路由注册（CRED-03 + CRED-04）✓ 2026-05-07（commits 6820fe7 / 192d0a1 / 9d02021）
  - [x] 02-02-PLAN.md — 端到端 curl + Django shell 验收 8 条 success criteria + qy_lty / qy-lty-admin 两端修改记录互引（CRED-03 + CRED-04）✓ 2026-05-07（commits 3cfd481 / 46d72b8）

### Phase 3: 客户端读取与日志脱敏
**Goal**: 手机端（LTY_App_Project_URP）和设备端（LTY_Project）能通过 `/api/credential-slot/` 拿到**明文** APP ID + Access Token 去调用第三方服务；同时确保 Access Token 在阿里云日志中始终脱敏，不论是 PUT 请求体还是管理端 GET 响应体
**Depends on**: Phase 2
**Requirements**: CRED-05, CRED-06
**Success Criteria**（必须为真）:
  1. 携带有效 `token:{token}` 调用 `GET /api/credential-slot/`，返回 `{ success, code, message, data: { app_id, access_token: <明文>, updated_at } }`，Access Token 为明文（客户端实际调用第三方需要）
  2. 不携带 user token、或携带过期 token 调用客户端端点均被 `RedisTokenAuthentication` 拒绝（401），错误响应符合标准壳层
  3. 在生产日志（阿里云日志服务）中检索 Phase 2 / Phase 3 的请求轨迹：`PUT /api/v1/admin/credential-slot/` 请求体里的 `access_token` 字段被脱敏；管理端 `GET` 响应体里的 `access_token` 同样脱敏；客户端明文 GET 端点的响应体不写入日志（或同样脱敏），无任何位置暴露完整 Access Token 明文
  4. 端到端验证：管理后台用 PUT 写入一组凭据 → 手机端调用客户端 GET 拿到的 `app_id` / `access_token` 与管理端写入的一致（往返一致性成立）
**Plans:** 2 plans
  - [x] 03-01-PLAN.md — 客户端凭据槽位 GET 接口（CRED-05：CredentialSlotClientView 明文返回 + /api/credential-slot/ 路由注册）✓ 2026-05-08（commits 5269a08 / 50dcf1c / a58980f）
  - [x] 03-02-PLAN.md — 阿里云日志 access_token 脱敏（CRED-06：AccessTokenMaskFilter + LOGGING 配置 + 修改记录）✓ 2026-05-08（commits 891a5ea / 35eb110 / 7a9e511 / db4d5cf；端到端 9 truth × 32 项断言全 PASS）

## Progress

**执行顺序：**
Phase 按数值顺序执行：1 → 2 → 3（如出现紧急插入，记为 1.1 / 2.1 等）

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. 凭据槽位数据层 | 2/2 | ✓ Complete | 2026-05-07 |
| 2. 管理端读写接口 | 2/2 | ✓ Complete | 2026-05-07 |
| 3. 客户端读取与日志脱敏 | 2/2 | ✓ Complete | 2026-05-08 |

**Milestone v1.0 总进度：6/6 plans (100%) — 完结 ✓**

---

*生成时间：2026-05-07，Milestone v1.0「通用凭据槽位（APP ID + Access Token）」启动*
*最后更新：2026-05-08，Milestone v1.0 完结（CRED-01 至 CRED-06 全部交付）*