# 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` | 更新用户设置 |