si-meng-spec/ToDoList
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate project documentation

Browse Source
This commit is contained in:
simeng
2026-06-08 16:09:28 +08:00
parent 4ce7de48c4
commit bee9658b2d
3 changed files with 171 additions and 555 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
README.md
View File

@@ -1,163 +1,215 @@
# Elysia ToDo - 爱莉希雅待办事项
一款全栈个人信息管理应用，集待办任务、习惯打卡、纪念日提醒于一体。
Elysia ToDo 是一个全栈个人信息管理应用，当前代码包含待办任务、习惯打卡、纪念日、长期目标、证书管理、数据备份导入、WebDAV 同步和单用户密码登录能力。
## 功能概览
### 任务管理
- **待办列表** — 创建、编辑、删除任务，支持分类、标签、优先级
- **四象限视图** — 基于艾森豪威尔矩阵（重要/紧急）的四象限优先级模型
- **日历视图** — 按月/周/日查看任务排布
- **拼音搜索** — 支持中文拼音快速检索任务和分类
- 待办列表：创建、编辑、删除、完成切换、分类、标签、截止时间和优先级。
- 四象限视图：使用 `q1` 到 `q4` 表示重要/紧急优先级。
- 日历视图：按日历方式查看任务排布。
- 拼音搜索：前端使用 `pinyin-pro` 支持中文拼音检索。
### 习惯打卡
- 习惯分组管理（学习、运动、生活等）
- 每日打卡记录，支持周期配置与休息日
- 周视图打卡进度展示，一目了然
### 纪念日管理
- 自定义纪念日分类
- 支持农历/公历日期
- 倒计时提醒，不错过重要日子
- 习惯分组管理，支持颜色、图标和排序。
- 习惯支持每日/每周频率、目标次数、指定活跃日期和归档状态。
- 打卡记录按日期保存，可用于周视图/月视图展示。
### 系统功能
- 偏好设置（站点名称、默认视图等）
- 可折叠侧边栏
- 响应式布局
- SPA 单页应用，History 路由模式
### 纪念日
- 纪念日分类管理。
- 纪念日支持日期、年份、循环标记、提前提醒天数和说明。
- 前端提供倒计时、分类筛选和编辑弹窗。
### 目标管理
- 长期目标支持 `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 |
| 构建工具 | Vite 7 |
| HTTP 客户端 | Axios |
| 后端框架 | FastAPI |
| ORM | SQLAlchemy |
| 数据库 | SQLite |
| ORM | SQLAlchemy 2 |
| 数据库 | PostgreSQL，默认由 `DATABASE_URL` 指定 |
| ASGI 服务器 | Uvicorn |
| 密码与令牌 | bcrypt + python-jose |
## 项目结构
```
```text
ToDoList/
├── main.py # 启动入口（编译前端 + 启动后端）
├── requirements.txt # Python 依赖
├── .gitignore
├── api/ # 后端
│ └── app/
│ ├── config.py # 配置（端口、路径、CORS 等）
│ ├── database.py # 数据库引擎与会话管理
│ ├── main.py # FastAPI 应用（路由、中间件、静态文件）
│ ├── models/ # SQLAlchemy 数据模型
│ ├── schemas/ # Pydantic 请求/响应模型
│ ├── routers/ # API 路由
│ └── utils/ # 工具函数（CRUD、日志、日期）
├── WebUI/ # 前端
│ ├── package.json
│ ├── vite.config.ts
│ └── src/
│ ├── api/ # Axios 接口封装
│ ├── components/ # 通用组件
│ ├── views/ # 页面视图
│ ├── stores/ # Pinia 状态管理
│ ├── router/ # 路由配置
│ ├── styles/ # 全局样式 (SCSS)
│ └── utils/ # 前端工具（拼音、优先级、日期）
└── tests/ # 测试
├── 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/` 目录，也没有独立的测试脚本。
### 环境要求
## 环境要求
- Python 3.10+
- Node.js 18+
- npm
- 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` 读取，推荐通过环境变量覆盖。
### 安装与运行
## 启动与停止
```bash
# 1. 克隆项目
git clone <your-repo-url>
cd ToDoList
官方启动入口是脚本，不建议把 `python`、`npm`、`uvicorn` 作为日常手工启动方式。
# 2. 安装 Python 依赖
pip install -r requirements.txt
```cmd
scripts\start.bat
```
# 3. 一键启动（自动编译前端 + 启动后端）
python main.py
`scripts\start.bat` 会执行以下动作：
1. 切换到项目根目录。
2. 检查 Python 和项目文件。
3. 首次运行时安装 Python 依赖。
4. 检查并释放 `23994` 端口。
5. 运行 `main.py`。
6. `main.py` 会按需执行前端依赖安装、`npm.cmd run build`、复制 `WebUI/dist` 到 `api/webui`，再启动 FastAPI。
停止服务：
```cmd
scripts\stop.bat
```
启动后访问：
- 前端页面：http://localhost:23994
- API 文档：http://localhost:23994/docs
### 前端开发模式
如果需要前后端分离开发（热更新）：
```bash
# 终端 1 — 启动后端
cd api
uvicorn app.main:app --host 0.0.0.0 --port 23994
# 终端 2 — 启动前端开发服务器
cd WebUI
npm install
npm run dev
```
前端开发服务器运行在 http://localhost:5173，已配置 API 代理到后端。
## API 概览
所有接口均以 `/api` 为前缀，启动后端后访问 `/docs` 查看 Swagger 文档。
| 模块 | 前缀 | 说明 |
|------|------|------|
| 任务 | `/api/tasks` | 任务 CRUD、状态切换、批量操作 |
| 分类 | `/api/categories` | 分类 CRUD |
| 标签 | `/api/tags` | 标签 CRUD |
| 习惯 | `/api/habits` | 习惯、习惯组、打卡记录 |
| 纪念日 | `/api/anniversaries` | 纪念日、纪念日分类 |
| 设置 | `/api/user-settings` | 用户偏好设置 |
| 健康检查 | `/health` | 服务状态检查 |
## 数据模型关系
```
Category ──< Task >── Tag
│
HabitGroup ──< Habit ──< HabitCheckin
AnniversaryCategory ──< Anniversary
UserSettings （单例）
```
- 健康检查：http://localhost:23994/health
## 配置说明
在 `api/app/config.py` 中可以修改：
主要配置位于 `api/app/config.py`。
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| HOST | `0.0.0.0` | 监听地址 |
| PORT | `23994` | 服务端口 |
| DATABASE_PATH | `api/data/todo.db` | SQLite 数据库路径 |
| WEBUI_PATH | `api/webui` | 前端静态文件目录 |
| CORS_ORIGINS | `localhost:5173, 23994` | 允许的跨域来源 |
| 配置项 | 当前默认值 | 说明 |
|--------|------------|------|
| `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 快照。
项目支持在 Windows 和 Linux 上运行。`main.py` 会自动处理平台差异（npm 命令、端口占用检测等）。
## API 概览
对于生产环境部署，建议：
- 使用 `gunicorn` + `uvicorn worker` 替代直接运行
- 配置反向代理（Nginx）
- 数据库可替换为 PostgreSQL 或 MySQL（修改 `config.py` 中的 `DATABASE_URL`）
除 `/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` | 服务状态 |
## 数据模型关系
```text
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/` 下的验证脚本，再通过脚本执行验证。