---
name: pbl_blueprint
description: PBL 蓝图聚合根与子对象、版本、模板（M1a）。蓝图 CRUD/树/fork、7 类子对象泛化契约、版本 change_delta、模板实例化与离线兜底。所有读写 tenant_id 强制打头，缺失即 fail-closed 拒绝。
---

# pbl_blueprint 模块技能

## 1. 模块定位
`pbl_blueprint` 是 PBL（Project-Based Learning）平台的**蓝图域聚合根模块**，负责：
- 蓝图主表 `pbl_blueprint` 的 CRUD / 列表 / 树 / fork
- 7 类子对象的**泛化契约**（一套 CRUD 覆盖 7 张表）
- 版本快照 `pbl_blueprint_version`（含 `change_delta` 增量、diff、rollback）
- 模板 `pbl_blueprint_template` / `pbl_blueprint_template_item`（实例化 + 离线兜底）

模块是 **Python 包**（无 app.py / 无端口 / 无 Dockerfile），通过 `load_pbl_blueprint(env)` 挂到应用 `apps/pbls`。

## 2. 目录结构
```
modules/pbl_blueprint/
├── pyproject.toml
├── scripts/load_path.py            # RBAC 路径注册（API/页面/表权限）
└── pbl_blueprint/                  # 包目录 = 模块名（禁 src/）
    ├── __init__.py                 # 导出 load_pbl_blueprint
    ├── init.py                     # 装配入口 + env 注册 + 契约字典
    ├── db.py                       # 库名解析 / sqlor 获取 / 异常体系 / 建表
    ├── blueprint_crud.py           # 蓝图 CRUD + 树 + fork + 版本契约
    ├── subobjects.py               # 7 类子对象泛化 CRUD
    ├── templates.py                # 模板 CRUD + 实例化 + 离线兜底
    ├── api.py                      # HTTP API 层 + API_PATHS + HANDLERS
    ├── models/*.json               # 表定义（四段式 summary/fields/indexes/codes）
    ├── json/*.json                 # CRUD 定义（根键 tblname + params.editable/browserfields）
    ├── sql/pbl_blueprint.core.sql       # 核心 4 表 DDL
    ├── sql/pbl_blueprint.subobjects.sql # 子对象 7 表 DDL
    ├── init/data.json              # 初始化数据（内置模板）
    └── wwwroot/index.ui            # 前端页面
```

## 3. 数据表（11 张）
核心 4 张：`pbl_blueprint`、`pbl_blueprint_version`、`pbl_blueprint_template`、`pbl_blueprint_template_item`
子对象 7 张：`pbl_blueprint_task`、`pbl_blueprint_mission`、`pbl_blueprint_role`、
`pbl_blueprint_learning_goal`、`pbl_blueprint_evidence_spec`、`pbl_blueprint_artifact_spec`、
`pbl_blueprint_reflection_spec`

统一约定：
- 主键 `id` = varchar(32)，32 位无横线 UUID（`db.new_id()`）
- `tenant_id` varchar(32) NOT NULL，**每个索引首列**
- 软删除 `deleted` tinyint（0 正常 / 1 已删除）
- 结构化字段用 `json` 类型（`spec` / `config` / `snapshot` / `change_delta` / `rule` / `permissions`）
- 审计五件套 `created_by/created_at/updated_by/updated_at/deleted`

## 4. 子对象泛化契约（重点）
7 类子对象共用一套函数，`obj_type` 分派到表：

| obj_type | 表 | 编码前缀 | 特有字段 |
|---|---|---|---|
| task | pbl_blueprint_task | TASK | parent_id |
| mission | pbl_blueprint_mission | MISSION | task_id(必填), unlock_condition |
| role | pbl_blueprint_role | ROLE | task_id, permissions |
| learning_goal | pbl_blueprint_learning_goal | GOAL | task_id, dimension, weight |
| evidence_spec | pbl_blueprint_evidence_spec | EVI | task_id, mission_id, learning_goal_id, evidence_type, collect_mode, rule, weight |
| artifact_spec | pbl_blueprint_artifact_spec | ART | task_id, mission_id, artifact_type, accept_criteria, required, weight |
| reflection_spec | pbl_blueprint_reflection_spec | REF | task_id, mission_id, trigger_point, reflection_type, rubric_ref, weight |

```python
from pbl_blueprint import load_pbl_blueprint
contract = load_pbl_blueprint(env)
contract['create_subobject'](tenant_id, 'mission', {'blueprint_id': bp_id, 'task_id': t_id, 'name': '关卡1'}, env=env)
contract['list_subobjects'](tenant_id, 'task', bp_id, env=env)
contract['batch_upsert_subobjects'](tenant_id, 'task', bp_id, rows, env=env)  # Designer Agent 整树写入
```

## 5. 蓝图契约
```python
create_blueprint(tenant_id, data, env, operator)      # 自动生成 code PBL-{yyyyMMdd}-{seq4}
update_blueprint(tenant_id, blueprint_id, data, ...)  # 状态流转校验 STATUS_FLOW
delete_blueprint(tenant_id, blueprint_id, ...)        # 软删（连带子对象+版本）
get_blueprint(tenant_id, blueprint_id, with_children) # with_children=True 附带 7 类子树
list_blueprints(tenant_id, filters, page, page_size)  # 分页 + keyword/status/subject 过滤
get_blueprint_tree(tenant_id, blueprint_id)           # {obj_type: [rows]}
fork_blueprint(tenant_id, blueprint_id, new_name, target_tenant_id)  # 跨租户复制，ID 重映射
```
状态机：`draft → validating → validated → compiling → compiled → published → archived`（非法流转抛 `PblValidationError`）。

## 6. 版本契约
```python
save_version(tenant_id, blueprint_id, remark)   # 存全量 snapshot + 计算 change_delta，主表 version_no 自增
list_versions(tenant_id, blueprint_id, page, page_size)
diff_versions(tenant_id, blueprint_id, version_a, version_b)  # {added, updated, removed}
rollback_version(tenant_id, blueprint_id, version_no)         # 先自动存当前版本再回滚
```
`change_delta` 结构：`{"added":[{"obj_type","id","name"}], "updated":[{"obj_type","id","fields"}], "removed":[...]}`

## 7. 模板与离线兜底
```python
create_template(tenant_id, {'name':..., 'items':[{'obj_type':'task','ref_key':'T1','name':...}, ...]})
instantiate_template(tenant_id, template_id, name, overrides)  # ref_key/parent_ref 解析为真实 ID，use_count 自增
build_offline_fallback_blueprint(tenant_id, name)              # Agent/网络不可用时的最小可用蓝图（9 条子对象）
```
模板条目用 `ref_key` / `parent_ref` 做**模板内相对引用**，实例化时按 `SUBOBJECT_TYPES` 顺序解析为真实 ID（父先于子）。

## 8. tenant_id 强制打头（铁律）
- 每个契约函数第一入参 `tenant_id`，内部 `db.require_tenant()` 校验
- 缺失/空/非字符串 → 抛 `PblTenantRequired`（code=`PBL_TENANT_REQUIRED`），**fail-closed 不放行**
- 所有 where 条件由 `_where(tenant_id, extra)` 构造，`tenant_id=` 永远在最前
- API 层 `_tid(params)` 从入参或 `context.tenant_id` 取，取不到直接失败
- 平台内置模板 `tenant_id='platform'`，`list_templates(include_platform=True)` 才并入

## 9. 异常码
| code | 含义 |
|---|---|
| PBL_TENANT_REQUIRED | 租户上下文缺失 |
| PBL_VALIDATION_ERROR | 入参校验失败 |
| PBL_NOT_FOUND / PBL_BLUEPRINT_NOT_FOUND / PBL_SUBOBJECT_NOT_FOUND / PBL_VERSION_NOT_FOUND / PBL_TEMPLATE_NOT_FOUND | 记录不存在 |
| PBL_UNKNOWN_OBJ_TYPE | 未知子对象类型 |
| PBL_DB_UNAVAILABLE | sqlor 不可用 |

## 10. 数据访问约束
- 库名：`ServerEnv().get_module_dbname('pbl_blueprint')`，**禁止硬编码 DBNAME**
- SQL 只用 sqlor 标准 API：`sor.C / sor.U / sor.D / sor.R / sor.sqlExe`，禁编造 save/list/insert
- 建表：`db.ensure_tables()` 幂等执行 `sql/*.sql`（`CREATE TABLE IF NOT EXISTS`）

## 11. API 路径（25 个，见 api.py API_PATHS）
前缀 `/pbl_blueprint/`，分四组：`blueprint/*`(7)、`version/*`(4)、`subobject/*`(7)、`template/*`(7)。
RBAC 注册：`python -m pbl_blueprint.scripts.load_path`（幂等，注册 API + 页面 + 表权限共 39 条路径）。

## 12. 下游模块依赖
- `pbl_validation`（M2）读 `get_blueprint_tree` 做 14 维校验，回写 `quality_level`
- `pbl_compiler`（M3）读蓝图树生成 Game Definition
- `pbl_evidence`（M5）按 `evidence_spec` / `artifact_spec` 采集
- `pbl_assessment`（M6）按 `learning_goal.weight` / `reflection_spec.rubric_ref` 评分
- `pbl_agent_runtime`（M4）用 `batch_upsert_subobjects` 写 Designer 产出，fail-closed 裁决