签入版本

EasyGoAdmin_Gin_EleVue/zh/appendix/api-cheatsheet.md

@@ -1,279 +1,74 @@
 # E. API 接口速查表
 
-:::tip 概述
-本表列出所有 API 路由的完整清单，包含 HTTP 方法、路径和所需权限码。
+:::tip 说明
+按模块速查接口形态。标准 CRUD 按统一模式列出；实际清单以 /api.json 与 /swagger 为准（运行时生成）。
 :::
 
-## 公开接口
+## 标准模式（多数模块）
 
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/api/login` | 用户登录 |
-| GET | `/api/logout` | 用户登出 |
-| GET | `/api/captcha` | 获取验证码 |
-| POST | `/api/oauth2/token` | 刷新 Token |
-| DELETE | `/api/oauth2/remove/:token` | 移除 Token |
-| GET | `/api/oauth2/check/token` | 检查 Token |
+| 动作 | 方法与路径模式 | 权限码模式 |
+|---|---|---|
+| 分页 | GET /api/{模块}/page | sys:{模块}:page |
+| 列表 | GET /api/{模块}/list | sys:{模块}:list |
+| 详情 | GET /api/{模块}/detail/:id | sys:{模块}:detail |
+| 新增 | POST /api/{模块}/add | sys:{模块}:add |
+| 修改 | PUT /api/{模块}/update | sys:{模块}:update |
+| 删除 | DELETE /api/{模块}/delete/:id | sys:{模块}:delete |
+| 批量删除 | DELETE /api/{模块}/batchDelete | sys:{模块}:batchDelete |
 
-## 首页 / 个人中心
+## 认证与个人中心
 
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/index/getUser` | - | 获取当前用户信息 |
-| GET | `/api/index/getMenus` | - | 获取菜单列表 |
-| PUT | `/api/index/updatePassword` | - | 修改密码 |
-| PUT | `/api/index/updateProfile` | - | 修改个人资料 |
+| 接口 | 说明 |
+|---|---|
+| GET /api/captcha | 验证码（公开） |
+| POST /api/login | 登录（公开） |
+| POST /api/oauth2/token | 刷新/兑换（公开） |
+| GET /api/oauth2/check/token | 校验令牌 |
+| DELETE /api/oauth2/remove/:token | 撤销令牌 |
+| GET /api/logout | 登出 |
+| GET /api/index/getUser / getMenus | 当前用户/菜单 |
+| PUT /api/index/updatePassword / updateProfile | 改密/资料 |
+| GET /api/health | 健康检查（公开） |
 
-## 用户管理
+## 模块域名对照
 
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/user/page` | sys:user:page | 分页列表 |
-| GET | `/api/user/detail/:id` | sys:user:detail | 详情 |
-| POST | `/api/user/add` | sys:user:add | 新增 |
-| PUT | `/api/user/update` | sys:user:update | 修改 |
-| PUT | `/api/user/resetPwd` | sys:user:resetPwd | 重置密码 |
-| DELETE | `/api/user/delete/:id` | sys:user:delete | 删除 |
-| DELETE | `/api/user/batchDelete` | sys:user:batchDelete | 批量删除 |
-| POST | `/api/user/import` | sys:user:import | 导入 |
-| GET | `/api/user/export` | sys:user:export | 导出 |
+| 域 | 路径前缀 |
+|---|---|
+| 组织权限 | /api/user、/api/role、/api/menu、/api/dept、/api/level、/api/position、/api/tenant |
+| 内容 | /api/article、/api/category、/api/notice、/api/link |
+| 数据配置 | /api/dict（字典项 /api/dict/item/*、业务别名 /api/dictionary/*）、/api/param、/api/config（配置项 /api/config/item/*、网站配置 /api/config/web/*）、/api/city |
+| 定时任务 | /api/job（任务日志 /api/job/log/*） |
+| 在线用户 | /api/onlineUser |
+| 日志（特殊前缀） | 操作日志 /api/oper/log/*、登录日志 /api/login/log/*（权限码 sys:operLog:* / sys:loginLog:*） |
+| 监控（单接口） | GET /api/server/info、GET /api/cache/info |
+| 文件 | /api/upload/uploadFile(s)、/api/file/template/* |
+| 工具 | /api/example/*、/api/generator/*（page/preview/generate/batchGenerate） |
 
-## 角色管理
+## 常用非标准接口
 
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/role/page` | sys:role:page | 分页列表 |
-| GET | `/api/role/list` | sys:role:list | 全量列表 |
-| GET | `/api/role/detail/:id` | sys:role:detail | 详情 |
-| POST | `/api/role/add` | sys:role:add | 新增 |
-| PUT | `/api/role/update` | sys:role:update | 修改 |
-| DELETE | `/api/role/delete/:id` | sys:role:delete | 删除 |
-| DELETE | `/api/role/batchDelete` | sys:role:batchDelete | 批量删除 |
-| GET | `/api/role/menu/list/:id` | - | 角色菜单列表 |
-| POST | `/api/role/menu/save` | sys:role:authorize | 保存角色菜单 |
+| 接口 | 说明 |
+|---|---|
+| PUT /api/example/status | 单列状态（status 型模块同构） |
+| POST /api/example/import / GET /api/example/export | 导入导出 |
+| PUT /api/user/resetPwd | 重置用户密码 |
+| GET /api/user/document/:id | 用户打印信息 |
+| POST /api/role/menu/save | 保存角色菜单权限 |
+| POST /api/tenant/account | 添加租户账号 |
+| GET /api/tenant/users/:tenantId | 查询租户用户 |
+| GET /api/dict/item/getDictItemList/:code | 字典项快捷查询（登录即可） |
+| GET /api/dict/refreshCache | 刷新字典缓存 |
+| GET /api/job/runOnce/:id、pause/:id、resume/:id | 任务执行/暂停/恢复 |
+| GET /api/onlineUser/forceLogout/:id | 强制下线指定会话 |
+| GET /api/onlineUser/forceLogoutUser/:userId | 踢出用户全部设备 |
 
-## 菜单管理
+注：用户的角色分配没有独立接口——Add/Update 请求的 `roles` 字段在事务内重写 gin_user_role。
 
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/menu/list` | sys:menu:page | 菜单列表（树形） |
-| GET | `/api/menu/detail/:id` | sys:menu:detail | 详情 |
-| POST | `/api/menu/add` | sys:menu:add | 新增 |
-| PUT | `/api/menu/update` | sys:menu:update | 修改 |
-| DELETE | `/api/menu/delete/:id` | sys:menu:delete | 删除 |
+## 约定提醒
 
-## 部门管理
+- 请求/响应字段小驼峰；分页 pageNo/pageSize → PageData
+- 信封 0/1/401；Bearer access token
+- 精确清单与 schema：`GET /api.json`
 
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/dept/list` | sys:dept:page | 部门列表（树形） |
-| GET | `/api/dept/detail/:id` | sys:dept:detail | 详情 |
-| POST | `/api/dept/add` | sys:dept:add | 新增 |
-| PUT | `/api/dept/update` | sys:dept:update | 修改 |
-| DELETE | `/api/dept/delete/:id` | sys:dept:delete | 删除 |
+## 相关
 
-## 岗位管理
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/position/page` | sys:position:page | 分页列表 |
-| GET | `/api/position/list` | sys:position:list | 全量列表 |
-| GET | `/api/position/detail/:id` | sys:position:detail | 详情 |
-| POST | `/api/position/add` | sys:position:add | 新增 |
-| PUT | `/api/position/update` | sys:position:update | 修改 |
-| DELETE | `/api/position/delete/:id` | sys:position:delete | 删除 |
-| DELETE | `/api/position/batchDelete` | sys:position:batchDelete | 批量删除 |
-
-## 职级管理
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/level/page` | sys:level:page | 分页列表 |
-| GET | `/api/level/list` | sys:level:list | 全量列表 |
-| GET | `/api/level/detail/:id` | sys:level:detail | 详情 |
-| POST | `/api/level/add` | sys:level:add | 新增 |
-| PUT | `/api/level/update` | sys:level:update | 修改 |
-| DELETE | `/api/level/delete/:id` | sys:level:delete | 删除 |
-| DELETE | `/api/level/batchDelete` | sys:level:batchDelete | 批量删除 |
-| GET | `/api/level/export` | sys:level:export | 导出 |
-| POST | `/api/level/import` | sys:level:import | 导入 |
-
-## 数据字典
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/dict/page` | sys:dict:page | 分页列表 |
-| GET | `/api/dict/detail/:id` | sys:dict:detail | 详情 |
-| GET | `/api/dict/refreshCache` | sys:dict:refreshCache | 刷新缓存 |
-| POST | `/api/dict/add` | sys:dict:add | 新增 |
-| PUT | `/api/dict/update` | sys:dict:update | 修改 |
-| DELETE | `/api/dict/delete/:id` | sys:dict:delete | 删除 |
-| DELETE | `/api/dict/batchDelete` | sys:dict:batchDelete | 批量删除 |
-
-## 字典项
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/dict/item/page` | sys:dict:item:page | 分页列表 |
-| GET | `/api/dict/item/detail/:id` | sys:dict:item:detail | 详情 |
-| GET | `/api/dict/item/getDictItemList/:code` | - | 按编码获取字典项 |
-| POST | `/api/dict/item/add` | sys:dict:item:add | 新增 |
-| PUT | `/api/dict/item/update` | sys:dict:item:update | 修改 |
-| DELETE | `/api/dict/item/delete/:id` | sys:dict:item:delete | 删除 |
-| DELETE | `/api/dict/item/batchDelete` | sys:dict:item:batchDelete | 批量删除 |
-
-## 租户管理
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/tenant/page` | sys:tenant:page | 分页列表 |
-| GET | `/api/tenant/detail/:id` | sys:tenant:detail | 详情 |
-| GET | `/api/tenant/users/:tenantId` | - | 租户用户列表 |
-| POST | `/api/tenant/add` | sys:tenant:add | 新增 |
-| POST | `/api/tenant/account` | sys:tenant:add | 创建租户账号 |
-| PUT | `/api/tenant/update` | sys:tenant:update | 修改 |
-| DELETE | `/api/tenant/delete/:id` | sys:tenant:delete | 删除 |
-| DELETE | `/api/tenant/batchDelete` | sys:tenant:batchDelete | 批量删除 |
-
-## 系统配置
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/config/page` | sys:config:page | 分页列表 |
-| GET | `/api/config/list` | sys:config:list | 全量列表 |
-| GET | `/api/config/detail/:id` | sys:config:detail | 详情 |
-| GET | `/api/config/web/index` | sys:config:web | 网站配置 |
-| POST | `/api/config/web/save` | sys:config:web | 保存网站配置 |
-| POST | `/api/config/add` | sys:config:add | 新增 |
-| PUT | `/api/config/update` | sys:config:update | 修改 |
-| DELETE | `/api/config/delete/:id` | sys:config:delete | 删除 |
-
-## 配置项
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/config/item/page` | sys:config:item:page | 分页列表 |
-| GET | `/api/config/item/list` | sys:config:item:list | 全量列表 |
-| GET | `/api/config/item/detail/:id` | sys:config:item:detail | 详情 |
-| POST | `/api/config/item/add` | sys:config:item:add | 新增 |
-| PUT | `/api/config/item/update` | sys:config:item:update | 修改 |
-| DELETE | `/api/config/item/delete/:id` | sys:config:item:delete | 删除 |
-
-## 系统参数
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/param/page` | sys:param:page | 分页列表 |
-| GET | `/api/param/list` | sys:param:list | 全量列表 |
-| GET | `/api/param/detail/:id` | sys:param:detail | 详情 |
-| POST | `/api/param/add` | sys:param:add | 新增 |
-| PUT | `/api/param/update` | sys:param:update | 修改 |
-| DELETE | `/api/param/delete/:id` | sys:param:delete | 删除 |
-
-## 通知公告
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/notice/page` | sys:notice:page | 分页列表 |
-| GET | `/api/notice/list` | - | 全量列表 |
-| GET | `/api/notice/detail/:id` | sys:notice:detail | 详情 |
-| POST | `/api/notice/add` | sys:notice:add | 新增 |
-| PUT | `/api/notice/update` | sys:notice:update | 修改 |
-| DELETE | `/api/notice/delete/:id` | sys:notice:delete | 删除 |
-
-## 城市行政区划
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/city/list` | sys:city:page | 城市列表 |
-| GET | `/api/city/detail/:id` | sys:city:detail | 详情 |
-| POST | `/api/city/add` | sys:city:add | 新增 |
-| PUT | `/api/city/update` | sys:city:update | 修改 |
-| DELETE | `/api/city/delete/:id` | sys:city:delete | 删除 |
-| GET | `/api/city/getCityList/:parentCode` | - | 按父编码获取城市 |
-
-## 文章管理
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/article/page` | sys:article:page | 分页列表 |
-| GET | `/api/article/list` | sys:article:list | 全量列表 |
-| GET | `/api/article/detail/:id` | sys:article:detail | 详情 |
-| POST | `/api/article/add` | sys:article:add | 新增 |
-| PUT | `/api/article/update` | sys:article:update | 修改 |
-| DELETE | `/api/article/delete/:id` | sys:article:delete | 删除 |
-| DELETE | `/api/article/batchDelete` | sys:article:batchDelete | 批量删除 |
-
-## 文章分类
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/category/page` | sys:category:page | 分页列表 |
-| GET | `/api/category/list` | sys:category:list | 全量列表 |
-| GET | `/api/category/detail/:id` | sys:category:detail | 详情 |
-| POST | `/api/category/add` | sys:category:add | 新增 |
-| PUT | `/api/category/update` | sys:category:update | 修改 |
-| DELETE | `/api/category/delete/:id` | sys:category:delete | 删除 |
-
-## 友情链接
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/link/page` | sys:link:page | 分页列表 |
-| GET | `/api/link/detail/:id` | sys:link:detail | 详情 |
-| POST | `/api/link/add` | sys:link:add | 新增 |
-| PUT | `/api/link/update` | sys:link:update | 修改 |
-| DELETE | `/api/link/delete/:id` | sys:link:delete | 删除 |
-
-## 定时任务
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/job/page` | sys:job:page | 分页列表 |
-| GET | `/api/job/list` | sys:job:list | 全量列表 |
-| GET | `/api/job/detail/:id` | sys:job:detail | 详情 |
-| GET | `/api/job/runOnce/:id` | sys:job:execute | 手动执行一次 |
-| GET | `/api/job/pause/:id` | sys:job:pause | 暂停任务 |
-| GET | `/api/job/resume/:id` | sys:job:resume | 恢复任务 |
-| POST | `/api/job/add` | sys:job:add | 新增 |
-| PUT | `/api/job/update` | sys:job:update | 修改 |
-| DELETE | `/api/job/delete/:id` | sys:job:delete | 删除 |
-
-## 任务日志
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/job/log/page` | sys:job:log:page | 分页列表 |
-| GET | `/api/job/log/detail/:id` | sys:job:log:detail | 详情 |
-| DELETE | `/api/job/log/delete/:id` | sys:job:log:delete | 删除 |
-
-## 操作日志
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/oper/log/page` | sys:oper:log:page | 分页列表 |
-| GET | `/api/oper/log/detail/:id` | sys:oper:log:detail | 详情 |
-| DELETE | `/api/oper/log/delete/:id` | sys:oper:log:delete | 删除 |
-
-## 登录日志
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/login/log/page` | sys:login:log:page | 分页列表 |
-| GET | `/api/login/log/detail/:id` | sys:login:log:detail | 详情 |
-| DELETE | `/api/login/log/delete/:id` | sys:login:log:delete | 删除 |
-
-## 文件上传
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| POST | `/api/upload/uploadFile` | - | 上传文件 |
-
-## 代码生成器
-
-| 方法 | 路径 | 权限码 | 说明 |
-|------|------|--------|------|
-| GET | `/api/generator/page` | sys:generator:page | 可生成表列表 |
-| POST | `/api/generator/preview` | sys:generator:preview | 预览生成代码 |
-| POST | `/api/generator/generate` | sys:generator:generate | 生成代码 |
-| POST | `/api/generator/batchGenerate` | sys:generator:generate | 批量生成 |
+- [8.8 API 接口总览](/zh/api-spec/overview.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/components.md

@@ -1,105 +1,58 @@
-# G. 前端组件速查
+# H. 前端组件速查
 
-:::tip 概述
-以下组件定义在 `ui/src/components/` 目录下，可在页面中直接引入使用。
+:::tip 说明
+`ui/src/components` 公共组件速查（28 个）。业务页面优先复用；页面私有组件放 views 下 components/。
 :::
 
-## 数据展示
+## 骨架与容器
 
-| 组件 | 路径 | 说明 | 核心 Props |
-|------|------|------|-----------|
-| BasicTable | `components/Table/` | 数据表格 | `columns`、`dataSource`、`pagination` |
-| PageWrapper | `components/Page/` | 页面容器 | `title`、`contentFullHeight` |
-| CountTo | `components/CountTo/` | 数字动画 | `startVal`、`endVal`、`duration` |
-| Qrcode | `components/Qrcode/` | 二维码 | `value`、`size`、`level` |
-| Icon | `components/icon/` | 图标选择器 | `value`、`disabled` |
+| 组件 | 职责 |
+|---|---|
+| Page | 页面容器（标题/内容区/响应高度） |
+| Modal | 弹窗封装（新增/编辑常用） |
+| Form | 表单容器（布局/重置/提交） |
+| Table | 数据表格封装（列配置/加载/选择） |
+| pagination | 分页条（pageNo/pageSize 契约） |
 
 ## 数据录入
 
-| 组件 | 路径 | 说明 | 核心 Props |
-|------|------|------|-----------|
-| BasicForm | `components/Form/` | 动态表单 | `schemas`、`labelWidth` |
-| BasicModal | `components/Modal/` | 弹窗 | `title`、`width`、`okText` |
-| BasicUpload | `components/Upload/` | 文件上传 | `action`、`maxCount`、`accept` |
-| Editor | `components/Editor/` | 富文本编辑器 | `value`、`height`、`placeholder` |
-| Password | `components/Password/` | 密码强度 | `value`、`placeholder` |
-| ChinaArea | `components/ChinaArea/` | 省市区联动 | `value`、`placeholder` |
-| Region | `components/Region/` | 行政区划 | `value`、`level` |
-| Cropper | `components/Cropper/` | 头像裁剪 | `image`、`aspectRatio` |
-| NumberInput | `components/numberInput/` | 数字输入 | `value`、`min`、`max` |
-| PriceInput | `components/priceInput/` | 价格输入 | `value`、`precision` |
+| 组件 | 职责 |
+|---|---|
+| Select | 下拉（支持字典数据源） |
+| TableSelect | 表格选择器（选人/选部门，单/多选） |
+| Upload | 文件/图片上传（两段式契约） |
+| Editor | 富文本（TinyMCE / vue-quill 双引擎） |
+| Cropper | 图片裁剪 |
+| Password | 密码输入 |
+| numberInput / priceInput | 数字/金额输入（精度控制） |
+| ChinaArea / Region | 省市区级联 |
 
-## Excel
+## 数据展示
 
-| 组件 | 路径 | 说明 |
-|------|------|------|
-| ImportExcel | `components/Excel/` | Excel 导入（解析文件） |
-| Export2Excel | `components/Excel/` | Excel 导出（生成文件） |
+| 组件 | 职责 |
+|---|---|
+| CountTo | 数字滚动动画 |
+| Qrcode | 二维码生成 |
+| Render | 配置化/函数式渲染 |
+| icon | 图标（菜单与页面统一入口） |
 
-## 其他
+## 功能性
 
-| 组件 | 路径 | 说明 |
-|------|------|------|
-| Authority | `components/Authority/` | 权限组件（根据权限显示/隐藏） |
-| CheckToken | `components/CheckToken/` | Token 校验组件 |
-| Lockscreen | `components/Lockscreen/` | 锁屏组件 |
-| Websocket | `components/Websocket/` | WebSocket 组件 |
+| 组件 | 职责 |
+|---|---|
+| Authority | 权限包装（组件式权限控制） |
+| CheckToken | 令牌校验 |
+| Websocket | WebSocket 封装（实时推送） |
+| Lockscreen | 锁屏 |
+| Application | 应用级注入 |
+| importFile | 导入文件交互 |
+| Excel | 前端 Excel 解析/生成 |
 
-## 使用示例
+## 速览入口
 
-### BasicTable
+组件 props 与用法以各组件源码注释为准（`ui/src/components/{名}`）。典型组合见：
 
-```vue
-<template>
-  <BasicTable @register="registerTable" />
-</template>
-
-<script setup>
-import { BasicTable, useTable } from '@/components/Table';
-
-const [registerTable] = useTable({
-  api: getExamplePage,
-  columns: [
-    { title: 'ID', field: 'id', width: 80 },
-    { title: '名称', field: 'name' },
-    { title: '状态', field: 'statusText', width: 100 },
-  ],
-});
-</script>
-```
-
-### BasicForm
-
-```vue
-<template>
-  <BasicForm @register="registerForm" />
-</template>
-
-<script setup>
-import { BasicForm, useForm } from '@/components/Form';
-
-const [registerForm] = useForm({
-  schemas: [
-    { field: 'name', label: '名称', component: 'Input', required: true },
-    { field: 'status', label: '状态', component: 'Select', componentProps: { options: [...] } },
-  ],
-});
-</script>
-```
-
-### BasicModal
-
-```vue
-<template>
-  <BasicModal @register="registerModal" @ok="handleSubmit" />
-</template>
-
-<script setup>
-import { BasicModal, useModal } from '@/components/Modal';
-
-const [registerModal, { openModal, closeModal }] = useModal();
-
-const handleAdd = () => openModal(true, { isUpdate: false });
-const handleSubmit = async () => { /* ... */ closeModal(); };
-</script>
-```
+- [9.9 表格与页面组件](/zh/frontend/table-components.html)
+- [9.10 数据录入组件](/zh/frontend/form-components.html)
+- [9.11 数据展示组件](/zh/frontend/display-components.html)
+- [9.12 Excel 导入导出组件](/zh/frontend/excel-components.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/config-reference.md

@@ -1,145 +1,93 @@
 # C. 配置项速查
 
-## 后端 .env 配置
-
-:::tip 格式说明
-`.env` 文件采用 INI 分组格式，`[SECTION]` 表示分组，分组下的 `KEY = value` 对应该分组的配置项。
+:::tip 说明
+`config/config.yaml` 全部配置节速查。任意键可用环境变量覆盖（大写 + 点换下划线 + `APP_` 前缀，仅覆盖已存在键）。完整注释见配置文件本身。
 :::
 
-### 全局变量
+## server
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `APP_DEBUG` | `true` | 调试模式（生产环境设为 false） |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| server.address | :8000 | 监听地址 |
 
-### 应用配置 `[APP]`
+## logger
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认时区 |
-| `DEMO` | `false` | 演示模式（开启后拦截写操作） |
-| `SHOW_ERROR_MSG` | `true` | 显示错误详情（生产环境设为 false） |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| logger.level | all | debug/info/warn/error/all |
+| logger.stdout | true | 控制台输出 |
+| logger.path | log | 日志目录 |
 
-### 数据库配置 `[DATABASE]`
+## database.default
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `TYPE` | `mysql` | 数据库类型：mysql / pgsql / sqlsrv / oracle / sqlite |
-| `HOSTNAME` | `127.0.0.1` | 数据库主机 |
-| `DATABASE` | - | 数据库名（SQLite 为文件路径） |
-| `USERNAME` | `root` | 数据库用户 |
-| `PASSWORD` | - | 数据库密码 |
-| `HOSTPORT` | `3306` | 数据库端口 |
-| `CHARSET` | `utf8mb4` | 字符集 |
-| `DEBUG` | `true` | 是否开启 SQL 调试 |
-| `PREFIX` | `think_` | 表前缀 |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| driver | mysql | mysql/postgres/sqlserver/sqlite/oracle |
+| host / port | 127.0.0.1 / 3306 | 连接（sqlite 忽略） |
+| username / password | root / root | 账号 |
+| dbname | easygoadmin.gin.elevue | 库名（sqlite 为文件路径） |
+| params | charset=utf8mb4&... | DSN 追加参数 |
+| debug | false | SQL 日志 |
+| maxOpenConns / maxIdleConns | 50 / 10 | 连接池 |
+| connMaxLifetime | 3600 | 连接存活（秒） |
 
-各数据库默认端口：
+## redis.default
 
-| 数据库 | 默认端口 | 默认用户 |
-|--------|----------|----------|
-| MySQL | 3306 | root |
-| PostgreSQL | 5432 | postgres |
-| SQL Server | 1433 | sa |
-| Oracle | 1521 | - |
-| SQLite | - | - |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| address | 127.0.0.1:6379 | 为空降级内存 |
+| db | 0 | 库编号 |
+| pass | — | 密码 |
 
-### JWT 配置 `[JWT]`
+## jwt / captcha / rateLimit
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `SECRET` | 内置默认 | 签名密钥（**生产环境务必修改**） |
-| `ACCESS_TTL` | `7200` | access_token 有效期（秒） |
-| `REFRESH_TTL` | `604800` | refresh_token 有效期（秒） |
-| `ISSUER` | `rxthinkcmf` | 签发者标识 |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| jwt.secret | 样例值 | 签名密钥（生产必换） |
+| jwt.issuer | easygoadmin | 签发者 |
+| jwt.accessTokenExpire | 7200 | 访问令牌（秒） |
+| jwt.refreshTokenExpire | 604800 | 刷新令牌（秒） |
+| captcha.expire / length / chars | 300 / 6 / 字符集 | 验证码参数 |
+| captcha.bypassCode | 空 | 万能码（prod 拒绝非空） |
+| captcha.fontPath / imageWidth / ... | Vera.ttf / 160... | 渲染参数 |
+| rateLimit.enable / limit / windowSeconds | true / 120 / 60 | 普通限流 |
+| rateLimit.authLimit | 10 | 认证接口限流 |
 
-### 文件上传配置 `[FILE]`
+## operationLog / job / tenant / app
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `UPLOAD_DIR` | - | 上传根目录（绝对路径） |
-| `DOMAIN_URL` | - | 文件访问域名 |
-| `IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp,svg` | 图片允许后缀 |
-| `FILE_EXT` | 多种后缀 | 文件允许后缀 |
-| `MAX_SIZE` | `10` | 最大文件大小（MB） |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| operationLog.enable / logQuery | true / true | 操作日志开关 |
+| job.logRetentionDays | 90 | 日志保留（LogClean） |
+| job.lockTTLSeconds | 300 | 任务锁 TTL |
+| tenant.defaultId | 1 | 超管新增默认归属 |
+| app.timezone | Asia/Shanghai | 时区 |
+| app.demo | false | 演示模式（拒写） |
+| app.prod | false | 生产模式（红线校验） |
 
-### 缓存配置 `[CACHE]`
+## api / cors / file
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `DRIVER` | `file` | 缓存驱动：file / redis |
-| `REDIS_HOST` | `127.0.0.1` | Redis 主机（driver=redis 时生效） |
-| `REDIS_PORT` | `6379` | Redis 端口（driver=redis 时生效） |
-| `REDIS_PASSWORD` | - | Redis 密码 |
-| `REDIS_DB` | `0` | Redis 数据库编号 |
-| `REDIS_PREFIX` | `rx:` | 缓存键前缀 |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| api.proxyIps | 127.0.0.1,::1,... | 受信代理（CIDR） |
+| api.maxBodyMB | 10 | 请求体上限 |
+| api.docs / api.metrics | true / true | 文档/指标端点 |
+| cors.allowOrigin | * | 允许来源 |
+| file.uploadDir | upload 绝对路径 | 上传根 |
+| file.domainUrl | http://file.gin.elevue（样例） | 文件访问域址（生产覆盖；为空则应用回退） |
+| file.imageExt / fileExt / maxSize | 白名单 / 10 | 扩展名与大小 |
+| file.tempExpireDays | 7 | temp 保留天数 |
 
-### CORS 配置 `[CORS]`
+## generator / ip2region
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `ALLOW_ORIGIN` | `*` | 允许的跨域来源 |
+| 键 | 默认 | 说明 |
+|---|---|---|
+| generator.enable | true | 总开关（生产 false） |
+| generator.parentMenuId | 189 | 菜单挂载父级 |
+| generator.overwrite | true | 覆盖策略 |
+| ip2region.path | resource/data/ip2region.xdb | 归属地库 |
 
-### API 配置 `[API]`
+## 相关
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `CAMEL_SNAKE_CONVERT` | `true` | 驼峰/下划线自动转换 |
-| `PROXY_IPS` | （空） | 受信代理 IP 列表（逗号分隔，支持 CIDR）。部署在 CDN/负载均衡后面时配置，中间件会从 `X-Forwarded-For` / `X-Real-IP` 头提取真实客户端 IP。未配置时默认信任 `127.0.0.1` 和 `::1`。 |
-
-### 验证码配置 `[CAPTCHA]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `CAPTCHA_BYPASS_CODE` | （空） | 万能验证码，仅开发调试用，**生产环境务必留空** |
-| `CAPTCHA_LENGTH` | `6` | 验证码字符长度（4-6位） |
-| `CAPTCHA_EXPIRE` | `300` | 过期时间（秒） |
-| `CAPTCHA_RATE_WINDOW` | `60` | 防刷窗口期（秒） |
-| `CAPTCHA_RATE_LIMIT` | `20` | 窗口期内最大获取次数 |
-| `CAPTCHA_CHARS` | `ABCDEFGHJKLMNPQRSTUVWXYZ2346789` | 字符集 |
-| `CAPTCHA_FONT_PATH` | `static/fonts/Vera.ttf` | 字体路径 |
-| `CAPTCHA_IMAGE_WIDTH` | `160` | 图片宽度（像素） |
-| `CAPTCHA_IMAGE_HEIGHT` | `50` | 图片高度（像素） |
-| `CAPTCHA_FONT_SIZE` | `28` | 字体大小 |
-| `CAPTCHA_NOISE_LINES` | `8` | 干扰线数量 |
-| `CAPTCHA_NOISE_DOTS` | `500` | 噪点数量 |
-
-### 代码生成器配置 `[GENERATOR]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `PARENT_MENU_ID` | `189` | 生成模块的父菜单ID |
-| `APP_NAME` | `tool` | 模块应用名（路由前缀） |
-
-### 国际化配置 `[LANG]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `default_lang` | `zh-cn` | 默认语言 |
-
-## 前端环境变量
-
-| 变量 | 说明 |
-|------|------|
-| `VITE_GLOB_API_URL` | API 基础路径（如 `/api`） |
-| `VITE_GLOB_API_URL_PREFIX` | API 前缀 |
-
-## 配置文件对照
-
-| .env 分组 | 配置文件 | 主要配置键 |
-|-----------|---------|-----------|
-| `[DATABASE]` | `config/database.php` | `type` / `hostname` / `database` / `username` / `password` |
-| `[JWT]` | `config/jwt.php` | `secret` / `access_ttl` / `refresh_ttl` |
-| `[FILE]` | `config/file.php` | `upload_dir` / `domain_url` / `max_size` |
-| `[CACHE]` | `config/cache.php` | `driver` / `redis_host` / `redis_port` |
-| `[CORS]` | `config/cors.php` | `allow_origin` |
-| `[API]` | `config/api.php` | `camel_snake_convert` |
-| `[CAPTCHA]` | 无配置文件，`CaptchaService` 直接读取 `env()` | `captcha_bypass_code` / `captcha_length` / `captcha_expire` |
-| `[LANG]` | `config/lang.php` | `default_lang` |
-| — | `config/tenant.php` | `default_tenant_id` |
-
-### 租户配置
-
-| 配置文件 | 配置键 | 默认值 | 说明 |
-|----------|--------|--------|------|
-| `config/tenant.php` | `default_tenant_id` | `1` | 默认租户ID，超管操作租户隔离表时自动代入 |
+- [2.3 配置文件与环境变量](/zh/quickstart/env-vars.html)
+- [.env.example]（键一致性由 make check-config 硬检查）

EasyGoAdmin_Gin_EleVue/zh/appendix/database-tables.md

@@ -1,76 +1,71 @@
 # B. 数据库表结构速查
 
-## SQL 脚本目录
+:::tip 说明
+25 张 `gin_` 表。所有表统一带公共审计列：`create_user / create_time / update_user / update_time / del_flag`；租户级表（标 ※）另含 `tenant_id`（白名单 9 张：user/user_role/role/dept/level/position/article/category/notice/link）。
+:::
 
-项目为每种数据库提供了独立的 SQL 脚本：
+## 组织权限
 
-```text
-document/
-├── mysql/rxthinkcmf.thinkphp8.elevue.sql        # MySQL 版本
-├── postgresql/rxthinkcmf.thinkphp8.elevue.sql   # PostgreSQL 版本
-├── sqlserver/rxthinkcmf.thinkphp8.elevue.sql    # SQL Server 版本
-├── oracle/rxthinkcmf.thinkphp8.elevue.sql       # Oracle 版本
-└── sqlite/rxthinkcmf.thinkphp8.elevue.sql       # SQLite 版本
-```
+| 表 | 业务列（除公共列） |
+|---|---|
+| gin_user ※ | tenant_id, code, realname, gender, avatar, mobile, email, dept_id, level_id, position_id, province_code, city_code, district_code, street_code, city_info, address, username, password, salt, intro, status, sort, note |
+| gin_user_role ※ | tenant_id, user_id, role_id |
+| gin_role ※ | tenant_id, name, data_scope, code, sort, note |
+| gin_role_menu ※ | tenant_id, role_id, menu_id |
+| gin_menu | name, icon, icon2, parent_id, path, component, permission, target, type, status, hide, sort, note |
+| gin_dept ※ | tenant_id, name, type, parent_id, sort, note |
+| gin_level ※ | tenant_id, name, status, sort |
+| gin_position ※ | tenant_id, name, status, sort |
+| gin_tenant | name, code, contact, mobile, email, address, logo, status, expire_time, max_user_num, note |
 
-各脚本已针对对应数据库的 SQL 语法做了适配，可直接导入使用。
+## 内容管理
 
-## 用户相关
+| 表 | 业务列 |
+|---|---|
+| gin_article ※ | tenant_id, category_id, title, cover, images, intro, content, author, status, click, sort |
+| gin_category ※ | tenant_id, category_name, category_code, parent_id, sort, note |
+| gin_notice ※ | tenant_id, title, cover, type, click_num, status, content |
+| gin_link ※ | tenant_id, name, type, url, form, image, status, sort, note |
 
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_user | 用户表 | tenant_id, code, username, password, salt, realname, gender, avatar, mobile, email, status, dept_id, level_id, position_id, province_code, city_code, district_code, street_code, city_info, address, intro, note, sort |
-| think_user_role | 用户角色关联 | user_id, role_id |
-| think_role | 角色表 | tenant_id, name, code, data_scope, sort, note |
-| think_role_menu | 角色菜单关联 | role_id, menu_id |
-| think_menu | 菜单表 | parent_id, name, permission, type, path, component |
-| think_dept | 部门表 | parent_id, name, sort |
-| think_position | 岗位表 | name, status, sort |
-| think_level | 职级表 | name, status, sort |
+## 数据与配置
 
-## 系统配置
+| 表 | 业务列 |
+|---|---|
+| gin_dict | name, code, sort, note |
+| gin_dict_item | name, value, dict_id, sort, note |
+| gin_param | name, code, value, type, status, sort, note |
+| gin_config | name, code, sort, note |
+| gin_config_item | name, code, value, options, config_id, type, status, sort, note |
+| gin_city | city_code, area_code, parent_code, zip_code, level, pid, name, short_name, full_name, pinyin, lng, lat |
 
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_dict | 字典表 | name, code |
-| think_dict_item | 字典项 | dict_id, name, value, sort |
-| think_config | 配置表 | name, code |
-| think_config_item | 配置项 | config_id, name, code, value |
-| think_param | 参数表 | name, code, value, status |
+## 任务与日志
 
-## 租户
+| 表 | 业务列 |
+|---|---|
+| gin_job | job_name, job_alias, job_group, job_trigger, status, cron_expression, execute_policy, is_sync, url, params, note |
+| gin_job_log | job_id, job_name, job_group, job_trigger, job_message, cron_expression, status, start_time, end_time, consume_time, exception_info |
+| gin_operation_log | title, type, source, method, request_method, url, param, result, ip, location, os, browser, consume_time, status, error |
+| gin_login_log | username, log_type, source, method, request_method, url, param, result, ip, location, os, browser, consume_time, status, error |
 
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_tenant | 租户表 | name, code, contact, mobile, email, address, status, expire_time, max_user_num, note |
+## 工具
 
-## 内容
+| 表 | 业务列 |
+|---|---|
+| gin_file_template | name, code, file_name, file_path, note, sort |
+| gin_example | name, avatar, type, status, sort |
 
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_article | 文章表 | title, category_id, cover, content, status |
-| think_category | 分类表 | parent_id, name, sort |
-| think_link | 链接表 | name, url, sort |
-| think_notice | 公告表 | title, content, status |
+## 关键列语义
 
-## 日志
+| 列 | 语义 |
+|---|---|
+| del_flag | 0 正常 / 1 已删除（全局钩子与 Scope 执行） |
+| data_scope | 角色数据范围：1 全部 / 2 本部门及以下 / 3 本部门 / 4 仅本人 |
+| gin_menu.permission | 权限节点码（sys:模块:操作） |
+| gin_menu.type | 0-菜单（页面）1-节点（纯权限点） |
+| gin_job.url | 任务处理器注册名（数据驱动查找） |
+| gin_user.password / salt | bcrypt(password+salt)，salt 独立存储 |
 
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_login_log | 登录日志 | username, status, ip, location |
-| think_operation_log | 操作日志 | title, type, method, url, param, ip |
+## 相关
 
-## 定时任务
-
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_job | 任务表 | job_name, url, cron_expression, status |
-| think_job_log | 任务日志 | job_id, status, job_message |
-
-## 其他
-
-| 表名 | 说明 | 关键字段 |
-|------|------|----------|
-| think_city | 城市表 | name, code, parent_code, level |
-| think_file_template | 文件模板 | name, code, file_path |
-| think_example | 案例演示 | name, type, status, sort, avatar |
+- [4.10 数据库设计](/zh/architecture/database-design.html)
+- [2.2 数据库初始化](/zh/quickstart/database-init.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/enums.md

@@ -1,84 +1,39 @@
-# I. 前端 Enums 速查
+# J. 前端枚举速查
 
-:::tip 概述
-前端枚举定义在 `ui/src/enums/` 目录下，用于统一管理常量值。
+:::tip 说明
+`ui/src/enums` 枚举常量速查。统一 `as const` + 类型导出，禁止散落裸字符串常量。
 :::
 
-## httpEnum
+## 枚举清单
 
-**文件**：`enums/httpEnum.ts`
-
-```typescript
-// 请求方法
-export enum RequestEnum {
-  GET = 'GET',
-  POST = 'POST',
-  PUT = 'PUT',
-  DELETE = 'DELETE',
-}
-
-// 响应状态码
-export enum ResultEnum {
-  SUCCESS = 0,     // 业务成功
-  FAIL = 1,        // 业务失败
-}
-
-// 内容类型
-export enum ContentTypeEnum {
-  JSON = 'application/json',
-  FORM_URLENCODED = 'application/x-www-form-urlencoded',
-}
-```
-
-## pageEnum
-
-**文件**：`enums/pageEnum.ts`
-
-```typescript
-export enum PageEnum {
-  // 登录页
-  BASE_LOGIN = '/login',
-  // 首页
-  BASE_HOME = '/dashboard',
-  // 错误页
-  BASE_ERROR_LOG = '/exception/404',
-  REDIRECT = '/redirect',
-}
-```
+| 文件 | 内容 | 典型消费方 |
+|---|---|---|
+| pageEnum.ts | 页面路径常量（BASE_LOGIN 等） | 路由守卫、登录跳转 |
+| httpEnum.ts | HTTP 常量（结果类型、超时、重试） | http 拦截器 |
+| permissionsEnum.ts | 权限相关常量 | usePermission、指令 |
+| roleEnum.ts | 角色常量 | 超管判定展示 |
+| cacheEnum.ts | 缓存键常量 | Storage 相关 |
+| breakpointEnum.ts | 响应式断点 | 布局、侧边栏折叠 |
+| avatarEnum.ts | 头像相关常量 | 个人中心 |
 
 ## 使用示例
 
 ```typescript
-import { ResultEnum } from '@/enums/httpEnum';
 import { PageEnum } from '@/enums/pageEnum';
 
-// 判断响应是否成功
-if (response.code === ResultEnum.SUCCESS) {
-    // 处理成功
-}
-
-// 跳转登录页
-router.push(PageEnum.BASE_LOGIN);
-
-// 判断请求方法
-if (method === RequestEnum.POST) {
-    // POST 请求
-}
+const loginPath = PageEnum.BASE_LOGIN;
 ```
 
-## 自定义枚举
+## 与后端常量的关系
 
-```typescript
-// 添加新枚举时，在 enums/ 目录下创建文件
-// ui/src/enums/statusEnum.ts
+前后端共享语义的值（如超管通配权限码 `*:*:*`、数据范围档位 1–4）两端各自有常量定义——修改任一侧必须同步另一侧，并更新本速查。
 
-export enum UserStatus {
-  ENABLE = 1,
-  DISABLE = 2,
-}
+## 编写规约
 
-export enum ArticleStatus {
-  DRAFT = 0,
-  PUBLISHED = 1,
-}
-```
+- 键名大写下划线，字符串值为主
+- 带类型导出（`typeof Xxx` / 联合类型）
+- 新枚举先确认无既有文件覆盖该域
+
+## 相关
+
+- [9.18 Hooks 与枚举](/zh/frontend/hooks-enums.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/faq.md

@@ -1,57 +1,104 @@
 # A. 常见问题汇总
 
-:::tip 概述
-本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
+:::tip 说明
+全项目高频问题的总入口，按主题分组并给出深入链接。分章 FAQ：[2.8 快速入门](/zh/quickstart/faq.html)、[3.12 模块开发](/zh/guide/faq.html)、[10.8 生成器](/zh/generator/faq.html)、[11.10 故障排查](/zh/deploy/troubleshooting.html)。
 :::
 
-## 环境问题
+## 启动与配置
 
-| 问题 | 解决方案 |
-|------|----------|
-| PHP 版本低于 8.2 | 升级到 PHP 8.2+，项目使用了 8.2 的强类型特性 |
-| 缺少 pdo_mysql 扩展 | `apt install php8.2-mysql` 或 `dnf install php-mysqlnd` |
-| 缺少 gd 扩展 | `apt install php8.2-gd` 或 `dnf install php-gd` |
-| Composer 下载慢 | `composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/` |
-| Redis 未安装 | 可选，改用 file 缓存：`.env` 中 `[CACHE]` 下设置 `DRIVER = file` |
-| 缺少 redis 扩展 | `pecl install redis` |
-| Oracle pdo_oci 加载失败（Windows） | 安装 Oracle Instant Client 19c + VC++ 2015-2022 Redistributable，php.ini 启用 `extension=pdo_oci`，配置系统 PATH 后重启 Apache |
-| 命令行有 pdo_oci，浏览器 phpinfo 没有 | Apache 服务启动时 PATH 未刷新，完全停止再启动 Apache 即可 |
-| Oracle Instant Client 路径含中文/空格导致加载失败 | 解压到 `C:\oracle\instantclient_19_20` 等固定路径，避免空格与中文 |
+**Q：启动即退出？**
 
-## 启动问题
+启动 fail-fast：JWT 密钥/DSN 校验失败直接退出。生产模式（app.prod=true）还拒绝默认密钥、非空万能码、未关闭的生成器。按报错提示修正配置或 APP_* 环境变量。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 端口被占用 | `php think run --port 8080` |
-| 数据库连接失败 | 检查 `.env` 中的数据库配置 |
-| 401 未授权 | 检查请求头是否携带 `Authorization: Bearer <token>` |
-| 403 禁止访问 | 检查用户权限配置，确认角色已分配菜单 |
-| 502 Bad Gateway | 检查 PHP-FPM 是否启动：`systemctl status php8.2-fpm` |
+**Q：Redis 连接失败会不会挂？**
 
-## 业务问题
+不会。自动降级内存模式并告警（多实例下语义退化，生产应修复 Redis）。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 唯一性校验报错 | 检查数据是否重复，确认 `uniqueFields` 配置 |
-| 枚举显示名为空 | 检查字典配置，确认 `serializeMaps` 正确 |
-| 文件上传失败 | 检查 `FILE.UPLOAD_DIR` 配置和目录权限 |
-| 导入失败 | 检查 Excel 表头是否与 `headerMap` 一致 |
-| 排序不生效 | 检查 `pageOrderBy` 配置，或前端 `orderField` 参数 |
+**Q：环境变量设置了不生效？**
 
-## 前端问题
+规则：键名大写 + 点换下划线 + `APP_` 前缀，**仅覆盖 YAML 已存在的键**，空值视为未设置。
 
-| 问题 | 解决方案 |
-|------|----------|
-| pnpm install 失败 | `rm -rf node_modules pnpm-lock.yaml && pnpm install` |
-| API 404 | 检查后端路由注册和 Vite 代理配置 |
-| 菜单不显示 | 检查菜单配置、组件路径、角色权限 |
-| 白屏 | 打开 F12 控制台查看错误 |
-| Token 频繁过期 | 检查 `JWT.ACCESS_TTL` 配置（默认 7200 秒） |
+**Q：新增配置键 make check-config 报错？**
 
-## 定时任务问题
+配置键必须与 .env.example 一致——同步更新样例文件。
 
-| 问题 | 解决方案 |
-|------|----------|
-| 任务不执行 | 检查 crontab 配置：`crontab -l` |
-| 任务重复执行 | 检查是否有多个 cron 或 daemon 在运行 |
-| 任务执行超时 | 检查 PHP `max_execution_time` 配置 |
+## 认证与权限
+
+**Q：Token 合法但 401？**
+
+在黑名单（已登出/被强制下线），或 IdentityLoader 未接线导致身份扩展为空。
+
+**Q：接口 403？**
+
+角色未授权该权限码，或菜单节点与 RouteSpec 拼写不一致。改授权后权限缓存最长 300 秒生效，重新登录立即生效。
+
+**Q：新授权/改菜单不生效？**
+
+前端路由是登录时生成的——重新登录刷新菜单与权限。
+
+## 数据访问
+
+**Q：查到已删除数据？**
+
+绕过了 `Ctx(ctx)`（用了 Raw 或裸 DB）。一切查询走仓储 Ctx 入口。
+
+**Q：物理删除被拦截？**
+
+设计行为。业务删除用软删除；特殊场景 `hooks.WithPhysicalDelete(ctx)` 显式放行。
+
+**Q：租户数据串了？**
+
+新租户级表必须同步登记 hooks.tenantTables 白名单（9 张），且表含 tenant_id 列。
+
+**Q：Update 后字段变零值？**
+
+Update 是全量表单语义——未提交字段按零值落库，前端须回传全部业务字段。
+
+## 文件
+
+**Q：上传成功但访问 404？**
+
+两段式：上传只进 temp，保存记录时才转正。另核对 file.domainUrl 与 nginx root 同构（不含 upload 段）。
+
+**Q：富文本图片失效？**
+
+正文引用的文件被清理；占位符还原依赖 domainUrl 配置正确。
+
+## 生成器
+
+**Q：生成后手写内容丢了？**
+
+overwrite=true 会覆盖全部产物。有手写内容的模块用 overwrite=false。
+
+**Q：枚举没生成字典？**
+
+列注释须为标准枚举形态：`1-在用 2-停用`。
+
+## 前端
+
+**Q：登录后白屏？**
+
+菜单 component 路径与 views 文件不符（懒加载失败）。
+
+**Q：刷新 404？**
+
+Nginx history 回退缺失：`try_files $uri $uri/ /index.html`。
+
+**Q：按钮不显示？**
+
+v-perm 码与菜单节点不一致，或角色未勾选该节点。
+
+## 性能与监控
+
+**Q：接口突然变慢？**
+
+排查顺序：/metrics（路由维度）→ 服务监控页 → SQL debug → 限流是否误伤 → Redis 是否降级。
+
+**Q：日志文件过大？**
+
+校准 job.logRetentionDays（LogClean 清理）与 zap 轮转；关闭 operationLog.logQuery 缓解查询类刷量。
+
+## 相关
+
+- [11.10 故障排查手册](/zh/deploy/troubleshooting.html)
+- [K. 术语表](/zh/appendix/glossary.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/functions.md

@@ -1,66 +1,100 @@
-# D. 公共函数速查
+# D. Utility 函数速查
 
-:::tip 概述
-以下函数定义在 `app/common.php` 中，可在任何地方直接调用。
+:::tip 说明
+`utility/` 13 个基础包的常用入口速查。全部包无业务语义、不 import internal。
 :::
 
-## 字符串 / 加密
+## apperr
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `random_string($length)` | 生成随机字符串 | `string random_string(int $length = 16)` |
-| `encrypt_password($password, $salt)` | 密码加密（bcrypt） | `array encrypt_password(string $password, ?string $salt = null)` |
-| `verify_password($password, $hash, $salt)` | 验证密码 | `bool verify_password(string $password, string $encryptPassword, string $salt)` |
+| API | 说明 |
+|---|---|
+| apperr.New(code, msg) | 构造业务错误 |
+| apperr.Newf(code, format, args...) | 格式化业务错误 |
+| .Code() | 取码（response 映射用） |
 
-## 文件处理
+业务代码经 consts 别名引用（CodeXxx 哨兵）。
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `upload_file($formName, $type)` | 上传文件到临时目录 | `array upload_file(string $formName = 'file', string $type = 'file')` |
-| `save_file($fileUrl, $saveDir)` | 临时文件迁移到正式目录 | `string\|false save_file(string $fileUrl, string $saveDir = '')` |
-| `save_content(&$content, $saveDir)` | 处理富文本中的媒体文件 | `bool save_content(string &$content, string $saveDir = 'article')` |
-| `get_file_url($path)` | 相对路径转完整 URL | `string get_file_url(string $path)` |
-| `create_file_path($saveDir, $ext)` | 生成文件存储路径 | `string create_file_path(string $saveDir = '', string $ext = '')` |
-| `save_remote_file($url, $saveDir)` | 保存远程文件 | `string\|false save_remote_file(string $url, string $saveDir = '')` |
-| `detect_image_ext($content)` | 根据内容检测图片后缀 | `?string detect_image_ext(string $content)` |
+## cache
 
-## 驼峰 / 下划线转换
+| API | 说明 |
+|---|---|
+| Init / Close / InMemory | 生命周期与模式查询 |
+| Set / Get / Del / Exists | 基础读写（TTL 秒） |
+| SetNX | 不存在才写（锁） |
+| Incr | 计数（限流） |
+| ZAdd/ZRem/ZRangeByScore/ZCard/ZRemRangeByScore | 有序集合（在线会话） |
+| PING / Info / DBSize | Redis 原始（监控） |
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `snake_to_camel($str)` | 下划线转驼峰 | `string snake_to_camel(string $str)` |
-| `camel_to_snake($str)` | 驼峰转下划线 | `string camel_to_snake(string $str)` |
-| `array_snake_to_camel($data)` | 数组键名下划线转驼峰（递归） | `array array_snake_to_camel(array $data)` |
-| `array_camel_to_snake($data, $except)` | 数组键名驼峰转下划线（递归） | `array array_camel_to_snake(array $data, array $except = [])` |
-| `is_camel_convert_enabled()` | 是否开启转换 | `bool is_camel_convert_enabled()` |
+## captcha
 
-## 工具函数
+| API | 说明 |
+|---|---|
+| Generate(ctx) | 返回 (key, dataURL) |
+| Verify(ctx, key, code) | 校验（一码一用） |
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `get_client_ip()` | 获取客户端 IP | `string get_client_ip()` |
-| `format_page_params($params)` | 格式化分页参数 | `array format_page_params(array $params)` |
+## config
 
-## 使用示例
+| API | 说明 |
+|---|---|
+| config.String(key, def) | 字符串 |
+| config.Bool(key, def) | 布尔 |
+| （数值型同族） | 配置读取统一入口 |
 
-```php
-// 生成随机字符串
-$str = random_string(32);
+## crypto
 
-// 密码加密
-$result = encrypt_password('123456');
-// ['password' => '$2y$12$...', 'salt' => 'xK7pMn3qRt']
+| API | 说明 |
+|---|---|
+| GenerateSalt() | 随机盐 |
+| HashPassword(password, salt) | bcrypt 哈希 |
+| VerifyPassword(hashed, password, salt) | 恒时比对 |
+| IsBcrypt(hashed) | 格式识别 |
 
-// 验证密码
-$ok = verify_password('123456', $user->password, $user->salt);
+## excel
 
-// 文件上传
-$result = upload_file('avatar', 'image');
-if (isset($result['error'])) {
-    return Result::fail($result['error']);
-}
+| API | 说明 |
+|---|---|
+| ReadSheet(file) | (headers, rows, err)，剥表头跳空行 |
+| WriteSheet(dir, baseName, headers, rows) | 写 xlsx，返回 fileName/filePath |
 
-// 驼峰转换
-camel_to_snake('createTime');    // 'create_time'
-snake_to_camel('create_time');   // 'createTime'
-```
+## ip2region
+
+IP → 归属地（消费 xdb 数据库文件），登录/操作日志采集用。
+
+## jwt
+
+| API | 说明 |
+|---|---|
+| Sign(ctx, tokenType, userID, tenantID, username, realname) | 签发双令牌 |
+| Parse(ctx, tokenStr) | 解析校验（Claims） |
+| ExpireDuration(ctx, tokenType) | 有效期 |
+
+## logger
+
+结构化 zap：Infof/Warnf/Errorf 等，支持 ctx 追踪字段（trace_id 自动关联）。
+
+## response
+
+| API | 说明 |
+|---|---|
+| Ok / OkMsg / Page | 成功信封 |
+| Fail / FailCode | 失败信封（401 原码透出） |
+| Write / WriteWithCode | 写出并记录（中间件读取） |
+| DeniedReason / GetDeniedReason | 拒绝原因传递 |
+
+## upload
+
+| API | 说明 |
+|---|---|
+| SaveTemp | 两段式第一段 |
+| SaveFromTemp / SaveFromTempMulti | 转正 |
+| GetFileUrl | 相对路径 → 访问 URL |
+| SafeJoin | 路径穿越防护 |
+| BaseDir / TempBaseDir / GetAccessBase | 目录基址 |
+
+## ua / validator
+
+ua：User-Agent 解析（OS/浏览器）。validator：binding 标签校验引擎（router 绑定层调用）。
+
+## 相关
+
+- [4.7 基座与公共体系](/zh/architecture/base-system.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/glossary.md

@@ -1,72 +1,64 @@
-# J. 术语表
+# K. 术语表
 
-## 后端术语
+:::tip 说明
+项目核心术语速查，按主题排列。首次出现的专业词都能在这里找到一句话解释。
+:::
 
-| 术语 | 全称 | 说明 |
-|------|------|------|
-| JWT | JSON Web Token | 无状态认证令牌，用于接口认证 |
-| RBAC | Role-Based Access Control | 基于角色的访问控制 |
-| CORS | Cross-Origin Resource Sharing | 跨域资源共享 |
-| ORM | Object-Relational Mapping | 对象关系映射，数据库操作抽象层 |
-| CRUD | Create/Read/Update/Delete | 增删改查 |
-| API | Application Programming Interface | 应用程序编程接口 |
-| bcrypt | - | 密码哈希算法，内置盐值 |
-| OPcache | - | PHP 字节码缓存扩展 |
-| Redis | - | 内存数据库，用于缓存 |
-| Nginx | - | Web 服务器 / 反向代理 |
-| Composer | - | PHP 依赖管理工具 |
-| PSR | PHP Standards Recommendation | PHP 标准推荐 |
-| FPM | FastCGI Process Manager | PHP 进程管理器 |
-| DNF | Dandified Yum | Rocky Linux / CentOS 包管理器 |
-| PECL | PHP Extension Community Library | PHP 扩展安装工具 |
+## 架构
 
-## 前端术语
+| 术语 | 解释 |
+|---|---|
+| 四件套 | 一个模块的四个文件：dto / repository / service / handler |
+| RouteSpec | 路由声明表：一条声明同时定义注册/权限/日志/公开 |
+| 路由元数据 | RouteSpec 注册时写入进程内表，authz/日志/OpenAPI 同源消费 |
+| 反射元数据驱动 | router.Bind 按方法签名反射注册路由的机制 |
+| ModuleSpec | 声明式 CRUD 基座：差异进声明字段与钩子 |
+| 逃生舱 | 写不进声明的复杂逻辑手写方法的合法通道 |
+| WireCheck | 启动期探测中间件接线完整性（缺失告警降级） |
+| fail-fast | 配置非法拒绝启动的设计原则 |
 
-| 术语 | 全称 | 说明 |
-|------|------|------|
-| Vue | - | 渐进式 JavaScript 框架 |
-| TypeScript | - | JavaScript 超集，类型安全 |
-| Vite | - | 前端构建工具 |
-| Pinia | - | Vue 3 官方状态管理库 |
-| ElementPlus | - | Vue 3 UI 组件库 |
-| Axios | - | HTTP 请求库 |
-| TailwindCSS | - | 原子化 CSS 框架 |
-| TinyMce | - | 富文本编辑器 |
-| ECharts | - | 数据可视化图表库 |
-| pnpm | - | 高性能 Node.js 包管理器 |
-| ESLint | - | JavaScript/TypeScript 代码检查工具 |
-| Prettier | - | 代码格式化工具 |
-| keep-alive | - | Vue 组件缓存机制 |
+## 数据
 
-## 业务术语
+| 术语 | 解释 |
+|---|---|
+| 软删除 | UPDATE del_flag=1；物理删除被钩子拦截 |
+| 审计盖章 | Create/Update 钩子自动补齐审计字段 |
+| 租户白名单 | 9 张含 tenant_id 的租户级表清单（hooks.tenantTables） |
+| 数据权限 | 行级过滤（全部/本部门及以下/本部门/仅本人） |
+| Scope | repository.Ctx 在 SQL 构建前注入的查询条件 |
+| WithTrans | 事务入口，回调 ctx 携带事务连接 |
+| WithPhysicalDelete | 显式放行物理删除的 ctx 开关 |
 
-| 术语 | 说明 |
-|------|------|
-| 软删除 | 通过 `is_delete` 字段标记删除，不物理删除 |
-| 租户隔离 | 通过 `tenant_id` 字段实现多租户数据隔离 |
-| 数据权限 | 基于角色的 data_scope 控制数据可见范围 |
-| access_token | 访问令牌，短期有效（默认 2 小时） |
-| refresh_token | 刷新令牌，长期有效（默认 7 天） |
-| 驼峰命名 | camelCase，如 `createTime` |
-| 下划线命名 | snake_case，如 `create_time` |
-| RBAC | 基于角色的访问控制：用户 → 角色 → 菜单/权限 |
-| 超级管理员 | uid=1 的用户，跳过所有权限校验 |
-| 租户管理员 | tenant_id=0 的用户，不受租户隔离限制 |
-| 声明式 CRUD | 通过属性配置定义行为，无需编写通用代码 |
-| 生命周期钩子 | beforeAdd/afterAdd 等，用于注入定制逻辑 |
+## 认证安全
 
-## 框架术语
+| 术语 | 解释 |
+|---|---|
+| 双令牌 | access_token（短）+ refresh_token（长） |
+| jti | 令牌唯一标识，黑名单与在线登记的键 |
+| 黑名单 | 缓存登记失效令牌，TTL 取剩余有效期 |
+| 通配码 | `*:*:*`，超管全通过 |
+| 受信代理 | api.proxyIps 列表内来源才信任转发头 |
 
-| 术语 | 说明 |
-|------|------|
-| BaseLogic | 业务逻辑基类，提供声明式 CRUD 能力 |
-| BaseTenantLogic | 租户逻辑基类，继承 BaseLogic，自动租户隔离 |
-| BaseController | 控制器基类，提供统一响应和通用 CRUD 方法 |
-| BaseModel | 模型基类，提供软删除和审计字段 |
-| Result | 统一响应类，构造标准 JSON 响应 |
-| ExceptionHandle | 异常处理类，统一捕获异常并返回 JSON |
-| AttributeService | 注解服务，通过反射读取控制器方法注解 |
-| DictService | 字典服务，提供字典项读取和缓存 |
-| ParamService | 参数服务，提供系统参数读取和缓存 |
-| PasswordService | 密码服务，bcrypt 双重加盐加密 |
-| JwtService | JWT 服务，签发/刷新/解析令牌 |
+## 文件
+
+| 术语 | 解释 |
+|---|---|
+| 两段式上传 | 先 temp 后转正；未保存不落正式目录 |
+| saveTransform | 写侧转正（temp → 模块目录） |
+| readTransform | 读侧补访问域名 |
+| 占位符契约 | 富文本正文存 [IMG_URL]/{相对路径} |
+| ExpandContentFields | 占位符还原的唯一出口 |
+
+## 前端
+
+| 术语 | 解释 |
+|---|---|
+| 动态路由 | 登录后按菜单 API 生成注入的路由表 |
+| 信封解包 | http 拦截器把统一响应拆成 data/错误 |
+| v-perm / v-perms | 按权限码移除元素的指令（任一/全部） |
+| 设计 token | 主题变量（颜色/间距），换主题不改业务样式 |
+
+## 相关
+
+- [1.1 项目介绍](/zh/introduction.html)
+- [4.1 整体架构概览](/zh/architecture/overview.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/middleware.md

@@ -1,120 +1,52 @@
 # F. 中间件执行顺序
 
-:::tip 概述
-本页展示请求在框架中的完整中间件执行流程，包括全局中间件和应用中间件的执行顺序，帮助开发者理解请求处理链路。
+:::tip 说明
+全局中间件链（顺序勿动）：trace → CORS → metrics → response → ratelimit → demo → JWT → tenant → authz → operation_log。每个请求按此顺序穿过。
 :::
 
-## 执行流程图
+## 执行表
 
-```text
-请求进入
-    │
-    ▼
-┌────────────────┐
-│ProxyMiddleware │  全局中间件（最先执行）
-│                │  从代理头提取真实客户端 IP
-└──────┬─────────┘
-       │
-       ▼
-┌──────────────┐
-│CorsMiddleware│  全局中间件
-│              │  处理 OPTIONS 预检 + 跨域响应头
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐    401
-│AuthMiddleware│──────────► 未认证（Token 缺失/无效/过期）
-│              │    403
-│ JWT认证      │──────────► 无权限
-│ 权限校验     │
-└──────┬───────┘
-       │ 注入 userInfo
-       ▼
-┌──────────────┐    403
-│TenantMiddleware│──────────► 租户异常（禁用/过期）
-│              │
-│ 租户上下文   │
-└──────┬───────┘
-       │ 注入 tenantId, tenantInfo
-       ▼
-┌──────────────┐    403
-│DemoMiddleware│──────────► 演示环境禁止写操作
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│ LogMiddleware│  记录操作日志（写操作始终记录）
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│ 控制器方法    │
-└──────────────┘
-```
+| # | 中间件 | 职责 | 拦截行为 | ctx 写入 |
+|---|---|---|---|---|
+| 1 | Trace | trace_id + 请求元信息 | 不拦截 | trace_id、IP、UA、方法、URL |
+| 2 | CORS | 跨域响应头 | OPTIONS 204 终止 | 无 |
+| 3 | Metrics | Prometheus 计数/耗时 | 不拦截 | 无 |
+| 4 | Response | 统一信封 + panic 恢复 | 错误时写信封终止 | 响应码/体记录 |
+| 5 | RateLimit | 固定窗口限流 | 超限拒绝 | 拒绝原因 |
+| 6 | Demo | 演示模式拒写 | 非 GET/HEAD/OPTIONS 且非公开路径拒绝 | 无 |
+| 7 | JWT | 令牌解析、身份注入 | 401 | 身份、jti/exp、角色权限 |
+| 8 | Tenant | 租户状态校验 | 禁用/过期拒绝 | 无（读身份） |
+| 9 | Authz | 功能权限校验 | 403 | 拒绝原因 |
+| 10 | OperationLog | 操作日志异步落库 | 不拦截 | 无（读响应记录） |
 
-## 中间件职责
+另有链外兜底：`gin.CustomRecovery`（静态资源等业务链之外的 panic）。
 
-| 中间件 | 类型 | 职责 | 配置 |
-|--------|------|------|------|
-| ProxyMiddleware | 全局 | 代理头解析，提取真实客户端 IP | .env → `[API]` PROXY_IPS |
-| CorsMiddleware | 全局 | 跨域处理 | config/cors.php |
-| AuthMiddleware | 路由级 | JWT 认证 + 权限校验 | config/middleware.php → auth_except |
-| TenantMiddleware | 路由级 | 租户上下文注入 | 内置排除列表 |
-| DemoMiddleware | 路由级 | 演示环境拦截 | .env → [APP] DEMO |
-| LogMiddleware | 路由级 | 操作日志记录 | config/middleware.php → log_except |
+## 顺序约束理由
 
-## 排除配置
+- trace 最先：后续一切日志依赖 trace_id
+- Response 在业务前：panic 恢复包住全部 handler；错误出口统一
+- ratelimit/demo 在身份前：防未认证高频攻击
+- JWT → tenant → authz 逐层依赖前置注入的身份
+- operation_log 链尾：须读到最终响应才采集
 
-```php
-// config/middleware.php
-return [
-    'auth_except' => [
-        'login',
-        'captcha',
-        'oauth2/token',
-        'oauth2/check/token',
-    ],
-    'log_except' => [
-        'login',
-        'logout',
-        'captcha',
-        'oauth2',
-    ],
-];
-```
+## 免登录判定（IsPublicRequest）
 
-## 注入内容
+两个来源汇合：
 
-| 中间件 | 注入字段 | 说明 |
-|--------|---------|------|
-| ProxyMiddleware | `$_SERVER['REMOTE_ADDR']` | 覆盖为真实客户端 IP |
-| AuthMiddleware | `$request->userInfo` | 用户信息（uid, username, type 等） |
-| TenantMiddleware | `$request->tenantId` | 租户 ID（0=超级管理员） |
-| TenantMiddleware | `$request->isSuperAdmin` | 是否超级管理员 |
-| TenantMiddleware | `$request->tenantInfo` | 租户信息对象 |
+| 来源 | 内容 |
+|---|---|
+| 基础设施白名单 | /api/health、/api.json、/swagger*、/metrics |
+| 路由元数据 | RouteSpec.Public=true（登录/验证码/令牌兑换） |
 
-## ProxyMiddleware 详解
+## 拒绝类请求的可观测差异
 
-当项目部署在 CDN / 负载均衡 / Nginx 反向代理后面时，PHP 的 `REMOTE_ADDR` 是代理服务器的 IP（通常是 `127.0.0.1`），真实客户端 IP 由代理通过 `X-Forwarded-For` / `X-Real-IP` 请求头传递。
+| 拒绝 | 操作日志 | metrics 归类 |
+|---|---|---|
+| 限流 / 权限 403 | 不记录 | denied |
+| 租户拒绝 | 不记录 | error |
+| 未认证 401 | 不记录 | —（JWT 层） |
 
-### 工作原理
+## 相关
 
-```text
-客户端(真实IP) → CDN/代理 → Nginx → PHP-FPM
-                  ↓ 设置头
-         X-Forwarded-For: 真实IP, 代理IP
-         X-Real-IP: 真实IP
-```
-
-1. 检查 `REMOTE_ADDR` 是否在受信代理列表（`.env` → `PROXY_IPS`）
-2. 如果是，从 `X-Real-IP` 或 `X-Forwarded-For` 头提取真实 IP
-3. 覆盖 `$_SERVER['REMOTE_ADDR']`，后续 `request()->ip()` 返回真实 IP
-
-### 配置
-
-```ini
-# .env [API] 段
-# 受信代理 IP（逗号分隔，支持 CIDR 网段）
-# 未配置时默认信任 127.0.0.1 和 ::1
-PROXY_IPS = 127.0.0.1,::1,101.226.0.0/15,180.101.0.0/16
-```
+- [4.2 请求处理链路](/zh/architecture/request-flow.html)
+- [5.17 链路追踪与指标](/zh/core/trace-metrics.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/module-spec.md

@@ -0,0 +1,72 @@
+# G. ModuleSpec 声明速查
+
+:::tip 说明
+`ModuleSpec[Item, LItem, DRes]` 全部声明字段速查。泛型三参数：行结构、列表元素（树形可不同）、详情结构。
+:::
+
+## 数据源与查询（applyFilters 固定顺序生效）
+
+| 字段 | 序 | 行为 |
+|---|---|---|
+| Model | 1 | 数据源工厂（必填），通常 `NewXxxRepo().Ctx(ctx)` |
+| LikeFields | 2 | 逐列 LIKE 请求同名字段，空串跳过 |
+| EqFields | 3 | 等值过滤（列名转 lowerCamel），零值跳过 |
+| KeywordFields | 4 | keyword 对多列 LIKE，括号包成单个 AND |
+| Filter | 5 | 复杂条件追加（勿重复前四项已覆盖条件） |
+| DataScope | 6 | 数据权限（ApplyDataScope 工厂），最后一步 |
+
+排序：请求 orderField 命中 `OrderableFields` 白名单时前端排序生效；否则 `OrderBy`（List 专属可用 `ListOrderBy`）。
+
+## 输出声明
+
+| 字段 | 行为 |
+|---|---|
+| IsTree + ParentOf | 树形输出（仅 List 建树；ParentOf 返回 0 表根） |
+| ChildSetter | 子级写入器（缺省反射写 Children 字段） |
+| SerializeMaps | 枚举 → 字典编码，读侧回填 {field}Text |
+| FileFields | 单文件：写侧转正、读侧补域名 |
+| MultiFileFields | 逗号分隔多文件 |
+| ContentFields | 富文本：写侧占位符化、读侧还原 |
+| FileSaveDir | 三类文件共用的转正子目录 |
+| FieldLabels | 唯一校验提示标签覆盖 |
+
+## 业务规则
+
+| 字段 | 行为 |
+|---|---|
+| UniqueFields | Add/Update 前逐条预检（并发以 uk 索引为准） |
+| ToData | req → 落库 map（不映射审计字段） |
+
+## 钩子（错误原样上抛；禁 HTTP/IO、禁 append）
+
+| 钩子 | 时机 |
+|---|---|
+| BeforeAdd / AfterAdd | 新增前后 |
+| BeforeUpdate / AfterUpdate | 修改前后 |
+| BeforeDelete / AfterDelete | 删除前后 |
+| BeforeBatchDelete / AfterBatchDelete | 批量删除前后 |
+| AfterPageList | 分页查询后 |
+| AfterDetail | 详情查询后 |
+
+## 标准方法签名
+
+```go
+spec.Page(ctx, req, pageNo, pageSize) (*Item, total, error)   // 返回切片 + 总数
+spec.List(ctx, req) ([]*LItem, error)
+spec.Detail(ctx, id, req) (*DRes, error)
+spec.Add(ctx, req) (int64, error)
+spec.Update(ctx, id, req) error
+spec.Delete(ctx, id) error
+spec.BatchDelete(ctx, ids) error
+```
+
+## 使用要点
+
+- 声明变量命名 `{模块}Spec`，包级 var
+- 手写方法可复用 `spec.applyFilters(ctx, spec.Model(ctx), req)`（导出场景）
+- 钩子内修改 data/元素可以，append 不行
+
+## 相关
+
+- [3.5 业务层开发（service）](/zh/guide/service.html)
+- [4.7 基座与公共体系](/zh/architecture/base-system.html)

EasyGoAdmin_Gin_EleVue/zh/appendix/stores.md

@@ -1,131 +1,36 @@
-# H. 前端 Store 速查
+# I. 前端 Store 速查
 
-:::tip 概述
-前端使用 Pinia 进行全局状态管理，核心 Store 定义在 `ui/src/store/modules/` 目录下。
+:::tip 说明
+Pinia 7 个 store 模块速查。storage 键统一在 `store/mutation-types.ts` 定义常量。
 :::
 
-## userStore
+## 模块清单
 
-**文件**：`store/modules/user.ts`
+| Store | 主要 state | 主要 getter/action |
+|---|---|---|
+| user | token、用户信息、权限集合 | getPermissions、setToken、GetInfo |
+| asyncRoute | 菜单树、动态路由表、注入标记 | generateRoutes、setDynamicAddedRoute、getIsDynamicAddedRoute |
+| tabsView | 标签页列表、当前页签 | 多页签增删切换（经 storage 持久化） |
+| designSetting | 主题配色、布局尺寸、组件大小 | 主题切换即时生效（持久化） |
+| projectSetting | 项目开关（水印/锁屏/面包屑等） | 设置项读写 |
+| lockscreen | 锁屏状态 | 锁定/解锁 |
+| ossConfig | 对象存储配置 | 直传场景配置读取 |
 
-### 状态
+## mutation-types（storage 键）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `token` | string | JWT Token |
-| `username` | string | 用户名 |
-| `avatar` | string | 头像 URL |
-| `permissions` | string[] | 权限列表 |
-| `info` | object | 用户信息 |
+| 常量 | 用途 |
+|---|---|
+| ACCESS_TOKEN | 登录令牌 |
+| FIRST_ROUTE | 首个落地路由 |
+| （其他） | 主题、标签页、锁屏等持久化键 |
 
-### Actions
+## 使用规约速记
 
-| Action | 说明 | 返回 |
-|--------|------|------|
-| `login(userInfo)` | 登录 | Promise |
-| `GetInfo()` | 获取用户信息 | Promise |
-| `logout()` | 登出 | Promise |
+- `useXxxStore()` 组件内获取；`useXxxStoreWidthOut()` 守卫等组件外场景
+- 权限集合只读（登录后装配）
+- 页面局部状态不进 store
+- 新增持久化键先在 mutation-types 登记
 
-### 使用示例
+## 相关
 
-```typescript
-import { useUserStore } from '@/store/modules/user';
-
-const userStore = useUserStore();
-
-// 登录
-await userStore.login({ username: 'admin', password: '123456' });
-
-// 获取用户信息
-const info = userStore.getUserInfo;
-const permissions = userStore.getPermissions;
-
-// 登出
-await userStore.logout();
-```
-
----
-
-## asyncRouteStore
-
-**文件**：`store/modules/asyncRoute.ts`
-
-### 状态
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `menus` | array | 菜单列表 |
-| `keepAliveComponents` | string[] | 缓存的组件名 |
-| `isDynamicAddedRoute` | boolean | 是否已添加动态路由 |
-
-### Actions
-
-| Action | 说明 |
-|--------|------|
-| `generateRoutes(userInfo)` | 从后端获取菜单并生成路由 |
-| `setDynamicAddedRoute(flag)` | 设置动态路由添加状态 |
-| `setKeepAliveComponents(components)` | 设置 keep-alive 组件列表 |
-
----
-
-## projectSettingStore
-
-**文件**：`store/modules/projectSetting.ts`
-
-| 字段 | 说明 |
-|------|------|
-| `navMode` | 导航模式（侧边/顶部） |
-| `navTheme` | 导航主题（暗色/亮色） |
-| `isShowMenuBar` | 是否显示菜单栏 |
-| `isCollapse` | 菜单是否折叠 |
-
----
-
-## ossConfigStore
-
-**文件**：`store/modules/ossConfig.ts`
-
-| 字段 | 说明 |
-|------|------|
-| `ossConfig` | 云存储配置 |
-
-路由守卫中初始化，用于文件上传。
-
----
-
-## designSettingStore
-
-**文件**：`store/modules/designSetting.ts`
-
-| 字段 | 说明 |
-|------|------|
-| `appTheme` | 主题色 |
-| `darkMode` | 是否暗色模式 |
-
----
-
-## tabsViewStore
-
-**文件**：`store/modules/tabsView.ts`
-
-| 字段 | 说明 |
-|------|------|
-| `tabsList` | 标签页列表 |
-
-| Action | 说明 |
-|--------|------|
-| `addTab(route)` | 添加标签 |
-| `removeTab(route)` | 关闭标签 |
-| `closeOtherTabs(route)` | 关闭其他标签 |
-| `closeAllTabs()` | 关闭所有标签 |
-
----
-
-## 在组件外使用
-
-```typescript
-// 在 setup 外使用 Store
-import { useUserStoreWidthOut } from '@/store/modules/user';
-
-const userStore = useUserStoreWidthOut();
-```
+- [9.6 状态管理（Pinia）](/zh/frontend/store.html)