DDMS 合规性验证软件

本项目旨在开发一套DDMS（领域数据管理服务）合规性验证软件。该软件能够自动化地对注册到DMS平台的第三方DDMS进行一系列检查，包括API接口行为、数据模型的规范性、业务流程的正确性、以及数据质量等，确保其符合DMS平台定义的数据共享标准和技术规范。

项目结构

ddms_compliance_suite/
├── ddms_compliance_suite/      # Python 包的根目录 (应用核心代码)
│   ├── __init__.py
│   ├── main.py                 # 应用主入口
│   │
│   ├── api_caller/             # API 调用模块
│   │   ├── __init__.py
│   │   └── caller.py           # API 调用逻辑
│   │
│   ├── assertion_engine/       # 断言引擎模块
│   │   ├── __init__.py
│   │   └── engine.py           # 断言逻辑
│   │
│   ├── config/                 # 配置管理模块
│   │   ├── __init__.py
│   │   └── manager.py          # 配置加载与管理
│   │
│   ├── input_parser/           # 输入解析模块
│   │   ├── __init__.py
│   │   └── parser.py           # 输入文件解析逻辑
│   │
│   ├── json_schema_validator/  # JSON Schema 验证模块
│   │   ├── __init__.py
│   │   └── validator.py        # Schema 验证逻辑
│   │
│   ├── logging_service/        # 日志服务模块
│   │   ├── __init__.py
│   │   └── logger.py           # 日志配置与记录
│   │
│   ├── models/                 # Pydantic 数据模型
│   │   ├── __init__.py
│   │   ├── base_models.py      # 基础模型或通用模型
│   │   ├── config_models.py    # 应用配置相关模型
│   │   ├── rule_models.py      # 规则库相关模型
│   │   └── validation_models.py # 验证输入/输出相关模型
│   │
│   ├── report_generator/       # 报告生成模块
│   │   ├── __init__.py
│   │   └── generator.py        # 报告生成逻辑
│   │
│   ├── rule_repository/        # 规则库模块
│   │   ├── __init__.py
│   │   ├── repository.py       # 规则库核心逻辑
│   │   └── adapters/           # 规则存储适配器
│   │       ├── __init__.py
│   │       ├── base_adapter.py # 适配器基类
│   │       └── filesystem_adapter.py # 文件系统适配器
│   │
│   └── test_executor/          # 测试执行器模块
│       ├── __init__.py
│       └── executor.py         # 测试编排与执行逻辑
│
├── configs/                    # 配置文件存放目录
│   └── config.yaml.example     # 示例配置文件
│
├── rules/                      # 规则文件存放目录 (JSON格式)
│   ├── api_linting_rules/      # API Linting 规则
│   │   └── api-naming-convention/
│   │       └── 1.0.0.json      # 版本化的规则文件
│   ├── business_logic_rules/   # 业务逻辑规则/断言模板
│   │   └── well-id-format-rule/
│   │       └── 1.0.0.json
│   ├── data_quality/           # 数据质量校验规则
│   │   └── well-depth-range-check/
│   │       └── 1.0.0.json
│   └── json_schemas/           # JSON Schema 文件
│       └── well-data-schema/
│           └── 1.0.0.json
│
├── tests/                      # 测试代码目录
│   ├── __init__.py
│   ├── test_api_caller.py
│   ├── test_json_schema_validator.py
│   └── test_rule_repository.py
│
├── README.md                   # 项目说明文件
└── requirements.txt            # Python 依赖库列表

安装

1. 克隆仓库
2. 创建并激活虚拟环境 (推荐):

   python -m venv venv
   source venv/bin/activate  # macOS/Linux
   # venv\Scripts\activate  # Windows
   

3. 安装依赖:

   pip install -r requirements.txt
   

配置

编辑 configs/config.yaml (可以从 configs/config.yaml.example 复制开始)。这个配置文件包含了各个模块的设置，特别是规则库模块的配置，例如规则文件的存储路径等。

规则库

规则库是本系统的核心组件之一，它使用JSON文件格式存储各类规则，包括：

• JSON Schema 规则: 用于验证API请求/响应的数据结构
• 业务逻辑断言: 定义业务规则和验证逻辑
• API Linting 规则: 用于检查API设计是否符合规范
• 数据质量规则: 用于验证数据的质量和准确性
• Python 代码规则: 使用 Python 代码实现复杂的验证逻辑

规则文件结构

规则文件按照类别和版本存储在 rules/ 目录下。每个规则都有一个唯一的ID和版本号，使用以下目录结构:

rules/
  <规则类别>/
    <规则ID>/
      <版本号>.json

添加新规则

要添加新规则，只需在适当的目录下创建新的JSON文件并遵循规则模型的结构。每个规则必须包含id, name, category, version等基本字段，以及该类别特定的字段。

参考 rules/ 目录下的示例规则文件以了解格式要求。

Python 代码规则

Python 代码规则允许您使用 Python 代码编写复杂的验证逻辑，是一种非常灵活的规则类型。示例：

{
  "id": "complex-validation-rule",
  "name": "复杂验证规则",
  "description": "使用Python代码实现复杂的验证逻辑",
  "category": "PythonCode",
  "version": "1.0.0",
  "severity": "error",
  "is_enabled": true,
  "tags": ["validation"],
  "target_type": "DataObject",
  "target_identifier": "Example",
  "allow_imports": true,
  "allowed_modules": ["math", "re", "json", "datetime"],
  "code": "def validate():\n    # In this location write validation logic\n    return {'is_valid': True, 'message': '验证通过'}"
}

Python 代码规则的主要字段：

• code: 包含 Python 代码的字符串
• code_file: 外部Python代码文件的路径（作为code的替代选项）
• entry_function: 入口函数名（默认为 validate）
• expected_parameters: 规则执行时需要的参数列表
• allow_imports: 是否允许导入外部模块
• allowed_modules: 允许导入的模块列表
• timeout: 代码执行超时时间（秒）

出于安全考虑，Python 代码在受控环境中执行，对可访问的资源和操作进行限制。代码应定义一个与 entry_function 指定名称相同的函数，并在参数列表中包含 expected_parameters 中的所有参数。

从外部文件加载Python代码

对于较长的复杂Python代码，可以将代码单独存储在外部文件中，而不是嵌入到JSON规则文件里。这样可以提高代码的可读性和维护性。方法如下：

1. 创建具有 code_file 属性而非 code 属性的规则文件：

{
  "id": "well-coordinates-validation",
  "name": "井坐标复杂验证规则",
  "description": "验证井的坐标数据，包括检查是否在特定区域内、坐标系转换等",
  "category": "PythonCode",
  "version": "1.0.0",
  "severity": "error",
  "is_enabled": true,
  "target_type": "DataObject",
  "target_identifier": "Well",
  "allow_imports": true,
  "allowed_modules": ["math", "re", "json", "datetime"],
  "entry_function": "validate",
  "expected_parameters": ["well_data"],
  "timeout": 5,
  "code_file": "python_code/well-coordinates-validation/1.0.0.py"
}

2. 在对应的路径创建Python代码文件（相对于rules目录）：

# 在 rules/python_code/well-coordinates-validation/1.0.0.py 文件中
import math

def validate():
    # 在这里编写复杂验证逻辑
    return {'is_valid': True, 'message': '验证通过'}

3. 系统会自动加载并执行外部Python文件中的代码：
   • 如果规则中指定了id和version，系统会查找 rules/python_code/{id}/{version}.py
   • 否则，系统会使用 code_file 属性中指定的相对路径

使用外部文件的主要优势：

• 更好的代码可读性和组织结构
• 支持代码编辑器的语法高亮和自动完成
• 便于版本控制和代码审查
• 可以更轻松地处理复杂逻辑和较长的代码

运行

python -m ddms_compliance_suite.main

您也可以通过导入模块方式在其他Python代码中使用本软件的功能：

from ddms_compliance_suite.config.manager import ConfigurationManager
from ddms_compliance_suite.rule_repository.repository import RuleRepository

# 加载配置
config_manager = ConfigurationManager(config_path="path/to/config.yaml")
config = config_manager.get_config()

# 初始化规则库
rule_repo = RuleRepository(config.rule_repository)

# 查询规则
from ddms_compliance_suite.models.rule_models import RuleQuery, TargetType
query = RuleQuery(target_type=TargetType.API_RESPONSE, target_identifier="getWellData")
rules = rule_repo.query_rules(query)

# 输出查询到的规则
for rule in rules:
    print(f"Rule: {rule.name} (ID: {rule.id}, Version: {rule.version})")