Files
trade-message-center/.trellis/tasks/09-11-remove-image-dimensions/design.md
T

4.1 KiB
Raw Blame History

技术设计:从 OneTalk 图片链路移除宽高

Boundary and invariant

widthheight 是 OneTalk 上游 raw image payload 的非业务字段,不再是 Trade Message Center 的任何规范化图片事实。MAIN decoder 是唯一可以看见 raw payload 的边界,但不得读取、校验、投影或以它们影响结果。此后图片确认的可靠性来自:候选 message ID 优先;无 ID 时,目标会话、sent 方向、image kind、sizeBytesmd5、可用 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

  1. apps/onetalk-contract/src/content.ts 删除 OneTalkImageContent.width / .heightCONTENT_KEYS.image 对应键和 ONETALK_MAX_IMAGE_DIMENSION_PX。exact-shape guard 将带任一 dimension key 的 canonical content 判为无效。
  2. apps/chrome-extension/src/onetalk/main-page/message-observer/content-decoder.ts 删除 dimension import、normalized 字段和 validation。raw payload 即使带错误类型、超界值或仅单边字段,也不影响图片的其它安全校验和无宽高 normalized output。
  3. apps/chrome-extension/src/onetalk/main-page/image-send.ts 的 final image metadata 只提取 sizeBytes、非空 md5 和可选 fileIdsend-observation.ts 的 pending expected / matcher 不再保留或比较 dimensions。
  4. 所有 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,移除顶层 widthheight 键。文本、文件、其余 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 与 sizevalidator 只接受无宽高的 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。