# 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. 创建并激活虚拟环境 (推荐): ```bash python -m venv venv source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows ``` 3. 安装依赖: ```bash 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 代码编写复杂的验证逻辑，是一种非常灵活的规则类型。示例： ```json { "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` 属性的规则文件： ```json { "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目录）： ```python # 在 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` 属性中指定的相对路径 使用外部文件的主要优势： - 更好的代码可读性和组织结构 - 支持代码编辑器的语法高亮和自动完成 - 便于版本控制和代码审查 - 可以更轻松地处理复杂逻辑和较长的代码 ## 运行 ```bash python -m ddms_compliance_suite.main ``` 您也可以通过导入模块方式在其他Python代码中使用本软件的功能： ```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})")