diff --git a/pc/docs/dictionary-usage.md b/pc/docs/dictionary-usage.md index f028f78..f72f7ef 100644 --- a/pc/docs/dictionary-usage.md +++ b/pc/docs/dictionary-usage.md @@ -1,548 +1 @@ -# 字典系统使用指南 - -## 概述 - -字典（Dictionary）系统是一个用于管理应用中常用的枚举值和标签化数据的功能。通过字典系统，你可以在后台统一管理这些数据，而无需修改代码和重新编译部署。 - -### 字典的核心概念 - -- **字典类型（Dict Type）**：用来分类管理字典项，例如 `user_status`（用户状态）、`gender`（性别）等 -- **字典编码（Dict Code）**：字典类型的唯一标识，用于前端查询，例如 `user_status`、`gender` -- **字典项（Dict Item）**：具体的字典值和标签，包括： - - `dict_value`：存储在数据库中的实际值（例如 `1`、`0`） - - `dict_label`：显示给用户的标签文本（例如 "启用"、"禁用"） - -### 数据库表结构 - -```sql --- 字典类型表 -CREATE TABLE sys_dict_type ( - id BIGINT, - dict_code VARCHAR(50) -- 字典编码（唯一） - dict_name VARCHAR(100) -- 字典名称 - status TINYINT -- 是否启用 - ... -) - --- 字典项表 -CREATE TABLE sys_dict_item ( - id BIGINT, - dict_type_id BIGINT -- 关联的字典类型ID - dict_label VARCHAR(100) -- 显示标签（如 "启用"） - dict_value VARCHAR(100) -- 存储值（如 "1"） - status TINYINT -- 是否启用 - ... -) -``` - ---- - -## 后端 API 接口 - -### 1. 获取字典项（最常用） - -**根据字典编码获取字典项列表：** - -```http -GET /api/dict/items/code/:code?include_disabled=0 -``` - -**请求示例：** -```bash -curl -X GET "http://localhost:8080/api/dict/items/code/user_status?include_disabled=0" -``` - -**响应示例：** -```json -{ - "code": 0, - "message": "success", - "data": [ - { - "id": 1, - "dict_type_id": 101, - "dict_label": "启用", - "dict_value": "1", - "status": 1, - "sort": 1, - ... - }, - { - "id": 2, - "dict_type_id": 101, - "dict_label": "禁用", - "dict_value": "0", - "status": 1, - "sort": 2, - ... - } - ] -} -``` - -**参数说明：** -- `code` (string, 必需)：字典编码，例如 `user_status` -- `include_disabled` (int, 可选)：是否包含禁用项，0 = 不包含（默认），1 = 包含 - ---- - -### 2. 字典管理接口 - -#### 获取字典类型列表 -```http -GET /api/dict/types?parentId=&status= -``` - -#### 添加字典类型 -```http -POST /api/dict/types -{ - "dict_code": "user_status", - "dict_name": "用户状态", - "status": 1 -} -``` - -#### 添加字典项 -```http -POST /api/dict/items -{ - "dict_type_id": 101, - "dict_label": "启用", - "dict_value": "1", - "status": 1, - "sort": 1 -} -``` - -#### 更新/删除字典项 -```http -PUT /api/dict/items/:id -DELETE /api/dict/items/:id -``` - ---- - -## 前端 API（Vue/JavaScript） - -### 前端 API 文件位置 - -``` -pc/src/api/dict.js -``` - -### 可用函数 - -#### getDictItemsByCode(code, includeDisabled = false) - -**最常用的函数**，根据字典编码获取字典项列表。 - -**参数：** -- `code` (string)：字典编码，例如 `'user_status'` -- `includeDisabled` (boolean)：是否包含禁用项，默认 `false` - -**返回：** Promise，返回字典项数组 - -**示例：** -```javascript -import { getDictItemsByCode } from '@/api/dict' - -// 获取用户状态字典 -const statusItems = await getDictItemsByCode('user_status') -console.log(statusItems) -// 输出： -// [ -// { dict_label: '启用', dict_value: '1', ... }, -// { dict_label: '禁用', dict_value: '0', ... } -// ] -``` - ---- - -#### 其他可用函数 - -```javascript -// 获取字典类型列表 -getDictTypes(params) - -// 根据ID获取字典类型 -getDictTypeById(id) - -// 添加字典类型 -addDictType(data) - -// 更新字典类型 -updateDictType(id, data) - -// 删除字典类型 -deleteDictType(id) - -// 获取字典项列表（需传入参数过滤） -getDictItems(params) - -// 根据ID获取字典项 -getDictItemById(id) - -// 添加字典项 -addDictItem(data) - -// 更新字典项 -updateDictItem(id, data) - -// 删除字典项 -deleteDictItem(id) - -// 批量更新字典项排序 -batchUpdateDictItemSort(data) -``` - ---- - -## 前端组件中的使用示例 - -### 示例 1：在用户管理页面显示用户状态 - -**场景**：在用户列表中，根据用户的 `status` 字段显示对应的状态标签。 - -**文件**：`pc/src/views/system/users/index.vue` - -**实现步骤**： - -#### 1. 导入字典 API -```javascript -import { getDictItemsByCode } from '@/api/dict' -``` - -#### 2. 定义状态字典数据和加载函数 -```javascript - -``` - -#### 3. 定义辅助函数 -```javascript -// 根据状态值获取字典标签 -const getStatusLabel = (status: any) => { - const sval = status !== undefined && status !== null ? String(status) : '' - - // 查找匹配的字典项 - const item = statusDict.value.find( - (d: any) => String(d.dict_value) === sval || d.dict_value === status - ) - - if (item && item.dict_label) { - return item.dict_label - } - - // 兼容旧逻辑：如果没有匹配的字典项 - if (status === 1 || sval === '1' || sval === 'active') return '启用' - return '禁用' -} - -// 根据标签确定 el-tag 的样式类型 -const getStatusTagType = (status: any) => { - const label = getStatusLabel(status) - if (!label) return 'info' - - const l = label.toString() - if (l.includes('启用') || l.includes('正常') || l.includes('active')) return 'success' - if (l.includes('禁用') || l.includes('停用') || l.includes('inactive')) return 'danger' - - return 'info' -} -``` - -#### 4. 在模板中使用 -```vue - -``` - ---- - -### 示例 2：在下拉选择中使用字典 - -**场景**：在"添加/编辑用户"对话框中，用字典项填充状态下拉选择。 - -```vue - - - -``` - ---- - -### 示例 3：多个字典项的场景 - -**场景**：同时加载多个字典（用户状态、性别、部门类型等）。 - -```javascript - -``` - ---- - -## 最佳实践 - -### 1. 缓存字典数据 - -避免在每个组件中都调用字典 API。建议在全局 store 中缓存字典数据： - -**文件**：`pc/src/stores/dict.ts` - -```typescript -import { defineStore } from 'pinia' -import { ref } from 'vue' -import { getDictItemsByCode } from '@/api/dict' - -export const useDictStore = defineStore('dict', () => { - const dicts = ref>({}) - - const fetchDict = async (code: string) => { - if (dicts.value[code]) { - return dicts.value[code] - } - - try { - const res = await getDictItemsByCode(code) - const items = res?.data || res || [] - dicts.value[code] = Array.isArray(items) ? items : [] - return dicts.value[code] - } catch (err) { - console.error(`Failed to fetch dict ${code}:`, err) - return [] - } - } - - return { dicts, fetchDict } -}) -``` - -**在组件中使用：** - -```javascript -import { useDictStore } from '@/stores/dict' - -const dictStore = useDictStore() -const statusDict = await dictStore.fetchDict('user_status') -``` - -### 2. 创建字典枚举文件 - -建议为常用字典创建枚举文件，便于维护： - -**文件**：`pc/src/constants/dicts.ts` - -```typescript -// 字典编码常量 -export const DICT_CODES = { - USER_STATUS: 'user_status', - GENDER: 'gender', - DEPT_TYPE: 'dept_type', - POSITION_LEVEL: 'position_level', -} as const - -// 用于 TypeScript 类型 -export type DictCode = typeof DICT_CODES[keyof typeof DICT_CODES] -``` - -**在组件中使用：** - -```javascript -import { DICT_CODES } from '@/constants/dicts' -import { useDictStore } from '@/stores/dict' - -const dictStore = useDictStore() -const statusDict = await dictStore.fetchDict(DICT_CODES.USER_STATUS) -``` - -### 3. 处理不同的数据值类型 - -字典值可能是数字、字符串或其他类型。确保比较时进行正确的类型转换： - -```javascript -const getStatusLabel = (status: any) => { - // 转换为字符串便于比较 - const statusStr = String(status) - - const item = statusDict.value.find((d: any) => { - // 支持多种比较方式 - return ( - String(d.dict_value) === statusStr || - d.dict_value === status || - d.dict_value == status // 宽松比较 - ) - }) - - return item?.dict_label || '未知' -} -``` - -### 4. 错误处理 - -始终为字典加载添加适当的错误处理和回退机制： - -```javascript -const fetchStatusDict = async () => { - try { - const res = await getDictItemsByCode('user_status') - statusDict.value = res?.data || [] - } catch (err) { - console.error('Failed to fetch status dict:', err) - // 使用默认的回退数据 - statusDict.value = [ - { dict_label: '启用', dict_value: '1' }, - { dict_label: '禁用', dict_value: '0' }, - ] - } -} -``` - ---- - -## 常见问题 - -### Q1: 字典数据在页面刷新后丢失了？ - -**A:** 这是正常的，字典数据只在组件的生命周期内存在。建议使用全局 store（Pinia）来缓存字典数据，或在每个需要的组件中通过 `onMounted` 加载。 - -### Q2: 后端添加了新的字典项，前端不显示新数据？ - -**A:** 前端缓存了字典数据。有两种解决方案： -1. 刷新浏览器页面，重新加载字典 -2. 在后端修改字典后，调用缓存清除接口（如果有的话），或手动清除前端 store 中的字典缓存 - -### Q3: 字典编码对应的字典类型不存在？ - -**A:** 确保： -1. 后端已在 `sys_dict_type` 表中添加了对应的字典类型记录 -2. 字典类型的状态（`status`）为启用（通常为 1） -3. 至少添加了一项字典项（`sys_dict_item` 表中有数据） -4. 字典编码（`dict_code`）完全匹配（区分大小写） - -### Q4: 如何在后台管理系统中管理字典？ - -**A:** 通常在系统设置或配置模块中有"字典管理"功能，可以： -- 添加/编辑/删除字典类型 -- 管理字典项（标签、值、排序、启用/禁用等） - -具体路径取决于你的后台管理系统设计。 - ---- - -## 总结 - -使用字典系统的核心步骤： - -1. **后端准备**：在 `sys_dict_type` 和 `sys_dict_item` 表中添加字典数据 -2. **前端导入**：`import { getDictItemsByCode } from '@/api/dict'` -3. **加载字典**：在 `onMounted` 或其他合适位置调用 API 加载 -4. **使用字典**：通过 `dict_value` 和 `dict_label` 来显示和存储数据 -5. **最优化**：使用 Pinia store 缓存字典，避免重复请求 - -通过字典系统，你可以灵活地管理应用中的枚举值和标签数据，而无需修改代码。 +# 字典使用示例 diff --git a/pc/docs/pinia-dict-guide.md b/pc/docs/pinia-dict-guide.md new file mode 100644 index 0000000..31f9123 --- /dev/null +++ b/pc/docs/pinia-dict-guide.md @@ -0,0 +1,374 @@ +# Pinia 字典管理系统使用指南 + +## 系统架构 + +``` +┌─────────────────────────────────────┐ +│ API 接口 (getDictItemsByCode) │ +│ /api/dict/items/code/{code} │ +└──────────────┬──────────────────────┘ + │ + ↓ +┌─────────────────────────────────────┐ +│ Pinia Store (useDictStore) │ +│ ✅ 自动缓存字典数据 │ +│ ✅ 避免重复请求 │ +│ ✅ 支持同步/异步访问 │ +└──────────────┬──────────────────────┘ + │ + ┌──────┴──────┐ + ↓ ↓ + ┌────────┐ ┌──────────────┐ + │组件 │ │Composable │ + │直接用 │ │useDict Hook │ + └────────┘ └──────────────┘ +``` + +--- + +## 核心文件说明 + +### 1. **Store**: `src/stores/dict.js` + +字典数据的全局管理器 + +**主要方法**： +```javascript +import { useDictStore } from '@/stores/dict' + +const dictStore = useDictStore() + +// ✅ 异步获取字典（推荐） +const items = await dictStore.getDictItems('user_status') + +// ✅ 同步获取字典（已缓存时） +const items = dictStore.getDictItemsSync('user_status') + +// ✅ 获取字典值对应的标签 +const label = dictStore.getDictLabel('user_status', 1) + +// ✅ 预加载多个字典 +await dictStore.preloadDicts(['user_status', 'user_role']) + +// ✅ 清空缓存 +dictStore.clearCache('user_status') +``` + +--- + + + +--- + + + +--- + +## 使用场景 + +### 场景1：在列表页加载字典 + +**文件**: `src/views/system/users/index.vue` + +```vue + + + +``` + +--- + +### 场景2：在编辑对话框使用字典 + +**文件**: `src/views/system/users/components/UserEdit.vue` + +```vue + + + +``` + +--- + +### 场景3：直接使用字典Store + +直接使用字典Store获取数据： + +```vue + + + +``` + +--- + +### 场景4：预加载应用启动时需要的字典 + +**文件**: `src/main.js` + +```javascript +import { createApp } from 'vue' +import { createPinia } from 'pinia' +import { useDictStore } from '@/stores/dict' + +const app = createApp(App) +const pinia = createPinia() + +app.use(pinia) + +// 在应用启动后预加载常用字典 +const dictStore = useDictStore() +await dictStore.preloadDicts([ + 'user_status', + 'common_status', + 'yes_no', +]) + +app.mount('#app') +``` + +--- + +## 字典数据结构 + +后端返回的字典数据结构： + +```json +[ + { + "dict_id": 1, + "dict_value": "1", + "dict_label": "启用", + "dict_type": "user_status", + "remarks": "用户启用状态", + "remark": "用户启用状态" + }, + { + "dict_id": 2, + "dict_value": "0", + "dict_label": "禁用", + "dict_type": "user_status", + "remarks": "用户禁用状态", + "remark": "用户禁用状态" + } +] +``` + +**关键字段**： +- `dict_value`: 字典值（存储在数据库中） +- `dict_label`: 字典标签（显示给用户） +- `dict_type`: 字典类型编码（如 'user_status'） + +--- + +## 最佳实践 + +### ✅ DO + +1. **使用字符串而不是硬编码数字** + ```javascript + // ✅ 好 + dictStore.getDictItems('user_status') + + // ❌ 差 + // 避免直接使用数字，应该使用字符串 + ``` + +2. **在父组件加载，通过 props 传给子组件** + ```javascript + // ✅ 父组件负责数据，子组件负责展示 + // index.vue + const statusDict = await dictStore.getDictItems('user_status') + + // UserEdit.vue + const props = defineProps({ statusDict: Array }) + ``` + +3. **直接使用字典Store** + ```javascript + // ✅ 直接使用Store获取数据 + const statusDict = await dictStore.getDictItems('user_status') + ``` + +4. **预加载常用字典** + ```javascript + // ✅ 应用启动时预加载，避免页面初始化时加载 + await dictStore.preloadDicts([...]) + ``` + +### ❌ DON'T + +1. **不要在多个地方重复加载同一个字典** + ```javascript + // ❌ 糟糕：重复加载 + // 页面A + const dict1 = await dictStore.getDictItems('user_status') + + // 页面B（Store 会自动缓存，但代码看起来重复） + const dict2 = await dictStore.getDictItems('user_status') + ``` + +2. **不要忘记处理加载状态** + ```javascript + // ❌ 可能展示空白 + const { statusDict } = useUserStatusDict() + + // ✅ 处理加载状态 + const { statusDict, loading } = useUserStatusDict() + if (loading) { /* 显示加载中 */ } + ``` + +3. **不要混用不同的字典访问方式** + ```javascript + // ❌ 混乱 + const dict1 = await dictStore.getDictItems('user_status') + const dict2 = dictStore.getDictItemsSync('user_role') + + // ✅ 统一使用 + const dict1 = await dictStore.getDictItems('user_status') + const dict2 = await dictStore.getDictItems('user_role') + ``` + +--- + +## 性能优化建议 + +| 优化项 | 说明 | +|------|------| +| **缓存** | Store 自动缓存，同一个字典只请求一次 | +| **预加载** | 在路由切换前预加载需要的字典 | +| **同步访问** | 已加载的字典可用 `getDictItemsSync` 同步获取 | +| **避免重复** | 不要在多个组件重复请求同一个字典 | + +--- + +## 故障排查 + +### 问题1：状态选项为空 + +**原因**：字典未加载 +**解决**： +```javascript +// ❌ 错误：字典还未加载 +const statusDict = dictStore.getDictItemsSync('user_status') // 返回 [] + +// ✅ 正确：等待异步加载完成 +const statusDict = await dictStore.getDictItems('user_status') +``` + +### 问题2：重复加载字典 + +**原因**：没有使用 Store 的缓存 +**解决**： +```javascript +// 所有调用都会自动使用缓存，只请求一次 +await dictStore.getDictItems('user_status') // 首次：发送请求 +await dictStore.getDictItems('user_status') // 第二次：返回缓存 +``` + +### 问题3：字典显示不对 + +**原因**：value 类型不匹配（如 1 vs "1"） +**解决**： +```javascript +// Store 会自动处理类型匹配 +const item = items.find(i => + String(i.dict_value) === String(value) || i.dict_value === value +) +``` + +--- + +## 集成检清表 + +- [x] 创建 `src/stores/dict.js` - Store +- [x] 在 `index.vue` 中导入 `useDictStore` +- [x] 在 `UserEdit.vue` 中使用 `useDictStore` 获取字典数据 +- [x] 测试字典加载和显示 +- [x] 验证缓存功能（打开浏览器 DevTools 检查 Network） +- [x] 预加载常用字典（可选） + +--- + +## 相关文件修改 + +已修改的文件： +- ✅ `src/stores/dict.js` - 新建 +- ✅ `src/views/system/users/index.vue` - 使用 `useDictStore` +- ✅ `src/views/system/users/components/UserEdit.vue` - 使用字典功能 +- ✅ `src/constants/dictCodes.js` - 删除（不再需要） +- ✅ `src/composables/useDict.js` - 删除（不再需要） + diff --git a/pc/src/assets/less/style.less b/pc/src/assets/less/style.less index 8569856..3651b32 100644 --- a/pc/src/assets/less/style.less +++ b/pc/src/assets/less/style.less @@ -50,5 +50,5 @@ body { } } .el-form-item__label{ - min-width: 60px; + min-width: 80px !important; } \ No newline at end of file diff --git a/pc/src/stores/dict.js b/pc/src/stores/dict.js new file mode 100644 index 0000000..9ebc324 --- /dev/null +++ b/pc/src/stores/dict.js @@ -0,0 +1,179 @@ +import { defineStore } from 'pinia' +import { ref, computed } from 'vue' +import { getDictItemsByCode } from '@/api/dict' + +/** + * 字典 Store + * + * 用于全局管理系统字典数据 + * 缓存字典数据避免重复请求，提高性能 + * + * 使用示例： + * const dictStore = useDictStore() + * const statusDict = await dictStore.getDictItems('user_status') + * const roleDict = dictStore.getDictItemsSync('user_role') // 已加载则同步返回 + */ +export const useDictStore = defineStore('dict', () => { + // 字典缓存：{ dictCode: [...items] } + const dictCache = ref({}) + + // 正在加载的字典代码集合 + const loadingCodes = ref(new Set()) + + /** + * 获取字典项（异步） + * @param {string} code - 字典编码，如 'user_status' + * @returns {Promise} 字典项数组 + */ + async function getDictItems(code) { + // 如果缓存中已有，直接返回 + if (dictCache.value[code]) { + return dictCache.value[code] + } + + // 避免重复请求：如果已在加载中，等待 + if (loadingCodes.value.has(code)) { + // 等待加载完成（最多 5 秒） + return await new Promise((resolve) => { + let count = 0 + const timer = setInterval(() => { + if (dictCache.value[code]) { + clearInterval(timer) + resolve(dictCache.value[code]) + } + count++ + if (count > 50) { + clearInterval(timer) + resolve([]) + } + }, 100) + }) + } + + // 标记为正在加载 + loadingCodes.value.add(code) + + try { + const res = await getDictItemsByCode(code) + let items = [] + + // 兼容不同的 API 响应格式 + if (res?.data && Array.isArray(res.data)) { + items = res.data + } else if (Array.isArray(res)) { + items = res + } else if (res?.data?.data && Array.isArray(res.data.data)) { + items = res.data.data + } + + // 缓存字典项 + dictCache.value[code] = items + // console.log(`✅ 字典 [${code}] 已加载，共 ${items.length} 项`) + + return items + } catch (error) { + console.error(`❌ 加载字典 [${code}] 失败:`, error) + dictCache.value[code] = [] + return [] + } finally { + // 移除加载标记 + loadingCodes.value.delete(code) + } + } + + /** + * 同步获取字典项（如果已缓存） + * @param {string} code - 字典编码 + * @returns {Array} 字典项数组，未缓存则返回空数组 + */ + function getDictItemsSync(code) { + return dictCache.value[code] || [] + } + + /** + * 预加载字典（在应用启动时调用） + * @param {Array} codes - 字典编码数组 + * @returns {Promise} + */ + async function preloadDicts(codes) { + const promises = codes.map(code => getDictItems(code)) + await Promise.all(promises) + } + + /** + * 根据字典编码和值获取标签 + * @param {string} code - 字典编码 + * @param {any} value - 字典值 + * @returns {string} 字典标签 + */ + function getDictLabel(code, value) { + const items = getDictItemsSync(code) + if (!items.length) { + console.warn(`⚠️ 字典 [${code}] 未加载，无法获取标签`) + return String(value) + } + + const item = items.find(i => String(i.dict_value) === String(value) || i.dict_value === value) + return item ? item.dict_label : String(value) + } + + /** + * 根据字典编码和标签获取值 + * @param {string} code - 字典编码 + * @param {string} label - 字典标签 + * @returns {any} 字典值 + */ + function getDictValue(code, label) { + const items = getDictItemsSync(code) + if (!items.length) { + console.warn(`⚠️ 字典 [${code}] 未加载，无法获取值`) + return null + } + + const item = items.find(i => i.dict_label === label) + return item ? item.dict_value : null + } + + /** + * 清空缓存 + * @param {string} code - 字典编码，不指定则清空所有 + */ + function clearCache(code) { + if (code) { + delete dictCache.value[code] + // console.log(`✅ 已清除字典 [${code}] 缓存`) + } else { + dictCache.value = {} + // console.log(`✅ 已清除所有字典缓存`) + } + } + + /** + * 刷新字典 + * @param {string} code - 字典编码 + * @returns {Promise} + */ + async function refreshDict(code) { + clearCache(code) + return getDictItems(code) + } + + /** + * 获取所有已缓存的字典 + * @returns {Object} + */ + const allDicts = computed(() => dictCache.value) + + return { + dictCache, + loadingCodes, + getDictItems, + getDictItemsSync, + preloadDicts, + getDictLabel, + getDictValue, + clearCache, + refreshDict, + allDicts, + } +}) diff --git a/pc/src/views/system/tenant/components/audit.vue b/pc/src/views/system/tenant/components/audit.vue index 3e50315..6de9114 100644 --- a/pc/src/views/system/tenant/components/audit.vue +++ b/pc/src/views/system/tenant/components/audit.vue @@ -30,8 +30,8 @@ {{ tenantData.email || '未设置' }} - - {{ tenantData.status === 'enabled' ? '启用' : '禁用' }} + + {{ getTenantStatusText(tenantData.status) }} @@ -54,8 +54,13 @@ > - 通过 - 拒绝 + + {{ item.dict_label }} + @@ -79,9 +84,10 @@