---
url: /docs/api-docs/v1/shoes.md
---
# shoes API（跑鞋库）

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

## Action 一览（9）

| action | 鉴权 | 说明 |
|---|---|---|
| `list` | 登录 | 我的跑鞋列表（healthRatio/remainingKm 派生） |
| `add` | 登录 | 添加跑鞋 |
| `update` | 登录 | 更新跑鞋信息 |
| `retire` | 登录 | 退役（retiringSoon 70% 阈值判定依据） |
| `myStats` | 登录 | 跑鞋统计（healthMap） |
| `getDetail` | 登录 | 跑鞋详情 |
| `getMileageHistory` | 登录 | 里程历史 |
| `updateThreshold` | 登录 | 更新里程预警阈值 |
| `compareShoes` | 登录 | 双鞋对比（须本人 2 双） |

## 通用约定

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

## 变更记录

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