160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# 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)
|