# 暖记下一步工作路线图

> **创建日期**: 2026-06-07
> **状态**: 讨论稿，待确认优先级后逐一推进
> **当前代码状态**: 工作区 26 个文件 +1051/-319 行未提交

---

## 当前快照

| 指标 | 数值 |
|------|------|
| 后端测试 | 518 通过 |
| 前端测试 | 116 新增 (Phase 4) |
| 审计发现 | 345 项 (42 C / 90 H / 123 M / 90 L) |
| 未提交改动 | Discover 全栈 + 编辑器增强 + 多页动态化 |
| 未提交新文件 | discover_bloc / discover_models / discover_handler / discover_service |

---

## 方向 A — 当前改动收尾提交

> **目标**: 把工作区 1000+ 行改动拆分成有意义的提交，保持 git 历史清晰
> **预估**: 2-3h（拆分 + 验证 + 提交）
> **优先级**: ⭐⭐⭐⭐⭐ — 做任何事之前先把当前工作落地

### A.1 提交拆分建议

| # | 提交内容 | 涉及文件 | scope |
|---|---------|---------|-------|
| 1 | Discover 后端 (DTO + Service + Handler + 路由注册) | crates/erp-diary 4 文件 + main.rs | `feat(diary)` |
| 2 | Discover 前端 (BLoC + Models + Page 动态化) | app/features/discover/ 4 文件 | `feat(app)` |
| 3 | 编辑器: 查看模式 + 图层排序 | editor_page + editor_bloc + draggable_element | `feat(app)` |
| 4 | 编辑器: 标签面板动态化 + 贴纸选择器重构 | tag_panel + sticker_picker_sheet | `feat(app)` |
| 5 | 搜索页动态化 (热搜词 + 模板搜索) | search_page | `feat(app)` |
| 6 | 个人资料页动态化 (成就徽章 + 头像首字母) | profile_page | `feat(app)` |
| 7 | 教师页班级码对话框 | teacher_page | `feat(app)` |
| 8 | 贴纸库动态分类 | sticker_library_page | `feat(app)` |
| 9 | Wiki 文档更新 | wiki/ 4 文件 | `docs` |

### A.2 验证清单

- [ ] `cargo check` 后端编译通过
- [ ] `cargo test` 后端测试通过
- [ ] `flutter analyze` 前端分析通过
- [ ] 每个提交可独立编译

### A.3 讨论点

- Discover 功能是否属于 Phase 1 范围？审计报告 7b-H06 指出它属于 Phase 2
- 编辑器查看模式是新增功能还是修复？影响提交类型选择 (feat vs fix)

---

## 方向 B — 审计修复路线图推进

> **目标**: 按审计报告 345 项发现的修复路线图推进
> **预估**: Phase 0 已完成 ~80%，Phase 1-3 待推进
> **优先级**: ⭐⭐⭐⭐ — 安全和稳定性是上线的前提

### B.1 Phase 0 紧急修复 — 已完成项 ✅

| # | 修复项 | 状态 |
|---|--------|------|
| 1 | RLS 变量名 bug 修复 | ✅ 已修复 |
| 2 | 内容安全词库填充 + 分享前检查 | ✅ 已修复 |
| 3 | 日记列表 IDOR 修复 | 需确认 |
| 4 | 审计日志 + 文件上传权限守卫 | 需确认 |
| 5 | class_service unwrap() 安全处理 | 需确认 |
| 6 | 事务添加 (create_class/join_class) | 需确认 |
| 7 | 笔画缓存 use-after-dispose 修复 | ✅ 已修复 |

### B.2 Phase 1 安全加固 (~31h)

| # | 任务 | 预估 | 讨论点 |
|---|------|------|--------|
| 1 | 家长同意验证流程 | 8h | PIPL 合规法律要求，但 Phase 1 MVP 是否先跳过？ |
| 2 | 家长绑定验证流程 | 4h | 同上 |
| 3 | Token 黑名单改用 SHA-256 | 1h | 简单，可顺手做 |
| 4 | **全部 DTO 添加 Validate + handler 调用** | 8h | 影响面最大，系统性修复 |
| 5 | Flutter 强制 HTTPS + 证书固定 | 4h | 开发阶段 HTTP 方便调试，生产再强制？ |
| 6 | 班级码改用字母数字混合 | 2h | 安全强度提升 3386 倍 |
| 7 | Flutter Token 自动刷新 | 4h | 体验提升明显 |

### B.3 Phase 2 性能优化 (~24h)

| # | 任务 | 预估 |
|---|------|------|
| 1 | 后端 4 个 N+1 查询修复 | 8h |
| 2 | Isar 索引 + 分页 + N+1 修复 | 6h |
| 3 | mood_stats 改用 SQL GROUP BY | 2h |
| 4 | 笔画光栅化改为 BBox 裁剪 (50 条笔画 1.6GB → 合理范围) | 4h |
| 5 | SyncEngine 合并同资源操作 | 4h |

### B.4 Phase 3 质量提升 (持续)

| # | 任务 |
|---|------|
| 1 | 补充后端集成测试 + Flutter BLoC 测试 |
| 2 | 统一同步协议 (Flutter ↔ Rust) |
| 3 | 创建端点改返回 201 |
| 4 | 添加 DiaryApiDoc OpenAPI 文档 |
| 5 | 无障碍性 Semantics |
| 6 | DiaryEvent 枚举接入 EventBus |

### B.5 讨论点

- Phase 1 的家长验证流程比较重，MVP 阶段是否可以用简化版（注册时勾选确认代替完整验证链）？
- 性能优化在数据量小的时候感知不明显，是否延后到真实用户测试时再做？
- 同步协议断裂是最严重的架构问题，但也是改动量最大的——何时投入？

---

## 方向 C — 端到端联调

> **目标**: 确保 Flutter → Rust API 全链路数据流通
> **预估**: 8-16h
> **优先级**: ⭐⭐⭐⭐ — 不联调就不知道能不能跑

### C.1 核心联调路径

| # | 链路 | 前端模块 | 后端 API | 状态 |
|---|------|---------|---------|------|
| 1 | **注册 → 登录 → Token 获取** | AuthBloc | POST /auth/* | ✅ 通过 |
| 2 | **创建日记 → 保存到后端** | EditorBloc → JournalRepository | POST /diary/journals | ✅ 通过 |
| 3 | **日记列表加载** | HomeBloc | GET /diary/journals | ✅ 通过 |
| 4 | **班级创建 → 加入 → 查看成员** | ClassBloc | POST/GET /diary/classes/* | ✅ 通过 |
| 5 | **贴纸浏览 → 收藏** | StickerBloc | GET /diary/stickers/* | ✅ 通过 (空) |
| 6 | **发现页数据加载** | DiscoverBloc | GET /diary/discover | ✅ 通过 |
| 7 | **搜索日记/模板** | SearchBloc | GET /diary/journals?search= | ✅ 通过 |
| 8 | **心情统计** | CalendarBloc | GET /diary/stats/mood | ✅ 通过 |
| 9 | **同步 (离线→在线)** | SyncEngine | POST /diary/sync | ❌ 协议断裂 |

### C.1b DTO 验证生效确认

| 测试 | 结果 |
|------|------|
| 负版本号 `version: -1` | ✅ 拒绝: "版本号不能为负数" |
| 标签过长 (50+ chars) | ✅ 拒绝: "超过 30 字符" |
| 班级码非字母数字 `!!!!!!` | ✅ 拒绝: "仅允许字母和数字" |
| 贴纸包负价格 `price: -100` | ✅ 拒绝: "价格不能为负数" |
| 评语创建 (admin 角色) | ✅ 正确返回 403 (仅 teacher) |

### C.2 联调方式讨论

**方案 A — 手动联调（快速验证）**
- 启动后端 + Flutter Web
- 手动走一遍核心流程
- 用 Chrome DevTools 看 Network 请求
- 优点：快速、直观
- 缺点：不可复现、覆盖不全

**方案 B — 自动化集成测试（推荐）**
- 后端：已有 9 个集成测试，扩展到覆盖所有 API
- 前端：用 integration_test 包写 Flutter 集成测试
- 优点：可复现、持续验证
- 缺点：前期投入大

**方案 C — Postman/HTTP 请求集**
- 先用 Postman 验证所有后端 API
- 再手动跑 Flutter 前端
- 折中方案

### C.3 讨论点

- 同步功能 (链路 9) 已知断裂，联调时是否先跳过？
- 先做后端 API 验证还是直接跑 Flutter？
- 是否需要准备测试数据种子？

---

## 方向 D — 产品体验打磨

> **目标**: 从小学生用户视角出发，打磨交互体验
> **预估**: 持续迭代
> **优先级**: ⭐⭐⭐ — 功能能跑之后的首要任务

### D.1 体验问题清单

| # | 问题 | 严重性 | 讨论点 |
|---|------|--------|--------|
| 1 | **首次使用引导** — 新用户打开 app 不知道干什么 | HIGH | 需要设计引导流程 |
| 2 | **空状态设计** — 列表为空时显示什么？ | MEDIUM | 需要插画/文案 |
| 3 | **加载状态** — 骨架屏 vs 转圈 vs 进度条？ | MEDIUM | 统一 Loading 策略 |
| 4 | **错误提示** — 网络错误/服务器错误/离线 如何提示？ | HIGH | 儿童友好的错误文案 |
| 5 | **手写反馈** — 写字时有声音/动画反馈吗？ | LOW | 增强沉浸感 |
| 6 | **心情追踪可视化** — fl_chart 集成够好看吗？ | MEDIUM | 需要实际渲染验证 |
| 7 | **成就/徽章系统** — 有雏形但完整吗？ | MEDIUM | 当前只有数据模型 |
| 8 | **贴纸交互** — 拖拽/缩放/旋转手感如何？ | HIGH | 核心体验 |
| 9 | **日历视图** — 月历和日记的关联够直观吗？ | MEDIUM | |
| 10 | **班级动态** — 老师点评 → 学生能看到吗？ | HIGH | 核心社交功能 |

### D.2 可能的新功能想法

| # | 想法 | 复杂度 | 讨论点 |
|---|------|--------|--------|
| 1 | **每日写作提示** — "今天你吃了什么好吃的？" | 低 | 已有 Discover daily_inspiration，可扩展 |
| 2 | **天气/心情自动检测** — 根据文字内容建议心情标签 | 中 | 需要 NLP 或关键词匹配 |
| 3 | **日记模板市场** — 下载别人分享的日记模板 | 高 | Phase 2 功能？ |
| 4 | **语音输入** — 口述转文字辅助写作 | 高 | 技术选型待定 |
| 5 | **涂鸦动画回放** — 把绘画过程做成短视频 | 中 | 技术上可行 (已有时间戳数据) |
| 6 | **多页日记** — 一篇日记可以有很多页 | 中 | 编辑器需要支持翻页 |
| 7 | **日记封面** — 自动/手动生成好看的封面 | 低 | 取日记第一张图或涂鸦 |
| 8 | **分享到班级圈** — 类似朋友圈的班级动态流 | 高 | Phase 2 功能？ |

### D.3 讨论点

- 哪些体验问题必须在 MVP 之前解决？
- 新功能想法中哪些值得现在就开始探索？
- 是否需要做一轮真实的用户测试（找几个小学生试用）？

---

## 方向 E — 上线准备 / DevOps

> **目标**: 从开发环境走向可发布的 App
> **预估**: 20-40h (取决于目标平台)
> **优先级**: ⭐⭐ — 功能稳定后再做

### E.1 短期目标：可内测的 APK

| # | 任务 | 预估 | 状态 |
|---|------|------|------|
| 1 | Flutter Android 构建 + 签名 | 4h | 未开始 |
| 2 | 生产环境配置 (HTTPS, 密钥管理) | 4h | 未开始 |
| 3 | 服务器部署 (Docker Compose 生产配置) | 4h | 未开始 |
| 4 | 环境变量管理 (.env → 生产密钥注入) | 2h | 未开始 |

### E.2 中期目标：应用商店

| # | 任务 | 预估 |
|---|------|------|
| 1 | App Store / Google Play 开发者账号 | 1h |
| 2 | 应用图标 + 启动页设计 | 4h |
| 3 | 隐私政策 + 用户协议 (PIPL 合规) | 4h |
| 4 | 应用截图 + 描述文案 | 2h |
| 5 | 内部测试轨道分发 | 2h |
| 6 | iOS 打包准备 (Mac + Xcode + 证书) | 8h |

### E.3 CI/CD 流水线

| # | 任务 | 预估 |
|---|------|------|
| 1 | GitHub Actions / Gitea CI 配置 | 4h |
| 2 | 后端: cargo test + clippy + Docker build | 2h |
| 3 | 前端: flutter analyze + test + build | 2h |
| 4 | 管理端: pnpm lint + build | 1h |
| 5 | 自动部署到测试服务器 | 4h |

### E.4 讨论点

- 先做 Android APK（开发者模式安装）给内部测试？
- 服务器是用现有机器还是云服务器？
- CI/CD 用 Gitea 内置的还是 GitHub Actions？
- iOS 是否需要购买 Mac 设备？

---

## 方向间的依赖关系

```
A (提交收尾)
 │
 ├─→ B (审计修复) ─→ E (上线准备)
 │                   │
 ├─→ C (端到端联调)  │
 │     │             │
 │     └─→ D (体验打磨)
 │
 └─────────────────────────────→ 时间线
```

**关键路径**: A → C → D → E（先提交 → 再联调 → 再打磨 → 再上线）
**安全路径**: A → B → E（先提交 → 再修 bug → 再上线）
**混合路径**: A → B+C 并行 → D → E（推荐）

---

## 建议的推进顺序

1. **A — 收尾提交** ✅ (已完成) — 7 个提交已推送
2. **B — 安全加固** ✅ (已完成) — DTO 验证 + Token 刷新 + 班级码
3. **C — 端到端联调** ✅ (已完成) — 8/9 条链路通过
4. **D.1 体验问题修复** (下一步) — 好用
5. **B.3 性能优化** (2-3 天) — 快
6. **E.1 内测 APK** (1-2 天) — 可分享
7. **D.2 新功能探索** (持续) — 有趣
8. **E.2-E.3 应用商店 + CI/CD** (1-2 周) — 正式上线

---

## 开放讨论

> 以下问题需要在推进前达成共识：

1. **Phase 范围**: Discover 功能属于 Phase 1 还是 Phase 2？审计报告标记为 Phase 2 违规
2. **MVP 定义**: 最小可用版本的边界在哪？哪些功能必须有，哪些可以等？
3. **家长验证**: 完整 PIPL 流程 vs 注册勾选确认，MVP 选哪个？
4. **同步策略**: 修复现有协议 vs 重新设计 vs MVP 先不支持同步？
5. **测试设备**: 有没有 Android 设备可以用来真机测试？
6. **目标用户验证**: 有没有机会找真实小学生试用收集反馈？
7. **时间预期**: 从现在到"可内测"你期望多久？

---

*文档结束 — 确认方向后按优先级逐一推进*