---
url: /docs/api-docs/v1/goal.md
---
# goal API（目标系统）

> 路由：`POST /api/v1/goal`（action 协议：`{"action": "...", "payload": {...}}`）
> 错误码段：40407xxx（全表见[错误码权威注册表](/ai-contexts/error-code-registry)）
> 鉴权：全部需登录
> 字段真相：`src/app/goal/application/usecase/`（Request dataclass）+ `tests/integration/test_goal_actions.py`（可执行契约）

## Action 一览（14）

| action | 鉴权 | 说明 |
|---|---|---|
| `list` | 登录 | 目标列表（status asc + createdAt desc） |
| `add` | 登录 | 创建目标（周期自动算 / custom 必传） |
| `remove` | 登录 | 删除目标 |
| `pauseGoal` | 登录 | 暂停（仅 active/paused） |
| `resumeGoal` | 登录 | 恢复 |
| `myProgress` | 登录 | 我的进度 |
| `addFamilyGoal` | 登录 | 家庭目标（family 端口） |
| `myFamilyGoals` | 登录 | 家庭目标列表 |
| `addCustomMilestone` | 登录 | 自定义里程碑（上限 20 → km 唯一） |
| `removeCustomMilestone` | 登录 | 删除里程碑 |
| `listCustomMilestones` | 登录 | 里程碑列表 |
| `checkMilestoneAchievement` | 登录 | 达成检查（achievedAt 累计扫描） |
| `updateProgress` | 登录 | 手动进度（仅 health kind） |
| `recommend` | 登录 | 目标推荐（8 规则 + priority 排序） |

## 通用约定

* 信封：HTTP 200 + `{"code","msg","data"}`；`code="0"` 成功；`404407002` 未登录（HTTP 401）；`404407001` 参数错（HTTP 400）
* 写操作均落 audit/测试可断言（集成测试 = 可执行契约）

## 变更记录

| 日期 | 内容 |
|---|---|
| 2026-09-16 | 首版（四域审查棒 3 — action 清单代码直出）|