From 3cb2a6f586e22939b680272923121c80a3ac8603 Mon Sep 17 00:00:00 2001 From: Rogee Date: Mon, 22 Dec 2025 21:30:17 +0800 Subject: [PATCH] update llm.txt --- backend/llm.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/backend/llm.txt b/backend/llm.txt index f3cee23..5349200 100644 --- a/backend/llm.txt +++ b/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`