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

2026-07-15 22:08:03 +08:00
parent 54d4e81240
commit bf207c20f5
2 changed files with 211 additions and 19 deletions
@@ -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/` 目录)