diff --git a/plans/next-steps-roadmap.md b/plans/next-steps-roadmap.md new file mode 100644 index 0000000..8acd410 --- /dev/null +++ b/plans/next-steps-roadmap.md @@ -0,0 +1,306 @@ +# 暖记下一步工作路线图 + +> **创建日期**: 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. **时间预期**: 从现在到"可内测"你期望多久? + +--- + +*文档结束 — 确认方向后按优先级逐一推进*