mirror of
https://github.com/sinanyuntu/trade-message-center.git
synced 2026-09-17 13:22:11 +08:00
4.1 KiB
4.1 KiB
技术设计:从 OneTalk 图片链路移除宽高
Boundary and invariant
width 与 height 是 OneTalk 上游 raw image payload 的非业务字段,不再是 Trade Message Center 的任何规范化图片事实。MAIN decoder 是唯一可以看见 raw payload 的边界,但不得读取、校验、投影或以它们影响结果。此后图片确认的可靠性来自:候选 message ID 优先;无 ID 时,目标会话、sent 方向、image kind、sizeBytes、md5、可用 fileId、发送时钟窗口和唯一性共同约束。
OneTalk raw contentType=101/custom.type=7
(raw width/height ignored)
↓
OneTalkImageContent without dimensions
↓
live batch → SendObservationCorrelator
↓ unique match
PageCommandResult confirmed_sent
↓
send.confirmation → durable JSONB fact → message.created/send.result
不改变事实来源或终态顺序:SDK/HTTP 成功仍不确认;仅完整 live sent message 能确认;server 继续 commit -> message.created -> conversation.updated -> send.result。
Contract and decoder
apps/onetalk-contract/src/content.ts删除OneTalkImageContent.width/.height、CONTENT_KEYS.image对应键和ONETALK_MAX_IMAGE_DIMENSION_PX。exact-shape guard 将带任一 dimension key 的 canonical content 判为无效。apps/chrome-extension/src/onetalk/main-page/message-observer/content-decoder.ts删除 dimension import、normalized 字段和 validation。raw payload 即使带错误类型、超界值或仅单边字段,也不影响图片的其它安全校验和无宽高 normalized output。apps/chrome-extension/src/onetalk/main-page/image-send.ts的 final image metadata 只提取sizeBytes、非空md5和可选fileId;send-observation.ts的 pending expected / matcher 不再保留或比较 dimensions。- 所有 message frame、send confirmation/result 和 HTTP projection 由同一 content guard 收窄,因此不额外建立另一个 image result 或 legacy parser。
Durable data and protocol rollout
- 新 custom Drizzle migration 仅执行:对
onetalk_message.content ->> 'kind' = 'image'的 JSONB,移除顶层width、height键。文本、文件、其余 image key、主键和索引不变;不改已执行 migration。 - 迁移要被正确登记到 Drizzle journal。它是数据迁移,不需要扭曲 TypeScript schema 或添加另一份 runtime normalizer。
ONETALK_PROTOCOL_VERSION由 5 升至 6,所有 current-workspace frame builders、decoders、fixtures 和 harness 同步更新。没有 v5 adapter、双写或字段回填。- 严格切换的运行顺序:停止旧 server →
db:migrate清理 JSONB → 启动 v6 server → 发布并重连 v6 extension/Mind client。迁移前后都不能让旧 server 读取已清理图片,也不能让新 server 读取带宽高的旧事实。 - 当前工作区只能修改 shared Bright/extension/harness/server;真实 Mind workspace 是外部 release participant。只读检查未发现该 checkout 的字段消费者,但发布者仍须验证其实际部署的 client 已切至 v6。
Presentation and documentation
- Mind test harness image metadata 只展示 extension 与 size,validator 只接受无宽高的 canonical image。
- 更新仍描述“当前 normalized contract / confirmation matching”的非归档 docs;原始 OneTalk 证据样本可保留宽高,但旁注说明这两个 raw 字段被 decoder 忽略且不会跨 MAIN 边界。
- 不修改归档任务记录或上游 raw protocol 事实。
Risks and rollback
- 最大风险是 strict v6 与未更新端并存;这是预期 fail-closed,发布要在维护窗口执行。不能通过兼容 adapter 回滚该风险。
- 数据迁移会永久删除两个非业务 JSONB 字段。回滚代码只能恢复到“无宽高 content”的 v6 定义;若要恢复旧定义,必须另写新 migration 并接受历史尺寸不可恢复。
- 若
TEST_DATABASE_URL不可用,migration 数据效果只能以 SQL review、Drizzle check 和 unit projection 测试验证;生产执行前必须在目标数据库的维护窗口跑 migration。