中介黑名单更新

2026-02-05 13:33:27 +08:00
parent 1af2677c05
commit 81d4038302
48 changed files with 2789 additions and 1312 deletions
--- a/doc/plans/2026-02-05-中介黑名单前端适配APIv2.0重构设计.md
+++ b/doc/plans/2026-02-05-中介黑名单前端适配APIv2.0重构设计.md
@@ -0,0 +1,642 @@
+# 中介黑名单前端适配API v2.0重构设计文档
+
+**文档版本**: v1.0
+**创建日期**: 2026-02-05
+**设计目标**: 将前端字段完全对齐API v2.0规范,实现前后端字段名一致
+
+---
+
+## 一、变更背景
+
+### 1.1 API v2.0核心变更
+
+后端API已升级至v2.0版本,主要变更包括:
+
+- **统一业务ID**: 使用`bizId`替代`intermediaryId`作为主键
+- **接口分离**: 个人和实体中介使用独立的详情查询接口
+- **字段规范化**: 统一字段命名规范,消除歧义
+- **DTO/VO分离**: 请求和响应对象完全分离
+
+### 1.2 重构目标
+
+1. **字段名对齐**: 前端表单字段与API请求字段完全一致
+2. **消除映射**: 移除前后端字段名转换逻辑
+3. **代码简化**: 降低维护成本,提升可读性
+4. **类型安全**: 确保个人和实体中介字段正确隔离
+
+---
+
+## 二、字段映射方案
+
+### 2.1 个人中介字段映射
+
+| 旧前端字段 | API v2.0字段 | 说明 |
+|-----------|-------------|------|
+| intermediaryId | bizId | 主键ID |
+| certificateNo | personId | 证件号码 |
+| indivType | personType | 人员类型 |
+| indivSubType | personSubType | 人员子类型 |
+| indivGender | gender | 性别 |
+| indivCertType | idType | 证件类型 |
+| indivPhone | mobile | 手机号码 |
+| indivWechat | wechatNo | 微信号 |
+| indivAddress | contactAddress | 联系地址 |
+| indivCompany | company | 所在公司 |
+| indivPosition | position | 职位 |
+| indivRelatedId | relatedNumId | 关联人员ID |
+| indivRelation | relationType | 关系类型 |
+
+**保持不变的字段:**
+- name (姓名)
+- remark (备注)
+- intermediaryType (中介类型)
+- status (状态)
+
+### 2.2 实体中介字段映射
+
+| 旧前端字段 | API v2.0字段 | 说明 |
+|-----------|-------------|------|
+| intermediaryId | bizId | 主键ID |
+| name | enterpriseName | 机构名称 |
+| certificateNo / corpCreditCode | socialCreditCode | 统一社会信用代码 |
+| corpType | enterpriseType | 主体类型 |
+| corpNature | enterpriseNature | 企业性质 |
+| corpIndustryCategory | industryClass | 行业分类 |
+| corpIndustry | industryName | 所属行业 |
+| corpEstablishDate | establishDate | 成立日期 |
+| corpAddress | registerAddress | 注册地址 |
+| corpLegalRep | legalRepresentative | 法定代表人 |
+| corpLegalCertType | legalCertType | 法定代表人证件类型 |
+| corpLegalCertNo | legalCertNo | 法定代表人证件号码 |
+| corpShareholder1-5 | shareholder1-5 | 股东信息(1-5) |
+
+**保持不变的字段:**
+- remark (备注)
+- intermediaryType (中介类型)
+- status (状态)
+
+---
+
+## 三、文件修改清单
+
+### 3.1 需要修改的文件
+
+| 序号 | 文件路径 | 修改类型 | 优先级 |
+|-----|---------|---------|-------|
+| 1 | `ruoyi-ui/src/api/ccdiIntermediary.js` | API层 | P0 |
+| 2 | `ruoyi-ui/src/views/ccdiIntermediary/index.vue` | 主页面 | P0 |
+| 3 | `ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue` | 编辑组件 | P0 |
+| 4 | `ruoyi-ui/src/views/ccdiIntermediary/components/DetailDialog.vue` | 详情组件 | P1 |
+| 5 | `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue` | 导入组件 | P1 |
+
+### 3.2 无需修改的文件
+
+| 序号 | 文件路径 | 原因 |
+|-----|---------|------|
+| 1 | `SearchForm.vue` | 查询参数与API兼容 |
+| 2 | `DataTable.vue` | 已使用友好名称字段 |
+
+---
+
+## 四、API层修改详情
+
+### 4.1 ccdiIntermediary.js
+
+#### 新增接口
+
+```javascript
+// 查询个人中介详情
+export function getPersonIntermediary(bizId) {
+  return request({
+    url: '/ccdi/intermediary/person/' + bizId,
+    method: 'get'
+  })
+}
+
+// 查询实体中介详情
+export function getEntityIntermediary(socialCreditCode) {
+  return request({
+    url: '/ccdi/intermediary/entity/' + socialCreditCode,
+    method: 'get'
+  })
+}
+```
+
+#### 删除接口
+
+```javascript
+// 删除以下旧版统一接口
+// getIntermediary(intermediaryId)
+// addIntermediary(data)
+// updateIntermediary(data)
+```
+
+---
+
+## 五、主页面修改详情
+
+### 5.1 index.vue - 数据模型
+
+#### queryParams修改
+
+```javascript
+queryParams: {
+  pageNum: 1,
+  pageSize: 10,
+  name: null,
+  certificateNo: null,  // 保持不变(API查询参数兼容)
+  intermediaryType: null,
+  status: null
+}
+```
+
+#### form数据模型
+
+```javascript
+form: {
+  // 通用字段
+  bizId: null,  // 原 intermediaryId
+  intermediaryType: '1',
+  status: '0',
+  remark: null,
+
+  // 个人中介字段
+  name: null,
+  personId: null,  // 原 certificateNo
+  personType: null,  // 原 indivType
+  personSubType: null,  // 原 indivSubType
+  relationType: null,  // 原 indivRelation
+  gender: null,  // 原 indivGender
+  idType: null,  // 原 indivCertType
+  mobile: null,  // 原 indivPhone
+  wechatNo: null,  // 原 indivWechat
+  contactAddress: null,  // 原 indivAddress
+  company: null,  // 原 indivCompany
+  socialCreditCode: null,  // 新增
+  position: null,  // 原 indivPosition
+  relatedNumId: null,  // 原 indivRelatedId
+
+  // 实体中介字段
+  enterpriseName: null,  // 原 name
+  socialCreditCode: null,  // 原 certificateNo/corpCreditCode
+  enterpriseType: null,  // 原 corpType
+  enterpriseNature: null,  // 原 corpNature
+  industryClass: null,  // 原 corpIndustryCategory
+  industryName: null,  // 原 corpIndustry
+  establishDate: null,  // 原 corpEstablishDate
+  registerAddress: null,  // 原 corpAddress
+  legalRepresentative: null,  // 原 corpLegalRep
+  legalCertType: null,  // 原 corpLegalCertType
+  legalCertNo: null,  // 原 corpLegalCertNo
+  shareholder1: null,  // 原 corpShareholder1
+  shareholder2: null,  // 原 corpShareholder2
+  shareholder3: null,  // 原 corpShareholder3
+  shareholder4: null,  // 原 corpShareholder4
+  shareholder5: null   // 原 corpShareholder5
+}
+```
+
+### 5.2 核心方法修改
+
+#### handleSelectionChange
+
+```javascript
+handleSelectionChange(selection) {
+  this.ids = selection.map(item => item.bizId);  // 原 intermediaryId
+  this.single = selection.length !== 1;
+  this.multiple = !selection.length;
+}
+```
+
+#### handleDetail
+
+```javascript
+handleDetail(row) {
+  if (row.intermediaryType === '1') {
+    // 个人中介
+    getPersonIntermediary(row.bizId).then(response => {
+      this.detailData = response.data;
+      this.detailOpen = true;
+    });
+  } else {
+    // 实体中介
+    getEntityIntermediary(row.socialCreditCode).then(response => {
+      this.detailData = response.data;
+      this.detailOpen = true;
+    });
+  }
+}
+```
+
+#### handleUpdate
+
+```javascript
+handleUpdate(row) {
+  this.reset();
+  if (row.intermediaryType === '1') {
+    getPersonIntermediary(row.bizId).then(response => {
+      this.form = response.data;
+      this.open = true;
+      this.title = "修改中介黑名单";
+    });
+  } else {
+    getEntityIntermediary(row.socialCreditCode).then(response => {
+      this.form = response.data;
+      this.open = true;
+      this.title = "修改中介黑名单";
+    });
+  }
+}
+```
+
+#### submitForm
+
+```javascript
+submitForm() {
+  if (this.form.bizId != null) {  // 原 intermediaryId
+    // 修改模式
+    if (this.form.intermediaryType === '1') {
+      updatePersonIntermediary(this.form).then(response => {
+        this.$modal.msgSuccess("修改成功");
+        this.open = false;
+        this.getList();
+      });
+    } else {
+      updateEntityIntermediary(this.form).then(response => {
+        this.$modal.msgSuccess("修改成功");
+        this.open = false;
+        this.getList();
+      });
+    }
+  } else {
+    // 新增模式
+    if (this.form.intermediaryType === '1') {
+      addPersonIntermediary(this.form).then(response => {
+        this.$modal.msgSuccess("新增成功");
+        this.open = false;
+        this.getList();
+      });
+    } else {
+      addEntityIntermediary(this.form).then(response => {
+        this.$modal.msgSuccess("新增成功");
+        this.open = false;
+        this.getList();
+      });
+    }
+  }
+}
+```
+
+#### handleDelete
+
+```javascript
+handleDelete(row) {
+  const bizIds = row.bizId || this.ids.join(',');  // 原 intermediaryIds
+  this.$modal.confirm('是否确认删除中介黑名单编号为"' + bizIds + '"的数据项？')
+    .then(function() {
+      return delIntermediary(bizIds);
+    }).then(() => {
+      this.getList();
+      this.$modal.msgSuccess("删除成功");
+    }).catch(() => {});
+}
+```
+
+---
+
+## 六、EditDialog组件修改详情
+
+### 6.1 个人中介表单字段修改
+
+| 行号 | 修改内容 |
+|-----|---------|
+| 46 | `form.certificateNo` → `form.personId` |
+| 54 | `form.indivType` → `form.personType` |
+| 66 | `form.indivSubType` → `form.personSubType` |
+| 80 | `form.indivGender` → `form.gender` |
+| 92 | `form.indivCertType` → `form.idType` |
+| 106 | `form.indivPhone` → `form.mobile` |
+| 110 | `form.indivWechat` → `form.wechatNo` |
+| 116 | `form.indivAddress` → `form.contactAddress` |
+| 121 | `form.indivCompany` → `form.company` |
+| 126 | `form.indivPosition` → `form.position` |
+| 133 | `form.indivRelatedId` → `form.relatedNumId` |
+| 138 | `form.indivRelation` → `form.relationType` |
+
+### 6.2 实体中介表单字段修改
+
+| 行号 | 修改内容 |
+|-----|---------|
+| 172 | `form.name` → `form.enterpriseName` |
+| 179 | `form.certificateNo` → `form.socialCreditCode` |
+| 190 | `form.corpType` → `form.enterpriseType` |
+| 202 | `form.corpNature` → `form.enterpriseNature` |
+| 227 | `form.corpIndustryCategory` → `form.industryClass` |
+| 234 | `form.corpIndustry` → `form.industryName` |
+| 217 | `form.corpEstablishDate` → `form.establishDate` |
+| 239 | `form.corpAddress` → `form.registerAddress` |
+| 244 | `form.corpLegalRep` → `form.legalRepresentative` |
+| 249-251 | 添加下拉框:`form.legalCertType` (证件类型) |
+| 254 | `form.corpLegalCertNo` → `form.legalCertNo` |
+| 260-284 | `form.corpShareholder1-5` → `form.shareholder1-5` |
+
+### 6.3 Script部分修改
+
+#### computed属性
+
+```javascript
+isAddMode() {
+  return !this.form || !this.form.bizId;  // 原 intermediaryId
+}
+```
+
+#### initDialogState方法
+
+```javascript
+const isAdd = !this.form || !this.form.bizId;  // 原 intermediaryId
+```
+
+#### 删除方法
+
+删除`handleCertificateNoChange`方法(v2.0无需字段同步)
+
+#### 验证规则修改
+
+**个人中介:**
+
+```javascript
+indivRules: {
+  name: [
+    { required: true, message: "姓名不能为空", trigger: "blur" },
+    { max: 100, message: "姓名长度不能超过100个字符", trigger: "blur" }
+  ],
+  personId: [  // 原 certificateNo
+    { required: true, message: "证件号不能为空", trigger: "blur" },
+    { max: 50, message: "证件号长度不能超过50个字符", trigger: "blur" }
+  ],
+  remark: [
+    { max: 500, message: "备注长度不能超过500个字符", trigger: "blur" }
+  ]
+}
+```
+
+**实体中介:**
+
+```javascript
+corpRules: {
+  enterpriseName: [  // 原 name
+    { required: true, message: "机构名称不能为空", trigger: "blur" },
+    { max: 200, message: "机构名称长度不能超过200个字符", trigger: "blur" }
+  ],
+  socialCreditCode: [  // 原 certificateNo
+    { required: true, message: "统一社会信用代码不能为空", trigger: "blur" },
+    { max: 50, message: "统一社会信用代码长度不能超过50个字符", trigger: "blur" }
+  ],
+  remark: [
+    { max: 500, message: "备注长度不能超过500个字符", trigger: "blur" }
+  ]
+}
+```
+
+---
+
+## 七、DetailDialog组件修改详情
+
+### 7.1 核心字段修改
+
+```vue
+<!-- 业务ID -->
+<el-descriptions-item label="业务ID">{{ detailData.bizId }}</el-descriptions-item>
+
+<!-- 证件号/信用代码 -->
+<el-descriptions-item label="证件号/信用代码">
+  <span v-if="detailData.intermediaryType === '1'">{{ detailData.personId || '-' }}</span>
+  <span v-else>{{ detailData.socialCreditCode || '-' }}</span>
+</el-descriptions-item>
+```
+
+### 7.2 个人中介字段修改
+
+| 旧字段 | 新字段 |
+|--------|--------|
+| detailData.indivType | detailData.personType |
+| detailData.indivSubType | detailData.personSubType |
+| detailData.indivGenderName | detailData.genderName |
+| detailData.indivCertType | detailData.idType |
+| detailData.indivPhone | detailData.mobile |
+| detailData.indivWechat | detailData.wechatNo |
+| detailData.indivAddress | detailData.contactAddress |
+| detailData.indivCompany | detailData.company |
+| detailData.indivPosition | detailData.position |
+| detailData.indivRelatedId | detailData.relatedNumId |
+| detailData.indivRelation | detailData.relationType |
+
+**新增字段:**
+- detailData.socialCreditCode (企业统一信用码)
+
+### 7.3 实体中介字段修改
+
+| 旧字段 | 新字段 |
+|--------|--------|
+| detailData.corpCreditCode | detailData.socialCreditCode |
+| detailData.corpType | detailData.enterpriseType |
+| detailData.corpNature | detailData.enterpriseNature |
+| detailData.corpIndustryCategory | detailData.industryClass |
+| detailData.corpIndustry | detailData.industryName |
+| detailData.corpEstablishDate | detailData.establishDate |
+| detailData.corpAddress | detailData.registerAddress |
+| detailData.corpLegalRep | detailData.legalRepresentative |
+| detailData.corpLegalCertType | detailData.legalCertType |
+| detailData.corpLegalCertNo | detailData.legalCertNo |
+| detailData.corpShareholder1-5 | detailData.shareholder1-5 |
+
+---
+
+## 八、ImportDialog组件修改详情
+
+### 8.1 模板下载URL修正
+
+**错误代码:**
+
+```javascript
+this.download('dpc/intermediary/importPersonTemplate', ...)
+this.download('dpc/intermediary/importEntityTemplate', ...)
+```
+
+**修正为:**
+
+```javascript
+handleDownloadTemplate() {
+  if (this.formData.importType === 'person') {
+    this.download('ccdi/intermediary/importPersonTemplate', {}, `个人中介黑名单模板_${new Date().getTime()}.xlsx`);
+  } else {
+    this.download('ccdi/intermediary/importEntityTemplate', {}, `机构中介黑名单模板_${new Date().getTime()}.xlsx`);
+  }
+}
+```
+
+---
+
+## 九、下拉框优化
+
+### 9.1 新增下拉框
+
+**法定代表人证件类型** (实体中介表单)
+
+```vue
+<el-form-item label="法定代表人证件类型">
+  <el-select v-model="form.legalCertType" placeholder="请选择证件类型" clearable style="width: 100%">
+    <el-option
+      v-for="item in certTypeOptions"
+      :key="item.value"
+      :label="item.label"
+      :value="item.value"
+    />
+  </el-select>
+</el-form-item>
+```
+
+### 9.2 已有下拉框验证
+
+- ✅ 性别 (genderOptions)
+- ✅ 证件类型 (certTypeOptions)
+- ✅ 主体类型 (corpTypeOptions)
+- ✅ 企业性质 (corpNatureOptions)
+- ✅ 人员类型 (indivTypeOptions)
+- ✅ 人员子类型 (indivSubTypeOptions)
+- ✅ 关联关系 (relationTypeOptions)
+
+---
+
+## 十、测试计划
+
+### 10.1 功能测试清单
+
+**查询功能:**
+- [ ] 列表查询正常显示
+- [ ] 按姓名/机构名称模糊查询
+- [ ] 按证件号精确查询
+- [ ] 按中介类型筛选(个人/机构)
+- [ ] 分页功能正常
+
+**个人中介CRUD:**
+- [ ] 新增个人中介 - 所有字段保存成功
+- [ ] 查看个人中介详情 - 所有字段正确显示
+- [ ] 修改个人中介 - 数据更新成功
+- [ ] 删除个人中介 - 删除成功
+
+**机构中介CRUD:**
+- [ ] 新增机构中介 - 所有字段保存成功
+- [ ] 查看机构中介详情 - 所有字段正确显示
+- [ ] 修改机构中介 - 数据更新成功
+- [ ] 删除机构中介 - 删除成功
+
+**导入功能:**
+- [ ] 下载个人中介导入模板成功
+- [ ] 下载机构中介导入模板成功
+- [ ] 个人中介数据导入成功
+- [ ] 机构中介数据导入成功
+- [ ] 导入时更新已存在数据功能正常
+
+**下拉框验证:**
+- [ ] 性别下拉框显示正确
+- [ ] 证件类型下拉框显示正确
+- [ ] 法定代表人证件类型下拉框显示正确
+- [ ] 主体类型下拉框显示正确
+- [ ] 企业性质下拉框显示正确
+
+### 10.2 回归测试
+
+- [ ] 权限控制正常
+- [ ] 表单验证规则生效
+- [ ] 错误提示信息正确
+- [ ] 响应式布局正常
+- [ ] 浏览器兼容性(Chrome/Firefox/Edge)
+
+---
+
+## 十一、风险与注意事项
+
+### 11.1 兼容性风险
+
+**影响范围**: 所有中介黑名单相关功能
+
+**缓解措施**:
+1. 完整的功能测试覆盖
+2. 保留旧版代码备份
+3. 分步骤部署,先测试环境验证
+
+### 11.2 数据风险
+
+**风险点**: 字段名变更可能导致数据丢失
+
+**缓解措施**:
+1. 确保后端已做好兼容处理
+2. 导出测试数据进行对比验证
+3. 增量导入测试
+
+### 11.3 注意事项
+
+1. **字段同步**: 确保前后端字段完全一致,不要遗留转换逻辑
+2. **类型判断**: 所有详情查询必须根据`intermediaryType`调用不同接口
+3. **验证规则**: 个人和实体中介的必填字段不同,需分别配置
+4. **下拉框复用**: 法定代表人证件类型可复用`certTypeOptions`
+
+---
+
+## 十二、实施建议
+
+### 12.1 实施步骤
+
+1. **第一阶段**: API层修改
+   - 新增详情查询接口
+   - 删除旧版统一接口
+   - 验证接口调用正常
+
+2. **第二阶段**: 主页面修改
+   - 修改数据模型
+   - 修改核心方法
+   - 测试查询和删除功能
+
+3. **第三阶段**: 组件修改
+   - EditDialog组件字段重命名
+   - DetailDialog组件字段重命名
+   - ImportDialog组件URL修正
+   - 测试新增和修改功能
+
+4. **第四阶段**: 全面测试
+   - 功能测试
+   - 回归测试
+   - 兼容性测试
+
+### 12.2 回滚方案
+
+如发现问题严重,可按以下步骤回滚:
+
+1. 恢复API层接口
+2. 恢复前端文件备份
+3. 重启前端服务
+4. 清理浏览器缓存
+
+---
+
+## 附录
+
+### 附录A: 相关文档
+
+- [中介黑名单管理API文档-v2.0.md](../api/中介黑名单管理API文档-v2.0.md)
+- [中介黑名单后端设计文档.md](../docs/中介黑名单后端.md)
+
+### 附录B: 变更历史
+
+| 版本 | 日期 | 作者 | 变更说明 |
+|-----|------|------|---------|
+| v1.0 | 2026-02-05 | Claude | 初始版本,完成前端适配设计 |
+
+### 附录C: 审批记录
+
+| 角色 | 姓名 | 审批状态 | 日期 |
+|-----|------|---------|------|
+| 开发 | - | 待审批 | - |
+| 测试 | - | 待审批 | - |
+| 产品 | - | 待审批 | - |