From 2f5056e4f4bed6a4c538bcfb230ace9aa5b92c44 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 1 Apr 2026 12:44:46 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=9B=A2=E9=98=9F=E5=A1=AB=E6=8A=A5?=
 =?UTF-8?q?=E8=A1=A8=E5=8D=95=E6=A8=A1=E5=BC=8F=E6=8E=A5=E5=8F=A3=E5=8F=98?=
 =?UTF-8?q?=E6=9B=B4=E9=80=9A=E7=9F=A5=20(PR=20#105)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-04-01_1230_team_report_form.md       | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 changelogs/2026-04/2026-04-01_1230_team_report_form.md

diff --git a/changelogs/2026-04/2026-04-01_1230_team_report_form.md b/changelogs/2026-04/2026-04-01_1230_team_report_form.md
new file mode 100644
index 0000000..79f1a0a
--- /dev/null
+++ b/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