6.1 KiB
6.1 KiB
Proposal: 同步前端以支持中介黑名单详细字段和类型化模板导入
Change ID
sync-intermediary-frontend-with-detailed-fields
Summary
同步前端代码，使其与后端 API 文档中定义的中介黑名单增强功能保持一致，支持个人和机构类型的详细字段展示，以及类型化的模板下载和导入功能。
Motivation
问题背景
后端已完成中介黑名单的增强（变更 enhance-intermediary-with-detailed-fields），新增了：
- 个人类型的详细字段（人员类型、性别、证件类型、手机号码、微信号等）
- 机构类型的详细字段（统一社会信用代码、主体类型、企业性质、法定代表人、股东等）
- 分离的个人和机构导入模板下载接口
- 分离的个人和机构导入接口
现状
当前前端代码 ruoyi-ui/src/views/dpcIntermediary/index.vue 和 ruoyi-ui/src/api/dpcIntermediary.js 仅支持基础字段：
- 只显示核心字段（姓名/机构名称、证件号、中介类型、状态、备注）
- 只有一个通用的导入模板下载接口
- 只有一个通用的导入接口
- 详情对话框不支持根据类型显示不同字段
业务需求
- 列表页面保持简洁，显示核心字段
- 详情对话框需要根据中介类型显示不同的详细字段
- 导入功能需要支持分别下载和导入个人/机构模板
- 新增/编辑对话框需要支持详细字段的录入
Scope
包含的功能
2.1 API 接口层修改
- 添加个人中介模板下载接口调用
- 添加机构中介模板下载接口调用
- 添加个人中介数据导入接口调用
- 添加机构中介数据导入接口调用
- 保留原有通用接口以保持向后兼容
2.2 列表页面修改
- 保持列表显示简洁（核心字段）
- 添加"查看详情"按钮
- 导入功能改为支持类型选择（个人/机构）
2.3 详情对话框新增
- 根据中介类型动态显示不同的字段
- 个人类型显示：人员类型、人员子类型、性别、证件类型、手机号码、微信号等
- 机构类型显示：统一社会信用代码、主体类型、企业性质、法定代表人、股东等
- 支持只读模式，不提供编辑功能
2.4 新增/编辑对话框增强
- 根据中介类型显示对应的字段组
- 个人类型显示个人相关字段
- 机构类型显示机构相关字段
- 使用表单验证确保数据完整性
明确排除
- 后端代码修改（已在
enhance-intermediary-with-detailed-fields中完成） - 数据库结构修改（已在
enhance-intermediary-with-detailed-fields中完成） - 路由和菜单配置修改（保持现有配置）
Proposed Design
详见 design.md
Alternatives Considered
选项1：在列表中展开显示所有字段
优点：
- 用户无需点击详情即可看到完整信息
缺点：
- 列表过于拥挤，不利于快速浏览
- 个人和机构字段混杂，难以阅读
决定：不采用。保持列表简洁，详情通过对话框展示。
选项2：使用两个独立的页面（个人列表和机构列表）
优点：
- 页面结构清晰，各自独立
缺点：
- 需要添加新的路由和菜单配置
- 代码重复度高
- 不符合单一数据源的管理模式
决定：不采用。使用同一个列表页面，通过中介类型区分。
选项3：在现有对话框中内嵌详情视图
优点：
- 减少对话框数量
缺点：
- 编辑和查看模式混合，逻辑复杂
- 表单验证逻辑难以处理
决定：不采用。分离详情对话框和编辑对话框，职责更清晰。
Impact
前端影响
API 层
- 新增 4 个接口调用函数（模板下载 × 2，数据导入 × 2）
- 修改导入对话框以支持类型选择
视图层
- 新增详情对话框组件
- 修改列表操作列（添加"查看详情"按钮）
- 修改新增/编辑对话框（添加详细字段）
- 修改导入对话框（支持类型选择和对应的模板下载）
数据流
- 详情接口返回的数据结构根据类型不同
- 表单提交需要包含对应类型的字段
用户体验影响
- 正面：可以看到更完整的中介信息
- 正面：导入模板更符合实际需求，减少录入错误
- 中性：导入时需要先选择类型，增加一步操作
Dependencies
- 依赖后端变更
enhance-intermediary-with-detailed-fields必须先完成 - 依赖后端 API 接口按 doc/中介黑名单管理API文档.md 定义实现
Related Changes
enhance-intermediary-with-detailed-fields- 后端增强功能
Open Questions
-
详情对话框是否支持编辑？
- 建议：不支持编辑，只做展示。编辑使用现有的编辑对话框。
-
新增/编辑对话框如何处理大量字段？
- 建议：使用 el-tabs 或 el-row/el-col 分组展示，提高可读性。
-
导入时是否需要类型验证？
- 建议：在后端验证，前端只负责选择正确的模板和接口。
-
旧数据的详情如何处理？
- 建议：旧数据没有详细字段，详情对话框显示空值或占位符（如"未填写"）。
Success Criteria
- API 接口层添加新的接口调用函数
- 列表页面添加"查看详情"按钮
- 详情对话框根据类型正确显示不同字段
- 新增/编辑对话框支持详细字段录入
- 导入功能支持个人/机构类型选择
- 可以下载个人中介专用模板
- 可以下载机构中介专用模板
- 可以使用个人模板导入数据
- 可以使用机构模板导入数据
- 现有功能保持正常运行