ManageServer API开发手册

接口说明

项目	内容
文档名称	ManageServer API开发手册
服务访问地址	`ly.zhenyou.top`
接口前缀	`/api/user`
适用对象	适用于 App 端、前端联调、测试验收、接口对接及实施交付。
文档依据	依据 `project-docs/API_DOCUMENT.md` 与 `project-docs/API_PATHS_REFERENCE.md` 当前实现整理。

1. 文档说明

本文档用于说明 ManageServer 当前用户端接口的调用方式、数据结构与业务约束，覆盖认证、用户信息、设备管理、训练管理及审计查询等核心能力。本文档面向研发、测试、实施及第三方集成团队，作为接口联调、验收测试与交付使用的统一依据。

2. 服务地址与测试账号

类型	账号	昵称	说明
管理员测试账号	`admin_01`	管理员账号	用于管理端相关联调与权限验证。
普通用户测试账号	`test_user_01`	测试用户	用于用户端设备、训练、审计等功能验证。

说明：当前文档仅记录测试内置账号标识，账号密码请以实际测试环境下发信息为准。

3. 调用规范

事项	说明
协议与地址	当前测试环境访问地址为 `ly.zhenyou.top`。
接口前缀	用户端接口统一以 `/api/user` 为前缀。
鉴权方式	除注册、登录外，其余接口均需在请求头中携带 JWT：`Authorization: Bearer <accessToken>`。
数据格式	请求与响应统一采用 `application/json`。
时间格式	日期时间字段统一采用 ISO-8601 格式，例如 `2026-03-14T15:10:00`。
权限说明	用户端接口面向已登录账号开放；设备绑定、解绑、换绑及设默认等用户操作仅允许 `ROLE_USER` 调用。

4. 统一响应结构

系统接口统一返回以下 JSON 结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

字段	类型	说明
`code`	int	业务状态码，`0` 表示成功，其余表示失败或异常。
`message`	string	结果说明信息，成功时通常返回 `success`。
`data`	object / array / null	业务数据主体；无返回数据时一般为 `null`。

4.1 常见错误码

错误码	说明
400	请求参数错误
401	未认证或令牌无效
403	无访问权限
500	系统内部错误
1001	用户名已存在
1002	用户不存在
1003	用户状态不可用
1004	用户名或密码错误
1006	原密码错误
2001	设备不存在
2002	设备状态不可用
2003	设备已被其他用户绑定
2004	已达到设备绑定上限
2005	设备绑定关系不存在
2006	设备编号或序列号已存在
2007	仅普通用户可以绑定、解绑或设置默认设备
3001	训练记录不存在
3002	训练状态不允许当前操作
3003	训练设备未绑定到当前用户
3004	训练通道不存在
3005	训练指标定义不存在

5. 接口总览

模块	主要接口
认证模块	`/api/user/auth/register`、`/api/user/auth/login`、`/api/user/auth/logout`、`/api/user/auth/change-password`、`/api/user/auth/refresh-token`
用户模块	`/api/user/me`、`/api/user/profile`、`/api/user/avatar`、`/api/user/username`
设备模块	`/api/user/devices/bind`、`/api/user/devices/unbind`、`/api/user/devices/rebind`、`/api/user/devices/default`、`/api/user/devices/my`、`/api/user/devices/current`、`/api/user/devices/{deviceId}`
训练模块	`/api/user/trainings` 及其子路径
审计模块	`/api/user/audit/login-logs`、`/api/user/audit/operation-logs`、`/api/user/audit/trainings/{trainingId}/events`

6. 认证模块

认证模块用于完成用户注册、登录、退出登录、密码变更及访问令牌刷新，是用户访问系统的基础能力。

接口名称	方法	路径	说明
用户注册	POST	`/api/user/auth/register`	注册普通用户账号，成功后返回用户 ID。
用户登录	POST	`/api/user/auth/login`	使用用户名和密码登录，成功后返回访问令牌。
退出登录	POST	`/api/user/auth/logout`	当前会话主动退出，并记录审计日志。
修改密码	POST	`/api/user/auth/change-password`	修改当前用户密码，需提供原密码。
刷新令牌	POST	`/api/user/auth/refresh-token`	换发新的访问令牌。

6.1 用户注册

POST ly.zhenyou.top/api/user/auth/register

{
  "username": "test_user_01",
  "password": "123456",
  "nickname": "测试用户"
}

{
  "code": 0,
  "message": "success",
  "data": 1
}

6.2 用户登录

POST ly.zhenyou.top/api/user/auth/login

{
  "username": "test_user_01",
  "password": "123456"
}

{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1,
    "username": "test_user_01",
    "nickname": "测试用户",
    "accessToken": "xxx",
    "tokenType": "Bearer",
    "expiresIn": 7200
  }
}

7. 用户模块

用户模块用于维护当前登录用户的个人资料，包括基本信息查询、资料更新、头像更新和用户名修改。

接口名称	方法	路径	说明
查询当前用户信息	GET	`/api/user/me`	查询当前登录用户基础档案信息。
更新个人资料	PUT	`/api/user/profile`	修改昵称、手机号、邮箱、性别、生日等信息。
更新头像	PUT	`/api/user/avatar`	修改头像地址。
修改用户名	PUT	`/api/user/username`	修改当前登录用户名。

7.1 查询当前用户信息

GET ly.zhenyou.top/api/user/me
Authorization: Bearer <accessToken>

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "test_user_01",
    "nickname": "测试用户",
    "phone": null,
    "email": null,
    "avatarUrl": null,
    "gender": null,
    "birthday": null,
    "status": "NORMAL",
    "lastLoginTime": "2026-03-14T11:00:00"
  }
}

7.2 更新个人资料

PUT ly.zhenyou.top/api/user/profile
Authorization: Bearer <accessToken>

{
  "nickname": "新昵称",
  "phone": "13800138000",
  "email": "demo@test.com",
  "gender": 1,
  "birthday": "1998-01-01"
}

8. 设备模块

设备模块用于管理普通用户与设备之间的绑定关系，包括绑定、解绑、换绑、设置默认设备以及查询本人设备信息。

接口名称	方法	路径	说明
绑定设备	POST	`/api/user/devices/bind`	将设备绑定到当前普通用户账号。
解绑设备	POST	`/api/user/devices/unbind`	解除指定设备与当前用户的绑定关系。
换绑设备	POST	`/api/user/devices/rebind`	将旧设备解绑并将新设备绑定到当前用户。
设置默认设备	POST	`/api/user/devices/default`	在已绑定设备中设置默认设备。
查询我的设备列表	GET	`/api/user/devices/my`	查询当前用户已绑定的全部设备。
查询当前默认设备	GET	`/api/user/devices/current`	查询当前用户默认设备。
查询我的设备详情	GET	`/api/user/devices/{deviceId}`	查询当前用户指定设备详情。

8.1 绑定设备

POST ly.zhenyou.top/api/user/devices/bind
Authorization: Bearer <accessToken>

{
  "deviceId": "DEV-001",
  "setAsDefault": true
}

业务约束：

仅 ROLE_USER 可调用。
设备必须已存在，且状态为 NORMAL。
单个用户最多可绑定 10 台设备。

8.2 解绑设备

POST ly.zhenyou.top/api/user/devices/unbind
Authorization: Bearer <accessToken>

{
  "deviceId": "DEV-001",
  "unbindReason": "测试解绑"
}

8.3 换绑设备

POST ly.zhenyou.top/api/user/devices/rebind
Authorization: Bearer <accessToken>

{
  "oldDeviceId": "DEV-001",
  "newDeviceId": "DEV-002",
  "setAsDefault": true,
  "unbindReason": "更换设备"
}

8.4 查询我的设备列表

GET ly.zhenyou.top/api/user/devices/my
Authorization: Bearer <accessToken>

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "deviceId": "DEV-001",
      "deviceSn": "SN-001",
      "deviceName": "测试设备1",
      "deviceType": "EMG4",
      "channelCount": 4,
      "status": "NORMAL",
      "onlineStatus": "OFFLINE",
      "isDefault": true,
      "bindTime": "2026-03-14T11:10:00"
    }
  ]
}

9. 训练模块

训练模块用于完成训练全流程管理，包括训练创建、启动、过程指标保存、最终指标保存、原始文件索引登记、结束、中断、列表查询、详情查询、删除、重算与统计。

接口名称	方法	路径	说明
创建训练	POST	`/api/user/trainings`	创建训练记录，初始状态为 `PENDING`。
开始训练	POST	`/api/user/trainings/{id}/start`	将训练状态切换为 `RUNNING`。
保存过程指标	POST	`/api/user/trainings/{id}/metric-snapshots`	保存训练过程中的指标快照。
保存最终指标	POST	`/api/user/trainings/{id}/final-metrics`	保存或更新训练最终指标结果。
保存原始文件索引	POST	`/api/user/trainings/{id}/raw-files`	登记原始文件索引信息，不保存文件本体。
结束训练	POST	`/api/user/trainings/{id}/finish`	正常完成训练并写入结果摘要。
中断训练	POST	`/api/user/trainings/{id}/interrupt`	中断训练流程。
查询我的训练列表	GET	`/api/user/trainings`	查询当前用户全部训练记录。
查询训练详情	GET	`/api/user/trainings/{id}`	查询指定训练完整详情。
删除训练	DELETE	`/api/user/trainings/{id}`	逻辑删除训练记录。
重算最终指标	POST	`/api/user/trainings/{id}/recalculate`	根据已有快照重新计算最终指标。
训练统计	GET	`/api/user/trainings/statistics`	查询训练统计概览。

9.1 创建训练

POST ly.zhenyou.top/api/user/trainings
Authorization: Bearer <accessToken>

{
  "deviceId": "DEV-001",
  "stationId": null,
  "trainingType": "RELAX",
  "sampleRate": 1000,
  "remark": "首次训练"
}

业务约束：训练设备必须已绑定到当前用户；创建成功后训练状态为 PENDING。

9.2 保存过程指标

POST ly.zhenyou.top/api/user/trainings/{id}/metric-snapshots
Authorization: Bearer <accessToken>

{
  "items": [
    {
      "channelNo": 1,
      "metricCode": "RMS",
      "windowNo": 0,
      "snapshotTime": "2026-03-14T15:10:00",
      "metricValue": 12.3456,
      "metricStatus": "CALCULATED"
    }
  ]
}

业务约束：仅 RUNNING 状态允许保存；metricCode 必须为已启用指标定义。

9.3 保存最终指标

POST ly.zhenyou.top/api/user/trainings/{id}/final-metrics
Authorization: Bearer <accessToken>

{
  "items": [
    {
      "channelNo": 1,
      "metricCode": "RMS",
      "metricValue": 15.6789,
      "metricText": null,
      "metricStatus": "CALCULATED",
      "algorithmVersion": "v1.0.0"
    }
  ]
}

9.4 保存原始文件索引

POST ly.zhenyou.top/api/user/trainings/{id}/raw-files
Authorization: Bearer <accessToken>

{
  "items": [
    {
      "fileType": "RAW_EMG",
      "filePath": "/data/emg/session-1.raw",
      "fileHash": "sha256-demo",
      "fileSize": 102400,
      "sampleRate": 1000,
      "durationMs": 30000,
      "storageType": "LOCAL"
    }
  ]
}

说明：该接口仅保存原始文件索引信息，不直接上传文件本体。

9.5 结束训练

POST ly.zhenyou.top/api/user/trainings/{id}/finish
Authorization: Bearer <accessToken>

{
  "remark": "训练正常完成",
  "resultSummary": {
    "overallScore": 92.5,
    "conclusion": "状态稳定"
  }
}

9.6 查询我的训练列表

GET ly.zhenyou.top/api/user/trainings
Authorization: Bearer <accessToken>

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "sessionNo": "TS202603141510001234",
      "deviceId": "DEV-001",
      "deviceName": "测试设备1",
      "channelCount": 4,
      "trainingType": "RELAX",
      "status": "COMPLETED",
      "startTime": "2026-03-14T15:10:00",
      "endTime": "2026-03-14T15:10:30",
      "durationMs": 30000,
      "sampleRate": 1000,
      "createdAt": "2026-03-14T15:09:58"
    }
  ]
}

9.7 查询训练详情

返回内容通常包括：

训练主记录
通道列表
最终指标列表
原始文件索引列表
训练事件列表

9.8 重算最终指标

POST ly.zhenyou.top/api/user/trainings/{id}/recalculate
Authorization: Bearer <accessToken>

{
  "algorithmVersion": "recalculate-v1"
}

说明：当前版本会基于过程指标快照求平均值后回写最终指标表。

9.9 训练统计

返回内容通常包括：

总训练数
各状态训练数
总训练时长
过程指标条数
最终指标条数

10. 审计模块

审计模块用于支撑用户级行为留痕与训练过程追踪，包括登录日志、操作审计日志及训练事件日志查询。

接口名称	方法	路径	说明
查询我的登录日志	GET	`/api/user/audit/login-logs`	查询当前用户的登录历史记录。
查询我的操作审计日志	GET	`/api/user/audit/operation-logs`	查询当前用户的操作留痕记录。
查询训练事件日志	GET	`/api/user/audit/trainings/{trainingId}/events`	查询指定训练会话的事件日志。

10.1 查询我的登录日志

GET ly.zhenyou.top/api/user/audit/login-logs
Authorization: Bearer <accessToken>

10.2 查询我的操作审计日志

GET ly.zhenyou.top/api/user/audit/operation-logs
Authorization: Bearer <accessToken>

10.3 查询训练事件日志

GET ly.zhenyou.top/api/user/audit/trainings/{trainingId}/events
Authorization: Bearer <accessToken>

11. 管理端接口

管理端接口用于后台运营、设备管理、用户管理、训练审计及安全控制。根据角色不同分为管理员接口与超级管理员接口两类，调用时应使用对应权限账号获取访问令牌。

11.1 访问说明

类别	路径前缀	访问角色	说明
管理端接口	`/api/admin`	`ROLE_ADMIN`、`ROLE_SUPER_ADMIN`	用于普通后台管理。管理员仅可查看普通用户相关数据。
超级管理员接口	`/api/superadmin`	`ROLE_SUPER_ADMIN`	用于全局账号、权限、安全与全量审计管理。

11.2 管理员接口

分类	方法	路径	说明
仪表盘	GET	`/api/admin/dashboard/overview`	查询管理端概览统计信息。
用户	GET	`/api/admin/users`	查询普通用户列表，不包含管理员和超级管理员。
用户	GET	`/api/admin/users/{userId}`	查询指定普通用户详情。
用户	GET	`/api/admin/users/{userId}/trainings`	查询指定普通用户训练列表，支持 `status`、`deviceId`、`trainingType` 筛选。
设备	GET	`/api/admin/devices`	查询设备池列表。
设备	POST	`/api/admin/devices`	新增设备。
设备	GET	`/api/admin/devices/{deviceId}`	查询设备详情。
设备	GET	`/api/admin/devices/{deviceId}/bindings`	查询设备归属历史。
设备	PUT	`/api/admin/devices/{deviceId}`	编辑设备信息。
设备	POST	`/api/admin/devices/{deviceId}/disable`、`/enable`	启用或禁用设备。
设备	POST	`/api/admin/devices/{deviceId}/assign`、`/unbind`	分配设备给普通用户或解除绑定关系。
训练	GET	`/api/admin/trainings`	查询普通用户训练记录。
审计	GET	`/api/admin/audit/login-logs`、`/api/admin/audit/operation-logs`	查询普通用户全量登录日志和操作日志，支持筛选。
审计	GET	`/api/admin/audit/users/{userId}/login-logs`、`/api/admin/audit/users/{userId}/operation-logs`	按普通用户查询定向日志，适合问题排查。

11.2.1 管理端鉴权示例

Authorization: Bearer <adminToken>

11.2.2 新增设备示例

POST ly.zhenyou.top/api/admin/devices
Authorization: Bearer <adminToken>

{
  "deviceId": "DEV-002",
  "deviceSn": "SN-002",
  "deviceName": "测试设备2",
  "deviceType": "EMG8",
  "channelCount": 8,
  "model": "EMG-Model-B",
  "firmwareVersion": "1.0.0",
  "hardwareVersion": "1.0.0",
  "bluetoothMac": "AA:BB:CC:DD:EE:FF",
  "wirelessInfo": "BLE",
  "manufactureDate": "2026-03-01",
  "remark": "后台新增设备"
}

11.2.3 分配设备示例

POST ly.zhenyou.top/api/admin/devices/DEV-002/assign
Authorization: Bearer <adminToken>

{
  "userId": 2,
  "setAsDefault": true
}

业务说明：

设备仅能分配给普通用户。
若设备已绑定其他用户，系统会先解绑再重新绑定到目标用户。
setAsDefault 用于指定该设备是否设为目标用户默认设备。

11.2.4 设备归属历史

GET ly.zhenyou.top/api/admin/devices/DEV-002/bindings
Authorization: Bearer <adminToken>

返回该设备的完整绑定历史，包括绑定账号、账号角色、默认设备标记、绑定时间、解绑时间、解绑原因及历史状态等信息。

11.2.5 审计查询说明

接口	筛选参数
`/api/admin/audit/login-logs`	`username`、`loginType`、`success`、`startTime`、`endTime`
`/api/admin/audit/operation-logs`	`username`、`module`、`operationType`、`resultStatus`、`startTime`、`endTime`

管理员仅可查看普通用户日志；若目标 userId 属于管理员或超级管理员，接口应返回拒绝访问或用户不可见。