pbl_blueprint/README.md

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）

# 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()   # 再加载蓝图域

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

自测

python3 -m py_compile pbl_blueprint/*.py scripts/load_path.py
python3 scripts/selftest.py     # 无 DB 环境下的契约/租户 fail-closed 静态校验