wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
ccdi/doc/requirements/plans/2026-02-05-中介黑名单前端适配APIv2.0重构设计.md
wkc 02249c402e 文件夹整理
2026-02-09 14:28:25 +08:00

18 KiB
Raw Permalink Blame History

中介黑名单前端适配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

新增接口

// 查询个人中介详情
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'
  })
}

删除接口

// 删除以下旧版统一接口
// getIntermediary(intermediaryId)
// addIntermediary(data)
// updateIntermediary(data)

五、主页面修改详情

5.1 index.vue - 数据模型

queryParams修改

queryParams: {
  pageNum: 1,
  pageSize: 10,
  name: null,
  certificateNo: null,  // 保持不变(API查询参数兼容)
  intermediaryType: null,
  status: null
}

form数据模型

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

handleSelectionChange(selection) {
  this.ids = selection.map(item => item.bizId);  // 原 intermediaryId
  this.single = selection.length !== 1;
  this.multiple = !selection.length;
}

handleDetail

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

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

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

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属性

isAddMode() {
  return !this.form || !this.form.bizId;  // 原 intermediaryId
}

initDialogState方法

const isAdd = !this.form || !this.form.bizId;  // 原 intermediaryId

删除方法

删除handleCertificateNoChange方法(v2.0无需字段同步)

验证规则修改

个人中介:

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" }
  ]
}

实体中介:

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 核心字段修改

<!-- 业务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修正

错误代码:

this.download('dpc/intermediary/importPersonTemplate', ...)
this.download('dpc/intermediary/importEntityTemplate', ...)

修正为:

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 新增下拉框

法定代表人证件类型 (实体中介表单)

<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: 相关文档

附录B: 变更历史

版本 日期 作者 变更说明
v1.0 2026-02-05 Claude 初始版本,完成前端适配设计

附录C: 审批记录

角色 姓名 审批状态 日期
开发 - 待审批 -
测试 - 待审批 -
产品 - 待审批 -
Reference in New Issue View Git Blame Copy Permalink