174 lines
5.2 KiB
Markdown
174 lines
5.2 KiB
Markdown
# Elysia ToDo - 爱莉希雅待办事项
|
||
|
||
一款全栈个人信息管理应用，集待办任务、习惯打卡、纪念日提醒、资产总览于一体。
|
||
|
||
## 功能概览
|
||
|
||
### 任务管理
|
||
- **待办列表** — 创建、编辑、删除任务，支持分类、标签、优先级
|
||
- **四象限视图** — 基于艾森豪威尔矩阵（重要/紧急）的四象限优先级模型
|
||
- **日历视图** — 按月/周/日查看任务排布
|
||
- **拼音搜索** — 支持中文拼音快速检索任务和分类
|
||
|
||
### 习惯打卡
|
||
- 习惯分组管理（学习、运动、生活等）
|
||
- 每日打卡记录，支持周期配置与休息日
|
||
- 周视图打卡进度展示，一目了然
|
||
|
||
### 纪念日管理
|
||
- 自定义纪念日分类
|
||
- 支持农历/公历日期
|
||
- 倒计时提醒，不错过重要日子
|
||
|
||
### 资产总览
|
||
- 财务账户管理（现金、银行卡、电子钱包等）
|
||
- 收支记录与历史查询
|
||
- 分期还款跟踪
|
||
- 资产汇总统计
|
||
|
||
### 系统功能
|
||
- 偏好设置（站点名称、默认视图等）
|
||
- 可折叠侧边栏
|
||
- 响应式布局
|
||
- SPA 单页应用，History 路由模式
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端框架 | Vue 3 + TypeScript |
|
||
| UI 组件库 | Element Plus |
|
||
| 状态管理 | Pinia |
|
||
| 路由 | Vue Router 4 |
|
||
| 构建工具 | Vite |
|
||
| 后端框架 | FastAPI |
|
||
| ORM | SQLAlchemy |
|
||
| 数据库 | SQLite |
|
||
| ASGI 服务器 | Uvicorn |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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/ # 测试
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Python 3.10+
|
||
- Node.js 18+
|
||
- npm
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <your-repo-url>
|
||
cd ToDoList
|
||
|
||
# 2. 安装 Python 依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 一键启动（自动编译前端 + 启动后端）
|
||
python main.py
|
||
```
|
||
|
||
启动后访问：
|
||
- 前端页面：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` 为前缀，详细的请求/响应格式参见 [API_DOCS.md](./API_DOCS.md) 或访问 `/docs` 查看 Swagger 文档。
|
||
|
||
| 模块 | 前缀 | 说明 |
|
||
|------|------|------|
|
||
| 任务 | `/api/tasks` | 任务 CRUD、状态切换、批量操作 |
|
||
| 分类 | `/api/categories` | 分类 CRUD |
|
||
| 标签 | `/api/tags` | 标签 CRUD |
|
||
| 习惯 | `/api/habits` | 习惯、习惯组、打卡记录 |
|
||
| 纪念日 | `/api/anniversaries` | 纪念日、纪念日分类 |
|
||
| 资产 | `/api/accounts` | 账户、交易记录、分期还款 |
|
||
| 设置 | `/api/user-settings` | 用户偏好设置 |
|
||
| 健康检查 | `/health` | 服务状态检查 |
|
||
|
||
## 数据模型关系
|
||
|
||
```
|
||
Category ──< Task >── Tag
|
||
│
|
||
HabitGroup ──< Habit ──< HabitCheckin
|
||
|
||
AnniversaryCategory ──< Anniversary
|
||
|
||
FinancialAccount ──< AccountHistory
|
||
──< DebtInstallment
|
||
|
||
UserSettings （单例）
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
在 `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` | 允许的跨域来源 |
|
||
|
||
数据库文件和日志文件会在首次运行时自动创建，无需手动初始化。
|
||
|
||
## 部署
|
||
|
||
项目支持在 Windows 和 Linux 上运行。`main.py` 会自动处理平台差异（npm 命令、端口占用检测等）。
|
||
|
||
对于生产环境部署，建议：
|
||
- 使用 `gunicorn` + `uvicorn worker` 替代直接运行
|
||
- 配置反向代理（Nginx）
|
||
- 数据库可替换为 PostgreSQL 或 MySQL（修改 `config.py` 中的 `DATABASE_URL`）
|