feat: 团队填报API变更通知 (PR #104)

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

@@ -0,0 +1,139 @@
+# feat: 团队填报——对接全国旅游监管服务平台团队信息同步API
+
+- **PR**: #104
+- **服务**: hl-order-service, hl-gateway
+- **类型**: 新功能
+
+---
+
+## 新增接口（4个）
+
+### 1. 同步团队信息到监管平台
+
+```
+POST /admin/team-report/sync
+```
+
+**请求体**:
+```json
+{
+  "orderId": 1234567890
+}
+```
+
+**响应**:
+```json
+{
+  "code": 200,
+  "data": {
+    "reportId": 1234567890,
+    "orderId": 1234567890,
+    "teamId": "HL2603-PP-002",
+    "agencyCode": "hulai",
+    "agencyLicense": "L-NMG-100953",
+    "businessType": 2,
+    "syncStatus": "SYNCED",
+    "platformStatus": null,
+    "platformStatusText": "未知",
+    "uploadCount": 0,
+    "errorMsg": null,
+    "syncedAt": "2026-04-01T12:00:00"
+  }
+}
+```
+
+**说明**: 根据订单数据自动组装团队信息，上报到12301全国旅游监管服务平台。已同步的订单可重复调用（会更新）。
+
+---
+
+### 2. 取消团队
+
+```
+POST /admin/team-report/cancel
+```
+
+**请求体**:
+```json
+{
+  "orderId": 1234567890,
+  "cancelType": 1,
+  "cancelDesc": "旅行社原因取消"
+}
+```
+
+**cancelType 取值**: 0=游客个人原因, 1=旅行社原因, 2=不可抗因素, 3=其他
+
+---
+
+### 3. 查询审核状态（实时从平台查询）
+
+```
+GET /admin/team-report/status/{orderId}
+```
+
+**说明**: 实时调用12301平台查询团队审核状态。
+
+---
+
+### 4. 获取同步记录
+
+```
+GET /admin/team-report/{orderId}
+```
+
+**说明**: 获取该订单的团队填报记录。未同步过返回 `data: null`。
+
+---
+
+## syncStatus 状态
+
+| 值 | 含义 |
+|---|---|
+| PENDING | 待同步 |
+| SYNCED | 已同步 |
+| FAILED | 同步失败 |
+| CANCELLED | 已取消 |
+
+## platformStatus 平台审核状态
+
+| 值 | 含义 |
+|---|---|
+| 1 | 待提交 |
+| 2 | 已提交/已审核 |
+| 3 | 审核不通过 |
+| 4 | 审核通过 |
+| 7 | 待取消 |
+| 8 | 已取消 |
+| 9 | 已出团 |
+
+---
+
+## 前端对接说明
+
+在**订单详情页**的「合同保险」tab → 合同信息区域旁边，新增：
+
+1. **「同步团队」按钮** — 调用 `POST /admin/team-report/sync { orderId }`
+   - 有合同信息后展示此按钮
+   - 点击后显示同步结果（成功/失败+错误信息）
+
+2. **同步状态展示** — 调用 `GET /admin/team-report/{orderId}`
+   - 已同步：显示 syncStatus + platformStatusText
+   - 未同步：不展示
+
+3. **「刷新状态」按钮** — 调用 `GET /admin/team-report/status/{orderId}`
+
+4. **「取消团队」按钮** — 调用 `POST /admin/team-report/cancel { orderId }`
+
+---
+
+## DDL
+
+部署前需在 hl_order_service 库执行:
+```sql
+-- sql/team_report.sql
+```
+
+## 需重启服务
+
+- hl-order-service
+- hl-gateway