wkc/ccdi

Fork 0

Files

wjj 26cd049991 新增图谱功能及验收清单

2026-05-29 18:33:26 +08:00

24 KiB

Raw Blame History

图谱开发决策记录

记录当前已确认的资金流图谱和关系图谱开发口径，作为后续开发、验收和跨对话延续的依据。

1. 页面嵌入位置

图谱功能先嵌入项目详情页的“专项排查”页签。
现有前端入口为 ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue。
页面在项目详情内承载，但资金流图谱本身不按 project_id 过滤。
查询入口以全局身份证号 cret_no 或员工姓名为准。

2. 图谱表结构原则

建表逻辑尽量保持图谱平台已验证过的 SQL 逻辑。
不重新设计统一点表/边表。
表名保留图谱平台 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_sum_edge
不在五张图谱表中增加 project_id 作为查询过滤口径。
一条流水可能存在于多个项目中，资金流图谱按全局资金关系构建，避免项目维度导致重复建点或重复算边。

3. 五张表职责

表名	作用
`lx_fund_flow_subject_node`	主体点，表示人员、企业、名称代理主体
`lx_fund_flow_account_node`	账户点，表示具体账号或名称代理账户
`lx_fund_flow_own_account_edge`	主体到账户的持有关系
`lx_fund_flow_detail_edge`	账户层逐笔资金交易边
`lx_fund_flow_sum_edge`	主体层资金汇总边，前端默认展示

关键点：

一个人可能有多个账号，所以必须保留主体点、账户点、持有边三层结构。
前端默认展示主体层汇总边，不默认展示全部账户层明细边，避免节点过多。
点击汇总边后，再查询账户层逐笔流水。

4. 构建逻辑

构建逻辑以 tupu/资金流图谱代码/lanxi_liushui_no_relation_simplified.sql 为主。

重要口径：

项目内 SQL 尽量和图谱平台原 SQL 保持一致。
先导入一部分“所有员工流水明细”作为图谱基座。
这部分基座数据视为已验证、绝对正确，不应被后续构建流程随意清空或覆盖。
后续从 ccdi_bank_statement 拉取新增流水时，需要先和图谱基座做一致性判断。
如果 ccdi_bank_statement 中的流水已经能在图谱基座中匹配到一致流水，则不同步进图谱，避免重复计入。
如果没有匹配到一致流水，则按原图谱 SQL 逻辑增量插入图谱。

保留的核心口径：

本方证件号 cret_no 必须存在。
对手方名称必须存在，空值、空串、0 过滤。
金额必须有效，支出和收入统一成 amount 与 flag。
支出 flag = 1，收入 flag = 2。
明细去重，避免重复流水导致金额和笔数翻倍。
同名归并只作用于主体层，不改变账户节点和账户明细边。
无账号但有名称的对手方，按原 SQL 逻辑生成名称代理账户和名称代理主体。

一期先不展开追溯能力。需要为后续追溯预留字段和逻辑口子：

source_table
penetrate_level
后续可扩展 FIRST、LEVEL1 等来源。

4.1 基座与增量同步口径

图谱表不是“清空重建”的临时结果表，而是承载已验证图谱基座和后续增量的正式结果表。

基座数据：

来源为先导入的所有员工流水明细。
按原图谱平台 SQL 生成五张 lx_* 表。
基座数据作为可信结果保留。

增量数据：

来源为后续 ccdi_bank_statement。
拉取后先按原 SQL 的流水标准化和去重口径生成候选流水。
候选流水和既有 lx_fund_flow_detail_edge 做一致性比对。
已存在一致流水时跳过，不插入图谱。
不存在一致流水时，再增量生成账户点、主体点、持有边、明细边和汇总边。

一致性比对建议使用稳定业务特征，而不是 project_id：

本方账号
本方户名
对手方账号
对手方户名
交易日期
金额
收支方向 flag
摘要 user_memo
银行流水号或交易流水号，如果有

增量插入要求：

点表按 object_key 去重插入。
持有边按 object_key 去重插入。
明细边先判重，未存在才插入。
汇总边需要按主体对和方向重新聚合或局部 upsert，不能简单追加导致金额翻倍。

4.2 ODPS 基座同步到 MySQL

当前真实部署口径：

原图谱 SQL 已在 ODPS 中有一份结果。
ODPS 结果只涉及行内流水。
ODPS 已经产出五张图谱结果表。
可以先将 ODPS 中五张结果表一次性同步到纪检 MySQL。
MySQL 同步建表脚本记录在 sql/ccdi/graph/01_lx_fund_graph_mysql_ddl.sql。
生产数据库表结构变更由人工单独执行，不跟随测试环境或应用发布自动更新。
项目内保留 SQL 文件，用于本地验证、评审和生产手动执行参考。

同步后的 MySQL 五张表继续使用原图谱表名：

lx_fund_flow_subject_node
lx_fund_flow_account_node
lx_fund_flow_own_account_edge
lx_fund_flow_detail_edge
lx_fund_flow_sum_edge

同步要求：

ODPS 到 MySQL 首次同步只做基座装载。
基座装载完成后，后续不再通过清空五张表重建处理。
ODPS 字段和 MySQL 字段同名的按显式字段列表导入。
MySQL 侧新增字段如 family_relation_type、summary_object_key、source_table、penetrate_level、bank_statement_id、bank_trx_number 可为空。
lx_fund_flow_sum_edge.detail_ids 在 MySQL 中使用 LONGTEXT 接收 ODPS ARRAY 同步后的 JSON 或字符串表示，前后端查询不强依赖该字段。

4.3 MySQL 后续增量方式

后续新增数据都在纪检 MySQL 内处理：

来源表为 ccdi_bank_statement。
增量逻辑从 ccdi_bank_statement 抽取候选流水。
候选流水按原图谱 SQL 口径标准化、过滤、生成 object_key。
先和既有 lx_fund_flow_detail_edge 做一致性判重。
已存在一致流水时不插入图谱。
不存在一致流水时，才增量插入点、账户、持有边、明细边。
汇总边 lx_fund_flow_sum_edge 按主体对和方向重新聚合或局部 upsert。

调度建议：

一期建议做每日定时调度，不建议一开始做实时。
推荐使用 RuoYi/Quartz 定时任务，每天凌晨或低峰期执行。
同时保留后台手动触发能力，便于首次补跑、排查和修复。
实时同步不是不能做，但没有必要优先做；实时会增加事务、锁、重复判断和汇总边更新复杂度。

推荐执行节奏：

ODPS 五张结果表一次性同步到 MySQL。
MySQL 跑一次家庭关系补充和 summary_object_key 回填。
每日 Quartz 调度从 ccdi_bank_statement 抽取新增候选流水。
候选流水与 lx_fund_flow_detail_edge 判重。
未命中重复的流水增量入图。
更新对应主体层汇总边。
前端始终只基于 MySQL 五张 lx_* 图谱表查询展示。

4.4 数据库变更执行边界

数据库表结构改动属于生产库手工变更，不纳入测试环境自动更新。

后续开发分工：

SQL 文件由代码库保留，作为生产手工执行依据和本地验证依据。
生产执行由人工确认后单独处理。
后端开发默认这些表在目标库中已经存在。
前端开发不感知数据库变更，只调用后端接口。
测试环境如没有这五张表，需要手动执行 SQL 后再联调。
应用发布包不自动执行这些 DDL。

5. 家庭关系

家庭关系是本次项目内新增能力，参考 tupu/资金流图谱代码/资金流图谱_家庭关系补充.sql。

处理原则：

不改变资金方向。
不改变主体归并逻辑。
不改变账户层明细边生成逻辑。
只在资金边上增加家庭关系标注。

匹配规则：

交易任意一侧可映射到员工主体。
员工主体必须有身份证号。
对手方姓名命中 ccdi_staff_fmy_relation.relation_name。
同一员工和同一关系人姓名只有一个 relation_type 时才标注。
多个关系类型冲突时不打标，避免误判。

建议补充字段：

lx_fund_flow_detail_edge.family_relation_type
lx_fund_flow_sum_edge.family_relation_type

6. 查询逻辑

搜索主体：

select *
from lx_fund_flow_subject_node
where idnocfno = #{keyword}
   or name like concat('%', #{keyword}, '%');

查询主体层资金图：

select *
from lx_fund_flow_sum_edge
where from_key = concat('idno_node/', #{objectKey})
   or to_key = concat('idno_node/', #{objectKey})
order by amount desc, total_trans_cnt desc
limit #{limit};

点击汇总边查询逐笔流水：

select *
from lx_fund_flow_detail_edge
where summary_object_key = #{sumObjectKey}
order by trx_date desc
limit #{offset}, #{pageSize};

说明：

原图谱平台 detail_ids 可以保留。
MySQL 分页查询建议增加 summary_object_key，用于从汇总边直接查明细边。
summary_object_key 是查询优化字段，不改变原图谱平台点边模型。

7. 前后端开发边界

后端负责：

从五张 lx_* 图谱结果表读取数据。
按身份证号或姓名定位主体。
返回主体层图谱节点和汇总边。
支持点击资金汇总边分页查询逐笔流水。
透出家庭关系字段。
空表或脏数据时返回空结果，不让前端报错。

前端负责：

在“专项排查”页签中呈现图谱展示区域。
支持身份证号或员工姓名搜索。
支持“资金图谱 / 关系图谱”页签。
一期资金图谱做实，关系图谱可先保留入口。
默认展示主体层资金汇总图。
点击边展示逐笔流水明细。
展示图谱明细边中已写入的家庭关系标签，如配偶、父母、子女。

8. 基座保护与异常数据处理

图谱表承载已验证基座，不按“可随意清空重建”设计。人工可以维护或清理异常数据，但默认应保护已有基座。

处理要求：

后续增量同步不得清空五张 lx_* 表。
增量同步前必须先判断候选流水是否已存在于 lx_fund_flow_detail_edge。
已存在一致流水时跳过，避免重复金额和重复笔数。
人工清理异常边后，后端查询需要能容忍局部缺失数据。
边表有、点表缺失时，后端过滤无法匹配节点的边，不让前端报错。
明细边为空时，点击汇总边提示暂无逐笔流水。
如果人工确实清理了部分图谱数据，后续增量插入仍需按 object_key 和流水一致性规则防重。

9. UI 风格

固定设计口径：

浅色系统风格。
正式后台质感。
与当前纪检系统色调保持一致，蓝、白、灰为主。
朝图谱平台式交互靠齐。
不做黑色大屏。
不做网感、霓虹、炫光科技风。
图谱画布使用浅灰白背景，边界清楚。
搜索区放在顶部，支持身份证号和姓名。
页签为“资金图谱”和“关系图谱”。
明细使用右侧抽屉或下方面板展示，优先保证字段清楚和分页性能。

10. 后续开发顺序

建议顺序：

先落项目内 SQL：DDL、构建 SQL、家庭关系补充 SQL、索引 SQL。
先支持已导入员工流水明细作为图谱基座。
增加 ccdi_bank_statement 到图谱表的增量同步逻辑。
增量同步必须先和既有 lx_fund_flow_detail_edge 做一致性判重，已存在则不同步。
后端接口改为读取五张 lx_* 图谱表。
前端在“专项排查”页签接入图谱展示区域。
完成资金图谱搜索、展示、点击边查明细。
增加家庭关系标签展示。
验证基座保护、增量防重、一个人多个账号、家庭关系命中等场景。

11. 当前代码进度与偏差

截至 2026-05-28，项目内已经做过一版一期资金流图谱代码，但这版实现口径与当前最终方案不完全一致，后续需要重构而不是直接当最终版。

已完成过的代码：

后端新增 CcdiFundGraphController，接口路径为 /ccdi/project/fund-graph/graph 和 /ccdi/project/fund-graph/edge-detail。
后端新增 DTO/VO：CcdiFundGraphQueryDTO、CcdiFundGraphEdgeDetailQueryDTO、CcdiFundGraphVO、CcdiFundGraphNodeVO、CcdiFundGraphEdgeVO、CcdiFundGraphStatementVO。
后端新增 Mapper 和 Service：CcdiFundGraphMapper、ICcdiFundGraphService、CcdiFundGraphServiceImpl、CcdiFundGraphMapper.xml。
前端新增接口文件 ruoyi-ui/src/api/ccdi/fundGraph.js。
前端新增组件 ProjectAnalysisFundFlowTab.vue。
前端已在 ProjectAnalysisDialog.vue 中接入资金流图谱页签。

旧版已验证情况：

mvn -pl ccdi-project -am compile -DskipTests 通过。
npm run build:prod 通过。
真实库只读校验过项目 33 和姓名样例，能查出资金边，点击边能查逐笔流水。
曾修正 MySQL 8 保留词别名 rows 和字符集排序规则不一致问题。

当前偏差：

旧版接口是实时从 ccdi_bank_statement 聚合资金图谱，不读取五张 lx_* 图谱结果表。
旧版查询带项目上下文，当前最终口径是不按 project_id 过滤，以全局 cret_no 或姓名为入口。
旧版前端接在项目分析弹窗 ProjectAnalysisDialog，当前最终入口应放在“专项排查”页签。
旧版没有按图谱平台五表基座和增量同步口径处理。
旧版没有家庭关系标注。

后续处理原则：

可复用旧版的图谱展示、点击边查明细、分页表格等前端交互经验。
可复用旧版 DTO/VO 中适合前端展示的字段，但字段来源需要改为五张 lx_* 表。
后端 SQL 必须从实时聚合 ccdi_bank_statement 改为读取 lx_fund_flow_subject_node、lx_fund_flow_account_node、lx_fund_flow_own_account_edge、lx_fund_flow_detail_edge、lx_fund_flow_sum_edge。
前端入口需要从项目分析弹窗迁移或重做到“专项排查”页签。
旧版文件在重构时应谨慎处理，避免影响当前项目分析弹窗已有功能。

12. 页面查询与汇总表最新决策

13. 节点穿透最新决策

节点穿透以 lx_fund_flow_subject_node.object_key 为唯一标识，不按姓名穿透。

口径：

实名主体按原 SQL 逻辑生成 object_key，即 md5(trim(idnocfno))。
用户点击节点后，可选择“以此节点为中心查询”或“展开此节点”。
默认不自动穿透，避免图谱过长和误展开。
后端按被选节点的 object_key 查询其账户和流水。
节点是否可穿透由后端返回 canExpand 控制。

允许穿透：

有明确身份证号或证件号的实名主体。
有明确账户归属、能通过 lx_fund_flow_own_account_edge 找到账户的主体。

默认不穿透：

只有名称、没有证件号、没有明确账户归属的名称代理主体。
无法通过 object_key 准确定位账户集合的节点。

交互建议：

一期做“设为中心查询”，即点击节点后重新以该节点为中心画一跳图。
后续再做“在当前图上追加展开”，避免一期图谱状态管理过复杂。

14. 最终减法版决策

本节覆盖前文早期关于五张表、lx_fund_flow_sum_edge、关系图谱页签的旧设想。后续开发以本节为准。

本节为 2026-05-28 资金流图谱减法版决策，重点是不依赖 lx_fund_flow_sum_edge。关于关系图谱页签，后续已在第 16 节更新为“保留关系图谱能力”，以第 16 节为准。

必要表：

lx_fund_flow_subject_node
lx_fund_flow_account_node
lx_fund_flow_own_account_edge
lx_fund_flow_detail_edge

不依赖：

lx_fund_flow_sum_edge

页面查询：

输入身份证号、姓名或点击节点 object_key。
后端定位主体点。
后端查询主体持有账户。
后端从 lx_fund_flow_detail_edge 按账户、trx_date、金额等条件实时聚合资金边。
前端只渲染后端返回的资金节点、资金边和逐笔明细。

家庭关系：

只作为资金流图谱中的标签展示。
家庭关系识别在图谱构建或数据加工阶段完成，并写入 lx_fund_flow_detail_edge.family_relation_type；后端查询接口只读取并返回该字段，不实时匹配家庭表。
如果生产构建需要按对手方户名匹配 ccdi_staff_fmy_relation.relation_name，应在构建 SQL 中完成，并控制同名误判风险。
有明确 relation_cert_no 的家庭关系人按实名主体处理，object_key = md5(trim(relation_cert_no))。
用户点击该节点时，可按该节点 object_key 设为中心继续查询。

测试数据：

测试 DDL 为 sql/ccdi/graph/01_lx_fund_graph_mysql_ddl.sql。
测试数据脚本为 sql/ccdi/graph/02_lx_fund_graph_seed_test_data.sql。
测试数据只写四张必要表。
测试数据来源于 dev 库 ccdi_bank_statement 和 ccdi_staff_fmy_relation。
原始流水表不被修改。

15. 前后端与页面交互设计

默认查询：

默认查询全部流水，不默认带交易日期过滤。
用户选择交易日期后，后端才按 lx_fund_flow_detail_edge.trx_date 过滤。
时间过滤不查汇总表，直接从明细边实时聚合。

后端接口建议：

GET  /ccdi/project/fund-graph/search
GET  /ccdi/project/fund-graph/graph
GET  /ccdi/project/fund-graph/edge-detail
POST /ccdi/project/fund-graph/manual-edge

GET /ccdi/project/relation-graph/search
GET /ccdi/project/relation-graph/graph
GET /ccdi/project/relation-graph/suspected-enterprises

接口职责：

search：按身份证号或姓名查主体点，返回候选主体列表。
graph：按主体 object_key 查询一跳资金图，默认全部流水，可选日期、金额、方向过滤。
edge-detail：点击资金边后，分页查询该边下的逐笔流水。

graph 入参：

objectKey     必填，主体 object_key
startDate     可选，交易开始日期
endDate       可选，交易结束日期
amountMin     可选，最小金额
amountMax     可选，最大金额
direction     可选，1支出、2收入
limit         可选，默认20

graph 返回：

centerNode    当前中心主体
nodes         图谱节点
edges         聚合后的资金边
summary       当前查询范围的总金额、总笔数、家庭关系边数量

节点字段：

objectKey
nodeKey       idno_node/{object_key}
name
idNo
nodeType      PERSON / PROXY
canExpand
relationType  如果是家庭关系节点，返回配偶/父亲/母亲等

边字段：

edgeKey
fromKey
toKey
fromName
toName
direction     1支出、2收入
amount
transactionCount
firstTrxDate
lastTrxDate
familyRelationType

edge-detail 入参：

fromObjectKey
toObjectKey
direction
startDate
endDate
pageNum
pageSize

页面交互：

页面位置：项目详情“专项排查”页签。
页面标题：图谱展示。
展示“资金流图谱”和“关系图谱”两个页签。
搜索区只保留必要控件：身份证号/姓名、交易日期、查询、重置。
默认空态提示：请输入身份证号或姓名查询资金流图谱。
查询后画一跳图，中心节点为当前人员。
边上只显示金额和笔数，家庭关系用标签显示。
点击资金边，右侧抽屉展示逐笔流水。
点击节点，提供“设为中心查询”；默认不自动穿透。
只有 canExpand = true 的节点展示“设为中心查询”。

性能口径：

前端不聚合金额和笔数。
后端只围绕一个主体的账户集合查明细边。
默认全部流水也只查当前主体相关边，不扫全表。
必须使用 lx_fund_flow_own_account_edge.from_key、lx_fund_flow_detail_edge.from_key/trx_date、lx_fund_flow_detail_edge.to_key/trx_date 索引。
后端 SQL 参数比较需要显式 COLLATE utf8mb4_general_ci，避免当前库连接排序规则和表排序规则不一致。

当前 dev 测试数据：

测试身份证号：617673198109148314
测试 object_key：以 `MD5('617673198109148314')` 为准
主体点：10
账户点：14
持有边：14
明细边：72

测试覆盖：

默认全部流水聚合。
日期范围筛选聚合。
支出方向 flag = 1。
收入方向 flag = 2。
家庭关系标签：配偶、父亲、母亲。
普通对手方：支付宝、淘宝、美团、财付通、小店、银行转账。
点击家庭关系节点按 object_key 设为中心查询。

16. 2026-05-29 最新验收口径

本节为当前最新口径，用于覆盖前文早期变更记录中的冲突描述。

当前图谱功能保留两类能力：

资金流图谱：作为专项排查中的核心图谱能力，读取 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，支持家庭关系、股东持股、法定代表人关系和疑似同名企业召回。

当前页面入口：

项目详情“专项排查”页签展示完整图谱工作台，包含“资金流图谱”和“关系图谱”两个页签。
项目分析弹窗“资金流向”页签展示简版资金流图谱。
项目分析弹窗“关系图谱”页签展示简版关系图谱。

当前接口入口：

GET  /ccdi/project/fund-graph/search
GET  /ccdi/project/fund-graph/graph
GET  /ccdi/project/fund-graph/edge-detail
POST /ccdi/project/fund-graph/manual-edge

GET /ccdi/project/relation-graph/search
GET /ccdi/project/relation-graph/graph
GET /ccdi/project/relation-graph/suspected-enterprises

当前数据库执行口径：

新环境可参考 sql/ccdi/graph/01_lx_fund_graph_mysql_ddl.sql 和 sql/ccdi/graph/03_lx_relation_graph_mysql_ddl.sql。
已建资金流图谱表的环境使用 sql/ccdi/graph/06_lx_fund_graph_existing_table_supplement.sql 补字段和补索引，不删除、不重建、不清空基座数据。
已建关系图谱表的环境使用 sql/ccdi/graph/03_lx_relation_graph_mysql_ddl.sql 中的补充逻辑补字段和补索引。
生产 DDL 和补充 SQL 都由人工确认后手动执行，不随应用发布自动执行。

当前验收样例：

资金流图谱测试身份证号：617673198109148314
关系图谱测试身份证号：330101198001010011

24 KiB Raw Blame History Unescape Escape