dodo/docs/decisions.md

dodo 产品与技术决策记录

定位与当前范围

dodo 是纯自托管、面向个人长期使用的任务与生活管理 PWA。当前包含任务/子任务、文件夹与清单、今日视图、重复任务、习惯、倒数日、Markdown 备忘录、附件、会话管理、审计和数据备份；不提供番茄钟、自然语言建任务或外部通知渠道。

技术与数据

• Monorepo：Vue 3 + TypeScript + Vite 前端，FastAPI + Pydantic v2 + SQLAlchemy 2 Async + Alembic 后端
• PostgreSQL 生产、SQLite 测试；UUIDv7 主键，时间点使用 UTC，日历语义使用用户时区
• 单 Docker 镜像，外部 PostgreSQL；AGPL-3.0
• 用户业务读写必须按归属过滤；更新任务/备忘录使用乐观锁

产品模型

• 文件夹 → 清单 → 一层任务树；系统收集箱受保护
• 清单删除定义为归档：保留任务成员关系，归档期间隐藏，恢复后原样出现；永久删除仅允许作用于已归档清单
• 截止日期区分全天日期和具体时间；重复任务支持 RFC 5545 计划重复及“完成后重复”
• 习惯支持完成型/数值型、日/周/月/间隔计划、暂停、历史和归档
• 倒数日支持公历/农历、生日/纪念日、重复、置顶与归档
• 备忘录使用 Markdown，支持软删除、恢复及归档后永久删除

UI 决策

• 桌面保留左导航/内容/可选详情三栏；移动端使用底部导航
• 手机底栏固定为“今天、习惯、倒数日、设置”，精确匹配当前页面；不使用“更多”中转
• 新建入口使用同一个普通圆形 Plus FAB，禁止装饰性光环或吉祥物
• 设置页使用连续分组：数据、账户与安全、登录设备、活动、危险操作
• 任务、习惯、倒数日、备忘录、操作菜单和确认框统一走 AppSheet / AppDialog 覆盖层栈；共享背景 inert、焦点陷阱、Escape、忙碌态和嵌套焦点恢复
• 桌面任务/备忘录详情可保持非模态，移动端由同一组件切为底部模态弹层

备份决策

• “完整备份”专指 dodo-backup ZIP version 2，而不是旧 JSON/CSV
• v2 覆盖全部用户业务实体、历史/例外、附件元数据与附件字节；manifest 记录实体数量和每个条目的 SHA-256
• 恢复必须先预检，再用绑定用户、文件摘要和模式的短期单次令牌执行
• 预检拒绝未知/缺失实体、不安全 ZIP 路径、重复条目、异常压缩比/容量、校验和错误、非法字段、破坏关系拓扑或一层任务树的数据
• merge 通过持久化 ID/摘要账本保证幂等与冲突可见；replace 仅替换当前用户业务数据
• 附件恢复采用同文件系统暂存/隔离与补偿；数据库提交后的清理失败可用同一令牌重试清理，不会再次导入
• 保留 JSON/CSV v1 恢复兼容，但明确其不包含日志、暂停、重复例外和附件字节，仅用于旧数据迁移

工程质量

• API 基路径 /api/v1；Cookie Session、同源 CSRF、安全响应头、登录限流
• 附件与备份均有容量限制、路径包含检查和用户归属校验
• 后端使用 pytest + ruff，前端使用 Vitest + vue-tsc/Vite；变更结束运行全量测试、构建和 git diff --check