Appearance
✨ 核心亮点
🔌 离线优先（Offline-First） 断网状态下可正常增删改查，操作写入本地 SQLite + 离线队列（Outbox Pattern），联网后自动按序同步至服务端，操作不丢失、不重复。
⚡ 实时多端同步 基于 SSE（Server-Sent Events）实现服务端到客户端的实时推送。设备 A 修改待办，设备 B 在数秒内自动刷新，无需手动操作。Client-ID 过滤机制确保发起变更的设备不会收到冗余推送。
📱 跨平台响应式外壳 同一套 Flutter 代码编译出 Windows 桌面端（NavigationRail 侧边栏）和 Android 移动端（BottomNavigationBar 底栏），两端共享全部业务组件，平台差异只在外层壳中处理。
🔒 完善的安全设计 全链路 HTTPS、bcrypt 密码哈希、JWT 双 Token 鉴权（access 1小时 / refresh 30天）、后端端口隔离、敏感配置环境变量管理。
🖥 功能预览
| 模块 | 功能 |
|---|---|
| 待办管理 | 创建 / 编辑 / 删除 / 完成，支持标题、备注、优先级、截止时间 |
| 筛选与搜索 | 按状态、优先级筛选，关键字实时搜索，多维排序 |
| 账号体系 | 邮箱注册登录，忘记密码（验证码邮件），访客模式 |
| 多端同步 | 实时同步，离线队列，增量拉取 |
| 到期提醒 | 临期（15 分钟前）和逾期通知，Windows 托盘 / Android 系统推送 |
| 日志调试 | 应用内日志查看器，全链路 Correlation ID，后端 /logs/ Web 界面 |
🚀 快速开始
后端部署
前提：Ubuntu 22.04+ VPS，已安装 Docker、Nginx，域名已解析。
bash
# 1. 克隆后端代码
git clone <your-backend-repo-url> ~/todo_backend
cd ~/todo_backend
# 2. 创建配置文件
cp .env.example .env
vim .env # 填写 JWT_SECRET、DB_PASSWORD、RESEND_API_KEY 等
# 3. 创建日志目录并启动
mkdir -p logs
docker compose up -d --build
# 4. 验证服务启动
docker compose logs -f apiNginx 配置、SSL 证书申请、完整环境变量说明 详见 第七章：生产环境部署。
客户端构建
bash
# Windows 桌面端
flutter build windows --release
# Android（arm64，体积最优）
flutter build apk --release --target-platform android-arm64📖 技术文档
| 章节 | 内容 |
|---|---|
| 一、项目概览 | 功能清单、技术栈详解、数据安全保护 |
| 二、系统架构设计 | 整体架构图、数据流向、前后端分层 |
| 三、核心架构亮点 | 离线优先、实时同步、跨平台响应式外壳深度解析 |
| 四、技术选型思考 | Flutter / Dart Shelf / SSE / Drift / JWT / Nginx 的选型对比与理由 |
| 五、踩坑与调优实录 | SSE 死穴、像素溢出、Release 包网络失败、通知库编译报错等真实排查过程 |
| 六、安全设计 | 传输层、密码存储、JWT、端口隔离、日志安全全链路保护 |
| 七、生产环境部署 | 从零部署完整操作手册，含 Nginx 配置、SSL 证书、Resend 邮件配置 |
| 八、项目结构 | 前后端目录树、各层职责说明、数据库表结构 |
📁 仓库结构
todo_app/ ← Flutter 前端
todo_backend/ ← Dart Shelf 后端