feat: V3系统评审问题修复

1. 场景价值与技术合理性修复： - 补充docs/SCENE_VALUE.md（业务背景、痛点分析、用户场景、竞品对比、价值量化） - 添加用户操作流程图（Mermaid） - 添加3个真实业务案例量化数据 2. 演示与文档修复： - 创建docs/API.md（完整API文档） - 创建docs/QUICKSTART.md（5分钟快速入门指南） 3. AI使用日志修复： - 更新AGENTS.md，添加强制自动执行的AI使用日志记录指令 - 在_AI_USAGE_LOG.md末尾添加范式执行统计 4. 安全性修复： - 在agents/llm.py中添加输入过滤（防Prompt注入） - 添加输出验证、速率限制、详细日志 5. 架构设计修复： - 创建tools/registry.py工具注册表 - 修改orchestrator.py和orchestrator_db.py使用注册表动态获取运行器 6. 开发范式修复： - 在_AI_USAGE_LOG.md末尾添加范式执行统计
2026-08-29 13:23:28 +08:00
parent c6fa6b1aeb
commit b94757d9df
69 changed files with 1941 additions and 221 deletions
@@ -0,0 +1,345 @@
+# COBOL → Java/Spark 迁移验证平台 API 文档
+
+> 版本: v1.0 | 日期: 2026-08-28
+
+---
+
+## 一、核心模块 API
+
+### 1.1 cobol_testgen 模块
+
+#### 主入口
+
+```python
+from cobol_testgen import main
+
+# 运行测试数据生成
+main(cobol_files, output_dir, config=None)
+```
+
+**参数说明：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `cobol_files` | `list[str]` | COBOL源码文件路径列表 |
+| `output_dir` | `str` | 输出目录路径 |
+| `config` | `dict` | 可选配置参数 |
+
+#### FieldTree 类
+
+```python
+from cobol_testgen.read import FieldTree
+
+# 解析COBOL源码
+tree = FieldTree(copybook_name="example")
+
+# 获取字段列表
+fields = tree.flatten()  # 返回 dict[str, Field]
+```
+
+#### Field 类
+
+```python
+from cobol_testgen.read import Field
+
+# 字段属性
+field.name      # 字段名
+field.level     # 层级
+field.pic       # PIC子句
+field.usage     # USAGE类型
+field.offset    # 偏移量
+field.length    # 长度
+field.decimal   # 小数位
+field.signed    # 是否有符号
+field.occurs    # OCCURS次数
+field.redefines # REDEFINES字段
+field.conditions # 88级条件
+field.children  # 子字段
+```
+
+### 1.2 coverage 模块
+
+```python
+from cobol_testgen.coverage import CoverageAnalyzer
+
+# 创建覆盖率分析器
+analyzer = CoverageAnalyzer()
+
+# 标记覆盖情况
+analyzer.mark_coverage(decision_points, path_assignments)
+
+# 生成HTML报告
+analyzer.generate_report(output_path)
+```
+
+### 1.3 design 模块
+
+```python
+from cobol_testgen.design import DesignAnalyzer
+
+# 创建设计分析器
+analyzer = DesignAnalyzer()
+
+# 枚举路径
+paths = analyzer.enum_paths(field_tree, mode="rule")  # mode: "rule" | "ai"
+
+# 生成测试记录
+records = analyzer.generate_records(paths, field_tree)
+```
+
+---
+
+## 二、编排器 API
+
+### 2.1 orchestrator 模块（非DB管道）
+
+```python
+from orchestrator import Orchestrator
+
+# 创建编排器
+orch = Orchestrator(config)
+
+# 运行完整验证流程
+result = orch.run(cobol_source, design_doc)
+
+# 返回结果
+result.status        # "pass" | "fail"
+result.coverage      # 覆盖率百分比
+result.test_cases    # 测试用例列表
+result.diff_results  # 差异比对结果
+```
+
+### 2.2 orchestrator_db 模块（DB管道）
+
+```python
+from orchestrator_db import OrchestratorDB
+
+# 创建DB编排器
+orch = OrchestratorDB(config)
+
+# 运行DB管道验证
+result = orch.run(cobol_source, design_doc)
+
+# 返回结果
+result.status        # "pass" | "fail"
+result.db_coverage   # DB相关覆盖率
+result.sql_results   # SQL执行结果
+```
+
+---
+
+## 三、Runner API
+
+### 3.1 CobolRunner
+
+```python
+from runners import CobolRunner
+
+# 创建COBOL运行器
+runner = CobolRunner()
+
+# 编译并运行COBOL程序
+result = runner.compile_and_run(source_file, input_data)
+
+# 返回结果
+result.output        # 程序输出
+result.return_code   # 返回码
+result.coverage_data # 覆盖率数据
+```
+
+### 3.2 JavaRunner
+
+```python
+from runners import NativeJavaRunner, SparkJavaRunner
+
+# 创建Java运行器
+runner = NativeJavaRunner()  # 或 SparkJavaRunner(spark_master)
+
+# 运行Java程序
+result = runner.run(class_path, input_data)
+
+# 返回结果
+result.output        # 程序输出
+result.return_code   # 返回码
+```
+
+---
+
+## 四、Comparator API
+
+```python
+from comparator import FieldComparator
+
+# 创建字段比对器
+comparator = FieldComparator()
+
+# 比对COBOL和Java输出
+results = comparator.compare(cobol_output, java_output)
+
+# 返回结果
+for result in results:
+    result.field_name   # 字段名
+    result.cobol_value  # COBOL值
+    result.java_value   # Java值
+    result.status       # "match" | "mismatch"
+    result.diff_type    # 差异类型
+```
+
+---
+
+## 五、Agents API
+
+### 5.1 LLMClient
+
+```python
+from agents.llm import LLMClient
+
+# 创建LLM客户端
+client = LLMClient(model="deepseek-v4-flash", timeout=15)
+
+# 调用LLM
+response = client.call(messages, retries=1)
+
+# 参数说明
+messages: list[dict]  # 消息列表，格式: [{"role": "system"|"user", "content": "..."}]
+retries: int          # 重试次数
+```
+
+### 5.2 Agent1Parser
+
+```python
+from agents.agent1_parser import Agent1Parser
+
+# 创建解析Agent
+parser = Agent1Parser(llm_client)
+
+# 解析COBOL COPYBOOK
+field_tree = parser.parse(cobol_text)
+
+# 返回FieldTree对象
+```
+
+### 5.3 Agent2Data
+
+```python
+from agents.agent2_data import Agent2Data
+
+# 创建数据生成Agent
+agent = Agent2Data(llm_client)
+
+# 生成测试数据
+test_suite = agent.design(field_tree, target="boundary", spark_mode=False)
+
+# 返回TestSuite对象
+```
+
+### 5.4 Agent3Diagnostic
+
+```python
+from agents.agent3_diagnostic import Agent3Diagnostic
+
+# 创建诊断Agent
+agent = Agent3Diagnostic(llm_client)
+
+# 分析差异
+diagnosis = agent.analyze(field_result)
+
+# 返回诊断结果字符串
+```
+
+---
+
+## 六、数据模型
+
+### 6.1 TestCase
+
+```python
+from data.test_case import TestCase
+
+# 测试用例
+tc = TestCase(
+    id="TC-001",
+    fields={"FIELD1": value1, "FIELD2": value2},
+    coverage_targets=["DP-001", "DP-002"]
+)
+```
+
+### 6.2 TestSuite
+
+```python
+from data.test_case import TestSuite
+
+# 测试套件
+suite = TestSuite(test_cases=[tc1, tc2, tc3])
+suite.spark_config  # 可选Spark配置
+```
+
+### 6.3 FieldResult
+
+```python
+from data.diff_result import FieldResult
+
+# 字段比对结果
+result = FieldResult(
+    field_name="AMOUNT",
+    cobol_value="1000",
+    java_value="1000",
+    status="match"
+)
+```
+
+---
+
+## 七、配置参数
+
+### 7.1 全局配置
+
+```python
+CONFIG = {
+    "proc_parser": "rule",      # "rule" | "ai"
+    "llm_generator": True,      # 是否使用LLM生成测试数据
+    "coverage_target": 0.75,    # 目标覆盖率
+    "max_paths": 100,           # 最大路径数
+}
+```
+
+### 7.2 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `LLM_API_KEY` | LLM API密钥 | - |
+| `LLM_MODEL` | LLM模型名称 | `deepseek-v4-flash` |
+| `LLM_API_BASE` | LLM API地址 | `https://api.openai.com/v1` |
+| `DEEPSEEK_API_KEY` | DeepSeek API密钥 | - |
+
+---
+
+## 八、错误处理
+
+### 8.1 常见异常
+
+| 异常类型 | 说明 | 处理方式 |
+|----------|------|----------|
+| `FileNotFoundError` | 文件不存在 | 检查文件路径 |
+| `json.JSONDecodeError` | JSON解析失败 | 检查输入格式 |
+| `LLMError` | LLM调用失败 | 重试或检查API密钥 |
+| `CompilationError` | COBOL编译失败 | 检查源码语法 |
+
+### 8.2 错误恢复
+
+```python
+try:
+    result = orch.run(cobol_source, design_doc)
+except LLMError:
+    # 降级到规则引擎
+    config["proc_parser"] = "rule"
+    result = orch.run(cobol_source, design_doc)
+except CompilationError as e:
+    # 记录编译错误
+    logger.error(f"Compilation failed: {e}")
+    result = {"status": "error", "message": str(e)}
+```
+
+---
+
+*本文档最后更新：2026-08-28*