# Requirements — QY LTY Backend

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

---

## Validated（已交付能力）

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

### 用户与认证（AUTH）

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

### AI 对话与语音（AI）

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

### 设备交互（DEV）

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

### 卡片系统（CARD）

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

### 成就（ACH）

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

### 订阅（SUB）

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

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

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

### 视觉智能（VI）

- [x] **VI-01** 阿里云人脸检测 / 识别（`ali_vi_app`）

### 通用基础设施（INF）

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

### 管理后台（ADM）

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

### 部署（DEP）

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

---

## Active（当前 milestone 目标）

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

### 通用凭据槽位（CRED）

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

### 候选优先级（已转移自 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

<!-- 由 /gsd-roadmap 在生成 ROADMAP 时回填；后续 /gsd-plan-phase 可继续细化到 plan 粒度 -->

### 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 客户端读取与日志脱敏 | Done（Plan 03-01，2026-05-08） |
| CRED-06 Access Token 阿里云日志过滤 | Phase 3 客户端读取与日志脱敏 | Done（Plan 03-02，2026-05-08） |

**覆盖率**：6/6 Active 需求映射到 Phase ✓（无孤儿，无重复）；**6/6 全部 Done — Milestone v1.0 完结**

---

*Last updated: 2026-05-08 — Phase 3 完成（Plan 03-01 + Plan 03-02 全部交付，CRED-05 / CRED-06 标记 Done）；Milestone v1.0「通用凭据槽位（APP ID + Access Token）」CRED-01 至 CRED-06 全部交付；下一周期 milestone 候选评估见上方「候选优先级」段*