60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# pbl_validation —— PBL 校验引擎（M2）
|
||
|
||
14 维校验 + 5 级质量状态（quality_state），阈值配置化常量（`mcRatio=0.7`，Q-OPEN-8），
|
||
输出固定契约 `pbl.validation.report/1.0` 的校验报告。
|
||
|
||
## 目录结构
|
||
```
|
||
modules/pbl_validation/
|
||
├── pbl_validation/ # Python 包（模块本体，无 app.py）
|
||
│ ├── __init__.py # 导出：load_pbl_validation + 5 契约 + 引擎纯函数 + 常量
|
||
│ ├── constants.py # 阈值配置化常量 / 5 级质量状态 / 严重度 / 阈值合并校验
|
||
│ ├── dimensions.py # 14 维定义 + CheckContext + DimResult/Issue + 14 个 checker
|
||
│ ├── engine.py # 引擎主入口 run_validation + decide_quality_state + 报告契约
|
||
│ ├── api.py # 5 个契约接口（.dspy）+ DB 适配（q_all/q_one/tenant_id）
|
||
│ └── init.py # load_pbl_validation()：库名解析/建表/契约注册/规则种子
|
||
├── sql/pbl_validation.sql # 2 张表 DDL + 14 条内置规则种子（幂等）
|
||
├── scripts/load_path.py # 模块路径与契约清单注册
|
||
├── tests/test_validation_engine.py # 111 项断言自测（纯函数层，无需 DB）
|
||
├── skill/SKILL.md # 模块技能文档（详细规范）
|
||
└── pyproject.toml
|
||
```
|
||
|
||
## 快速使用
|
||
```python
|
||
from pbl_validation import run_validation, is_publishable
|
||
|
||
report = run_validation(blueprint_dict, tenant_id="t1", blueprint_id="BP1", version="v1")
|
||
print(report["quality_state"], report["total_score"]) # Q4_EXCELLENT 0.97
|
||
ok, msg = is_publishable(report) # 发布门禁：需 >= Q3_GOOD
|
||
```
|
||
|
||
契约接口（HTTP）：
|
||
```
|
||
POST /pbl_validation/api/pbl_validation_run.dspy {"tenant_id":"t1","blueprint":{...}}
|
||
POST /pbl_validation/api/pbl_validation_get.dspy {"tenant_id":"t1","result_id":"vr_x"}
|
||
POST /pbl_validation/api/pbl_validation_list.dspy {"tenant_id":"t1","page":1,"page_size":20}
|
||
POST /pbl_validation/api/pbl_validation_rule_list.dspy {"tenant_id":"t1"}
|
||
POST /pbl_validation/api/pbl_validation_rule_save.dspy {"tenant_id":"t1","dim":"D08","thresholds":{"mcRatio":0.8}}
|
||
```
|
||
|
||
## 14 维 / 5 级
|
||
- 维度：D01 结构完整性、D02 命名规范、D03 学习目标对齐、D04 驱动问题质量、D05 角色设计、
|
||
D06 场景设计、D07 实体模型、D08 任务链完整性（含 mcRatio 多路径覆盖率）、
|
||
D09 规则引用完整性、D10 评估量规、D11 产出物绑定、D12 难度平衡、D13 时长平衡、
|
||
D14 安全合规。
|
||
- 质量状态：`Q0_DRAFT` / `Q1_INCOMPLETE` / `Q2_BASIC` / `Q3_GOOD` / `Q4_EXCELLENT`，
|
||
由 R1~R8 规则自上而下短路判定（详见 skill/SKILL.md）。
|
||
|
||
## 自测
|
||
```bash
|
||
cd modules/pbl_validation && python3 tests/test_validation_engine.py
|
||
# PASSED: 111 FAILED: 0
|
||
```
|
||
|
||
## 铁律
|
||
- 库名只用 `ServerEnv().get_module_dbname('pbl_validation')`，禁止硬编码 DBNAME；
|
||
- 所有读写强制带 `tenant_id`，缺失 fail-closed；
|
||
- sqlor 只用 `C/U/D/R/I/sqlExe`，查询走 `q_all/q_one`；
|
||
- 引擎为纯函数（无 DB/网络/随机），确定性可复现。
|