lty/qy_lty/.planning/REQUIREMENTS.md

Requirements — QY LTY Backend

初始化日期: 2026-05-07 类型: Brownfield 文档化（从 .planning/codebase/ 推断） 状态: 已落地能力归档完成；Active milestone 待 /gsd-new-milestone 启动

---

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 目标）

（暂无）

本次 /gsd-new-project 是 brownfield 文档化，没有指定新 milestone。

下一次启动新功能开发时，请用：

/gsd-new-milestone

GSD 会引导你确认 milestone 目标、把新需求加到本段（带 REQ-ID），然后 /gsd-plan-phase 拆 phase。

候选优先级（来自 CONCERNS.md 与项目活动信号，按风险/价值排序，仅供参考）：

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

（暂无 phase；待 /gsd-new-milestone 后启动）

---

Last updated: 2026-05-07 after brownfield documentation pass