# AutFeng Hub 开放接口文档

> 版本 `v1` · 更新日期 2026-07-29 · 面向 AutFeng 客户端（Android / iOS）与网页端对接

AutFeng Hub 是 AutFeng（Alight Motion 授权二开版）的社区与交易平台，提供两类能力：

1. **内容社区** — XML / AMPROJ 预设、工程模板与素材的上传、检索、下载
2. **服务交易** — 视频代剪、接同款复刻、定制预设与教学订单的撮合、托管与结算

---

## 目录

- [1. 接入准备](#1-接入准备)
- [2. 通用约定](#2-通用约定)
- [3. 认证与账号](#3-认证与账号)
- [4. 用户与会员](#4-用户与会员)
- [5. 资源（预设 / 素材）](#5-资源预设--素材)
- [6. 上传与投稿](#6-上传与投稿)
- [7. 社区动态](#7-社区动态)
- [8. 服务订单](#8-服务订单)
- [9. 剪辑师](#9-剪辑师)
- [10. 钱包与积分](#10-钱包与积分)
- [11. 消息与通知](#11-消息与通知)
- [12. 管理端接口](#12-管理端接口)
- [13. Webhook 回调](#13-webhook-回调)
- [14. 状态机](#14-状态机)
- [15. 枚举字典](#15-枚举字典)
- [16. 客户端集成](#16-客户端集成)
- [17. 错误码](#17-错误码)
- [18. 变更日志](#18-变更日志)

---

## 1. 接入准备

### 1.1 环境地址

| 环境 | Base URL | 说明 |
|---|---|---|
| 生产 | `https://api.autfeng.app/v1` | 正式数据 |
| 预发 | `https://api-staging.autfeng.app/v1` | 结构与生产一致，数据独立 |
| 本地 | `http://127.0.0.1:8080/v1` | 本地联调 |

### 1.2 应用密钥

每个客户端平台一套密钥，在管理台「系统设置 → API 对接」获取：

| 平台 | App ID | 密钥前缀 |
|---|---|---|
| Android | `af_android` | `af_live_...` |
| iOS | `af_ios` | `af_live_...` |
| 网页端 | `af_web` | `af_live_...` |

密钥仅用于**请求签名**，不要写在可反编译的明文常量里；建议做一次本地加密存储 + 运行时解密。

### 1.3 请求签名

除公开只读接口外，所有请求需带签名头：

```
X-AF-App-Id:     af_android
X-AF-Timestamp:  1785267600           # 秒级时间戳，与服务端偏差需 < 300 秒
X-AF-Nonce:      f3a9c1e07b2d4        # 随机串，5 分钟内不可重复
X-AF-Sign:       <签名值>
X-AF-Client-Ver: 4.2.1                # 客户端版本，用于兼容性过滤
X-AF-Device-Id:  <设备唯一标识>
```

签名算法：

```
raw  = METHOD + "\n" + PATH + "\n" + SORTED_QUERY + "\n" + BODY_MD5 + "\n" + TIMESTAMP + "\n" + NONCE
sign = HMAC_SHA256(raw, APP_SECRET) -> hex lowercase
```

- `SORTED_QUERY`：query 参数按 key 升序拼接为 `k=v&k=v`，无参数时为空串
- `BODY_MD5`：请求体的 MD5（hex lowercase），GET 或空体时为空串
- 签名错误返回 `40101`，时间戳超窗返回 `40102`，nonce 重放返回 `40103`

---

## 2. 通用约定

### 2.1 响应结构

所有接口统一包裹：

```json
{
  "code": 0,
  "message": "ok",
  "data": {},
  "requestId": "req_9f2c7b1e4a8d",
  "serverTime": 1785267600
}
```

- `code = 0` 表示成功，非 0 见 [错误码](#17-错误码)
- `requestId` 请在客户端日志中保留，排查问题时提供

### 2.2 分页

请求：

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `page` | int | 1 | 页码，从 1 开始 |
| `pageSize` | int | 20 | 每页条数，最大 50 |
| `cursor` | string | - | 游标分页（信息流场景优先用它） |

响应：

```json
{
  "code": 0,
  "data": {
    "list": [],
    "page": 1,
    "pageSize": 20,
    "total": 12840,
    "hasMore": true,
    "cursor": "eyJpZCI6InAyMDAxIn0"
  }
}
```

> 列表页用 `page`，社区信息流用 `cursor`（避免翻页时因新内容插入导致重复）。

### 2.3 限流

| 维度 | 限制 | 超限返回 |
|---|---|---|
| 单设备 | 120 次 / 分钟 | `42901` |
| 单用户 | 600 次 / 分钟 | `42901` |
| 下载接口 | 30 次 / 分钟，200 次 / 天 | `42902` |
| 上传接口 | 10 次 / 分钟 | `42903` |

响应头会带剩余额度：

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1785267660
```

### 2.4 幂等

创建类接口（下单、支付、提现）支持幂等键，重复提交返回首次结果：

```
Idempotency-Key: <客户端生成的 UUID>
```

### 2.5 时间与金额

- 时间统一为**秒级 Unix 时间戳**（int），客户端自行转本地时区
- 金额统一为**分**（int），例如 `16800` 表示 ¥168.00
- 积分为整数，无小数

---

## 3. 认证与账号

### 3.1 发送验证码

```
POST /auth/sms/send
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `phone` | string | 是 | 手机号 |
| `region` | string | 否 | 区号，默认 `86` |
| `scene` | string | 是 | `login` / `bind` / `reset` |

```json
{ "phone": "13800001234", "scene": "login" }
```

响应：`{ "code": 0, "data": { "expiresIn": 300, "retryAfter": 60 } }`

### 3.2 手机号登录 / 注册

```
POST /auth/login/sms
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `phone` | string | 是 | 手机号 |
| `code` | string | 是 | 6 位验证码 |
| `inviteCode` | string | 否 | 邀请码，仅首次注册生效 |

```json
{
  "code": 0,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "rt_8f2c...",
    "expiresIn": 7200,
    "isNewUser": false,
    "user": {
      "id": "u_1001",
      "name": "猫鹤",
      "handle": "Ayaka.Meow",
      "avatar": "https://cdn.autfeng.app/avatar/u_1001.webp",
      "level": 12,
      "vip": { "plan": "pro", "expireAt": 1787356800 }
    }
  }
}
```

后续请求带：`Authorization: Bearer <accessToken>`

### 3.3 密码登录

```
POST /auth/login/password
```

```json
{ "account": "13800001234", "password": "<sha256(明文+盐)>" }
```

> 客户端**不要**直传明文密码。盐由 `GET /auth/salt?account=` 获取。

### 3.4 扫码登录（客户端授权网页端）

```
POST /auth/qr/create        # 网页端调用，返回二维码内容
GET  /auth/qr/status        # 网页端轮询
POST /auth/qr/confirm       # 客户端扫码后调用
```

`POST /auth/qr/create` 响应：

```json
{
  "code": 0,
  "data": { "qrId": "qr_7a2f9c", "content": "autfeng://login?qr=qr_7a2f9c", "expiresIn": 120 }
}
```

`GET /auth/qr/status?qrId=qr_7a2f9c` 的 `data.status`：`pending` → `scanned` → `confirmed` / `expired`。
`confirmed` 时同时返回 token，与 3.2 结构一致。

### 3.5 刷新 Token

```
POST /auth/token/refresh
```

```json
{ "refreshToken": "rt_8f2c..." }
```

`accessToken` 有效期 2 小时，`refreshToken` 30 天。刷新时 `refreshToken` 会轮换，需覆盖存储。

### 3.6 退出登录

```
POST /auth/logout          # 当前设备
POST /auth/logout/others   # 其他设备
```

---

## 4. 用户与会员

### 4.1 当前用户信息

```
GET /user/me
```

```json
{
  "code": 0,
  "data": {
    "id": "u_1001",
    "name": "猫鹤",
    "handle": "Ayaka.Meow",
    "avatar": "https://cdn.autfeng.app/avatar/u_1001.webp",
    "bio": "专注 ACG 混剪与卡点转场",
    "level": 12,
    "exp": 3840,
    "expNext": 5000,
    "verified": true,
    "creator": { "isCreator": true, "creatorId": "c_505", "level": "认证讲师" },
    "vip": {
      "plan": "pro",
      "planName": "专业版",
      "expireAt": 1787356800,
      "daysLeft": 28,
      "benefits": ["unlimited_export", "vip_presets", "cloud_sync", "no_service_fee"]
    },
    "stats": {
      "uploads": 24, "downloads": 312, "followers": 1840,
      "following": 96, "likesGot": 12460, "ordersBuy": 8, "ordersSell": 42
    },
    "wallet": { "balance": 128650, "frozen": 16800, "points": 3840 },
    "prefs": { "clientVersion": "4.2.0", "defaultRatio": "9:16", "filterIncompatible": true }
  }
}
```

### 4.2 更新资料

```
PATCH /user/me
```

```json
{ "name": "猫鹤", "bio": "...", "directions": ["卡点混剪", "转场特效"] }
```

### 4.3 用户主页

```
GET /user/{userId}
GET /user/{userId}/resources?page=1&pageSize=20
GET /user/{userId}/posts
POST /user/{userId}/follow
DELETE /user/{userId}/follow
```

### 4.4 会员套餐与购买

```
GET  /vip/plans
POST /vip/purchase
```

会员体系是「档位 × 周期」二维模型：4 个档位（`free` / `std` / `pro` / `studio`），其中 `free` 为注册基线、不可购买；另 3 档各有月 / 季 / 年三个计费周期。

```
GET  /vip/plans
GET  /vip/quote?tier=pro&cycle=year
POST /vip/purchase
```

`GET /vip/plans`：

```json
{
  "code": 0,
  "data": {
    "current": { "tier": "pro", "cycle": "quarter", "expireAt": 1787356800, "daysLeft": 28, "autoRenew": false },
    "cycles": [
      { "key": "month", "name": "月付", "unit": "月", "months": 1 },
      { "key": "quarter", "name": "季付", "unit": "季", "months": 3, "tag": "省 11%" },
      { "key": "year", "name": "年付", "unit": "年", "months": 12, "tag": "省 22%", "best": true }
    ],
    "tiers": [
      {
        "key": "free", "name": "免费版", "sub": "注册即得", "color": "#8FB4B2", "icon": "user",
        "purchasable": false,
        "price": { "month": 0, "quarter": 0, "year": 0 },
        "limits": { "exportPerDay": 3, "watermark": 1, "cloudGb": 0, "vipRes": 0,
                    "serviceFeeOff": 0, "downloadPerDay": 10, "aiQuota": 0 },
        "highlights": ["每日 3 次导出（带水印）", "免费资源无限浏览", "每日 10 次下载"]
      },
      {
        "key": "std", "name": "标准版", "sub": "日常够用", "color": "#39C5BB", "icon": "zap",
        "purchasable": true,
        "price": { "month": 1200, "quarter": 3200, "year": 9800 },
        "limits": { "exportPerDay": 30, "watermark": 0, "cloudGb": 2, "vipRes": 1,
                    "serviceFeeOff": 0, "downloadPerDay": 60, "aiQuota": 20 },
        "highlights": ["每日 30 次导出，无水印", "会员专享资源可下载", "云端工程同步 2GB", "每日 60 次下载"]
      },
      {
        "key": "pro", "name": "专业版", "sub": "创作者首选", "color": "#2AB3A9", "icon": "crown",
        "purchasable": true, "recommended": true,
        "price": { "month": 1800, "quarter": 4800, "year": 16800 },
        "limits": { "exportPerDay": -1, "watermark": 0, "cloudGb": 10, "vipRes": 1,
                    "serviceFeeOff": 1, "downloadPerDay": -1, "aiQuota": 100 },
        "highlights": ["无限次导出，无水印", "云端工程同步 10GB", "下单免平台服务费", "不限下载次数", "投稿审核优先排队"]
      },
      {
        "key": "studio", "name": "工作室版", "sub": "团队协作", "color": "#B4881F", "icon": "briefcase",
        "purchasable": true,
        "price": { "month": 4800, "quarter": 13200, "year": 45800 },
        "limits": { "exportPerDay": -1, "watermark": 0, "cloudGb": 100, "vipRes": 1,
                    "serviceFeeOff": 1, "downloadPerDay": -1, "aiQuota": 500 },
        "highlights": ["专业版全部权益", "5 个子账号，工程共享", "云端同步 100GB", "专属客服与优先仲裁", "批量导出与商用授权"]
      }
    ],
    "benefitMatrix": [
      {
        "group": "导出与水印",
        "items": [
          { "name": "每日导出次数", "limitKey": "exportPerDay", "type": "num", "unit": " 次" },
          { "name": "去除导出水印", "limitKey": "watermark", "type": "neg" },
          { "name": "最高导出分辨率", "vals": { "free": "1080p", "std": "2K", "pro": "4K", "studio": "4K" } },
          { "name": "批量导出", "vals": { "free": 0, "std": 0, "pro": 0, "studio": 1 } }
        ]
      },
      {
        "group": "资源与素材",
        "items": [
          { "name": "每日下载次数", "limitKey": "downloadPerDay", "type": "num", "unit": " 次" },
          { "name": "会员专享资源", "limitKey": "vipRes", "type": "bool" },
          { "name": "积分兑换折扣", "vals": { "free": "无", "std": "9 折", "pro": "8 折", "studio": "7 折" } }
        ]
      }
    ]
  }
}
```

字段约定（客户端务必按这套规则渲染，不要把档位差异写死在前端）：

| 字段 | 约定 |
|---|---|
| `price.*` | 单位**分**，整数。`0` 表示该档不售卖此周期 |
| `limits.*` | `-1` = 不限量；`0` = 无此权益；正整数 = 具体额度 |
| `limits.watermark` | 语义是**是否带水印**，`1` 为带。矩阵里 `type: "neg"` 的行需取反显示 |
| `benefitMatrix[].items[].type` | `num` 数值+`unit`；`gb` 数值+` GB`；`bool` 勾/叉；`neg` 取反后勾/叉 |
| `items[].vals` | 存在时**优先于** `limitKey`，按档位 key 直接取值，可为字符串或 `1/0` |
| `recommended` | 全表最多一个，用于高亮主推档位 |

矩阵行的取值优先级为 `vals[tierKey]` → `limits[limitKey]` 经 `type` 转换。新增权益行时服务端只需扩 `benefitMatrix`，客户端无需发版。

`GET /vip/quote`：升级 / 续费前取实付金额，**折抵金额必须由服务端计算**，客户端不要自行按剩余天数折算。

```json
{
  "code": 0,
  "data": {
    "tier": "studio", "cycle": "year",
    "listPrice": 45800,
    "credit": 12880,
    "creditReason": "专业版剩余 28 天按日折抵",
    "payable": 32920,
    "effectAt": 1785283200,
    "expireAt": 1816819200,
    "isUpgrade": true
  }
}
```

`POST /vip/purchase`：

```json
{ "tier": "pro", "cycle": "year", "payMethod": "alipay", "autoRenew": true, "returnUrl": "autfeng://pay/result" }
```

```json
{
  "code": 0,
  "data": {
    "orderNo": "VIP20260729001",
    "tier": "pro",
    "cycle": "year",
    "amount": 16800,
    "payMethod": "alipay",
    "payParams": { "orderStr": "..." }
  }
}
```

> `amount` 必须与同参数下 `GET /vip/quote` 的 `payable` 一致；不一致按服务端为准并提示用户重新确认。
> `payParams` 直接透传给对应支付 SDK。支付结果以 [Webhook](#13-webhook-回调) 与 `GET /vip/order/{orderNo}` 为准，不要以客户端回调为准。

降档（如 `studio` → `pro`）不即时生效，服务端在当前周期到期时切换，`GET /vip/plans` 的 `current` 会附带 `pendingTier` 字段。

### 4.5 签到

```
POST /user/checkin
GET  /user/checkin/status
```

```json
{
  "code": 0,
  "data": { "success": true, "points": 10, "continuousDays": 8, "bonusPoints": 0, "nextBonusDay": 14 }
}
```

---

## 5. 资源（预设 / 素材）

### 5.1 资源列表

```
GET /resources
```

| 参数 | 类型 | 说明 |
|---|---|---|
| `type` | string | `preset` / `asset`，不传则全部 |
| `category` | string | 分类 key，见 [枚举](#15-枚举字典)，多个用逗号 |
| `ratio` | string | `9:16` / `16:9` / `1:1` / `4:5` / `2.35:1`，多个用逗号 |
| `fileType` | string | `xml` / `amproj` / `mp4` / `wav` / `ttf` / `png` / `cube` |
| `priceType` | string | `free` / `points` / `vip` / `paid` |
| `maxVersion` | string | **客户端版本**，服务端只返回 `minVersion <= maxVersion` 的资源 |
| `license` | string | `commercial` / `cc-by` / `personal` |
| `keyword` | string | 关键词，匹配标题与标签 |
| `sort` | string | `hot`（默认）/ `new` / `downloads` / `rating` / `size` |
| `authorId` | string | 按作者筛选 |

> **重要**：客户端务必传 `maxVersion`，否则用户会下载到无法导入的预设，这是投诉最高的一类问题。

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": "p_2001",
        "type": "preset",
        "title": "赛博故障 Glitch 转场包",
        "category": "transition",
        "categoryName": "转场",
        "fileType": "xml",
        "ratio": "9:16",
        "cover": "https://cdn.autfeng.app/cover/p_2001.webp",
        "previewVideo": "https://cdn.autfeng.app/preview/p_2001.mp4",
        "duration": 6,
        "layers": 12,
        "sizeBytes": 327680,
        "minVersion": "4.2.0",
        "compatible": true,
        "price": { "type": "free", "points": 0, "amount": 0 },
        "license": "personal",
        "stats": { "downloads": 320, "likes": 120, "favorites": 40, "comments": 3, "rating": 4.6 },
        "author": {
          "id": "u_1002", "name": "零度剪辑", "avatar": "...", "level": 18, "verified": true
        },
        "tags": ["转场", "9:16", "XML", "热门"],
        "createdAt": 1785260000,
        "featured": true
      }
    ],
    "page": 1, "pageSize": 20, "total": 12840, "hasMore": true
  }
}
```

`compatible` 由服务端结合 `X-AF-Client-Ver` 计算，客户端可直接用它决定按钮态。

### 5.2 资源详情

```
GET /resources/{resourceId}
```

比列表多返回：

```json
{
  "description": "完整说明文本（支持基础 Markdown）",
  "params": [
    { "name": "主遮罩 Mask_A", "type": "形状遮罩", "keyframes": 6, "adjustable": true, "note": "控制扩散范围" }
  ],
  "files": [
    { "name": "main.xml", "sizeBytes": 327680, "usage": "主文件" },
    { "name": "readme.txt", "sizeBytes": 1024, "usage": "授权与说明" }
  ],
  "requirements": { "minVersion": "4.2.0", "fonts": ["锐利黑体"], "plugins": [] },
  "copyright": { "source": "own", "sourceName": "完全原创", "note": "", "commercialUse": false },
  "related": [ { "id": "p_2012", "title": "水墨扩散遮罩转场", "cover": "..." } ],
  "userState": { "liked": false, "favorited": true, "downloaded": true, "canDownload": true }
}
```

### 5.3 下载资源

```
POST /resources/{resourceId}/download
```

```json
{ "clientVersion": "4.2.1", "ratio": "9:16" }
```

```json
{
  "code": 0,
  "data": {
    "downloadUrl": "https://dl.autfeng.app/p_2001.xml?token=...&expires=1785271200",
    "expiresIn": 3600,
    "fileName": "cyber_glitch_transition.xml",
    "sizeBytes": 327680,
    "md5": "9f2c7b1e4a8d3f5c...",
    "importScheme": "autfeng://import?res=p_2001&token=...",
    "cost": { "type": "free", "points": 0, "pointsLeft": 3840 }
  }
}
```

失败场景：

| code | 含义 | 客户端处理 |
|---|---|---|
| `40901` | 版本不兼容 | 提示升级到 `minVersion` |
| `40902` | 积分不足 | 跳积分获取页 |
| `40903` | 需要会员 | 跳会员购买页 |
| `40904` | 需付费购买 | 跳支付流程 |
| `42902` | 超出下载限额 | 提示次日恢复 |

### 5.4 互动

```
POST   /resources/{id}/like
DELETE /resources/{id}/like
POST   /resources/{id}/favorite
DELETE /resources/{id}/favorite
POST   /resources/{id}/report
GET    /resources/{id}/comments?page=1
POST   /resources/{id}/comments
```

`POST /resources/{id}/report`：

```json
{ "reason": "copyright", "detail": "与 p_2017 图层结构一致" }
```

`reason` 取值：`copyright` / `mismatch` / `illegal` / `pricing` / `other`

### 5.5 分类与筛选项

```
GET /resources/categories
GET /resources/filters
```

`GET /resources/filters` 返回全部可用筛选项及计数，客户端据此渲染筛选面板，避免硬编码：

```json
{
  "code": 0,
  "data": {
    "categories": [ { "key": "transition", "name": "转场", "icon": "zap", "count": 4128 } ],
    "ratios": [ { "key": "9:16", "name": "竖屏短视频", "count": 8420 } ],
    "priceTypes": [ { "key": "free", "name": "免费", "count": 9640 } ],
    "versions": ["4.0.6", "4.1.0", "4.2.0", "4.2.1"]
  }
}
```

---

## 6. 上传与投稿

投稿分三步：**申请上传凭证 → 直传对象存储 → 提交投稿单**。大文件不经过业务服务器。

### 6.1 申请上传凭证

```
POST /upload/token
```

```json
{ "fileName": "cyber_glitch.xml", "sizeBytes": 327680, "purpose": "resource", "md5": "9f2c..." }
```

`purpose`：`resource`（资源文件）/ `cover`（封面）/ `preview`（预览视频）/ `post`（动态配图）/ `order`（订单素材）

```json
{
  "code": 0,
  "data": {
    "uploadId": "up_7f3a9c",
    "method": "PUT",
    "uploadUrl": "https://oss.autfeng.app/tmp/up_7f3a9c?signature=...",
    "headers": { "Content-Type": "application/octet-stream" },
    "expiresIn": 1800,
    "maxSizeBytes": 209715200,
    "chunkSize": 5242880,
    "multipart": false
  }
}
```

> `sizeBytes > 100MB` 时 `multipart: true`，需按 `chunkSize` 分片并调用 `POST /upload/multipart/complete` 合并。

### 6.2 提交投稿

```
POST /resources
```

```json
{
  "type": "preset",
  "title": "赛博故障 Glitch 转场包（9:16 竖屏）",
  "category": "transition",
  "ratio": "9:16",
  "minVersion": "4.2.0",
  "description": "效果原理与导入说明，至少 20 字",
  "tags": ["转场", "赛博", "竖屏"],
  "files": [{ "uploadId": "up_7f3a9c", "usage": "main" }],
  "coverUploadId": "up_8a4b1d",
  "previewUploadId": "up_9c5e2f",
  "tech": { "layers": 12, "duration": 6, "bpm": 128 },
  "price": { "type": "points", "points": 120 },
  "license": "personal",
  "copyright": { "source": "own", "note": "" }
}
```

```json
{
  "code": 0,
  "data": { "resourceId": "p_2099", "auditStatus": "pending", "estimatedMinutes": 120 }
}
```

必填校验失败返回 `42201`，`data.fields` 指出具体字段：

```json
{
  "code": 42201,
  "message": "参数校验失败",
  "data": { "fields": { "copyright.source": "版权来源声明为必填项" } }
}
```

### 6.3 我的投稿

```
GET   /user/me/resources?status=pending|passed|rejected|draft
PATCH /resources/{id}
DELETE /resources/{id}
POST  /resources/{id}/offline
GET   /resources/{id}/stats
```

`GET /resources/{id}/stats`：

```json
{
  "code": 0,
  "data": {
    "downloads": { "total": 12840, "last7Days": [186, 320, 148, 428, 268, 96, 396] },
    "sources": [ { "name": "分类页", "percent": 42 }, { "name": "搜索", "percent": 28 } ],
    "earnings": { "points": 3852, "amount": 0 }
  }
}
```

---

## 7. 社区动态

### 7.1 动态列表

```
GET /posts?kind=work|ask|tut|notice&sort=new|hot&cursor=
```

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": "f_401",
        "kind": "work",
        "kindName": "作品展示",
        "text": "用新做的三维运镜工程重剪了一版 MAD...",
        "images": ["https://cdn.autfeng.app/post/f_401_1.webp"],
        "video": null,
        "ratio": "9:16",
        "author": { "id": "u_1002", "name": "零度剪辑", "avatar": "...", "verified": true },
        "refResource": { "id": "p_2005", "type": "preset", "title": "三维空间运镜工程", "cover": "..." },
        "tags": ["作品展示", "运镜"],
        "stats": { "likes": 1284, "comments": 96, "shares": 41 },
        "userState": { "liked": false, "favorited": false },
        "solved": false,
        "pinned": false,
        "createdAt": 1785265000
      }
    ],
    "cursor": "eyJpZCI6ImZfNDAxIn0", "hasMore": true
  }
}
```

### 7.2 发布动态

```
POST /posts
```

```json
{
  "kind": "work",
  "text": "分享一个卡点技巧...",
  "imageUploadIds": ["up_1a2b", "up_3c4d"],
  "videoUploadId": null,
  "refResourceId": "p_2005",
  "tags": ["作品展示", "卡点"]
}
```

### 7.3 其他

```
GET    /posts/{id}
DELETE /posts/{id}
POST   /posts/{id}/like
DELETE /posts/{id}/like
GET    /posts/{id}/comments
POST   /posts/{id}/comments
POST   /posts/{id}/comments/{commentId}/accept   # 求助帖采纳答案
GET    /topics                                    # 话题活动列表
GET    /topics/{id}/posts
```

---

## 8. 服务订单

### 8.1 创建需求

```
POST /orders
```

```json
{
  "serviceType": "same",
  "title": "接同款｜赛博故障开场 15 秒复刻",
  "detail": "详细要求，至少 20 字",
  "spec": {
    "ratio": "9:16",
    "durationSec": 15,
    "resolution": "1080p",
    "fps": 30,
    "styles": ["赛博故障", "卡点混剪"],
    "needProject": true
  },
  "reference": { "urls": ["https://v.douyin.com/xxxx"], "uploadIds": ["up_5e6f"] },
  "budget": { "min": 15000, "max": 30000 },
  "deadlineDays": 2,
  "assign": { "mode": "open", "creatorIds": [] }
}
```

- `serviceType`：`same`（接同款）/ `edit`（代剪）/ `preset`（定制预设）/ `tutor`（教学）
- `assign.mode`：`open`（公开招标）/ `direct`（直接指派）/ `invite`（定向邀请）
- `serviceType = same` 时 `reference.urls` 必填，否则返回 `42202`

```json
{
  "code": 0,
  "data": {
    "orderId": "AF20260729001",
    "status": "pending",
    "escrow": { "required": true, "amount": 22500, "paid": false }
  }
}
```

### 8.2 订单列表

```
GET /orders?role=buyer|seller&status=&page=1
```

`status` 支持逗号分隔多值，取值见 [订单状态机](#141-订单状态机)。

### 8.3 订单详情

```
GET /orders/{orderId}
```

```json
{
  "code": 0,
  "data": {
    "orderId": "AF20260729001",
    "serviceType": "same",
    "serviceTypeName": "接同款复刻",
    "title": "接同款｜赛博故障开场 15 秒复刻",
    "detail": "...",
    "status": "working",
    "statusName": "制作中",
    "progress": 55,
    "spec": { "ratio": "9:16", "durationSec": 15, "resolution": "1080p", "fps": 30, "needProject": true },
    "amount": 16800,
    "serviceFee": 840,
    "buyer": { "id": "u_1003", "name": "橘子汽水", "avatar": "..." },
    "creator": { "id": "c_503", "userId": "u_1007", "name": "Neon", "avatar": "...", "level": "金牌剪辑师", "rating": 4.92 },
    "revisions": { "total": 2, "used": 0 },
    "escrow": { "status": "held", "amount": 16800 },
    "timeline": [
      { "node": "created", "name": "发布需求", "done": true, "at": 1785245000 },
      { "node": "quoted", "name": "确认报价", "done": true, "at": 1785248000 },
      { "node": "escrow", "name": "资金托管", "done": true, "at": 1785248200 },
      { "node": "working", "name": "制作中", "done": true, "at": 1785248300 },
      { "node": "review", "name": "提交验收", "done": false, "at": null },
      { "node": "settled", "name": "结算完成", "done": false, "at": null }
    ],
    "deliveries": [
      {
        "version": "v1",
        "note": "按需求完成初剪",
        "files": [{ "name": "v1_preview.mp4", "sizeBytes": 88473600, "url": "...", "type": "video" }],
        "createdAt": 1785259000
      }
    ],
    "createdAt": 1785245000,
    "deadline": 1785417600,
    "actions": ["contact", "urge", "refund"]
  }
}
```

> `actions` 由服务端按状态与角色计算，客户端据此渲染按钮，**不要在客户端写状态判断逻辑**，避免两端不一致。

### 8.4 报价与接单

```
GET  /orders/{orderId}/quotes
POST /orders/{orderId}/quotes            # 剪辑师报价
POST /orders/{orderId}/quotes/{quoteId}/accept   # 买家接受
POST /orders/{orderId}/quotes/{quoteId}/reject
```

`POST /orders/{orderId}/quotes`：

```json
{ "amount": 16800, "deliveryDays": 2, "revisions": 2, "note": "实现思路与交付内容说明" }
```

### 8.5 资金托管与支付

```
POST /orders/{orderId}/escrow
```

```json
{ "payMethod": "balance" }
```

`payMethod`：`balance`（余额）/ `alipay` / `wechat`。非余额支付返回 `payParams` 供 SDK 调起。

### 8.6 交付与验收

```
POST /orders/{orderId}/deliveries          # 剪辑师提交成片
POST /orders/{orderId}/accept              # 买家验收，触发结算
POST /orders/{orderId}/revisions           # 买家申请修改
POST /orders/{orderId}/progress            # 剪辑师更新进度
```

`POST /orders/{orderId}/deliveries`：

```json
{
  "version": "v1",
  "note": "首版成片，节奏已对齐参考视频",
  "uploadIds": ["up_7a8b", "up_9c0d"]
}
```

`POST /orders/{orderId}/revisions`：

```json
{ "detail": "00:03 转场太快；00:12 字幕挡住主体", "uploadIds": ["up_1e2f"] }
```

修改轮次用尽时返回 `42204`，需先走 `POST /orders/{orderId}/revisions/extra` 追加付费修改。

### 8.7 取消、退款与纠纷

```
POST /orders/{orderId}/cancel
POST /orders/{orderId}/refund
POST /orders/{orderId}/dispute
GET  /orders/{orderId}/dispute
POST /orders/{orderId}/dispute/evidence
```

`POST /orders/{orderId}/dispute`：

```json
{ "reason": "成片节奏与需求文档不符", "uploadIds": ["up_3g4h"] }
```

### 8.8 评价

```
POST /orders/{orderId}/review
```

```json
{ "score": 5, "tags": ["沟通顺畅", "交付及时", "效果还原度高"], "content": "文字评价" }
```

---

## 9. 剪辑师

```
GET  /creators?direction=&status=&sort=rating|orders|price&page=1
GET  /creators/{creatorId}
GET  /creators/{creatorId}/works
GET  /creators/{creatorId}/packages
GET  /creators/{creatorId}/reviews
POST /creators/apply                 # 申请入驻
GET  /creators/me/dashboard          # 剪辑师工作台
PATCH /creators/me                   # 更新接单状态、价格
GET  /requests                       # 需求墙（剪辑师视角）
```

`GET /creators/{creatorId}`：

```json
{
  "code": 0,
  "data": {
    "id": "c_503",
    "user": { "id": "u_1007", "name": "Neon", "avatar": "...", "verified": true },
    "title": "赛博 / 故障风格",
    "level": "金牌剪辑师",
    "intro": "风格化开场与故障视觉",
    "status": "free",
    "rating": 4.92,
    "stats": { "orders": 731, "onTimeRate": 97.4, "replyMinutes": 9, "creditScore": 92 },
    "priceFrom": 12800,
    "tags": ["赛博朋克", "故障艺术", "开场动画"],
    "skills": ["AutFeng", "故障算法", "字体设计"],
    "packages": [
      { "id": "pk_1", "name": "标准版", "price": 25600, "deliveryDays": 3, "revisions": 2,
        "features": ["60 秒内成片", "2 轮修改", "含 AMPROJ 工程"], "recommended": true }
    ],
    "joinedAt": 1774915200
  }
}
```

`PATCH /creators/me`：

```json
{ "status": "busy", "priceFrom": 12800, "autoAcceptInvite": false }
```

`status`：`free`（可接单）/ `busy`（排期紧张）/ `off`（暂停接单）

---

## 10. 钱包与积分

```
GET  /wallet
GET  /wallet/transactions?type=in|out|points&page=1
POST /wallet/withdraw
GET  /wallet/withdraw/{withdrawId}
GET  /wallet/methods
POST /wallet/methods
POST /wallet/recharge
GET  /points/rules
GET  /points/tasks
POST /points/exchange
```

`GET /wallet`：

```json
{
  "code": 0,
  "data": {
    "balance": 128650,
    "frozen": 16800,
    "pendingSettle": 42000,
    "points": 3840,
    "totalIncome": 862000,
    "withdrawRule": { "minAmount": 5000, "feeRate": 0.006, "minFee": 100, "dailyLimit": 2000000, "arrivalDays": "1-3" }
  }
}
```

`POST /wallet/withdraw`：

```json
{ "amount": 100000, "methodId": "pm_1", "smsCode": "123456" }
```

```json
{
  "code": 0,
  "data": { "withdrawId": "W20260729003", "amount": 100000, "fee": 600, "actual": 99400, "status": "pending" }
}
```

`POST /points/exchange`：

```json
{ "itemId": "px_preset_ticket", "quantity": 1 }
```

---

## 11. 消息与通知

```
GET  /messages/conversations
GET  /messages/conversations/{convId}/messages?cursor=
POST /messages/conversations/{convId}/messages
POST /messages/conversations/{convId}/read
GET  /notifications?type=&page=1
POST /notifications/read
POST /notifications/read-all
GET  /notifications/settings
PATCH /notifications/settings
POST /devices/push-token            # 注册推送 token
```

`POST /messages/conversations/{convId}/messages`：

```json
{ "type": "text", "content": "首版已上传，麻烦看下节奏点", "uploadIds": [] }
```

`type`：`text` / `image` / `file` / `video`

`POST /devices/push-token`：

```json
{ "platform": "android", "provider": "fcm", "token": "...", "deviceId": "..." }
```

`provider` 可选：`fcm` / `apns` / `huawei` / `xiaomi` / `oppo` / `vivo`

### 长连接（可选）

订单进度与消息推荐用 WebSocket，避免轮询：

```
wss://ws.autfeng.app/v1?token=<accessToken>
```

服务端推送帧：

```json
{ "event": "order.status_changed", "data": { "orderId": "AF20260729001", "status": "review" }, "ts": 1785267600 }
```

心跳：客户端每 30 秒发 `{"event":"ping"}`，服务端回 `{"event":"pong"}`。90 秒无心跳断开。

---

## 12. 管理端接口

管理端接口前缀 `/admin`，需管理员 token 且校验角色权限，权限不足返回 `40301`。

### 12.1 数据看板

```
GET /admin/dashboard/overview?range=today|7d|30d
GET /admin/dashboard/trend?range=7d
GET /admin/dashboard/funnel
GET /admin/dashboard/todos
GET /admin/logs?page=1
```

### 12.2 内容审核

```
GET  /admin/audit/resources?status=pending&risk=&page=1
GET  /admin/audit/resources/{id}
POST /admin/audit/resources/{id}/pass
POST /admin/audit/resources/{id}/reject
POST /admin/audit/resources/batch
GET  /admin/audit/posts
GET  /admin/audit/reports
POST /admin/audit/reports/{id}/handle
```

`POST /admin/audit/resources/{id}/reject`：

```json
{ "reasons": ["未声明版权来源"], "note": "请补充素材来源与授权链接" }
```

`POST /admin/audit/resources/batch`：

```json
{ "ids": ["p_2099", "p_2100"], "action": "pass" }
```

### 12.3 资源与运营

```
GET    /admin/resources
PATCH  /admin/resources/{id}
POST   /admin/resources/{id}/offline
POST   /admin/resources/{id}/feature
GET    /admin/resources/{id}/stats
GET    /admin/categories
PATCH  /admin/categories/{key}
GET    /admin/ops/banners
POST   /admin/ops/banners
PATCH  /admin/ops/banners/{id}
DELETE /admin/ops/banners/{id}
GET    /admin/ops/slots
PATCH  /admin/ops/slots/{slotId}
GET    /admin/ops/notices
POST   /admin/ops/notices
GET    /admin/ops/topics
POST   /admin/ops/topics
```

`PATCH /admin/ops/slots/{slotId}`：

```json
{ "resourceIds": ["p_2001", "p_2005"], "fillRule": "manual_hot" }
```

`fillRule`：`manual`（纯手动）/ `manual_hot`（手动 + 热度补位）/ `auto_new` / `auto_downloads`

### 12.4 订单与财务

```
GET  /admin/orders
GET  /admin/orders/{id}
POST /admin/orders/{id}/arbitrate
POST /admin/orders/{id}/force-settle
POST /admin/orders/{id}/timeout-compensate
GET  /admin/finance/overview
GET  /admin/finance/withdrawals?status=pending
POST /admin/finance/withdrawals/{id}/pay
POST /admin/finance/withdrawals/{id}/reject
POST /admin/finance/withdrawals/batch-pay
GET  /admin/finance/transactions
GET  /admin/finance/settlements
POST /admin/finance/reconcile
```

`POST /admin/orders/{id}/arbitrate`：

```json
{ "result": "split", "conclusion": "需求文档未明确节奏密度，双方各承担一半", "buyerRefund": 8400 }
```

`result`：`buyer`（判给买家）/ `creator`（判给剪辑师）/ `split`（按进度分账）

### 12.5 用户与创作者

```
GET   /admin/users
GET   /admin/users/{id}
POST  /admin/users/{id}/mute
POST  /admin/users/{id}/ban
POST  /admin/users/{id}/points
POST  /admin/users/{id}/grant-vip
GET   /admin/creators
POST  /admin/creators/{id}/level
POST  /admin/creators/{id}/limit
GET   /admin/creators/applications
POST  /admin/creators/applications/{id}/approve
POST  /admin/creators/applications/{id}/reject
```

`POST /admin/users/{id}/points`：

```json
{ "delta": 100, "reason": "活动补发" }
```

### 12.6 系统设置

```
GET   /admin/settings
PATCH /admin/settings
GET   /admin/roles
POST  /admin/roles
PATCH /admin/roles/{id}
GET   /admin/api-keys
POST  /admin/api-keys/{id}/rotate
GET   /admin/webhooks
POST  /admin/webhooks
POST  /admin/webhooks/{id}/test
```

---

## 13. Webhook 回调

平台向你配置的地址推送事件。

### 13.1 请求格式

```
POST <你的回调地址>
Content-Type: application/json
X-AF-Event: order.status_changed
X-AF-Event-Id: evt_9f2c7b1e
X-AF-Timestamp: 1785267600
X-AF-Signature: <hmac_sha256(body, webhook_secret)>
```

```json
{
  "eventId": "evt_9f2c7b1e",
  "event": "order.status_changed",
  "createdAt": 1785267600,
  "data": {
    "orderId": "AF20260729001",
    "fromStatus": "working",
    "toStatus": "review",
    "operator": "creator"
  }
}
```

### 13.2 事件列表

| 事件 | 触发时机 |
|---|---|
| `order.created` | 需求发布 |
| `order.quoted` | 收到报价 |
| `order.escrow_paid` | 资金托管完成 |
| `order.status_changed` | 订单状态变更（含全部流转） |
| `order.delivered` | 剪辑师提交成片 |
| `order.accepted` | 买家验收 |
| `order.settled` | 结算完成 |
| `order.disputed` | 发起纠纷 |
| `order.arbitrated` | 仲裁完成 |
| `audit.passed` | 投稿审核通过 |
| `audit.rejected` | 投稿被驳回 |
| `resource.offline` | 资源被下架 |
| `withdraw.paid` | 提现打款完成 |
| `withdraw.rejected` | 提现被驳回 |
| `vip.purchased` | 会员购买成功 |
| `vip.expiring` | 会员即将到期（提前 7 天） |
| `user.banned` | 用户被封禁 |

### 13.3 验签与重试

```
expected = HMAC_SHA256(raw_body, webhook_secret)  # hex lowercase
比对 X-AF-Signature，不一致丢弃
```

- 请在 **5 秒内**返回 HTTP 200，响应体内容不作要求
- 非 200 会重试：1s、5s、30s、2min、10min、1h、6h（共 7 次）
- 用 `eventId` 做幂等，同一事件可能重复投递

---

## 14. 状态机

### 14.1 订单状态机

```
                    ┌──────────────┐
                    │   pending    │ 待接单 / 招标中
                    └──────┬───────┘
                    报价    │       取消 / 超时无人接单
                ┌──────────┴──────────┐
                ▼                     ▼
         ┌──────────┐          ┌──────────────┐
         │  quoted  │ 已报价    │  cancelled   │ 已取消
         └────┬─────┘          └──────────────┘
     买家接受 │ 并完成托管               ▲
              ▼                         │ 协商取消 / 超时赔付
         ┌──────────┐                   │
         │ working  │ 制作中 ───────────┤
         └────┬─────┘                   │
     提交成片 │                         │
              ▼                         │
         ┌──────────┐   申请修改   ┌────┴─────┐
         │  review  │ ───────────► │  revise  │ 修改中
         │  待验收   │ ◄─────────── │          │
         └────┬─────┘   重新提交    └──────────┘
   验收 / 超时 │ 自动验收                │
              ▼                         │ 申请介入
         ┌──────────┐             ┌─────▼──────┐
         │   done   │ 已完成       │  dispute   │ 纠纷处理
         └──────────┘             └─────┬──────┘
              ▲                         │ 仲裁
              └─────────────────────────┘
```

| 状态 | code | 允许操作（买家） | 允许操作（剪辑师） |
|---|---|---|---|
| `pending` | 待接单 | 取消、修改需求、催办 | 报价 |
| `quoted` | 已报价 | 接受报价、拒绝 | 修改报价、撤销 |
| `working` | 制作中 | 催进度、申请退款、沟通 | 更新进度、提交成片 |
| `review` | 待验收 | 验收、申请修改、下载 | 等待（可补充说明） |
| `revise` | 修改中 | 沟通 | 重新提交 |
| `done` | 已完成 | 评价、下载、再来一单 | 查看结算 |
| `cancelled` | 已取消 | 重新发布 | - |
| `dispute` | 纠纷处理 | 补充证据 | 补充证据 |

自动流转规则：

- `pending` 超过 72 小时无人报价 → `cancelled`，托管金额退回
- `review` 超过 7 天买家未操作 → `done`，自动结算
- `working` 超过 deadline 24 小时未交付 → 买家可触发 `cancelled` 全额退款

### 14.2 审核状态机

```
draft ──提交──► pending ──通过──► passed ──下架──► offline
                   │                                  │
                   └──驳回──► rejected ──修改重提──────┘
                                   │
                                   └──► pending
```

### 14.3 提现状态机

```
pending ──风控通过 + 打款──► paid
   │
   └──驳回──► rejected（金额退回余额）
```

---

## 15. 枚举字典

### 预设分类 `presetCategory`

| key | 名称 |
|---|---|
| `transition` | 转场 |
| `text` | 文字动效 |
| `particle` | 粒子特效 |
| `color` | 调色 |
| `beat` | 卡点节奏 |
| `camera` | 运镜 |
| `shake` | 抖动 |
| `project` | 完整工程 |

### 素材分类 `assetCategory`

| key | 名称 |
|---|---|
| `video` | 视频素材 |
| `audio` | 音频音效 |
| `font` | 字体 |
| `image` | 图片贴纸 |
| `lut` | LUT 调色 |
| `overlay` | 叠加层 |

### 画面比例 `ratio`

`9:16`（竖屏短视频）· `16:9`（横屏）· `1:1`（方形）· `4:5`（朋友圈 / IG）· `2.35:1`（电影宽银幕）

### 获取方式 `priceType`

| key | 名称 | 说明 |
|---|---|---|
| `free` | 免费 | 所有人可下载 |
| `points` | 积分兑换 | 消耗积分，作者得 70% |
| `vip` | 会员专享 | 仅会员可下载 |
| `paid` | 付费下载 | 平台抽成 15% |

### 授权范围 `license`

| key | 名称 | 可商用 |
|---|---|---|
| `commercial` | 可商用 | 是 |
| `cc-by` | CC-BY 署名 | 是，需署名 |
| `personal` | 仅个人使用 | 否 |

### 版权来源 `copyright.source`

`own`（完全原创）· `mix`（含授权素材）· `remix`（二次创作）· `auth`（获授权代发）

### 服务类型 `serviceType`

| key | 名称 | 参考价（分） |
|---|---|---|
| `same` | 接同款复刻 | 12800 起 |
| `edit` | 视频代剪 | 8800 起 |
| `preset` | 定制预设 | 16800 起 |
| `tutor` | 一对一教学 | 6800 / 小时 |

### 剪辑师等级 `creatorLevel`

`认证剪辑师` · `金牌剪辑师` · `特效专家` · `认证讲师`

### 动态类型 `postKind`

`work`（作品展示）· `ask`（求助）· `tut`（教程）· `notice`（官方公告）

---

## 16. 客户端集成

### 16.1 版本兼容性处理

这是最容易出问题的地方，务必按下面的顺序处理：

1. 每次请求带 `X-AF-Client-Ver`，列表接口另传 `maxVersion` 参数
2. 用响应里的 `compatible` 字段决定下载按钮态，不要在客户端比较版本号
3. 下载前调 `POST /resources/{id}/download`，若返回 `40901` 则弹升级引导
4. 用户在设置里改了「我的 AutFeng 版本」时，同步到 `PATCH /user/me` 的 `prefs.clientVersion`

```
GET /resources?maxVersion=4.2.0&ratio=9:16
```

### 16.2 深链（Deep Link）

客户端需注册 `autfeng://` scheme：

| 链接 | 行为 |
|---|---|
| `autfeng://import?res={resourceId}&token={dlToken}` | 下载并导入资源 |
| `autfeng://resource?id={resourceId}` | 打开资源详情 |
| `autfeng://order?id={orderId}` | 打开订单详情 |
| `autfeng://creator?id={creatorId}` | 打开剪辑师主页 |
| `autfeng://post?id={postId}` | 打开社区动态 |
| `autfeng://vip` | 打开会员购买页 |
| `autfeng://wallet` | 打开钱包 |
| `autfeng://login?qr={qrId}` | 扫码登录确认 |

网页端「在 AutFeng 中打开」按钮即调 `importScheme`。建议同时配置 Universal Link / App Links 作为降级。

### 16.3 导入流程建议

```
1. 校验版本  ->  compatible == false 则提示升级，终止
2. 请求下载  ->  POST /resources/{id}/download
3. 下载文件  ->  用 downloadUrl，校验 md5
4. 检查依赖  ->  requirements.fonts 中缺失的字体先提示安装
5. 导入工程  ->  调用 AutFeng 导入模块
6. 上报结果  ->  POST /resources/{id}/import-result
```

`POST /resources/{id}/import-result`：

```json
{ "success": true, "clientVersion": "4.2.1", "errorCode": null, "errorMessage": null }
```

导入失败的上报会用于修正资源的 `minVersion` 标注，请务必接。

### 16.4 离线与缓存

| 数据 | 建议缓存 | 失效策略 |
|---|---|---|
| 分类 / 筛选项 | 24 小时 | 版本号变化时刷新 |
| 资源列表 | 5 分钟 | 下拉刷新强制更新 |
| 资源详情 | 30 分钟 | 进入页面后台静默刷新 |
| 用户信息 | 常驻 | 登录、支付、验收后刷新 |
| 已下载资源 | 永久 | 用户手动清理 |

列表接口支持 `If-None-Match`，未变更返回 `304`：

```
GET /resources?category=transition
If-None-Match: "W/9f2c7b1e"
```

### 16.5 埋点事件

建议至少上报这些事件，用于漏斗分析：

```
POST /analytics/events
```

```json
{
  "events": [
    { "event": "resource_view", "props": { "resourceId": "p_2001", "from": "category" }, "ts": 1785267600 },
    { "event": "resource_download", "props": { "resourceId": "p_2001", "priceType": "free" }, "ts": 1785267610 },
    { "event": "import_result", "props": { "resourceId": "p_2001", "success": true }, "ts": 1785267640 }
  ]
}
```

关键事件：`app_open` · `resource_view` · `resource_download` · `import_result` · `order_create` · `order_pay` · `vip_view` · `vip_purchase` · `upload_submit`

---

## 17. 错误码

### HTTP 状态码

| 状态码 | 含义 |
|---|---|
| 200 | 请求成功（业务成败看 `code`） |
| 400 | 参数格式错误 |
| 401 | 未认证或 token 失效 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 状态冲突 |
| 422 | 参数校验失败 |
| 429 | 触发限流 |
| 500 | 服务端错误 |

### 业务错误码

| code | 含义 | 建议处理 |
|---|---|---|
| `0` | 成功 | - |
| `40001` | 参数格式错误 | 检查请求体 |
| `40101` | 签名校验失败 | 检查签名算法与密钥 |
| `40102` | 时间戳超出窗口 | 与服务端对时 |
| `40103` | Nonce 重放 | 每次请求生成新 nonce |
| `40104` | Token 已失效 | 走 refresh，失败则重新登录 |
| `40105` | Token 被踢下线 | 提示「账号在其他设备登录」 |
| `40301` | 权限不足 | 隐藏对应入口 |
| `40302` | 账号被封禁 | 展示封禁说明与申诉入口 |
| `40303` | 账号被禁言 | 禁用发布入口 |
| `40401` | 资源不存在 | 返回列表并刷新 |
| `40402` | 资源已下架 | 提示已下架 |
| `40901` | 客户端版本不兼容 | 弹升级引导，标出 `minVersion` |
| `40902` | 积分不足 | 跳积分任务页 |
| `40903` | 需要会员 | 跳会员购买页 |
| `40904` | 需付费购买 | 跳支付流程 |
| `40905` | 订单状态不允许该操作 | 刷新订单详情 |
| `40906` | 余额不足 | 跳充值页 |
| `42201` | 字段校验失败 | 按 `data.fields` 标红 |
| `42202` | 接同款缺少参考链接 | 聚焦参考链接输入框 |
| `42203` | 文件格式不支持 | 提示允许的格式 |
| `42204` | 修改轮次已用尽 | 引导追加付费修改 |
| `42205` | 文件超出大小限制 | 提示上限 |
| `42901` | 请求过于频繁 | 按 `X-RateLimit-Reset` 退避 |
| `42902` | 下载次数超限 | 提示次日恢复 |
| `42903` | 上传次数超限 | 提示稍后再试 |
| `50001` | 服务端内部错误 | 带 `requestId` 反馈 |
| `50301` | 服务维护中 | 展示维护公告 |

---

## 18. 变更日志

### v1.0.0 · 2026-07-29

首个正式版本。

- 认证：短信、密码、扫码三种登录方式
- 资源：预设 / 素材的检索、详情、下载、互动，带版本兼容性校验
- 投稿：三步式上传（凭证 → 直传 → 提交），强制版权来源声明
- 社区：动态发布、互动、话题活动
- 订单：四类服务、公开招标 / 直接指派、资金托管、修改轮次、纠纷仲裁
- 钱包：余额、积分、提现、结算
- 管理端：审核、资源、订单、用户、创作者、财务、运营、系统设置
- Webhook：18 类事件，带签名与重试

### 兼容性承诺

- 已发布字段不删除、不改类型；新增字段客户端需容忍未知字段
- 枚举值可能新增，客户端对未知枚举做兜底展示（用 `xxxName` 字段直接显示服务端下发的名称）
- 破坏性变更走新版本前缀 `/v2`，`/v1` 至少维护 12 个月