diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index e33e2f6..d71a86a 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -4,6 +4,12 @@ --- +### 2026-08-24 03:00:00 - 文档 +- **范式步骤：** V3总体设计文档更新 +- **修改摘要：** 更新00-overview.md，添加黑盒模块设计（2B章节）、PGMパターン、多KEY测试、黑盒数据流、双管道架构图 +- **涉及文件：** `docs/detailed-design/00-overview.md` +- **使用模型：** deepseek + ### 2026-08-24 02:00:00 - 文档 - **范式步骤：** README项目描述更新 - **修改摘要：** 更新项目描述和项目概述，添加业务场景、价值量化表格，明确白盒+黑盒双管道定位 diff --git a/docs/detailed-design/00-overview.md b/docs/detailed-design/00-overview.md index 520026d..b09ab91 100644 --- a/docs/detailed-design/00-overview.md +++ b/docs/detailed-design/00-overview.md @@ -1,6 +1,6 @@ # V3系统总体设计 -> 版本: v1.0 | 日期: 2026-08-22 +> 版本: v1.1 | 日期: 2026-08-24 > 本文档描述COBOL迁移验证平台V3的总体架构和模块设计。 --- @@ -9,17 +9,17 @@ ### 1.1 系统定位 -COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验证COBOL程序向Java/Spark迁移的正确性。 +COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验证COBOL程序向Java/Spark迁移的正确性。通过**白盒+黑盒双管道**自动生成测试数据，实现全分支路径覆盖验证。 ### 1.2 核心能力 | 能力 | 说明 | |------|------| -| COBOL源码解析 | 自动解析DATA DIVISION和PROCEDURE DIVISION | -| 测试数据生成 | 基于分支覆盖的测试数据自动生成 | -| 双管道验证 | 支持非DB（flat file）和DB（SQLite）两种验证模式 | +| 白盒分析 | 静态解析COBOL源码，自动识别分支路径，生成覆盖全路径的测试数据 | +| 黑盒生成 | 解析設計書自动识别程序模式（16种PGMパターン），LLM生成テストデータ | +| 双管道验证 | 白盒+黑盒并行运行，分别验证COBOL和Java/Spark输出 | | 覆盖率分析 | 静态分支覆盖 + 动态gcov覆盖 | -| AI辅助 | LLM驱动的程序分类和测试策略生成 | +| 多KEY测试 | 自动验证复合KEY的比较正确性 | ### 1.3 技术栈 @@ -43,33 +43,31 @@ COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验 │ V3系统架构 │ ├─────────────────────────────────────────────────────────────────┤ │ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ CLI入口 │ │ Web界面 │ │ API接口 │ │ -│ │ main.py │ │ web/ │ │ __init__ │ │ -│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ -│ │ │ │ │ -│ └────────────────────┼────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 统一入口 (run.py) │ │ +│ │ 白盒 cobol_testgen → 黑盒 black-box-data-create │ │ +│ └──────────────────────────────────────────────────────────┘ │ │ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────────────────────┐ │ -│ │ 编排层 (Orchestrator) │ │ -│ │ orchestrator.py (非DB) orchestrator_db.py (DB) │ │ -│ └─────────────────────────────────────────────────────────┘ │ -│ │ │ -│ ┌────────────────────┼────────────────────┐ │ -│ │ │ │ │ -│ ▼ ▼ ▼ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 核心引擎 │ │ 运行引擎 │ │ AI代理 │ │ -│ │ cobol_testgen│ │ runners/ │ │ agents/ │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ │ │ │ -│ │ │ │ │ -│ ▼ ▼ ▼ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 比对模块 │ │ 报告模块 │ │ 配置模块 │ │ -│ │ comparator/ │ │ report/ │ │ config/ │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ ┌────────────────────┴────────────────────┐ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────┐ ┌──────────────────────────┐ │ +│ │ 白盒管道 │ │ 黑盒管道 │ │ +│ │ cobol_testgen │ │ black-box-data-create │ │ +│ │ (静态分析+测试数据) │ │ (設計書解析+LLM生成) │ │ +│ └──────────────────────────┘ └──────────────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────┐ ┌──────────────────────────┐ │ +│ │ 编排层 │ │ 规则层 │ │ +│ │ orchestrator_db.py │ │ rules/pgm_pattern/ │ │ +│ └──────────────────────────┘ └──────────────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────┐ ┌──────────────────────────┐ │ +│ │ 运行引擎 │ │ LLM引擎 │ │ +│ │ runners/gixsql_runner │ │ DeepSeek API │ │ +│ └──────────────────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` @@ -80,9 +78,78 @@ COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验 |------|------|------| | **L1 数据层** | data/ | 共享数据模型 | | **L2 核心层** | cobol_testgen/, config/ | COBOL解析、配置管理 | -| **L3 业务层** | hina/, agents/, comparator/ | 分类、AI代理、比对 | +| **L3 业务层** | hina/, agents/, comparator/, black-box-data-create/ | 分类、AI代理、比对、黑盒生成 | | **L4 编排层** | orchestrator*, runners/ | 流程编排、执行 | -| **L5 接口层** | main.py, web/, __init__.py | 用户接口 | +| **L5 接口层** | main.py, run.py, web/, __init__.py | 用户接口 | + +--- + +## 二-B、黑盒模块设计 + +### 2B.1 模块概述 + +black-box-data-create 是基于詳細設計書的LLM数据生成模块，通过解析設計書/COPY句定義書/DB定義書，自动生成テストデータ。 + +### 2B.2 处理流程 + +``` +詳細設計書 + COPY句定義書 + DB定義書 + COBOL源码 + │ + ▼ +InputParser: 解析設計書中的入出力定義、処理内容 + │ + ▼ +RuleLoader: 按PGMパターン匹配规则文件 + │ + ▼ +PromptBuilder: 组装DeepSeek API提示词 + │ + ▼ +APIClient: 调用DeepSeek API生成テストデータ + │ + ▼ +OutputWriter: 输出JSON/SQL文件 +``` + +### 2B.3 PGMパターン + +| パターン | 说明 | 对应程序 | +|----------|------|----------| +| マッチング(1:1) | 1对1匹配 | KIN01INP, KIN02UPD | +| マッチング(1:N) | 1对多匹配 | KIN03EXP | +| マッチング(N:1) | 多对1匹配 | KIN04CHK | +| DB更新 | 数据库更新 | KIN08DBU | +| 振り分け(IF) | IF条件分支 | KIN05MAT | +| 振り分け(EVALUATE) | EVALUATE分支 | KIN07DAI | +| 項目チェック | 字段校验 | ZAN01CHK, ZAN02CHK | +| キーブレイク(集計) | KEY-break汇总 | SHA01SIF | +| キーブレイク(集約) | KEY-break聚合 | SHA02MNC | +| SELECT処理 | SELECT查询 | KYU04CAL | +| MERGE | 合并处理 | KIN06CLD | +| CSV→FB変換 | CSV转flat file | KIN09CSV | + +### 2B.4 多KEY测试 + +对于复合KEY程序（如 A001+A002+A003），自动生成各KEY变形的追加データ： + +| 变形类型 | 说明 | +|----------|------| +| KEY1変更 | 仅改变KEY1，验证KEY1比较正确性 | +| KEY2変更 | 仅改变KEY2，验证KEY2比较正确性 | +| KEY3変更 | 仅改变KEY3，验证KEY3比较正确性 | + +### 2B.5 模块文件 + +| 文件 | 职责 | +|------|------| +| agent/__init__.py | generate() 入口 | +| agent/models.py | 数据クラス定義 | +| agent/input_parser.py | 設計書 + COPYBOOK + DB定義解析 | +| agent/rule_loader.py | PGMパターン→ルール匹配 | +| agent/prompt_builder.py | API提示词组装 | +| agent/api_client.py | DeepSeek API调用（3回重试） | +| agent/output_writer.py | JSON/SQL文件输出 | +| main.py | CLI入口 | --- @@ -92,7 +159,8 @@ COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验 | 模块 | 文件数 | 行数 | 职责 | |------|--------|------|------| -| cobol_testgen/ | 22 | ~8000 | COBOL解析、测试数据生成 | +| cobol_testgen/ | 22 | ~8000 | COBOL解析、白盒测试数据生成 | +| black-box-data-create/ | 8 | ~5000 | 設計書解析、黑盒LLM数据生成 | | orchestrator_db.py | 1 | 1334 | DB管道6步编排 | | runners/ | 8 | ~600 | 编译运行引擎 | | hina/ | 11 | ~2000 | HINA程序分类 | @@ -100,6 +168,7 @@ COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验 | comparator/ | 6 | ~400 | 字段比对 | | config/ | 5 | ~300 | 配置管理 | | report/ | 1 | ~200 | 报告生成 | +| run.py | 1 | 86 | 全流程统一入口 | ### 3.2 模块依赖关系 @@ -117,6 +186,18 @@ models.py (零依赖) ├── flatfile.py (read, file_io) │ └── __init__.py (所有上层模块) + +black-box-data-create/ + │ + ├── models.py (零依赖) + ├── markdown_utils.py (stdlib) + ├── input_parser.py (models, markdown_utils) + ├── rule_loader.py (models) + ├── prompt_builder.py (models) + ├── api_client.py (requests) + ├── output_writer.py (models) + │ + └── __init__.py (所有上层模块) ``` --- @@ -178,6 +259,47 @@ orchestrator_db.py: step5_run_java() (可选) orchestrator_db.py: step6_verify() ``` +### 4.3 黑盒管道数据流 + +``` +詳細設計書.md + │ + ▼ +input_parser.py: 解析設計書 + COPY句定義書 + DB定義書 + │ + ▼ +rule_loader.py: PGMパターン匹配 → 选择规则文件 + │ + ▼ +prompt_builder.py: 组装API提示词 + │ + ▼ +api_client.py: DeepSeek API调用（3回重试） + │ + ▼ +output_writer.py: 输出JSON/SQL文件 + │ + ▼ +output/{プログラムID}/g{N}/{プログラムID}_g{N}.json +output/{プログラムID}/g{N}/{プログラムID}_g{N}.sql +``` + +### 4.4 全流程数据流（run.py） + +``` +run.py + │ + ├── 步骤1: cobol_testgen（白盒） + │ ├── 静态分析 + 测试数据生成 + │ ├── 编译运行 COBOL 程序 + │ └── gcov 覆盖率收集 + │ + └── 步骤2: black-box-data-create（黑盒） + ├── 解析設計書 + COPY + DB定義 + ├── LLM 生成 JSON/SQL + └── 输出到 output/{程序ID}/g{N}/ +``` + --- ## 五、接口设计 @@ -207,6 +329,24 @@ def main(): pass ``` +```python +# black-box-data-create/agent/__init__.py + +def generate( + design_md: str, + source_cbl: str, + file_db_md: str, + cpy_dir: str, + db_md: str, + output_dir: str = "output", + api_key: str = None, + model: str = None, + rules_dir: str = None, +) -> dict: + """黑盒数据生成入口""" + pass +``` + ### 5.2 配置接口 ```python @@ -235,6 +375,8 @@ class Config: | 编译错误 | cobc编译失败 | 记录日志，跳过该程序 | | 运行错误 | 程序执行异常 | 捕获异常，标记失败 | | 超时错误 | 执行超时 | 强制终止，记录超时 | +| API错误 | DeepSeek API调用失败 | 3回重试，失败后跳过 | +| 設計書解析错误 | 設計書格式不正确 | 记录警告，使用默认值 | ### 6.2 容错机制 @@ -242,6 +384,8 @@ class Config: - **LLM失败**：回退到规则引擎 - **gcov失败**：跳过覆盖率收集 - **DB连接失败**：重试或跳过 +- **API重试**：DeepSeek API 3回重试机制 +- **JSON解析容错**：支持非标准JSON格式 --- @@ -255,6 +399,7 @@ class Config: | 测试数据生成 | < 30秒 | | 编译运行 | < 60秒 | | 覆盖率报告 | < 10秒 | +| 黑盒数据生成 | < 120秒（含API调用） | ### 7.2 优化策略 @@ -262,6 +407,7 @@ class Config: - **并行执行**：多场景gcov并行收集 - **缓存机制**：LLM结果缓存 - **增量补充**：质量门循环最多4次 +- **API重试**：3回重试机制，避免单次失败 --- @@ -272,12 +418,14 @@ class Config: - COBOL源码：长度限制、编码检查 - 配置文件：YAML schema验证 - 文件路径：路径遍历防护 +- 設計書：格式验证、大小写检查 ### 8.2 资源限制 - LLM调用：最大成本限制 - 执行时间：超时强制终止 - 内存使用：大文件分块处理 +- API限流：避免超过API配额 --- @@ -296,6 +444,8 @@ class Config: - 43个COBOL基准程序 - 33+2种程序类型 - 58个电信测试程序 +- 16种PGMパターン +- 24个黑盒测试程序 --- @@ -314,11 +464,12 @@ class Config: ```bash # 1. 安装Python依赖 -pip install lark pathlib pyyaml +pip install lark pathlib pyyaml requests # 2. 安装GnuCOBOL # 下载GC32-BDB-SP1，添加到PATH # 3. 验证安装 python -c "from cobol_testgen import extract_structure; print('OK')" +python -c "from blackbox.agent import generate; print('OK')" ```