update llm.txt

backend/llm.txt

@@ -227,6 +227,17 @@ Common types:
 - 服务层读写 `types.JSONType[T]`：
   - 读取：`v := model.Field.Data()`
   - 修改：`model.Field.Edit(func(v *T) { ... })` 或 `model.Field.Set(newValue)`
+
+### 2.5 一个字段多种结构（判别联合）
+
+- 当同一个 `jsonb` 字段存在多种不同结构（例如订单快照：充值 vs 购买），不要让字段类型漂移为 `any/map`。
+- 推荐统一包裹为“判别联合”结构：`type Xxx struct { Kind string; Data json.RawMessage }`，并将该字段映射为 `types.JSONType[fields.Xxx]`。
+- 写入时：
+  - `Kind` 建议与业务枚举对齐（例如订单类型），便于 SQL/报表按 `kind` 过滤。
+  - `Data` 写入对应 payload 的 JSON（payload 可以是多个不同 struct）。
+- 读取时：
+  - 先 `snap := model.Snapshot.Data()`，再 `switch snap.Kind` 选择对应 payload 结构去 `json.Unmarshal(snap.Data, &payload)`。
+- 兼容历史数据（旧 JSON 没有 kind/data）时，`UnmarshalJSON` 可以将其标记为 `legacy` 并把原始 JSON 放入 `Data`，避免线上存量读取失败。
 - Array: `types.Array[T]`
 - UUID: `types.UUID`, `types.BinUUID`
 - Date/Time: `types.Date`, `types.Time`