新增专项核查拓展查询设计文档
This commit is contained in:
456
docs/design/2026-03-24-special-check-extended-query-design.md
Normal file
456
docs/design/2026-03-24-special-check-extended-query-design.md
Normal file
@@ -0,0 +1,456 @@
|
||||
# 专项核查拓展查询卡片设计文档
|
||||
|
||||
**模块**: 项目详情 - 专项核查
|
||||
**日期**: 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
Block a user