docs: 完成缺口分析项3-7 - AGENTS.md、README完善、测试报告、示例数据、Agent架构图

2026-08-22 22:35:49 +08:00
parent 57db3a3ee6
commit 459e05a4c0
8 changed files with 708 additions and 7 deletions
@@ -0,0 +1,145 @@
+# COBOL → Java/Spark 迁移验证平台 V3
+
+AI 辅助的自动化测试工具，用于验证 COBOL 程序向 Java/Spark 迁移的正确性。支持非 DB（flat file）和 DB（EXEC SQL → gixsql + SQLite）两条平行管道。
+
+## 核心命令
+
+```bash
+# 安装依赖
+pip install lark pathlib pyyaml
+
+# 运行非 DB 回归测试
+python test-data/s15_coverage_verification.py
+
+# 运行 DB 端到端测试
+python test-data/s30_db_e2e.py
+
+# 单程序运行（自动路由）
+python -m cobol_testgen ../cobol-tna-system/src/KIN01INP.cbl
+
+# 带 gcov 覆盖率的单程序运行
+python -m cobol_testgen --gcov <cobol_src> runtime/
+
+# 诊断脚本
+python diagnose_db2.py          # DB 全流程
+python diagnose_kind8dbrun.py   # DB 编译运行
+```
+
+## 架构
+
+```
+CLI (main.py)
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   编排层 (Orchestrator)                       │
+│  orchestrator.py (非DB)    orchestrator_db.py (DB)          │
+└─────────────────────────────────────────────────────────────┘
+    │
+    ├──┬──────────┬──────────┬──────────┬──────────┐
+    ▼  ▼          ▼          ▼          ▼          ▼
+cobol_testgen   runners   comparator  agents     hina/
+(数据生成)     (编译运行)  (比对验证)   (LLM)    (分类)
+    │
+    ├── config/
+    │
+    └── report/
+```
+
+## 目录结构
+
+```
+cobol-java-v3/
+├── cobol_testgen/           # 核心引擎 (~8000行)
+│   ├── __init__.py          # 公开 API 入口
+│   ├── models.py            # 共享数据模型 (零依赖)
+│   ├── read.py              # INPUT: 预处理 + DATA DIVISION 解析
+│   ├── core.py              # CORE: 分支树构建
+│   ├── cond.py              # CONDITION: 条件解析 + MC/DC
+│   ├── design.py            # DESIGN: 路径枚举 + 值生成
+│   ├── coverage.py          # COVERAGE: 覆盖标记 + HTML 报告
+│   ├── output.py            # OUTPUT: JSON 输出
+│   └── to_sql.py            # SQL 辅助: WHERE 约束解析
+├── runners/                 # 编译运行引擎
+│   ├── cobol_runner.py      # GnuCOBOL 编译运行
+│   └── gixsql_runner.py     # DB 管道编译运行
+├── agents/                  # LLM 代理
+│   └── api_client.py        # DeepSeek API 调用
+├── comparator/              # 字段比对
+├── hina/                    # HINA 程序分类
+├── config/                  # 配置管理
+├── report/                  # 报告生成
+├── test-data/               # 测试套件
+├── tests/                   # 单元测试 (80+文件)
+├── benchmark-programs/      # 43个基准 COBOL 程序
+├── docs/                    # 文档
+│   ├── detailed-design/     # V3 详细设计 (9个文档)
+│   └── development-paradigm.md
+└── sample/                  # 示例数据
+```
+
+## 测试命令
+
+```bash
+# 运行所有单元测试
+python -m pytest tests/ -v
+
+# 运行核心引擎测试
+python -m pytest tests/cobol_testgen/ -v
+
+# 运行覆盖率验证
+python test-data/s15_coverage_verification.py
+
+# 运行 DB 端到端测试
+python test-data/s30_db_e2e.py
+```
+
+## 关键约束与注意事项
+
+### 解析器
+- **Lark 语法** (`grammar.lark`): Earley parser, dynamic lexer
+- **命名终端**: 必须使用 `USAGE_VAL` 而非内联字符串
+- **88 级限制**: 目标程序无 88 级 VALUE 子句
+- **REDEFINES/FILLER**: 捕获但跳过 (debug 日志警告)
+
+### 路径枚举
+- **MC/DC 条件**: 支持 AND/OR/NOT 复合条件
+- **路径上限**: 规则引擎 100 路径, LLM 模式 5000 路径
+- **O(N) 算法**: 避免 O(2^N) 爆炸
+
+### DB 管道
+- **gixsql**: 预处理 EXEC SQL → SQLite
+- **种子键一致性**: WHERE 宿主变量 MOVE 链解析到输入记录根字段
+- **列名归一化**: `-`/`_` 容忍 (`EMP-ID` vs `EMP_ID`)
+
+### 覆盖率
+- **分支覆盖率目标**: 75%
+- **条件覆盖率**: 75% (`_FUNC_MOD` 合成函数不可匹配)
+- **HTML 报告**: 全中文 (标题、图例、徽章)
+
+## 环境要求
+
+- Python 3.12+ (`lark`, `pyyaml`)
+- GnuCOBOL 3.2.0 (GC32-BDB-SP1)
+- gixsql (已 vendored 在 `gixsql/` 目录)
+- DeepSeek API (可选, 用于 LLM 路径生成)
+
+## AI 使用规范
+
+本项目使用 DeepSeek 作为 AI 辅助工具。使用时需注意:
+
+1. **API Key**: 设置 `DEEPSEEK_API_KEY` 环境变量
+2. **日志记录**: 所有 AI 生成/修改的文件需记录在 `_AI_USAGE_LOG.md`
+3. **审查流程**: 代码变更需经过 code-review skill 审查
+4. **硬编码禁止**: 禁止硬编码绝对路径、API Key、密码
+
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| `SETUP.md` | 环境搭建、运行指南 |
+| `docs/v3-理解文档.md` | 系统架构、组件说明 |
+| `docs/detailed-design/` | V3 详细设计 (9个文档) |
+| `docs/development-paradigm.md` | 开发范式流程图 |
+| `docs/test-report.md` | 测试报告 |
+| `_AI_USAGE_LOG.md` | AI 使用日志 |