hl-api-changelog/changelogs-v2/2026-05/21_2791_司机档案-修改接口-管理后台.md

【修改接口·管理后台】司机档案 6 接口（详情新增 relatedOrders mock 字段 + 全模块快照）

PR: #2796（详情加 relatedOrders mock 字段） | 服务: hl-fleet-service | 更新时间: 2026-05-21

存放目录: changelogs-v2/2026-05/ 影响范围: 管理后台「车管 / 司机档案」页（列表 + 详情 + 新增 + 编辑 + 软删 + Excel 批量导入）

---

⚠️ 关键变化

#	接口	状态	说明
§3.2	GET /admin/fleet/drivers/{driverId}	🔧 修改	响应新增 relatedOrders 字段（mock 占位，固定 3 条假数据）
其余 5 接口	—	首推	契约自模块首次落地（PR #2724）以来未变化，本次首推完整 changelog

relatedOrders 字段是 mock！固定返回 3 条假数据，所有司机返回相同内容。前端可基于字段做 UI 但不要硬编码业务逻辑（如"看到张总订单 = 司机已派单"）。详见 §3.2 + §9 + §12。

---

1. 接口背景

司机档案是车队所有司机的主数据：基本信息 / 驾照 / 紧急联系人 / 保险 / 历史统计 / 标签 / 多类目附件（身份证/驾驶证/肖像/健康证/培训证/荣誉/从业资格/其他 8 类）。

PR #2796 在司机详情 §3.2 响应里加了 relatedOrders 字段，让前端可以提前对接「司机详情 → 关联订单列表」的 UI 区块。但由于派车模块（订单 ↔ 司机关联）尚未对接到 fleet 服务，当前返回固定 3 条 mock 假数据，待后续真实化（详见 #2791）。

---

2. 变更清单

#	方法	路径	变更类型	说明
1	GET	/admin/fleet/drivers/page	首推	分页列表
2	GET	/admin/fleet/drivers/{driverId}	修改	详情，新增 relatedOrders mock 字段
3	POST	/admin/fleet/drivers	首推	新增（含标签 + 附件批量提交）
4	PUT	/admin/fleet/drivers/{driverId}	首推	编辑（attachments diff + tags 全量覆盖）
5	DELETE	/admin/fleet/drivers/{driverId}	首推	软删
6	POST	/admin/fleet/drivers/import	首推	Excel 批量导入（按身份证去重）

---

3. 接口详情

3.1 分页查询

GET /admin/fleet/drivers/page

• 使用场景：司机档案列表页，支持「2026 年赛季在册 / 续费待回复 / 往年档案 / 黑名单 / 全部」5 个 tab 切换（前端按 season 字段传值）
• 认证：管理后台 JWT
• 幂等：是

Query 入参：

字段	类型	必填	默认	校验	说明
page	int	❌	1	>= 1	页码
pageSize	int	❌	20	1-100	每页条数
keyword	string	❌	—	—	姓名模糊匹配
driverStatus	string	❌	—	idle/busy/rest/pending	状态精确（见 §6.2）
season	string	❌	—	active/pending/archived/blacklist	赛季精确（见 §6.3，对应前端 5 tab）
tagName	string	❌	—	—	标签名精确（拥有该标签的司机）
primaryVehiclePlate	string	❌	—	—	常驻车车牌精确匹配
insuranceType	string	❌	—	annual/perTrip/none	保险类型精确（见 §6.4）

出参：Result<PageResult<DriverPageItemRespVO>> （phone/idCard 脱敏；列表项含 tags，不含附件详情）

字段	类型	说明
records[].id	string	司机 ID
records[].name	string	姓名
records[].phone	string	手机号（脱敏，如 138****1234）
records[].idCard	string	身份证号（脱敏，如 150102******1234）
records[].gender	string	性别
records[].years	int	驾龄
records[].driverStatus	string	状态（见 §6.2）
records[].season	string	赛季（见 §6.3）
records[].primaryVehiclePlate	string	常驻车车牌
records[].insuranceType	string	保险类型（见 §6.4）
records[].tags[]	array	标签列表
records[].createTime	datetime	—
total / page / pageSize	int	分页元数据

典型示例 请求（5 tab 之一：在册）：

GET /admin/fleet/drivers/page?page=1&pageSize=20&season=active
Authorization: Bearer <token>
（无请求体）

典型示例 响应：

{
  "code": 200,
  "data": {
    "records": [
      {
        "id": "1234567890123456789",
        "name": "张三",
        "phone": "138****1234",
        "idCard": "150102******1234",
        "gender": "男",
        "years": 8,
        "driverStatus": "idle",
        "season": "active",
        "primaryVehiclePlate": "蒙A-88888",
        "insuranceType": "annual",
        "tags": ["老司机", "蒙语流利"],
        "createTime": "2025-05-21 14:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "msg": "成功"
}

前端 tab → season 取值映射：

前端 tab	后端参数
全部	（不传 season）
2026 年赛季在册	season=active
续费待回复	season=pending
往年档案	season=archived
黑名单	season=blacklist

"2026 年"是装饰文案（取自前端业务文案约定），后端 season 字段不带年份维度。

错误码：400 参数校验 / 401 未登录

---

3.2 详情 🔧 修改（新增 relatedOrders mock 字段）

GET /admin/fleet/drivers/{driverId}

• 使用场景：详情页 / 编辑前预填
• 认证：管理后台 JWT
• 幂等：是

路径入参：

字段	类型	必填	说明
driverId	Long	✅	司机 ID

出参：Result<DriverDetailRespVO>

主体字段（含 §3.1 全部字段）+ 以下扩展：

字段	类型	说明
nation	string	民族
preferredTypeKey	string	常开车型大类 key
preferredModel	string	常开车型名
vehicleSource	string	车源（own/company）
activeYearsJson	string	历次在册年份 JSON 数组字符串（如 "[2023,2024,2025]"）
license	object	驾照信息（见下）
emergency	object	紧急联系人（见下）
insurance	object	保险信息（见下）
stats	object	历史统计（见下）
tags[]	array	标签列表
attachments	object<string, array>	附件按类目分组（key=category，value=该类目附件列表）
relatedOrders[]	array	关联订单（mock 占位，固定 3 条，详见警示）
createTime / updateTime	datetime	—

license（DriverLicenseVO，DB 字段平铺，API 嵌套返回）：

字段	类型	说明
no	string	驾照号
type	string	准驾车型（A1/A2/B1/B2 等）
expire	date	有效期
issuedBy	string	发证机关

emergency（DriverEmergencyVO）：

字段	类型	说明
name	string	紧急联系人姓名
phone	string	手机号
relation	string	关系（父亲 / 妻子 等）

insurance（DriverInsuranceVO）：

字段	类型	说明
type	string	保险类型（见 §6.4）
company	string	保险公司（annual 必填）
policyNo	string	年保单号（annual 必填）
annualPremium	string	年保险费（BigDecimal 序列化）
annualStart	date	年保险起始日
annualEnd	date	年保险结束日
perDayRate	string	行程保险日费率（perTrip 必填）

stats（DriverStatsVO，详情专用）：

字段	类型	说明
totalOrders	int	历史接单总数
avgRating	string	平均评分 0-5（BigDecimal 序列化）
lastOrderAt	date	最近接单日期

attachments：Map<String, List<DriverAttachmentRespVO>>，key=类目（见 §6.1），value=该类目下的附件列表（按 sortNo 升序）：

字段	类型	说明
id	string	附件 ID
driverId	string	所属司机 ID
category	string	类目（见 §6.1）
sortNo	int	同类目排序（0-based）
url	string	OSS URL
mimeType	string	例 image/jpeg

relatedOrders[]（⚠️ mock 占位）：

字段	类型	说明
orderId	string	订单 ID（前端跳转用）
orderNo	string	订单号（如 HL2026060100123）
groupNo	string	团号（如 T2026-001）
customerName	string	客户姓名
tripStartDate	date	行程起始日
tripEndDate	date	行程结束日
destination	string	目的地概要
orderStatus	string	订单状态（pending / in_progress / completed）
vehicleType	string	车型快照
licensePlate	string	车牌快照

mock 真相（来自代码 DriverService.buildMockRelatedOrders()）：

• 当前固定返回 3 条假数据（李先生 in_progress / 王女士 completed / 张总 pending）
• 所有 driverId 返回的内容完全相同
• 真实化时机：派车模块对接 fleet 服务后，由 DriverService 改为 Feign 调 order 服务按 staffId 反查（Issue #2791）

典型示例 响应（节选）：

{
  "code": 200,
  "data": {
    "id": "1234567890123456789",
    "name": "张三",
    "phone": "138****1234",
    "idCard": "150102******1234",
    "gender": "男",
    "nation": "蒙古族",
    "years": 8,
    "driverStatus": "idle",
    "season": "active",
    "activeYearsJson": "[2023,2024,2025]",
    "primaryVehiclePlate": "蒙A-88888",
    "preferredTypeKey": "suv",
    "preferredModel": "丰田汉兰达",
    "vehicleSource": "company",
    "license": {
      "no": "15010219800101XXXX",
      "type": "B2",
      "expire": "2030-01-01",
      "issuedBy": "内蒙古公安厅交通管理局"
    },
    "emergency": {
      "name": "张三丰",
      "phone": "13800000000",
      "relation": "妻子"
    },
    "insurance": {
      "type": "annual",
      "company": "中国人保财险",
      "policyNo": "PICC-2024-XXX",
      "annualPremium": "3000.00",
      "annualStart": "2024-01-01",
      "annualEnd": "2025-01-01",
      "perDayRate": null
    },
    "stats": {
      "totalOrders": 128,
      "avgRating": "4.85",
      "lastOrderAt": "2025-05-18"
    },
    "tags": ["老司机", "蒙语流利"],
    "attachments": {
      "id_card": [
        { "id": "...", "driverId": "...", "category": "id_card", "sortNo": 0, "url": "https://oss/.../front.jpg", "mimeType": "image/jpeg" },
        { "id": "...", "driverId": "...", "category": "id_card", "sortNo": 1, "url": "https://oss/.../back.jpg", "mimeType": "image/jpeg" }
      ],
      "driver_license": [...],
      "portrait": [...]
    },
    "relatedOrders": [
      {
        "orderId": "900000000000000001",
        "orderNo": "HL2026060100123",
        "groupNo": "T2026-001",
        "customerName": "李先生",
        "tripStartDate": "2026-06-01",
        "tripEndDate": "2026-06-05",
        "destination": "呼伦贝尔草原 / 阿尔山 / 海拉尔",
        "orderStatus": "in_progress",
        "vehicleType": "丰田汉兰达",
        "licensePlate": "蒙A-12345"
      },
      {
        "orderId": "900000000000000002",
        "orderNo": "HL2026051800456",
        "groupNo": "T2026-002",
        "customerName": "王女士",
        "tripStartDate": "2026-05-18",
        "tripEndDate": "2026-05-22",
        "destination": "额尔古纳 / 室韦 / 莫尔道嘎",
        "orderStatus": "completed",
        "vehicleType": "丰田考斯特",
        "licensePlate": "蒙A-66666"
      },
      {
        "orderId": "900000000000000003",
        "orderNo": "HL2026070200789",
        "groupNo": "T2026-003",
        "customerName": "张总",
        "tripStartDate": "2026-07-02",
        "tripEndDate": "2026-07-08",
        "destination": "满洲里 / 套娃景区 / 国门",
        "orderStatus": "pending",
        "vehicleType": "奔驰威霆",
        "licensePlate": "蒙A-88888"
      }
    ],
    "createTime": "2025-05-21 14:00:00",
    "updateTime": "2025-05-21 14:00:00"
  },
  "msg": "成功"
}

错误码：600205 司机不存在 / 401 未登录

---

3.3 新增

POST /admin/fleet/drivers

• 使用场景：新增司机（含 tags 批量 + 附件批量提交，同一事务）
• 认证：管理后台 JWT
• 幂等：否（身份证 / 手机号重复抛 600200 / 600203）

Body 入参（DriverSaveReqVO）：

字段	类型	必填	校验	说明
name	string	✅	@Size(max=32)	姓名
phone	string	✅	@Pattern(^\d{11}$)	手机号 11 位（编辑时忽略）
idCard	string	✅	@Size(min=18,max=32)	身份证号（编辑时忽略）
gender	string	❌	@Size(max=4)	性别（男 / 女）
nation	string	❌	@Size(max=16)	民族
years	int	❌	—	驾龄（年）
driverStatus	string	❌	@Pattern(idle|busy|rest|pending)	状态
season	string	❌	@Pattern(active|pending|archived|blacklist)	赛季
primaryVehiclePlate	string	❌	@Size(max=16)	常驻车车牌
preferredTypeKey	string	❌	@Size(max=16)	常开车型大类 key
preferredModel	string	❌	@Size(max=64)	常开车型名
vehicleSource	string	❌	@Size(max=16)	车源（own / company）
license	object	❌	—	驾照嵌套对象（同 §3.2）
emergency	object	❌	—	紧急联系人嵌套对象（同 §3.2）
insurance	object	❌	—	保险嵌套对象（同 §3.2）
tags[]	array	❌	@Size(max=20)	标签列表（全量覆盖）
attachments[]	array	❌	—	附件数组（见 §3.3 attachment 表）

attachments[] 单项（DriverAttachmentReqVO）：

字段	类型	必填	校验	说明
id	Long	❌	—	新增项不传
category	string	✅	@Size(max=32)	类目（见 §6.1）
url	string	✅	@Size(max=512)	OSS URL
mimeType	string	✅	@Size(max=64)	例 image/jpeg
sortNo	int	❌	—	不传时按入参顺序自动重写 0..N-1

出参：Result<DriverCreateRespVO>

字段	类型	说明
id	string	新增司机 ID
attachmentIds[]	array	附件 ID 列表（按入参顺序）

典型示例 请求（节选）：

POST /admin/fleet/drivers
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "张三",
  "phone": "13812341234",
  "idCard": "150102198001011234",
  "gender": "男",
  "nation": "蒙古族",
  "years": 8,
  "driverStatus": "idle",
  "season": "active",
  "primaryVehiclePlate": "蒙A-88888",
  "preferredTypeKey": "suv",
  "preferredModel": "丰田汉兰达",
  "vehicleSource": "company",
  "license": {
    "no": "15010219800101XXXX",
    "type": "B2",
    "expire": "2030-01-01",
    "issuedBy": "内蒙古公安厅交通管理局"
  },
  "emergency": {
    "name": "张三丰",
    "phone": "13800000000",
    "relation": "妻子"
  },
  "insurance": {
    "type": "annual",
    "company": "中国人保财险",
    "policyNo": "PICC-2024-XXX",
    "annualPremium": "3000.00",
    "annualStart": "2024-01-01",
    "annualEnd": "2025-01-01"
  },
  "tags": ["老司机", "蒙语流利"],
  "attachments": [
    { "category": "id_card", "url": "https://oss/.../id-front.jpg", "mimeType": "image/jpeg" },
    { "category": "id_card", "url": "https://oss/.../id-back.jpg", "mimeType": "image/jpeg" },
    { "category": "driver_license", "url": "https://oss/.../license.jpg", "mimeType": "image/jpeg" },
    { "category": "portrait", "url": "https://oss/.../portrait.jpg", "mimeType": "image/jpeg" }
  ]
}

异常 请求（身份证重复）：

{ "code": 600200, "msg": "身份证已存在", "data": null }

异常 请求（驾照过期）：

{ "code": 600201, "msg": "驾照已过期", "data": null }

错误码：400 参数校验 / 600200 身份证已存在 / 600201 驾照已过期 / 600203 手机号已存在 / 601002 附件类目非法 / 601003 类目张数达上限 / 401 未登录

---

3.4 编辑（attachments diff + tags 全量覆盖）

PUT /admin/fleet/drivers/{driverId}

• 使用场景：编辑司机基本信息 + 标签全量覆盖 + 附件增删改一次性提交
• 认证：管理后台 JWT
• 幂等：是

路径入参：

字段	类型	必填	说明
driverId	Long	✅	司机 ID

Body 入参：同 §3.3（共用 DriverSaveReqVO），但：

• idCard / phone 后端忽略（不可改）
• tags[] 全量覆盖：物理删除旧 tags + 批量 INSERT 新 tags（空数组 = 清空所有标签）
• attachments[] diff 语义：有 id 命中 → 保留；无 id → INSERT；DB 有但未传 → 软删

附件 diff 语义（与车辆档案 §3.4 一致）：

入参 attachments[] 项	DB 中的对应行	行为
有 id + DB 命中	存在	保留（可更新 sortNo）
无 id（新增项）	—	INSERT
—	存在但本次未传	软删

特别说明（前 3 类目"换证留历史"语义）：id_card / driver_license / portrait 旧附件不在本次入参里 → 自动软删；新 url 无 id → INSERT。前端"换证"时不需要先调删除接口，直接组装新 attachments 数组即可。

出参：Result<DriverUpdateRespVO>

字段	类型	说明
kept	int	保留的附件数
inserted	int	新插入的附件数
softDeleted	int	软删的附件数
tagsReplaced	int	覆盖写入的标签数

典型示例 响应：

{
  "code": 200,
  "data": { "kept": 3, "inserted": 1, "softDeleted": 2, "tagsReplaced": 3 },
  "msg": "成功"
}

错误码：400 参数校验 / 600201 驾照已过期 / 600205 司机不存在 / 601002 类目非法 / 601003 类目张数达上限 / 401 未登录

---

3.5 软删

DELETE /admin/fleet/drivers/{driverId}

• 使用场景：下架司机
• 认证：管理后台 JWT
• 幂等：是

路径入参：

字段	类型	必填	说明
driverId	Long	✅	司机 ID

出参：Result<Void>

典型示例 响应：

{ "code": 200, "data": null, "msg": "成功" }

异常 请求（业务流水 PR 上线后才生效）：

{ "code": 600204, "msg": "司机有未完成派单，不能删除", "data": null }

错误码：600204 有未完成派单（占位，业务流水 PR 上线后生效） / 600205 司机不存在 / 401 未登录

---

3.6 Excel 批量导入

POST /admin/fleet/drivers/import

• 使用场景：运营批量录入司机
• 认证：管理后台 JWT
• 幂等：是（按身份证去重，已存在则更新，不存在则新增）

入参（multipart/form-data）：

字段	类型	必填	说明
file	file	✅	Excel（.xlsx / .xls）或 CSV

表头约定（第 1 行 15 列，顺序固定）：

姓名 | 手机号 | 身份证号 | 性别 | 民族 | 驾龄(年) |
驾照号 | 准驾车型 | 驾照有效期(yyyy-MM-dd) | 发证机关 |
紧急联系人姓名 | 紧急联系人手机 | 与司机关系 |
保险类型(annual/perTrip/none) | 常驻车车牌

出参：Result<DriverImportRespVO>（字段名与车辆导入不同）

字段	类型	说明
total	int	总行数（不含表头）
insertedCount	int	新增成功数
renewedCount	int	更新成功数（按身份证去重，已存在则更新）
errorCount	int	失败行数
errors[]	array	失败行详情

典型示例 响应：

{
  "code": 200,
  "data": {
    "total": 10,
    "insertedCount": 6,
    "renewedCount": 2,
    "errorCount": 2,
    "errors": [
      { "row": 3, "name": "张三", "msg": "驾照已过期" },
      { "row": 7, "name": "李四", "msg": "手机号格式错误" }
    ]
  },
  "msg": "成功"
}

⚠️ 与车辆导入的出参字段不同：车辆是 success/failed/errorRows，司机是 insertedCount/renewedCount/errorCount/errors。前端不能复用同一份解析逻辑。

错误码：400 文件解析失败 / 401 未登录

---

6. 枚举 / 数据字典

6.1 附件类目（category，DriverAttachmentCategoryEnum）

所属字段：DriverAttachmentReqVO.category / DriverAttachmentRespVO.category | 类型：String | 必填：✅

真枚举（后端硬编码 8 类目，含同类目张数上限）：

值	中文	张数上限	备注
id_card	身份证	2	"换证留历史"语义（支持正反 2 张或新旧 2 套）
driver_license	驾驶证	2	"换证留历史"
portrait	肖像照	2	"换证留历史"
health_cert	健康证	2	—
training_cert	培训证书	5	—
award	荣誉奖励	5	—
qualification	从业资格证	3	—
other	其他附件	5	—

超出上限触发 601003 "该类目张数已达上限"。

6.2 司机状态（driverStatus，DriverStatusEnum）

所属字段：DriverSaveReqVO.driverStatus / DriverPageReqVO.driverStatus / DriverPageItemRespVO.driverStatus / DriverDetailRespVO.driverStatus | 类型：String | 必填：❌

@Pattern 强校验枚举：

值	中文	说明
idle	空闲	可接单
busy	在途	正在执行派单
rest	休假	暂不接单
pending	待激活	新入职 / 回归尚未完成入驻

6.3 赛季（season，SeasonEnum）

所属字段：同 driverStatus | 类型：String | 必填：❌

@Pattern 强校验枚举：

值	中文	说明
active	在册	当前赛季正常在职
pending	待续签	赛季到期已发出续签邀请
archived	已归档	本赛季已退出
blacklist	黑名单	永久拉黑

6.4 保险类型（insuranceType，InsuranceTypeEnum）

所属字段：DriverInsuranceVO.type / DriverPageReqVO.insuranceType / DriverPageItemRespVO.insuranceType | 类型：String | 必填：❌

值	中文	必填字段
annual	年保险	需填 company / policyNo / annualPremium / annualStart / annualEnd
perTrip	行程保险	需填 perDayRate（按行程计费）
none	无保险	—

6.5 订单状态（orderStatus，mock 字段）

所属字段：DriverDetailRespVO.relatedOrders[].orderStatus | 类型：String | mock 占位

值	中文
pending	待出行
in_progress	进行中
completed	已完成

⚠️ 这是 mock 数据里的取值，真实派车模块对接后值列表可能扩展（如 canceled / refunded 等）。前端不要硬编码状态映射，等真实化后由后端文档明确。

---

7. 错误码（全模块汇总）

code	含义	触发条件	涉及接口
400	参数校验失败	字段缺失/长度/枚举/手机号格式/MIME 非法	所有写入接口
401	未登录	JWT 无效或缺失	全部 6 接口
600200	身份证已存在	idCard 全局唯一约束	§3.3
600201	驾照已过期	license.expire < 今日（新增 / 编辑主动校验）	§3.3 §3.4
600203	手机号已存在	phone 全局唯一约束	§3.3
600204	司机有未完成派单	业务流水 PR 上线后才触发（目前占位）	§3.5
600205	司机不存在	driverId 无效或软删	§3.2 §3.4 §3.5
601001	实体不存在	附件关联的主司机不存在	§3.3 §3.4
601002	附件类目非法	category 不在 §6.1 枚举内	§3.3 §3.4
601003	该类目张数已达上限	超出 §6.1 张数上限	§3.3 §3.4
601004	文件超出大小限制	应用层 + OSS HEAD 校验	§3.3 §3.4
601005	文件类型非法	MIME 不在白名单	§3.3 §3.4

错误码段位 600200-600205 归属司机档案（无与车辆 / 车型管理库冲突）；601001-601005 归属附件管理子段（车辆 / 司机共用）。

未列错误码 600202（司机已黑名单）：占位常量，业务流水 PR 上线后才会触发。

---

9. 业务边界

• ✅ PII 脱敏：phone / idCard 在 §3.1 列表项 + §3.2 详情响应中均脱敏返回（138****1234 / 150102******1234）；DB 存明文。前端展示时直接用响应值即可
• ✅ 编辑不可改 idCard / phone：§3.4 入参中的 idCard / phone 后端忽略，要改身份证 / 手机号需联系后端管理员（业务上极少发生）
• ✅ 驾照过期校验：§3.3 §3.4 主动校验 license.expire < 今日（不影响存量数据，仅写入时校验）
• ✅ tags 全量覆盖语义：§3.4 tags=[] = 清空所有标签；tags=null 也视为不修改（不传字段 = 不动），建议前端显式传空数组清空
• ✅ 附件 diff 语义：与车辆档案 §3.4 一致；id_card/driver_license/portrait 三类支持"换证留历史"（旧软删 + 新插入由 diff 天然完成）
• ✅ 唯一约束：idCard / phone 全局唯一
• ⚠️ relatedOrders mock 占位：见 §3.2 / §12

---

10. 修改前后对比（仅 §3.2 详情）

10.1 字段级对比

字段	改前	改后
DriverDetailRespVO	无 relatedOrders 字段	新增 relatedOrders[] 字段（mock 数据）

10.2 行为级对比

行为	改前	改后
调 §3.2 详情	响应里无关联订单信息	响应额外含 3 条 mock 订单

---

11. 影响评估

• 是否破坏向后兼容：否（仅新增字段，老前端忽略该字段照常工作）
• 前端是否必须同步上线：否（前端可按节奏对接 relatedOrders UI 区块）
• 影响已有数据：无（mock 数据来自代码，不入库）

---

12. 注意事项

• ⚠️ relatedOrders 是 mock：
  • 固定 3 条假数据，所有司机返回相同内容
  • 前端不要硬编码业务逻辑（如"看到张总订单 = 司机已派单 / 不能软删"等推断）
  • 真实化时机：派车模块对接 fleet 服务后，由 DriverService.buildMockRelatedOrders 替换为 Feign 实现（Issue #2791）
  • 真实化后字段名 / 字段类型与本 changelog 一致（已约定的契约），但取值范围可能扩展（如 orderStatus 增加 canceled）
• 分页参数名：page / pageSize（不是 pageNo）
• Long 主键序列化：id / attachments[].id / relatedOrders[].orderId 等 Long 字段 JSON 返回为 String，前端不要当 Number 解析
• 车辆导入 vs 司机导入字段名不同：见 §3.6 警示
• 5 个 tab 实现：见 §3.1 表格，纯通过 season 参数实现，无新接口
• 错误码段位连续：600200-600205 全在司机档案段，无避让

---

13. 关联 / 联系人

13.1 链接

• Issue（relatedOrders mock）: #2791
• PR（relatedOrders mock）: #2796
• Merge commit: ec0380439
• API 文档: docs/order-v3/api/API-SPEC-FLEET-V1.5.html §3 司机档案
• DB 文档: docs/order-v3/database/DATABASE-SCHEMA-FLEET-V1.5.html §2.4 + §2.7
• 同期相关 changelog:
  • 车型管理库 9 接口（21_2785_车型管理库-新增接口-管理后台.md）
  • 车辆档案 6 接口（21_车辆档案-修改接口-管理后台.md）

13.2 联系人

• 后端负责人: @yst（腰苏图）
• 前端对接（管理后台）: 待指派