87 lines
11 KiB
JSON
87 lines
11 KiB
JSON
{
|
||
"summary": [
|
||
{
|
||
"name": "pbl_runtime_event",
|
||
"title": "运行时事件流(append-only)",
|
||
"comment": "运行时事件流：append-only（禁 UPDATE/DELETE，由存储过程 pbl_assert_append_only + BEFORE UPDATE/BEFORE DELETE 触发器强制），按 created_at 做按月 RANGE COLUMNS(created_at) 分区（分区键禁 TIMESTAMP，故用 DATETIME），分区保留 14 个月（超期由维护过程 DROP PARTITION）。物理主键必须为复合主键 (id, created_at) —— MySQL/MariaDB 要求分区表的所有唯一键（含主键）必须包含分区列，否则建表报错 1503；id 仍是逻辑主键与自增列。本 json 与 scripts/pbl_runtime_event_ddl.py 的 COLUMNS/PRIMARY_KEY/UNIQUE_KEYS/SECONDARY_KEYS 为同一真源的两个视图：DDL 侧为权威派生源（列顺序=物理列顺序，每列 ddl_type 记录其物理类型串），本 json 用规范抽象类型（long/str/text/datetime/short）表达同一结构，任何一侧变更必须同步另一侧。occurred_at 仅作 M11a 兼容可空列保留（DDL 侧 LEGACY_COLUMNS），不再是任何唯一键/主键/分区键成员。【spec 合规登记 · 私有顶层扩展键】本表定义在 database-table-definition-spec 四段式（summary/fields/indexes/codes）之外使用了若干 spec 未定义的顶层扩展键，清单如下：summary 段 = module / engine / charset / collate / tenant_scoped / append_only / write_paths / guards / partition / ddl_source；fields 段 = ddl_type / auto_increment / comment；codes 段 = comment。这些键是本模块与 scripts/pbl_runtime_event_ddl.py 生成器对齐用的私有键，sqlor 解析 models/*.json 时忽略（只消费 name/title/primary/type/length/nullable/default/name+idxtype+idxfields/field+table+valuefield+textfield+cond 等 spec 已定义键），不影响建表与 CRUD 渲染；删除或改名其中任何一个都会使 json↔DDL 一致性取证脚本失去比对依据。【id 类型偏离说明】fields[0].id 采用 type=long（配 auto_increment + ddl_type=BIGINT NOT NULL AUTO_INCREMENT），这是对 spec 规则「id 字段必须 str/length 32」的有意偏离，非疏漏：本表是按月 RANGE COLUMNS 分区的 append-only 事件流，DDL 权威源要求自增 BIGINT 物理主键 (id, created_at)，若改为 str(32) 将无法承载 AUTO_INCREMENT 且与分区表主键约束冲突（事件级高写入量也不适合应用层生成 32 位字符串主键）；对外幂等/追溯标识由 event_uid（str 64，uk_event_uid 唯一键）承担。此项偏离已在此登记并在交付摘要中说明，评审请勿据此判为结构缺陷、也不要把本 comment 正文复制进 title。",
|
||
"module": "pbl_runtime_ext",
|
||
"engine": "mariadb",
|
||
"charset": "utf8mb4",
|
||
"collate": "utf8mb4_general_ci",
|
||
"tenant_scoped": true,
|
||
"primary": ["id", "created_at"],
|
||
"append_only": true,
|
||
"write_paths": ["INSERT only"],
|
||
"guards": {
|
||
"append_only": {
|
||
"type": "stored_procedure+triggers",
|
||
"procedure": "pbl_assert_append_only()",
|
||
"triggers": ["BEFORE UPDATE", "BEFORE DELETE"],
|
||
"sqlstate": "45000",
|
||
"break_glass": "@pbl_guard_ctx",
|
||
"admin_ctx": "append_only_admin",
|
||
"note": "sor.U()/sor.D() 会被触发器拒绝；本模块所有写路径只发 INSERT（tx_event/tx_write 已如此）"
|
||
}
|
||
},
|
||
"partition": {
|
||
"method": "RANGE COLUMNS",
|
||
"column": "created_at",
|
||
"interval": "month",
|
||
"prefix": "p",
|
||
"max_partition": "pmax",
|
||
"precreate_months": 6,
|
||
"retention_months": 14,
|
||
"note": "PARTITION BY RANGE COLUMNS(`created_at`) (PARTITION pYYYYMM VALUES LESS THAN (DATE 'YYYY-MM-01'), ..., PARTITION pmax VALUES LESS THAN (MAXVALUE))"
|
||
},
|
||
"ddl_source": "modules/pbl_runtime_ext/scripts/pbl_runtime_event_ddl.py"
|
||
}
|
||
],
|
||
"fields": [
|
||
{"name": "id", "title": "自增ID", "comment": "自增ID(逻辑主键;物理主键=(id,created_at))", "type": "long", "nullable": "no", "auto_increment": true, "ddl_type": "BIGINT NOT NULL AUTO_INCREMENT"},
|
||
{"name": "tenant_id", "title": "租户ID", "comment": "租户ID(多租户强制打头)", "type": "str", "length": 32, "nullable": "no", "default": "", "ddl_type": "VARCHAR(32) NOT NULL DEFAULT ''"},
|
||
{"name": "event_uid", "title": "事件UID", "comment": "事件UID(uuid,应用层生成)", "type": "str", "length": 64, "nullable": "no", "ddl_type": "VARCHAR(64) NOT NULL"},
|
||
{"name": "event_code", "title": "事件编码", "comment": "事件编码", "type": "str", "length": 64, "nullable": "no", "default": "", "ddl_type": "VARCHAR(64) NOT NULL DEFAULT ''"},
|
||
{"name": "idem_key", "title": "幂等键", "comment": "幂等键(同键重复投递只落一条)", "type": "str", "length": 128, "nullable": "no", "default": "", "ddl_type": "VARCHAR(128) NOT NULL DEFAULT ''"},
|
||
{"name": "world_id", "title": "世界ID", "comment": "世界ID(引用 world 基表,只读)", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "scene_id", "title": "场景/会话ID", "comment": "场景/会话ID(引用 scense 基表,只读)", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "session_id", "title": "游戏会话ID", "comment": "游戏会话ID(M11a 语义,与 scene_id 同域)", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "entity_id", "title": "实体ID", "comment": "实体ID(引用 entity 基表,只读)", "type": "str", "length": 64, "nullable": "no", "default": "", "ddl_type": "VARCHAR(64) NOT NULL DEFAULT ''"},
|
||
{"name": "actor_id", "title": "触发者", "comment": "触发者(服务端会话解析,客户端禁填)", "type": "str", "length": 64, "nullable": "no", "default": "", "ddl_type": "VARCHAR(64) NOT NULL DEFAULT ''"},
|
||
{"name": "event_type", "title": "事件类型", "comment": "事件类型", "type": "str", "length": 64, "nullable": "no", "ddl_type": "VARCHAR(64) NOT NULL"},
|
||
{"name": "payload", "title": "事件负载", "comment": "事件负载JSON(任务书字段)", "type": "text", "nullable": "yes", "ddl_type": "TEXT NULL"},
|
||
{"name": "payload_json", "title": "事件负载JSON", "comment": "事件负载JSON(M11a 写路径列名,与 payload 同义留宽)", "type": "text", "nullable": "yes", "ddl_type": "LONGTEXT NULL"},
|
||
{"name": "causation_id", "title": "因果链", "comment": "因果链:引发本事件的事件UID", "type": "str", "length": 64, "nullable": "no", "default": "", "ddl_type": "VARCHAR(64) NOT NULL DEFAULT ''"},
|
||
{"name": "seq", "title": "会话内单调序号", "comment": "会话内单调序号(轮询游标,应用层生成)", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "seq_no", "title": "会话内单调序号(M11a)", "comment": "会话内单调序号(M11a 写路径列名)", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "source", "title": "来源", "comment": "来源:runtime/agent/script/client_intent", "type": "str", "length": 32, "nullable": "no", "default": "runtime", "ddl_type": "VARCHAR(32) NOT NULL DEFAULT 'runtime'"},
|
||
{"name": "state", "title": "事件状态", "comment": "applied/rejected/rolled_back", "type": "str", "length": 16, "nullable": "no", "default": "applied", "ddl_type": "VARCHAR(16) NOT NULL DEFAULT 'applied'"},
|
||
{"name": "state_version", "title": "服务端权威版本", "comment": "本事件推进到的服务端权威版本", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "tx_group", "title": "事务组", "comment": "事务组(同组同事务)", "type": "str", "length": 64, "nullable": "no", "default": "", "ddl_type": "VARCHAR(64) NOT NULL DEFAULT ''"},
|
||
{"name": "broadcast", "title": "是否参与广播", "comment": "是否参与广播 0/1", "type": "short", "nullable": "no", "default": 1, "ddl_type": "TINYINT NOT NULL DEFAULT 1"},
|
||
{"name": "created_by", "title": "创建人", "comment": "创建人", "type": "long", "nullable": "no", "default": 0, "ddl_type": "BIGINT NOT NULL DEFAULT 0"},
|
||
{"name": "created_at", "title": "创建时间", "comment": "创建时间(分区键,禁TIMESTAMP)", "type": "datetime", "nullable": "no", "default": "CURRENT_TIMESTAMP", "ddl_type": "DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP"},
|
||
{"name": "updated_at", "title": "记录时间戳", "comment": "记录时间戳(append-only:永不 UPDATE)", "type": "datetime", "nullable": "no", "default": "CURRENT_TIMESTAMP", "ddl_type": "DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP"},
|
||
{"name": "occurred_at", "title": "兼容列(旧分区键)", "comment": "兼容列(M11a 旧分区键,新写入可空;不属任何键)", "type": "datetime", "nullable": "yes", "ddl_type": "DATETIME NULL"}
|
||
],
|
||
"indexes": [
|
||
{"name": "uk_event_uid", "idxtype": "unique", "idxfields": ["tenant_id", "event_uid", "created_at"], "comment": "事件UID幂等唯一；含分区键 created_at（分区表唯一键必须包含分区列）"},
|
||
{"name": "uk_tenant_idem", "idxtype": "unique", "idxfields": ["tenant_id", "idem_key", "created_at"], "comment": "租户内幂等键唯一；含分区键 created_at"},
|
||
{"name": "ix_scene_created", "idxtype": "index", "idxfields": ["scene_id", "created_at"], "comment": "按场景/会话+时间范围拉取事件（分区裁剪）"},
|
||
{"name": "ix_tenant_session_seq", "idxtype": "index", "idxfields": ["tenant_id", "session_id", "seq"], "comment": "会话内序号游标"},
|
||
{"name": "ix_tenant_session_seqno", "idxtype": "index", "idxfields": ["tenant_id", "session_id", "seq_no"], "comment": "会话内序号游标(M11a 列名)"},
|
||
{"name": "ix_tenant_world_type", "idxtype": "index", "idxfields": ["tenant_id", "world_id", "event_type"], "comment": "世界维度事件类型检索"},
|
||
{"name": "ix_tx_group", "idxtype": "index", "idxfields": ["tx_group"], "comment": "事务组回查"},
|
||
{"name": "ix_created_at", "idxtype": "index", "idxfields": ["created_at"], "comment": "时间轴/分区维护辅助索引"}
|
||
],
|
||
"codes": [
|
||
{
|
||
"field": "event_type",
|
||
"table": "appcodes_kv",
|
||
"valuefield": "k",
|
||
"textfield": "v",
|
||
"cond": "parentid='pbl_event_type'",
|
||
"comment": "取值域由 pbl_appcodes 模块 seed 注入的 appcode 组 pbl_event_type 保障（appcodes.id=pbl_event_type，子项落 appcodes_kv.parentid）；本表只引用不注入数据。证据路径（更正后）：modules/pbl_appcodes/init/data.json:44 —— 该行为 \"pbl_event_type\": [ 组定义起始行（实测仓库内无 modules/pbl_appcodes/pbl_appcodes/init/data.json 这一嵌套层级，旧摘要中多写的一层 pbl_appcodes/ 系笔误，行号与内容本身正确）"
|
||
}
|
||
]
|
||
}
|