# 实体库管理设计文档 ## 1. 背景 当前仓库已经存在企业主体表 `ccdi_enterprise_base_info`，并且“中介管理”中的实体中介部分已经在复用该表完成部分新增、编辑、详情和导入能力。 本次需求不是新建表，也不是扩展复杂关联能力，而是基于现有企业主体表，单独建设一个“实体库管理”页面，并严格参照“员工信息维护”的实现方式交付完整的新增、查看、编辑、删除、导入能力。 ## 2. 目标 建设一套独立的“实体库管理”模块，满足以下要求： - 页面名称固定为“实体库管理” - 数据表固定为 `ccdi_enterprise_base_info` - 功能范围仅包含单表维护，不引入子表或聚合编辑 - 支持新建、查看、编辑、删除、导入 - 页面交互、接口组织、异步导入、失败记录查看方式整体对齐员工信息维护 - `riskLevel`、`entSource` 允许维护，不写死 - 导入时若统一社会信用代码已存在，一律按失败处理，不覆盖更新 ## 3. 非目标 - 不改造“中介管理”现有混合页面 - 不在本次中引入企业附属信息子表 - 不在本次中引入员工企业关系、客户企业关系、中介关系联动维护 - 不设计兼容性补丁式方案，不保留中介实体 DTO 命名给新模块复用 ## 4. 现状分析 ### 4.1 已有基础 仓库中已经存在以下可复用基础： - 实体表对应领域对象：`CcdiEnterpriseBaseInfo` - 实体表 Mapper：`CcdiEnterpriseBaseInfoMapper` - 中介模块中的实体新增、编辑、详情、导入能力 - 员工信息维护的完整单表维护范式： - 独立 Controller - 独立 DTO / VO / Excel / ImportFailureVO - 独立前端页面与 API - 异步导入状态轮询 - 失败记录分页查看 ### 4.2 已有问题 当前实体企业数据虽然已经能在中介模块中被部分维护，但存在以下问题： - 业务语义属于“中介管理”，不等于“实体库管理” - DTO / VO / Excel 命名与字段口径绑定在 `IntermediaryEntity` 语义上 - 现有实体中介字段未完整覆盖本次需要维护的 `status`、`riskLevel`、`entSource`、`dataSource` - 页面是中介混合模式，不符合“完全按照员工信息维护方式实现”的要求 因此本次应建设独立模块，而不是继续把“实体库管理”能力挂靠在中介模块之下。 ## 5. 方案比较 ### 5.1 方案一：新建独立实体库管理模块 做法： - 新建独立的后端 Controller / Service / DTO / VO / Excel / 导入服务 - 新建独立前端页面、独立 API、独立菜单和权限 - 底层复用 `ccdi_enterprise_base_info` 优点： - 与“员工信息维护”模式最一致 - 业务语义清晰，后续维护成本最低 - 不会把“实体库管理”和“中介管理”概念揉在一起 缺点： - 开发量略高于直接复用中介实体代码 ### 5.2 方案二：直接复用中介管理中的实体部分 做法： - 将中介管理中的“实体中介”能力直接暴露为实体库入口 优点： - 改动少 缺点： - 模块语义错误 - DTO / VO / 页面命名与业务不一致 - 后续权限、菜单、字段扩展容易混乱 ### 5.3 方案三：页面独立，后端继续复用中介实体 DTO / 导入类 做法： - 页面新建 - 后端尽量套用 `IntermediaryEntity` 的类和导入逻辑 优点： - 开发速度较快 缺点： - 代码命名混乱 - 字段口径不完整 - 后续扩展时会继续带来语义污染 ### 5.4 结论 采用方案一：新建独立“实体库管理”模块，底层复用 `ccdi_enterprise_base_info`，实现方式全面对齐员工信息维护。 ## 6. 总体设计 ### 6.1 模块边界 本次实体库管理模块只负责维护 `ccdi_enterprise_base_info` 单表数据，不承担其他关系表维护职责。 ### 6.2 后端结构 新增独立链路： - `CcdiEnterpriseBaseInfoController` - `ICcdiEnterpriseBaseInfoService` - `CcdiEnterpriseBaseInfoServiceImpl` - `CcdiEnterpriseBaseInfoQueryDTO` - `CcdiEnterpriseBaseInfoAddDTO` - `CcdiEnterpriseBaseInfoEditDTO` - `CcdiEnterpriseBaseInfoVO` - `CcdiEnterpriseBaseInfoExcel` - `EnterpriseBaseInfoImportFailureVO` - `ICcdiEnterpriseBaseInfoImportService` - `CcdiEnterpriseBaseInfoImportServiceImpl` Mapper 层优先复用现有 `CcdiEnterpriseBaseInfoMapper`，若分页查询或批量导入需要独立 SQL，则在现有 Mapper 基础上补充对应方法。 ### 6.3 前端结构 新增独立页面与 API： - `ruoyi-ui/src/views/ccdiEnterpriseBaseInfo/index.vue` - `ruoyi-ui/src/api/ccdiEnterpriseBaseInfo.js` 页面交互模式整体对齐员工信息维护： - 查询表单 - 工具栏按钮 - 数据表格 - 新增/编辑弹窗 - 详情弹窗 - 导入弹窗 - 导入失败记录查看 ## 7. 数据口径设计 ### 7.1 主键 主键固定为 `socialCreditCode`。 规则如下： - 新增时必填 - 编辑时不可修改 - 详情、删除、导入去重均以该字段为准 ### 7.2 维护字段 本次页面维护字段覆盖 `ccdi_enterprise_base_info` 核心单表字段： - `socialCreditCode` - `enterpriseName` - `enterpriseType` - `enterpriseNature` - `industryClass` - `industryName` - `establishDate` - `registerAddress` - `legalRepresentative` - `legalCertType` - `legalCertNo` - `shareholder1` - `shareholder2` - `shareholder3` - `shareholder4` - `shareholder5` - `status` - `riskLevel` - `entSource` - `dataSource` ### 7.3 字段策略 - `riskLevel` 允许查询、展示、编辑、导入 - `entSource` 允许查询、展示、编辑、导入 - `dataSource` 允许查询、展示、编辑、导入 - 不新增动态股东列表，继续保持 `shareholder1-5` 固定字段结构 ## 8. 页面设计 ### 8.1 查询区 查询条件按员工信息维护的密度设计，包含： - 企业名称 - 统一社会信用代码 - 企业类型 - 企业性质 - 行业分类 - 经营状态 - 风险等级 - 企业来源 ### 8.2 列表区 建议展示列： - 企业名称 - 统一社会信用代码 - 企业类型 - 企业性质 - 行业分类 - 所属行业 - 法定代表人 - 经营状态 - 风险等级 - 企业来源 - 数据来源 - 创建时间 - 操作 操作列固定为： - 详情 - 编辑 - 删除 ### 8.3 新增/编辑弹窗 交互方式对齐员工信息维护，采用整页弹窗表单。 表单项包含： - 统一社会信用代码 - 企业名称 - 企业类型 - 企业性质 - 行业分类 - 所属行业 - 成立日期 - 注册地址 - 法定代表人 - 法定代表人证件类型 - 法定代表人证件号码 - 股东1 - 股东2 - 股东3 - 股东4 - 股东5 - 经营状态 - 风险等级 - 企业来源 - 数据来源 其中： - 新增时 `socialCreditCode` 可填写 - 编辑时 `socialCreditCode` 禁止修改 ### 8.4 详情弹窗 详情展示字段与编辑表单保持同口径，采用只读方式展示。 ### 8.5 导入交互 导入流程完全对齐员工信息维护： - 下载模板 - 上传 Excel - 提交异步导入任务 - 轮询导入状态 - 本地缓存最近一次任务信息 - 导入失败时展示“查看导入失败记录”按钮 - 失败记录支持分页查看 ## 9. 接口设计 接口前缀建议统一为 `/ccdi/enterpriseBaseInfo`。 ### 9.1 列表查询 - `GET /ccdi/enterpriseBaseInfo/list` 入参为查询 DTO，返回分页表格结构。 ### 9.2 详情查询 - `GET /ccdi/enterpriseBaseInfo/{socialCreditCode}` ### 9.3 新增 - `POST /ccdi/enterpriseBaseInfo` ### 9.4 编辑 - `PUT /ccdi/enterpriseBaseInfo` ### 9.5 删除 - `DELETE /ccdi/enterpriseBaseInfo/{socialCreditCodes}` 支持批量删除。 ### 9.6 导入模板 - `POST /ccdi/enterpriseBaseInfo/importTemplate` ### 9.7 导入数据 - `POST /ccdi/enterpriseBaseInfo/importData` ### 9.8 查询导入状态 - `GET /ccdi/enterpriseBaseInfo/importStatus/{taskId}` ### 9.9 查询导入失败记录 - `GET /ccdi/enterpriseBaseInfo/importFailures/{taskId}` ## 10. 权限与菜单设计 新增菜单名称固定为“实体库管理”。 建议菜单与权限如下： - 菜单路径：`enterpriseBaseInfo` - 组件路径：`ccdiEnterpriseBaseInfo/index` - 列表权限：`ccdi:enterpriseBaseInfo:list` - 查询权限：`ccdi:enterpriseBaseInfo:query` - 新增权限：`ccdi:enterpriseBaseInfo:add` - 修改权限：`ccdi:enterpriseBaseInfo:edit` - 删除权限：`ccdi:enterpriseBaseInfo:remove` - 导入权限：`ccdi:enterpriseBaseInfo:import` 菜单应挂到“信息维护”目录下，方式与员工信息维护等现有业务菜单一致。 ## 11. 校验规则 ### 11.1 新增/编辑校验 - 企业名称不能为空 - 统一社会信用代码不能为空 - 统一社会信用代码必须符合 18 位社会信用代码格式 - 新增时若数据库中已存在相同统一社会信用代码，则报错 - 编辑时若记录不存在，则报错 - `status`、`riskLevel`、`entSource`、`dataSource` 必须在允许值内 - 其他字段按长度、日期格式做基础校验 ### 11.2 导入校验 - Excel 至少包含一条数据 - 企业名称不能为空 - 统一社会信用代码不能为空 - 统一社会信用代码格式必须正确 - 同一导入文件中若统一社会信用代码重复，则该重复记录失败 - 数据库中若已存在相同统一社会信用代码，则该记录失败 ## 12. 导入策略 本次导入采用“严格新增”策略，不支持覆盖更新。 即： - 不提供 `updateSupport` 覆盖更新能力 - 已存在统一社会信用代码的记录直接记为失败 - Excel 内重复记录直接记为失败 - 成功记录批量插入 - 失败记录落 Redis，保留最近任务失败明细查询能力 导入状态结构与员工信息维护保持一致： - `PROCESSING` - `SUCCESS` - `PARTIAL_SUCCESS` ## 13. 错误处理 错误处理遵循现有员工维护风格，使用直接明确的业务提示： - “该统一社会信用代码已存在” - “实体信息不存在” - “至少需要一条数据” - “任务不存在或已过期” 不引入额外异常框架或复杂回退逻辑。 ## 14. 测试设计 ### 14.1 后端测试重点 - 列表分页和多条件查询正确 - 详情返回正确 - 新增成功，主键重复时报错 - 编辑成功，编辑不存在记录时报错 - 删除成功 - 导入成功、部分成功、失败状态正确 - 导入失败记录查询正确 ### 14.2 前端测试重点 - 查询、重置、分页交互正常 - 新增、详情、编辑、删除链路正常 - 编辑态主键不可修改 - 导入弹窗、状态轮询、失败记录查看正常 - 最近一次导入任务缓存与失败按钮显示逻辑正常 - 权限按钮显示与菜单路由正确 ## 15. 实施文档要求 由于本次需求涉及前后端改动，后续实施阶段需按仓库规范输出两份实施计划： - 后端实施计划：`docs/plans/backend/` - 前端实施计划：`docs/plans/frontend/` ## 16. 最终结论 本次采用“独立实体库管理模块 + 复用现有企业主体表”的实现方式，以最短路径满足业务目标，同时保证： - 业务语义清晰 - 代码结构与员工信息维护一致 - `riskLevel`、`entSource`、`dataSource` 均可维护 - 导入严格新增，重复统一社会信用代码直接失败 - 不引入超出需求范围的扩展能力