# Proposal: 同步前端以支持中介黑名单详细字段和类型化模板导入

## Change ID
`sync-intermediary-frontend-with-detailed-fields`

## Summary
同步前端代码，使其与后端 API 文档中定义的中介黑名单增强功能保持一致，支持个人和机构类型的详细字段展示，以及类型化的模板下载和导入功能。

## Motivation

### 问题背景
后端已完成中介黑名单的增强（变更 `enhance-intermediary-with-detailed-fields`），新增了：
1. 个人类型的详细字段（人员类型、性别、证件类型、手机号码、微信号等）
2. 机构类型的详细字段（统一社会信用代码、主体类型、企业性质、法定代表人、股东等）
3. 分离的个人和机构导入模板下载接口
4. 分离的个人和机构导入接口

### 现状
当前前端代码 [ruoyi-ui/src/views/dpcIntermediary/index.vue](../../../../ruoyi-ui/src/views/dpcIntermediary/index.vue) 和 [ruoyi-ui/src/api/dpcIntermediary.js](../../../../ruoyi-ui/src/api/dpcIntermediary.js) 仅支持基础字段：
- 只显示核心字段（姓名/机构名称、证件号、中介类型、状态、备注）
- 只有一个通用的导入模板下载接口
- 只有一个通用的导入接口
- 详情对话框不支持根据类型显示不同字段

### 业务需求
1. 列表页面保持简洁，显示核心字段
2. 详情对话框需要根据中介类型显示不同的详细字段
3. 导入功能需要支持分别下载和导入个人/机构模板
4. 新增/编辑对话框需要支持详细字段的录入

## Scope

### 包含的功能

#### 2.1 API 接口层修改
- 添加个人中介模板下载接口调用
- 添加机构中介模板下载接口调用
- 添加个人中介数据导入接口调用
- 添加机构中介数据导入接口调用
- 保留原有通用接口以保持向后兼容

#### 2.2 列表页面修改
- 保持列表显示简洁（核心字段）
- 添加"查看详情"按钮
- 导入功能改为支持类型选择（个人/机构）

#### 2.3 详情对话框新增
- 根据中介类型动态显示不同的字段
- 个人类型显示：人员类型、人员子类型、性别、证件类型、手机号码、微信号等
- 机构类型显示：统一社会信用代码、主体类型、企业性质、法定代表人、股东等
- 支持只读模式，不提供编辑功能

#### 2.4 新增/编辑对话框增强
- 根据中介类型显示对应的字段组
- 个人类型显示个人相关字段
- 机构类型显示机构相关字段
- 使用表单验证确保数据完整性

### 明确排除
- 后端代码修改（已在 `enhance-intermediary-with-detailed-fields` 中完成）
- 数据库结构修改（已在 `enhance-intermediary-with-detailed-fields` 中完成）
- 路由和菜单配置修改（保持现有配置）

## Proposed Design
详见 [design.md](./design.md)

## Alternatives Considered

### 选项1：在列表中展开显示所有字段
**优点**：
- 用户无需点击详情即可看到完整信息

**缺点**：
- 列表过于拥挤，不利于快速浏览
- 个人和机构字段混杂，难以阅读

**决定**：不采用。保持列表简洁，详情通过对话框展示。

### 选项2：使用两个独立的页面（个人列表和机构列表）
**优点**：
- 页面结构清晰，各自独立

**缺点**：
- 需要添加新的路由和菜单配置
- 代码重复度高
- 不符合单一数据源的管理模式

**决定**：不采用。使用同一个列表页面，通过中介类型区分。

### 选项3：在现有对话框中内嵌详情视图
**优点**：
- 减少对话框数量

**缺点**：
- 编辑和查看模式混合，逻辑复杂
- 表单验证逻辑难以处理

**决定**：不采用。分离详情对话框和编辑对话框，职责更清晰。

## Impact

### 前端影响

#### API 层
- 新增 4 个接口调用函数（模板下载 × 2，数据导入 × 2）
- 修改导入对话框以支持类型选择

#### 视图层
- 新增详情对话框组件
- 修改列表操作列（添加"查看详情"按钮）
- 修改新增/编辑对话框（添加详细字段）
- 修改导入对话框（支持类型选择和对应的模板下载）

#### 数据流
- 详情接口返回的数据结构根据类型不同
- 表单提交需要包含对应类型的字段

### 用户体验影响
- **正面**：可以看到更完整的中介信息
- **正面**：导入模板更符合实际需求，减少录入错误
- **中性**：导入时需要先选择类型，增加一步操作

## Dependencies
- 依赖后端变更 `enhance-intermediary-with-detailed-fields` 必须先完成
- 依赖后端 API 接口按 [doc/中介黑名单管理API文档.md](../../../../doc/中介黑名单管理API文档.md) 定义实现

## Related Changes
- `enhance-intermediary-with-detailed-fields` - 后端增强功能

## Open Questions

1. **详情对话框是否支持编辑？**
   - 建议：不支持编辑，只做展示。编辑使用现有的编辑对话框。

2. **新增/编辑对话框如何处理大量字段？**
   - 建议：使用 el-tabs 或 el-row/el-col 分组展示，提高可读性。

3. **导入时是否需要类型验证？**
   - 建议：在后端验证，前端只负责选择正确的模板和接口。

4. **旧数据的详情如何处理？**
   - 建议：旧数据没有详细字段，详情对话框显示空值或占位符（如"未填写"）。

## Success Criteria
- [ ] API 接口层添加新的接口调用函数
- [ ] 列表页面添加"查看详情"按钮
- [ ] 详情对话框根据类型正确显示不同字段
- [ ] 新增/编辑对话框支持详细字段录入
- [ ] 导入功能支持个人/机构类型选择
- [ ] 可以下载个人中介专用模板
- [ ] 可以下载机构中介专用模板
- [ ] 可以使用个人模板导入数据
- [ ] 可以使用机构模板导入数据
- [ ] 现有功能保持正常运行

## References
- [doc/中介黑名单管理API文档.md](../../../../doc/中介黑名单管理API文档.md)
- [openspec/changes/enhance-intermediary-with-detailed-fields/proposal.md](../enhance-intermediary-with-detailed-fields/proposal.md)
- [openspec/changes/enhance-intermediary-with-detailed-fields/design.md](../enhance-intermediary-with-detailed-fields/design.md)
