31 lines
4.1 KiB
JSON
31 lines
4.1 KiB
JSON
{
|
||
"summary": [
|
||
{
|
||
"name": "pbl_entity_state",
|
||
"title": "实体当前状态（乐观锁版本表）",
|
||
"primary": ["id"],
|
||
"catelog": "relation",
|
||
"comment": "PBL 实体当前状态表（world_sync 侧，M11b-2 新增）。保存世界内实体的最新完整状态快照，state_version 为乐观锁版本号（每次成功写入 +1），用于防止并发覆盖（丢失更新）。【主键与唯一性】规范主键 id 为 str(32)（应用层生成 uuid4().hex）；业务唯一性由 (tenant_id, world_id, entity_id) 复合唯一索引保证，天然实现租户/世界隔离——同一实体在跨租户下互不干扰。【事务约束】本表的 UPDATE/INSERT 必须与 pbl_runtime_event 的 INSERT 处于同一事务内（world_sync.pbl_runtime_tx.write_event_with_state），任一失败整事务回滚；禁止脱离事务单独更新本表。【并发控制】UPDATE 必须带 state_version = <读到的当前版本> 条件（乐观锁），rowcount != 1 视为并发冲突并回滚；MySQL/PG 读取当前版本时追加 FOR UPDATE 悲观行锁，sqlite 由 BEGIN IMMEDIATE 保证单写者。【列真源】fields 与 world_sync/pbl_runtime_sql.py 的 STATE_COLUMNS 及 pbl_runtime_tx.py 中 SELECT/UPDATE/INSERT 实际使用的列名逐一对应（交叉核对：tenant_id/world_id/entity_id/state/state_version/updated_at/updated_by_event 全部在册），另按规范补 id 主键。【与 pbl_runtime_ext 的差异】modules/pbl_runtime_ext/models/pbl_entity_state.json（M11a 侧）使用 state_json/checksum/updated_by 等不同列集与 int 自增 id，属另一张同名表的另一套定义，两者不可混用；本文件为 world_sync（M11b-2）写入路径的权威定义，双真源合并方案已登记待 PM 裁决。【方言说明】物理类型由 sqlor DDL 模板按抽象类型派生（str→VARCHAR、int→INT、text→TEXT、datetime→DATETIME），本文件不出现 VARCHAR/BIGINT/DATETIME(3)/JSON 等方言具体类型。",
|
||
"module": "world_sync",
|
||
"owner_module": "world_sync",
|
||
"milestone": "M11b-2",
|
||
"tenant_scoped": true
|
||
}
|
||
],
|
||
"fields": [
|
||
{"name": "id", "title": "主键ID", "type": "str", "length": 32, "nullable": "no", "comment": "规范主键（str(32)），应用层生成 uuid4().hex；首次 INSERT 状态行时创建"},
|
||
{"name": "tenant_id", "title": "租户ID", "type": "str", "length": 64, "nullable": "no", "comment": "租户隔离维度，所有读写 WHERE 打头列"},
|
||
{"name": "world_id", "title": "世界ID", "type": "str", "length": 64, "nullable": "no", "comment": "世界隔离维度，与 tenant_id 共同限定作用域"},
|
||
{"name": "entity_id", "title": "实体ID", "type": "str", "length": 64, "nullable": "no", "comment": "实体标识，(tenant_id, world_id, entity_id) 定位唯一状态行"},
|
||
{"name": "state", "title": "实体状态", "type": "text", "nullable": "no", "comment": "实体当前完整状态，JSON 文本（规范抽象类型 text，不用方言 JSON 类型；序列化见 pbl_runtime_tx._dumps）"},
|
||
{"name": "state_version", "title": "状态版本号", "type": "int", "nullable": "no", "default": "0", "comment": "乐观锁版本号，每次成功写入 +1；与 pbl_runtime_event.state_version 保持一致"},
|
||
{"name": "updated_at", "title": "最近生效时间", "type": "datetime", "nullable": "no", "comment": "最近一次生效的 UTC 时间戳（应用层写入 ISO8601 文本，见 pbl_runtime_tx.utc_now_text）"},
|
||
{"name": "updated_by_event", "title": "最近生效事件ID", "type": "str", "length": 64, "nullable": "yes", "comment": "最近生效的事件业务键，回指 pbl_runtime_event.event_id"}
|
||
],
|
||
"indexes": [
|
||
{"name": "uk_es_tenant_world_entity", "idxtype": "unique", "idxfields": ["tenant_id", "world_id", "entity_id"], "comment": "业务唯一键：一个租户一个世界内一个实体只有一行当前状态；并发首次插入靠它触发冲突回滚"},
|
||
{"name": "ix_es_tenant_world_updated", "idxtype": "index", "idxfields": ["tenant_id", "world_id", "updated_at"], "comment": "按世界扫描最近变更实体（对账/清理用）"}
|
||
],
|
||
"codes": []
|
||
}
|