1581 lines
40 KiB
Markdown
1581 lines
40 KiB
Markdown
# Elysia ToDo - 接口文档
|
||
|
||
> 爱莉希雅待办事项系统 RESTful API 接口文档
|
||
> 基础地址：`http://localhost:23994`
|
||
> 认证方式：无（所有接口均为公开访问）
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [1. 健康检查](#1-健康检查)
|
||
- [2. 任务管理 (Tasks)](#2-任务管理-tasks)
|
||
- [3. 分类管理 (Categories)](#3-分类管理-categories)
|
||
- [4. 标签管理 (Tags)](#4-标签管理-tags)
|
||
- [5. 习惯组管理 (Habit Groups)](#5-习惯组管理-habit-groups)
|
||
- [6. 习惯管理 (Habits)](#6-习惯管理-habits)
|
||
- [7. 习惯打卡 (Habit Check-ins)](#7-习惯打卡-habit-check-ins)
|
||
- [8. 纪念日分类 (Anniversary Categories)](#8-纪念日分类-anniversary-categories)
|
||
- [9. 纪念日管理 (Anniversaries)](#9-纪念日管理-anniversaries)
|
||
- [10. 财务账户 (Accounts)](#10-财务账户-accounts)
|
||
- [11. 分期还款 (Debt Installments)](#11-分期还款-debt-installments)
|
||
- [12. 用户设置 (User Settings)](#12-用户设置-user-settings)
|
||
- [附录：通用响应格式](#附录通用响应格式)
|
||
- [附录：数据模型关系图](#附录数据模型关系图)
|
||
|
||
---
|
||
|
||
## 1. 健康检查
|
||
|
||
### `GET /health`
|
||
|
||
服务健康检查接口，用于确认服务是否正常运行。
|
||
|
||
**请求参数：** 无
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"message": "Elysia ToDo API is running!"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| status | string | 服务状态，`"ok"` 表示正常 |
|
||
| message | string | 服务描述信息 |
|
||
|
||
---
|
||
|
||
## 2. 任务管理 (Tasks)
|
||
|
||
### `GET /api/tasks`
|
||
|
||
获取任务列表，支持按状态、分类、优先级筛选和排序。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| status | string | 否 | `"all"` | 任务状态：`all`（全部）、`in_progress`（进行中）、`completed`（已完成） |
|
||
| category_id | integer | 否 | - | 按分类 ID 筛选 |
|
||
| priority | string | 否 | - | 按优先级筛选：`q1`（重要且紧急）、`q2`（重要不紧急）、`q3`（不重要但紧急）、`q4`（不重要不紧急） |
|
||
| sort_by | string | 否 | `"created_at"` | 排序字段：`created_at`、`priority`、`due_date` |
|
||
| sort_order | string | 否 | `"desc"` | 排序方向：`asc`（升序）、`desc`（降序） |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"title": "完成接口文档",
|
||
"description": "为项目编写完整的 API 接口文档",
|
||
"priority": "q1",
|
||
"due_date": "2026-03-15T00:00:00",
|
||
"is_completed": false,
|
||
"category_id": 2,
|
||
"created_at": "2026-03-14T10:00:00",
|
||
"updated_at": "2026-03-14T10:00:00",
|
||
"category": {
|
||
"id": 2,
|
||
"name": "工作",
|
||
"color": "#FF6B6B",
|
||
"icon": "briefcase"
|
||
},
|
||
"tags": [
|
||
{
|
||
"id": 1,
|
||
"name": "重要"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/tasks`
|
||
|
||
创建新任务。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| title | string | **是** | - | 任务标题，最长 200 字符 |
|
||
| description | string | 否 | null | 任务描述 |
|
||
| priority | string | 否 | `"q4"` | 优先级：`q1`、`q2`、`q3`、`q4` |
|
||
| due_date | string | 否 | null | 截止日期，ISO 8601 格式 |
|
||
| category_id | integer | 否 | null | 所属分类 ID |
|
||
| tag_ids | integer[] | 否 | [] | 关联标签 ID 列表 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"title": "完成接口文档",
|
||
"description": "为项目编写完整的 API 接口文档",
|
||
"priority": "q1",
|
||
"due_date": "2026-03-15T00:00:00",
|
||
"category_id": 2,
|
||
"tag_ids": [1, 3]
|
||
}
|
||
```
|
||
|
||
**响应：** HTTP `201 Created`，返回 `TaskResponse` 对象（格式同上）。
|
||
|
||
---
|
||
|
||
### `GET /api/tasks/{task_id}`
|
||
|
||
获取单个任务详情。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| task_id | integer | 任务 ID |
|
||
|
||
**响应：** 返回 `TaskResponse` 对象。
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 404 | 任务不存在 |
|
||
|
||
---
|
||
|
||
### `PUT /api/tasks/{task_id}`
|
||
|
||
更新任务信息（部分更新，只提交需要修改的字段）。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| task_id | integer | 任务 ID |
|
||
|
||
**请求体（所有字段均为可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| title | string | 任务标题 |
|
||
| description | string | 任务描述 |
|
||
| priority | string | 优先级：`q1`、`q2`、`q3`、`q4` |
|
||
| due_date | string | 截止日期 |
|
||
| is_completed | boolean | 是否完成 |
|
||
| category_id | integer | 所属分类 ID |
|
||
| tag_ids | integer[] | 关联标签 ID 列表 |
|
||
|
||
**响应：** 返回更新后的 `TaskResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/tasks/{task_id}`
|
||
|
||
删除任务。关联的标签关系将自动解除。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| task_id | integer | 任务 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `PATCH /api/tasks/{task_id}/toggle`
|
||
|
||
切换任务的完成状态（已完成 ↔ 未完成）。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| task_id | integer | 任务 ID |
|
||
|
||
**响应：** 返回更新后的 `TaskResponse` 对象，其中 `is_completed` 字段已被取反。
|
||
|
||
---
|
||
|
||
## 3. 分类管理 (Categories)
|
||
|
||
### `GET /api/categories`
|
||
|
||
获取分类列表，支持分页。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| skip | integer | 否 | 0 | 跳过的记录数 |
|
||
| limit | integer | 否 | 100 | 每页记录数，最大 100 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "工作",
|
||
"color": "#FF6B6B",
|
||
"icon": "briefcase"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "学习",
|
||
"color": "#4ECDC4",
|
||
"icon": "book"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/categories`
|
||
|
||
创建新分类。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| name | string | **是** | - | 分类名称，最长 100 字符 |
|
||
| color | string | 否 | `"#FFB7C5"` | 颜色值（十六进制） |
|
||
| icon | string | 否 | `"folder"` | 图标标识 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `CategoryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `PUT /api/categories/{category_id}`
|
||
|
||
更新分类信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category_id | integer | 分类 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | 分类名称 |
|
||
| color | string | 颜色值 |
|
||
| icon | string | 图标标识 |
|
||
|
||
**响应：** 返回更新后的 `CategoryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/categories/{category_id}`
|
||
|
||
删除分类。如果该分类下有关联的任务，将返回 400 错误。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category_id | integer | 分类 ID |
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "分类已删除"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 该分类下存在关联任务，无法删除 |
|
||
|
||
---
|
||
|
||
## 4. 标签管理 (Tags)
|
||
|
||
### `GET /api/tags`
|
||
|
||
获取标签列表。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| skip | integer | 否 | 0 | 跳过的记录数 |
|
||
| limit | integer | 否 | 100 | 每页记录数 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{ "id": 1, "name": "重要" },
|
||
{ "id": 2, "name": "紧急" },
|
||
{ "id": 3, "name": "待审核" }
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/tags`
|
||
|
||
创建新标签。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | **是** | 标签名称，最长 50 字符，全局唯一 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"name": "重要"
|
||
}
|
||
```
|
||
|
||
**响应：** HTTP `201 Created`，返回 `TagResponse` 对象。
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 标签名称已存在 |
|
||
|
||
> **注意：** 标签不支持更新操作，如需修改请先删除再重新创建。
|
||
|
||
---
|
||
|
||
### `DELETE /api/tags/{tag_id}`
|
||
|
||
删除标签，关联的任务-标签关系将自动解除。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| tag_id | integer | 标签 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "标签已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 习惯组管理 (Habit Groups)
|
||
|
||
习惯组用于对习惯进行分组管理，类似于文件夹的概念。
|
||
|
||
### `GET /api/habit-groups`
|
||
|
||
获取所有习惯组列表。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "健康",
|
||
"color": "#FF6B6B",
|
||
"icon": "heart",
|
||
"sort_order": 0
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "学习",
|
||
"color": "#4ECDC4",
|
||
"icon": "book",
|
||
"sort_order": 1
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/habit-groups`
|
||
|
||
创建新的习惯组。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| name | string | **是** | - | 组名称，最长 100 字符 |
|
||
| color | string | 否 | `"#FFB7C5"` | 颜色值 |
|
||
| icon | string | 否 | `"flag"` | 图标标识 |
|
||
| sort_order | integer | 否 | 0 | 排序顺序 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `HabitGroupResponse` 对象。
|
||
|
||
---
|
||
|
||
### `PUT /api/habit-groups/{group_id}`
|
||
|
||
更新习惯组信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| group_id | integer | 习惯组 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | 组名称 |
|
||
| color | string | 颜色值 |
|
||
| icon | string | 图标标识 |
|
||
| sort_order | integer | 排序顺序 |
|
||
|
||
**响应：** 返回更新后的 `HabitGroupResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/habit-groups/{group_id}`
|
||
|
||
删除习惯组。组内的习惯不会被删除，但其 `group_id` 将被设为 `null`。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| group_id | integer | 习惯组 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "习惯组已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 习惯管理 (Habits)
|
||
|
||
### `GET /api/habits`
|
||
|
||
获取习惯列表。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| include_archived | boolean | 否 | false | 是否包含已归档的习惯 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "每日阅读",
|
||
"description": "至少阅读 30 分钟",
|
||
"group_id": 2,
|
||
"target_count": 1,
|
||
"frequency": "daily",
|
||
"active_days": "[0,1,2,3,4,5,6]",
|
||
"is_archived": false,
|
||
"created_at": "2026-03-01T00:00:00",
|
||
"updated_at": "2026-03-14T00:00:00",
|
||
"group": {
|
||
"id": 2,
|
||
"name": "学习",
|
||
"color": "#4ECDC4",
|
||
"icon": "book",
|
||
"sort_order": 1
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
**HabitResponse 字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | integer | 习惯 ID |
|
||
| name | string | 习惯名称 |
|
||
| description | string\|null | 习惯描述 |
|
||
| group_id | integer\|null | 所属习惯组 ID |
|
||
| target_count | integer | 每日/每周目标次数（≥1） |
|
||
| frequency | string | 频率：`daily`（每日）、`weekly`（每周） |
|
||
| active_days | string\|null | 活跃日期（JSON 数组），如 `"[0,2,4]"` 表示周一/三/五（0=周一，6=周日） |
|
||
| is_archived | boolean | 是否已归档 |
|
||
| created_at | datetime | 创建时间 |
|
||
| updated_at | datetime | 更新时间 |
|
||
| group | object\|null | 关联的习惯组信息 |
|
||
|
||
---
|
||
|
||
### `POST /api/habits`
|
||
|
||
创建新习惯。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| name | string | **是** | - | 习惯名称，最长 200 字符 |
|
||
| description | string | 否 | null | 习惯描述 |
|
||
| group_id | integer | 否 | null | 所属习惯组 ID |
|
||
| target_count | integer | 否 | 1 | 目标次数（≥1） |
|
||
| frequency | string | 否 | `"daily"` | 频率：`daily`、`weekly` |
|
||
| active_days | string | 否 | null | 活跃日期（JSON 数组字符串） |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `HabitResponse` 对象。
|
||
|
||
---
|
||
|
||
### `PUT /api/habits/{habit_id}`
|
||
|
||
更新习惯信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | 习惯名称 |
|
||
| description | string | 习惯描述 |
|
||
| group_id | integer | 所属习惯组 ID |
|
||
| target_count | integer | 目标次数 |
|
||
| frequency | string | 频率 |
|
||
| active_days | string | 活跃日期 |
|
||
|
||
**响应：** 返回更新后的 `HabitResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/habits/{habit_id}`
|
||
|
||
删除习惯，关联的打卡记录将一并被级联删除。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "习惯已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `PATCH /api/habits/{habit_id}/archive`
|
||
|
||
切换习惯的归档状态。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**响应：** 返回更新后的 `HabitResponse` 对象，`is_archived` 字段已被取反。
|
||
|
||
---
|
||
|
||
## 7. 习惯打卡 (Habit Check-ins)
|
||
|
||
### `GET /api/habits/{habit_id}/checkins`
|
||
|
||
获取习惯的打卡记录。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| from_date | string | 否 | - | 起始日期（YYYY-MM-DD） |
|
||
| to_date | string | 否 | - | 结束日期（YYYY-MM-DD） |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"habit_id": 1,
|
||
"checkin_date": "2026-03-14",
|
||
"count": 2,
|
||
"created_at": "2026-03-14T08:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/habits/{habit_id}/checkins`
|
||
|
||
进行打卡。如果当天已有打卡记录，将累加 `count`；否则创建新记录。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| count | integer | 否 | 1 | 本次打卡次数 |
|
||
|
||
**响应：** 返回 `CheckinResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/habits/{habit_id}/checkins`
|
||
|
||
取消打卡（减少当天打卡次数）。如果次数减至 0，将删除该天的打卡记录。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| count | integer | 否 | 1 | 要减少的次数（≥1） |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "打卡已取消"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `GET /api/habits/{habit_id}/checkins/stats`
|
||
|
||
获取习惯的统计数据。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| habit_id | integer | 习惯 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"total_days": 42,
|
||
"current_streak": 7,
|
||
"longest_streak": 15,
|
||
"today_count": 1,
|
||
"today_completed": true
|
||
}
|
||
```
|
||
|
||
**HabitStatsResponse 字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| total_days | integer | 总打卡天数 |
|
||
| current_streak | integer | 当前连续打卡天数 |
|
||
| longest_streak | integer | 最长连续打卡天数 |
|
||
| today_count | integer | 今日已打卡次数 |
|
||
| today_completed | boolean | 今日目标是否已完成 |
|
||
|
||
---
|
||
|
||
## 8. 纪念日分类 (Anniversary Categories)
|
||
|
||
纪念日分类用于对纪念日进行分组管理。
|
||
|
||
### `GET /api/anniversary-categories`
|
||
|
||
获取所有纪念日分类列表。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "生日",
|
||
"icon": "cake",
|
||
"color": "#FF6B6B",
|
||
"sort_order": 0
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "节日",
|
||
"icon": "star",
|
||
"color": "#FFD93D",
|
||
"sort_order": 1
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/anniversary-categories`
|
||
|
||
创建新的纪念日分类。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| name | string | **是** | - | 分类名称，最长 50 字符 |
|
||
| icon | string | 否 | `"calendar"` | 图标标识 |
|
||
| color | string | 否 | `"#FFB7C5"` | 颜色值 |
|
||
| sort_order | integer | 否 | 0 | 排序顺序 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `AnniversaryCategoryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `PUT /api/anniversary-categories/{category_id}`
|
||
|
||
更新纪念日分类信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category_id | integer | 纪念日分类 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | 分类名称 |
|
||
| icon | string | 图标标识 |
|
||
| color | string | 颜色值 |
|
||
| sort_order | integer | 排序顺序 |
|
||
|
||
**响应：** 返回更新后的 `AnniversaryCategoryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/anniversary-categories/{category_id}`
|
||
|
||
删除纪念日分类。分类下的纪念日不会被删除，但其 `category_id` 将被设为 `null`。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category_id | integer | 纪念日分类 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "纪念日分类已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 纪念日管理 (Anniversaries)
|
||
|
||
### `GET /api/anniversaries`
|
||
|
||
获取纪念日列表，包含计算出的下次日期、剩余天数和第 N 次纪念日信息。结果按即将到来的日期排序。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| category_id | integer | 否 | - | 按分类 ID 筛选 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"title": "爱莉希雅生日",
|
||
"date": "2020-03-14",
|
||
"year": 2020,
|
||
"category_id": 1,
|
||
"description": "最重要的日子！",
|
||
"is_recurring": true,
|
||
"remind_days_before": 3,
|
||
"created_at": "2026-01-01T00:00:00",
|
||
"updated_at": "2026-01-01T00:00:00",
|
||
"category": {
|
||
"id": 1,
|
||
"name": "生日",
|
||
"icon": "cake",
|
||
"color": "#FF6B6B",
|
||
"sort_order": 0
|
||
},
|
||
"next_date": "2026-03-14",
|
||
"days_until": 0,
|
||
"year_count": 6
|
||
}
|
||
]
|
||
```
|
||
|
||
**计算字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| next_date | date\|null | 下一次纪念日日期 |
|
||
| days_until | integer\|null | 距离下一次纪念日的天数 |
|
||
| year_count | integer\|null | 第几次纪念日（从原始年份起算） |
|
||
|
||
---
|
||
|
||
### `POST /api/anniversaries`
|
||
|
||
创建新的纪念日。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| title | string | **是** | - | 纪念日标题，最长 200 字符 |
|
||
| date | string | **是** | - | 日期（YYYY-MM-DD） |
|
||
| year | integer | 否 | null | 原始年份，用于计算第 N 次 |
|
||
| category_id | integer | 否 | null | 所属分类 ID |
|
||
| description | string | 否 | null | 描述信息 |
|
||
| is_recurring | boolean | 否 | true | 是否每年重复 |
|
||
| remind_days_before | integer | 否 | 3 | 提前几天提醒 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `AnniversaryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `GET /api/anniversaries/{anniversary_id}`
|
||
|
||
获取单个纪念日详情。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| anniversary_id | integer | 纪念日 ID |
|
||
|
||
**响应：** 返回 `AnniversaryResponse` 对象（含计算字段）。
|
||
|
||
---
|
||
|
||
### `PUT /api/anniversaries/{anniversary_id}`
|
||
|
||
更新纪念日信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| anniversary_id | integer | 纪念日 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| title | string | 纪念日标题 |
|
||
| date | string | 日期 |
|
||
| year | integer | 原始年份 |
|
||
| category_id | integer | 所属分类 ID |
|
||
| description | string | 描述信息 |
|
||
| is_recurring | boolean | 是否每年重复 |
|
||
| remind_days_before | integer | 提前几天提醒 |
|
||
|
||
**响应：** 返回更新后的 `AnniversaryResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/anniversaries/{anniversary_id}`
|
||
|
||
删除纪念日。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| anniversary_id | integer | 纪念日 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "纪念日已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 财务账户 (Accounts)
|
||
|
||
财务账户支持储蓄账户和债务账户两种类型。GET 列表接口会返回每个账户的分期还款汇总信息。
|
||
|
||
### `GET /api/accounts`
|
||
|
||
获取所有财务账户列表。对于债务类型账户，`installments` 字段会包含分期还款计划摘要。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "招商银行储蓄卡",
|
||
"account_type": "savings",
|
||
"balance": 15000.00,
|
||
"icon": "bank",
|
||
"color": "#FF6B6B",
|
||
"sort_order": 0,
|
||
"is_active": true,
|
||
"description": "日常储蓄",
|
||
"created_at": "2026-01-01T00:00:00",
|
||
"updated_at": "2026-03-14T00:00:00",
|
||
"installments": []
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "信用卡",
|
||
"account_type": "debt",
|
||
"balance": -5000.00,
|
||
"icon": "credit-card",
|
||
"color": "#4ECDC4",
|
||
"sort_order": 1,
|
||
"is_active": true,
|
||
"description": null,
|
||
"created_at": "2026-01-01T00:00:00",
|
||
"updated_at": "2026-03-14T00:00:00",
|
||
"installments": [
|
||
{
|
||
"id": 1,
|
||
"total_amount": 6000.0,
|
||
"remaining_periods": 5,
|
||
"next_payment_date": "2026-04-15",
|
||
"days_until_payment": 32
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/accounts`
|
||
|
||
创建新的财务账户。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| name | string | **是** | - | 账户名称，最长 100 字符 |
|
||
| account_type | string | 否 | `"savings"` | 账户类型：`savings`（储蓄）、`debt`（债务） |
|
||
| balance | number | 否 | 0.0 | 初始余额 |
|
||
| icon | string | 否 | `"wallet"` | 图标标识 |
|
||
| color | string | 否 | `"#FFB7C5"` | 颜色值 |
|
||
| sort_order | integer | 否 | 0 | 排序顺序 |
|
||
| is_active | boolean | 否 | true | 是否启用 |
|
||
| description | string | 否 | null | 描述信息 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `AccountResponse` 对象。
|
||
|
||
---
|
||
|
||
### `GET /api/accounts/{account_id}`
|
||
|
||
获取单个账户详情。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 账户 ID |
|
||
|
||
**响应：** 返回 `AccountResponse` 对象。
|
||
|
||
---
|
||
|
||
### `PUT /api/accounts/{account_id}`
|
||
|
||
更新账户信息。
|
||
|
||
> **注意：** 此接口不支持直接修改余额，余额请通过 `POST /api/accounts/{id}/balance` 修改。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 账户 ID |
|
||
|
||
**请求体（所有字段可选，**不包含 balance**）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | string | 账户名称 |
|
||
| account_type | string | 账户类型 |
|
||
| icon | string | 图标标识 |
|
||
| color | string | 颜色值 |
|
||
| sort_order | integer | 排序顺序 |
|
||
| is_active | boolean | 是否启用 |
|
||
| description | string | 描述信息 |
|
||
|
||
**响应：** 返回更新后的 `AccountResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/accounts/{account_id}`
|
||
|
||
删除账户，关联的历史记录和分期还款计划将一并被级联删除。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 账户 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "账户已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/accounts/{account_id}/balance`
|
||
|
||
更新账户余额，自动创建余额变动历史记录。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 账户 ID |
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| new_balance | number | **是** | 新的余额值 |
|
||
| note | string | 否 | 变动备注，最长 200 字符 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"new_balance": 16000.00,
|
||
"note": "工资到账"
|
||
}
|
||
```
|
||
|
||
**响应：** 返回更新后的 `AccountResponse` 对象。同时会自动在 `account_history` 表中创建一条记录。
|
||
|
||
---
|
||
|
||
### `GET /api/accounts/{account_id}/history`
|
||
|
||
获取账户的余额变动历史，支持分页。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 账户 ID |
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| page | integer | 否 | 1 | 页码（从 1 开始） |
|
||
| page_size | integer | 否 | 20 | 每页记录数，最大 100 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"total": 15,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"records": [
|
||
{
|
||
"id": 15,
|
||
"account_id": 1,
|
||
"change_amount": 1000.0,
|
||
"balance_before": 15000.0,
|
||
"balance_after": 16000.0,
|
||
"note": "工资到账",
|
||
"created_at": "2026-03-14T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**AccountHistoryResponse 字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | integer | 记录 ID |
|
||
| account_id | integer | 账户 ID |
|
||
| change_amount | number | 变动金额（正数=收入，负数=支出） |
|
||
| balance_before | number | 变动前余额 |
|
||
| balance_after | number | 变动后余额 |
|
||
| note | string\|null | 变动备注 |
|
||
| created_at | datetime | 记录时间 |
|
||
|
||
---
|
||
|
||
## 11. 分期还款 (Debt Installments)
|
||
|
||
分期还款计划仅与 `account_type` 为 `debt` 的账户关联。GET 列表接口会返回计算出的下次还款日期、剩余天数和剩余期数等字段。
|
||
|
||
### `GET /api/debt-installments`
|
||
|
||
获取所有分期还款计划列表，包含计算字段，按紧急程度排序。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"account_id": 2,
|
||
"total_amount": 6000.0,
|
||
"total_periods": 12,
|
||
"current_period": 8,
|
||
"payment_day": 15,
|
||
"payment_amount": 500.0,
|
||
"start_date": "2025-09-15",
|
||
"is_completed": false,
|
||
"created_at": "2025-09-01T00:00:00",
|
||
"updated_at": "2026-03-01T00:00:00",
|
||
"next_payment_date": "2026-04-15",
|
||
"days_until_payment": 32,
|
||
"remaining_periods": 5,
|
||
"account_name": "信用卡",
|
||
"account_icon": "credit-card",
|
||
"account_color": "#4ECDC4"
|
||
}
|
||
]
|
||
```
|
||
|
||
**计算字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| next_payment_date | date\|null | 下一次还款日期 |
|
||
| days_until_payment | integer\|null | 距离下次还款的天数 |
|
||
| remaining_periods | integer\|null | 剩余还款期数 |
|
||
| account_name | string\|null | 关联账户名称 |
|
||
| account_icon | string\|null | 关联账户图标 |
|
||
| account_color | string\|null | 关联账户颜色 |
|
||
|
||
---
|
||
|
||
### `POST /api/debt-installments`
|
||
|
||
创建新的分期还款计划。
|
||
|
||
**请求体：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| account_id | integer | **是** | - | 关联的债务账户 ID |
|
||
| total_amount | number | **是** | - | 总金额 |
|
||
| total_periods | integer | **是** | - | 总期数 |
|
||
| current_period | integer | 否 | 1 | 当前期数（从 1 开始，指向下一期未还） |
|
||
| payment_day | integer | **是** | - | 每月还款日（1-31） |
|
||
| payment_amount | number | **是** | - | 每期还款金额 |
|
||
| start_date | string | **是** | - | 起始日期（YYYY-MM-DD） |
|
||
| is_completed | boolean | 否 | false | 是否已完成 |
|
||
|
||
**响应：** HTTP `201 Created`，返回 `DebtInstallmentResponse` 对象。
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 关联账户不是债务类型（`account_type` 不为 `debt`） |
|
||
|
||
---
|
||
|
||
### `PUT /api/debt-installments/{installment_id}`
|
||
|
||
更新分期还款计划。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| installment_id | integer | 分期计划 ID |
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| account_id | integer | 关联账户 ID |
|
||
| total_amount | number | 总金额 |
|
||
| total_periods | integer | 总期数 |
|
||
| current_period | integer | 当前期数 |
|
||
| payment_day | integer | 每月还款日 |
|
||
| payment_amount | number | 每期还款金额 |
|
||
| start_date | string | 起始日期 |
|
||
| is_completed | boolean | 是否已完成 |
|
||
|
||
**响应：** 返回更新后的 `DebtInstallmentResponse` 对象。
|
||
|
||
---
|
||
|
||
### `DELETE /api/debt-installments/{installment_id}`
|
||
|
||
删除分期还款计划。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| installment_id | integer | 分期计划 ID |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "分期计划已删除"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `PATCH /api/debt-installments/{installment_id}/pay`
|
||
|
||
标记一期为已还款。`current_period` 递增 1，如果所有期数都已还完，自动将 `is_completed` 设为 `true`。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| installment_id | integer | 分期计划 ID |
|
||
|
||
**响应：** 返回更新后的 `DebtInstallmentResponse` 对象。
|
||
|
||
**错误响应：**
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 分期计划已全部还完 |
|
||
|
||
---
|
||
|
||
## 12. 用户设置 (User Settings)
|
||
|
||
用户设置为单例模式，全局只有一条记录（`id=1`）。首次访问时自动创建默认设置。
|
||
|
||
### `GET /api/user-settings`
|
||
|
||
获取用户设置。如果不存在，自动创建默认设置并返回。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"nickname": "爱莉希雅",
|
||
"avatar": null,
|
||
"signature": "美好的一天从微笑开始~",
|
||
"birthday": "2020-03-14",
|
||
"email": null,
|
||
"site_name": "爱莉希雅待办",
|
||
"theme": "pink",
|
||
"language": "zh-CN",
|
||
"default_view": "list",
|
||
"default_sort_by": "created_at",
|
||
"default_sort_order": "desc",
|
||
"created_at": "2026-01-01T00:00:00",
|
||
"updated_at": "2026-03-14T00:00:00"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| id | integer | 1 | 固定为 1 |
|
||
| nickname | string | `"爱莉希雅"` | 用户昵称 |
|
||
| avatar | string\|null | null | 头像 URL |
|
||
| signature | string\|null | null | 个性签名 |
|
||
| birthday | date\|null | null | 生日 |
|
||
| email | string\|null | null | 邮箱 |
|
||
| site_name | string | `"爱莉希雅待办"` | 站点名称 |
|
||
| theme | string | `"pink"` | 主题 |
|
||
| language | string | `"zh-CN"` | 语言 |
|
||
| default_view | string | `"list"` | 默认视图 |
|
||
| default_sort_by | string | `"created_at"` | 默认排序字段 |
|
||
| default_sort_order | string | `"desc"` | 默认排序方向 |
|
||
|
||
---
|
||
|
||
### `PUT /api/user-settings`
|
||
|
||
更新用户设置（upsert 模式，不存在则创建）。
|
||
|
||
**请求体（所有字段可选）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| nickname | string | 用户昵称 |
|
||
| avatar | string | 头像 URL |
|
||
| signature | string | 个性签名 |
|
||
| birthday | string | 生日（YYYY-MM-DD） |
|
||
| email | string | 邮箱 |
|
||
| site_name | string | 站点名称 |
|
||
| theme | string | 主题 |
|
||
| language | string | 语言 |
|
||
| default_view | string | 默认视图 |
|
||
| default_sort_by | string | 默认排序字段 |
|
||
| default_sort_order | string | 默认排序方向 |
|
||
|
||
**响应：** 返回更新后的 `UserSettingsResponse` 对象。
|
||
|
||
---
|
||
|
||
## 附录：通用响应格式
|
||
|
||
### 成功响应
|
||
|
||
大部分接口返回具体数据对象或对象列表。部分接口（如删除操作）返回以下格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功提示"
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 请求参数错误 / 业务逻辑错误（如重复名称、关联约束等） |
|
||
| 404 | 资源不存在 |
|
||
| 422 | 请求体验证失败（Pydantic 校验错误） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
**422 错误响应示例：**
|
||
|
||
```json
|
||
{
|
||
"detail": [
|
||
{
|
||
"loc": ["body", "title"],
|
||
"msg": "field required",
|
||
"type": "value_error.missing"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**500 错误响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "服务器内部错误",
|
||
"error_code": "INTERNAL_ERROR"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：数据模型关系图
|
||
|
||
```
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ categories │ 1───N │ tasks │ N───M │ tags │
|
||
│──────────────│ │──────────────│ │──────────────│
|
||
│ id │ │ id │ │ id │
|
||
│ name │ │ title │ │ name (unique)│
|
||
│ color │ │ description │ └──────────────┘
|
||
│ icon │ │ priority │
|
||
└──────────────┘ │ due_date │ ┌──────────────┐
|
||
│ is_completed │ │ task_tags │
|
||
│ category_id ─┤ │──────────────│
|
||
│ created_at │ │ task_id (PK) │
|
||
│ updated_at │ │ tag_id (PK) │
|
||
└──────────────┘ └──────────────┘
|
||
|
||
┌──────────────┐ 1───N ┌──────────────┐ 1───N ┌────────────────┐
|
||
│habit_groups │ │ habits │ │ habit_checkins │
|
||
│──────────────│ │──────────────│ │────────────────│
|
||
│ id │ │ id │ │ id │
|
||
│ name │ │ name │ │ habit_id (FK) │
|
||
│ color │ │ description │ │ checkin_date │
|
||
│ icon │ │ group_id ────│ │ count │
|
||
│ sort_order │ │ target_count │ │ created_at │
|
||
└──────────────┘ │ frequency │ └────────────────┘
|
||
│ active_days │
|
||
│ is_archived │
|
||
└──────────────┘
|
||
|
||
┌────────────────────┐ 1───N ┌────────────────┐
|
||
│anniversary_ │ │ anniversaries │
|
||
│categories │ │────────────────│
|
||
│────────────────────│ │ id │
|
||
│ id │ │ title │
|
||
│ name │ │ date │
|
||
│ icon │ │ year │
|
||
│ color │ │ category_id ───│
|
||
│ sort_order │ │ description │
|
||
└────────────────────┘ │ is_recurring │
|
||
│ remind_days_ │
|
||
│ before │
|
||
└────────────────┘
|
||
|
||
┌──────────────────┐ 1───N ┌────────────────┐
|
||
│financial_accounts│ │account_history │
|
||
│──────────────────│ │────────────────│
|
||
│ id │ │ id │
|
||
│ name │ │ account_id ────│
|
||
│ account_type │ │ change_amount │
|
||
│ balance │ │ balance_before │
|
||
│ icon │ │ balance_after │
|
||
│ color │ │ note │
|
||
│ sort_order │ │ created_at │
|
||
│ is_active │ └────────────────┘
|
||
│ description │
|
||
└──────────────────┘
|
||
│ 1───N ┌────────────────┐
|
||
│debt_installments │
|
||
│────────────────│
|
||
│ id │
|
||
│ account_id ────│
|
||
│ total_amount │
|
||
│ total_periods │
|
||
│ current_period │
|
||
│ payment_day │
|
||
│ payment_amount │
|
||
│ start_date │
|
||
│ is_completed │
|
||
└────────────────┘
|
||
|
||
┌──────────────────┐
|
||
│ user_settings │ (单例, id=1)
|
||
│──────────────────│
|
||
│ id │
|
||
│ nickname │
|
||
│ avatar │
|
||
│ signature │
|
||
│ birthday │
|
||
│ email │
|
||
│ site_name │
|
||
│ theme │
|
||
│ language │
|
||
│ default_view │
|
||
│ default_sort_by │
|
||
│ default_sort_order│
|
||
└──────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 接口总览（共 50 个接口）
|
||
|
||
| # | 方法 | 路径 | 功能 |
|
||
|---|------|------|------|
|
||
| 1 | GET | `/health` | 健康检查 |
|
||
| 2 | GET | `/api/tasks` | 获取任务列表 |
|
||
| 3 | POST | `/api/tasks` | 创建任务 |
|
||
| 4 | GET | `/api/tasks/{id}` | 获取任务详情 |
|
||
| 5 | PUT | `/api/tasks/{id}` | 更新任务 |
|
||
| 6 | DELETE | `/api/tasks/{id}` | 删除任务 |
|
||
| 7 | PATCH | `/api/tasks/{id}/toggle` | 切换任务完成状态 |
|
||
| 8 | GET | `/api/categories` | 获取分类列表 |
|
||
| 9 | POST | `/api/categories` | 创建分类 |
|
||
| 10 | PUT | `/api/categories/{id}` | 更新分类 |
|
||
| 11 | DELETE | `/api/categories/{id}` | 删除分类 |
|
||
| 12 | GET | `/api/tags` | 获取标签列表 |
|
||
| 13 | POST | `/api/tags` | 创建标签 |
|
||
| 14 | DELETE | `/api/tags/{id}` | 删除标签 |
|
||
| 15 | GET | `/api/habit-groups` | 获取习惯组列表 |
|
||
| 16 | POST | `/api/habit-groups` | 创建习惯组 |
|
||
| 17 | PUT | `/api/habit-groups/{id}` | 更新习惯组 |
|
||
| 18 | DELETE | `/api/habit-groups/{id}` | 删除习惯组 |
|
||
| 19 | GET | `/api/habits` | 获取习惯列表 |
|
||
| 20 | POST | `/api/habits` | 创建习惯 |
|
||
| 21 | PUT | `/api/habits/{id}` | 更新习惯 |
|
||
| 22 | DELETE | `/api/habits/{id}` | 删除习惯 |
|
||
| 23 | PATCH | `/api/habits/{id}/archive` | 切换习惯归档状态 |
|
||
| 24 | GET | `/api/habits/{id}/checkins` | 获取打卡记录 |
|
||
| 25 | POST | `/api/habits/{id}/checkins` | 打卡 |
|
||
| 26 | DELETE | `/api/habits/{id}/checkins` | 取消打卡 |
|
||
| 27 | GET | `/api/habits/{id}/checkins/stats` | 获取习惯统计 |
|
||
| 28 | GET | `/api/anniversary-categories` | 获取纪念日分类列表 |
|
||
| 29 | POST | `/api/anniversary-categories` | 创建纪念日分类 |
|
||
| 30 | PUT | `/api/anniversary-categories/{id}` | 更新纪念日分类 |
|
||
| 31 | DELETE | `/api/anniversary-categories/{id}` | 删除纪念日分类 |
|
||
| 32 | GET | `/api/anniversaries` | 获取纪念日列表 |
|
||
| 33 | POST | `/api/anniversaries` | 创建纪念日 |
|
||
| 34 | GET | `/api/anniversaries/{id}` | 获取纪念日详情 |
|
||
| 35 | PUT | `/api/anniversaries/{id}` | 更新纪念日 |
|
||
| 36 | DELETE | `/api/anniversaries/{id}` | 删除纪念日 |
|
||
| 37 | GET | `/api/accounts` | 获取账户列表 |
|
||
| 38 | POST | `/api/accounts` | 创建账户 |
|
||
| 39 | GET | `/api/accounts/{id}` | 获取账户详情 |
|
||
| 40 | PUT | `/api/accounts/{id}` | 更新账户 |
|
||
| 41 | DELETE | `/api/accounts/{id}` | 删除账户 |
|
||
| 42 | POST | `/api/accounts/{id}/balance` | 更新余额 |
|
||
| 43 | GET | `/api/accounts/{id}/history` | 获取余额变动历史 |
|
||
| 44 | GET | `/api/debt-installments` | 获取分期还款列表 |
|
||
| 45 | POST | `/api/debt-installments` | 创建分期还款计划 |
|
||
| 46 | PUT | `/api/debt-installments/{id}` | 更新分期还款计划 |
|
||
| 47 | DELETE | `/api/debt-installments/{id}` | 删除分期还款计划 |
|
||
| 48 | PATCH | `/api/debt-installments/{id}/pay` | 标记一期为已还 |
|
||
| 49 | GET | `/api/user-settings` | 获取用户设置 |
|
||
| 50 | PUT | `/api/user-settings` | 更新用户设置 |
|