docs(qy_lty): 生成 Milestone v1.0 ROADMAP（3 个 phase）

3 个串行 phase（粒度 coarse）： 1. 凭据槽位数据层（CRED-01, CRED-02）— DB 单例 + Django Admin 2. 管理端读写接口（CRED-03, CRED-04）— /api/v1/admin/credential-slot/ GET+PUT 3. 客户端读取与日志脱敏（CRED-05, CRED-06）— /api/credential-slot/ 明文 GET + 阿里云日志过滤 REQUIREMENTS.md Traceability 段回填 6/6 映射；STATE.md 切到 Phase 1 待启动状态。
2026-05-07 16:42:37 +08:00 · 2026-05-07 16:42:37 +08:00 · 4637998420
commit 4637998420
parent 8ae12ca86c
3 changed files with 164 additions and 40 deletions
--- a/qy_lty/.planning/REQUIREMENTS.md
+++ b/qy_lty/.planning/REQUIREMENTS.md
@ -2,7 +2,7 @@

 **初始化日期**: 2026-05-07
 **类型**: Brownfield 文档化（从 `.planning/codebase/` 推断）
-**状态**: 已落地能力归档完成；Active milestone 待 `/gsd-new-milestone` 启动
+**状态**: 已落地能力归档完成；Milestone v1.0「通用凭据槽位」已生成 ROADMAP.md（3 个 phase）

 ---

@ -22,7 +22,7 @@

 - [x] **AI-01** Kimi 单轮 / 多轮文本对话
 - [x] **AI-02** 多服务商语音抽象（火山 / 阿里云 NLS / 腾讯）
- [x] **AI-03** TTS（文本→语音）+ ASR（语音→文本）通用接口
+- [x] **AI-03** TTS（文本→语音）+ ASR(语音→文本) 通用接口
 - [x] **AI-04** 字幕落库 + Bot 配置管理

 ### 设备交互（DEV）
@ -132,10 +132,21 @@

 ## Traceability

-<!-- 由 /gsd-plan-phase 在生成 phase 时回填：每个 phase 解决哪些 REQ-ID -->
+<!-- 由 /gsd-roadmap 在生成 ROADMAP 时回填；后续 /gsd-plan-phase 可继续细化到 plan 粒度 -->

-（暂无 phase；待 `/gsd-new-milestone` 后启动）
+### Milestone v1.0 通用凭据槽位（2026-05-07 ROADMAP 落地）
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| CRED-01 单例 `CredentialSlot` 模型 + 迁移 | Phase 1 凭据槽位数据层 | Pending |
+| CRED-02 Django Admin 注册（脱敏 + 隐藏新增按钮） | Phase 1 凭据槽位数据层 | Pending |
+| CRED-03 管理端 GET（admin token，脱敏返回） | Phase 2 管理端读写接口 | Pending |
+| CRED-04 管理端 PUT（admin token，全字段覆写 + get_or_create） | Phase 2 管理端读写接口 | Pending |
+| CRED-05 客户端 GET（user token，明文返回） | Phase 3 客户端读取与日志脱敏 | Pending |
+| CRED-06 Access Token 阿里云日志过滤 | Phase 3 客户端读取与日志脱敏 | Pending |
+
+**覆盖率**：6/6 Active 需求映射到 Phase ✓（无孤儿，无重复）

 ---

-*Last updated: 2026-05-07 启动 Milestone v1.0「通用凭据槽位」*
+*Last updated: 2026-05-07 — Milestone v1.0「通用凭据槽位」ROADMAP 生成，Traceability 回填*
--- a/qy_lty/.planning/ROADMAP.md
+++ b/qy_lty/.planning/ROADMAP.md
@ -0,0 +1,71 @@
+# 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**: TBD
+
+### 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. 凭据槽位数据层 | 0/TBD | Not started | - |
+| 2. 管理端读写接口 | 0/TBD | Not started | - |
+| 3. 客户端读取与日志脱敏 | 0/TBD | Not started | - |
+
+---
+
+*生成时间：2026-05-07，Milestone v1.0「通用凭据槽位（APP ID + Access Token）」启动*
--- a/qy_lty/.planning/STATE.md
+++ b/qy_lty/.planning/STATE.md
@ -1,6 +1,6 @@
 # Project State — QY LTY Backend

-**最后更新**: 2026-05-07（启动 Milestone v1.0 通用凭据槽位）
+**最后更新**: 2026-05-07（ROADMAP.md 已生成，Milestone v1.0 待启动 Phase 1）

 ## 项目引用

@ -8,69 +8,111 @@

 **核心价值**：设备端与手机端通过同一个 user_id 实时互通——`device_{user_id}` 分组语义必须始终成立。

-**当前重点**：Milestone v1.0 通用凭据槽位（APP ID + Access Token）— 后端存储 + 管理端读写 + 客户端读取 + 脱敏
+**当前重点**：Milestone v1.0 通用凭据槽位（APP ID + Access Token）— Phase 1「凭据槽位数据层」待启动

 ## 当前位置

 ```
-Phase: 未启动（定义需求中）
-Plan: —
-Status: 需求定义中（roadmap 待生成）
-Last activity: 2026-05-07 — 启动 Milestone v1.0
+Phase: 1 of 3（凭据槽位数据层）
+Plan: — of TBD
+Status: 待启动（ROADMAP.md 已生成，等待 /gsd-plan-phase 1 进入规划）
+Last activity: 2026-05-07 — 生成 ROADMAP.md，Milestone v1.0 三个 phase 已落地
 ```

-## 状态
+Progress: [░░░░░░░░░░] 0%

-| 项目 | 状态 |
-|------|------|
-| 代码库映射 | ✅ `.planning/codebase/` 7 文档（commit `64a8cb8`） |
-| PROJECT.md | ✅ 已加入 Milestone v1.0 段 + Active 6 项 |
-| REQUIREMENTS.md | 🟡 Active 段待回填（CRED-01~06），可追溯性待 phase 回填 |
-| 路线图 | ⏸️ 待 gsd-roadmapper 生成 |
-| 当前 phase | — |
-| 当前 milestone | v1.0 通用凭据槽位 |
+## 性能指标
+
+**速度：**
+- 已完成 plan 数：0
+- 平均耗时：—
+- 总执行时间：—
+
+**按 Phase：**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| — | — | — | — |
+
+**最近趋势：**
+- 最近 5 个 plan：—
+- 趋势：—
+
+*每完成一个 plan 后更新*
+
+## 累积上下文
+
+### 决策
+
+完整决策日志见 PROJECT.md「关键决策」表。
+当前 milestone 相关决策：
+
+- 凭据槽位以 `pk=1 + get_or_create` 模式落地单例语义（PROJECT.md「关键约束」段）
+- 客户端 GET 接口必须返回**明文** Access Token（手机端/设备端实际调用第三方需要），仅管理端 GET 与日志做脱敏
+
+### Pending Todos
+
+无（`.planning/todos/pending/` 暂无条目）
+
+### Blockers/Concerns
+
+无
+
+## Deferred Items
+
+从 brownfield 文档化阶段沉淀的候选优先级（详见 REQUIREMENTS.md → Active → 候选优先级），本期 v1.0 不消化：
+
+| 类别 | 条目 | 状态 | 沉淀于 |
+|------|------|------|--------|
+| HIGH | ACH-02 成就解锁条件校验缺失 | 候选 | 2026-05-07 brownfield |
+| HIGH | SMS 验证码无频率限制 | 候选 | 2026-05-07 brownfield |
+| HIGH | 收紧 DEBUG / CORS_ALLOW_ALL_ORIGINS 默认值 | 候选 | 2026-05-07 brownfield |
+| HIGH | 移除测试 MAC `AA:BB:CC:DD:EE:FF` 硬编码 | 候选 | 2026-05-07 brownfield |
+| HIGH | 测试基础设施搭建（pytest 体系） | 候选 | 2026-05-07 brownfield |
+| MEDIUM | 好感度 P2/P3/P4（Service / 接口 / 客户端集成） | 候选 | 2026-05-07 brownfield |
+| MEDIUM | Python 3.8 → 3.11/3.12 升级 | 候选 | 2026-05-07 brownfield |
+| MEDIUM | 拆分 device_interaction/views.py（1867 行） | 候选 | 2026-05-07 brownfield |

 ## 下一步

-**当你准备开始下一个开发周期**：
-
 ```
-/gsd-new-milestone
+/gsd-plan-phase 1
 ```

-GSD 会：
-1. 询问 milestone 目标（例如：好感度系统 P2、安全加固、测试基础设施……）
-2. 把需求加到 `.planning/REQUIREMENTS.md` 的 Active 段
-3. 路由到 `/gsd-roadmap` 拆 phase
-
-**候选优先级排序见 `REQUIREMENTS.md → Active → 候选优先级` 段**。
+进入 Phase 1「凭据槽位数据层」的规划环节，把 CRED-01 / CRED-02 拆为可执行 plan。

 ## 工作流配置

 详见 `.planning/config.json`：

- 模式：**YOLO**（自动通过审批，直接执行）
- 粒度：**Coarse**（每个 milestone 拆 3-5 phase）
+- 模式：**YOLO**（自动通过审批）
+- 粒度：**Coarse**（3-5 phase / milestone）
 - 并行化：**已启用**
- 工作流 agent：research / plan_check / verifier 全部启用
- 模型档位：**balanced**（Sonnet 主力）
+- workflow agent：research / plan_check / verifier 全部启用
+- 模型档位：**balanced**
 - `.planning/` 提交到 git：**是**

-随时可用 `/gsd-settings` 调整。
+`/gsd-settings` 可调整。

 ## 锚定路径重要说明

-`.planning/` 必须保持在 `c:\Users\admin\Desktop\Lila-Server\qy_lty\` 这一层（**不是父级 `Lila-Server\`**）。父级 `.git` 容易让 GSD CLI 误把 `Lila-Server` 当作 project_root；本目录的存在就是锚定信号，不要删。
+`.planning/` 必须保持在 `c:\Users\admin\Desktop\Lila-Server\qy_lty\` 这一层（**不是**父级 `Lila-Server\`）。父级 `.git` 容易让 GSD 误把 `Lila-Server` 当作 project_root；本目录的存在就是锚定信号。

 ## 项目规则提醒

-CLAUDE.md 中两条强制规则，做任何 phase 时必须遵守：
+CLAUDE.md 两条强制规则（任何 phase 都必须遵守）：

-1. **沟通语言**：所有面向用户的回复使用中文（CLAUDE.md 顶部「沟通语言」章节）
-2. **修改记录**：每次代码 / 配置 / 迁移 / CI / Docker / 文档结构性改动 **必须**追加到 `docs/修改记录.md` 顶部（CLAUDE.md 「项目修改记录规则」章节）
+1. **沟通语言**：所有面向用户的回复使用中文
+2. **修改记录**：每次代码 / 配置 / 迁移 / CI / Docker / 文档结构性改动**必须**追加到 `docs/修改记录.md` 顶部

-`qy_lty` 与 `qy-lty-admin` 是独立项目，修改记录互不混合，跨项目联动两端各写一条。
+`qy_lty` 与 `qy-lty-admin` 是独立项目，修改记录互不混合。
+
+## Session Continuity
+
+Last session: 2026-05-07
+Stopped at: ROADMAP.md / STATE.md / REQUIREMENTS.md traceability 三文件落地，Phase 1 待启动
+Resume file: None（直接 `/gsd-plan-phase 1` 即可）

 ---

-*由 /gsd-new-project（brownfield 文档化）生成于 2026-05-07*
+*由 /gsd-roadmap 于 2026-05-07 更新*