83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# Todo List 需求规格说明
|
||
|
||
## 项目简介
|
||
|
||
一个简约大方的 Todo List 单页应用，支持多层级待办事项管理（主任务/子任务/孙任务），数据存储于本地 JSON 文件，无需数据库和鉴权，适合个人服务器部署。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**：Node.js + Express，提供 RESTful API
|
||
- **前端**：原生 HTML/CSS/JS，无框架依赖
|
||
- **数据存储**：本地 JSON 文件（`data/todos.json`）
|
||
- **部署**：PM2 进程守护
|
||
- **运行环境**：Node.js ≥ 18
|
||
|
||
## 核心功能
|
||
|
||
### 1. 任务管理
|
||
|
||
- **创建主任务**：页面顶部提供一个 `+` 按钮和输入框，输入标题后点击确认按钮（✓）或按回车键即可创建
|
||
- **创建子任务**：每个主任务下方可添加子任务，子任务缩进一级
|
||
- **创建孙任务**：每个子任务下方可添加孙任务，孙任务缩进两级
|
||
- **层级限制**：最多支持三级（主/子/孙），不再支持更深层级
|
||
|
||
### 2. 任务状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `active` | 进行中（默认） |
|
||
| `completed` | 已完成 |
|
||
| `abandoned` | 已废弃 |
|
||
|
||
- **完成**：点击任务前的复选框即可标记完成，完成的任务文字添加删除线并变灰
|
||
- **废弃**：通过操作菜单将任务标记为废弃，废弃任务与已完成任务视觉区分（如使用不同颜色/图标）
|
||
- **级联完成**：当主任务被标记为完成时，其下所有子孙任务自动标记为已完成
|
||
- **恢复**：已完成/已废弃的任务可以恢复为进行中状态
|
||
|
||
### 3. 历史记录
|
||
|
||
- **历史面板**：可切换查看"进行中"和"历史记录"（已完成 + 已废弃）
|
||
- 历史记录按完成/废弃时间倒序排列
|
||
- 支持按状态筛选：全部 / 已完成 / 已废弃
|
||
- 历史记录中的任务不可编辑，仅可恢复或删除
|
||
|
||
### 4. 数据持久化
|
||
|
||
- 所有数据存储在 `data/todos.json` 文件中
|
||
- 服务启动时自动读取，每次数据变更时自动写入
|
||
- 文件写入采用防抖策略，避免频繁 I/O
|
||
- 如 JSON 文件损坏，自动备份并重建空数据
|
||
|
||
## 非功能需求
|
||
|
||
- **响应式设计**：适配桌面和移动端
|
||
- **无框架依赖**：前端使用原生 JavaScript，保持极简
|
||
- **部署简单**：`pnpm start` 或 `pm2 start` 一键启动
|
||
- **无鉴权**：不实现登录/鉴权，适合内网或个人 VPS 使用
|
||
|
||
## API 设计
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `GET` | `/api/todos` | 获取所有任务 |
|
||
| `POST` | `/api/todos` | 创建任务 |
|
||
| `PATCH` | `/api/todos/:id` | 更新任务（标题、状态） |
|
||
| `DELETE` | `/api/todos/:id` | 删除任务（级联删除子孙） |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
my-todo-list/
|
||
├── server.js # Express 服务入口
|
||
├── data/
|
||
│ └── todos.json # 数据文件（运行时生成）
|
||
├── public/
|
||
│ ├── index.html # 页面结构
|
||
│ ├── style.css # 样式
|
||
│ └── app.js # 前端逻辑
|
||
├── ecosystem.config.js # PM2 配置
|
||
├── package.json
|
||
├── README.md
|
||
└── spec.md
|
||
```
|