00先看这一页

服务端本轮迭代已完成并全部上线。这份文档给小程序的开发同学：哪些接口新增、哪些被重新设计、哪些要停用，以及每块业务背后的数据关系。

最重要的五件事

按页面看：需要改哪些

01通用约定

所有接口共享同一套响应、鉴权与错误约定，先对齐这页能省掉一半联调时间。

错误码与前端动作

联调入口

生产 Swagger 只在服务器回环可用，用 SSH 隧道访问：

ssh -N -i ~/.ssh/deepblue_admin_prod_ed25519     -L 9081:127.0.0.1:9081 -L 9082:127.0.0.1:9082 deploy@8.138.236.251

# C 端接口文档： http://127.0.0.1:9082/actuator/swagger-ui
# OpenAPI 规范：   http://127.0.0.1:9082/actuator/openapi   （可导入 Apifox）

如果本地连不上，先确认隧道进程还在；Swagger 端口仅绑定回环，不要尝试从公网访问。

02身份标识：user.id → user_no

这是本轮唯一的破坏性变更：所有“人”的对外标识从自增数字改成不可枚举的 user_no。它影响每一个带用户的接口。

规则

存量用户没有 user_no 怎么办

后端不做全量回填。两种时机按需生成（CAS + 唯一索引，幂等）：

路径对照（旧 → 新）

03约训练域：场馆 → 课次 → 约课

约训练从「活动 + 时段 + 按身份计费」重构成独立领域。旧的 /api/training/schedule、/api/training/session/{id}、/api/training/booking*、/api/training/my-bookings 已删除，必须换新接口。

三级页面与接口

课程类型的语义（决定“要不要付钱”）

约课主流程

payType 判定顺序（后端已算好，前端只展示）

课次状态与「待核销」

状态 4 是 2026-10 新增：课次到期且有报名时进入，教练发布训练记录后转 2；超过 72 小时未处理由系统兜底核销并扣次。

取消与退款

开课前 12 小时内不可自助取消（每节课可用 cancelDeadlineHours 覆盖）：接口返回 cancellable=false + cancelBlockReason，前端引导走订单退款。

常见错误文案（可直接展示）

04课包与权益：按次抵扣与核销

课包是“按次承诺”的商品：买了课包，约课时按课程类型对应的权益扣次数，而不是付钱。理解这张图，就能理解所有“剩余次数”的口径。

我的课包（3 个接口）

列表 / 详情字段

状态字典

流水字段

权益字典（新增能力）

权益不再是写死的枚举，而是可维护的字典：GET /api/entitlement-types（公开）返回启用中的权益。

{
  "code": 200,
  "data": [
    { "code": "THEORY", "name": "理论课" },
    { "code": "POOL",   "name": "泳池课" },
    { "code": "DEPTH",  "name": "深度课" },
    { "code": "PHOTO",  "name": "水下摄影" },
    { "code": "RETAKE", "name": "免费补考" }
  ]
}

响应结构没变。新增权益（例如把水摄做成课包可抵扣项）由运营在管理台维护，小程序无需改代码；权益中文名一律用接口返回值，不要在前端写死映射。

05课程商品：直售 / 拼团卖课包次数

课程商品是「考证拼团」的泛化：售卖的是课包模板的次数，买完到约训练约课扣次。价格与档位一律取自课包模板，商品本身不存价格。

接口

业务口径

我的订单状态

06证书：目录、我的证书、教练资格

证书体系从“手填文本”改成“目录 + 审核”：用户从字典里选证书，服务端按目录回填名称/机构/等级；证书是报名门槛与教练资格的依据。

① 证书目录（公开）

GET /api/certificate-definitions — 无需登录，按 sortOrder 升序返回启用中的目录项。

{
  "code": 200,
  "data": [
    {
      "certificateCode": "AIDA_2",
      "category": "FREEDIVING",          // FREEDIVING 自由潜 / SCUBA 水肺
      "qualificationType": "DIVER",      // DIVER 潜水员证书 / COACH 教练资格
      "organizationCode": "AIDA",        // 列表分组建议用这个
      "organizationName": "AIDA International",
      "levelCode": "2",
      "levelName": "AIDA 2",
      "displayName": "AIDA 2",
      "cardImageUrl": "https://…/card.png",
      "badgeImageUrl": "https://…/badge.png",
      "sortOrder": 102
    }
  ]
}

② 我的证书

提交规则（容易踩坑）

// 新增：不传 id
{ "certificateCode": "AIDA_2", "certNo": "AIDA-CN-2024-001",
  "issuedAt": "2019-04-28", "certImages": ["https://…/1.jpg"] }

// 被驳回后重新提交：必须带 id（服务端会把状态置回 0 并清空驳回原因）
{ "id": 12, "certificateCode": "AIDA_2", "certNo": "…", "issuedAt": "…", "certImages": ["…"] }

• 同一张证书重复新增返回 409「该用户已提交过此证书」——重新提交请带 id；
• 未传 certificateCode（兼容老客户端）时必须传 certName；
• 证书名称/机构/等级由目录回填，前端不要自己拼。

③ 教练资格

用户持有的证书中，若目录的 qualificationType = COACH 且该条记录 coach_qualification = 1，则作为教练教学资格；教练审核通过会同步用户类型与认证状态。

前端只需：教练主页/课次卡片展示认证信息；「教练入驻」表单里选择教练类证书。

④ 证书还能从哪来

除了用户自己上传、管理台审核，运营现在还可以按课包直接发证（管理台「用户详情 › 课包 › 发放证书」）。

对小程序的影响：用户可能在没有上传记录的情况下突然多一张「已通过」的证书——这是正常业务动作，列表与「我的证书」会直接出现。

07个人日志：训练记录、教练评价、成绩档案

课程结束后，教练为每个报名学员登记评价（文字、图片、成绩指标）；学员在「我的日志 → 训练记录」查看每次约训与历史成绩曲线。

① 指标字典（决定“不同课程类型填不同内容”）

GET /api/user/training/metric-defs?courseType=DEPTH（需登录）

初始种子 8 项：STA（秒）、DYNB/DYM/DNF（米）→ 泳池课；FIM/CWTB/CWT/CNF（米）→ 深度课。运营可新增，新增指标无需发版。

② 教练端（需登录且必须是该课教练）

{
  "bookingId": 51,
  "content": "本次深度训练完成攀绳下潜 26 米，耳压平衡顺畅。",
  "images": ["https://…/1.jpg"],
  "metrics": [
    { "code": "FIM",  "value": 26, "remark": "个人最好成绩" },
    { "code": "CWTB", "value": 26 }
  ],
  "draft": false
}

• 每个预约一条日志，重复提交是更新并自动写历史版本；
• draft=true 存草稿：不校验必填、不计入最佳成绩；发布（false/缺省）时 required=1 的指标缺失会被拒绝；
• 只有课程已结束且预约状态为「已上课/未到场」时可填写；并发修改返回「评价刚被修改过，请刷新后重试」；
• 发布即核销该学员报名（占用转已用、扣课包次数）。

③ 学员端（需登录，仅本人）

// 训练记录的一天
{
  "date": "2026-10-12",
  "weekday": "周一",
  "records": [
    { "logId": 88, "bookingId": 51, "sessionId": 9, "title": "深度训练",
      "venueName": "深蓝一号泳池", "coachName": "李教练", "courseTypeName": "深度课",
      "startTime": "09:00", "endTime": "11:00", "thumbnail": "https://…",
      "logStatus": "PUBLISHED" }
  ]
}

08他人主页与潜水记录

他人主页是公开页（无需登录），全部按 userNo 访问；潜水记录是作者侧的内容管理，支持可见性。

① 他人主页（公开，无需登录）

② 潜水记录（作者侧，需登录）

• 图片 ≤ 9 张；diveDate 不能晚于今天；
• buddyPostId 必须是本人参与过的潜伴约潜；trainingLogId 必须是本人的训练评价；
• visibility：PUBLIC（默认）/ PRIVATE（仅自己）。

③ 同班入口

GET /api/user/training/sessions/{sessionId}/classmates（需登录，仅该节课报名学员可访问）→ 同班学员与教练（userNo、昵称、头像、是否教练、到课状态）。

另外 GET /api/user/training/bookings/{bookingId} 新增 classmates（前 10 位）与 classmateCount，用于「同班」头像条。

09考证拼团与分层拼团价（存量功能）

这套接口已被课程商品取代，但老小程序仍在用，所以保留为只读并标记待下线。若你还需维护它，这里是它的口径。

分层价的三个硬规则

1. groupBuyEnabled=false → 隐藏拼团入口（该课包未配置拼团价）；
2. 有多档位时下单必须传 tierSize，否则报「请选择拼团档位」；传了不存在的档位报「该课程不支持 N 人拼团」；
3. 团的有效期是团级的（开团时写死 endTime），与活动的 registrationDeadline 无关。

10废弃接口与迁移映射

服务端对“要停用”的接口都打了 deprecated 标记（共 13 个）。它们现在仍可调用，但新页面不要再接。

接口迁移表

11接入清单（按页面）

可直接当任务清单用。每项都对应上面的章节，做完打勾。

身份与通用

约训练（重写）

课包与课程商品

证书

个人日志与内容

12附录：字典与字段速查

A. 字典

B. 字段速查（旧 → 新）

13附录：C 端完整接口清单（185 条）

由源码注解自动提取。可输入路径或关键字过滤；公开 表示无需登录。