wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f8c5a9ec5f28a760edb418423f3f1ae194fd0e5
ccdi/docs/design/2026-03-24-special-check-extended-query-design.md

12 KiB
Raw Blame History

专项核查拓展查询卡片设计文档

模块: 项目详情 - 专项核查 日期: 2026-03-24 状态: 已确认

一、背景

当前项目详情页的专项核查页签已包含两块内容：

  1. 员工家庭资产负债专项核查
  2. 图谱外链展示占位卡片

其中图谱外链卡片当前仅作为后续接入外链图谱页面的预留入口，尚未承载真实业务查询能力。

本轮需求是在图谱外链卡片下方新增一张“拓展查询”卡片，用于查询项目范围内员工的采购、招聘、调动记录，并支持按主题 Tab 切换、按员工姓名和时间范围检索，以及按记录查看完整详情。

二、目标

本次设计目标如下：

  1. 在专项核查页签中新增“拓展查询”卡片，位置固定在图谱外链卡片下方。
  2. 通过 Tab 切换展示 3 类拓展查询主题：
    • 采购记录
    • 招聘记录
    • 调动记录
  3. 列表数据只查询当前专项核查同范围员工，不扩展到项目全部目标员工。
  4. 查询栏按主题独立配置，不共享无关筛选项。
  5. 列表展示必要字段，操作列提供“查看详情”按钮。
  6. 点击“查看详情”后，通过弹窗展示该条记录全部字段。

三、范围

3.1 本次范围

  • 新增专项核查页的拓展查询卡片
  • 新增采购、招聘、调动 3 个主题的 Tab 切换
  • 新增项目范围拓展查询列表接口
  • 新增项目范围拓展查询详情接口
  • 新增对应前端查询、分页、详情弹窗交互
  • 补充前后端测试与验证记录

3.2 不在本次范围

  • 不接入真实图谱外链地址
  • 不改动现有员工家庭资产负债专项核查逻辑
  • 不新开独立路由页面
  • 不扩展到项目全部目标员工
  • 不为招聘记录新增时间筛选字段
  • 不新增导出、编辑、删除等操作
  • 不引入缓存、异步预计算或额外结果表

四、已确认业务口径

本次设计确认以下口径，后续实施必须严格遵守：

  1. “项目范围内员工”定义为当前专项核查同范围员工，即现有专项核查链路中已归并出来的员工集合。
  2. 不按项目全部目标员工查询。
  3. 查询卡片位置固定在“图谱外链展示”卡片下方。
  4. 采用横向 Tab 切换主题，不使用竖向主题导航。
  5. 每个主题使用独立查询栏，不共享查询表单。
  6. 采购记录按“申请人姓名 + 申请日期范围”筛选。
  7. 招聘记录按“面试官姓名”筛选，本次不增加时间筛选。
  8. 调动记录按“员工姓名 + 调动日期范围”筛选。
  9. 列表只展示必要字段，详情弹窗展示该条记录全部字段。

五、方案对比

5.1 方案 A：图谱卡片下方新增独立拓展查询卡片

做法：

  • 保留现有图谱卡片不变
  • 在图谱卡片下方新增一张“拓展查询”卡片
  • 卡片内部顶部使用横向 Tab 切换主题

优点：

  • 完全符合“在图谱外链卡片下面添加拓展查询功能卡片”的原始需求
  • 不影响现有图谱占位卡片结构
  • 页面层级清晰，用户认知成本低
  • 前端改造路径最短

缺点：

  • 页面纵向高度会增加

5.2 方案 B：图谱卡片与拓展查询合并为一个大卡片

做法：

  • 图谱占位与拓展查询共用同一张卡片

问题：

  • 与“在图谱外链卡片下面添加卡片”的需求不一致
  • 图谱占位与实际查询职责混在一起，层次不清

5.3 方案 C：独立拓展查询卡片，但使用左侧竖向主题导航

做法：

  • 与方案 A 一样新增独立卡片
  • 但主题切换改为左侧竖向导航

问题：

  • 用户已明确要求通过 Tab 页切换主题
  • 与当前页面已有横向区块风格不一致

5.4 推荐方案

采用方案 A：在图谱外链卡片下方新增独立拓展查询卡片，卡片内部使用横向 Tab 切换采购、招聘、调动 3 个主题。

六、页面结构设计

专项核查页整体结构调整后如下：

  1. 员工家庭资产负债专项核查卡片
  2. 图谱外链展示卡片
  3. 拓展查询卡片

其中前两张卡片不修改现有交互，仅在其下方追加第三张卡片。

拓展查询卡片结构如下：

6.1 卡片头部

  • 标题：拓展查询
  • 副标题：查询专项核查同范围员工的采购、招聘、调动记录

6.2 Tab 区

  • Tab 1：采购记录
  • Tab 2：招聘记录
  • Tab 3：调动记录

6.3 主题查询区

每个 Tab 使用独立查询栏：

  • 采购记录：
    • 员工姓名
    • 申请日期范围
    • 搜索
    • 重置
  • 招聘记录：
    • 员工姓名
    • 搜索
    • 重置
  • 调动记录：
    • 员工姓名
    • 调动日期范围
    • 搜索
    • 重置

6.4 列表区

Tab 下方展示当前主题列表与分页。

切换 Tab 时：

  • 不共用查询表单
  • 不互相覆盖列表数据
  • 各主题保留自己的查询条件与分页状态
  • 首次进入某个 Tab 时再触发该 Tab 的首查

6.5 详情弹窗

操作列统一提供“查看详情”按钮。

点击后：

  • 采购记录弹出采购详情弹窗
  • 招聘记录弹出招聘详情弹窗
  • 调动记录弹出调动详情弹窗

详情弹窗展示该条记录全部字段，不裁剪字段内容。

七、列表字段设计

7.1 采购记录列表字段

  • 采购事项 ID
  • 项目名称
  • 标的物名称
  • 申请人姓名
  • 申请日期
  • 操作

7.2 招聘记录列表字段

  • 招聘项目编号
  • 招聘项目名称
  • 职位名称
  • 面试官姓名摘要
  • 录用情况
  • 操作

其中面试官姓名摘要定义为：

  • 优先展示 面试官1姓名 / 面试官2姓名
  • 如某一个为空，则只展示存在的姓名

7.3 调动记录列表字段

  • 员工姓名
  • 调动类型
  • 调动前部门
  • 调动后部门
  • 调动日期
  • 操作

八、后端设计

8.1 接口归属

本次不直接复用信息采集模块现有 /list 接口，而是在专项核查域新增项目范围拓展查询接口，统一挂在：

  • CcdiProjectSpecialCheckController

原因：

  1. 现有信息采集模块接口仅面向各自主表查询，不包含“专项核查同范围员工”的限制。
  2. 如果前端调用现有接口后自行过滤，会导致项目范围口径不稳定。
  3. 在专项核查域统一收口，后续维护更清晰。

8.2 接口设计

建议新增 6 个接口：

  • GET /ccdi/project/special-check/extended-query/purchase/list
  • GET /ccdi/project/special-check/extended-query/purchase/detail
  • GET /ccdi/project/special-check/extended-query/recruitment/list
  • GET /ccdi/project/special-check/extended-query/recruitment/detail
  • GET /ccdi/project/special-check/extended-query/transfer/list
  • GET /ccdi/project/special-check/extended-query/transfer/detail

8.3 项目范围员工口径复用

项目范围员工统一复用当前专项核查 mapper 中的员工范围定义，即：

  • CcdiProjectSpecialCheckMapper.xml 中的 projectEmployeeScopeSql

该范围已经与当前专项核查页保持一致，本轮不重新定义口径，不新增第二套项目员工范围逻辑。

8.4 列表查询设计

采购记录

数据来源：

  • ccdi_purchase_transaction

范围限制：

  • 记录必须命中专项核查同范围员工

筛选条件：

  • projectId
  • staffName
  • applyDateStart
  • applyDateEnd

员工姓名口径：

  • 按采购记录的 applicant_name 检索

时间口径：

  • 按采购记录的 apply_date 检索

招聘记录

数据来源：

  • ccdi_staff_recruitment

范围限制：

  • 记录必须命中专项核查同范围员工

筛选条件：

  • projectId
  • staffName

员工姓名口径：

  • 按招聘记录的 interviewer_name_1 或 interviewer_name_2 检索

时间口径：

  • 本次不提供招聘时间筛选

调动记录

数据来源：

  • ccdi_staff_transfer
  • ccdi_base_staff

范围限制：

  • 记录必须命中专项核查同范围员工

筛选条件：

  • projectId
  • staffName
  • transferDateStart
  • transferDateEnd

员工姓名口径：

  • 按调动记录对应员工的 staff_name 检索

时间口径：

  • 按 transfer_date 检索

8.5 详情查询设计

详情接口按各自主键查询，并返回该条记录全部字段：

  • 采购详情：按 purchaseId
  • 招聘详情：按 recruitId
  • 调动详情：按 id

详情查询仍需校验该记录属于当前专项核查同范围员工；不属于时返回业务错误，避免越权或口径漂移。

8.6 DTO / VO 设计

建议在 ccdi-project 模块下新增独立 DTO：

  • 采购拓展查询 DTO
  • 招聘拓展查询 DTO
  • 调动拓展查询 DTO

列表返回对象按主题独立定义轻量 VO，仅保留列表必要字段。

详情返回可优先复用现有 VO 字段结构：

  • CcdiPurchaseTransactionVO
  • CcdiStaffRecruitmentVO
  • CcdiStaffTransferVO

如直接复用存在耦合问题，再在 ccdi-project 下补充专项核查详情 VO，但本轮优先选择最短路径实现。

九、前端设计

9.1 页面挂载位置

继续以：

  • ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue

作为专项核查页签容器，不新增路由。

9.2 组件拆分

建议新增一张独立的拓展查询区块组件，例如：

  • ExtendedQuerySection.vue

职责如下：

  • 管理当前激活 Tab
  • 管理各 Tab 的查询参数
  • 驱动列表加载与分页
  • 打开并关闭详情弹窗

详情展示建议按主题拆分为小组件或局部模板：

  • 采购详情复用现有采购页的分组展示方式
  • 招聘详情复用现有招聘页的分组展示方式
  • 调动详情补齐与前两者一致的详情展示结构

9.3 状态管理

每个 Tab 独立维护以下状态：

  • query
  • list
  • loading
  • pageNum
  • pageSize
  • total
  • detailOpen
  • detailLoading
  • detailData

原则如下：

  1. 不共享查询表单
  2. 不共享列表数据
  3. 切换 Tab 时保留各自上次查询状态
  4. 首次进入 Tab 时再请求列表

9.4 空态与异常

  • 列表无数据时展示当前主题无数据空态
  • 列表查询失败时提示错误信息，并清空当前主题列表
  • 详情查询失败时只提示错误，不污染列表状态
  • projectId 为空时沿用当前专项核查页已有空态逻辑

十、测试与验证设计

10.1 前端验证

补充以下验证：

  1. 专项核查页新增拓展查询卡片结构断言
  2. 卡片位于图谱外链卡片下方的结构断言
  3. 3 个主题 Tab 的存在性断言
  4. 不同 Tab 显示不同查询栏字段的断言
  5. 操作列“查看详情”按钮存在性断言
  6. 调动主题详情弹窗存在性断言
  7. 前端构建验证

10.2 后端验证

补充以下验证：

  1. 项目范围员工口径是否与 projectEmployeeScopeSql 一致
  2. 采购列表按申请人姓名和申请日期范围过滤是否正确
  3. 招聘列表按面试官姓名过滤是否正确
  4. 调动列表按员工姓名和调动日期范围过滤是否正确
  5. 详情接口是否能校验记录属于当前项目范围员工
  6. 记录不属于当前项目范围员工时是否返回预期错误

10.3 联调验证

联调时重点验证：

  1. Tab 切换后各自查询条件不会互相污染
  2. 招聘主题不展示时间范围
  3. 采购与调动主题展示时间范围
  4. 详情弹窗字段完整性与原业务页一致

十一、实施约束

本轮实施需遵守以下要求：

  1. 不新增兼容性分支或降级方案。
  2. 不在需求外扩展更多主题。
  3. 不新增导出、编辑、删除、批量操作。
  4. 不改变现有图谱占位卡片行为。
  5. 根据本设计文档产出两份实施计划：
    • 后端实施计划放 docs/plans/backend/
    • 前端实施计划放 docs/plans/frontend/

十二、结论

本次采用“图谱外链卡片下方新增独立拓展查询卡片”的方案，在专项核查页签内新增采购、招聘、调动 3 个主题查询能力。所有查询严格限制为当前专项核查同范围员工，采购与调动支持时间范围筛选，招聘仅支持面试官姓名筛选。前端不新增路由，后端在专项核查域新增统一接口，保持实现路径最短、页面职责清晰、业务口径稳定。

Reference in New Issue View Git Blame Copy Permalink