---
url: /docs/api-docs.md
---
# API Docs

面向前端开发者的 API 接口契约参考。

## 当前版本（v1）

| 域 | 说明 | 入口 |
|---|---|---|
| **OAuth** | 登录认证 9 action（captcha / sms-send / sms-verify / sms-login / callback / rotate / logout / bind-phone / unbind） | [→ v1/oauth/](/api-docs/v1/oauth/) |
| **Admin MIS** | 管理后台 82 use case / 12 子域（auth / dashboard / user / content / order / withdrawal / review / interpret / release / channel / config / misc） | [→ v1/admin/](/api-docs/v1/admin/) |
| **User** | C 端用户 11 action（onboarding / 绑定 / 邀请 / 会员 / 注销 — V1 action 协议） | [→ v1/user/actions](/api-docs/v1/user/actions) |
| **Device** | 设备线（共享 action + 授权中心四态 + honor / zepp 双厂商云 API） | [→ v1/device/](/api-docs/v1/device/) |

## 版本说明

知识库版本与 API 版本同步（Q26）。新增 v2 时此页会同步展开。

## 内容来源（Q28 三层自动）

| 内容 | 来源 |
|---|---|
| Action 字段表 | 契约权威 = 代码本体（路由文件 + usecase Request/Response dataclass），OpenAPI schema 自动生成 |
| 错误码矩阵（40101xxx / 40201xxx / 40301xxx / 4040xxxx） | AI 生成初稿 → 开发者 review |
| 状态机图（Mermaid） | AI 生成 → 开发者 review |
| 业务说明 / mock 差异 | AI 生成初稿 → 开发者 review |

## 协作约定

* **API 字段变更**必须先在 [Internal Wiki → OAuth 实施](/internal-wiki/architecture/oauth-implementation) / [Admin MIS 设计](/internal-wiki/architecture/admin-mis-design) 同步，再回写本文档
* **错误码新增**必须按 [错误码体系](/internal-wiki/architecture/error-codes) 的分配规则，避免码值冲突
  （区段隔离：OAuth `40101xxx` / admin `40201xxx` / user `40301xxx` / honor `40401xxx` / zepp `40402xxx` / device `40403xxx`）
* **状态机变更**必须同步更新 Redis key 设计 + TTL + Lua 脚本