feat(contract): 拆分 12301 合同方案 changelog 为 3 份独立文档(附件 Tab/导游 Tab/出行人字段) - 前端 mmg 重新阅读

2026-05-01 15:51:00 +08:00
@@ -0,0 +1,132 @@
+# 合同方案管理页 — 新增「附件管理」Tab
+
+**类型**: 后端新接口
+**前端处理者**: mmg
+**日期**: 2026-05-01
+**关联**: 工单 #1590 / PR #1592 #1594
+**影响页面**: 管理后台「合同管理 → 合同方案 → 编辑方案」
+
+---
+
+## 这是什么
+
+合同方案现在可以挂附件（PDF/图片）。生成 12301 合同时，方案附件会**自动作为合同附件嵌入**到 12301 平台合同 PDF 中。
+
+**用途举例**：
+- 旅行社服务标准 PDF
+- 公司资质照片
+- 安全告知补充说明
+- 任何需要随合同长期出现的材料
+
+**业务规则**：方案上传几个附件，生成合同时就嵌入几个，不需要每个订单单独传。
+
+---
+
+## UI 需求
+
+在合同方案编辑页（路由类似 `/admin/contract/scheme/edit/:id`）加一个 **「附件管理」Tab**，里面：
+
+1. **附件列表表格**：
+   - 列：文件名 / 类型 / 大小 / 排序号 / 创建时间 / 操作
+   - 操作：下载（`ossUrl`）/ 调整排序号 / 删除
+
+2. **上传按钮**：
+   - 点击 → 弹窗
+   - 表单字段：
+     - 文件（必填，accept=`.pdf,.jpg,.jpeg,.png`，限 10MB）
+     - 文件类型（下拉：PDF / 图片 / 其他）
+     - 排序号（数字，默认 0，越小越前）
+   - 提交 → multipart 上传
+
+3. **删除二次确认**：删后从列表移除
+
+---
+
+## 接口
+
+**Base path**: `/admin/contract/scheme/{schemeId}/attachments`
+
+### 1. 查询附件列表
+
+```
+GET /admin/contract/scheme/{schemeId}/attachments
+Authorization: Bearer <admin_token>
+
+→ 200
+{
+  "code": 200,
+  "data": [
+    {
+      "attachmentId": "2049914870366703618",   // String 雪花
+      "schemeId": 3,
+      "fileName": "服务标准.pdf",
+      "ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/scheme-attachment/2026-05/3_xxx.pdf",
+      "fileSize": 102400,                       // 字节数
+      "fileType": "PDF",                        // PDF / IMAGE / OTHER
+      "sortOrder": 10,
+      "createTime": "2026-05-01 10:12:45"
+    }
+  ]
+}
+```
+
+### 2. 上传新附件（multipart/form-data）
+
+```
+POST /admin/contract/scheme/{schemeId}/attachments
+Authorization: Bearer <admin_token>
+Content-Type: multipart/form-data
+
+form-data:
+  file:        <File 二进制>           (必填, ≤10MB)
+  fileType:    "PDF"                   (必填, 字典 PDF / IMAGE / OTHER)
+  sortOrder:   10                      (选填, 默认 0)
+
+→ 200
+{
+  "code": 200,
+  "data": { ...同上单条结构, 含新生成 attachmentId 和 ossUrl... }
+}
+```
+
+### 3. 调整排序
+
+```
+PUT /admin/contract/scheme/{schemeId}/attachments/{attachmentId}/sort
+Content-Type: application/json
+{ "sortOrder": 20 }
+
+→ 200 { "code": 200, "data": null }
+```
+
+### 4. 删除附件（软删除）
+
+```
+DELETE /admin/contract/scheme/{schemeId}/attachments/{attachmentId}
+
+→ 200 { "code": 200, "data": null }
+```
+
+---
+
+## 字段字典
+
+`fileType` 字典 `contract_attachment_type`:
+
+| 字典 value | 显示名 |
+|-----------|------|
+| PDF | PDF 文档 |
+| IMAGE | 图片 |
+| OTHER | 其他 |
+
+---
+
+## 测试服已就绪
+
+可以现在直接调测试服 (`https://api.test.1814.love:9443`) 的 GET 端点验证（schemeId=3 是测试数据）。
+
+---
+
+## 服务重启
+
+后端 hl-order-service-v2 已上线，前端开发完直接对接即可。