pmc
a58980fd73
- 新增 03-01-SUMMARY.md：4.5 min × 3 task / 2 commit / 2 修改文件 / 6 truth × 15 断言全 PASS - STATE.md 切到 Phase 3 In Progress（5/6 plan complete，83%），决策段累积 5 条 [Plan 03-01] 决策 - ROADMAP.md 更新 Phase 3 进度（1/2 plan complete） - REQUIREMENTS.md 标记 CRED-05 → Done - 3 处 deviations 全 auto-fixed（Rule 1 docstring 字面量误报 / Rule 3 Windows shell 行级 REPL / Rule 3 GBK 编码）；plan acceptance criteria 全部达成 Hand-off to Plan 03-02：DB 探针态保持 / _phase3_01_verify.py 留仓库根待删除 / 不写 docs/修改记录.md（由 03-02 Task 4 一并写）
78 lines
6.3 KiB
Markdown
78 lines
6.3 KiB
Markdown
# 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）
|
||
|
||
## 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）
|
||
- [ ] **Phase 3: 客户端读取与日志脱敏** — 在 `/api/credential-slot/` 暴露明文读取端点（user token 鉴权），并在阿里云日志链路过滤 `access_token`
|
||
|
||
## 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/ 路由注册）
|
||
- [ ] 03-02-PLAN.md — 阿里云日志 access_token 脱敏（CRED-06：AccessTokenMaskFilter + LOGGING 配置 + 修改记录）
|
||
|
||
## 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. 客户端读取与日志脱敏 | 0/2 | Not started | - |
|
||
|
||
---
|
||
|
||
*生成时间：2026-05-07，Milestone v1.0「通用凭据槽位（APP ID + Access Token）」启动*
|