# 合同方案管理页 — 新增「附件管理」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 已上线，前端开发完直接对接即可。