lty/qy_lty/.planning/ROADMAP.md

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 注册（脱敏 + 隐藏新增按钮）✓ 2026-05-07 完成（Plan 01-01 + 01-02）
• 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

• 01-01-PLAN.md — 凭据槽位单例模型 + 迁移 + mask_token 工具（CRED-01）✓ 2026-05-07 完成（commits a9c25eb / 30c7caf / a475fe4）
• 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

• 02-01-PLAN.md — CredentialSlot serializer + view（GET 脱敏 / PUT 覆写 + admin 二次校验）+ admin_urls 路由注册（CRED-03 + CRED-04）
• 02-02-PLAN.md — 端到端 curl + Django shell 验收 8 条 success criteria + qy_lty / qy-lty-admin 两端修改记录互引（CRED-03 + CRED-04）

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. 凭据槽位数据层	2/2	✓ Complete	2026-05-07
2. 管理端读写接口	0/2	Planned	-
3. 客户端读取与日志脱敏	0/TBD	Not started	-

---

生成时间：2026-05-07，Milestone v1.0「通用凭据槽位（APP ID + Access Token）」启动