API Docs

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

当前版本（v1）

域	说明	入口
OAuth	登录认证 9 action（captcha / sms-send / sms-verify / sms-login / callback / rotate / logout / bind-phone / unbind）	→ v1/oauth/
Admin MIS	管理后台 82 use case / 12 子域（auth / dashboard / user / content / order / withdrawal / review / interpret / release / channel / config / misc）	→ v1/admin/
User	C 端用户 11 action（onboarding / 绑定 / 邀请 / 会员 / 注销 — V1 action 协议）	→ v1/user/actions
Device	设备线（共享 action + 授权中心四态 + honor / zepp 双厂商云 API）	→ 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 实施 / Admin MIS 设计 同步，再回写本文档
• 错误码新增必须按 错误码体系 的分配规则，避免码值冲突 （区段隔离：OAuth 40101xxx / admin 40201xxx / user 40301xxx / honor 40401xxx / zepp 40402xxx / device 40403xxx）
• 状态机变更必须同步更新 Redis key 设计 + TTL + Lua 脚本