zyc/lty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lty/qy_lty/.planning/REQUIREMENTS.md
pmc a58980fd73 docs(03-01): 完成 Phase 3 Plan 01 — CRED-05 客户端 GET 接口落地 
- 新增 03-01-SUMMARY.md：4.5 min × 3 task / 2 commit / 2 修改文件 / 6 truth × 15 断言全 PASS
- STATE.md 切到 Phase 3 In Progress（5/6 plan complete，83%），决策段累积 5 条 [Plan 03-01] 决策
- ROADMAP.md 更新 Phase 3 进度（1/2 plan complete）
- REQUIREMENTS.md 标记 CRED-05 → Done
- 3 处 deviations 全 auto-fixed（Rule 1 docstring 字面量误报 / Rule 3 Windows shell 行级 REPL / Rule 3 GBK 编码）；plan acceptance criteria 全部达成

Hand-off to Plan 03-02：DB 探针态保持 / _phase3_01_verify.py 留仓库根待删除 / 不写 docs/修改记录.md（由 03-02 Task 4 一并写）
2026-05-08 10:20:13 +08:00

7.8 KiB
Raw Blame History

Requirements — QY LTY Backend

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

Validated（已交付能力）

以下需求均为 2026-05-07 之前已上线 的能力，从代码与 docs/ 推断而来。任何修改都需要走完整 phase 流程，不要直接动。

用户与认证（AUTH）

  • AUTH-01 自定义用户模型 ParadiseUser（继承 AbstractUser，含画像字段）
  • AUTH-02 Redis 后端 token 认证（30 天 TTL）
  • AUTH-03 手机号 + 阿里云 SMS 验证码登录
  • AUTH-04 WeChat OAuth（django-allauth + Weixin provider）
  • AUTH-05 设备端 MAC 换 user-token（POST /api/user/mac-login/）

AI 对话与语音（AI）

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

设备交互（DEV）

  • DEV-01 双通道 WebSocket（Header 鉴权 + URL 鉴权）
  • DEV-02 Channel Layer 分组 device_{user_id}
  • DEV-03 设备绑定 / 解绑 / 设主 / 状态查询 REST 接口
  • DEV-04 Redis 心跳（device:last_seen:{mac}，5 min TTL）
  • DEV-05 设备 connected/disconnected 状态写库
  • DEV-06 "后绑挤先绑"控制权语义
  • DEV-07 火山引擎 RTC token 签发（room_{user_id}）
  • DEV-08 11 种 WebSocket message type 完整支持（chat/weather/sing/dance/touch/flow_light/device_info/device_state/conversation_status/conversation_subtitle/factory_reset）

卡片系统（CARD）

  • CARD-01 卡片分类 + 属性配置
  • CARD-02 批量生成 + 二维码
  • CARD-03 使用追踪 + 数据分析

成就（ACH）

  • ACH-01 成就定义 + 稀有度等级 + 用户进度
  • ACH-02 成就解锁条件校验 — ⚠️ TODO 占位，achievement_app/views.py:139 未实现；任意客户端可主张任意成就。需要单独 phase 修复。

订阅（SUB）

  • SUB-01 用户订阅模型 + 状态管理
  • SUB-02 APScheduler 定时任务

好感度系统（AFF，2026-04 P1）

  • AFF-01 设备级好感度计数（UserDevice.favorability）
  • AFF-02 6 张配套表（Rule/Level/Log/Counter/Setting/RewardClaim）
  • AFF-03 配置驱动规则（区间随机 / 上限 / 冷却 / 等级奖励）
  • AFF-04 Service 层（P2）— 未交付，下个 milestone
  • AFF-05 接口层（P3）— 未交付，下个 milestone
  • AFF-06 客户端集成（P4）— 未交付，下个 milestone

视觉智能（VI）

  • VI-01 阿里云人脸检测 / 识别（ali_vi_app）

通用基础设施（INF）

  • INF-01 StandardResponseMiddleware 统一响应包装
  • INF-02 CustomPageNumberPagination 自定义分页
  • INF-03 Aliyun OSS 上传抽象
  • INF-04 Aliyun Log Service 生产日志
  • INF-05 Swagger / ReDoc API 文档（drf-yasg）

管理后台（ADM）

  • ADM-01 Django Admin（SimpleUI 主题，中英双语）
  • ADM-02 /api/v1/admin/ REST 命名空间

部署（DEP）

  • DEP-01 Docker + docker-compose（端口 12012）
  • DEP-02 Daphne ASGI（HTTP + WebSocket 同进程）
  • DEP-03 PostgreSQL + Redis 双依赖
  • DEP-04 i18n 双语（zh_HAns / en）

Active（当前 milestone 目标）

Milestone v1.0：通用凭据槽位（APP ID + Access Token） 启动日期：2026-05-07 目标：后端提供全局单例凭据存储；管理端可读写；手机端 + 设备端可读取。

通用凭据槽位（CRED）

  • CRED-01 单例 CredentialSlot Django 模型 + 迁移；DB 层强制最多一条记录（pk=1 固定主键或单字段唯一约束）；含 app_id、access_token、updated_at 字段 ✓ Plan 01-01 完成（2026-05-07，commits a9c25eb / 30c7caf / a475fe4）
  • CRED-02 Django Admin 注册：列表态/查看态对 access_token 字段脱敏；新增/编辑态可见明文（运营录入需要）；隐藏"新增"按钮（强制单例语义） ✓ Plan 01-02 完成（2026-05-07，commit 653f057；Task 2 由 orchestrator Django test client 程序化验收 10/10 PASS）
  • CRED-03 管理端 GET /api/v1/admin/credential-slot/：admin token 鉴权（admin_token:{token} Redis key 体系）；返回 { app_id, access_token: <masked>, updated_at }，Access Token 仅返回末 4 位脱敏掩码
  • CRED-04 管理端 PUT /api/v1/admin/credential-slot/：admin token 鉴权；接受 { app_id, access_token } 全字段覆写更新；空记录场景自动 get_or_create；变更写入 updated_at
  • CRED-05 客户端 GET /api/credential-slot/：user token 鉴权（token:{token} Redis key 体系，复用 RedisTokenAuthentication）；明文返回 { app_id, access_token, updated_at }（手机端 / 设备端实际调用第三方服务需要）
  • CRED-06 Access Token 日志过滤：阿里云日志格式化器 / 自定义日志过滤器中识别 access_token 字段并脱敏，覆盖 PUT 请求体、admin GET 响应体两条最易泄露路径

候选优先级（已转移自 brownfield 文档化阶段，本期不消化）

下面是从 CONCERNS.md 转过来的潜在 milestone 候选，本期 v1.0 不处理，留作下一周期参考：

  1. HIGH 修复 ACH-02 成就条件校验缺失 — 当前任意客户端可主张任意成就
  2. HIGH 修复 SMS 验证码无频率限制 — 生产 DoS 向量
  3. HIGH 收紧 DEBUG / CORS_ALLOW_ALL_ORIGINS 默认值 — 信息泄露 + CSRF 邻接风险
  4. HIGH 移除测试 MAC AA:BB:CC:DD:EE:FF 硬编码绑定绕过
  5. HIGH 测试基础设施搭建（pytest + pytest-django + 关键路径测试）
  6. MEDIUM 完成好感度系统 P2/P3/P4（Service 层 + 接口层 + 客户端集成）
  7. MEDIUM Python 3.8 → 3.11/3.12 升级
  8. MEDIUM WebSocket URL token 鉴权废弃（防 access log 泄露）
  9. MEDIUM 拆分 device_interaction/views.py（1867 行单文件）

Out of Scope

（理由详见 PROJECT.md，此处不重复）

  • 管理后台前端 — 在 ../qy-lty-admin/ 独立项目
  • Unity 客户端业务逻辑 — 在 LTY_App_Project_URP / LTY_Project 独立项目
  • APM / 全链路追踪 — 暂不引入
  • 多 Redis 实例 / Sentinel — 暂不上 HA
  • 跨项目混合修改记录 — 各自维护

Traceability

Milestone v1.0 通用凭据槽位（2026-05-07 ROADMAP 落地）

Requirement Phase Status
CRED-01 单例 CredentialSlot 模型 + 迁移 Phase 1 凭据槽位数据层 Done（Plan 01-01，2026-05-07）
CRED-02 Django Admin 注册（脱敏 + 隐藏新增按钮） Phase 1 凭据槽位数据层 Done（Plan 01-02，2026-05-07）
CRED-03 管理端 GET（admin token，脱敏返回） Phase 2 管理端读写接口 Done（Plan 02-01 + 02-02，2026-05-07）
CRED-04 管理端 PUT（admin token，全字段覆写 + get_or_create） Phase 2 管理端读写接口 Done（Plan 02-01 + 02-02，2026-05-07）
CRED-05 客户端 GET（user token，明文返回） Phase 3 客户端读取与日志脱敏 Pending
CRED-06 Access Token 阿里云日志过滤 Phase 3 客户端读取与日志脱敏 Pending

覆盖率：6/6 Active 需求映射到 Phase ✓（无孤儿，无重复）

Last updated: 2026-05-07 — Phase 2 完成（Plan 02-01 + Plan 02-02 全部交付，CRED-03 / CRED-04 标记 Done）；下一步启动 Phase 3 规划（CRED-05 客户端 GET 明文 + CRED-06 阿里云日志脱敏）