# API Reference

本文档记录当前已实现的 `web-api` 与 `manage-api` 接口。阅读顺序建议先看 [API 索引](#api-索引)，再点击接口链接查看后面的 JavaDoc 风格详细说明。这里只说明调用、返回结构和业务规则；规划中的接口见 `docs/requirements/`。

## 通用约定

| 环境 | Base URL | 说明 |
| --- | --- | --- |
| web-api local | `http://localhost:8601/xhzy-live/app` | APP/H5 前台接口。 |
| manage-api local | `http://localhost:8602` | 管理后台接口，根 context。 |
| manage-api dev | `https://test.zhinan.run/xhzy-live` | dev profile 使用 `/xhzy-live`，需部署对应版本后生效。 |
| web-api dev | `https://test.zhinan.run/xhzy-live/app` | 需配置对应 Nginx 转发后生效。 |

下文列出的都是完整接口路径，在对应模块的 Base URL 后直接拼接。需要登录的接口传 `X-Token: <登录响应的 data.token>`；web-api 新签发的用户 Token 统一以 `xhlv_` 开头，manage-api 管理员登录的 `data` 本身就是 Token。APP 调用短信、一键或微信登录时可传 `X-V: <版本号>`，登录成功后保存为用户的 `appVersion`；未传或传空值时不清空已有版本。POST JSON 请求传 `Content-Type: application/json`。响应采用 `ApiResponse<T>`：

```json
{
  "code": 0,
  "message": "成功",
  "data": {}
}
```

业务码严格沿用知南既有约定：`0` 表示成功，`-1` 表示业务处理失败，`-999` 表示无效 Token。参数校验失败、账号或密码错误、数据不存在、数据冲突、没有操作权限及系统内部异常都返回 `code=-1`，具体原因读取 `message`；缺失、过期或已注销的 Token 返回 `code=-999`、`message=无效Token`。业务接口不使用 `400/401/403/404/500` 作为业务码；请求路径不存在时返回 HTTP `404`，响应体为 `{"code":-1,"message":"接口不存在"}`。时间格式为 `yyyy-MM-dd HH:mm:ss`。

分页 `data` 为 `PageVo<T>`：

```json
{
  "list": [],
  "total": 0,
  "current": 1,
  "size": 20
}
```

`page` 默认 1，`pageSize` 默认 20，页大小上限 200。成功导出用户时直接返回 `.xlsx` 文件，不包裹 `ApiResponse`。

当前应用配置了 `spring.jackson.default-property-inclusion=non_null`：示例中的可空字段在实际值为 `null` 时会被省略，包括顶层 `data`。下文用完整示例展示字段形状；前端读取可空字段时应兼容缺省。ID/计数为 JSON number，时间为字符串。

### 公共对象结构

| 对象 | 字段 | 类型 | 说明 |
| --- | --- | --- | --- |
| `PageVo<T>` | `list` | `T[]` | 当前页数据，可为空数组。 |
| `PageVo<T>` | `total` | number | 符合查询条件的总数。 |
| `PageVo<T>` | `current` | number | 当前页码，从 1 开始。 |
| `PageVo<T>` | `size` | number | 每页数量。 |
| `Manager` | `id` | number | 管理员 ID。 |
| `Manager` | `name` | string | 管理员名称。 |
| `Manager` | `passport` | string | 登录账号。 |
| `Manager` | `imageUrl` | string | 管理员头像 URL；历史账号可能缺省。 |
| `Manager` | `roleId` | number | 角色 ID。 |
| `Manager` | `role` | object | `{id,name}`，角色摘要。 |
| `Manager` | `loginTime` | string | 最近登录时间，可缺省。 |
| `Role` | `id` | number | 角色 ID。 |
| `Role` | `name` | string | 角色名称。 |
| `Role` | `description` | string | 角色描述，可缺省。 |
| `Role` | `permission` | JSON | 旧后台兼容的权限配置，通常为权限标识字符串数组，由前端解释。 |
| `Role` | `userNum` | number | 关联管理员数量。 |
| `Role` | `updateTime` | string | 最近更新时间，可缺省。 |
| `SysParam` | `id` | number | 配置 ID。 |
| `SysParam` | `paramKey` | string | 配置键。 |
| `SysParam` | `name` | string | 配置名称。 |
| `SysParam` | `content` | JSON | 配置内容，可为对象、数组或其他 JSON 值。 |
| `SysParam` | `showStatus` | number | 展示状态，可缺省。 |
| `AuditLog` | `time` | string | 操作时间。 |
| `AuditLog` | `managerId` | number | 操作人 ID，可缺省。 |
| `AuditLog` | `managerName` | string | 操作人名称，可缺省。 |
| `AuditLog` | `action` | string | 操作名称。 |
| `AuditLog` | `targetType` | string | 操作对象类型，可缺省。 |
| `AuditLog` | `targetId` | string | 操作对象 ID，可缺省。 |
| `AuditLog` | `targetName` | string | 操作对象名称，可缺省。 |
| `AuditLog` | `ip` | string | 客户端 IP，可缺省。 |
| `AuditLog` | `success` | boolean | 是否成功。 |
| `LoginRecord` | `id` | number | 登录记录 ID。 |
| `LoginRecord` | `deviceInfo` | string | 设备信息，可缺省。 |
| `LoginRecord` | `loginType` | string | 登录类型，可缺省。 |
| `LoginRecord` | `ip` | string | 登录 IP，可缺省。 |
| `LoginRecord` | `loginTime` | string | 登录时间，可缺省。 |

`User` 字段较多，见业务用户分组内的字段表。示例中的具体 ID、名称、时间均为形状示意，不代表测试库已有这些记录。

## API 索引

### web-api

| 分组 | 说明 | API |
| --- | --- | --- |
| 公共配置 | 读取旧 APP 兼容的公共配置，并获取前台 COS 直传签名。 | [前台配置列表](#get-commonsys_params)<br>[职业列表](#get-commonoccupation)<br>[获取 COS 签名](#get-commoncossign) |
| 微页面 | 按 ID 匿名读取后台维护的微页面。 | [微页面详情](#get-micro_pageinfo) |
| 我的 | 用户资料、微信换绑、账号注销、反馈、商城订单和收货地址兼容接口。 | [个人资料](#get-userinfo)<br>[修改个人资料](#post-usermodifyinfo)<br>[微信绑定信息](#get-userbindlist)<br>[微信不可解绑](#post-userunbindwx)<br>[绑定/换绑微信](#post-userbindwx)<br>[注销账号](#post-userunregister)<br>[意见反馈](#post-feedbackadd)<br>[订单分页](#get-usershoporderpage)<br>[订单详情](#get-usershoporderinfo)<br>[地址列表](#get-userconsigneelist)<br>[地址详情](#get-userconsigneeinfo) |
| 前台登录与身份绑定 | 发送验证码、手机号/一键/微信登录、采集 APP 版本、绑定手机号或微信、注销账号、退出登录。 | [发送登录验证码](#post-verify_codesendlogin)<br>[发送绑定验证码](#post-verify_codesendbind)<br>[发送注销验证码](#post-verify_codesendunregister)<br>[短信验证码登录](#post-logincode)<br>[一键登录](#post-logincert)<br>[微信登录](#post-loginwx)<br>[绑定微信](#post-userbindwx)<br>[绑定手机号](#post-userbindphone)<br>[注销账号](#post-userunregister)<br>[退出登录](#post-loginout) |
| 商城商品与购物车 | 匿名浏览商品和分组；登录后维护购物车、记录商品浏览。 | [商城商品接口](#shop-product-api)<br>[购物车接口](#shop-cart-api)<br>[商品浏览统计](#get-stat-shopproductsee) |
| 商城地址与订单 | 地址簿、结算、下单、支付及用户订单；地址和订单均归商城库。 | [地址列表](#get-userconsigneelist)<br>[地址详情](#get-userconsigneeinfo)<br>[新增地址](#post-userconsigneeadd)<br>[修改地址](#post-userconsigneemodify)<br>[删除地址](#post-userconsigneedelete)<br>[结算支付接口](#shop-pay-api)<br>[订单分页](#get-usershoporderpage)<br>[订单详情](#get-usershoporderinfo)<br>[订单物流](#get-usershoporderexpress)<br>[修改备注](#post-usershopordermodifynote)<br>[修改订单地址](#post-usershopordermodifyconsignee)<br>[批量修改订单地址](#post-usershopordermodifybatchconsignee)<br>[取消订单](#post-usershopordercancel)<br>[确认收货](#post-usershoporderitemsure)<br>[删除订单](#post-usershoporderdelete)<br>[支付回调](#shop-payment-callback-api) |

### manage-api

| 分组 | 说明 | API |
| --- | --- | --- |
| 后台认证与会话 | 管理员登录、获取当前账号及权限、修改密码、退出登录。 | [登录](#post-manage-login)<br>[登录信息](#get-manage-login_info)<br>[修改密码](#post-manage-modify_pwd)<br>[退出登录](#post-manage-logout) |
| 后台账号管理 | 获取 COS 签名，查询、新增、修改与删除管理员账号。 | [获取 COS 签名](#get-manage-commoncossign)<br>[账号分页](#get-manage-managerpage)<br>[账号详情](#get-manage-managerinfo)<br>[新增账号](#post-manage-manageradd)<br>[修改账号](#post-manage-managermodify)<br>[删除账号](#post-manage-managerdelete) |
| 后台角色管理 | 查询、维护角色和前端权限配置。 | [角色分页](#get-manage-rolepage)<br>[角色列表](#get-manage-rolelist)<br>[角色详情](#get-manage-roleinfo)<br>[新增角色](#post-manage-roleadd)<br>[修改角色](#post-manage-rolemodify)<br>[删除角色](#post-manage-roledelete)<br>[账号可选角色](#get-manage-commonrolelist) |
| 后台系统配置 | 查询和维护系统参数。 | [配置列表](#get-manage-sys_paramlist)<br>[配置详情](#get-manage-sys_paraminfo)<br>[修改配置](#post-manage-sys_parammodify) |
| 后台操作日志 | 按条件分页查看操作记录。 | [操作日志分页](#get-manage-operation_logpage) |
| 后台业务用户 | 查询与导出用户、查看验证码和登录记录、维护手机号、客服备注、状态及密码。 | [用户分页](#get-manage-userpage)<br>[登录记录](#get-manage-userlogin_recordpage)<br>[查看验证码](#get-manage-userverify_code)<br>[手机号占用检查](#post-manage-usermodifypassportcheck)<br>[修改手机号](#post-manage-usermodifypassport)<br>[修改客服备注](#post-manage-usermodifyremark)<br>[修改用户状态](#post-manage-usermodifystatus)<br>[重置用户密码](#post-manage-usermodifypassword)<br>[导出用户](#get-manage-userexport) |
| 意见反馈 | 按处理状态查询、处理并导出用户反馈，接口与星鹤国学后台一致。 | [反馈分页](#get-manage-feedbackpage)<br>[处理反馈](#post-manage-feedbackprocess)<br>[导出反馈](#get-manage-feedbackexport) |
| 微页面 | 查询、新增、修改、复制和删除微页面，接口与星鹤国学后台一致。 | [微页面分页](#get-manage-micro_pagepage)<br>[微页面详情](#get-manage-micro_pageinfo)<br>[新增微页面](#post-manage-micro_pageadd)<br>[修改微页面](#post-manage-micro_pagemodify)<br>[复制微页面](#post-manage-micro_pagecopy)<br>[删除微页面](#post-manage-micro_pagedelete) |
| 平台管理 | 查询、新增、编辑和删除课程平台。 | [平台列表](#get-manage-platformpage)<br>[平台详情](#get-manage-platforminfo)<br>[新增平台](#post-manage-platformadd)<br>[编辑平台](#post-manage-platformmodify)<br>[删除平台](#post-manage-platformdelete) |
| 商城商品管理 | 商品、分类、标签及商品关联资源。 | [商城商品管理接口](#manage-shop-product-api) |
| 商城订单与履约 | 订单查询、线下单、发货、退款、导入和导出。 | [商城订单管理接口](#manage-shop-order-api) |
| 商城交易与统计 | 交易账户、账单、销售统计及常用选项。 | [商城交易与统计接口](#manage-shop-statistic-api) |
| 商城任务与购课记录 | 导入导出任务和阶段性购课记录查询。 | [商城任务与购课记录接口](#manage-shop-task-api) |

## web-api 接口

## 公共配置

<a id="get-commonsys_params"></a>

### GET /common/sys_params

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/CommonController.java` |
| Service | `web-api/src/main/java/com/xhzy/live/web/service/CommonService.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/SysParamVo.java` |

#### 功能

匿名读取后台配置管理中允许前台展示的配置。接口与后台 `/manage/sys_param/list` 共用 `sys_param` 数据和字段含义，只返回 `show_status=1` 的记录并按 ID 升序排列；不向前台开放配置详情和修改能力。`content` 是 JSON 数组或对象时按原结构返回，其他内容按字符串返回。

#### 输入

无 Query、Body 或 Token 要求。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "paramKey": "app.customer_service",
      "name": "客服配置",
      "content": {
        "phone": "400-000-0000"
      },
      "showStatus": 1
    }
  ]
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data[].id | number | 配置 ID。 |
| data[].paramKey | string | 配置键，与后台配置管理一致。 |
| data[].name | string | 配置名称。 |
| data[].content | object、array 或 string | 配置内容；JSON 数组或对象会解析后返回。 |
| data[].showStatus | number | 前台展示状态；本接口固定为 `1`。 |

<a id="get-commonoccupation"></a>

### GET /common/occupation

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/CommonController.java` |
| Service | `web-api/src/main/java/com/xhzy/live/web/service/CommonService.java` |

#### 功能

兼容旧星鹤国学 APP 的职业列表接口，用于个人资料编辑时选择职业。接口读取 `sys_param` 表中 `param_key=occupation` 的 `content`，JSON 数组或对象按原结构返回；普通字符串按字符串返回。

#### 输入

无 Query 或 Body 参数。请求头必须携带有效 `X-Token`。

#### 输出

配置为职业数组时：

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "label": "机关组织职员",
      "value": "B"
    },
    {
      "label": "机关组织中层管理",
      "value": "C"
    },
    {
      "label": "机关组织高管",
      "value": "D"
    },
    {
      "label": "企事业单位职员",
      "value": "E"
    },
    {
      "label": "企事业单位中层管理",
      "value": "F"
    },
    {
      "label": "企事业单位高管",
      "value": "G"
    },
    {
      "label": "私营企业职员",
      "value": "H"
    },
    {
      "label": "私营企业中层管理",
      "value": "I"
    },
    {
      "label": "私营企业高管",
      "value": "J"
    },
    {
      "label": "自由职业者",
      "value": "K"
    },
    {
      "label": "学生",
      "value": "L"
    },
    {
      "label": "已退休",
      "value": "A"
    },
    {
      "label": "其他",
      "value": "M"
    }
  ]
}
```

未配置 `occupation` 时保持旧接口行为，返回空字符串：

```json
{
  "code": 0,
  "message": "成功",
  "data": ""
}
```

#### 错误响应

Token 缺失、过期或已注销时返回 `code=-999`、`message=无效Token`。

<a id="get-commoncossign"></a>

### GET /common/cos/sign

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/CommonController.java` |
| Service | `web-api/src/main/java/com/xhzy/live/web/service/CosService.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/CosSignVo.java` |

#### 功能

为 APP/H5 获取腾讯云 COS 直传签名，完整地址为 `GET /xhzy-live/app/common/cos/sign`。接口需有效 `X-Token`，参数、签名算法、有效期和返回字段均与后台 `/manage/common/cos/sign` 一致，签名有效期为 3 小时。前后台读取同一组 `TENCENT_COS_*` 配置，使用同一个 AccessKey、SecretKey 和存储桶。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 是 | COS 对象键，必须以 `/` 开头，例如 `/xhzy-live/avatar/0123456789abcdef.png`；按请求值原样参与签名。 |
| method | string | 是 | 待签名的 HTTP 方法；不区分大小写，上传时传 `PUT`。 |

请求头必须携带有效 `X-Token`。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "sign": "q-sign-algorithm=sha1&...",
    "domain": "https://xhzy-live-1320544726.cos.ap-shanghai.myqcloud.com",
    "region": "ap-shanghai",
    "bucket": "xhzy-live-1320544726"
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.sign | string | 放入 COS 上传请求 `Authorization` 头的签名。 |
| data.domain | string | COS 原生存储桶域名。 |
| data.region | string | COS 地域。 |
| data.bucket | string | COS 存储桶名称。 |

前端对 `domain + key` 发起 `PUT` 请求，并设置 `Authorization: <data.sign>`。签名和实际上传必须使用完全相同的 `key`；上传域名必须使用接口返回的原生存储桶域名。

#### 错误响应

- Token 缺失、过期或已注销：`code=-999`、`message=无效Token`。
- `key` 为空或未以 `/` 开头、`method` 为空或不合法：`code=-1` 和对应业务提示。
- COS 密钥、存储桶、地域或域名未配置完整：`code=-1`、`message=腾讯云 COS 配置不完整`。

<a id="mine-api"></a>

## 我的模块

所有接口使用 `X-Token` 请求头，响应继续兼容旧 APP 的 `{code,message,data}` 结构。新 APP 不展示卡包、积分、购物车和学员学号；`GET /user/info` 仍保留旧客户端使用的字段，包括 `studentCode`，但新页面不读取该字段。

| 方法 | 地址 | 说明 | 兼容性 |
| --- | --- | --- | --- |
| GET | `/user/info` | 读取个人资料 | 旧地址和旧字段兼容 |
| POST | `/user/modify/info` | 修改昵称、头像、性别、生日、签名、职位和城市 | 旧地址和旧请求字段兼容 |
| POST | `/user/bind/wx` | 首次绑定或换绑微信 | 不提供解绑；跨微信应用按 `unionId` 校验归属 |
| GET | `/user/bind/list` | 查询微信绑定信息 | 旧地址及 `data.wx` 返回结构兼容 |
| POST | `/user/unbind/wx` | 旧客户端解绑入口 | 保留旧地址并返回“微信仅支持换绑，不可解绑” |
| POST | `/user/unregister` | 验证手机号验证码并注销当前账号 | 旧地址、请求字段和验证码类型兼容 |
| POST | `/feedback/add` | 提交意见反馈及资源 URL | 旧地址和旧请求字段兼容 |
| GET | `/user/shop/order/page` | 分页读取商城订单 | 旧地址、筛选参数和分页响应兼容 |
| GET | `/user/shop/order/info` | 读取订单详情 | 旧地址兼容 |
| GET | `/user/shop/order/express` | 读取订单物流 | 商城 Starter 正式接口 |
| POST | `/user/shop/order/modify/note` | 修改订单备注 | 旧地址兼容 |
| POST | `/user/shop/order/modify/consignee` | 修改订单地址快照 | 商城 Starter 正式接口 |
| POST | `/user/shop/order/modify/batch/consignee` | 批量修改订单地址快照 | 商城 Starter 正式接口 |
| POST | `/user/shop/order/cancel` | 取消订单 | 旧地址兼容 |
| POST | `/user/shop/order/item/sure` | 确认收货 | 旧地址兼容 |
| POST | `/user/shop/order/delete` | 删除关闭订单 | 旧地址兼容 |
| GET | `/user/consignee/list` | 收货地址列表 | 旧地址和返回字段兼容 |
| GET | `/user/consignee/info` | 收货地址详情 | 旧地址和返回字段兼容 |
| POST | `/user/consignee/add` | 新增收货地址 | 旧地址和请求字段兼容 |
| POST | `/user/consignee/modify` | 修改收货地址 | 旧地址和请求字段兼容 |
| POST | `/user/consignee/delete` | 删除收货地址 | 旧地址和请求字段兼容 |
| POST | `/login/out` | 退出登录 | 旧地址兼容 |

微信换绑只有在新微信未归属其他用户时才会解除当前绑定并写入新绑定。若相同 `unionId` 已通过任一微信 `appId` 关联其他用户，响应为：

```json
{
  "code": -1,
  "message": "绑定失败：您绑定的微信已关联其他账号",
  "data": null
}
```

<a id="post-userunregister"></a>

### POST /user/unregister

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserController.java` |
| Service | `web-api/src/main/java/com/xhzy/live/web/service/UserService.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/UnregisterVo.java` |

#### 功能

使用 `/verify_code/send/unregister` 发送的验证码注销当前账号。接口保持旧 APP 的地址、请求字段和注销验证码类型 `4`。注销成功后账号状态改为已删除，释放原手机号、解除微信绑定并撤销该用户的全部 Token；旧 Token 立即失效，历史业务记录保留，原手机号可重新注册新账号。

#### 输入

请求头必须携带有效 `X-Token`。

```json
{
  "code": "1234"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 当前账号绑定手机号收到的注销验证码。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -999 | `无效Token` | Token 缺失、过期或账号已注销。 |
| 200 | -1 | `请输入验证码` | 验证码为空。 |
| 200 | -1 | `当前账号未绑定手机号码` | 当前账号只有微信身份，尚未绑定手机号。 |
| 200 | -1 | `验证码不正确，请重新输入！` | 验证码错误或不是注销类型。 |
| 200 | -1 | `验证码已过期，请重新获取` | 验证码超过有效期。 |

<a id="get-userinfo"></a>

### GET /user/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserController.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginInfoVo.java` |

#### 功能

读取当前登录用户资料。请求头必须携带有效 `X-Token`。为兼容旧 APP，响应仍包含学员状态、学员学号和 IM 签名等历史字段；新 APP 的“我的”页面不展示 `studentCode`。

#### 输入

无 Query 或 Body 参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 10001,
    "name": "星鹤用户",
    "imageUrl": "https://example.com/avatar.png",
    "sex": "女",
    "passport": "13800138000",
    "occupation": "讲师",
    "city": "苏州市",
    "cityCode": "320500",
    "birthday": "1990-01-01",
    "studentCode": "XH000001",
    "personalSignature": "日日精进",
    "studentStatus": 1,
    "initStatus": 1,
    "pushStatus": 1,
    "tlsSign": "im-user-signature"
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.id` | number | 用户 ID。 |
| `data.name` | string | 昵称，可缺省。 |
| `data.imageUrl` | string | 头像 URL，可缺省。 |
| `data.sex` | string | 性别，可缺省。 |
| `data.passport` | string | 已绑定手机号；微信新用户未绑定时缺省。 |
| `data.occupation` | string | 职业，可缺省。 |
| `data.city` | string | 城市名称，可缺省。 |
| `data.cityCode` | string | 城市编码，可缺省。 |
| `data.birthday` | string | 生日，可缺省。 |
| `data.studentCode` | string | 旧客户端兼容学员学号；新 APP 不展示，可缺省。 |
| `data.personalSignature` | string | 个性签名，可缺省。 |
| `data.studentStatus` | number | 旧客户端兼容学员状态。 |
| `data.initStatus` | number | 旧客户端兼容初始化状态。 |
| `data.pushStatus` | number | 推送开关状态。 |
| `data.tlsSign` | string | 旧客户端兼容 IM 签名，可缺省。 |

#### 错误响应

Token 缺失、过期或已注销时返回 `code=-999`、`message=无效Token`。

<a id="post-usermodifyinfo"></a>

### POST /user/modify/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/ModifyUserInfoVo.java` |

#### 功能

修改当前用户基础资料。接口按请求中提供的非 `null` 字段覆盖用户资料，不修改手机号、微信绑定、学员状态或学员学号。

#### 输入

```json
{
  "name": "星鹤用户",
  "imageUrl": "https://example.com/avatar.png",
  "sex": "女",
  "birthday": "1990-01-01",
  "personalSignature": "日日精进",
  "occupation": "讲师",
  "city": "苏州市",
  "cityCode": "320500"
}
```

以上字段均为 string，均可缺省；请求头必须携带有效 `X-Token`。

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

<a id="get-userbindlist"></a>

### GET /user/bind/list

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserController.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/UserBindVo.java` |

#### 功能

查询当前用户的微信绑定信息。未绑定微信时 `data` 返回空对象；已绑定时沿用旧客户端的 `data.wx` 结构。

#### 输入

无 Query 或 Body 参数。请求头必须携带有效 `X-Token`。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "wx": {
      "openId": "oExampleOpenId",
      "nickName": "微信昵称",
      "avatarUrl": "https://example.com/wechat-avatar.png"
    }
  }
}
```

`wx.cellphone` 是旧结构保留字段，当前实现没有赋值，因此按非空序列化规则不返回。

<a id="post-userunbindwx"></a>

### POST /user/unbind/wx

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserController.java` |

#### 功能

旧客户端兼容入口。当前规则不允许解绑微信，只允许通过 `POST /user/bind/wx` 换绑；该接口在 Token 有效时固定返回业务失败。

#### 输入

无 Query 或 Body 参数。请求头必须携带有效 `X-Token`。

#### 输出

```json
{
  "code": -1,
  "message": "微信仅支持换绑，不可解绑"
}
```

<a id="post-feedbackadd"></a>

### POST /feedback/add

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/FeedbackController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/FeedbackVo.java` |

#### 功能

提交当前用户的意见反馈。`resources` 保存前端已经上传完成的资源 URL；本接口不接收文件二进制。

#### 输入

```json
{
  "title": "功能建议",
  "content": "希望订单展示更简洁",
  "isContact": 1,
  "resources": [
    "https://example.com/feedback-1.png"
  ]
}
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | string | 否 | 反馈标题。 |
| `content` | string | 是 | 反馈正文，不能为空。 |
| `isContact` | number | 否 | 是否愿意客服联系，默认 `0`。 |
| `resources` | string[] | 否 | 图片或附件 URL；空值和空字符串会被忽略。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

#### 错误响应

`content` 为空时返回 `code=-1`、`message=反馈内容不能为空`；Token 无效时返回 `code=-999`。

## 微页面

<a id="get-micro_pageinfo"></a>

### GET /micro_page/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/MicroPageController.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/MicroPageVo.java` |

#### 功能

按 ID 匿名读取状态为 `1` 的微页面，兼容旧星鹤 APP 接口路径。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 微页面 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 7,
    "name": "审核合规页",
    "dataUrl": "https://example.com/micro_page/7/page.json",
    "content": {
      "components": []
    }
  }
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面ID不能为空` | `id` 未传。 |
| 200 | -1 | `微页面不存在` | 页面不存在或状态不是 `1`。 |
| 200 | -1 | `微页面内容未配置` | 微页面没有 COS 内容地址。 |
| 200 | -1 | `微页面内容读取失败` | COS 文件不可访问或正文不是合法 JSON。 |

## 前台登录与身份绑定

前台登录响应统一返回 `LoginVo`。手机号登录后若 `needBindWechat=true`，APP 必须引导用户完成微信绑定；微信新用户登录后若 `needBindCellphone=true`，APP 可引导绑定手机号，也允许暂时跳过。

dev 测试环境不调用短信供应商，登录、绑定手机号和注销账号统一使用固定验证码 `111111`。正式环境仍按短信配置生成并发送随机验证码。

`LoginVo.info` 字段如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | number | 用户 ID。 |
| name | string | 用户名称，可缺省。 |
| imageUrl | string | 用户头像 URL，可缺省。 |
| sex | string | 性别，可缺省。 |
| passport | string | 手机号；尚未绑定手机号的微信用户缺省。 |

<a id="post-verify_codesendlogin"></a>

### POST /verify_code/send/login

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/VerifyCodeController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/SendVerifyCodeVo.java` |

#### 功能

向手机号发送登录验证码。无需 Token。验证码有效期由 `xhzy.auth.verify-code-expire-seconds` 配置，当前默认 300 秒。

#### 输入

```json
{
  "cellphone": "13800138000"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cellphone | string | 是 | 11 位中国大陆手机号，格式为 `1` 加 10 位数字。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `请输入手机号码` | 手机号为空。 |
| 200 | -1 | `请输入正确的手机号码` | 手机号格式错误。 |
| 200 | -1 | `验证码发送失败，请稍后重试` | 短信供应商调用失败。 |

<a id="post-verify_codesendbind"></a>

### POST /verify_code/send/bind

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/VerifyCodeController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/SendVerifyCodeVo.java` |

#### 功能

向手机号发送微信账号绑定手机号所需验证码。当前接口无需 Token，真正绑定时由 `/user/bind/phone` 校验 Token 和验证码。

#### 输入

```json
{
  "cellphone": "13800138000"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cellphone | string | 是 | 11 位中国大陆手机号。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

错误响应与 `/verify_code/send/login` 相同。

<a id="post-verify_codesendunregister"></a>

### POST /verify_code/send/unregister

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/VerifyCodeController.java` |
| Service | `web-api/src/main/java/com/xhzy/live/web/service/UserService.java` |

#### 功能

向当前登录账号绑定的手机号发送注销验证码。接口保持旧 APP 的地址和无 Body 调用方式，验证码类型为 `4`，默认有效期 300 秒。正式环境注销短信模板通过 `XHZY_SMS_UNREGISTER_TEMPLATE_ID` 配置，当前默认模板 ID 为 `1933320`。

#### 输入

请求头必须携带有效 `X-Token`，无 Query 或 Body 参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -999 | `无效Token` | Token 缺失、过期或账号已注销。 |
| 200 | -1 | `当前账号未绑定手机号码` | 当前账号只有微信身份，尚未绑定手机号。 |
| 200 | -1 | `短信服务未配置：XHZY_SMS_UNREGISTER_TEMPLATE_ID` | 正式环境未配置注销短信模板。 |
| 200 | -1 | `验证码发送失败，请稍后重试` | 短信供应商调用失败。 |

<a id="post-logincode"></a>

### POST /login/code

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/LoginController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/PhoneLoginVo.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginVo.java` |

#### 功能

使用手机号和短信验证码登录。手机号未注册时自动创建用户，昵称为手机号后四位，头像为 `https://cos.xhlive.com.cn/common/default_avatar.png`。若用户尚未绑定微信，返回 `needBindWechat=true`，前台必须继续微信绑定流程；已有用户登录时不覆盖其昵称和头像。

#### 输入

请求头：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| X-V | string | 否 | APP 版本号，例如 `1.0.0`；登录成功后保存到用户的 `appVersion`。 |

```json
{
  "cellphone": "13800138000",
  "code": "111111",
  "deviceType": "android/15"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cellphone | string | 是 | 11 位中国大陆手机号。 |
| code | string | 是 | `/verify_code/send/login` 发送的验证码。 |
| deviceType | string | 是 | 客户端设备及系统描述。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "token": "xhlv_example_token",
    "info": {
      "id": 10001,
      "name": "8000",
      "imageUrl": "https://cos.xhlive.com.cn/common/default_avatar.png",
      "passport": "13800138000"
    },
    "needBindCellphone": false,
    "needBindWechat": true
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.token | string | 登录 Token，后续通过 `X-Token` 请求头传递。 |
| data.openId | string | 微信 OpenID；手机号登录时通常缺省。 |
| data.info | object | 当前用户资料，字段见本分组开头。 |
| data.needBindCellphone | boolean | 是否需要引导绑定手机号；手机号登录固定为 `false`。 |
| data.needBindWechat | boolean | 是否必须继续绑定微信。 |

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `验证码不正确，请重新输入！` | 验证码不存在、已使用或类型不匹配。 |
| 200 | -1 | `验证码已过期，请重新获取` | 验证码超过有效期。 |
| 200 | -1 | `登录异常，如有疑问，请咨询客服` | 用户状态不可登录。 |

<a id="post-logincert"></a>

### POST /login/cert

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/LoginController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/OneClickLoginVo.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginVo.java` |

#### 功能

使用极光认证 SDK 返回的登录凭证完成本机号码一键登录。服务端向极光校验凭证，并使用 2048 位 RSA `OAEPWithSHA-256AndMGF1Padding` 解密手机号；后续注册、登录和微信绑定规则与 `/login/code` 相同。

#### 输入

请求头：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| X-V | string | 否 | APP 版本号，例如 `1.0.0`；登录成功后保存到用户的 `appVersion`。 |

```json
{
  "token": "jverify-login-token",
  "deviceType": "ios/18.0"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| token | string | 是 | 极光认证 SDK 返回的一次性 loginToken，不是本站 `X-Token`。 |
| deviceType | string | 是 | 客户端设备及系统描述。 |

#### 输出

返回结构与 `/login/code` 相同。新手机号用户的昵称为手机号后四位，头像为 `https://cos.xhlive.com.cn/common/default_avatar.png`，并返回 `needBindWechat=true`；已有用户登录时不覆盖其昵称和头像。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `一键登录凭证不能为空` | loginToken 为空。 |
| 200 | -1 | `一键登录未配置：{配置项}` | `XHZY_JVERIFY_APP_KEY`、`XHZY_JVERIFY_MASTER_SECRET` 或与极光控制台公钥配对的 `XHZY_JVERIFY_RSA_PRIVATE_KEY` 未配置。 |
| 200 | -1 | `一键登录失败：{极光错误信息}` | 极光未返回成功码 `8000`。 |
| 200 | -1 | `一键登录手机号解密失败` | RSA 私钥不匹配或手机号密文异常。 |

<a id="post-loginwx"></a>

### POST /login/wx

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/LoginController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/WechatLoginVo.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginVo.java` |

#### 功能

使用微信移动应用授权返回的 code 登录。首次登录会创建不带手机号的用户并立即签发 Token，返回 `needBindCellphone=true`；手机号绑定可跳过。

#### 输入

请求头：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| X-V | string | 否 | APP 版本号，例如 `1.0.0`；登录成功后保存到用户的 `appVersion`。 |

```json
{
  "code": "wechat-oauth-code",
  "deviceType": "ios/18.0"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 微信 SDK 授权后返回的一次性 code。 |
| deviceType | string | 是 | 客户端设备及系统描述。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "token": "xhlv_example_token",
    "openId": "wechat-open-id",
    "info": {
      "id": 10002,
      "name": "微信用户",
      "imageUrl": "https://example.com/avatar.png"
    },
    "needBindCellphone": true,
    "needBindWechat": false
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.token | string | 已登录 Token；用户跳过手机号绑定后仍可继续使用。 |
| data.openId | string | 当前微信 OpenID。 |
| data.info.passport | string | 已绑定手机号时返回；新微信用户缺省。 |
| data.needBindCellphone | boolean | 是否显示可跳过的手机号绑定引导。 |
| data.needBindWechat | boolean | 微信登录固定为 `false`。 |

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微信授权码不能为空` | code 为空。 |
| 200 | -1 | `微信登录未配置：{配置项}` | `XHZY_WECHAT_APP_ID` 或 `XHZY_WECHAT_APP_SECRET` 未配置。 |
| 200 | -1 | `微信授权失败` | 微信 access token 换取失败。 |
| 200 | -1 | `获取微信用户信息失败` | 微信用户资料查询失败。 |
| 200 | -1 | `微信绑定用户不存在` | 历史绑定关系指向已不存在的用户。 |

<a id="post-userbindwx"></a>

### POST /user/bind/wx

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserIdentityController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/BindWechatVo.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginVo.java` |

#### 功能

为当前手机号用户绑定微信。需有效 `X-Token`。新客户端传微信授权 `code`；兼容旧客户端传 `openId`，但该 OpenID 必须已存在于当前微信应用的身份记录中。`code` 与 `openId` 至少提供一个，优先使用 `code`。

#### 输入

请求头：`X-Token: xhlv_example_token`

```json
{
  "code": "wechat-oauth-code",
  "deviceType": "android/15"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 条件必填 | 微信 SDK 授权 code；新客户端使用。 |
| openId | string | 条件必填 | 兼容旧客户端，仅允许绑定服务端已记录的 OpenID。 |
| deviceType | string | 否 | 设备描述，缺省时使用 `app`。 |

#### 输出

返回完整 `LoginVo` 和新的 Token；`needBindWechat=false`。前端应使用新 Token 覆盖本地旧 Token。

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "token": "xhlv_reissued_token",
    "openId": "wechat-open-id",
    "info": {
      "id": 10001,
      "name": "13800138000",
      "passport": "13800138000"
    },
    "needBindCellphone": false,
    "needBindWechat": false
  }
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -999 | `无效Token` | Token 缺失、过期或已注销。 |
| 200 | -1 | `微信授权码不能为空` | code 和 openId 都未提供。 |
| 200 | -1 | `微信登录未配置：{配置项}` | 使用 code 授权时，`XHZY_WECHAT_APP_ID` 或 `XHZY_WECHAT_APP_SECRET` 未配置。 |
| 200 | -1 | `微信授权失败` | 使用 code 授权时，微信 access token 换取失败。 |
| 200 | -1 | `获取微信用户信息失败` | 使用 code 授权时，微信用户资料查询失败。 |
| 200 | -1 | `微信身份不存在，请重新授权` | 旧客户端提交的 openId 未被服务端记录。 |
| 200 | -1 | `绑定失败：您绑定的微信已关联其他账号` | 微信 OpenID 或同一 unionId 已属于另一个用户。 |

<a id="post-userbindphone"></a>

### POST /user/bind/phone

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/UserIdentityController.java` |
| Request VO | `web-api/src/main/java/com/xhzy/live/web/vo/BindCellphoneVo.java` |
| Response VO | `web-api/src/main/java/com/xhzy/live/web/vo/LoginVo.java` |

#### 功能

为当前微信用户绑定手机号。需有效 `X-Token`。若手机号已有未绑定其他微信的账号，服务端会将当前微信身份合并到该手机号账号、注销临时微信账号并签发新 Token。

#### 输入

请求头：`X-Token: xhlv_example_token`

```json
{
  "cellphone": "13800138000",
  "code": "1234",
  "deviceType": "ios/18.0"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cellphone | string | 是 | 11 位中国大陆手机号。 |
| code | string | 是 | `/verify_code/send/bind` 发送的验证码。 |
| deviceType | string | 否 | 设备描述，缺省时使用 `app`。 |

#### 输出

返回完整 `LoginVo` 和新的 Token，两个绑定标志均为 `false`。前端必须使用新 Token 覆盖本地旧 Token。

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "token": "xhlv_reissued_token",
    "openId": "wechat-open-id",
    "info": {
      "id": 10001,
      "name": "微信用户",
      "imageUrl": "https://example.com/avatar.png",
      "passport": "13800138000"
    },
    "needBindCellphone": false,
    "needBindWechat": false
  }
}
```

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -999 | `无效Token` | Token 缺失、过期或已注销。 |
| 200 | -1 | `当前账号未绑定微信` | 当前用户不是微信登录账号。 |
| 200 | -1 | `验证码不正确，请重新输入！` | 绑定验证码无效。 |
| 200 | -1 | `该手机号已绑定其他微信` | 目标手机号已有不同微信绑定。 |

<a id="post-loginout"></a>

### POST /login/out

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `web-api/src/main/java/com/xhzy/live/web/controller/LoginController.java` |

#### 功能

注销 `X-Token`。为兼容旧 APP，Token 缺失时也返回成功。

#### 输入

请求头：`X-Token: xhlv_example_token`。无请求体。

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

## 商城接口

商城接口由 `shop-web-spring-boot-starter` 提供，在本服务中仍使用 web-api 的 Base URL 和 `X-Token`。商城系统编码由服务端固定为 `xhlive`，前端传入的 `sysCode`、用户 ID、商品价格和支付金额均不作为可信数据。下单时服务端重新读取商品、规格、价格及库存。

直播间下单时，前端在创建订单请求中附带以下可选请求头；`X-Live-Id` 存在时，订单来源固定记录为 `LIVE_ROOM`：

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `X-Live-Id` | 否 | 直播间 ID；直播间下单必须传。 |
| `X-Channel-Id` | 否 | 渠道 ID。 |
| `X-Invite-Code` | 否 | 邀请码。 |
| `X-Order-Source` | 否 | 来源补充标识。 |

<a id="shop-product-api"></a>

### 商品与分组

| 方法 | 路径 | Token | 输入 | 输出 |
| --- | --- | --- | --- | --- |
| GET | `/shop/product/list` | 否 | `ids`，可重复传入的商品 ID。 | 商品数组。 |
| GET | `/shop/product/page` | 否 | `key,page,pageSize`。 | 商品分页。 |
| GET | `/shop/product/group/page` | 否 | `groupId,key,page,pageSize`；`groupId` 对应商城分类 ID。 | 分类商品分页。 |
| GET | `/shop/product/ios/page` | 否 | `key,page,pageSize`。 | 兼容旧接口的商品分页。 |
| GET | `/shop/product/coupon/page` | 否 | `page,pageSize`。 | 首期未启用优惠券，返回空分页。 |
| GET | `/shop/product/report/list` | 是 | 无。 | 首期返回空数组。 |
| GET | `/shop/product/info` | 否 | `id`。 | 商品详情、规格、图片和详情正文。 |
| GET | `/shop/group/info` | 否 | `id`，商城分类 ID。 | `{id,name}`。 |

金额字段单位为元，保留两位小数；库存字段为 `quantity`。商品详情中的 `specs` 为可选规格列表，`resources` 为图片地址数组。

<a id="shop-cart-api"></a>

### 购物车

| 方法 | 路径 | 输入 |
| --- | --- | --- |
| GET | `/shop/cart/count` | 无。 |
| GET | `/shop/cart/list` | 无。 |
| POST | `/shop/cart/add` | `{"productId":1001,"productSpecId":2001,"num":1}` |
| POST | `/shop/cart/modify` | `{"id":1,"productId":1001,"productSpecId":2001,"num":2}` |
| POST | `/shop/cart/delete` | `{"ids":[1,2]}` |

所有购物车操作按当前 Token 对应的商城用户隔离，不能读取或修改其他用户的数据。

<a id="shop-consignee-api"></a>

### 地址簿

| 方法 | 路径 | 输入 |
| --- | --- | --- |
| GET | `/user/consignee/list` | 无。 |
| GET | `/user/consignee/info` | Query：`id`。 |
| POST | `/user/consignee/add` | 地址对象；返回新增地址 ID。 |
| POST | `/user/consignee/modify` | 含 `id` 的地址对象。 |
| POST | `/user/consignee/delete` | `{"id":1}` |

地址对象示例：

```json
{
  "id": 1,
  "province": {"id": 310000, "name": "上海市"},
  "city": {"id": 310100, "name": "上海市"},
  "region": {"id": 310115, "name": "浦东新区"},
  "name": "张三",
  "mobile": "13800138000",
  "address": "世纪大道 100 号",
  "isDefault": 1
}
```

每个商城用户最多一个默认地址。查询、修改和删除均校验地址归属；删除默认地址后，系统会把最近创建的剩余地址设为默认地址。下单后地址复制到订单快照，后续修改地址簿不会改变历史订单。

以下地址接口由 `shop-web-spring-boot-starter` 的 `ShopConsigneeController` 提供，全部要求有效 `X-Token`。

<a id="get-userconsigneelist"></a>

### GET /user/consignee/list

#### 功能

查询当前用户的收货地址，默认地址排在最前，其余地址按 ID 倒序排列。

#### 输入

无 Query 或 Body 参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "province": {"id": 310000, "name": "上海市"},
      "city": {"id": 310100, "name": "上海市"},
      "region": {"id": 310115, "name": "浦东新区"},
      "name": "张三",
      "mobile": "13800138000",
      "address": "世纪大道 100 号",
      "isDefault": 1
    }
  ]
}
```

<a id="get-userconsigneeinfo"></a>

### GET /user/consignee/info

#### 功能

读取当前用户的一条收货地址，不允许读取其他用户的地址。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | number | 是 | 收货地址 ID。 |

#### 输出

`data` 为与地址列表元素相同的地址对象。地址不存在或不属于当前用户时返回 `code=-1`、`message=收货地址不存在`。

<a id="post-userconsigneeadd"></a>

### POST /user/consignee/add

#### 功能

新增收货地址并返回地址 ID。第一条地址自动成为默认地址；传 `isDefault=1` 时会取消原默认地址。

#### 输入

请求体使用上方地址对象，新增时不传 `id`。`province`、`city`、`region`、`name`、`mobile` 和 `address` 必填；`mobile` 必须匹配 11 位中国大陆手机号格式。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": 1
}
```

<a id="post-userconsigneemodify"></a>

### POST /user/consignee/modify

#### 功能

修改当前用户的收货地址。传 `isDefault=1` 时将该地址设为唯一默认地址。

#### 输入

请求体使用上方完整地址对象，`id` 必填，其余地址字段校验与新增接口一致。

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

<a id="post-userconsigneedelete"></a>

### POST /user/consignee/delete

#### 功能

删除当前用户的一条收货地址。删除默认地址后，最近创建的剩余地址自动成为默认地址。

#### 输入

```json
{
  "id": 1
}
```

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

<a id="shop-pay-api"></a>

### 结算与支付

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/shop/pay/coupon/list` | 首期返回空数组。 |
| POST | `/shop/pay/order/check` | 检查是否已有相同未支付订单。 |
| POST | `/shop/pay/calculate` | 服务端重新计算商品价格、优惠和应付金额。 |
| POST | `/shop/pay/order/create` | 创建订单并按 `payType` 创建外部支付单。 |
| POST | `/shop/pay/unified/order/create` | 创建统一订单，不立即创建外部支付单。 |
| POST | `/shop/pay/unified/order/out` | 对统一订单创建微信或支付宝支付单。 |
| GET | `/shop/pay/order/result` | Query：`orderNo`，查询本人订单支付结果。 |
| GET | `/shop/pay/order/tooltip` | Query：`id`，读取本人订单支付提示。 |

下单请求沿用旧 `PayInfoBean` 字段。新版前端必须传唯一 `clientOrderNo`；旧请求不传时仍可解析。使用地址簿时传 `consigneeId`，服务端读取当前用户地址并生成订单地址快照。`items` 只接受商品 ID、规格 ID、数量及既有业务对象关联字段，客户端金额会被重新计算。

```json
{
  "clientOrderNo": "live-20260928-000001",
  "payType": 2,
  "consigneeId": 1,
  "items": [
    {
      "num": 1,
      "product": {"id": 1001},
      "productSpec": {"id": 2001}
    }
  ],
  "note": "请尽快发货"
}
```

`payType`：`2` 微信 APP、`3` 支付宝 APP、`5` 微信公众号、`6` 支付宝网页。零元订单直接进入与支付回调相同的支付成功处理链路。库存不足、优惠券或积分未开放、地址不属于当前用户等情况返回 `code=-1`。

<a id="shop-user-order-api"></a>

### 用户订单

| 方法 | 路径 | 输入 |
| --- | --- | --- |
| GET | `/user/shop/order/page` | `status,key,page,pageSize`；状态 `1` 待付款、`2` 待发货、`3` 待收货。 |
| GET | `/user/shop/order/info` | `id` 或 `orderNo`。 |
| GET | `/user/shop/order/express` | Query：`id`；返回本人订单的发货单、物流内容和对应商品。 |
| POST | `/user/shop/order/modify/note` | `{"id":1,"note":"备注"}` |
| POST | `/user/shop/order/modify/consignee` | `{"id":1,"consignee":地址对象}`；未发货前修改订单地址快照。 |
| POST | `/user/shop/order/modify/batch/consignee` | `{"consignees":[含 orderId 的地址对象]}`。 |
| POST | `/user/shop/order/cancel` | `{"id":1}`；仅未支付订单可取消并恢复库存。 |
| POST | `/user/shop/order/item/sure` | `{"itemId":1}` |
| POST | `/user/shop/order/delete` | `{"id":1}`；逻辑删除，仅对当前用户隐藏。 |

订单详情包含 `consignee` 地址快照、`source` 直播来源和 `items` 商品快照。全部接口校验订单属于当前 `xhlive` 用户。

以下订单接口由 `shop-web-spring-boot-starter` 的 `ShopUserOrderController` 提供，全部要求有效 `X-Token`。

<a id="get-usershoporderpage"></a>

### GET /user/shop/order/page

#### 功能

分页查询当前用户的商城订单，按订单 ID 倒序排列。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `status` | number | 否 | `1` 待付款、`2` 待发货、`3` 待收货；不传表示全部。 |
| `key` | string | 否 | 按订单号模糊查询。 |
| `page` | number | 否 | 页码，默认 `1`。 |
| `pageSize` | number | 否 | 每页数量，默认 `20`，最大 `100`。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 101,
        "orderNo": "XHLV202609290001",
        "clientOrderNo": "app-20260929-0001",
        "payType": 2,
        "payStatus": 1,
        "deliverStatus": 0,
        "refundStatus": 0,
        "totalMoney": 99.00,
        "payMoney": 99.00,
        "payPoint": 0,
        "note": "请尽快发货",
        "createTime": "2026-09-29 10:00:00",
        "payTime": "2026-09-29 10:01:00",
        "consignee": {
          "id": 201,
          "province": {"id": 310000, "name": "上海市"},
          "city": {"id": 310100, "name": "上海市"},
          "region": {"id": 310115, "name": "浦东新区"},
          "name": "张三",
          "mobile": "13800138000",
          "address": "世纪大道 100 号"
        },
        "source": {
          "sourceType": "LIVE_ROOM",
          "liveId": 3001,
          "channelId": "channel-a",
          "inviteCode": "invite-001",
          "source": "discover"
        },
        "items": [
          {
            "id": 301,
            "productId": 1001,
            "productSpecId": 2001,
            "productName": "示例商品",
            "productNum": 1,
            "totalMoney": 99.00,
            "payMoney": 99.00,
            "payStatus": 1,
            "deliverStatus": 0,
            "refundStatus": 0,
            "needExpress": true,
            "info": "规格快照"
          }
        ]
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.list[].id` | number | 订单 ID。 |
| `data.list[].orderNo` | string | 服务端订单号。 |
| `data.list[].clientOrderNo` | string | 客户端幂等订单号，可缺省。 |
| `data.list[].payType` | number | 支付方式。 |
| `data.list[].payStatus` | number | 支付状态。 |
| `data.list[].deliverStatus` | number | 发货状态。 |
| `data.list[].refundStatus` | number | 退款状态。 |
| `data.list[].totalMoney` | number | 订单原金额，单位元。 |
| `data.list[].payMoney` | number | 实付金额，单位元。 |
| `data.list[].payPoint` | number | 使用积分；首期为 `0`。 |
| `data.list[].note` | string | 用户备注，可缺省。 |
| `data.list[].createTime` | string | 创建时间。 |
| `data.list[].payTime` | string | 支付时间，未支付时缺省。 |
| `data.list[].consignee` | object | 下单时的地址快照，不需要物流时可缺省。 |
| `data.list[].source` | object | 直播间、渠道和邀请码来源，可缺省。 |
| `data.list[].items` | array | 商品快照列表。 |

<a id="get-usershoporderinfo"></a>

### GET /user/shop/order/info

#### 功能

按订单 ID 或订单号读取当前用户的订单详情，返回结构与订单分页中的单条订单一致。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | number | 条件必填 | 订单 ID；与 `orderNo` 至少传一个。 |
| `orderNo` | string | 条件必填 | 订单号；与 `id` 至少传一个。当前代码未显式校验两者同时缺省，调用方不得均省略。 |

#### 输出

`data` 为订单分页 `data.list[]` 的完整订单对象。订单不存在或不属于当前用户时返回 `code=-1`、`message=订单不存在`。

<a id="get-usershoporderexpress"></a>

### GET /user/shop/order/express

#### 功能

查询当前用户订单的发货单、物流内容及每张发货单包含的商品。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | number | 是 | 订单 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 401,
      "noticeSn": "DN202609290001",
      "express": "SF1234567890",
      "expressName": "顺丰速运",
      "content": {},
      "createTime": "2026-09-29 12:00:00",
      "items": []
    }
  ]
}
```

<a id="post-usershopordermodifynote"></a>

### POST /user/shop/order/modify/note

#### 功能

修改当前用户订单备注。

#### 输入

```json
{
  "id": 101,
  "note": "工作日送货"
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。

<a id="post-usershopordermodifyconsignee"></a>

### POST /user/shop/order/modify/consignee

#### 功能

修改一张尚未发货且需要物流的订单地址快照，不会修改用户地址簿。

#### 输入

```json
{
  "id": 101,
  "consignee": {
    "province": {"id": 310000, "name": "上海市"},
    "city": {"id": 310100, "name": "上海市"},
    "region": {"id": 310115, "name": "浦东新区"},
    "name": "张三",
    "mobile": "13800138000",
    "address": "世纪大道 100 号"
  }
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。订单不需要地址时返回“订单不需要收货地址”，已有商品发货时返回“订单已有商品发货”。

<a id="post-usershopordermodifybatchconsignee"></a>

### POST /user/shop/order/modify/batch/consignee

#### 功能

批量修改多张订单的地址快照，每条地址通过 `orderId` 指定订单。

#### 输入

```json
{
  "consignees": [
    {
      "orderId": 101,
      "province": {"id": 310000, "name": "上海市"},
      "city": {"id": 310100, "name": "上海市"},
      "region": {"id": 310115, "name": "浦东新区"},
      "name": "张三",
      "mobile": "13800138000",
      "address": "世纪大道 100 号"
    }
  ]
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。

<a id="post-usershopordercancel"></a>

### POST /user/shop/order/cancel

#### 功能

取消当前用户的未支付订单，并由商城订单服务恢复对应库存。

#### 输入

```json
{
  "id": 101
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。

<a id="post-usershoporderitemsure"></a>

### POST /user/shop/order/item/sure

#### 功能

确认本人订单中的一个待收货商品，并重新计算订单状态。

#### 输入

```json
{
  "itemId": 301
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。商品不存在或当前状态不可确认收货时返回 `code=-1`。

<a id="post-usershoporderdelete"></a>

### POST /user/shop/order/delete

#### 功能

将当前用户订单逻辑删除；删除后不再出现在用户订单列表中。

#### 输入

```json
{
  "id": 101
}
```

#### 输出

成功返回 `{"code":0,"message":"成功"}`。

<a id="get-stat-shopproductsee"></a>

### GET /stat/shop/product/see

Query 参数 `id` 为商品 ID。Token 可选；登录用户会记录唯一浏览关系，匿名调用直接成功。

<a id="shop-payment-callback-api"></a>

### 支付回调

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/callback/wx/payNotify` | 微信 XML 回调。 |
| POST | `/callback/ali/payNotify` | 支付宝表单回调。 |

回调不需要 Token，只由 web-api 暴露。服务端校验签名、应用/商户、外部支付单号、金额和第三方交易号；重复成功回调不会重复更新订单或发放权益。

## manage-api 接口

商城管理接口由 `shop-manage-spring-boot-starter` 提供，通过本地 Service 访问同一 MySQL 实例中的 `xhgx_shop`，不使用 Hessian、HTTP 或 RabbitMQ。所有管理接口统一挂在 `/manage` 下并使用 Manager Token；例如商品分页为 `GET /manage/shop/product/page`，订单分页为 `GET /manage/shop/order/page`，统计首页为 `GET /manage/statistic/index`。无效 Token 返回 `code=-999`。

商品、订单、发货、退款、导出和统计的相对路径、HTTP 方法及字段保持不变。订单分页追加可选 Query 参数 `liveId`、`channelId`；订单导出请求体也接受同名可选字段。订单详情与列表返回 `clientOrderNo`、`sourceType`、`liveId`、`channelId`、`inviteCode`、`source`。

后台可创建礼品、实物、知识、服务和组合商品。知识及服务商品的关联资源固定使用 `sysCode=xhlive`；`GET /manage/common/out/res/list` 只查询本地 `shop_object` 快照。课程模块尚未启用，`POST /manage/user_course/retry` 返回 `code=-1` 和“课程模块尚未启用”。知识及服务商品支付后暂时沿用自动完成状态，但不会创建课程或其他权益数据。

商城正式配置为 `xhzy.shop.manage.enabled`、`xhzy.shop.schema`、`xhzy.shop.public-base-url` 和 `xhzy.shop.manage.temp-dir`。直播服务配置 `xhzy.shop.schema=xhgx_shop` 以启用动态表名；独立商城后台直接连接商城库，不配置 schema 改写。支付公开地址只在实际发起支付时校验，后台启动不依赖该地址。临时文件只能写入独立的商城临时目录。

统计首页 `GET /statistic/index` 追加可选 Query 参数 `liveId`、`channelId`。任一来源条件存在时，销售额、退款额、订单数、支付用户数和待发货数按 `shop_order_source` 过滤；不传时保持原统计口径。

<a id="manage-shop-api"></a>

## 商城管理接口

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `XHZY_Live_Shop_Service/shop-manage-spring-boot-starter/src/main/java/com/xhgxshop/manage/controller/` |
| 商品 Controller | `.../controller/shop/` |
| 请求/响应 VO | `.../manage/vo/`、`common-entity` 和 `common-service` |

#### 通用规则

下列接口均已由当前 `manage-api` 集成，完整路径以 `/manage` 开头，必须携带有效的 `X-Token`。除文件下载外，成功响应使用统一结构：

```json
{
  "code": 0,
  "message": "成功",
  "data": null
}
```

分页接口的 `data` 为 `{list,total,current,size}`。表格中的 `JSON` 表示请求体使用 `Content-Type: application/json`；`Query` 参数拼接在 URL。金额输入和输出单位均为元，使用十进制 number；数据库内部以分保存。

<a id="manage-shop-product-api"></a>

### 商城商品管理

#### 商品

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/shop/product/list` | Query：重复传入 `ids[]`，例如 `ids[]=4&ids[]=9` | 按 ID 批量返回商品列表，用于微页面商品回显 |
| GET | `/manage/shop/product/page` | Query：`type,status,key,excludeLabelId,needSpec=false,page,pageSize`，均可选 | 商品分页 |
| GET | `/manage/shop/product/info` | Query：`id` | 商品详情 |
| POST | `/manage/shop/product/add` | JSON：`ShopProductVo` | `null` |
| POST | `/manage/shop/product/modify` | JSON：`ShopProductVo`，必须包含 `id` | `null` |
| POST | `/manage/shop/product/copy` | JSON：`{id}` | `null` |
| POST | `/manage/shop/product/delete` | JSON：`{id}` | `null` |
| POST | `/manage/shop/product/modify/status` | JSON：`{id,status}` | `null` |
| POST | `/manage/shop/product/modify/label` | JSON：`{id,labelType,labels}` | `null` |

`ShopProductVo` 的核心字段如下。`type` 支持礼品、实物、知识、服务和组合商品；知识及服务商品的 `relativeItem.sysCode` 由服务端按 `xhlive` 处理。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 修改时必填，新增时不传。 |
| `type` | number | 商品类型。 |
| `specType` | number | 规格模式。 |
| `barcode` | string | 商品编码。 |
| `name`、`subName` | string | 商品名称和副标题。 |
| `picUrl` | string | 商品主图 URL。 |
| `supplier` | string | 供应商。 |
| `minPrice`、`maxPrice`、`originalPrice` | number | 售价区间及原价，单位元。 |
| `description`、`tooltip` | string | 商品详情和提示。 |
| `status` | number | 商品状态。 |
| `relativeItem` | object | 关联对象 `{sysCode,id,type,name}`；仅知识/服务商品使用。 |
| `cate` | object[] | 分类摘要数组。 |
| `attrs`、`specs` | object[] | 规格属性与规格明细。 |
| `video`、`resources` | object/object[] | 视频与图片资源。 |
| `labels` | object[] | 商品标签。 |

#### 批量商品查询

微页面编辑时使用 `GET /manage/shop/product/list` 一次回显多个商品。参数名与旧后台一致，为可重复传入的 `ids[]`：

```http
GET /manage/shop/product/list?ids%5B%5D=4&ids%5B%5D=9&ids%5B%5D=8&ids%5B%5D=10
X-Token: <manager-token>
```

接口同时兼容原样的 `ids[]` 和 URL 编码后的 `ids%5B%5D`。未传 `ids[]` 时返回空数组。返回顺序由数据库查询决定，不保证与请求 ID 的顺序一致。

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 4,
      "type": 1,
      "specType": 1,
      "barcode": "P0004",
      "name": "示例商品",
      "subName": "商品副标题",
      "picUrl": "https://example.com/product.png",
      "supplier": "示例供应商",
      "minPrice": 99.00,
      "maxPrice": 99.00,
      "originalPrice": 129.00,
      "saleNum": 0,
      "status": 1,
      "updateTime": "2026-09-29 14:00:00",
      "cate": [],
      "labels": []
    }
  ]
}
```

批量接口返回商品基础字段、分类、关联对象和标签，不返回详情正文、图片资源及规格明细；值为 `null` 的字段按全局 JSON 配置省略。

#### 商品删除

删除接口固定为 `POST /manage/shop/product/delete`，JSON 请求体为 `{ "id": 商品ID }`。直播后台 dev 完整地址为 `https://test.zhinan.run/xhzy-live/manage/shop/product/delete`。只有当前端 `baseURL` 已经包含 `/manage` 时，调用代码才可以写成相对路径 `shop/product/delete`。删除为状态删除，并同步清理商品分类关联；成功返回 `code=0`。

#### 分类

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/shop/cate/list` | 无 | 分类树 `ShopCateVo[]` |
| GET | `/manage/shop/cate/info` | Query：`id` | 分类详情 |
| POST | `/manage/shop/cate/add` | JSON：`{name,level,sortNo,pid,spec}` | `null` |
| POST | `/manage/shop/cate/modify` | JSON：`{id,name,level,sortNo,pid,spec}` | `null` |
| POST | `/manage/shop/cate/modify/config` | JSON：`{id,spec}` | `null` |
| POST | `/manage/shop/cate/delete` | JSON：`{id}` | `null` |

#### 标签与标签商品

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/shop/label/page` | Query：`key,type,page,pageSize` | 标签分页 |
| GET | `/manage/shop/label/info` | Query：`id` | 标签详情 |
| POST | `/manage/shop/label/add` | JSON：`{type,name,themeColor,bgColor,borderColor}` | 新增后的标签 |
| POST | `/manage/shop/label/modify` | JSON：同新增并包含 `id` | 修改后的标签 |
| POST | `/manage/shop/label/delete` | JSON：`{id}` | `null` |
| GET | `/manage/shop/label/product/page` | Query：`labelId,status,key,page,pageSize` | 标签下商品分页 |
| POST | `/manage/shop/label/product/add` | JSON：`{labelId,ids}` | `null` |
| POST | `/manage/shop/label/product/delete` | JSON：`{labelId,id}` | `null` |
| POST | `/manage/shop/label/clear` | JSON：`{labelId}` | `null` |

<a id="manage-shop-order-api"></a>

### 商城订单管理

#### 订单查询与维护

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/shop/order/page` | Query：`status,searchType,key,startTime,endTime,minMoney,maxMoney,sysCode,productName,productType,couponStatus,pointStatus,type,orderStatus,refundStatus,mchId,liveId,channelId,page,pageSize` | 订单分页 |
| GET | `/manage/shop/order/info` | Query：`id` 或 `orderNo` | 订单详情 |
| POST | `/manage/shop/order/add` | JSON：`{userId,data}`，`data` 为结算下单对象 | `null` |
| POST | `/manage/shop/order/modify/remark` | JSON：`{id,remark}` | `null` |
| POST | `/manage/shop/order/modify/consignee` | JSON：`{id,consignee}` | `null` |
| POST | `/manage/shop/order/modify/price` | JSON：`{id,price}` | `null` |
| POST | `/manage/shop/order/delay` | JSON 数组：`[{id,delayTime}]` | `null` |
| POST | `/manage/shop/order/refund` | JSON：`RefundReqVo` | `null` |
| GET | `/manage/shop/order/refund/list` | Query：`id` | 订单退款记录数组 |
| GET | `/manage/shop/order/item/refund_info` | Query：`itemId` | 单个订单项退款信息 |
| GET | `/manage/shop/order/item/refund_info/list` | Query：重复传入 `itemIds[]` | 订单项退款信息数组 |
| POST | `/manage/shop/order/export` | Query：`sysCode`；JSON：订单筛选条件 | `null`，异步创建导出任务 |

`RefundReqVo` 字段为 `id,refundMoney,refundPoint,refundCouponIds,returnDataList,close,closeAll,reason`。订单分页、详情和导出结果包含直播来源字段 `clientOrderNo,sourceType,liveId,channelId,inviteCode,source`；`liveId` 和 `channelId` 可用于筛选直播订单。

#### 发货与物流

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/shop/order/express/list` | Query：`id`，订单 ID | 订单物流单数组 |
| GET | `/manage/shop/order/package/list` | Query：`id`，订单 ID | 订单包裹数组 |
| GET | `/manage/shop/order/express/info` | Query：`id,deliveryNoticeId` | `null`；触发物流信息刷新 |
| POST | `/manage/shop/order/modify/express` | JSON：`{id,expresses}` | `null` |
| POST | `/manage/shop/order/deliver` | JSON：`{id,itemIds,productSpecId,productNum,expressName,noticeSn}` | `null` |
| GET | `/manage/shop/order/deliver/page` | Query：`searchType,key,type,productName,startTime,endTime,page,pageSize` | 待发货订单分页 |
| POST | `/manage/shop/order/deliver/export` | JSON：待发货筛选条件 | `null`，异步创建导出任务 |
| POST | `/manage/shop/order/deliver/import` | JSON：`{fileUrl}` | `null`，异步创建回导任务 |
| POST | `/manage/shop/order/gift/import` | Query：`sysCode`；JSON：`{fileUrl}` | `null`，异步创建赠品导入任务 |

<a id="manage-shop-statistic-api"></a>

### 商城交易与统计

#### 常用选项

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/common/user/list` | Query：`sysCode,key` | 商城用户摘要数组 |
| GET | `/manage/common/shop/cate/list` | 无 | 可选商品分类数组 |
| GET | `/manage/common/shop/label/list` | Query：`type,key` | 可选标签数组 |
| GET | `/manage/common/out/res/list` | Query：`sysCode,type,key` | 本地 `shop_object` 资源快照数组；直播系统使用 `xhlive` |
| GET | `/manage/common/shop/product/list` | Query：`type,key` | 可选商品数组 |
| GET | `/manage/common/trade_account/list` | 无 | 支付账户数组 |
| GET | `/manage/common/express_company/list` | 无 | 快递公司数组 |

#### 统计

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/statistic/index` | Query：`startDate,endDate,liveId,channelId` | 销售额、退款额、订单数、支付用户数、待发货数 |
| GET | `/manage/statistic/product/data` | Query：`startDate,endDate`（必填，`yyyy-MM-dd`） | 商品销售图表数据 |
| GET | `/manage/statistic/product/page` | Query：`startDate,endDate,sortKey,sortType,page,pageSize` | 商品销售统计分页 |

日期参数 `startDate/endDate` 格式为 `yyyy-MM-dd`；订单、账单中的 `startTime/endTime` 格式为 `yyyy-MM-dd HH:mm:ss`。

#### 交易账户与账单

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/trade_account/list` | Query：`payType` | 交易账户数组 |
| GET | `/manage/trade_account/info` | Query：`id` | 交易账户详情 |
| POST | `/manage/trade_account/modify/status` | JSON：`{id,status}` | `null` |
| POST | `/manage/trade_account/modify` | JSON：`{id,name,companyName,mchId,payType,type,status,areas}` | `null` |
| GET | `/manage/shop/trade_record/page` | Query：`type,key,startTime,endTime,page,pageSize` | 交易账单分页 |
| POST | `/manage/shop/trade_record/export` | JSON：账单筛选条件 | `null`，异步创建导出任务 |

<a id="manage-shop-task-api"></a>

### 商城任务与购课记录

| 方法 | 路径 | 输入 | 响应 `data` |
| --- | --- | --- | --- |
| GET | `/manage/task/export/page` | Query：`sysCode,type,page,pageSize` | 导出任务分页 |
| GET | `/manage/task/import/page` | Query：`sysCode,type,page,pageSize` | 导入任务分页 |
| GET | `/manage/task/import/download` | Query：`id` | `.xlsx` 导入结果文件，不使用 JSON 包装 |
| GET | `/manage/user_course/page` | Query：`key,productId,status,synStatus,page,pageSize` | 历史购课记录分页 |
| GET | `/manage/user_course/export` | Query：`key,productId,status,synStatus` | `.xlsx` 购课记录文件，不使用 JSON 包装 |
| POST | `/manage/user_course/retry` | JSON：`{id}` | 当前固定返回 `code=-1,message=课程模块尚未启用` |

`user_course` 仅保留历史查询和导出入口。本期不会写入新的课程权益，也不会通过 Hessian、HTTP 或消息队列向旧系统补发。

## 后台认证与会话

<a id="post-manage-login"></a>

### POST /manage/login

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/LoginController.java` |
| 方法 | `LoginController.login` |

#### 功能

管理员登录；无需 Token。成功后将响应 `data` 字符串保存为 Token。

#### 输入

```json
{
  "passport": "admin",
  "password": "登录密码"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| passport | string | 是 | 后台管理员登录账号，不能为空。 |
| password | string | 是 | 后台管理员登录密码，不能为空。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": "登录Token"
}
```

<a id="get-manage-login_info"></a>

### GET /manage/login_info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/LoginController.java` |
| 方法 | `LoginController.loginInfo` |

#### 功能

读取当前管理员资料及其角色权限。需有效 Token。

#### 输入

无请求参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 1,
    "name": "管理员",
    "passport": "admin",
    "imageUrl": "https://cos.example.com/xhzy-live/avatar/example.jpg",
    "role": {
      "id": 1,
      "name": "超级管理员",
      "description": "内置全权限角色",
      "permission": [null, "*"],
      "userNum": null,
      "updateTime": "2026-09-22 10:00:00"
    }
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.id | number | 当前管理员 ID。 |
| data.name | string | 当前管理员名称。 |
| data.passport | string | 登录账号。 |
| data.imageUrl | string | 当前管理员头像 URL；历史账号未设置时缺省。 |
| data.role | `Role` | 当前角色完整信息。 |
| data.role.id | number | 当前角色 ID。 |
| data.role.name | string | 当前角色名称。 |
| data.role.description | string | 角色描述，可缺省。 |
| data.role.permission | JSON | 与旧后台一致的原始权限配置，通常是权限标识字符串数组。 |
| data.role.userNum | number | 登录信息中固定为 `null`。 |
| data.role.updateTime | string | 角色最后更新时间。 |

<a id="post-manage-modify_pwd"></a>

### POST /manage/modify_pwd

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/LoginController.java` |
| 方法 | `LoginController.modifyPassword` |

#### 功能

修改当前管理员密码。需有效 Token。

#### 输入

```json
{
  "oldPwd": "原密码",
  "newPwd": "6-20位新密码"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| oldPwd | string | 是 | 原登录密码。 |
| newPwd | string | 是 | 新密码，长度为 6-20 位字符。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口无业务返回数据；`data` 为 `null` 时省略。

<a id="post-manage-logout"></a>

### POST /manage/logout

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/LoginController.java` |
| 方法 | `LoginController.logout` |

#### 功能

撤销当前 `X-Token`。需有效 Token。

#### 输入

无需请求体。

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口无业务返回数据；`data` 为 `null` 时省略。

## 后台账号管理

接口需有效 Token。`Manager` 字段：`id`、`name`、`passport`、`imageUrl`、`roleId`、`role:{id,name}`、`loginTime`；写入时还可传 `password`，查询不返回密码。前端可依据当前角色的 `permission` 控制入口显示。

<a id="get-manage-commoncossign"></a>

### GET /manage/common/cos/sign

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/.../controller/CommonController.java` |
| Service | `ZhiNan_Common_Manage/.../service/CosService.java` |
| Response VO | `ZhiNan_Common_Manage/.../vo/CosSignVo.java` |

#### 功能

获取腾讯云 COS 请求签名。需有效 Token，契约与星鹤国学旧后台的 `cos/sign` 一致，签名有效期为 3 小时。管理端和 APP/H5 前台共用同一组 `TENCENT_COS_*` 配置。管理员头像的对象键由前端生成为 `/xhzy-live/avatar/<唯一文件名>`，不增加日期目录。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 是 | COS 对象键，必须以 `/` 开头，例如 `/xhzy-live/avatar/0123456789abcdef.png`；按请求值原样参与签名。 |
| method | string | 是 | 待签名的 HTTP 方法；不区分大小写，上传时传 `PUT`。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "sign": "q-sign-algorithm=sha1&...",
    "domain": "https://xhzy-live-1320544726.cos.ap-shanghai.myqcloud.com",
    "region": "ap-shanghai",
    "bucket": "xhzy-live-1320544726"
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.sign | string | 放入 COS 上传请求 `Authorization` 头的签名。 |
| data.domain | string | COS 访问域名。 |
| data.region | string | COS 地域。 |
| data.bucket | string | COS 存储桶名称。 |

前端对 `domain + key` 发起 `PUT` 请求，并设置 `Authorization: <data.sign>`。`domain` 是腾讯原生桶域名，不能替换为只支持读取的 CDN 或自定义加速域名。上传成功后，同一个 URL 即为提交管理员新增或编辑接口的 `imageUrl`。浏览器直传前还需在 COS 存储桶配置允许管理端来源的 CORS 规则。

兼容约定：`key` 与旧星鹤国学接口一致，以 `/` 开头并按前端传入值原样参与签名；`method` 兼容大小写；参数或签名错误统一返回 `code=-1` 和对应业务提示。Token 仅从 `X-Token` 请求头读取。

<a id="get-manage-managerpage"></a>

### GET /manage/manager/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/ManagerController.java` |
| 方法 | `ManagerController.page` |

#### 功能

分页查询管理员账号。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 否 | 账号搜索关键字。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 2,
        "name": "运营",
        "passport": "operator",
        "imageUrl": "https://cos.example.com/xhzy-live/avatar/example.jpg",
        "roleId": 2,
        "role": {
          "id": 2,
          "name": "运营角色"
        },
        "loginTime": "2026-09-22 10:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.list | `Manager[]` | 当前页管理员数组；空页为 `[]`。 |
| data.list[].id | number | 管理员 ID。 |
| data.list[].name | string | 管理员名称。 |
| data.list[].passport | string | 登录账号。 |
| data.list[].imageUrl | string | 管理员头像 URL；历史账号未设置时可能缺省。 |
| data.list[].roleId | number | 角色 ID。 |
| data.list[].role | object | `{id:number,name:string}`，角色摘要。 |
| data.list[].loginTime | string | 最近登录时间，可能缺省。 |
| data.total | number | 符合条件的总数。 |
| data.current | number | 当前页码。 |
| data.size | number | 每页数量。 |

密码字段不返回。

<a id="get-manage-managerinfo"></a>

### GET /manage/manager/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/ManagerController.java` |
| 方法 | `ManagerController.info` |

#### 功能

查询单个管理员账号。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 管理员 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 2,
    "name": "运营",
    "passport": "operator",
    "imageUrl": "https://cos.example.com/xhzy-live/avatar/example.jpg",
    "roleId": 2,
    "role": {
      "id": 2,
      "name": "运营角色"
    },
    "loginTime": "2026-09-22 10:00:00"
  }
}
```

`data` 为单个 `Manager`，字段及类型同账号分页的 `data.list[]`；`loginTime` 为空时缺省，`password` 不返回。

<a id="post-manage-manageradd"></a>

### POST /manage/manager/add

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/ManagerController.java` |
| 方法 | `ManagerController.add` |

#### 功能

新增管理员账号。

#### 输入

```json
{
  "name": "运营",
  "passport": "operator",
  "imageUrl": "https://cos.example.com/xhzy-live/avatar/example.jpg",
  "password": "6-20位密码",
  "roleId": 2
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 管理员名称，不能为空。 |
| passport | string | 是 | 登录账号，不能为空。 |
| imageUrl | string | 否 | 头像地址；使用 `data.domain + key`。省略时由前端显示默认头像。 |
| password | string | 是 | 初始密码，长度为 6-20 位字符。 |
| roleId | number | 是 | 已存在的角色 ID。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。接口不返回新账号 ID，需重新查询列表。

<a id="post-manage-managermodify"></a>

### POST /manage/manager/modify

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/ManagerController.java` |
| 方法 | `ManagerController.modify` |

#### 功能

修改管理员账号；传新密码时会撤销该账号原有 Token。

#### 输入

```json
{
  "id": 2,
  "name": "运营",
  "passport": "operator",
  "imageUrl": "https://cos.example.com/xhzy-live/avatar/example.jpg",
  "roleId": 2
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 待修改的管理员 ID。 |
| name | string | 是 | 管理员名称。 |
| passport | string | 是 | 登录账号。 |
| imageUrl | string | 否 | 新头像地址；省略时保留原头像。 |
| roleId | number | 是 | 已存在的角色 ID。 |
| password | string | 否 | 传入时更新密码，长度为 6-20 位字符，并撤销该账号的现有 Token；省略时不修改密码。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

<a id="post-manage-managerdelete"></a>

### POST /manage/manager/delete

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/ManagerController.java` |
| 方法 | `ManagerController.delete` |

#### 功能

软删除管理员账号；不能删除当前登录账号。

#### 输入

```json
{
  "id": 2
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 待删除的管理员 ID。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

## 后台角色管理

角色权限契约与星鹤国学旧后台一致。`Role` 字段为 `id`、`name`、`description`、`permission`、`userNum`、`updateTime`；其中 `permission` 是由前端解释的任意 JSON，通常使用权限标识字符串数组。后端只校验 Token 和管理员状态，不按这些标识拦截接口。

<a id="get-manage-rolepage"></a>

### GET /manage/role/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.page` |

#### 功能

分页查询角色。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 否 | 角色名称搜索关键字。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 2,
        "name": "运营角色",
        "description": "直播运营",
        "permission": null,
        "userNum": 3,
        "updateTime": "2026-09-22 10:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.list | `Role[]` | 当前页角色数组。 |
| data.list[].id | number | 角色 ID。 |
| data.list[].name | string | 角色名称。 |
| data.list[].description | string | 角色描述，可缺省。 |
| data.list[].permission | null | 分页接口不加载权限配置，固定为 `null`。 |
| data.list[].userNum | number | 关联管理员数量。 |
| data.list[].updateTime | string | 最后更新时间，可缺省。 |
| data.total | number | 总数。 |
| data.current | number | 当前页码。 |
| data.size | number | 每页数量。 |

<a id="get-manage-rolelist"></a>

### GET /manage/role/list

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.list` |

#### 功能

查询全部可用角色。

#### 输入

无请求参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 2,
      "name": "运营角色",
      "description": null,
      "permission": null,
      "userNum": null,
      "updateTime": null
    }
  ]
}
```

`data` 为角色摘要数组。每项只有 `id`、`name` 有值，其余 `Role` 字段为 `null`；无角色时为 `[]`。

<a id="get-manage-roleinfo"></a>

### GET /manage/role/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.info` |

#### 功能

查询角色详情与前端权限配置。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 角色 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 2,
    "name": "运营角色",
    "description": "直播运营",
    "permission": [
      null,
      "member_index_show",
      "member_index_export"
    ],
    "userNum": null,
    "updateTime": "2026-09-22 10:00:00"
  }
}
```

`data` 为单个 `Role`。`permission` 是数据库中 `role_permission.permission` 解析后的原始 JSON；详情接口中的 `userNum` 为 `null`，与旧后台保持一致。

<a id="post-manage-roleadd"></a>

### POST /manage/role/add

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.add` |

#### 功能

新增角色。

#### 输入

```json
{
  "name": "运营",
  "description": "直播运营",
  "permission": [null, "member_index_show", "member_index_export"]
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 角色名称。 |
| description | string | 否 | 角色描述。 |
| permission | JSON | 否 | 前端权限配置，原样保存；通常传权限标识字符串数组，也可传空数组 `[]`。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。接口不返回新角色 ID。

<a id="post-manage-rolemodify"></a>

### POST /manage/role/modify

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.modify` |

#### 功能

修改角色及前端权限配置。

#### 输入

```json
{
  "id": 2,
  "name": "运营",
  "description": "直播运营",
  "permission": [null, "member_index_show", "member_index_export"]
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 待修改的角色 ID。 |
| name | string | 是 | 角色名称。 |
| description | string | 否 | 角色描述。 |
| permission | JSON | 否 | 修改后的完整前端权限配置，原样覆盖。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

<a id="post-manage-roledelete"></a>

### POST /manage/role/delete

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/RoleController.java` |
| 方法 | `RoleController.delete` |

#### 功能

软删除角色。内置超级管理员角色或仍有关联账号的角色不能删除。

#### 输入

```json
{
  "id": 2
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 待删除的角色 ID。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

<a id="get-manage-commonrolelist"></a>

### GET /manage/common/role/list

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/CommonController.java` |
| 方法 | `CommonController.roleList` |

#### 功能

账号编辑页可选角色列表。需有效 Token。

#### 输入

无请求参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 2,
      "name": "运营角色",
      "description": null,
      "permission": null,
      "userNum": null,
      "updateTime": null
    }
  ]
}
```

`data` 为 `Role[]`；每项字段与 `/manage/role/list` 相同，空列表为 `[]`。

## 后台系统配置

`SysParam` 字段：`id`、`paramKey`、`name`、`content`（任意 JSON 值）、`showStatus`。接口需有效 Token；后端不按前端权限标识拦截。

<a id="get-manage-sys_paramlist"></a>

### GET /manage/sys_param/list

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/SysParamController.java` |
| 方法 | `SysParamController.list` |

#### 功能

查询系统配置列表。

#### 输入

无请求参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "paramKey": "example.key",
      "name": "示例配置",
      "content": {
        "enabled": true
      },
      "showStatus": 1
    }
  ]
}
```

`data` 为 `SysParam[]`，每项含 `id:number`、`paramKey:string`、`name:string`、`content:JSON`、可选 `showStatus:number`；无配置时为 `[]`。此接口只返回可见配置。

<a id="get-manage-sys_paraminfo"></a>

### GET /manage/sys_param/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/SysParamController.java` |
| 方法 | `SysParamController.info` |

#### 功能

按 ID 或配置 Key 查询配置。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 二选一 | 配置 ID。 |
| key | string | 二选一 | 配置键；`id` 与 `key` 至少提供一个。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 1,
    "paramKey": "example.key",
    "name": "示例配置",
    "content": {
      "enabled": true
    },
    "showStatus": 1
  }
}
```

`data` 为单个 `SysParam`；字段同配置列表元素。`content` 不固定为对象，前端应按具体 `paramKey` 解释其 JSON 结构。

<a id="post-manage-sys_parammodify"></a>

### POST /manage/sys_param/modify

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/SysParamController.java` |
| 方法 | `SysParamController.modify` |

#### 功能

新增或修改系统配置；`id` 为空时新增。

#### 输入

```json
{
  "id": 1,
  "paramKey": "example.key",
  "name": "示例配置",
  "content": {
    "enabled": true
  },
  "showStatus": 1
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 否 | 配置 ID；省略时新增。 |
| paramKey | string | 是 | 配置键。 |
| name | string | 是 | 配置名称。 |
| content | JSON | 是 | 配置内容，可为任意 JSON 值。 |
| showStatus | number | 否 | 展示状态。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。新增也不返回配置 ID。

## 后台操作日志

<a id="get-manage-operation_logpage"></a>

### GET /manage/operation_log/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `ZhiNan_Common_Manage/src/main/java/run/zhinan/common/manage/controller/OperationLogController.java` |
| 方法 | `OperationLogController.page` |

#### 功能

分页查询后台操作日志。需有效 Token。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 否 | 按操作人、动作、对象名或对象 ID 搜索。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "time": "2026-09-22 10:00:00",
        "managerId": 1,
        "managerName": "管理员",
        "action": "登录",
        "targetType": "manager",
        "targetId": "1",
        "targetName": "管理员",
        "ip": "127.0.0.1",
        "success": true
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

`data.list` 为 `AuditLog[]`，各字段类型见公共对象表；`total`、`current`、`size` 为 number，空页的 `list` 为 `[]`。

## 后台业务用户

本组接口由 `manage-api` 的 `UserController` 提供。只有 `xhzy.live.user-datasource.enabled=true` 且业务数据库可用时注册；当前 local、dev YAML 均开启。修改手机号和备注直接写业务库。

`User` 字段：`id`、`passport`、`status`、`initStatus`、`studentStatus`、`pushStatus`、`studentCode`、`imageUrl`、`name`、`sex`、`birthday`、`city`、`occupation`、`deviceType`、`appVersion`、`loginTime`、`createTime`、`balancePoint`、`remark`。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | number | 用户 ID。 |
| `passport` | string | 手机号/登录账号，可缺省。 |
| `status` | number | 用户状态；取值沿用业务库。 |
| `initStatus` | number | 初始化状态，可缺省。 |
| `studentStatus` | number | 学员身份状态；`0` 注册用户、`1` 体验学员、`2` 学员，可缺省。 |
| `pushStatus` | number | 推送状态，可缺省。 |
| `studentCode` | string | 学员证号，可缺省。 |
| `imageUrl` | string | 头像 URL，可缺省。 |
| `name` | string | 昵称，可缺省。 |
| `sex` | string | 性别，可缺省。 |
| `birthday` | string | 生日，可缺省。 |
| `city` | string | 城市，可缺省。 |
| `occupation` | string | 职业，可缺省。 |
| `deviceType` | string | 设备类型，可缺省。 |
| `appVersion` | string | 最近一次登录通过 `X-V` 请求头上报的 APP 版本；从未上报时缺省。 |
| `loginTime` | string | 最近登录时间，可缺省。 |
| `createTime` | string | 注册时间，可缺省。 |
| `balancePoint` | number | 当前积分余额，可缺省。 |
| `remark` | string | 当前客服备注，可缺省。 |

<a id="get-manage-userpage"></a>

### GET /manage/user/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.page` |

#### 功能

分页查询用户。需 `member_index_show`。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 否 | 昵称模糊匹配，或手机号/学员证号精确匹配。 |
| sortKey | string | 否 | `id`、`name`、`passport`、`studentCode`、`loginTime`、`createTime`；无有效值时按 ID 降序。 |
| sortType | string | 否 | `asc` 升序；其余值按降序处理。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 10001,
        "passport": "13800000000",
        "status": 1,
        "initStatus": 1,
        "studentStatus": 2,
        "pushStatus": 1,
        "studentCode": "XH10001",
        "imageUrl": "https://example.com/avatar.png",
        "name": "测试用户",
        "sex": "女",
        "birthday": "1990-01-01",
        "city": "北京",
        "occupation": "教师",
        "deviceType": "iOS",
        "appVersion": "1.0.0",
        "loginTime": "2026-09-22 10:00:00",
        "createTime": "2026-09-01 09:00:00",
        "balancePoint": 100,
        "remark": "已联系"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.list | `User[]` | 当前页用户数组；元素字段及类型见本组字段表。 |
| data.total | number | 符合条件的总数。 |
| data.current | number | 当前页码。 |
| data.size | number | 每页数量。 |

可空字段在数据库无值时可能不出现在 JSON 中。

<a id="get-manage-userlogin_recordpage"></a>

### GET /manage/user/login_record/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.loginRecordPage` |

#### 功能

分页查询指定用户的登录记录。需 `member_archive_note_record`。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 用户 ID。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 3,
        "deviceInfo": "iPhone",
        "loginType": "验证码",
        "ip": "127.0.0.1",
        "loginTime": "2026-09-22 10:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

`data.list` 为 `LoginRecord[]`；`id:number`，`deviceInfo:string`、`loginType:string`、`ip:string`、`loginTime:string` 可缺省；分页元数据为 number。

<a id="get-manage-userverify_code"></a>

### GET /manage/user/verify_code

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.verifyCode` |

#### 功能

查看指定用户当前登录验证码，并记录操作日志。需 `member_index_verify_code`。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| userId | number | 是 | 用户 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "code": "123456",
    "expireTime": "2026-09-22 10:10:00"
  }
}
```

`data.code:string` 为验证码；`data.expireTime:string` 为失效时间。没有有效验证码时服务返回 `data=null`，按当前 `non_null` 设置会省略顶层 `data` 字段。

<a id="post-manage-usermodifypassportcheck"></a>

### POST /manage/user/modify/passport/check

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.checkPassport` |

#### 功能

检查手机号是否被其他用户占用。需 `member_index_cellphone`。

#### 输入

```json
{
  "id": 10001,
  "passport": "13800000000"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 当前用户 ID。 |
| passport | string | 是 | 待检查手机号，不能为空。 |
| changeUserId | number | 否 | 本接口忽略该字段。 |

Postman 环境变量 `user_id`、`user_passport` 不能留空，否则请求体可能变成非法 JSON 或触发校验错误。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 10002,
    "passport": "13800000000",
    "status": 1,
    "studentStatus": 2,
    "name": "另一位用户",
    "balancePoint": 0
  }
}
```

有冲突时 `data` 为单个 `User`，字段全集与 `/manage/user/page` 的 `data.list[]` 一致；示例只展示非空字段。无冲突时 `data=null`，可能在 JSON 中省略，前端应把缺省也视为无冲突。

<a id="post-manage-usermodifypassport"></a>

### POST /manage/user/modify/passport

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.modifyPassport` |

#### 功能

修改手机号；`changeUserId` 非空时与目标用户调换手机号。需 `member_index_cellphone`，并记录操作日志。

#### 输入

```json
{
  "id": 10001,
  "passport": "13800000000",
  "changeUserId": null
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 要修改手机号的用户 ID。 |
| passport | string | 是 | 新手机号，不能为空。 |
| changeUserId | number | 否 | 调换号码的另一用户 ID；不调换时省略或传 `null`。 |

写操作建议前端二次确认。

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

<a id="post-manage-usermodifyremark"></a>

### POST /manage/user/modify/remark

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.modifyRemark` |

#### 功能

覆盖该用户当前客服备注，记录操作日志。需 `member_archive_note_modify`。

#### 输入

```json
{
  "id": 10001,
  "remark": "本次沟通后的备注"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 用户 ID。 |
| remark | string | 否 | 新客服备注；省略、`null` 或空字符串均清空当前备注。 |

不提供备注历史分页接口。

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。备注回显需重新请求用户列表。

<a id="post-manage-usermodifystatus"></a>

### POST /manage/user/modify/status

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.modifyStatus` |

#### 功能

设置用户为正常或黑名单状态，并记录操作日志。需 `member_index_set_blacklist`。加入黑名单会同时清空该用户当前 Token，使现有登录凭证失效；恢复正常后用户需要重新登录。

#### 输入

```json
{
  "id": 10001,
  "status": 2
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 用户 ID。 |
| status | number | 是 | `1` 表示正常，`2` 表示黑名单；不接受其他值。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。状态回显需重新请求用户列表，读取 `data.list[].status`。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `用户不存在` | `id` 不存在，或用户已被删除。 |
| 200 | -1 | `用户状态只能是 1 或 2` | `status` 不是 `1` 或 `2`。 |

<a id="post-manage-usermodifypassword"></a>

### POST /manage/user/modify/password

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.modifyPassword` |

#### 功能

重置指定用户的登录密码，并记录操作日志。需 `member_index_reset_password`。密码使用 BCrypt 编码后保存，接口不返回也不保存明文密码。

#### 输入

```json
{
  "id": 10001,
  "password": "NewPassword123",
  "confirmPassword": "NewPassword123"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 用户 ID。 |
| password | string | 是 | 新密码，不能为空且至少 6 位。 |
| confirmPassword | string | 否 | 确认密码；为兼容旧接口允许省略，传入时必须与 `password` 一致。 |

#### 输出

成功响应：

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `用户不存在` | `id` 不存在，或用户已被删除。 |
| 200 | -1 | `两次输入的密码不一致` | 传入的 `confirmPassword` 与 `password` 不一致。 |

<a id="get-manage-userexport"></a>

### GET /manage/user/export

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/UserController.java` |
| 方法 | `UserController.export` |

#### 功能

导出用户信息并记录操作日志。需 `member_index_export`。

#### 输入

无请求参数。

#### 输出

成功响应不是 JSON，而是 Excel 二进制流；`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`，`Content-Disposition` 携带 `.xlsx` 文件名。前端需按 blob 下载。导出列：用户 ID、昵称、手机号码、注册日期、身份、学员证号、备注、最后登录日期。

## 意见反馈

<a id="get-manage-feedbackpage"></a>

### GET /manage/feedback/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/FeedbackController.java` |
| 方法 | `FeedbackController.page` |

#### 功能

分页查询意见反馈，返回提交用户和图片资源。接口字段、筛选和排序行为与星鹤国学后台一致；按反馈 ID 倒序排列。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| status | number | 否 | 处理状态：`0` 未处理，`1` 已处理；省略时查询全部。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "user": {
          "id": 10001,
          "passport": "13800000000",
          "imageUrl": "https://example.com/avatar.png",
          "name": "测试用户",
          "deviceType": "iPhone"
        },
        "id": 3,
        "title": "功能建议",
        "content": "希望增加课程提醒",
        "isContact": 1,
        "status": 0,
        "createTime": "2026-09-24 10:00:00",
        "resources": [
          "https://example.com/feedback/1.png"
        ]
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.list | `Feedback[]` | 当前页反馈数组。 |
| data.list[].user | object | 提交用户。 |
| data.list[].user.id | number | 用户 ID。 |
| data.list[].user.passport | string | 用户手机号码，可缺省。 |
| data.list[].user.imageUrl | string | 用户头像 URL，可缺省。 |
| data.list[].user.name | string | 用户昵称，可缺省。 |
| data.list[].user.deviceType | string | 用户设备型号，可缺省。 |
| data.list[].id | number | 反馈 ID。 |
| data.list[].title | string | 问题类型，可缺省。 |
| data.list[].content | string | 问题描述，可缺省。 |
| data.list[].picUrl | string | 旧版保留字段；无值时省略。 |
| data.list[].isContact | number | 是否允许联系：`0` 否，`1` 是。 |
| data.list[].status | number | 处理状态：`0` 未处理，`1` 已处理。 |
| data.list[].remark | string | 后台处理备注；未处理或无备注时省略。 |
| data.list[].createTime | string | 反馈时间，格式 `yyyy-MM-dd HH:mm:ss`。 |
| data.list[].resources | `string[]` | 反馈图片 URL 数组，无图片时为空数组。 |
| data.total | number | 符合条件的反馈总数。 |
| data.current | number | 当前页码。 |
| data.size | number | 每页数量。 |

<a id="post-manage-feedbackprocess"></a>

### POST /manage/feedback/process

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/FeedbackController.java` |
| 方法 | `FeedbackController.process` |

#### 功能

处理一条未处理反馈，写入处理备注并将状态改为 `1`。请求和幂等行为与星鹤国学后台一致：已经处理的反馈再次提交时不覆盖原备注。需 `feedback_index_handle`。

#### 输入

```json
{
  "id": 3,
  "remark": "已经记录，将在后续版本改进"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 反馈 ID。 |
| remark | string | 否 | 处理备注。接口不向用户推送消息。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `反馈不存在` | `id` 对应的反馈不存在。 |

<a id="get-manage-feedbackexport"></a>

### GET /manage/feedback/export

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/FeedbackController.java` |
| 方法 | `FeedbackController.export` |

#### 功能

按处理状态导出反馈，行为与星鹤国学后台一致。每条反馈最多导出前三张图片。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| status | number | 否 | `0` 未处理，`1` 已处理；省略时导出全部。 |

#### 输出

成功响应不是 JSON，而是 Excel 二进制流：

- `Content-Type: application/vnd.ms-excel;charset=UTF-8`
- `Content-Disposition` 携带 `反馈_时间戳.xlsx` 文件名
- 工作表名称：`记录`
- 导出列依次为：创建人昵称、手机号码、手机型号、问题类型、问题描述、反馈日期、备注、是否可联系、图片1、图片2、图片3

## 微页面

微页面接口与星鹤国学后台保持一致。页面正文以 JSON 字符串写入 COS，数据库保存对应的文件 URL；管理端通过详情接口读取正文。后端不解释组件协议，`content` 的 JSON 结构由微页面编辑器维护。

<a id="get-manage-micro_pagepage"></a>

### GET /manage/micro_page/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |
| Response VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/MicroPageVo.java` |

#### 功能

分页查询状态为 `1` 的微页面，按 ID 倒序排列。`key` 按页面名称模糊匹配。需有效 Token。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| key | string | 否 | 页面名称关键字；省略或空字符串时查询全部。 |
| page | number | 否 | 页码，默认 1。 |
| pageSize | number | 否 | 每页数量，默认 20，最大 200。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "list": [
      {
        "id": 7,
        "name": "课程报名页",
        "createTime": "2026-09-24 15:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 20
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.list | `MicroPage[]` | 当前页微页面数组。 |
| data.list[].id | number | 微页面 ID。 |
| data.list[].name | string | 微页面名称。 |
| data.list[].createTime | string | 创建时间，格式 `yyyy-MM-dd HH:mm:ss`。 |
| data.total | number | 符合条件的微页面总数。 |
| data.current | number | 当前页码。 |
| data.size | number | 每页数量。 |

<a id="get-manage-micro_pageinfo"></a>

### GET /manage/micro_page/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |
| Response VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/MicroPageVo.java` |

#### 功能

查询微页面基本信息，并从 COS 读取页面正文。需有效 Token。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 微页面 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 7,
    "name": "课程报名页",
    "content": "{\"components\":[{\"type\":\"image\",\"url\":\"https://example.com/banner.png\"}]}"
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.id | number | 微页面 ID。 |
| data.name | string | 微页面名称。 |
| data.content | string | 页面组件 JSON 的原始字符串；历史记录没有正文 URL 时缺省。 |

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面不存在` | `id` 不存在或状态不是 `1`。 |
| 200 | -1 | `微页面内容读取失败` | COS 文件不存在、网络错误或 URL 无效。 |

<a id="post-manage-micro_pageadd"></a>

### POST /manage/micro_page/add

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |
| Request VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/MicroPageVo.java` |

#### 功能

新增微页面，将 `content` 作为 UTF-8 JSON 文件上传到 COS，并记录操作日志。需有效 Token。

#### 输入

```json
{
  "name": "课程报名页",
  "content": "{\"components\":[]}"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 微页面名称，不能为空。 |
| content | string | 是 | 页面组件 JSON 的原始字符串。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面名称不能为空` | `name` 缺失或仅包含空白字符。 |
| 200 | -1 | `微页面内容不能为空` | `content` 缺失或为 `null`。 |
| 200 | -1 | `文件上传失败` | COS 上传失败。 |

<a id="post-manage-micro_pagemodify"></a>

### POST /manage/micro_page/modify

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |
| Request VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/MicroPageVo.java` |

#### 功能

修改微页面名称和正文。正文会上传为新的 COS 文件，数据库改为保存新 URL，并记录操作日志。需有效 Token。

#### 输入

```json
{
  "id": 7,
  "name": "课程报名页（新版）",
  "content": "{\"components\":[{\"type\":\"text\",\"value\":\"立即报名\"}]}"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 微页面 ID。 |
| name | string | 是 | 微页面名称，不能为空。 |
| content | string | 是 | 修改后的页面组件 JSON 原始字符串。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面ID不能为空` | `id` 缺失。 |
| 200 | -1 | `微页面不存在` | `id` 不存在或状态不是 `1`。 |

## 平台管理

平台用于区分课程和学员所属的业务平台，提供列表、详情、新增、编辑和删除接口。

<a id="get-manage-platformpage"></a>

### GET /manage/platform/page

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/PlatformController.java` |
| Response VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/PlatformVo.java` |

#### 功能

查询全部正常平台，按平台编号升序排列。接口名称使用 `page`，实际返回完整数组，不接受分页参数。需有效 Token。

#### 输入

无请求参数。

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": [
    {
      "id": 1,
      "name": "星鹤国学",
      "code": "01",
      "userTotalNum": 120
    }
  ]
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data | `Platform[]` | 平台数组，无数据时为空数组。 |
| data[].id | number | 平台 ID。 |
| data[].code | string | 平台编号。 |
| data[].name | string | 平台名称。 |
| data[].userTotalNum | number | 平台总学员数，无学员时为 `0`。 |

<a id="get-manage-platforminfo"></a>

### GET /manage/platform/info

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/PlatformController.java` |
| Response VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/PlatformVo.java` |

#### 功能

查询平台编辑表单所需的信息。需有效 Token。

#### 输入

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 平台 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": 1,
    "name": "星鹤国学",
    "code": "01"
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.id | number | 平台 ID。 |
| data.code | string | 平台编号。 |
| data.name | string | 平台名称。 |

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `平台不存在` | `id` 不存在或平台已删除。 |

<a id="post-manage-platformadd"></a>

### POST /manage/platform/add

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/PlatformController.java` |
| Request VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/PlatformVo.java` |

#### 功能

新增平台并记录操作日志。需有效 Token。

#### 输入

```json
{
  "code": "01",
  "name": "星鹤国学"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 平台编号，正常平台之间不可重复。 |
| name | string | 是 | 平台名称。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `平台编号不能为空` | `code` 缺失或仅包含空白字符。 |
| 200 | -1 | `平台名称不能为空` | `name` 缺失或仅包含空白字符。 |
| 200 | -1 | `平台编号01已存在!` | 编号 `01` 已被正常平台使用。 |

<a id="post-manage-platformmodify"></a>

### POST /manage/platform/modify

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/PlatformController.java` |
| Request VO | `manage-api/src/main/java/com/xhzy/live/manage/vo/PlatformVo.java` |

#### 功能

修改平台编号和名称，并记录操作日志。需有效 Token。

#### 输入

```json
{
  "id": 1,
  "code": "01",
  "name": "星鹤国学"
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 平台 ID。 |
| code | string | 是 | 平台编号，正常平台之间不可重复。 |
| name | string | 是 | 平台名称。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `平台ID不能为空` | `id` 缺失。 |
| 200 | -1 | `平台不存在` | `id` 不存在或平台已删除。 |
| 200 | -1 | `平台编号01已存在!` | 编号 `01` 已被其他正常平台使用。 |

<a id="post-manage-platformdelete"></a>

### POST /manage/platform/delete

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/PlatformController.java` |

#### 功能

删除平台并记录操作日志。删除后平台不再出现在列表中。需有效 Token。

#### 输入

```json
{
  "id": 1
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 平台 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `平台ID不能为空` | `id` 缺失。 |
| 200 | -1 | `平台不存在` | `id` 不存在或平台已删除。 |

<a id="post-manage-micro_pagecopy"></a>

### POST /manage/micro_page/copy

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |

#### 功能

复制现有微页面。新页面沿用原名称和正文，但生成新的 ID 和 COS 文件 URL，并记录操作日志。需有效 Token。

#### 输入

```json
{
  "id": 7
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 被复制的微页面 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。复制成功后重新请求分页接口可取得新页面 ID。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面ID不能为空` | `id` 缺失。 |
| 200 | -1 | `微页面不存在` | `id` 不存在或状态不是 `1`。 |
| 200 | -1 | `微页面内容读取失败` | 原页面正文无法从 COS 读取。 |

<a id="post-manage-micro_pagedelete"></a>

### POST /manage/micro_page/delete

#### 位置

| 类型 | 位置 |
| --- | --- |
| Controller | `manage-api/src/main/java/com/xhzy/live/manage/controller/MicroPageController.java` |

#### 功能

物理删除微页面数据库记录，并记录操作日志。行为与星鹤国学后台一致；历史 COS 文件不在本接口中删除。需有效 Token。

#### 输入

```json
{
  "id": 7
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | number | 是 | 微页面 ID。 |

#### 输出

```json
{
  "code": 0,
  "message": "成功"
}
```

该接口没有业务返回数据，`data` 为 `null` 时省略。

#### 错误响应

| HTTP 状态 | code | message | 条件 |
| --- | --- | --- | --- |
| 200 | -1 | `微页面ID不能为空` | `id` 缺失。 |
| 200 | -1 | `微页面不存在` | `id` 不存在或状态不是 `1`。 |