签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/core/dict-guide.md

@@ -0,0 +1,100 @@
+# 5.11 字典配置与使用
+
+:::tip 概述
+本节是 {field}Text 字典驱动的使用手册：如何声明、填充链路如何工作、文案如何修改生效、常见坑有哪些。后端声明一处，全链路（列表/详情/导出）自动带显示名。
+:::
+
+## 使用三步
+
+```text
+1. 建表时列注释写枚举：  status int DEFAULT 1 COMMENT '状态：1-正常 2-禁用'
+   （生成器自动创建字典 user_status + 字典项；或字典管理页手工建）
+
+2. logic 模块头部声明映射：
+   var userSerializeMaps = map[string]string{
+       "status": "user_status",
+   }
+   挂进 spec：SerializeMaps: userSerializeMaps
+
+3. api/v1 行结构体加 Text 字段：
+   Status     int    `json:"status"`
+   StatusText string `json:"statusText"`   // 状态显示名（dict_item 解析）
+```
+
+读取时基座自动填充，前端直接展示 `statusText`。
+
+## 填充链路（机制详解）
+
+```text
+spec.SerializeMaps 声明 {字段: 字典编码}
+        │
+        ▼
+基座 FillTextFields（结构体存在 {Field}Text string 字段即自动填充，
+                    反射计划按类型缓存）
+        │
+        ▼
+DictGetText(ctx, code, value)
+        │ 查 dict→dict_item 的 name
+        ▼
+进程内缓存 dictTetxCache（{code}:{value} → 显示名，TTL 300s）
+        │ 未命中回源 Redis（dict:item:{code}，3600s）→ 数据库
+        ▼
+返回显示名；查无此项返回原值（不报错）
+```
+
+map 场景（非结构体，如导出行）用 `SerializeMapOnRead(ctx, row, maps)` 原地补 `row[field+"Text"]`。
+
+## 修改文案如何生效
+
+| 场景 | 生效时间 |
+|------|---------|
+| 字典管理页改 dict_item.name | 进程内缓存最迟 5 分钟（300s）自然过期 |
+| 需要立即全实例生效 | 调 `GET /api/dict/refreshCache`（刷 Redis 层；进程内层仍等过期） |
+| 新增字典项 | 同上（旧值缓存不受影响） |
+
+::: warning 三层缓存认知
+Redis 层（3600s，refreshCache 主动刷）→ 进程内层（300s，只等过期）→ 无缓存。改文案"看起来没生效"通常是进程内层未过期，等 5 分钟或重启。
+:::
+
+## 导出中的字典文本
+
+导出不走结构体填充，显式调用（真实模式，摘自 example 导出）：
+
+```go
+data = append(data, []any{
+    r["name"].String(),
+    DictGetText(ctx, "example_type", r["type"]),
+    DictGetText(ctx, "example_status", r["status"]),
+})
+```
+
+枚举列输出字典文本，Excel 直接可读（导出=所见）。
+
+## 前端消费
+
+```text
+1. 行内 {field}Text：直接展示后端返回的 statusText（首选——文案唯一真相在字典）
+2. 筛选下拉选项：调 /api/dict/item/getDictItemList/:code 拿字典项驱动 Select
+   （example 模块 querySchemas 的 options 是静态示例；真实模块建议字典驱动）
+3. 表单单选/多选：同上，按字典编码取选项
+```
+
+## 命名与例外
+
+```text
+编码规范：{模块snake}_{字段snake}（user_status / job_execute_policy / example_status）
+公共字典：role_data_scope（数据范围）等不带模块前缀
+
+例外：operation_log.type 存注解常量值（0-40/99），用静态表 LogTypeText
+     （consts.LogTypeNames），不走字典——数值与 gmeta logType 绑定，改动会破坏存量日志
+```
+
+## 常见问题
+
+| 症状 | 原因与处理 |
+|------|-----------|
+| {field}Text 全是数字 | spec 未声明 SerializeMaps / 结构体无 {Field}Text 字段 / 字典编码写错 |
+| 部分值有文本部分没有 | dict_item 缺该 value 的项 |
+| 改了文案没变化 | 进程内 300s 缓存未过期；调 refreshCache 只刷 Redis 层 |
+| 生成器没建字典 | 列注释格式不对（须 `字段：1-x 2-y` 形式）或非 MySQL 库内省不到注释 |
+| 查询返回原值 | DictGetText 设计为"查无返回原值"——排查 dict/dict_item 数据 |