96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# pbl_blueprint —— PBL 蓝图聚合根与子对象、版本、模板（M1a）
|
||
|
||
PBL（Project-Based Learning）平台的**蓝图域基础模块**。蓝图是整个 PBL 系统的
|
||
聚合根：一份蓝图定义了一个项目的学习目标、角色分工、驱动问题（Mission）、任务、
|
||
产出物规格、证据规格与反思规格，并带完整版本历史（`change_delta` 记录对话式改
|
||
模型的每一步）。模板（`pbl_template`）提供蓝图骨架与 LLM 不可用时的离线兜底槽位。
|
||
|
||
## 特性
|
||
|
||
- **多租户强制打头**：所有表的第二列即 `tenant_id`，所有读写 SQL 的 WHERE 第一
|
||
条件必须是 `tenant_id`；上下文缺失时 **fail-closed 抛 `PblTenantMissing`**，
|
||
绝不降级为全租户可见。
|
||
- **聚合根 + 7 类子对象**：`learning_goal / role / mission / task /
|
||
artifact_spec / evidence_spec / reflection_spec`，统一走
|
||
`pbl_blueprint_subobject_save|list|delete` 三个泛化契约，新增子对象类型只需在
|
||
`api.py: SUBOBJECTS` 注册一行 + 加 models/json 定义。
|
||
- **版本化**：任何主表/子对象变更都会自动升 `version_no` 并追加一条
|
||
`pbl_blueprint_version` 记录（含 `change_delta` 与全量 `snapshot_json`），
|
||
为 M2 校验引擎与 M3 Compiler 提供可追溯的模型演化证据。
|
||
- **模板实例化 + 离线兜底**：`pbl_template_instantiate` 展开
|
||
`blueprint_snapshot`，缺失字段用 `offline_slots[].default` 填充（LLM 不可用
|
||
时仍能产出可用蓝图）。
|
||
- **派生（fork）**：深拷贝聚合根与全部子对象，并重映射子对象之间的引用
|
||
（`mission_id / task_id / artifact_spec_id / role_id`）。
|
||
- **状态保护**：`status='published'` 的蓝图禁止直接改主表/子对象/删除，必须先
|
||
fork 或回退状态（`PblStateConflict`）。
|
||
|
||
## 数据表（10 张）
|
||
|
||
| 表 | 说明 |
|
||
|----|------|
|
||
| `pbl_blueprint` | 蓝图聚合根 |
|
||
| `pbl_blueprint_learning_goal` | 子对象-学习目标 |
|
||
| `pbl_blueprint_role` | 子对象-PBL 角色 |
|
||
| `pbl_blueprint_mission` | 子对象-驱动问题/Mission |
|
||
| `pbl_blueprint_task` | 子对象-任务 |
|
||
| `pbl_blueprint_artifact_spec` | 子对象-产出物规格 |
|
||
| `pbl_blueprint_evidence_spec` | 子对象-证据规格 |
|
||
| `pbl_blueprint_reflection_spec` | 子对象-反思规格 |
|
||
| `pbl_blueprint_version` | 版本快照 + change_delta |
|
||
| `pbl_template` | 模板（含离线兜底槽位） |
|
||
|
||
DDL 基线：`models/pbl_blueprint.subobjects.sql`；表定义四段式：`models/*.json`
|
||
（build.sh 用 `json2ddl mysql .` 生成 `mysql.ddl.sql`）。
|
||
|
||
## 契约接口（17 个，路径 `/pbl_blueprint/api/<name>.dspy`）
|
||
|
||
蓝图：`pbl_blueprint_create` / `_read` / `_update` / `_delete` / `_list` /
|
||
`_tree` / `_fork` / `_get_contract`
|
||
子对象：`pbl_blueprint_subobject_save` / `_list` / `_delete`
|
||
版本：`pbl_blueprint_version_create` / `_diff`
|
||
模板：`pbl_template_list` / `_instantiate` / `_save` / `_delete`
|
||
|
||
统一返回：`{"status":"success","data":...,"total":N}` 或
|
||
`{"status":"error","code":"PBL_XXX","message":"..."}`。
|
||
|
||
## 安装与集成（宿主应用 apps/pbls）
|
||
|
||
```python
|
||
# app/pbls.py
|
||
from pbl_blueprint.init import load_pbl_blueprint
|
||
|
||
def init():
|
||
env = ServerEnv()
|
||
env.get_module_dbname = get_module_dbname # 模块 -> 库名映射，禁止模块内硬编码
|
||
load_pbl_common() # 先加载公共内核（tenant 上下文/审计）
|
||
load_pbl_blueprint() # 再加载蓝图域
|
||
```
|
||
|
||
```bash
|
||
cd apps/pbls/pkgs && git clone <repo>/pbl_blueprint && pip install ./pbl_blueprint
|
||
bash modules/pbl_blueprint/build.sh # DDL + CRUD UI + 软链
|
||
./py3/bin/python modules/pbl_blueprint/scripts/load_path.py # RBAC 路径注册
|
||
```
|
||
|
||
## 目录
|
||
|
||
```
|
||
pbl_blueprint/
|
||
├── pbl_blueprint/ # Python 包：__init__.py / init.py / api.py
|
||
├── models/ # 10 张表定义（四段式 JSON）+ DDL 基线 SQL
|
||
├── json/ # 10 份 CRUD 定义
|
||
├── wwwroot/ # index.ui / menu.ui / api/*.dspy（17 个契约薄包装）
|
||
├── init/data.json # appcodes 10 组编码 + 2 份内置模板真实种子
|
||
├── scripts/load_path.py # RBAC 显式路径（无通配符）
|
||
├── skill/SKILL.md # agent 可读模块规范
|
||
├── pyproject.toml / build.sh / README.md
|
||
```
|
||
|
||
## 自测
|
||
|
||
```bash
|
||
python3 -m py_compile pbl_blueprint/*.py scripts/load_path.py
|
||
python3 scripts/selftest.py # 无 DB 环境下的契约/租户 fail-closed 静态校验
|
||
```
|