From 4637998420b474aa69c3b0412ba133ab88870f5a Mon Sep 17 00:00:00 2001 From: pmc <740076875@qq.com> Date: Thu, 7 May 2026 16:42:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(qy=5Flty):=20=E7=94=9F=E6=88=90=20Mileston?= =?UTF-8?q?e=20v1.0=20ROADMAP=EF=BC=883=20=E4=B8=AA=20phase=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 待启动状态。 --- qy_lty/.planning/REQUIREMENTS.md | 21 ++++-- qy_lty/.planning/ROADMAP.md | 71 ++++++++++++++++++++ qy_lty/.planning/STATE.md | 112 +++++++++++++++++++++---------- 3 files changed, 164 insertions(+), 40 deletions(-) create mode 100644 qy_lty/.planning/ROADMAP.md diff --git a/qy_lty/.planning/REQUIREMENTS.md b/qy_lty/.planning/REQUIREMENTS.md index c35d74e..b218119 100644 --- 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 - + -（暂无 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 回填* diff --git a/qy_lty/.planning/ROADMAP.md b/qy_lty/.planning/ROADMAP.md new file mode 100644 index 0000000..04319a0 --- /dev/null +++ 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: , 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）」启动* diff --git a/qy_lty/.planning/STATE.md b/qy_lty/.planning/STATE.md index 741542a..3e0e64d 100644 --- 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 更新*