Appearance
按功能浏览 —— 11 大功能类（业务能力聚合）
归属：API Docs → v1 → 按功能浏览 定位：门面页 —— 按业务能力聚合的找路入口；端点 / 字段 / 错误码的权威细节不在此页 相关：前端联调手册（30 端点） · 错误码权威注册表 · 模块手册
这一页和域目录是什么关系？ 域目录是明细 —— 按后端模块组织（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 登录认证 | 登录/注册/会话一条链：图形码 + 短信登录 + 双 token 轮换（rotate）+ 会话列表/吊销。9 action 统一入口 POST /api/v1/auth/oauth，错误走 HTTP 200 + 40101xxx 业务码 |
用户与画像
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
user | User · 15 Action 字段表 | C 端用户主数据 + 画像：资料/昵称读写、onboarding 四维向导（提交/建议/采纳）、myProfile 读画像。统一入口 POST /api/v1/user |
设备与健康数据
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
device | device 共享域 | 设备绑定/解绑 + 今日健康数据查询（action 协议）+ 授权中心（vendors 四态状态机）—— 接入任何厂商先读这页 |
honor | honor 荣耀 | 荣耀健康云：发起授权（M1）/ 回调（M2）/ 三接口健康数据同步 + 双层 job |
zepp | zepp | Zepp 云：三端 OAuth + webhook 六事件 + legacy 回调 + 每日同步 job |
xiaomi | xiaomi 小米 | 小米运动健康云：OAuth 授权 + 官方 webhook 推送（callback / webhook 均公开，以验签鉴权） |
suunto | Suunto | Suunto 云 API（APIM 双 header + webhook）—— 走 IDeviceVendor 框架，路由独立于 action 协议 |
四个厂商页都挂在 device 文档树内：绑定语义、错误码段（
40403xxx+ 各厂商段）与授权中心四态以 device 总览 为准。
运动与记录
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
sport | sport 运动 | 运动打卡 + 跑群（11 action）—— Checkin 聚合源：其它模块的打卡记录都汇到这里 |
shoes | shoes 跑鞋 | 跑鞋库（V1 迁移）：跑鞋数据读写 |
upload | upload 上传 | 数据包上传：COS 直传 + 解析记录状态机（跑步机/体脂秤等外部数据导入） |
训练与目标
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
training | training 训练 | 训练中心（V1 迁移）：计划广场 / 报名 / 我的任务 / 打卡 / 提醒 —— 5 端点，enroll/checkin 有「HTTP 200 假成功」坑，见手册 |
goal | goal 目标 | 目标系统（14 action）：目标设定、进度、达成判定 |
资产与交易
七个子域构成一条交易链：积分 / 优惠券 / 购物车 → 商城下单 → 拼团 → 分销佣金，均为 action 协议 + 4040xxxx 段错误码。
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
wallet | wallet 钱包 | 钱包：余额 + 流水（3 action） |
points | points 积分 | 积分：累计与消费明细（4 action） |
coupon | coupon 优惠券 | 优惠券：领券 / 可用券 / 核销（4 action） |
cart | cart 购物车 | 购物车：加购 / 改量 / 选中结算（5 action） |
mall | mall 商城 | 商城：商品浏览 + 下单 + 订单 7 态状态机 + 退款（6 action；商品浏览 3 个公开） |
group_buy | group_buy 拼团 | 拼团：开团/参团 + 人数成团判定 + 全员通知（4 action） |
distribution | distribution 分销 | 分销：邀请关系 + 佣金结算/追回（8 action，含 JS 浮点舍入复刻） |
社区互动
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
feed | feed 动态 | 社区动态：信息流 / 点赞 / 评论 / 话题（9 action） |
follow | follow 关注 | 关注关系：关注 / 取关 / 粉丝列表（6 action） |
favorite | favorite 收藏 | 收藏：收藏 / 取消 / 列表（4 action） |
review | review 评价 | C 端评价：发表 / 评分统计 / 申诉（7 action） |
内容与运营
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
agreement | 前端手册 · agreement 页 | 用户协议 / 隐私政策：2 端点免登录（GET /api/v1/content/agreements 系列）—— 响应字段是全项目唯一的 snake_case 组，勿改 |
ad | 前端手册 · splash 页 | 开机信息屏的代码模块名 —— 模块名是 ad、对外路由名才是 splash-screen；与下条同一模块、同一份文档 |
splash-screen | 前端手册 · splash 页 | 开机信息屏对外接口：开屏图/视频 + 公告 + 和风天气预报；2 端点全部免登录，异常复用 user 域错误码 |
recipe | 暂无独立 API 文档页 | 菜谱（错误码段 40423xxx） |
food | 暂无独立 API 文档页 | 食物库（错误码段 40424xxx） |
boohee | 暂无独立 API 文档页 | 薄荷健康数据对接（错误码段 40425xxx） |
recipe/food/boohee暂无独立 API 文档页 —— 三个域的错误码段已在注册表登记，接口细节未沉淀成文档。agreement/splash-screen的接口文档目前在前端联调手册（按前端源码文件分组的页），尚无独立域页。
数据与统计
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
stats | 前端手册 · page-direct 页 | 首页「今日概览」（stats/getTodayOverview）—— 无独立域页，接口级说明暂在前端手册；⚠️ 响应是嵌套结构，读顶层字段恒 undefined |
ranking | 暂无独立 API 文档页 | 排行榜（错误码段 40422xxx）—— 该段与 stats 的实际用码相撞，段归属待确认 |
kb | 暂无独立 API 文档页 | 知识库 RAG 检索（Agent 问答的数据源，pgvector） |
stats/ranking/kb暂无独立 API 文档页 ——stats/getTodayOverview的接口级说明见前端联调手册 page-direct 页。
运营后台
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
admin | Admin MIS | 管理后台 12 子域 / 82 use case：用户、内容、订单、提现、审核、发布、渠道、配置、misc —— RBAC 三角色 + 高敏感操作双二次确认 |
研发管理
| 域 | 文档 | 这个域是干什么的 |
|---|---|---|
rd | 暂无独立 API 文档页 | 研发日志 + 研发费用归集：AI 草稿 / 审核锁定 / 财务三格式导出（24 use case，错误码段 40426xxx） |
rd暂无独立 API 文档页 —— 模块说明见src/app/rd/CLAUDE.md（仓库内，未进知识库）。
Dev / Prd 双库对照
📖 完整说明 → 双库对照 · 一致性 + 仿真边界
一句话：两个库的 API 契约完全一致 —— 不要为它们写两套逻辑。真正的区别在数据。
| 维度 | Dev | Prd |
|---|---|---|
| 字段结构 / 错误码 / null 语义 | 完全一致（实测：各 104 用例，两库均 0 失败） | 同左 |
| 仿真数据 | 新号注册自动获得 7 天仿真数据 | 没有（双守卫 fail-closed，设计如此） |
| 用途 | 联调（页面有内容可测） | 真实业务 |
⚠️ 不用为两库分叉代码；但要按契约处理 null —— withDefaults 只补 undefined 不补 null，后端按「无数据源显式返 null，不伪造」设计， 前端必须兜底（见接线必读 · 7 条）。
相关入口
| 入口 | 组织维度 | 适用场景 |
|---|---|---|
| 本页 | 业务能力（11 大类） | 按功能找接口：知道要做什么，不知道属于哪个模块 |
| 域目录（各域页） | 后端模块（34 域） | 端点 / 字段 / 错误码的权威细节 |
| 前端联调手册 | 前端源码文件（src/api/*.ts） | 前端联调：打开哪个 .ts 就查哪页，30 端点 + 坑位速查 |
| 错误码权威注册表 | 错误码段 | 反查某码属于哪个域 |