新增图谱功能及验收清单

docs/tests/plans/2026-05-29-graph-acceptance-checklist.md

@@ -0,0 +1,127 @@
+# 图谱功能改动梳理与验收清单
+
+## 1. 验收目标
+
+本清单用于继续验收当前图谱相关改动，覆盖资金流图谱和关系图谱两部分，重点确认：
+
+- 已改动内容分别承担什么功能。
+- 后端接口是否返回正常，是否出现 `500`、鉴权异常或 SQL 报错。
+- 专项排查和项目分析弹窗中的真实页面是否能打开和查询。
+- 已建图谱表不重复建表，仅核对必要字段、索引和补充脚本。
+
+## 2. 改动梳理
+
+### 2.1 资金流图谱
+
+| 类型 | 文件/入口 | 功能 |
+| --- | --- | --- |
+| 后端 Controller | `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiFundGraphController.java` | 提供主体搜索、一层资金图谱查询、边流水明细分页、手工资金流向保存接口。 |
+| 后端 Service | `CcdiFundGraphServiceImpl.java` | 参数归一化、中心主体定位、真实边和手工边合并排序、节点组装、手工边保存、默认 `limit` 防空。 |
+| 后端 Mapper | `CcdiFundGraphMapper.java`、`CcdiFundGraphMapper.xml` | 读取 `lx_fund_flow_*` 表，按账户明细实时聚合主体资金边，查询逐笔流水，写入手工边。 |
+| DTO/VO | `CcdiFundGraph*DTO.java`、`CcdiFundGraph*VO.java` | 定义查询条件、手工边保存参数、图谱节点、资金边、流水明细返回结构。 |
+| 前端 API | `ruoyi-ui/src/api/ccdi/graph/fundGraph.js` | 封装 `/ccdi/project/fund-graph/*` 接口。 |
+| 前端组件 | `FundGraphSection.vue` | 资金图谱主工作台：搜索、日期范围、最小金额、ECharts 图谱、节点/边详情、边流水分页、手工新增资金流向。 |
+| 专项排查入口 | `SpecialCheck.vue` | 将原图谱占位卡替换为真实图谱组件。 |
+| 项目分析弹窗 | `ProjectAnalysisDialog.vue`、`ProjectAnalysisFundFlowTab.vue` | 在“资金流向”页签内展示简版资金图谱，弹窗内不展示逐笔流水表。 |
+| SQL | `sql/ccdi/graph/01_lx_fund_graph_mysql_ddl.sql`、`02_lx_fund_graph_seed_test_data.sql`、`06_lx_fund_graph_existing_table_supplement.sql` | 记录资金图谱必要表结构、开发联调测试数据，以及已建表环境补字段/补索引脚本。 |
+
+### 2.2 关系图谱
+
+| 类型 | 文件/入口 | 功能 |
+| --- | --- | --- |
+| 后端 Controller | `CcdiRelationGraphController.java` | 提供主体搜索、一层关系图谱查询、疑似同名企业查询接口。 |
+| 后端 Service | `CcdiRelationGraphServiceImpl.java` | 关系图谱主体定位、家庭/股东/法人边合并展示、疑似企业按姓名召回与年龄规则过滤。 |
+| 后端 Mapper | `CcdiRelationGraphMapper.java`、`CcdiRelationGraphMapper.xml` | 读取 `lx_rel_node`、`lx_rel_family_edge`、`lx_rel_stock_edge`、`lx_rel_represent_edge`。 |
+| DTO/VO | `CcdiRelationGraph*DTO.java`、`CcdiRelationGraph*VO.java` | 定义关系图谱查询、节点、边、疑似企业候选返回结构。 |
+| 前端 API | `ruoyi-ui/src/api/ccdi/graph/relationGraph.js` | 封装 `/ccdi/project/relation-graph/*` 接口。 |
+| 前端组件 | `FundGraphSection.vue` | 同一组件内提供“关系图谱”页签、节点/边详情和疑似同名企业面板。 |
+| 项目分析弹窗 | `ProjectAnalysisDialog.vue` | “关系图谱”页签由占位页改为真实关系图谱简版展示。 |
+| SQL | `03_lx_relation_graph_mysql_ddl.sql`、`04_lx_relation_graph_build_mysql.sql`、`05_lx_relation_graph_seed_test_data.sql` | 关系图谱建表、构建和测试数据脚本。DDL 已包含旧表补字段/补索引逻辑。 |
+
+### 2.3 关联修复
+
+| 文件 | 功能 |
+| --- | --- |
+| `CcdiModelParamServiceImpl.java` | 对 `ICcdiBankTagService` 增加 `@Lazy`，缓解服务循环依赖启动问题。 |
+| `CcdiProjectOverviewServiceImpl.java` | 对 `ICcdiModelParamService` 增加 `@Lazy`，缓解服务循环依赖启动问题。 |
+| `application-dev.yml`、`tongweb_62318.properties` | 本地/部署运行配置存在改动，不纳入本次图谱验收清单。 |
+
+## 3. 建表与补充脚本验收口径
+
+当前表已建好，本轮不重复执行建表脚本。验收时按以下口径处理：
+
+- `CREATE TABLE IF NOT EXISTS` 可保留在仓库内，作为新环境初始化和评审依据。
+- 已存在表只做字段、索引、字符集、排序规则核对。
+- 如已建资金流图谱表缺字段或缺索引，优先使用 `sql/ccdi/graph/06_lx_fund_graph_existing_table_supplement.sql` 补充，不要先删表再重建。
+- 如已建关系图谱表缺字段或缺索引，优先使用 `sql/ccdi/graph/03_lx_relation_graph_mysql_ddl.sql` 中的补充逻辑。
+- 所有图谱表、字符字段和新增索引保持 `utf8mb4`、`utf8mb4_general_ci` 口径。
+- 执行包含中文内容的 SQL 文件时使用 `bin/mysql_utf8_exec.sh <sql-file>`。
+- 生产环境 DDL 和补充 SQL 由人工确认后手动执行，不随应用发布自动执行。
+
+资金流图谱需核对：
+
+- `lx_fund_flow_subject_node`
+- `lx_fund_flow_account_node`
+- `lx_fund_flow_own_account_edge`
+- `lx_fund_flow_detail_edge`
+- `lx_fund_flow_manual_edge`
+
+关系图谱需核对：
+
+- `lx_rel_node`
+- `lx_rel_family_edge`
+- `lx_rel_stock_edge`
+- `lx_rel_represent_edge`
+
+## 4. 验收清单
+
+### 4.1 静态与构建
+
+- [ ] 后端 `mvn -pl ccdi-project -am compile -DskipTests` 通过。
+- [ ] 前端执行前确认 Node 版本；如 `nvm` 不可用，记录实际 Node 版本。
+- [ ] 前端 `npm run build:prod` 通过，无新增编译错误。
+- [ ] 检查暂存区，确认验收文档、业务代码、SQL、构建产物边界清晰。
+
+### 4.2 资金流图谱接口
+
+- [ ] 未登录访问图谱接口返回认证失败，不泄露数据。
+- [ ] 管理员登录后，`/ccdi/project/fund-graph/search` 可按身份证号查到主体。
+- [ ] `/ccdi/project/fund-graph/graph` 默认查询返回节点、边、总金额、交易笔数。
+- [ ] 日期范围查询返回正常，不出现 SQL 字符集/排序规则错误。
+- [ ] `direction=1` 支出查询返回正常。
+- [ ] `direction=2` 收入查询返回正常。
+- [ ] 点击边对应的 `/edge-detail` 分页返回正常，不再出现 `LIMIT null`。
+- [ ] 手工新增资金流向缺少起点时返回明确业务错误，不抛服务端异常栈。
+- [ ] 手工边与真实边合并后统一排序和统一 `limit`。
+
+### 4.3 关系图谱接口
+
+- [ ] `/ccdi/project/relation-graph/search` 可按身份证号或姓名查到主体。
+- [ ] `/ccdi/project/relation-graph/graph` 返回家庭、股东、法人关系边。
+- [ ] `/ccdi/project/relation-graph/suspected-enterprises` 可按姓名召回疑似企业。
+- [ ] 同名候选过多时返回阻断提示，不直接大批量展示。
+- [ ] 出生日期或身份证可用时，成立时未满 18 岁候选被过滤。
+
+### 4.4 专项排查页面
+
+- [ ] 登录后进入真实项目详情页，不打开原型页。
+- [ ] 切换到“专项排查”，图谱分析区域出现。
+- [ ] 资金流图谱默认空态文案正确。
+- [ ] 输入身份证号后点击查询，资金边统计展示正确。
+- [ ] 图谱画布非空白，页面无明显遮挡、错位。
+- [ ] 点击资金边后右侧展示金额、笔数、关系标签和逐笔流水。
+- [ ] 切换到关系图谱页签，搜索后页面无白屏、无控制台错误。
+- [ ] 浏览器控制台无 `error`，图谱相关网络请求均为 `200`。
+
+### 4.5 项目分析弹窗
+
+- [ ] 在结果总览人员行点击“查看详情”打开项目分析弹窗。
+- [ ] “资金流向”页签展示简版图谱，无搜索栏，画布能渲染。
+- [ ] “关系图谱”页签展示简版关系图谱，切换页签后图谱重新 resize。
+- [ ] 弹窗版不展示逐笔流水表，仅展示汇总信息。
+- [ ] 弹窗控制台无图谱 resize、ECharts 初始化、接口调用异常。
+
+### 4.6 待重点复核项
+
+- [ ] `nvm` 在当前 PowerShell 环境不可用；前端构建已记录实际 Node 版本。
+- [ ] 已建表环境执行补充前，先人工确认目标库、表结构差异和备份策略。

docs/tests/records/2026-05-29-graph-acceptance-record.md

@@ -0,0 +1,101 @@
+# 2026-05-29 图谱功能验收执行记录
+
+## 1. 执行信息
+
+- 执行时间：2026-05-29 17:36 ~ 17:43（Asia/Shanghai）
+- 验收环境：本机真实服务
+- 前端地址：`http://localhost/`
+- 后端地址：`http://localhost:62318`
+- 验收清单：`docs/tests/plans/2026-05-29-graph-acceptance-checklist.md`
+- 测试项目：`projectId=90342`，项目名 `test拉取行内流水`
+- 管理员账号：`admin`
+
+## 2. 构建与静态验证
+
+| 项目 | 命令 | 结果 |
+| --- | --- | --- |
+| 后端编译 | `mvn -pl ccdi-project -am compile -DskipTests` | 通过 |
+| 前端 Node 确认 | `nvm use; node -v` | `nvm` 不可用，实际 Node 为 `v22.22.0` |
+| 前端构建 | `npm run build:prod` | 通过，有既有资源体积 warning |
+
+说明：
+
+- Maven 输出存在既有重复依赖声明 warning：`ccdi-info-collection` 中 `ccdi-lsfx` 依赖重复。
+- 前端构建只有资源体积 warning，无编译失败。
+
+## 3. 接口验收
+
+### 3.1 鉴权
+
+- 未登录访问 `/ccdi/project/fund-graph/search`：返回 `401`，符合预期。
+- 未登录访问 `/ccdi/project/relation-graph/search`：返回 `401`，符合预期。
+- 使用 `/login` 登录成功，后续接口带 `Bearer token` 验收。
+
+### 3.2 资金流图谱
+
+测试身份证号：`617673198109148314`
+
+| 接口/场景 | 结果 |
+| --- | --- |
+| `/ccdi/project/fund-graph/search?keyword=617673198109148314` | `code=200`，查到 1 个主体 |
+| `/ccdi/project/fund-graph/graph?keyword=617673198109148314&limit=20&minTotalAmount=0` | `code=200`，10 个节点、18 条边、72 笔、总金额 `302844.78` |
+| 日期范围查询 | `code=200`，18 条边、72 笔 |
+| `direction=1` 支出查询 | `code=200`，9 条边、45 笔 |
+| `direction=2` 收入查询 | `code=200`，9 条边、27 笔 |
+| 第一条资金边明细分页 | `code=200`，返回 5 条，总数 5 |
+| 手工新增资金流向缺少起点 | 返回 `code=500`，业务提示：`起点主体不能为空` |
+
+结论：
+
+- 资金图谱核心查询、方向筛选、边明细分页可用。
+- 手工新增缺少必填项时已返回明确提示，未出现服务端异常栈。
+
+### 3.3 关系图谱
+
+测试身份证号：`330101198001010011`
+
+| 接口/场景 | 结果 |
+| --- | --- |
+| `/ccdi/project/relation-graph/search?keyword=330101198001010011` | `code=200`，查到 1 个主体 |
+| `/ccdi/project/relation-graph/graph?keyword=330101198001010011&limit=80` | `code=200`，3 个节点、2 条边 |
+| `/ccdi/project/relation-graph/suspected-enterprises` | `code=200`，返回 1 条疑似企业，`blocked=false` |
+
+结论：
+
+- 关系图谱接口可用，疑似企业查询可用。
+
+## 4. 页面验收
+
+使用 Playwright CLI 打开真实页面 `http://localhost/` 执行：
+
+1. 登录系统。
+2. 进入初核项目管理。
+3. 打开项目 `90342` 的详情页。
+4. 切换到“专项排查”。
+5. 在“资金流图谱”输入 `617673198109148314` 并查询。
+6. 切换“关系图谱”，输入 `330101198001010011` 并查询。
+7. 检查控制台和网络请求。
+
+结果：
+
+- 专项排查页面可正常加载图谱分析区域。
+- 资金流图谱查询后页面展示 `18 条资金边`、`72 笔`、`302,844.78 元`。
+- 关系图谱查询接口返回 `200`，页面无白屏。
+- 图谱相关网络请求：
+  - `/dev-api/ccdi/project/fund-graph/graph?keyword=617673198109148314&minTotalAmount=1000&limit=20` 返回 `200`
+  - `/dev-api/ccdi/project/relation-graph/graph?keyword=330101198001010011&limit=80` 返回 `200`
+- 浏览器控制台 `error` 数量为 0。
+- 截图证据：`output/playwright/graph-acceptance-special-check.png`
+
+## 5. 注意事项
+
+| 编号 | 级别 | 事项 | 影响 | 建议 |
+| --- | --- | --- | --- | --- |
+| GRAPH-002 | P2 | 当前 PowerShell 环境 `nvm` 不可用 | 不满足“前端命令前先 nvm use”的执行规范 | 修复 nvm 安装或 PATH；本轮实际使用 Node `v22.22.0` |
+| GRAPH-004 | P2 | 资金流 DDL 原先只有新建表口径，已建旧表需要差异补充 | 生产若已建旧表但缺字段，单靠 `CREATE TABLE IF NOT EXISTS` 不会补齐 | 已补充 `sql/ccdi/graph/06_lx_fund_graph_existing_table_supplement.sql`，执行前需人工核对 |
+
+## 6. 阶段性结论
+
+本轮未发现图谱接口 `500`、页面白屏或浏览器控制台 error。资金流图谱和关系图谱在当前本机真实服务上均可查询。
+
+当前图谱主链路验收通过。剩余事项为环境类或发布前核对类事项：`GRAPH-002` 需要修复本机 `nvm` 环境，`GRAPH-004` 需要在生产执行补充 SQL 前人工核对目标库和表结构差异。