# 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`