feat: 团队填报表单模式接口变更通知 (PR #105)

changelogs/2026-04/2026-04-01_1230_team_report_form.md

@@ -0,0 +1,93 @@
+# feat: 团队填报改为表单模式——预填/暂存/提交
+
+- **PR**: #105（基于 #104）
+- **服务**: hl-order-service
+- **类型**: 接口变更
+
+---
+
+## 接口变更
+
+原来的 `POST /admin/team-report/sync` **废弃**，改为以下3个接口：
+
+### 1. 预填表单（从订单自动填充）
+
+```
+GET /admin/team-report/prefill/{orderId}
+```
+
+**说明**: 首次调用从订单数据自动填充所有字段；如已有暂存记录，返回上次保存的数据。
+
+**响应**: 返回完整的 `TeamReportFormDTO`，包含以下区块：
+
+| 区块 | 字段 |
+|------|------|
+| 基础 | orderId, agencyCode, businessType |
+| 团队信息 | agencyName, agencyLicense, itineraryName, teamId, dateGo, timeGoHour/Minute, dateBack, timeBackHour/Minute, sourceCity, sourceProvince, destinationCity, destinationProvince, itineraryDay, vehicle, vehicleIn, vehicleOutNums, vehicleInNums, nativeTravelAgency, teamType, peopleNums, childNums, journeyDesc, applicantName, applicantPhone |
+| 导游信息 | guides: [{name, cardId, phone, type, isLeader}] |
+| 车队信息 | busInfo: [{carId, carComp, driverName, driverPhone}] |
+| 行程单 | itineraryList: [{dayNumber, siteNum, date, city, province, journeyDesc, title, isTransit}] |
+| 游客名单 | touristList: [{name, pyFamilyName, pyGivenName, dateOfBirth, phoneNum, sex, age, isChild, hrProvince, cardType, cardId, cardValidTo}] |
+
+---
+
+### 2. 暂存表单
+
+```
+POST /admin/team-report/save
+```
+
+**请求体**: 完整的 `TeamReportFormDTO`（和 prefill 返回结构一致）
+
+**说明**: 保存用户编辑的表单数据，不提交到12301。状态保持 `PENDING`。
+
+---
+
+### 3. 提交到12301
+
+```
+POST /admin/team-report/submit
+```
+
+**请求体**: 完整的 `TeamReportFormDTO`
+
+**说明**: 保存表单数据并提交到12301平台。成功后状态变为 `SYNCED`。
+
+---
+
+### 保留的接口
+
+| 接口 | 用途 |
+|------|------|
+| `GET /admin/team-report/{orderId}` | 获取同步记录（含 formData） |
+| `GET /admin/team-report/status/{orderId}` | 实时查询12301审核状态 |
+| `POST /admin/team-report/cancel` | 取消团队 |
+
+---
+
+## 前端页面对接
+
+参考12301团队信息同步页面，在订单详情新增「同步」tab：
+
+1. 进入页面 → 调用 `GET /admin/team-report/prefill/{orderId}` 获取预填数据
+2. 用户可编辑所有字段（旅行社主体radio、业务类型radio、团队信息表单、导游/车队/行程可增删行）
+3. 底部两个按钮：
+   - **「暂存」** → `POST /admin/team-report/save`
+   - **「提交到12301」** → `POST /admin/team-report/submit`
+4. 已提交后展示 syncStatus 和 platformStatus
+
+## 枚举值
+
+**businessType**: 2=国内游组团, 6=入境接待, 7=国内接待
+**teamType**: 1=自组自接, 2=包机, 3=专列, 4=其他
+**vehicle**: 1=飞机, 2=火车, 3=轮船, 4=汽车, 5=其它
+
+## DDL
+
+```sql
+ALTER TABLE team_report ADD COLUMN form_data JSON NULL COMMENT '表单数据JSON' AFTER upload_count;
+```
+
+## 需重启
+
+- hl-order-service