签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,326 @@
+# 5.10 字典模块
+
+:::tip 概述
+DictService 提供字典项的读取、正反向转换与缓存管理，是字典体系的核心服务。采用两级缓存（请求级 + 持久缓存），同一请求内不重复查库，跨请求复用持久缓存。
+:::
+
+## 字典体系架构
+
+```text
+┌─────────────────────────────────────────────────────────────────────┐
+│                         字典体系                                     │
+│                                                                     │
+│  ┌──────────────────┐    ┌──────────────────┐                      │
+│  │ think_dict       │    │ think_dict_item  │                      │
+│  │ 字典主表         │    │ 字典项表         │                      │
+│  │                  │    │                  │                      │
+│  │ id               │◄───│ dict_id          │                      │
+│  │ name (字典名称)  │    │ name (项名称)    │                      │
+│  │ code (字典编码)  │    │ value (项值)     │                      │
+│  │ remark           │    │ sort (排序)      │                      │
+│  └──────────────────┘    │ note (备注)      │                      │
+│                          └──────────────────┘                      │
+│                                                                     │
+│  ┌──────────────────┐    ┌──────────────────┐                      │
+│  │ DictService      │    │ Logic 层         │                      │
+│  │ 字典服务         │    │ serializeMaps    │                      │
+│  │                  │    │ 自动翻译         │                      │
+│  │ getText()        │    │                  │                      │
+│  │ getValue()       │◄───│ 'status' =>      │                      │
+│  │ getOptions()     │    │   'user_status'  │                      │
+│  │ clearCache()     │    │                  │                      │
+│  └──────────────────┘    └──────────────────┘                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 缓存架构
+
+```text
+请求级缓存（static::$localCache）    ← 同一请求内不重复查库
+        │ 未命中
+        ▼
+持久缓存（cache() 门面，1小时）      ← 跨请求复用（file/redis）
+        │ 未命中
+        ▼
+数据库查询（dict → dict_item）       ← 查询后写入两级缓存
+```
+
+### 缓存 Key 格式
+
+| 缓存类型 | Key 格式 | 存储内容 |
+|----------|---------|---------|
+| 请求级 | `$localCache['gender']` | `['1'=>'男', '2'=>'女']` |
+| 请求级（完整） | `$localCache['full_gender']` | `[{id, name, value, sort, note}, ...]` |
+| 持久缓存 | `dict_gender` | `['1'=>'男', '2'=>'女']` |
+| 持久缓存（完整） | `dict_full_gender` | `[{id, name, value, sort, note}, ...]` |
+
+### 缓存生命周期
+
+```text
+1. 首次查询 → 数据库 → 写入持久缓存 + 请求级缓存
+2. 同一请求再次命中 → 直接返回请求级缓存（最快）
+3. 不同请求命中 → 读取持久缓存（不查库）
+4. 缓存过期（1小时）→ 重新查库 → 更新两级缓存
+5. 字典数据变更 → 调用 clearCache() 清除 → 下次查询重新加载
+```
+
+## 核心方法
+
+### getText — 根据值获取名称（最常用）
+
+```php
+DictService::getText('gender', 1);        // '男'
+DictService::getText('user_status', 1);   // '启用'
+DictService::getText('gender', '');       // ''（空值返回空字符串）
+DictService::getText('gender', null);     // ''（空值返回空字符串）
+```
+
+**用途：** 列表展示时将数据库值转换为可读名称。
+
+### getValue — 根据名称反向获取值
+
+```php
+DictService::getValue('gender', '男');    // '1'
+DictService::getValue('user_status', '启用'); // '1'
+DictService::getValue('gender', '');     // ''（空值返回空字符串）
+```
+
+**用途：** Excel 导入时将中文文字转换为数据库存储的数值。
+
+### getOptions — 获取下拉框选项
+
+```php
+DictService::getOptions('gender');
+// [
+//     ['label' => '男', 'value' => '1'],
+//     ['label' => '女', 'value' => '2'],
+// ]
+```
+
+**用途：** 前端下拉框、单选框、复选框组件的数据源。
+
+### getFullItems — 获取完整字典项
+
+```php
+DictService::getFullItems('gender');
+// [
+//     ['id' => 1, 'name' => '男', 'value' => '1', 'sort' => 1, 'note' => ''],
+//     ['id' => 2, 'name' => '女', 'value' => '2', 'sort' => 2, 'note' => ''],
+// ]
+```
+
+**用途：** 需要 id、排序、备注等完整信息的场景。
+
+### clearCache — 清除缓存
+
+```php
+DictService::clearCache('gender');    // 清除指定字典的缓存
+DictService::clearCache();            // 仅清空请求级缓存
+DictService::clearAllCache();         // 清除所有字典持久缓存
+```
+
+## 方法清单
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `getText($code, $value)` | 值 → 名称 | `string` |
+| `getValue($code, $text)` | 名称 → 值 | `string` |
+| `getItems($code)` | 获取值→名称映射 | `array` `['1'=>'男', '2'=>'女']` |
+| `getOptions($code)` | 获取下拉框选项 | `array` `[['label'=>'男','value'=>'1'], ...]` |
+| `getFullItems($code)` | 获取完整字典项 | `array` `[{id, name, value, sort, note}, ...]` |
+| `clearCache($code?)` | 清除指定/请求级缓存 | `void` |
+| `clearAllCache()` | 清除所有字典缓存 | `void` |
+
+## 在 Logic 中使用
+
+### 自动翻译（serializeMaps）
+
+配置 `serializeMaps` 后，查询数据时自动补全 `{字段名}Text` 字段，无需手动调用 DictService：
+
+```php
+class UserLogic extends BaseTenantLogic
+{
+    /**
+     * 枚举显示名映射
+     *
+     * @var array
+     */
+    protected array $serializeMaps = [
+        'gender' => 'gender',
+        'status' => 'user_status',
+    ];
+}
+```
+
+**效果：**
+
+```text
+数据库：{ gender: 1, status: 1 }
+    │
+    ▼ processSerializeMaps()
+    │ DictService::getText('gender', 1) → '男'
+    │ DictService::getText('user_status', 1) → '启用'
+    ▼
+前端接收：{ gender: 1, genderText: '男', status: 1, statusText: '启用' }
+```
+
+### 手动调用
+
+```php
+// 在 Logic 或 Service 中手动调用
+$genderText = DictService::getText('gender', $user['gender']);
+$options = DictService::getOptions('gender');
+```
+
+## 在 Controller 中使用
+
+### 获取下拉框数据
+
+```php
+// app/controller/DictController.php
+
+/**
+ * 获取字典项下拉列表
+ *
+ * GET /dict/getOptions/{code}
+ */
+public function getOptions(string $code): Json
+{
+    $options = DictService::getOptions($code);
+    return $this->success($options);
+}
+```
+
+### 刷新字典缓存
+
+```php
+/**
+ * 刷新字典缓存
+ *
+ * GET /dict/refreshCache
+ */
+public function refreshCache(): Json
+{
+    DictService::clearAllCache();
+    return $this->success(null, '缓存刷新成功');
+}
+```
+
+## 在导入导出中使用
+
+### 导入时：文字转值
+
+```php
+// UserLogic::import()
+foreach ($data as &$row) {
+    // Excel 中"男" → 数据库中 1
+    if (!empty($row['gender']) && !is_numeric($row['gender'])) {
+        $row['gender'] = DictService::getValue('gender', $row['gender']);
+    }
+    // Excel 中"启用" → 数据库中 1
+    if (!empty($row['status']) && !is_numeric($row['status'])) {
+        $row['status'] = DictService::getValue('user_status', $row['status']);
+    }
+}
+```
+
+### 导出时：值转文字
+
+```php
+// 导出表头使用 Text 后缀字段
+$headers = [
+    'name'       => '姓名',
+    'genderText' => '性别',      // 自动翻译后的字段
+    'statusText' => '状态',      // 自动翻译后的字段
+];
+```
+
+## 前端集成
+
+### 获取字典选项
+
+```typescript
+// API
+export function getDictOptions(code: string) {
+  return http.request({ url: `/dict/getOptions/${code}`, method: 'GET' });
+}
+
+// 使用
+const genderOptions = ref([]);
+onMounted(async () => {
+  genderOptions.value = await getDictOptions('gender');
+});
+```
+
+### 下拉框组件
+
+```vue
+<template>
+  <el-select v-model="form.gender" placeholder="请选择性别">
+    <el-option
+      v-for="item in genderOptions"
+      :key="item.value"
+      :label="item.label"
+      :value="item.value"
+    />
+  </el-select>
+</template>
+```
+
+## 数据库表结构
+
+### think_dict（字典主表）
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `id` | INT | 主键 | 1 |
+| `name` | VARCHAR(50) | 字典名称 | 性别 |
+| `code` | VARCHAR(50) | 字典编码（唯一） | gender |
+| `remark` | VARCHAR(500) | 备注 | 性别字典 |
+| `...` | | 公共字段 | |
+
+### think_dict_item（字典项表）
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `id` | INT | 主键 | 1 |
+| `dict_id` | INT | 字典 ID（外键） | 1 |
+| `name` | VARCHAR(50) | 项名称 | 男 |
+| `value` | VARCHAR(50) | 项值 | 1 |
+| `sort` | INT | 排序 | 1 |
+| `note` | VARCHAR(200) | 备注 | |
+| `...` | | 公共字段 | |
+
+## 字典编码规范
+
+| 字典编码 | 名称 | 项值 | 用途 |
+|----------|------|------|------|
+| `gender` | 性别 | 0=女, 1=男 | 用户性别 |
+| `user_status` | 用户状态 | 0=禁用, 1=启用 | 用户账号状态 |
+| `article_status` | 文章状态 | 0=草稿, 1=已发布 | 文章状态 |
+| `tenant_status` | 租户状态 | 0=禁用, 1=启用 | 租户状态 |
+| `example_type` | 案例类型 | 0=类型一, 1=类型二 | 案例分类 |
+| `example_status` | 案例状态 | 0=禁用, 1=启用 | 案例状态 |
+
+## 缓存管理
+
+### 缓存失效时机
+
+| 时机 | 操作 | 说明 |
+|------|------|------|
+| 字典项新增/修改/删除 | `DictService::clearCache($code)` | 清除该字典的缓存 |
+| 手动刷新 | `GET /dict/refreshCache` | 清除所有字典缓存 |
+| 缓存过期 | 自动失效 | 1 小时 TTL |
+
+:::warning 字典数据变更后必须刷新缓存
+修改字典项后，如果不刷新缓存，前端显示的可能仍是旧数据。建议在字典管理的增删改接口中自动调用 `clearCache()`。
+:::
+
+## 安全特性
+
+| 特性 | 说明 |
+|------|------|
+| 两级缓存 | 请求级 + 持久缓存，减少数据库压力 |
+| 空值安全 | `getText`/`getValue` 对 null/空字符串返回空字符串 |
+| 类型安全 | 值统一转为字符串比较，避免类型松散比较问题 |
+| 缓存隔离 | 每个字典编码独立缓存，互不影响 |