docs: 项目 Wiki 知识库 — 7 文件覆盖架构/手写/数据/前端/后端/技术债
新增 wiki/ 知识库 (遵循 HMS wiki-methodology.md 5 节结构): - index.md (84 行) — 症状导航 13 条 + 模块索引 + 系统数据流 - architecture.md (120 行) — 基座剥离 7 耦合点 + Feature Flag + PIPL 合规 - handwriting-engine.md (124 行) — 双层 Canvas + O(1) 点缓冲 + 光栅化缓存 - data-layer.md (127 行) — Isar + SyncEngine 离线同步 + 踩坑记录 - frontend.md (118 行) — 16 模块地图 + BLoC 注入链 + 设计系统 - erp-diary.md (101 行) — 15 Entity / 10 Service / 8 Handler + API 端点 新增 docs/: - tech-debt-board.md (110 行) — 10 条技术债 + 偿还优先级排名 其他更新: - .gitignore: 添加 .understand-anything/ (待初始化) - CLAUDE.md §9: 添加 wiki 参考文档链接
This commit is contained in:
110
docs/tech-debt-board.md
Normal file
110
docs/tech-debt-board.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 暖记技术债看板
|
||||
|
||||
> 最后更新: 2026-06-01
|
||||
|
||||
## 指标概览
|
||||
|
||||
| 指标 | 当前值 | 目标 | 状态 |
|
||||
|------|--------|------|------|
|
||||
| flutter analyze 错误 | 0 | 0 | 🟢 健康 |
|
||||
| flutter analyze 警告 | 1 | 0 | 🟡 需改进 |
|
||||
| flutter analyze info | 18 | ≤10 | 🟡 需改进 |
|
||||
| 后端测试 | ~50 | 80%+ 覆盖 | 🟡 需改进 |
|
||||
| 前端测试 | 0 | 80%+ 覆盖 | 🔴 缺失 |
|
||||
| CI/CD | 无 | 全自动化 | 🔴 缺失 |
|
||||
| Docker 部署 | 未验证 | 可运行 | 🔴 缺失 |
|
||||
|
||||
## 高息技术债(按优先级排序)
|
||||
|
||||
### TD-1: editor_page.dart authorId 硬编码 [利息: HIGH]
|
||||
|
||||
- **现状**: `JournalEntry.create(authorId: 'local')` 硬编码
|
||||
- **影响**: 无法关联真实用户,同步后数据混乱
|
||||
- **修复成本**: 0.5 天
|
||||
- **计划**: 接入 AuthBloc 获取当前用户 ID
|
||||
- **文件**: `app/lib/features/editor/views/editor_page.dart:96`
|
||||
|
||||
### TD-2: CI/CD 未建立 [利息: HIGH]
|
||||
|
||||
- **现状**: 手动 `cargo check` + `flutter analyze`
|
||||
- **影响**: 无法防止回归,无自动部署
|
||||
- **修复成本**: 1 天
|
||||
- **计划**: GitHub Actions / Gitea CI + 基础流水线
|
||||
|
||||
### TD-3: 后端 Docker 部署未验证 [利息: HIGH]
|
||||
|
||||
- **现状**: `docker/` 目录有 compose 文件但从未实际运行
|
||||
- **影响**: 无法确认后端可正常启动
|
||||
- **修复成本**: 0.5 天
|
||||
- **计划**: docker-compose up + 健康检查验证
|
||||
|
||||
### TD-4: 笔画 toImage() 同步阻塞 [利息: MEDIUM]
|
||||
|
||||
- **现状**: `stroke_cache.dart` 中 `toImage()` 在主线程执行
|
||||
- **影响**: 大笔画可能导致 UI 卡顿
|
||||
- **修复成本**: 1 天
|
||||
- **计划**: compute() isolate 异步光栅化
|
||||
|
||||
### TD-5: 前端测试为零 [利息: MEDIUM]
|
||||
|
||||
- **现状**: `app/test/` 目录空
|
||||
- **影响**: 无回归保护,重构风险高
|
||||
- **修复成本**: 3 天
|
||||
- **计划**: Repository 单元测试 → BLoC 测试 → Widget 测试
|
||||
|
||||
### TD-6: 画布尺寸变化缓存过渡 [利息: MEDIUM]
|
||||
|
||||
- **现状**: 屏幕旋转时 ui.Image 缓存失效,需要重新光栅化
|
||||
- **影响**: 旋转瞬间可能卡顿或空白
|
||||
- **修复成本**: 1 天
|
||||
- **计划**: 监听尺寸变化,异步重建缓存
|
||||
|
||||
### TD-7: SecureStorage token 未持久化 [利息: MEDIUM]
|
||||
|
||||
- **现状**: app.dart 中 token 设置为 TODO 注释
|
||||
- **影响**: 每次重启需要重新登录
|
||||
- **修复成本**: 0.5 天
|
||||
- **计划**: flutter_secure_storage 存取 JWT
|
||||
|
||||
### TD-8: 编辑器不加载已有日记 [利息: MEDIUM]
|
||||
|
||||
- **现状**: journalId 非空时未从 Isar 读取数据
|
||||
- **影响**: 编辑已有日记时显示空白
|
||||
- **修复成本**: 1 天
|
||||
- **计划**: EditorBloc 添加 LoadJournal event + Isar 查询
|
||||
|
||||
### TD-9: Isar FTS 搜索未实现 [利息: LOW]
|
||||
|
||||
- **现状**: search 模块是空壳
|
||||
- **影响**: 无法搜索日记内容
|
||||
- **修复成本**: 1 天
|
||||
- **计划**: Isar FTS 索引 + 搜索结果页
|
||||
|
||||
### TD-10: SyncEngine 蜂窝数据未支持 [利息: LOW]
|
||||
|
||||
- **现状**: 仅 WiFi 自动同步
|
||||
- **影响**: 无 WiFi 时无法同步
|
||||
- **修复成本**: 0.5 天
|
||||
- **计划**: 添加用户设置允许蜂窝数据同步
|
||||
|
||||
## 已偿还债务
|
||||
|
||||
| 债务 | 还清日期 | 投入 |
|
||||
|------|---------|------|
|
||||
| 手写引擎单层 Canvas 卡顿 | 2026-06-01 | 双层架构 + 光栅化缓存 |
|
||||
| 编辑器 onSave 仅 debugPrint | 2026-06-01 | IsarJournalRepository 持久化 |
|
||||
| SyncEngine 队列纯内存 | 2026-06-01 | Isar PendingOperation 持久化 |
|
||||
| Isar 未初始化 | 2026-06-01 | main.dart init + Schema 注册 |
|
||||
| 深色模式适配问题 | 2026-05-31 | F11 修复 + B7 测试套件 |
|
||||
|
||||
## 偿还优先级排名
|
||||
|
||||
| 优先级 | 债务 | 预估投入 | 预期效果 |
|
||||
|--------|------|---------|---------|
|
||||
| P0 | TD-1 authorId 硬编码 | 0.5 天 | 数据可关联真实用户 |
|
||||
| P0 | TD-3 Docker 部署 | 0.5 天 | 后端可运行验证 |
|
||||
| P1 | TD-7 token 持久化 | 0.5 天 | 免重复登录 |
|
||||
| P1 | TD-8 加载已有日记 | 1 天 | 编辑器完整可用 |
|
||||
| P1 | TD-4 toImage 异步 | 1 天 | 消除大笔画卡顿 |
|
||||
| P2 | TD-2 CI/CD | 1 天 | 自动化质量守卫 |
|
||||
| P2 | TD-5 前端测试 | 3 天 | 回归保护 |
|
||||
Reference in New Issue
Block a user