30 KiB
30 KiB
数据流设计文档
版本: v1.0 | 日期: 2026-08-22 本文档描述 COBOL 迁移验证平台 V3 的完整数据流，覆盖非 DB（flat file）管道和 DB（SQL/SQLite）管道。
1. 数据流概述
1.1 设计目标
| 目标 | 说明 | 实现方式 |
|---|---|---|
| 可追溯性 | 每条测试数据可追溯到源码决策点 | 路径约束 (field, op, value, want_true) 记录决策分支选择 |
| 一致性 | 非 DB 与 DB 管道共享同一套解析/生成引擎 | cobol_testgen/ 统一提供 extract_structure + generate_data |
| 容错性 | 单步失败不中断整体管道 | 每步返回 DbPipelineResult(success, data)，失败立即终止后续 |
| 可观测性 | 全流程可监控、可调试 | 覆盖率报告、gcov 数据、JSON 中间产物、运行日志 |
1.2 管道对比
| 维度 | 非 DB 管道 | DB 管道 |
|---|---|---|
| 编排器 | orchestrator.py | orchestrator_db.py |
| 运行器 | runners/cobol_runner.py | runners/gixsql_runner.py |
| 输入格式 | 固定长度平面文件 | 平面文件 + SQLite DB 种子 |
| 输出格式 | 平面文件 | 平面文件 + SQLite DB |
| 验证方式 | comparator/ 逐字段比对 | Step 6 验证 COBOL/Java 输出一致性 |
| 步骤数 | 4 步（生成-运行-比对-报告） | 6 步（环境-生成-运行-提取-Java-验证） |
2. 非 DB 管道数据流
2.1 总体流程
COBOL 源码 (.cbl)
|
v [输入阶段]
read.py: preprocess() + parse_data_division()
|
v [生成阶段]
core.py: build_branch_tree() -> branch_tree + assignments
|
v
design.py: enum_paths() -> path_infos
|
v
design.py: make_base_record() -> base_record
|
v
design.py: apply_constraint() -> records (测试数据)
|
v [运行阶段]
output.py: output_json() -> 测试数据 JSON
output.py: output_input_files() -> 固定长度平面文件
|
v
runners/cobol_runner.py: compile() + run() -> 输出文件
|
v [比对阶段]
comparator/aligner.py: 按主键对齐 COBOL/Java 记录
comparator/field_compare.py: 逐字段比较
comparator/normalizer.py: EBCDIC/COMP-3 标准化
|
v
report/generator.py: 生成 HTML 报告
2.2 输入阶段
COBOL 源码 -> read.py 预处理 -> DATA DIVISION 解析 -> fields 结构信息
COBOL 源码 (fixed/free format)
|
v read.preprocess()
+-- resolve_copybooks(): 展开 COPY 语句
+-- _is_fixed_format(): 自动检测 fixed/free 格式
+-- 展开至每行 <=72 字符 (fixed) 或保持原样 (free)
+-- 去除 EXEC CICS/SQL 块、逗号、ALL 关键字
|
v 预处理后源码 (preprocessed)
|
v read.extract_data_division()
+-- 提取 DATA DIVISION 文本块
|
v read.parse_data_division()
+-- Lark grammar.lark 解析 (Earley parser, dynamic lexer)
+-- 逐行解析 FieldDef: level, name, PIC, USAGE, VALUE, REDEFINES, OCCURS
+-- PIC 子句解析 -> PicInfo (type, digits, decimal, length, signed)
+-- 返回 list[FieldDef]
|
v expand_occurs()
+-- OCCURS 展开为下标副本: WS-CELL(1), WS-CELL(2), ...
输出数据结构:
# fields: list[dict] -- 每个字段一个 dict
{
'name': 'R01EMP-ID', # 字段名 (大写)
'level': 1, # 层号 (01, 05, 77, 88)
'pic': 'X(8)', # PIC 子句原始文本
'pic_info': { # PIC 解析结果
'type': 'alphanumeric', # numeric | alphanumeric | alphabetic
'digits': 0, # 整数位数 (numeric)
'decimal': 0, # 小数位数 (numeric)
'length': 8, # 总长度 (alphanumeric)
'signed': False,
},
'section': 'FILE', # DATA DIVISION 节
'occurs': 0, # OCCURS 次数
'redefines': None, # REDEFINES 目标
'usage': None, # COMP | COMP-3 | BINARY | DISPLAY
'is_88': False, # 是否 88 级条件
'parent': None, # 88 级父字段名
'value': None, # VALUE 子句
'values': None, # 88 级多值列表
'is_filler': False,
}
2.3 生成阶段
fields -> core.py build_branch_tree -> design.py enum_paths -> make_base_record -> apply_constraint -> 测试数据
2.3.1 分支树构建
PROCEDURE DIVISION 文本
|
v core.build_branch_tree_fallback()
+-- pipeline_bridge: 3秒超时桥接
| +-- 优先: procedure_parser.py (新解析器, 行级状态机)
| +-- 回退: core._BrParser (旧解析器, 正则驱动)
|
+-- 段落扫描: scan_paragraphs() -> {name: (start, end)}
+-- 逐段解析 IF / EVALUATE / PERFORM / READ / WRITE / MOVE / COMPUTE
+-- 返回 (branch_tree: BrSeq, assignments: dict)
分支树节点类型:
| 节点 | 类 | 属性 | 说明 |
|---|---|---|---|
| 序列 | BrSeq | children: list | 顺序执行的语句序列 |
| 条件 | BrIf | condition, cond_tree, true_seq, false_seq | IF-ELSE 分支 |
| 评估 | BrEval | subject, subjects, when_list, other_seq | EVALUATE 多分支 |
| 循环 | BrPerform | perf_type, condition, body_seq | PERFORM UNTIL/VARYING |
| 查找 | BrSearch | table_name, is_all, when_list | SEARCH/SEARCH ALL |
| 赋值 | Assign | target, source_info | MOVE/COMPUTE/ADD/SUBTRACT/MULTIPLY/DIVIDE |
| 调用 | CallNode | program_name, using_params | CALL 子程序 |
| 跳转 | GoTo | target, body_seq | GO TO |
| 退出 | ExitNode | exit_type | EXIT PARAGRAPH/PERFORM/PROGRAM |
2.3.2 路径枚举
branch_tree + assignments
|
v design_mcdc.enum_paths() / design.enum_paths()
+-- 遍历分支树，收集每个决策点 (BrIf/BrEval/BrPerform)
+-- 对每个决策点生成 True/False 或 WHEN 分支路径
+-- MC/DC 约束集: cond.mcdc_sets() -> 每个叶条件的 T/F 独立约束
+-- 路径约束合并: prior_false 累积（EVALUATE WHEN 入口条件）
+-- PERFORM VARYING: 最后一次迭代约束 (last-iteration)
+-- SEARCH: 表索引约束 + AT END 分支
+-- 返回 path_infos: list[(constraints, path_assignments, term_type)]
路径约束格式:
# path_infos 的每个元素
(
# constraints: Path = list[Constraint]
[
('WRK-MONTH', '>', '0', True), # (field, op, value, want_true)
('WRK-MONTH', '<', '13', True),
('R01EMP-ID', '<>', '00000000', True),
],
# path_assignments: dict -- 赋值表
{
'WRK-PREV-EMP-ID': [{'type': 'move', 'source_vars': ['R01EMP-ID']}],
'DBV-EMP-ID': [{'type': 'move_literal', 'literal': 'A0000001'}],
},
# term_type: str
'normal' # 或 'abend'
)
2.3.3 测试数据记录生成
path_infos + data_fields
|
v design.generate_records()
|
+-- 遍历每条路径 (seq=1,2,3...):
| |
| +-- make_base_record(seq, data_fields)
| | +-- 按 VALUE 子句设置初始值
| | +-- 按 PIC 类型生成默认值:
| | | +-- numeric: _make_numeric_value(idx, seq, total_digits)
| | | +-- alphanumeric: _make_alpha_value(idx, seq, length)
| | | +-- date: seq_date(record_num) -> YYYYMMDD
| | +-- 返回 base_record: dict {field_name: value}
| |
| +-- Pass A: propagate_assignments(rec, path_assign, data_fields)
| | +-- 模拟赋值传播: MOVE/COMPUTE/READ INTO 等
| |
| +-- Pass B: apply_constraint(rec, field, op, val, want, ...)
| | +-- trace_to_root(): 沿 MOVE 链追溯到根字段
| | +-- invert_through_chain(): 反向求解约束值
| | +-- satisfying_value(): 满足约束的值计算
| | | +-- numeric: 边界值 +/-1
| | | +-- alphanumeric: 字典序边界
| | | +-- date: YYYYMMDD 格式边界
| | +-- 递归写入 base_record[field] = 满足值
| |
| +-- Pass B.5: forward propagate (变量间 MOVE 一致性)
| +-- Pass B.75: COMPUTE 重算 (约束修改源字段后)
| +-- get_term_type(path_cons) -> (filtered_cons, term_type)
|
+-- 返回 (records, kept_path_cons, term_types)
测试数据记录格式:
# records: list[dict] -- 每条记录一个 dict
[
{
'R01EMP-ID': 'A0000001',
'R01DATE': '20250101',
'R01LINE': '0001',
'WRK-PREV-EMP-ID': '',
'WRK-MONTH': '06',
'DBV-EMP-ID': 'A0000001',
'_assigned_fields': {'R01EMP-ID', 'R01DATE'}, # 内部标记
'_w02_path': True, # PREV 连锁标记
},
# ... 更多记录
]
2.4 运行阶段
测试数据 -> output.py -> cobol_runner compile/run -> 输出文件
records + fd_fields + open_dir
|
v output.output_json()
+-- 按 FD 分组: field_to_fd 映射字段到 FD
+-- 按 open_dir 确定方向: INPUT/OUTPUT/I-O
+-- 按 roles 分类: input/inout -> input 块, output/inout -> expected_output 块
+-- 不属于任何 FD 的字段 -> working_storage 块
+-- 输出 JSON: {program, records: [{input, expected_output, working_storage, termination}]}
|
v output.output_input_files()
+-- 仅处理 INPUT/I-O 方向的 FD
+-- 按 FD 分组，每 FD 输出一个 JSON: {stem}_{fd_name}.json
+-- abend 记录单独输出: {stem}_abend_{fd_name}.json
+-- 二进制模式: 按 field offsets 打包为固定长度二进制文件
|
v flatfile.write_all_files()
+-- analyze_fd_layout(): 解析 FD 记录布局 (字段名/PIC/offset/length)
+-- 按 FD 布局序列化每条记录为固定长度字节
+-- write_flat_file(): 输出到 outdir/{assign_name}
|
v runners/cobol_runner.compile()
+-- cobc -std=ibm -free -x src.cbl -o exe
|
v runners/cobol_runner.run()
+-- 设置 CWD，复制输入文件到 input/
+-- subprocess.run(exe) 执行
+-- 捕获 stdout/stderr，收集输出文件
+-- 返回 RunResult(success, records, log)
2.5 比对阶段
输出文件 -> aligner.py -> field_compare.py -> normalizer.py -> report/generator.py -> HTML 报告
COBOL 输出文件 + Java 输出文件
|
v comparator/aligner.py: align_records()
+-- 按主键字段 (如 CUST-ID) 分组
+-- 取两侧键的并集，按字符串排序
+-- 逐键配对: MATCHED / MISSING_IN_SPARK / EXTRA_IN_SPARK
+-- 返回 list[(cobol_record, java_record, status)]
|
v comparator/normalizer.py: normalize_encoding()
+-- EBCDIC -> ASCII 解码 (EBCDIC_037 映射表)
+-- COMP-3 压缩十进制解码 (nibble -> decimal)
+-- 日期格式标准化 (YYYYMMDD -> YYYY-MM-DD)
|
v comparator/field_compare.py: compare_field()
+-- 按字段类型选择比较策略:
| +-- numeric: Decimal 精度比较 + 容差 (tolerance=0.01)
| +-- date: YYYYMMDD 格式归一化后比较
| +-- string: strip 后直接比较
+-- 返回 FieldResult(field_name, status, cobol_value, java_value)
+-- status: PASS / MISMATCH / TOLERATED / NOT_SET
|
v comparator/rounding_detect.py: detect_rounding()
+-- 判断数值差异是否由 COBOL ROUNDED 子句引起
+-- 计算舍入误差范围
|
v report/generator.py: ReportGenerator
+-- generate_json(): 输出 JSON 报告 (VerificationRun 数据)
+-- generate_html(): 输出 HTML 报告
| +-- 覆盖率卡片: 段落覆盖率、分支覆盖率、决策点覆盖率
| +-- HINA 卡片: 判定类型、确信度
| +-- 质量评分卡片: quality_score
| +-- 重试历史卡片: heal_retry, simple_retry
| +-- 字段比对表格: PASS/MISMATCH 高亮
+-- 返回报告文件路径
3. DB 管道数据流
3.1 总体 6 步流程
COBOL 源码 (含 EXEC SQL)
|
v [Step 1: 环境整备]
step1_setup_environment()
+-- 复制源码到 ASCII 工作目录
+-- gixpp 预处理 + CONNECT TO 路径修补
+-- cobc 编译 -> exe_path
|
v [Step 2: 输入数据生成]
step2_generate_inputs(scenario)
+-- extract_structure() -> 分支树 + 赋值表
+-- generate_all_data() -> 测试数据记录
+-- _init_database() + _populate_database() -> SQLite DB 种子
+-- flatfile.write_all_files() -> 平面文件
|
v [Step 3: COBOL 执行]
step3_run_cobol(scenario)
+-- runner.run() -> 输出文件 + gcov 数据
|
v [Step 4: 中间数据提取]
step4_extract_intermediate()
+-- SELECT * FROM each table -> W01 JSON
|
v [Step 5: Java 执行] (可选)
step5_run_java()
+-- java -jar migration.jar -i W01.json -o output/
|
v [Step 6: 验证]
step6_verify()
+-- 比较 Java 输出与 COBOL 期望值
+-- 返回 VerificationRun (PASS/MISMATCH)
3.2 Step 1: 环境整备 (step1_setup_environment)
职责: gixpp 预处理 + cobc 编译
cobol_src_dir/{program_id}.cbl
|
v _copy_sources_to_workdir()
+-- 复制主源码 {program_id}.cbl -> work_dir/src/
+-- 复制 COPYBOOK (*.cpy) -> work_dir/src/
+-- 复制子程序 (SUB*.cbl) -> work_dir/src/
(搜索: cobol_src_dir, sub/, production/sub/, cobol-tna-system/sub/)
|
v runner.preprocess(src, preprocessed/, copybook_dirs)
+-- gixpp 预处理 + CONNECT TO 路径修补
| gixpp 错误转换: 'data/kin.db' -> 'sqlite://localhost/kin'
| 修补为: 'sqlite:///{db_path}'
|
v runner.compile(pp, exe, copybook_dirs, extra_srcs)
+-- cobc 编译 -> work_dir/bin/{program_id}.exe
+-- 编译日志写入 runtime_dir/logs/compile/
|
v 返回 DbPipelineResult(step=1, success, data={exe_path, log})
输入: cobol_src_dir, copybook_dirs, schema.subprograms 输出: src_path, pp_path, exe_path
3.3 Step 2: 输入数据生成 (step2_generate_inputs)
职责: COBOL 解析 -> 测试数据生成 -> DB 初始化 -> 平面文件输出
src_text + schema + scenario
|
v COBOL 解析
+-- extract_structure(src_text) -> 分支树 + 赋值表
+-- generate_all_data() -> 测试数据记录 (白盒+机能+策略)
+-- 后处理: R02APPL-ID 链接 R01APPL-ID
|
v DB 初始化
+-- 确定 DB 路径（场景分离: {program_id}_{scenario_id}.db）
+-- 清理旧 DB -> _init_database(db_path)
| +-- _create_tables(): 按 YAML schema 创建表 + 主键
+-- _populate_database(): 注入种子行
| +-- 解析 COBOL -> 分支树 -> 路径枚举
| +-- build_db_input(): 生成 DB 输入行
| | +-- collect_sql_meta(): 提取 SQL 元数据 (SELECT/INSERT/UPDATE/DELETE)
| | +-- _hostvar_root(): WHERE 宿主变量 MOVE 链解析
| | +-- _resolve_where_hostvar(): 宿主变量追溯到输入记录根字段
| | +-- 用输入键建种子（与运行时一致）
| +-- 覆盖率驱动数据补充（日期、假期等）
| +-- 区间协调（INSURANCE-RATES / EMP-MASTER）
| +-- INSERT OR IGNORE 写入 DB
+-- _inject_extra_seed_rows(): 大结果集注入
+-- _inject_sql_error_rows(): PK 冲突行注入
|
v 记录修补
+-- records[0].R01EMP-ID = SPACE（触发空社员路径）
+-- 全零 EMP-ID -> SPACE 清洗
+-- 注入重复 EMP-ID（AGG UPDATE 路径）
+-- _deduplicate_r01_pk(): PK 去重
+-- _inject_aggregation_boundaries(): 聚合边界数据
|
v 平面文件输出
+-- write_all_files(): 全 FD 平面文件
+-- write_sysin_file(): SYSIN 配置
|
v 返回 DbPipelineResult(step=2, data={records, flat_files, db_path})
输入: src_path, pp_path, schema, scenario 输出: generated_records, generated_structure, db_path, 平面文件
3.4 Step 3: COBOL 执行 (step3_run_cobol)
职责: 调用编译后的 COBOL 程序并收集 gcov 覆盖率数据
exe_path + schema + scenario
|
v 环境准备
+-- 创建 runtime/run_{id}/main/{input,output}/ 目录
+-- 复制生成的平面文件 -> input/
+-- 复制 JSON -> json/
|
v 文件方向映射 (_scan_assign_to)
+-- 正则扫描 SELECT/ASSIGN-TO -> {文件名: 方向}
+-- OPEN 语句解析 -> INPUT/OUTPUT 方向确定
|
v DB 路径准备
+-- 场景 DB -> 复制到默认 DB 路径
+-- CWD/data/kin.db（CONNECT TO 路径）
|
v 执行
+-- 清理前次 .gcda 文件
+-- runner.run(exe, cwd, db_path, env_overrides, command_args)
+-- 日志写入 runtime_dir/logs/
|
v gcov 数据收集
+-- .gcda 从 CWD + exe_dir 复制到 gcov/run_{id}/
+-- .gcno 同步（共享 .gcno，COPY 不 MOVE）
|
v 返回 DbPipelineResult(step=3, data={returncode, log, ...})
3.5 Step 4: 中间数据提取 (step4_extract_intermediate)
职责: 从 SQLite DB 导出 Java 程序所需的 JSON 中介数据
_current_db_path + schema.db_tables
|
v
+-- 打开 DB
+-- 遍历 schema.db_tables，对每张表执行 SELECT * FROM [table]
+-- 构建 meta = {program_id, tables: {table_name: [rows]}}
+-- 写入 work_dir/intermediate/{program_id}_W01.json
+-- 返回 DbPipelineResult(step=4, data={tables, w01_path})
3.6 Step 5: Java 执行 (step5_run_java)
职责: 调用 Java 转换程序处理 COBOL 输出数据
java_input_path + java_jar
|
v
+-- 创建 java_output 目录
+-- 构建命令: java -jar {java_jar} -i {java_input_path} -o {java_out}
+-- subprocess.run(cmd, capture_output=True, timeout=60)
+-- 返回 DbPipelineResult(step=5, data={returncode, log})
3.7 Step 6: 结果验证 (step6_verify)
职责: 比较 Java 输出与 COBOL 期望值
java_output_path + _current_db_path
|
v
+-- 构建 VerificationRun 结果对象
+-- 读取 DB 各表行数（调试信息）
+-- 扫描 java_output_path 下的 .txt/.json 文件
+-- 设置 exit_code 和 status（PASS/MISMATCH）
+-- 返回 VerificationRun
4. 核心数据结构
4.1 fields 列表格式
fields 是整个数据流的核心数据结构，贯穿输入-生成-运行全流程。
# 类型: list[dict]
# 来源: read.parse_data_division() + expand_occurs()
# 用途: 分支树构建、路径枚举、约束应用、JSON 输出
[
{
'name': str, # 字段名 (大写, 如 'R01EMP-ID')
'level': int, # 层号 (01, 05, 77, 88)
'pic': str | None, # PIC 子句原始文本
'pic_info': { # PIC 解析结果
'type': str, # 'numeric' | 'alphanumeric' | 'alphabetic' | 'unknown'
'digits': int, # 整数位数 (numeric)
'decimal': int, # 小数位数 (numeric)
'length': int, # 总长度 (alphanumeric)
'signed': bool, # 是否有符号
},
'section': str, # 'FILE' | 'WORKING-STORAGE' | 'LINKAGE'
'occurs': int, # OCCURS 次数 (0=无)
'occurs_depending': str | None, # OCCURS DEPENDING ON 目标
'redefines': str | None, # REDEFINES 目标字段名
'usage': str | None, # 'COMP' | 'COMP-3' | 'BINARY' | 'PACKED-DECIMAL' | 'DISPLAY'
'is_88': bool, # 是否 88 级条件
'parent': str | None, # 88 级父字段名
'value': str | None, # VALUE 子句值
'values': list[str] | None, # 88 级多值列表
'is_filler': bool, # 是否 FILLER
},
# ... 更多字段
]
4.2 Constraint 约束格式
Constraint 是路径枚举和约束应用的基本单元。
# 类型: tuple (4 元组)
# 定义: models.py 中 Constraint = tuple
# 格式: (field, operator, value, want_true)
Constraint = (
str, # field: 字段名 (如 'WRK-MONTH', 'R01EMP-ID')
str, # operator: 比较运算符 ('=' | '<>' | '>' | '<' | '>=' | '<=' | 'not_in')
str, # value: 比较值 (字符串形式, 如 '12', '00000000', 'SPACE')
bool, # want_true: True=满足条件, False=不满足条件
)
# 示例:
('WRK-MONTH', '>', '0', True) # WRK-MONTH > 0 为真
('R01EMP-ID', '<>', '00000000', True) # R01EMP-ID 不等于 00000000 为真
('SQLCODE', '=', '100', False) # SQLCODE = 100 为假 (即 SQLCODE != 100)
4.3 Path 路径格式
Path 是一条完整执行路径的所有约束集合。
# 类型: list[Constraint]
# 定义: models.py 中 Path = list[Constraint]
# 含义: 所有约束同时满足时，程序沿该路径执行
Path = [
('WRK-MONTH', '>', '0', True),
('WRK-MONTH', '<', '13', True),
('R01EMP-ID', '<>', '00000000', True),
('__DP', '=', 'T', True), # 决策点标记 (设计内部使用)
]
# path_infos 格式 (生成记录的输入):
path_infos = [
# (constraints, path_assignments, term_type)
(
[Constraint, ...], # 路径约束列表
{str: list[dict]}, # 赋值表 (目标 -> 赋值操作列表)
'normal' | 'abend', # 终止类型
),
# ... 更多路径
]
# 赋值表 (path_assignments) 格式:
{
'WRK-PREV-EMP-ID': [
{'type': 'move', 'source_vars': ['R01EMP-ID']}
],
'DBV-EMP-ID': [
{'type': 'move_literal', 'literal': 'A0000001'}
],
'WS-COUNT': [
{'type': 'compute', 'op': 'add', 'left': 'WS-COUNT', 'right': '1'}
],
}
4.4 测试数据 JSON 格式
测试数据 JSON 是非 DB 管道和 DB 管道共享的输出格式。
{
'program': str, # 程序名 (如 'KIN04CHK')
'records': [
{
'input': { # 按 FD 分组的输入字段
'FD_NAME': {
'FIELD1': str,
'FIELD2': str,
...
}
},
'expected_output': { # 按 FD 分组的期望输出字段
'FD_NAME': {
'FIELD1': str,
...
}
},
'working_storage': { # 不属于任何 FD 的工作存储字段
'WRK-MONTH': str,
'WS-COUNT': str,
...
},
'termination': str, # 'normal' | 'abend'
},
# ... 更多记录
],
'db_input': { # DB 管道专用: DB 种子数据 (可选)
'table_name': [
{'col1': val1, 'col2': val2, ...},
...
]
}
}
5. 数据流图
5.1 非 DB 管道完整流程 (Mermaid)
`mermaid flowchart TD A[COBOL 源码 .cbl] --> B[read.py preprocess] B --> C[read.py parse_data_division] C --> D[expand_occurs] D --> E[fields: list dict]
E --> F[core.py build_branch_tree]
F --> G[branch_tree + assignments]
G --> H[design.py enum_paths]
H --> I[path_infos]
I --> J[design.py generate_records]
E --> J
J --> K[records: list dict]
K --> L[output.py output_json]
L --> M[测试数据 JSON]
K --> N[output.py output_input_files]
K --> O[flatfile.write_all_files]
N --> P[固定长度平面文件]
O --> P
P --> Q[cobol_runner compile]
Q --> R[cobol_runner run]
R --> S[COBOL 输出文件]
S --> T[comparator/aligner align_records]
U[Java 输出文件] --> T
T --> V[记录对 pairs]
V --> W[comparator/normalizer]
W --> X[comparator/field_compare]
X --> Y[FieldResult list]
Y --> Z[report/generator generate_html]
Z --> AA[HTML 验证报告]
`
5.2 DB 管道完整流程 (Mermaid)
`mermaid flowchart TD A[COBOL 源码 含 EXEC SQL] --> B[Step 1: 环境整备] B --> B1[gixpp 预处理] B1 --> B2[cobc 编译] B2 --> B3[exe_path]
A --> C[Step 2: 输入数据生成]
B3 --> C
C --> C1[extract_structure]
C1 --> C2[generate_all_data]
C2 --> C3[records]
C3 --> C4[flatfile.write_all_files]
C4 --> C5[平面文件 input/]
C3 --> C6[build_db_input]
C6 --> C7[INSERT INTO SQLite DB]
C7 --> C8[db_path]
C5 --> D[Step 3: COBOL 执行]
C8 --> D
D --> D1[runner.run]
D1 --> D2[COBOL 输出文件]
D1 --> D3[gcov 数据]
D2 --> E[Step 4: 中间数据提取]
C8 --> E
E --> E1[SELECT * FROM tables]
E1 --> E2[W01 JSON]
E2 --> F[Step 5: Java 执行 可选]
F --> F1[java -jar migration.jar]
F1 --> F2[Java 输出文件]
F2 --> G[Step 6: 验证]
D2 --> G
G --> G1[VerificationRun]
G1 --> G2[PASS / MISMATCH]
`
5.3 数据流关键节点汇总
`mermaid flowchart LR subgraph 输入层 A1[COBOL 源码] A2[COPYBOOK] A3[YAML schema] end
subgraph 解析层
B1[preprocess]
B2[parse_data_division]
B3[build_branch_tree]
end
subgraph 生成层
C1[enum_paths]
C2[generate_records]
C3[build_db_input]
end
subgraph 输出层
D1[output_json]
D2[write_all_files]
D3[write_sysin_file]
end
subgraph 执行层
E1[cobol_runner]
E2[gixsql_runner]
E3[java -jar]
end
subgraph 验证层
F1[aligner]
F2[field_compare]
F3[coverage]
F4[report]
end
A1 --> B1 --> B2 --> B3
A2 --> B1
A3 --> C3
B3 --> C1 --> C2
C2 --> D1
C2 --> D2
C3 --> D2
C3 --> D3
D2 --> E1
D2 --> E2
D3 --> E2
E1 --> F1
E2 --> F1
E3 --> F1
F1 --> F2 --> F4
B3 --> F3 --> F4
`
6. 跨模块数据流转
6.1 模块间数据传递关系
| 源模块 | 目标模块 | 传递数据 | 数据格式 |
|---|---|---|---|
| read.py | core.py | preprocessed, data_fields | str, list[dict] |
| read.py | design.py | data_fields, open_dir, file_sec | list[dict], dict, dict |
| core.py | design.py | branch_tree, assignments | BrSeq, dict |
| cond.py | design.py | path constraints | list[Constraint] |
| design.py | output.py | records, kept_path_cons, term_types | list[dict], list, list[str] |
| design.py | to_sql.py | records, data_fields, assignments | list[dict], list[dict], dict |
| output.py | runner.py | records (JSON/binary) | dict, bytes |
| runner.py | comparator/ | output files | file paths |
| to_sql.py | orchestrator_db.py | db_input (DB seed rows) | dict[str, list[dict]] |
| flatfile.py | orchestrator_db.py | flat files (binary) | file paths |
| orchestrator_db.py | gixsql_runner.py | exe_path, db_path, env | Path, Path, dict |
| gixsql_runner.py | orchestrator_db.py | RunResult | dataclass |
| comparator/aligner.py | comparator/field_compare.py | aligned pairs | list[tuple] |
| comparator/field_compare.py | report/generator.py | FieldResults | list[FieldResult] |
| coverage.py | report/generator.py | DecisionPoints, coverage rates | list[DecisionPoint], float |
| data_merger.py | __init__.py | merged records | list[dict] |
| hina/strategy.py | data_merger.py | strategy records | list[dict] |
6.2 核心数据流路径
路径 1: 非 DB 管道 (flat file)
read.py (fields) -> core.py (branch_tree) -> design.py (records)
-> output.py (JSON + flat files) -> cobol_runner (output files)
-> comparator/ (verification results) -> report/ (HTML)
路径 2: DB 管道 (SQL/SQLite)
read.py (fields) -> core.py (branch_tree) -> design.py (records)
-> to_sql.py (DB seed rows) -> flatfile.py (flat files)
-> gixsql_runner (output files + DB state)
-> step4 (W01 JSON) -> step5 (Java output) -> step6 (verification)
路径 3: 覆盖率收集
core.py (branch_tree) -> coverage.py (decision_points)
-> mark_coverage (covered branches) -> gcov.py (dynamic coverage)
-> coverage.py (merged coverage) -> report/ (HTML report)
6.3 关键中间产物
| 产物 | 生成位置 | 消费位置 | 格式 |
|---|---|---|---|
| preprocessed | read.py | core.py, read.py | str (预处理后源码) |
| data_fields | read.py | core.py, design.py, to_sql.py | list[dict] |
| branch_tree | core.py | design.py, coverage.py | BrSeq |
| assignments | core.py | design.py, to_sql.py | dict |
| path_infos | design.py | design.py (generate_records) | list[tuple] |
| records | design.py | output.py, to_sql.py, flatfile.py | list[dict] |
| fd_fields | read.py | output.py | dict[str, set[str]] |
| open_dir | read.py | output.py, flatfile.py | dict[str, str] |
| file_sec | read.py | output.py, __init__.py | dict[str, list[str]] |
| db_input | to_sql.py | orchestrator_db.py | dict[str, list[dict]] |
| flat files | flatfile.py | runner.py | file paths (binary) |
| JSON | output.py | runner.py, coverage.py | file path |
| gcov data | gcov.py | coverage.py | dict[int, int] |
| DecisionPoints | coverage.py | report/generator.py | list[DecisionPoint] |
| VerificationRun | comparator/ | report/generator.py | dataclass |
| FieldResult | field_compare.py | report/generator.py | dataclass |