docs: add README.md, update SETUP.md with DB pipeline documentation

README.md

@@ -0,0 +1,70 @@
+# COBOL → Java/Spark 迁移验证平台 v3
+
+自动解析 COBOL 源码，生成覆盖全分支路径的测试数据，分别运行 COBOL 和 Java/Spark 两个版本，逐字段比对输出，判定迁移正确性。
+
+支持 **非 DB**（flat file I-O）和 **DB**（EXEC SQL → gixsql + SQLite）两条平行管道。
+
+## 快速开始
+
+```bash
+# 安装依赖
+pip install lark pathlib pyyaml
+
+# 运行非 DB 回归测试
+python test-data/s15_coverage_verification.py
+
+# 运行 DB 端到端测试（需设置环境变量，见 SETUP.md）
+python test-data/s30_db_e2e.py
+
+# 单程序运行（自动路由：含 EXEC SQL → DB 管道，否则非 DB）
+python -m cobol_testgen ../cobol-tna-system/src/KIN01INP.cbl
+```
+
+## 架构
+
+```
+CLI → orchestrator / orchestrator_db
+        │
+  ┌─────┼──────┬──────────┬──────────┐
+  ▼     ▼      ▼          ▼          ▼
+cobol_testgen  runners   comparator  agents
+(数据生成)    (编译运行)  (比对验证)  (LLM)
+```
+
+两条管道自动路由：
+- **非 DB**：`cobc` 编译 → flat file 二进制比对
+- **DB**：`gixpp` ESQL 预处理 → `cobc -l gixsql` 编译 → SQLite 表比对
+
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| `SETUP.md` | 环境搭建、运行指南、检查清单（含 DB 管道） |
+| `docs/v3-理解文档.md` | 系统架构、组件说明、数据流（中文，457 行） |
+| `docs/changelog-v1-to-v3.md` | V1→V3 演进记录 |
+| `docs/module-interfaces.md` | 模块接口定义 |
+| `DESIGN.md` | Web UI 设计规范 |
+| `CONTRIBUTING.md` | 贡献指南 |
+
+## 核心命令
+
+```bash
+# 非 DB 全量覆盖率报告
+python test-data/s25_per_program_report.py
+
+# DB 端到端测试
+python test-data/s30_db_e2e.py
+
+# 带 gcov 覆盖率的单程序运行
+python -m cobol_testgen --gcov <cobol_src> runtime/
+
+# 诊断脚本
+python diagnose_db2.py          # DB 全流程
+python diagnose_kind8dbrun.py   # DB 编译运行
+```
+
+## 依赖
+
+- **Python 3.12+** + `lark`, `pyyaml`
+- **GnuCOBOL 3.2.0** (GC32-BDB-SP1，含 DB2/SQLite 支持)
+- **gixsql** (已 vendored 在 `gixsql/` 目录)

SETUP.md

@@ -4,15 +4,19 @@
 
 COBOL 测试数据生成器（cobol-java-v3）是一个 Python 工具链，用于解析 COBOL 程序、提取控制流结构、生成覆盖所有分支的测试数据，并输出为固定的 flat file 格式供 GnuCOBOL 编译运行。
 
+系统支持两条平行的测试管道：**非 DB 管道**（flat file I-O 程序 → cobc 编译运行 → 二进制比对）和 **DB 管道**（EXEC SQL 程序 → gixpp ESQL 预处理 → cobc + libgixsql 编译运行 → SQLite 表比对），自动根据源码中是否包含 `EXEC SQL` 路由到对应管道。
+
 ### 核心能力
 
 | 能力 | 说明 |
 |------|------|
 | 解析 COBOL DATA DIVISION | Lark 语法 (Earley parser) → 字段定义 |
-| 解析 COBOL PROCEDURE DIVISION | 行级状态机 → 决策点树 |
+| 解析 COBOL PROCEDURE DIVISION | 行级状态机 → 决策点树 + EXEC SQL 抽取 |
 | 分支覆盖数据生成 | 每决策点生成 True/False 路径 → 记录 |
-| Flat file 输出 | COBOL 固定长度二进制文件 |
-| GnuCOBOL 编译运行 | 测试数据 → cobc 编译 → 运行验证 |
+| Flat file + SQLite DB 双输出 | 非 DB 程序→二进制 flat file；DB 程序→flat file + SQLite 表行 |
+| GnuCOBOL 编译运行 (非 DB) | 测试数据 → `cobc` 编译 → 运行 → 二进制比对 |
+| gixsql 编译运行 (DB) | `gixpp` ESQL 预处理 → `cobc -l gixsql` 编译 → SQLite 运行 → 表比对 |
+| 覆盖率报告 (gcov) | `--gcov` 模式下编译带 `-g --coverage`，合并后生成 HTML 报告 |
 
 ---
 
@@ -32,7 +36,8 @@ COBOL 测试数据生成器（cobol-java-v3）是一个 Python 工具链，用
 | 软件 | 版本 | 用途 |
 |------|------|------|
 | **Python** | 3.12+ | 运行测试数据生成器 |
-| **GnuCOBOL (cobc)** | 3.2.0 | 编译 COBOL 程序 & 运行时验证 |
+| **GnuCOBOL (cobc)** | 3.2.0 (GC32-BDB-SP1) | 编译 COBOL 程序 & 运行时验证（DB 管道需要含 SQLite 支持的版本） |
+| **gixsql** | 已 vendored (`gixsql/`) | ESQL 预处理器 (`gixpp.exe`) + 运行时 DLL (`libgixsql.dll`)，DB 管道必备 |
 | **Git** | 任意 | 拉取代码 |
 
 ### 2.3 Python 依赖
@@ -40,11 +45,12 @@ COBOL 测试数据生成器（cobol-java-v3）是一个 Python 工具链，用
 ```
 lark>=1.1.0          # Lark Earley parser (DATA DIVISION 解析)
 pathlib>=1.0.1       # 路径处理
+pyyaml>=6.0          # YAML 配置加载（DB 管道：per-program schema）
 ```
 
 安装命令：
 ```bash
-pip install lark pathlib
+pip install lark pathlib pyyaml
 ```
 
 ### 2.4 GnuCOBOL 安装
@@ -67,8 +73,13 @@ cobc --version
 # 典型路径: C:\GnuCOBOL\bin
 # 或自定义安装路径
 
-# COB_LIBRARY_PATH 用于运行时定位 DLL（SHARED 编译的子程序）
-# 如: set COB_LIBRARY_PATH=D:\cobol-java\cobol-tna-system\bin
+# COB_LIBRARY_PATH — 运行时 DLL 搜索路径
+# 非 DB 管道：子程序 DLL 目录（如 cobol-tna-system\bin）
+# DB 管道：必须包含 gixsql\lib\（libgixsql.dll, libgcc_s_dw2-1.dll 等）
+#   如: set COB_LIBRARY_PATH=D:\cobol-java\cobol-java-v3\gixsql\lib
+
+# GIXSQL_DB_PATH — DB 管道 SQLite 数据库路径（默认 C:\Temp\gix\）
+#   如: set GIXSQL_DB_PATH=C:\Temp\gix
 ```
 
 ---
@@ -83,7 +94,7 @@ cobc --version
 python --version
 # Python 3.12.x
 
-pip install lark pathlib
+pip install lark pathlib pyyaml
 ```
 
 ### 3.2 安装 GnuCOBOL 3.2
@@ -122,27 +133,52 @@ python -c "from cobol_testgen import extract_structure; print('OK')"
 ```
 cobol-java-v3/
 ├── cobol_testgen/             # 核心代码
-│   ├── __init__.py            # 公开 API (extract_structure, generate_data)
-│   ├── read.py                # 预处理器 + DATA DIVISION 解析
-│   ├── core.py                # 旧 PROCEDURE DIVISION 解析器 (BrParser)
+│   ├── __init__.py            # 公开 API (extract_structure, generate_data) + DB 自动路由
+│   ├── read.py                # 预处理器 + DATA DIVISION 解析 + EXEC SQL INCLUDE 解决
+│   ├── core.py                # 旧 PROCEDURE DIVISION 解析器 + EXEC SQL 抽取
 │   ├── cond.py                # 条件解析器
-│   ├── coverage.py            # 覆盖率统计
+│   ├── coverage.py            # 覆盖率统计 (+ gcov HTML 报告)
 │   ├── design_mcdc.py         # 线性路径枚举 (O(N) 替代 O(2^N))
 │   ├── pipeline_bridge.py     # 新旧解析器桥接层
 │   ├── procedure_parser.py    # 新 PROCEDURE DIVISION 解析器
 │   ├── flatfile.py            # Flat file 写入器
 │   ├── design.py              # 值生成 + 约束应用
+│   ├── to_sql.py              # SQL 约束解析 + DB 行生成 (DB 管道)
 │   ├── models.py              # 数据模型 (BrSeq, BrIf, BrEval...)
 │   ├── grammar.lark           # DATA DIVISION Lark 语法
 │   └── procedure_grammar.lark # PROCEDURE DIVISION Lark 语法 (实验性)
+├── orchestrator_db.py         # DB 6 步管道编排 (GixsqlOrchestrator)
+├── runners/                   # 编译运行引擎
+│   ├── cobol_runner.py        # 标准 GnuCOBOL runner（非 DB）
+│   ├── gixsql_runner.py       # gixpp + cobc runner（DB）
+│   ├── native_java_runner.py  # 原生 Java runner
+│   ├── spark_java_runner.py   # Spark Java runner
+│   ├── data_writer.py         # 测试数据写入器
+│   └── runner.py              # 基类
+├── config/
+│   ├── program_schema.py      # DB 程序 schema 加载器
+│   └── programs/              # per-program YAML 配置（6 个 DB 程序）
+│       ├── KIN02UPD.yaml
+│       ├── KIN03EXP.yaml
+│       ├── KIN06CLD.yaml
+│       ├── KIN08DBU.yaml
+│       ├── KIN09CSV.yaml
+│       └── ZAN06UPD.yaml
+├── gixsql/                    # 已 vendored ESQL 工具链
+│   ├── bin/gixpp.exe          # ESQL 预处理器
+│   └── lib/*.dll              # 运行时 (libgixsql, libgixsql-sqlite, libgcc 等)
 ├── test-data/                 # 测试套件
 │   ├── s15_coverage_verification.py   # 基础覆盖率验证 (8种控制结构)
 │   ├── s19_final_bridge_test.py       # 桥接器验证
 │   ├── s21_cond_fix_verify.py         # 条件解析验证
 │   ├── s25_per_program_report.py      # 每程序详细报告
-│   └── s26_regression_check.py        # 回归检查
+│   ├── s26_regression_check.py        # 回归检查
+│   └── s30_db_e2e.py                 # DB 端到端测试 (ZAN06UPD)
+├── diagnose_db2.py            # DB 全流程诊断脚本
+├── diagnose_kind8dbrun.py     # DB 单步诊断 (仅编译运行)
 ├── SETUP.md                  # 本文件
 └── docs/                      # 设计文档
+└── runtime/                   # 运行产物（测试数据、输入文件、覆盖率报告，已 gitignore）
 ```
 
 ---
@@ -197,6 +233,40 @@ st = extract_structure(src)
 recs = generate_data(src, st, copybook_dirs=["path/to/copybooks"])
 ```
 
+### 5.5 DB 端到端测试（5 分钟）
+
+DB 管道需要使用 `cobol-tna-system` 同级项目中的 DB 程序（含 `EXEC SQL` 的 COBOL 源码）：
+
+```bash
+# 1. 确认同级目录存在 cobol-tna-system
+dir ..\cobol-tna-system
+
+# 2. 设置环境变量
+set COB_LIBRARY_PATH=<proj_dir>\gixsql\lib
+mkdir C:\Temp\gix 2>nul
+set GIXSQL_DB_PATH=C:\Temp\gix
+
+# 3. 运行 DB 端到端测试 (ZAN06UPD - 6 步管线: 编译→生成数据→运行→提取→Java→比对)
+python test-data\s30_db_e2e.py
+```
+
+期望输出末尾：
+```
+COVERAGE: DB pipeline E2E PASSED
+```
+
+### 5.6 DB 单程序运行
+
+```bash
+# 自动路由: 源码含 EXEC SQL → DB 管道，否则走非 DB 管道
+python -m cobol_testgen ..\cobol-tna-system\src\ZAN06UPD.cbl
+
+# 带 gcov 覆盖率收集 (编译带 -g --coverage，生成 HTML 报告)
+python -m cobol_testgen --gcov ..\cobol-tna-system\src\KIN08DBU.cbl runtime\
+```
+
+DB 管道会自动加载 `config/programs/<PROGRAM_ID>.yaml` 中的表定义、子程序列表、运行场景（normal/collision/abnormal），多场景运行的 gcov 覆盖率会被合并输出。
+
 ---
 
 ## 6. 关键 API
@@ -242,7 +312,45 @@ dps = cov["decision_points"]  # 各决策点明细
 
 ---
 
-## 7. 运行条件明细（同事配置检查清单）
+## 7. DB 管道概述
+
+系统包含两条平行管道，根据 COBOL 源码是否包含 `EXEC SQL` 自动路由：
+
+| 方面 | 非 DB 管道 | DB 管道 |
+|------|------------|---------|
+| **入口** | `main.py` → `orchestrator.py` | Python CLI 自动检测 `EXEC SQL` → `orchestrator_db.py: GixsqlOrchestrator` |
+| **编译器** | `cobc -E` + 标准编译 | `gixpp.exe` (ESQL 预处理) + `cobc -l gixsql` |
+| **运行时** | 平面二进制文件 (I-O) | SQLite DB (EXEC SQL) + 平面文件 (顺序 I-O) |
+| **数据生成** | 分支覆盖记录集 | 分支覆盖记录集 + SQLite 表行 (按 WHERE 约束生成) |
+| **程序配置** | 无 | `config/programs/<ID>.yaml` (表定义、子程序、场景) |
+| **验证** | 二进制平面文件比对 | SQLite 表行比对 + Java 中间 JSON (W01.json) |
+| **覆盖率** | 静态分支覆盖 | 动态 gcov 覆盖率 (跨场景合并) |
+| **Java 集成** | Native Java / Spark Java | Java 读取中间 JSON |
+
+### 7.1 DB 管道 6 步流程
+
+| 步骤 | 方法 | 说明 |
+|------|------|------|
+| **1** | `step1_setup_environment` | gixpp ESQL 预处理 → cobc 编译（链接 libgixsql），避免中文路径问题 |
+| **2** | `step2_generate_inputs` | 解析 COBOL → 分支覆盖数据 + SQLite 表行（含正/异常场景） |
+| **3** | `step3_run_cobol` | 运行编译后 .exe（GIXSQL_DB_PATH 环境变量），收集 gcov |
+| **4** | `step4_extract_intermediate` | 读取 SQLite 表 → 中间 JSON（W01.json，供 Java 消费） |
+| **5** | `step5_run_java` | 执行 Java JAR，以中间 JSON 为输入 |
+| **6** | `step6_verify` | Java 输出 vs COBOL 预期值比对 |
+
+### 7.2 前置条件
+
+- **`cobol-tna-system` 同级项目**: DB 程序源码需位于 `../cobol-tna-system/src/`（或通过 `config/programs/*.yaml` 配置路径）
+- **`config/programs/<PROGRAM_ID>.yaml`**: 每个 DB 程序必须有对应的 YAML schema，定义：
+  - `db_tables`: 表名、列类型、主键
+  - `subprograms`: 子程序列表（编译时链接）
+  - `runs`: 运行场景（normal / collision / abnormal），每种场景可配置不同的 sysin 和预期输出
+- **`C:\Temp\gix\`**: SQLite 数据库存放目录（由 `GIXSQL_DB_PATH` 指定）
+- **`COB_LIBRARY_PATH`**: 必须包含 `gixsql/lib/`（运行时载入 `libgixsql.dll`）
+
+---
+
+## 8. 运行条件明细（同事配置检查清单）
 
 ### 必须满足
 
@@ -259,6 +367,15 @@ dps = cov["decision_points"]  # 各决策点明细
 - [ ] 子程序 DLL 路径在 `COB_LIBRARY_PATH` 环境中
 - [ ] EXEC SQL 需要 SQLite3 支持（GC32-BDB-SP1 版本含）
 
+### DB 管道额外检查
+
+- [ ] `gixsql/bin/gixpp.exe` 存在（vendored ESQL 预处理器）
+- [ ] `COB_LIBRARY_PATH` 包含 `<proj>/gixsql/lib/`（运行时 DLL）
+- [ ] `GIXSQL_DB_PATH` 已设置（如 `C:\Temp\gix`），目录存在
+- [ ] `config/programs/<ID>.yaml` 存在（per-program schema）
+- [ ] `../cobol-tna-system/` 同级目录存在（DB 程序源码）
+- [ ] `pip install pyyaml` 执行成功
+
 ### 常见问题
 
 | 问题 | 原因 | 解决 |
@@ -269,10 +386,14 @@ dps = cov["decision_points"]  # 各决策点明细
 | `gbk codec can't decode byte` | 编码问题 | 设置 `PYTHONIOENCODING=utf-8` |
 | `name 'pp_str' is not defined` | 报告脚本 Bug | 已修复，git pull 最新代码 |
 | `EXEC SQL ... not supported` | 需要 DB2/SQLite | 用 GC32-BDB-SP1 版本 GnuCOBOL |
+| `gixpp: command not found` | gixsql/bin 不在 PATH | `$env:PATH += ";<proj>\\gixsql\\bin"` |
+| `Cannot load libgixsql.dll` | COB_LIBRARY_PATH 未设置 | `$env:COB_LIBRARY_PATH = "<proj>\\gixsql\\lib"` |
+| `GIXSQL_DB_PATH not set` | SQLite 路径未指定 | `mkdir C:\Temp\gix -Force; $env:GIXSQL_DB_PATH = "C:\Temp\gix"` |
+| `config/programs/<ID>.yaml not found` | DB 程序缺少 schema | 补充对应 YAML 配置文件 |
 
 ---
 
-## 8. 测试基准程序说明
+## 9. 测试基准程序说明
 
 系统包含两套测试基准程序：
 
@@ -284,19 +405,20 @@ COPYBOOK: common/copybooks/
 类型: Matching / KeyBreak / Division / CSV / Sort 等
 ```
 
-### 勤怠管理系统 (6 程序)
+### 勤怠管理系统 (22 程序)
 
 ```
 路径: D:\cobol-java\cobol-tna-system/
 COPYBOOK: cpy/
 子程序: sub/*.cbl → bin/*.dll
 类型: 日企勤怠管理 (打工统计)
-EXEC SQL: ZAN06UPD 需要 SQLite3 支持
+DB 程序 (EXEC SQL): KIN02UPD, KIN03EXP, KIN06CLD, KIN08DBU, KIN09CSV, ZAN06UPD — 共 6 个
+非 DB 程序: KIN01INP, KIN04CHK, KIN05MAT, KIN07DAI, ZAN01CHK–ZAN05CAL, KYU01CVT–KYU09MRG — 共 16 个
 ```
 
 ---
 
-## 9. 快速启动脚本
+## 10. 快速启动脚本
 
 ### Windows (batch)
 
@@ -333,7 +455,7 @@ echo "=== DONE ==="
 
 ---
 
-## 10. 版本信息
+## 11. 版本信息
 
 | 版本 | 日期 | 说明 |
 |:----:|:----:|------|