新增专项排查图谱嵌入设计

docs/design/2026-05-07-project-special-check-graph-atlas-design.md

@@ -0,0 +1,99 @@
+# 项目详情专项排查图谱嵌入设计
+
+## 背景
+
+项目详情页的“专项排查”页面当前已有“图谱外链展示”占位卡片，需要替换为真实 iframe 图谱展示能力。图谱分为“资金图谱”和“关系图谱”两个页签，对应 `assets/图谱.txt` 中的两个外部链接。
+
+本次设计只涉及前端页面展示，不新增后端接口，不保存证件号，不调整项目详情主导航。
+
+## 目标
+
+- 在项目详情的“专项排查”页面内嵌入图谱展示区域。
+- 图谱区域包含共用证件号输入框和“资金图谱 / 关系图谱”两个页签。
+- 用户输入证件号后，前端执行标准化与 md5 加密，并替换图谱链接 `vId` 中 `/` 后的 hash 字符串。
+- 未输入证件号前不加载 iframe，只显示输入提示。
+
+## 页面位置
+
+在 `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue` 中，将现有“图谱外链展示”占位卡片替换为独立组件：
+
+- 上方：员工家庭资产负债专项核查
+- 中间：图谱展示组件
+- 下方：采购、招聘、调动扩展查询
+
+组件建议命名为 `GraphAtlasSection.vue`，放在 `ruoyi-ui/src/views/ccdiProject/components/detail/` 目录下，并由 `SpecialCheck.vue` 引入。
+
+## 交互设计
+
+图谱组件顶部展示一行查询区：
+
+- 证件号输入框
+- “查询图谱”按钮
+
+触发方式：
+
+- 输入框回车触发查询
+- 点击“查询图谱”按钮触发查询
+
+图谱页签顺序：
+
+1. 资金图谱
+2. 关系图谱
+
+未查询状态下，iframe 不渲染，展示空状态提示“请输入证件号后查询图谱”。查询成功后，当前页签渲染对应 iframe。切换页签时复用同一个已加密证件号重新生成 iframe 地址。
+
+## 数据处理
+
+证件号处理流程：
+
+1. 对用户输入执行 `trim`，去掉前后空格。
+2. 如果标准化后的证件号末尾是小写 `x`，转换为大写 `X`。
+3. 使用现有 `@/utils/md5` 工具生成 md5。
+4. 按当前页签替换图谱链接 `params.vId` 中 `/` 后的 hash。
+
+图谱 `vId` 规则：
+
+- 资金图谱：`idno_node/<md5证件号>`
+- 关系图谱：`rel_node/<md5证件号>`
+
+链接来源固定为 `assets/图谱.txt` 的两个外部图谱地址。本次按前端常量维护，不引入后端配置化。
+
+## 异常处理
+
+- 证件号为空时，点击按钮或回车提示“请输入证件号”，不加载 iframe。
+- 证件号非空时不做身份证格式校验，只执行标准化和 md5，避免引入需求外的业务规则。
+- iframe 只负责设置 `src`，不读取跨域内容。
+- 外部图谱服务的 token、网络或页面错误由 iframe 内部页面展示，当前系统不额外增加兜底跳转或降级逻辑。
+- 当前阶段外部图谱页面可能无法正常打开，验收以 iframe 链接拼接正确为准，不以 iframe 内容成功渲染为通过条件。
+
+## 样式要求
+
+- 图谱区域延续专项排查页面现有白底卡片风格。
+- iframe 区域设置稳定的最小高度，避免图谱区域过矮。
+- 大屏下图谱区域尽量占用可视高度，方便查看节点关系。
+- 查询区、页签、iframe 容器之间保持清晰间距，不影响上下两个专项排查区块。
+
+## 测试设计
+
+实现完成后按项目规则进行真实页面验证：
+
+1. 进入真实项目详情页，切换到“专项排查”。
+2. 确认图谱模块位于资产负债核查和扩展查询之间。
+3. 未输入证件号时点击“查询图谱”，确认提示“请输入证件号”，且页面不加载 iframe。
+4. 未输入证件号时在输入框按回车，确认同样提示“请输入证件号”，且页面不加载 iframe。
+5. 输入证件号后点击按钮，确认资金图谱 iframe 地址中的 `vId` 为 `idno_node/<md5证件号>`。
+6. 修改证件号后在输入框按回车，确认资金图谱 iframe 地址刷新为新的 `idno_node/<md5证件号>`。
+7. 切换到关系图谱，确认沿用同一个证件号，iframe 地址中的 `vId` 为 `rel_node/<md5证件号>`。
+8. 使用带前后空格、末尾小写 `x` 的证件号重复验证，确认按 `trim + X` 标准化后生成 md5。
+9. 当前阶段不要求外部图谱内容实际打开成功，以上 iframe `src` 链接正确即可判定图谱拼接链路通过。
+10. 测试结束后关闭本轮启动的前端进程。
+
+前端命令执行前必须先在 `ruoyi-ui` 目录执行 `nvm use`。
+
+## 非目标
+
+- 不新增后端接口。
+- 不将图谱链接写入数据库。
+- 不保存用户输入的证件号或 md5 结果。
+- 不新增项目详情顶部一级菜单。
+- 不为外部图谱服务增加 token 刷新、降级链接或兼容逻辑。