Elysia ToDo - 爱莉希雅待办事项
Elysia ToDo 是一个全栈个人信息管理应用，当前代码包含待办任务、习惯打卡、纪念日、长期目标、证书管理、数据备份导入、WebDAV 同步和单用户密码登录能力。
功能概览
任务管理
- 待办列表：创建、编辑、删除、完成切换、分类、标签、截止时间和优先级。
- 四象限视图：使用
q1到q4表示重要/紧急优先级。 - 日历视图：按日历方式查看任务排布。
- 拼音搜索：前端使用
pinyin-pro支持中文拼音检索。
习惯打卡
- 习惯分组管理，支持颜色、图标和排序。
- 习惯支持每日/每周频率、目标次数、指定活跃日期和归档状态。
- 打卡记录按日期保存，可用于周视图/月视图展示。
纪念日
- 纪念日分类管理。
- 纪念日支持日期、年份、循环标记、提前提醒天数和说明。
- 前端提供倒计时、分类筛选和编辑弹窗。
目标管理
- 长期目标支持
milestone里程碑模式和cumulative累计打卡模式。 - 目标可设置状态、目标值、输入单位、换算率、目标日期、分类、颜色、图标和排序。
- 目标详情支持阶段/里程碑、复盘、关联任务和目标打卡记录。
证书管理
- 证书分类管理。
- 证书支持图片、颁发机构、颁发日期、到期日期、说明和排序。
系统与数据
- 首次设置密码、登录、退出、修改密码，使用 Cookie 中的 JWT 做会话认证。
- 用户偏好设置：昵称、头像、签名、生日、邮箱、站点名称、主题、默认视图和默认排序。
- 数据备份导出和导入：通过
/api/backup/export与/api/backup/import处理 JSON 备份。 - WebDAV 同步：支持配置、测试连接、推送、拉取、双向同步、状态查询和清空远端同步数据。
- SPA 单页应用，后端静态服务支持 History 路由回退。
技术栈
| 层级 | 当前实现 |
|---|---|
| 前端框架 | Vue 3 + TypeScript |
| UI 组件库 | Element Plus |
| 状态管理 | Pinia |
| 路由 | Vue Router 4 |
| 构建工具 | Vite 7 |
| HTTP 客户端 | Axios |
| 后端框架 | FastAPI |
| ORM | SQLAlchemy 2 |
| 数据库 | PostgreSQL，默认由 DATABASE_URL 指定 |
| ASGI 服务器 | Uvicorn |
| 密码与令牌 | bcrypt + python-jose |
项目结构
ToDoList/
├── main.py # 编译前端、复制静态资源、启动后端
├── requirements.txt # Python 依赖锁定
├── Dockerfile # 后端镜像，依赖预构建的 api/webui
├── docker-compose.yml # PostgreSQL + 应用服务
├── scripts/
│ ├── start.bat # Windows CMD 启动脚本
│ └── stop.bat # Windows CMD 停止脚本
├── api/
│ ├── app/
│ │ ├── config.py # 数据库、端口、CORS、日志和 JWT 配置
│ │ ├── database.py # SQLAlchemy 引擎、会话、建表和轻量迁移
│ │ ├── main.py # FastAPI 应用、中间件、路由和静态文件
│ │ ├── models/ # SQLAlchemy 数据模型
│ │ ├── schemas/ # Pydantic 请求/响应模型
│ │ ├── routers/ # API 路由
│ │ └── utils/ # 日志、认证、同步、WebDAV、加密等工具
│ └── webui/ # 已构建前端静态资源，启动时由 main.py 覆盖
└── WebUI/
├── package.json
├── package-lock.json
├── vite.config.ts
└── src/
├── api/ # Axios 接口封装
├── components/ # 复用组件和弹窗
├── router/ # 路由和认证守卫
├── stores/ # Pinia 状态
├── styles/ # 全局 SCSS
├── utils/ # 日期、拼音、优先级工具
└── views/ # 页面视图
当前仓库只保留根目录 README.md 作为统一文档入口；没有 tests/ 目录，也没有独立的测试脚本。
环境要求
- Windows CMD 是默认运行环境。
- Python 3.10+。当前本机检查到的解释器是 Python 3.11.0。
- Node.js 满足 Vite 7 要求：
^20.19.0或>=22.12.0。 - npm。Windows 下优先使用
npm.cmd，避免 PowerShell shim 路径问题。 - PostgreSQL。默认连接由
api/app/config.py中的DATABASE_URL读取，推荐通过环境变量覆盖。
启动与停止
官方启动入口是脚本，不建议把 python、npm、uvicorn 作为日常手工启动方式。
scripts\start.bat
scripts\start.bat 会执行以下动作：
- 切换到项目根目录。
- 检查 Python 和项目文件。
- 首次运行时安装 Python 依赖。
- 检查并释放
23994端口。 - 运行
main.py。 main.py会按需执行前端依赖安装、npm.cmd run build、复制WebUI/dist到api/webui，再启动 FastAPI。
停止服务：
scripts\stop.bat
启动后访问：
配置说明
主要配置位于 api/app/config.py。
| 配置项 | 当前默认值 | 说明 |
|---|---|---|
DATABASE_URL |
从环境变量读取，否则使用内置 PostgreSQL 连接 | SQLAlchemy 数据库连接串 |
WEBUI_PATH |
api/webui |
后端挂载的前端静态资源目录 |
CORS_ORIGINS |
http://localhost:5173、http://localhost:23994 |
允许的跨域来源 |
LOG_LEVEL |
INFO |
应用日志级别 |
LOG_DIR |
api/logs |
文件日志目录 |
HOST |
0.0.0.0 |
服务监听地址 |
PORT |
23994 |
服务端口 |
JWT_SECRET |
首次启动写入 api/data/.jwt_secret |
JWT 和 WebDAV 密码加密派生密钥 |
运行时目录：
api/logs/app.log：应用日志，按天轮转。api/data/.jwt_secret：本机 JWT 密钥文件。api/data/backups/：WebDAV 拉取前的本地 JSON 快照。
API 概览
除 /health 外，业务接口均在 /api 下。大多数 /api/* 接口需要登录 Cookie。
| 模块 | 路径 | 说明 |
|---|---|---|
| 认证 | /api/auth/status、/api/auth/setup、/api/auth/login、/api/auth/logout、/api/auth/me、/api/auth/change-password |
首次设置、登录状态、登录退出和改密 |
| 任务 | /api/tasks、/api/tasks/{task_id}/toggle |
任务 CRUD 和完成切换 |
| 分类 | /api/categories |
任务分类 CRUD |
| 标签 | /api/tags |
标签列表、创建、删除 |
| 习惯分组 | /api/habit-groups |
习惯分组 CRUD |
| 习惯 | /api/habits、/api/habits/{habit_id}/checkins |
习惯 CRUD、归档和打卡 |
| 纪念日 | /api/anniversary-categories、/api/anniversaries |
纪念日分类和纪念日 CRUD |
| 目标 | /api/goals |
目标、步骤、复盘、关联任务和目标打卡 |
| 证书 | /api/certificate-categories、/api/certificates |
证书分类和证书 CRUD |
| 用户设置 | /api/user-settings |
用户偏好获取和更新 |
| 备份 | /api/backup/export、/api/backup/import |
JSON 备份导出和覆盖导入 |
| WebDAV 同步 | /api/sync/config、/api/sync/test、/api/sync/push、/api/sync/pull、/api/sync/sync、/api/sync/status、/api/sync/remote |
同步配置和操作 |
| 健康检查 | /health |
服务状态 |
数据模型关系
Category 1 -> N Task
Task N <-> N Tag
HabitGroup 1 -> N Habit
Habit 1 -> N HabitCheckin
AnniversaryCategory 1 -> N Anniversary
Category 1 -> N Goal
Goal 1 -> N GoalStep
GoalStep 1 -> N GoalStep
Goal 1 -> N GoalReview
Goal 1 -> N GoalCheckin
Goal N <-> N Task
CertificateCategory 1 -> N Certificate
UserSettings 1 -> 1
SyncSettings 1 -> 1
可同步模型使用 uuid、sync_version、is_deleted 支持 WebDAV 同步和软删除传播。
Docker 部署
docker-compose.yml 包含两个服务：
db：PostgreSQL，容器名elysia-todo-db。elysia-todo：应用服务，容器名elysia-todo，对外暴露23994。
注意：Dockerfile 只复制 api/ 和已经存在的 api/webui/，不会在镜像构建时编译 WebUI/。构建镜像前需要先通过启动流程或构建流程生成前端产物并复制到 api/webui。
当前已知差异
requirements.txt当前未显式列出requests，但api/app/utils/webdav.py会导入并使用它。干净环境如果报ModuleNotFoundError: No module named 'requests'，需要先补齐依赖配置。- 连接串、容器数据库密码等敏感配置当前存在于仓库配置文件中。对外发布或多人协作前，建议改为环境变量和
.env.example。 - 仓库当前没有测试目录和测试脚本。新增功能时应先补
scripts/下的验证脚本，再通过脚本执行验证。