zyc/lty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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 待启动状态。
This commit is contained in:
pmc 2026-05-07 16:42:37 +08:00
parent 8ae12ca86c
commit 4637998420
3 changed files with 164 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
qy_lty/.planning/REQUIREMENTS.md
View File

@ -2,7 +2,7 @@
**初始化日期**: 2026-05-07 **初始化日期**: 2026-05-07
**类型**: Brownfield 文档化（从 `.planning/codebase/` 推断） **类型**: 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-01** Kimi 单轮 / 多轮文本对话
- [x] **AI-02** 多服务商语音抽象（火山 / 阿里云 NLS / 腾讯） - [x] **AI-02** 多服务商语音抽象（火山 / 阿里云 NLS / 腾讯）
- [x] **AI-03** TTS（文本→语音）+ ASR（语音→文本）通用接口 - [x] **AI-03** TTS（文本→语音）+ ASR(语音→文本) 通用接口
- [x] **AI-04** 字幕落库 + Bot 配置管理 - [x] **AI-04** 字幕落库 + Bot 配置管理
### 设备交互（DEV） ### 设备交互（DEV）
@ -132,10 +132,21 @@
## Traceability ## 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 回填*

71
qy_lty/.planning/ROADMAP.md Normal file
View File

@ -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）」启动*

112
qy_lty/.planning/STATE.md
View File

@ -1,6 +1,6 @@
# Project State — QY LTY Backend # 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}` 分组语义必须始终成立。 **核心价值**：设备端与手机端通过同一个 user_id 实时互通——`device_{user_id}` 分组语义必须始终成立。
**当前重点**：Milestone v1.0 通用凭据槽位（APP ID + Access Token）— 后端存储 + 管理端读写 + 客户端读取 + 脱敏 **当前重点**：Milestone v1.0 通用凭据槽位（APP ID + Access Token）— Phase 1「凭据槽位数据层」待启动
## 当前位置 ## 当前位置
``` ```
Phase: 未启动（定义需求中） Phase: 1 of 3（凭据槽位数据层）
Plan: — Plan: — of TBD
Status: 需求定义中（roadmap 待生成） Status: 待启动（ROADMAP.md 已生成，等待 /gsd-plan-phase 1 进入规划）
Last activity: 2026-05-07 — 启动 Milestone v1.0 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 项 | - 已完成 plan 数：0
| REQUIREMENTS.md | 🟡 Active 段待回填（CRED-01~06），可追溯性待 phase 回填 | - 平均耗时：—
| 路线图 | ⏸️ 待 gsd-roadmapper 生成 | - 总执行时间：—
| 当前 phase | — |
| 当前 milestone | v1.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 会： 进入 Phase 1「凭据槽位数据层」的规划环节，把 CRED-01 / CRED-02 拆为可执行 plan。
1. 询问 milestone 目标（例如：好感度系统 P2、安全加固、测试基础设施……）
2. 把需求加到 `.planning/REQUIREMENTS.md` 的 Active 段
3. 路由到 `/gsd-roadmap` 拆 phase
**候选优先级排序见 `REQUIREMENTS.md → Active → 候选优先级` 段**。
## 工作流配置 ## 工作流配置
详见 `.planning/config.json`： 详见 `.planning/config.json`：
- 模式：**YOLO**（自动通过审批，直接执行） - 模式：**YOLO**（自动通过审批）
- 粒度：**Coarse**（每个 milestone 拆 3-5 phase） - 粒度：**Coarse**（3-5 phase / milestone）
- 并行化：**已启用** - 并行化：**已启用**
- 工作流 agent：research / plan_check / verifier 全部启用 - workflow agent：research / plan_check / verifier 全部启用
- 模型档位：**balanced**（Sonnet 主力） - 模型档位：**balanced**
- `.planning/` 提交到 git：**是** - `.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 顶部「沟通语言」章节） 1. **沟通语言**：所有面向用户的回复使用中文
2. **修改记录**：每次代码 / 配置 / 迁移 / CI / Docker / 文档结构性改动 **必须**追加到 `docs/修改记录.md` 顶部（CLAUDE.md 「项目修改记录规则」章节） 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 更新*