ToDoList/API_DOCS.md

Elysia ToDo - 接口文档

爱莉希雅待办事项系统 RESTful API 接口文档 基础地址：http://localhost:23994 认证方式：无（所有接口均为公开访问）

---

目录

• 1. 健康检查
• 2. 任务管理 (Tasks)
• 3. 分类管理 (Categories)
• 4. 标签管理 (Tags)
• 5. 习惯组管理 (Habit Groups)
• 6. 习惯管理 (Habits)
• 7. 习惯打卡 (Habit Check-ins)
• 8. 纪念日分类 (Anniversary Categories)
• 9. 纪念日管理 (Anniversaries)
• 10. 财务账户 (Accounts)
• 11. 分期还款 (Debt Installments)
• 12. 用户设置 (User Settings)
• 附录：通用响应格式
• 附录：数据模型关系图

---

1. 健康检查

GET /health

服务健康检查接口，用于确认服务是否正常运行。

请求参数： 无

响应示例：

{
  "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（降序）

响应示例：

[
  {
    "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 列表

请求示例：

{
  "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

响应示例：

{
  "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

响应示例：

[
  {
    "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

成功响应：

{
  "success": true,
  "message": "分类已删除"
}

错误响应：

状态码	说明
400	该分类下存在关联任务，无法删除

---

4. 标签管理 (Tags)

GET /api/tags

获取标签列表。

查询参数：

参数	类型	必填	默认值	说明
skip	integer	否	0	跳过的记录数
limit	integer	否	100	每页记录数

响应示例：

[
  { "id": 1, "name": "重要" },
  { "id": 2, "name": "紧急" },
  { "id": 3, "name": "待审核" }
]

---

POST /api/tags

创建新标签。

请求体：

字段	类型	必填	说明
name	string	是	标签名称，最长 50 字符，全局唯一

请求示例：

{
  "name": "重要"
}

响应： HTTP 201 Created，返回 TagResponse 对象。

错误响应：

状态码	说明
400	标签名称已存在

注意： 标签不支持更新操作，如需修改请先删除再重新创建。

---

DELETE /api/tags/{tag_id}

删除标签，关联的任务-标签关系将自动解除。

路径参数：

参数	类型	说明
tag_id	integer	标签 ID

响应示例：

{
  "success": true,
  "message": "标签已删除"
}

---

5. 习惯组管理 (Habit Groups)

习惯组用于对习惯进行分组管理，类似于文件夹的概念。

GET /api/habit-groups

获取所有习惯组列表。

响应示例：

[
  {
    "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

响应示例：

{
  "success": true,
  "message": "习惯组已删除"
}

---

6. 习惯管理 (Habits)

GET /api/habits

获取习惯列表。

查询参数：

参数	类型	必填	默认值	说明
include_archived	boolean	否	false	是否包含已归档的习惯

响应示例：

[
  {
    "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

响应示例：

{
  "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）

响应示例：

[
  {
    "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）

响应示例：

{
  "success": true,
  "message": "打卡已取消"
}

---

GET /api/habits/{habit_id}/checkins/stats

获取习惯的统计数据。

路径参数：

参数	类型	说明
habit_id	integer	习惯 ID

响应示例：

{
  "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

获取所有纪念日分类列表。

响应示例：

[
  {
    "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

响应示例：

{
  "success": true,
  "message": "纪念日分类已删除"
}

---

9. 纪念日管理 (Anniversaries)

GET /api/anniversaries

获取纪念日列表，包含计算出的下次日期、剩余天数和第 N 次纪念日信息。结果按即将到来的日期排序。

查询参数：

参数	类型	必填	默认值	说明
category_id	integer	否	-	按分类 ID 筛选

响应示例：

[
  {
    "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

响应示例：

{
  "success": true,
  "message": "纪念日已删除"
}

---

10. 财务账户 (Accounts)

财务账户支持储蓄账户和债务账户两种类型。GET 列表接口会返回每个账户的分期还款汇总信息。

GET /api/accounts

获取所有财务账户列表。对于债务类型账户，installments 字段会包含分期还款计划摘要。

响应示例：

[
  {
    "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

响应示例：

{
  "success": true,
  "message": "账户已删除"
}

---

POST /api/accounts/{account_id}/balance

更新账户余额，自动创建余额变动历史记录。

路径参数：

参数	类型	说明
account_id	integer	账户 ID

请求体：

字段	类型	必填	说明
new_balance	number	是	新的余额值
note	string	否	变动备注，最长 200 字符

请求示例：

{
  "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

响应示例：

{
  "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

获取所有分期还款计划列表，包含计算字段，按紧急程度排序。

响应示例：

[
  {
    "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

响应示例：

{
  "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

获取用户设置。如果不存在，自动创建默认设置并返回。

响应示例：

{
  "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 对象。

---

附录：通用响应格式

成功响应

大部分接口返回具体数据对象或对象列表。部分接口（如删除操作）返回以下格式：

{
  "success": true,
  "message": "操作成功提示"
}

错误响应

状态码	说明
400	请求参数错误 / 业务逻辑错误（如重复名称、关联约束等）
404	资源不存在
422	请求体验证失败（Pydantic 校验错误）
500	服务器内部错误

422 错误响应示例：

{
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 错误响应示例：

{
  "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	更新用户设置