79 lines
8.5 KiB
JSON
79 lines
8.5 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 兼容可空列保留，不再是任何唯一键/主键/分区键成员。",
|
||
"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",
|
||
"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", "appcode": "pbl_event_type"}
|
||
]
|
||
}
|