pmc
20036eeb2f
- 新增 SUMMARY.md：3 task / 3 commit / 32+42+26 行代码 / mask_token + CredentialSlot + 0004 迁移 - STATE.md：completed_plans 0→1（50%），下一步切到 Plan 01-02 - ROADMAP.md：Plan 01-01 勾选完成，进度表 1/2 In progress - REQUIREMENTS.md：CRED-01 勾选完成，traceability 状态 Pending→Done - 探针数据契约固化：DB pk=1 / access_token='probe_secret_xxxx' 留给 Plan 01-02 浏览器 checkpoint
74 lines
5.3 KiB
Markdown
74 lines
5.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 在数值序内夹在前后整数之间执行。
|
||
|
||
- [ ] **Phase 1: 凭据槽位数据层** — 落地 `CredentialSlot` 单例模型 + 迁移 + Django Admin 注册（脱敏 + 隐藏新增按钮）
|
||
- [ ] **Phase 2: 管理端读写接口** — 在 `/api/v1/admin/` 暴露凭据槽位 GET（脱敏）/ PUT（覆写）端点，admin token 鉴权
|
||
- [ ] **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）
|
||
- [ ] 01-02-PLAN.md — Django Admin 注册（脱敏/单例新增/禁删）+ 修改记录两条（CRED-02）
|
||
|
||
### 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**: TBD
|
||
|
||
### 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**: TBD
|
||
|
||
## Progress
|
||
|
||
**执行顺序：**
|
||
Phase 按数值顺序执行：1 → 2 → 3（如出现紧急插入，记为 1.1 / 2.1 等）
|
||
|
||
| Phase | Plans Complete | Status | Completed |
|
||
|-------|----------------|--------|-----------|
|
||
| 1. 凭据槽位数据层 | 1/2 | In progress（Plan 01-01 完成） | - |
|
||
| 2. 管理端读写接口 | 0/TBD | Not started | - |
|
||
| 3. 客户端读取与日志脱敏 | 0/TBD | Not started | - |
|
||
|
||
---
|
||
|
||
*生成时间：2026-05-07，Milestone v1.0「通用凭据槽位（APP ID + Access Token）」启动*
|