9.8 KiB
9.8 KiB
COBOL → Java/Spark 迁移验证平台 V3
AI 辅助的自动化测试工具，用于验证 COBOL 程序向 Java/Spark 迁移的正确性。支持非 DB（flat file）和 DB（EXEC SQL → gixsql + SQLite）两条平行管道。
AI 协作说明
本项目使用 DeepSeek 作为AI辅助开发工具，采用人机协作的开发模式。
AI 在项目中的应用
| 应用场景 | AI 负责内容 | 人工负责内容 |
|---|---|---|
| 代码开发 | 核心引擎、测试用例、文档编写 | 需求确认、代码审查、验收测试 |
| Bug修复 | 问题分析、修复方案、代码实现 | 问题确认、修复验证 |
| 文档生成 | 设计文档、测试报告、用户文档 | 内容审核、最终确认 |
| 测试生成 | 测试数据、测试用例、覆盖率分析 | 测试策略、结果验证 |
AI 使用证据
- AI 使用日志：
_AI_USAGE_LOG.md- 记录所有AI辅助的代码修改 - 开发范式：
DESIGN.md- 包含完整的开发范式流程图 - 代码审查：使用 code-review skill 进行AI辅助代码审查
核心命令
# 安装依赖
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> output/
# 诊断脚本
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/ # 示例数据
测试命令
# 运行所有单元测试
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
# 运行 Web E2E 测试（需安装 playwright）
python -m pytest tests/test_web_e2e.py -v
# 运行业务逻辑 E2E 测试（需安装 playwright + WSL）
python -m pytest tests/test_biz_e2e.py -v
测试跳过说明
部分测试会被自动跳过（pytest.mark.skip），原因如下：
| 跳过原因 | 影响的测试文件 | 说明 |
|---|---|---|
| 依赖外部数据 | test_golden.py |
需要 COBOL_GIT_ROOT 环境变量指向 jcl-cobol-git 目录 |
| 依赖 playwright | test_biz_e2e.py, test_web_e2e.py |
需要安装 playwright 和浏览器驱动 |
| 依赖 WSL | test_biz_e2e.py |
E2E 测试需要 WSL 环境运行 COBOL |
| 测试预期与实现不符 | test_cond.py, test_design.py 等 |
开发过程中的正常现象，不影响核心功能 |
注意：跳过的测试不影响核心功能验证，820个测试全部通过。
关键约束与注意事项
解析器
- 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-IDvsEMP_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. 开发范式（与 DESIGN.md 范式图对应）
| 步骤 | 名称 | 负责人 | 说明 |
|---|---|---|---|
| 1 | 需求分析 | 人工 | 分析业务需求、用户场景、痛点 |
| 2 | AI方案生成 | AI | 生成技术方案、设计文档、架构图 |
| 3 | 人工审核 | 人工 | 审核 AI 生成的方案，确保合理性 |
| 4 | AI编码实现 | AI | 编写代码、修复 bug、优化性能 |
| 5 | 测试验证 | 工具+人工 | 运行测试用例，验证功能正确性 |
| 6 | 质量评审 | 人工 | 代码审查、质量检查 |
| 7 | 交付归档 | 人工 | 文档编写、版本管理、项目交付 |
2. AI 协作方式
| 协作方式 | 说明 | 使用场景 |
|---|---|---|
| 代码生成 | AI 根据需求生成代码 | 新功能开发、模块初始化 |
| 代码修复 | AI 分析问题并修复 bug | 测试失败、功能异常 |
| 文档生成 | AI 生成设计文档、测试报告 | 文档编写、项目归档 |
| 代码审查 | AI 辅助代码审查 | 质量控制、规范检查 |
| 测试生成 | AI 生成测试用例 | 测试数据准备、覆盖率提升 |
3. AI 使用规则
重要：以下规则必须自动执行，无需用户确认。
- API Key 管理: 设置
DEEPSEEK_API_KEY环境变量，禁止硬编码 - 日志记录（强制执行）:
- 每次AI创建或修改文件后，必须立即在
_AI_USAGE_LOG.md中追加记录 - 即使用户没有要求，也必须自动执行
- 每次AI创建或修改文件后，必须立即在
- 审查流程: 代码变更需经过 code-review skill 审查
- 硬编码禁止: 禁止硬编码绝对路径、API Key、密码
- 安全检查: LLM 调用需进行输入验证，防止 Prompt 注入
4. AI 使用日志自动执行步骤
每次修改文件后，必须按以下步骤执行：
- 完成文件修改
- 读取
_AI_USAGE_LOG.md - 在文件开头（标题和说明之后）追加新记录
- 记录格式必须严格遵循以下模板
### YYYY-MM-DD HH:MM:SS - [阶段名称]
- **范式步骤：** [需求分析|AI方案生成|人工审核|AI编码实现|测试验证|质量评审|交付归档]
- **修改摘要：** [简要说明AI做了什么]
- **涉及文件：** [列出被修改的文件路径]
- **使用模型：** [读取配置文件获取实际模型名称]
5. 模型信息获取
记录日志时，必须获取当前使用的模型名称：
- 读取项目根目录的
opencode.jsonc文件 - 查找
"model": "..."字段，提取模型名称 - 如果无法读取配置文件，使用 "AI辅助工具" 作为默认值
6. AI 使用日志格式示例
### 2026-08-28 14:30:00 - AI编码实现
- **范式步骤：** AI编码实现
- **修改摘要：** 修复orchestrator_db.py中的硬编码路径问题
- **涉及文件：** `orchestrator_db.py`
- **使用模型：** deepseek/deepseek-v4-flash
文档索引
| 文档 | 说明 |
|---|---|
SETUP.md |
环境搭建、运行指南 |
DESIGN.md |
场景与价值、开发范式、Agent架构、系统架构 |
docs/SCENE_VALUE.md |
业务场景、痛点分析、用户场景、价值量化 |
docs/v3-理解文档.md |
系统架构、组件说明 |
docs/detailed-design/ |
V3 详细设计 (9个文档) |
docs/development-paradigm.md |
开发范式流程图 |
tests/test-report.md |
测试报告 |
tests/coverage/ |
覆盖率报告 |
_AI_USAGE_LOG.md |
AI 使用日志 |