---
url: /docs/api-docs/v1/capabilities.md
---
# 按功能浏览 —— 11 大功能类（业务能力聚合）

> 归属：API Docs → v1 → **按功能浏览**
> 定位：**门面页** —— 按业务能力聚合的找路入口；端点 / 字段 / 错误码的权威细节不在此页
> 相关：[前端联调手册（30 端点）](/api-docs/v1/frontend/) · [错误码权威注册表](/ai-contexts/error-code-registry) · [模块手册](/modules/)

**这一页和域目录是什么关系？** 域目录是**明细** —— 按后端模块组织（oauth / user / device / …），端点、字段、错误码的权威细节都在那边；本页是**门面** —— 按业务能力把 34 个域聚合成 11 个大类，方便**按功能找接口**：先问「这是哪块功能」（如「钱包、积分、优惠券都归资产与交易」），再点进域页看明细。**字段表一个字都不复制** —— 同一份事实只有一个维护处，两边不会不同步。

## 11 大功能类总览

| 功能大类 | 包含域 |
|---|---|
| [认证与会话](#认证与会话) | `oauth` |
| [用户与画像](#用户与画像) | `user` |
| [设备与健康数据](#设备与健康数据) | `device` / `honor` / `zepp` / `xiaomi` / `suunto` |
| [运动与记录](#运动与记录) | `sport` / `shoes` / `upload` |
| [训练与目标](#训练与目标) | `training` / `goal` |
| [资产与交易](#资产与交易) | `wallet` / `points` / `coupon` / `cart` / `mall` / `group_buy` / `distribution` |
| [社区互动](#社区互动) | `feed` / `follow` / `favorite` / `review` |
| [内容与运营](#内容与运营) | `agreement` / `ad` / `splash-screen` / `recipe` / `food` / `boohee` |
| [数据与统计](#数据与统计) | `stats` / `ranking` / `kb` |
| [运营后台](#运营后台) | `admin` |
| [研发管理](#研发管理) | `rd` |

***

## 认证与会话

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `oauth` | [OAuth 登录认证](/api-docs/v1/oauth/) | 登录/注册/会话一条链：图形码 + 短信登录 + 双 token 轮换（`rotate`）+ 会话列表/吊销。9 action 统一入口 `POST /api/v1/auth/oauth`，错误走 HTTP 200 + `40101xxx` 业务码 |

## 用户与画像

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `user` | [User · 15 Action 字段表](/api-docs/v1/user/actions) | C 端用户主数据 + 画像：资料/昵称读写、onboarding 四维向导（提交/建议/采纳）、`myProfile` 读画像。统一入口 `POST /api/v1/user` |

## 设备与健康数据

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `device` | [device 共享域](/api-docs/v1/device/) | 设备绑定/解绑 + 今日健康数据查询（action 协议）+ 授权中心（vendors 四态状态机）—— **接入任何厂商先读这页** |
| `honor` | [honor 荣耀](/api-docs/v1/device/honor) | 荣耀健康云：发起授权（M1）/ 回调（M2）/ 三接口健康数据同步 + 双层 job |
| `zepp` | [zepp](/api-docs/v1/device/zepp) | Zepp 云：三端 OAuth + webhook 六事件 + legacy 回调 + 每日同步 job |
| `xiaomi` | [xiaomi 小米](/api-docs/v1/device/xiaomi) | 小米运动健康云：OAuth 授权 + 官方 webhook 推送（callback / webhook 均公开，以验签鉴权） |
| `suunto` | [Suunto](/api-docs/v1/suunto/) | Suunto 云 API（APIM 双 header + webhook）—— 走 `IDeviceVendor` 框架，路由独立于 action 协议 |

> 四个厂商页都挂在 device 文档树内：绑定语义、错误码段（`40403xxx` + 各厂商段）与授权中心四态以 [device 总览](/api-docs/v1/device/) 为准。

## 运动与记录

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `sport` | [sport 运动](/api-docs/v1/sport/) | 运动打卡 + 跑群（11 action）—— **Checkin 聚合源**：其它模块的打卡记录都汇到这里 |
| `shoes` | [shoes 跑鞋](/api-docs/v1/shoes/) | 跑鞋库（V1 迁移）：跑鞋数据读写 |
| `upload` | [upload 上传](/api-docs/v1/upload/) | 数据包上传：COS 直传 + 解析记录状态机（跑步机/体脂秤等外部数据导入） |

## 训练与目标

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `training` | [training 训练](/api-docs/v1/training/) | 训练中心（V1 迁移）：计划广场 / 报名 / 我的任务 / 打卡 / 提醒 —— 5 端点，`enroll`/`checkin` 有「HTTP 200 假成功」坑，见手册 |
| `goal` | [goal 目标](/api-docs/v1/goal/) | 目标系统（14 action）：目标设定、进度、达成判定 |

## 资产与交易

七个子域构成一条交易链：**积分 / 优惠券 / 购物车 → 商城下单 → 拼团 → 分销佣金**，均为 action 协议 + `4040xxxx` 段错误码。

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `wallet` | [wallet 钱包](/api-docs/v1/wallet/) | 钱包：余额 + 流水（3 action） |
| `points` | [points 积分](/api-docs/v1/points/) | 积分：累计与消费明细（4 action） |
| `coupon` | [coupon 优惠券](/api-docs/v1/coupon/) | 优惠券：领券 / 可用券 / 核销（4 action） |
| `cart` | [cart 购物车](/api-docs/v1/cart/) | 购物车：加购 / 改量 / 选中结算（5 action） |
| `mall` | [mall 商城](/api-docs/v1/mall/) | 商城：商品浏览 + 下单 + 订单 7 态状态机 + 退款（6 action；商品浏览 3 个公开） |
| `group_buy` | [group\_buy 拼团](/api-docs/v1/group_buy/) | 拼团：开团/参团 + 人数成团判定 + 全员通知（4 action） |
| `distribution` | [distribution 分销](/api-docs/v1/distribution/) | 分销：邀请关系 + 佣金结算/追回（8 action，含 JS 浮点舍入复刻） |

## 社区互动

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `feed` | [feed 动态](/api-docs/v1/feed/) | 社区动态：信息流 / 点赞 / 评论 / 话题（9 action） |
| `follow` | [follow 关注](/api-docs/v1/follow/) | 关注关系：关注 / 取关 / 粉丝列表（6 action） |
| `favorite` | [favorite 收藏](/api-docs/v1/favorite/) | 收藏：收藏 / 取消 / 列表（4 action） |
| `review` | [review 评价](/api-docs/v1/review/) | C 端评价：发表 / 评分统计 / 申诉（7 action） |

## 内容与运营

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `agreement` | [前端手册 · agreement 页](/api-docs/v1/frontend/agreement) | 用户协议 / 隐私政策：2 端点免登录（`GET /api/v1/content/agreements` 系列）—— 响应字段是全项目唯一的 snake\_case 组，勿改 |
| `ad` | [前端手册 · splash 页](/api-docs/v1/frontend/splash) | 开机信息屏的**代码模块名** —— 模块名是 `ad`、对外路由名才是 `splash-screen`；与下条同一模块、同一份文档 |
| `splash-screen` | [前端手册 · splash 页](/api-docs/v1/frontend/splash) | 开机信息屏对外接口：开屏图/视频 + 公告 + 和风天气预报；2 端点全部免登录，异常复用 `user` 域错误码 |
| `recipe` | 暂无独立 API 文档页 | 菜谱（错误码段 `40423xxx`） |
| `food` | 暂无独立 API 文档页 | 食物库（错误码段 `40424xxx`） |
| `boohee` | 暂无独立 API 文档页 | 薄荷健康数据对接（错误码段 `40425xxx`） |

> `recipe` / `food` / `boohee` **暂无独立 API 文档页** —— 三个域的错误码段已在注册表登记，接口细节未沉淀成文档。
> `agreement` / `splash-screen` 的接口文档目前在前端联调手册（按前端源码文件分组的页），尚无独立域页。

## 数据与统计

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `stats` | [前端手册 · page-direct 页](/api-docs/v1/frontend/page-direct) | 首页「今日概览」（`stats/getTodayOverview`）—— 无独立域页，接口级说明暂在前端手册；⚠️ 响应是嵌套结构，读顶层字段恒 `undefined` |
| `ranking` | 暂无独立 API 文档页 | 排行榜（错误码段 `40422xxx`）—— 该段与 stats 的实际用码相撞，段归属待确认 |
| `kb` | 暂无独立 API 文档页 | 知识库 RAG 检索（Agent 问答的数据源，pgvector） |

> `stats` / `ranking` / `kb` **暂无独立 API 文档页** —— `stats/getTodayOverview` 的接口级说明见前端联调手册 [page-direct 页](/api-docs/v1/frontend/page-direct)。

## 运营后台

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `admin` | [Admin MIS](/api-docs/v1/admin/) | 管理后台 12 子域 / 82 use case：用户、内容、订单、提现、审核、发布、渠道、配置、misc —— RBAC 三角色 + 高敏感操作双二次确认 |

## 研发管理

| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
| `rd` | 暂无独立 API 文档页 | 研发日志 + 研发费用归集：AI 草稿 / 审核锁定 / 财务三格式导出（24 use case，错误码段 `40426xxx`） |

> `rd` **暂无独立 API 文档页** —— 模块说明见 `src/app/rd/CLAUDE.md`（仓库内，未进知识库）。

***

## Dev / Prd 双库对照

> 📖 完整说明 → **[双库对照 · 一致性 + 仿真边界](/api-docs/v1/frontend/dual-env)**

**一句话**：两个库的 **API 契约完全一致** —— 不要为它们写两套逻辑。真正的区别在**数据**。

| 维度 | Dev | Prd |
|---|---|---|
| 字段结构 / 错误码 / null 语义 | **完全一致**（实测：各 104 用例，两库均 0 失败） | 同左 |
| **仿真数据** | 新号注册**自动获得** 7 天仿真数据 | **没有**（双守卫 fail-closed，设计如此） |
| 用途 | 联调（页面有内容可测） | 真实业务 |

⚠️ **不用为两库分叉代码**；但要按契约处理 `null` ——
`withDefaults` 只补 `undefined` **不补 `null`**，后端按「无数据源显式返 null，不伪造」设计，
**前端必须兜底**（见[接线必读 · 7 条](/api-docs/v1/frontend/wiring-guide)）。

## 相关入口

| 入口 | 组织维度 | 适用场景 |
|---|---|---|
| 本页 | **业务能力**（11 大类） | 按功能找接口：知道要做什么，不知道属于哪个模块 |
| 域目录（各域页） | **后端模块**（34 域） | 端点 / 字段 / 错误码的权威细节 |
| [前端联调手册](/api-docs/v1/frontend/) | **前端源码文件**（`src/api/*.ts`） | 前端联调：打开哪个 `.ts` 就查哪页，30 端点 + 坑位速查 |
| [错误码权威注册表](/ai-contexts/error-code-registry) | **错误码段** | 反查某码属于哪个域 |