# 暖记 (Warm Notes) — 30 天行动计划：质量保障 + 核心体验 + 架构演进

> **版本**: 1.0
> **日期**: 2026-06-01
> **来源**: 多专家组头脑风暴（质量保障 / UX体验 / 系统架构）
> **目标**: 从当前状态推进到小学生可用的 MVP

---

## 1. 项目现状快照

| 指标 | 值 |
|------|-----|
| 后端 Rust | 51,459 行，8 个 crate，~50 测试 |
| 前端 Flutter | 18,398 行，70 文件，**0 测试** |
| 技术债 | 10 已记录 + 9 新发现 |
| CI/CD | 无 |
| Docker | 配置存在但未验证，Dockerfile 缺失 |

## 2. 三维分析矩阵

### 2.1 质量保障（QA 专家）

**核心发现**：前端 0 测试是最大风险。没有测试保障，任何重构都可能引入回归 Bug。

**策略**：由内向外，先逻辑后 UI。

| 批次 | 目标 | 用例数 | 工时 |
|------|------|--------|------|
| 1 | InMemoryJournalRepository + SyncEngine + EditorBloc | ~40 | 16h |
| 2 | AuthBloc + HomeBloc + CalendarBloc + MoodBloc | ~35 | 24h |
| 3 | IsarJournalRepository + RemoteJournalRepository | ~20 | 32h |

**CI/CD 设计**：
- PR 触发：cargo fmt/check/clippy/test + flutter analyze/test + cargo audit
- Main 触发：上述 + Docker 构建验证
- 质量门禁：必须通过全部检查 + 1 人 Code Review

**Docker 验证**：
- 创建多阶段 Dockerfile（rust:alpine → alpine）
- docker-compose 添加 server service
- verify.sh 自动化健康检查

### 2.2 核心体验（UX 专家）

**核心发现**：编辑器的文字/图片/贴纸工具全为占位，班级互动有 5 个断点。小学生"第一个 30 分钟"的体验路径断裂。

**编辑器 P0 缺口**：

| 缺口 | 现状 | 方案 | 工时 |
|------|------|------|------|
| 文字输入 | 工具栏显示静态文字 | 叠加式 TextField + 小/中/大字号 | 16h |
| 图片上传 | 无反应 | image_picker + 压缩 + 拖拽 | 12h |
| 贴纸接入 | 仅切换模式 | 编辑器贴纸面板 → 放置 | 8h |
| 模板传递 | 忽略 template 参数 | EditorPage 读取 template 查询参数 | 8h |

**班级流程 5 个断点**：

```
断点1: 班级码硬编码 'a1b2c3' → 需接入后端 API 生成
断点2: 班级码验证跳过 (TODO) → 需调用后端验证
断点3: 编辑器无分享选项 → 需添加分享 BottomSheet
断点4: 老师查看无只读模式 → 需 readonly 参数
断点5: 无评语输入入口 → 需评语 BottomSheet
```

**家长中心 PIPL 合规**：Phase 1 必须 4 功能（关联/查看/导出/删除），约 30h。

**搜索替代**：标签+心情筛选先行（6h），无需 Isar FTS。

### 2.3 架构演进（架构专家）

**核心发现**：Feature Flag 在规划中设计完善但未落地；状态管理两种模式混用；环境配置硬编码。

**Feature Flag 落地**（2h）：
- `erp-server/Cargo.toml` 添加 `[features] default = ["diary"]`
- `main.rs` 6 个区域用 `#[cfg(feature = "diary")]` 包裹

**状态管理统一**（2 天，第二批）：
- 5 个 ChangeNotifier → flutter_bloc + sealed class
- app.dart 移除 provider 依赖，统一 BlocProvider

**超大文件拆分**（第三批）：
- manifest.rs (1809行) → 8 个子文件
- data_service.rs (1907行) → 6 个子文件
- module.rs (1283行) → 事件处理器独立
- main.rs (820行) → bootstrap/router/seed 模块

**环境配置**（4h）：
- 新建 AppConfig 类，`--dart-define` 注入
- 修复 SSE 端口 8080 → 3000

## 3. 综合决策

### 3.1 优先级取舍

| 交锋点 | 决策 | 理由 |
|--------|------|------|
| 先测试 vs 先功能 | **功能优先 + 关键路径同步写测试** | 产品不可用比测试缺失更致命 |
| 状态管理统一 | **第二批再做** | 当前不阻塞开发，统一需要 2 天集中投入 |
| Feature Flag | **第三批与 CI/CD 同步** | Flag 是给 CI 用的，CI 建好了再落地 |
| 家长中心 | **仅做 PIPL 最低 4 功能** | 30h 已是极限，时间限制等 Phase 2 |

### 3.2 风险预警

| 风险 | 缓解策略 |
|------|---------|
| 编辑器文字输入比预期复杂 | 先做最简版（固定位置 TextField），后续迭代 |
| 家长中心 30h 可能低估 | 仅做 4 个核心功能，不做时间限制 |
| 测试和功能并行阻塞 | 测试只覆盖纯逻辑层，不测 UI |

## 4. 30 天行动时间线

### Week 1：核心路径打通 — 编辑器体验（~44h）

> 目标：小学生可以写出包含手写+文字+贴纸+照片的完整日记

| 任务 | 工时 | 交付物 |
|------|------|--------|
| 编辑器文字输入 | 16h | 叠加式 TextField + 小/中/大字号 + 颜色选择 |
| 编辑器图片上传 | 12h | image_picker + 压缩 + 拖拽定位 |
| 编辑器贴纸接入 | 8h | 贴纸面板 → 选择 → 放置到画布 |
| 模板数据传递 | 8h | EditorPage 读取 template 参数并预填充 |

### Week 2：班级互动闭环 + 测试基础（~52h）

> 目标：老师→学生→分享→点评 闭环可走通

| 任务 | 工时 | 交付物 |
|------|------|--------|
| 班级码生成+验证 | 14h | 前后端联调，6 位随机码 + 5 次锁定 |
| 分享到班级 | 8h | 编辑器完成按钮 → 分享/私密 BottomSheet |
| 老师只读查看+点评 | 12h | readonly 模式 + 评语 BottomSheet |
| 前端第一批测试 | 16h | EditorBloc + InMemoryRepo + SyncEngine (~40 用例) |
| 添加测试依赖 | 2h | bloc_test + mocktail |

### Week 3：质量保障体系（~42h）

> 目标：CI 自动化 + 核心模块 80% 测试覆盖

| 任务 | 工时 | 交付物 |
|------|------|--------|
| 前端第二批测试 | 24h | AuthBloc + HomeBloc + CalendarBloc + MoodBloc (~35 用例) |
| 后端 P0 单元测试 | 10h | journal/sync/class service 核心逻辑 |
| CI/CD 流水线 | 8h | pr-check.yml + main-merge.yml |

### Week 4：收尾 + 架构治理（~48h）

> 目标：搜索可用 + PIPL 合规 + 部署就绪

| 任务 | 工时 | 交付物 |
|------|------|--------|
| 搜索替代方案 | 6h | 标签+心情筛选（无 FTS） |
| 家长中心最小集 | 30h | 关联/查看/导出/删除 4 功能 |
| Docker 部署验证 | 6.5h | Dockerfile + docker-compose + verify.sh |
| 环境配置统一 | 4h | AppConfig + SSE 端口修复 |
| Feature Flag 落地 | 2h | Cargo.toml [features] + main.rs 条件编译 |

## 5. 成功标准

30 天后验收清单：

- [ ] 小学生可以写出包含 **手写 + 文字 + 贴纸 + 照片** 的完整日记
- [ ] **老师布置 → 学生写作 → 分享到班级 → 老师点评** 闭环可演示
- [ ] 前端 **~80 个测试** 覆盖核心 BLoC 和 Repository
- [ ] CI 自动运行 cargo check + flutter analyze + 测试
- [ ] Docker 一键启动（PG + Redis + Axum）
- [ ] 家长可查看孩子日记 + 导出/删除数据（PIPL 合规）
- [ ] 搜索可按标签和心情筛选日记

## 6. 总工时估算

| 方向 | 工时 | 占比 |
|------|------|------|
| 核心体验（编辑器+班级+家长） | ~122h | 55% |
| 质量保障（测试+CI+Docker） | ~100h | 38% |
| 架构治理（Feature Flag+环境配置） | ~20h | 7% |
| **合计** | **~186h** | 100% |

> 按 1 人每天 6h 有效开发时间，约 31 个工作日（~6 周）。

---

*本文档由多专家组头脑风暴综合生成：质量保障专家 + UX体验专家 + 系统架构专家*