docs: 更新V3总体设计文档，添加黑盒模块设计、PGMパターン、多KEY测试

_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项目描述更新
 - **修改摘要：** 更新项目描述和项目概述，添加业务场景、价值量化表格，明确白盒+黑盒双管道定位

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 |
+| 白盒分析 | 静态解析COBOL源码，自动识别分支路径，生成覆盖全路径的测试数据 |
-| 测试数据生成 | 基于分支覆盖的测试数据自动生成 |
+| 黑盒生成 | 解析設計書自动识别程序模式（16种PGMパターン），LLM生成テストデータ |
-| 双管道验证 | 支持非DB（flat file）和DB（SQLite）两种验证模式 |
+| 双管道验证 | 白盒+黑盒并行运行，分别验证COBOL和Java/Spark输出 |
 | 覆盖率分析 | 静态分支覆盖 + 动态gcov覆盖 |
-| AI辅助 | LLM驱动的程序分类和测试策略生成 |
+| 多KEY测试 | 自动验证复合KEY的比较正确性 |
 
 ### 1.3 技术栈
 
@@ -43,33 +43,31 @@ COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验
 │                        V3系统架构                                │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
-│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
+│  ┌──────────────────────────────────────────────────────────┐  │
-│  │  CLI入口     │     │  Web界面     │     │  API接口     │    │
+│  │                    统一入口 (run.py)                      │  │
-│  │  main.py     │     │  web/        │     │  __init__    │    │
+│  │         白盒 cobol_testgen → 黑盒 black-box-data-create  │  │
-│  └──────┬───────┘     └──────┬───────┘     └──────┬───────┘    │
+│  └──────────────────────────────────────────────────────────┘  │
-│         │                    │                    │            │
-│         └────────────────────┼────────────────────┘            │
 │                              │                                 │
-│                              ▼                                 │
+│         ┌────────────────────┴────────────────────┐            │
-│  ┌─────────────────────────────────────────────────────────┐  │
+│         │                                         │            │
-│  │                   编排层 (Orchestrator)                   │  │
+│         ▼                                         ▼            │
-│  │  orchestrator.py (非DB)    orchestrator_db.py (DB)      │  │
+│  ┌──────────────────────────┐       ┌──────────────────────────┐ │
-│  └─────────────────────────────────────────────────────────┘  │
+│  │      白盒管道            │       │      黑盒管道            │ │
-│                              │                                 │
+│  │  cobol_testgen           │       │  black-box-data-create   │ │
-│         ┌────────────────────┼────────────────────┐            │
+│  │  (静态分析+测试数据)     │       │  (設計書解析+LLM生成)    │ │
-│         │                    │                    │            │
+│  └──────────────────────────┘       └──────────────────────────┘ │
-│         ▼                    ▼                    ▼            │
+│         │                                         │            │
-│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
+│         ▼                                         ▼            │
-│  │  核心引擎    │     │  运行引擎    │     │  AI代理      │    │
+│  ┌──────────────────────────┐       ┌──────────────────────────┐ │
-│  │ cobol_testgen│     │  runners/    │     │  agents/     │    │
+│  │      编排层              │       │      规则层              │ │
-│  └──────────────┘     └──────────────┘     └──────────────┘    │
+│  │  orchestrator_db.py      │       │  rules/pgm_pattern/      │ │
-│         │                    │                    │            │
+│  └──────────────────────────┘       └──────────────────────────┘ │
-│         │                    │                    │            │
+│         │                                         │            │
-│         ▼                    ▼                    ▼            │
+│         ▼                                         ▼            │
-│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
+│  ┌──────────────────────────┐       ┌──────────────────────────┐ │
-│  │  比对模块    │     │  报告模块    │     │  配置模块    │    │
+│  │      运行引擎            │       │      LLM引擎             │ │
-│  │ comparator/  │     │  report/     │     │  config/     │    │
+│  │  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')"
 ```