frontend: 合同方案编辑页加附件+导游管理 UI 待办 (Issue #1637)

changelogs/2026-05/04_frontend_contract_scheme_attachment_ui_pending.md

@@ -0,0 +1,107 @@
+# 前端待办: 合同方案编辑页加附件管理 + 导游管理 UI
+
+> 📌 **状态**: 后端 API 已就绪(2026-05-01), 前端 mmg 待对接
+> **触发**: 2026-05-04 用户截图反馈"合同方案中可以上传附件咋没有呢"
+> **关联工单**: #1637
+
+**类型**: 前端待开发
+**前端处理者**: mmg
+**日期**: 2026-05-04
+**关联**: 工单 #1637 / PR #1592 #1594
+
+---
+
+## 现状
+
+用户截图(/contract/scheme 编辑合同方案弹窗)里只有方案名称/描述/平台/模板/签约模式/签署模式/旅行社/争议解决方式/管辖法院/补充条款/经办人姓名/经办人电话/排序 13 个字段, **没有附件上传 + 导游管理入口**。
+
+## 后端 API 已就绪
+
+测试服直接可调用, schemeId=3 已有真实数据(1 条附件 + 1 条导游)。
+
+### 附件管理 API
+
+```
+GET    /admin/contract/scheme/{schemeId}/attachments         查询列表
+POST   /admin/contract/scheme/{schemeId}/attachments         上传(multipart: file, fileType, sortOrder)
+PUT    /admin/contract/scheme/{schemeId}/attachments/{id}/sort 调排序
+DELETE /admin/contract/scheme/{schemeId}/attachments/{id}    删除
+```
+
+详细字段定义见 changelog: `2026-05/01_feat_contract_scheme_attachments_tab.md`
+
+### 导游管理 API
+
+```
+GET    /admin/contract/scheme/{schemeId}/tour-guides         查询列表
+POST   /admin/contract/scheme/{schemeId}/tour-guides         新增
+PUT    /admin/contract/scheme/{schemeId}/tour-guides/{id}    修改
+DELETE /admin/contract/scheme/{schemeId}/tour-guides/{id}    删除
+```
+
+详细字段定义见: `2026-05/01_feat_contract_scheme_tour_guides_tab.md`
+
+---
+
+## UI 实现建议(mmg 选一种)
+
+### 推荐: 方案 A - 列表页每行操作按钮 + 独立 Dialog/Drawer
+
+合同方案列表页 `/contract/scheme` 表格每行**操作列**加 2 个按钮:
+
+```
+| 方案名称  | 平台   | 模板    | ... | 操作                                |
+|----------|--------|---------|-----|-------------------------------------|
+| 全国旅游 | 12301  | A00001  | ... | 编辑 / 附件管理 / 导游 / 启停 / 删除 |
+```
+
+点击 "附件管理" → 弹独立 `<el-dialog>` 或 `<el-drawer>`:
+- 顶部: "上传附件" 按钮 (multipart 上传)
+- 中部: 附件列表表格 (fileName / fileType / fileSize / 排序 / 操作[下载/调排序/删除])
+- 不分页(单方案附件数量小)
+
+点击 "导游管理" → 同形 dialog/drawer:
+- 顶部: "新增导游" 按钮 → 表单弹窗(姓名/手机/导游证号/排序)
+- 中部: 导游列表表格 (name / phone / licenseNumber / 排序 / 操作[编辑/删除])
+
+### 备选: 方案 B - 编辑弹窗下方加折叠面板
+
+如果不想动列表页布局, 编辑合同方案弹窗 `<el-dialog>` 内容区下方加 2 个 `<el-collapse>`:
+
+```
+[原有方案表单字段]
+─────────
++ 附件管理 (折叠)   ← 点开后展开附件 CRUD UI
++ 导游管理 (折叠)   ← 点开后展开导游 CRUD UI
+─────────
+[取消] [保存]
+```
+
+注意: 弹窗会变很高, 建议加最大高度 + 内部滚动。
+
+### 不推荐: 方案 C - 跳详情页
+
+保存方案后跳合同方案详情页, Tab 布局(信息 / 附件 / 导游)。**对现有列表页直接编辑流程改动大, 不推荐。**
+
+---
+
+## 测试服可立即对接
+
+`https://api.test.1814.love:9443/admin/contract/scheme/3/attachments` 现在有 1 条附件
+`https://api.test.1814.love:9443/admin/contract/scheme/3/tour-guides` 现在有 1 条导游
+
+前端写完 UI 直接对接 schemeId=3 验证即可。
+
+---
+
+## 业务说明给 mmg 看(为啥需要这两个 UI)
+
+1. **附件**: 12301 国家旅游服务监管平台合同上报时, attachments[] 数组节点会嵌入合同 PDF。方案下挂的附件是**长期复用模板**(如旅行社服务标准 PDF / 资质材料), 上传一次每个该方案的合同自动嵌入。**不上传也能生成合同**(后端会自动生成行程 PDF 兜底), 但建议至少上传一次资质材料。
+
+2. **导游**: 12301 合同 tourGuides[] 数组渲染合同正文导游姓名/电话/导游证号。**有导游产品才需要配**, 自驾产品 / 不带团产品空数组也能上报(用户原话"导游有的产品没有")。
+
+---
+
+## 紧急程度
+
+P1 - 不阻塞 12301 合同生成主流程(合同照常生成 + 行程 PDF 自动嵌入), 但缺这两个 UI 就无法上传方案级附件 + 配导游, 体验降级。