update llm.txt

backend/llm.txt

@@ -230,14 +230,23 @@ Common types:
 
 ### 2.5 一个字段多种结构（判别联合）
 
-- 当同一个 `jsonb` 字段存在多种不同结构（例如订单快照：充值 vs 购买），不要让字段类型漂移为 `any/map`。
+- 当同一个 `jsonb` 字段存在多种不同结构（同一字段承载多个 payload），不要让字段类型漂移为 `any/map`。
 - 推荐统一包裹为“判别联合”结构：`type Xxx struct { Kind string; Data json.RawMessage }`，并将该字段映射为 `types.JSONType[fields.Xxx]`。
 - 写入时：
-  - `Kind` 建议与业务枚举对齐（例如订单类型），便于 SQL/报表按 `kind` 过滤。
+  - `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`，避免线上存量读取失败。
+
+---
+
+## 4) 审计与幂等（通用）
+
+- 若你为任意表新增结构化审计字段（例如 `operator_user_id`、`biz_ref_type/biz_ref_id`），服务层写入必须同步补齐（避免只写 remark/JSON 导致追溯困难）。
+- 注意：PostgreSQL 的可空列在本项目的 gen model 中可能会生成非指针类型（例如 `string/int64`），这会导致“未赋值”落库为 `''/0`：
+  - 若你要为 `(biz_ref_type,biz_ref_id,...)` 建唯一索引，**不要**只写 `IS NOT NULL` 条件；
+  - 应额外排除空/0（例如 `biz_ref_type <> '' AND biz_ref_id <> 0`），否则会因默认值冲突导致大量写入失败。
 - Array: `types.Array[T]`
 - UUID: `types.UUID`, `types.BinUUID`
 - Date/Time: `types.Date`, `types.Time`