优化更新

DjangoAdmin_FastAPI_EleVue/zh/volume4/api-cheatsheet.md

@@ -10,8 +10,8 @@ API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法
 
 | 方法 | 路径 | 说明 | 权限 |
 |:----|:----|:----|:----|
-| GET | `/api/captcha` | 获取图形验证码 | 无需登录 |
-| POST | `/api/login` | 用户登录 | 无需登录 |
+| GET | `/api/v1/captcha` | 获取图形验证码 | 无需登录 |
+| POST | `/api/v1/login` | 用户登录 | 无需登录 |
 | GET | `/api/v1/logout` | 退出登录 | 需登录 |
 
 ## 用户管理

DjangoAdmin_FastAPI_EleVue/zh/volume4/core/auth-flow.md

@@ -39,7 +39,7 @@
 ### 请求
 
 ```
-GET /api/captcha
+GET /api/v1/captcha
 ```
 
 ### 响应
@@ -89,7 +89,7 @@ async def captcha(request: Request):
 ### 请求
 
 ```
-POST /api/login
+POST /api/v1/login
 Content-Type: application/json
 
 {

DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict-guide.md

@@ -88,20 +88,41 @@ class TrainingService(BaseService[Training]):
 
 效果：列表/详情返回数据中自动添加 `trainingMethod` 和 `trainingMethodName` 字段。
 
-### 方式 2：手动获取字典值
+### 方式 2：通过 dict_util 获取（推荐后端使用）
 
 ```python
-from modules.dictionary.dict_item.repository import dict_item_repo
+from utils.dict_util import get_dict_map, get_dict_label, get_dict_items
 
-# 获取字典项列表
-items = dict_item_repo.get_all(dict_code='training_method', status=1)
+# 获取 {value: label} 映射
+options = get_dict_map('training_method')
+# 结果：{'1': '线上', '2': '线下', '3': '混合'}
 
-# 转为 {value: label} 字典
-options = {item.value: item.label for item in items}
+# 单值翻译
+label = get_dict_label('training_method', '1')
+# 结果：'线上'
+
+# 获取字典项列表（含排序信息）
+items = get_dict_items('training_method')
+# 结果：[{'label': '线上', 'value': '1', 'sort': 1}, ...]
+```
+
+### 方式 3：通过 Repository 直接查询
+
+```python
+from modules.dictionary.dict.repository import dict_repo
+from modules.dictionary.dict_item.repository import dictitem_repo
+
+# 先查字典类型获取 dict_id
+dict_obj = dict_repo.get_one(code='training_method')
+# 再查字典项
+items = dictitem_repo.filter_by(dict_id=dict_obj.id).all()
+
+# 转为 {value: name} 字典
+options = {item.value: item.name for item in items}
 # 结果：{'1': '线上', '2': '线下', '3': '混合'}
 ```
 
-### 方式 3：通过参数模块获取（适合系统配置）
+### 方式 4：通过参数模块获取（适合系统配置）
 
 ```python
 from modules.param.service import param_service

DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict.md

@@ -94,18 +94,25 @@ class DictItem(base_model, base_db):
 
 ## 使用示例
 
-### 后端获取字典
+### 后端获取字典（推荐使用 dict_util）
 
 ```python
-# 通过字典编码获取字典项列表
-from modules.dictionary.dict_item import service as dict_item_service
+from utils.dict_util import get_dict_items, get_dict_map, get_dict_label
 
-# 获取状态字典
-status_list = await dict_item_service.get_by_dict_code("sys_status")
-# 返回: [{"label": "正常", "value": "1"}, {"label": "停用", "value": "2"}]
+# 获取字典项列表（自动缓存，TTL 60秒兜底）
+items = get_dict_items("sys_status")
+# 返回: [{"label": "正常", "value": "1", "sort": 0}, {"label": "停用", "value": "2", "sort": 1}]
+
+# 获取 {value: label} 映射
+status_map = get_dict_map("sys_status")
+# 返回: {"1": "正常", "2": "停用"}
+
+# 单值翻译（value 自动转字符串匹配）
+label = get_dict_label("sys_status", 1, default="未知")
+# 返回: "正常"
 ```
 
-### dict_util 缓存工具
+### dict_util 缓存工具详解
 
 项目提供 `dict_util` 工具（`src/utils/dict_util.py`），内置进程内 TTL 缓存。由于字典数据几乎不变，且读写均落在同步 service 路径（无法使用请求级异步 Redis），因此采用进程内缓存而非 Redis 缓存：