签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -0,0 +1,195 @@
+# EasyGoAdmin Gin+ElementPlus 开发文档
+
+> EasyGoAdmin 企业级多租户后台管理基座 - Gin + GORM + Vue3 + ElementPlus。支持五种数据库一键切换、RBAC 按钮级权限、多租户数据隔离、声明式 CRUD 基座与代码生成器。本文档共 153 篇，按章节组织。
+
+## 1. 了解项目
+
+- [1.1 项目介绍](http://docs.gin.elevue.easygoadmin.vip/zh/introduction.html): EasyGoAdmin 是企业级多租户后台管理基座，后端基于 Gin + GORM，前端基于 Vue3 + ElementPlus，完全前后端分离架构。
+- [1.2 核心特性](http://docs.gin.elevue.easygoadmin.vip/zh/why.html): 本页展开介绍 EasyGoAdmin 的核心设计与能力清单。
+- [1.3 项目目录结构](http://docs.gin.elevue.easygoadmin.vip/zh/directory.html): 本页给出项目顶层与关键子目录的结构说明。
+- [1.4 新手入门指南](http://docs.gin.elevue.easygoadmin.vip/zh/course.html): 本页给出一条从"跑起来"到"独立开发模块"的最短学习路径。
+- [1.5 技术栈说明](http://docs.gin.elevue.easygoadmin.vip/zh/tech-stack.html): 本页列出前后端技术选型与版本基线。
+- [1.6 更新日志](http://docs.gin.elevue.easygoadmin.vip/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。
+
+## 2. 快速入门
+
+- [2.1 开发环境准备](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/environment.html): 本页列出本地开发所需的软件与版本基线。
+- [2.2 数据库初始化](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/database-init.html): 项目在 document/ 目录提供各数据库方言的初始化脚本。
+- [2.3 配置文件与环境变量](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/env-vars.html): 配置以 config/config.yaml 为基，任意键可被环境变量覆盖（12-Factor 风格）。
+- [2.4 后端服务启动](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/backend-start.html): 后端是单二进制服务，入口 cmd/api。
+- [2.5 前端服务启动](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/frontend-start.html): 前端为独立 Vite 工程（ui/），开发端口 8001，/api 请求代理到后端 8000。
+- [2.6 第一个接口调试](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/first-api.html): 本页用「获取验证码 → 登录 → 携带 Token 请求受保护接口」走一遍完整调用链，帮助你验证环境全通、理解统一响应格式。
+- [2.7 Docker 快速体验](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/docker.html): deploy/docker-compose.yaml 编排了应用、Nginx、MySQL、Redis 四个容器，一键拉起完整运行环境。
+- [2.8 常见问题 FAQ](http://docs.gin.elevue.easygoadmin.vip/zh/quickstart/faq.html): 本页汇总快速入门阶段的高频问题。
+
+## 3. 模块开发实战
+
+- [3.1 概述与目标](http://docs.gin.elevue.easygoadmin.vip/zh/guide/overview.html): 本章以项目内置的 example（案例演示，gin_example） 模块为例，从数据库建表到前端页面联调，完整演示开发全流程。
+- [3.2 数据库建表](http://docs.gin.elevue.easygoadmin.vip/zh/guide/database.html): 表是模块开发的起点。
+- [3.3 契约层开发（dto）](http://docs.gin.elevue.easygoadmin.vip/zh/guide/dto.html): dto 是模块的对外契约：json 标签即 API 字段名，binding/msg 标签给出校验规则与提示语，form 标签供 GET 参数绑定。
+- [3.4 数据访问层（repository）](http://docs.gin.elevue.easygoadmin.vip/zh/guide/repository.html): 仓储层做一件事：给 service 一个安全的数据库入口。
+- [3.5 业务层开发（service）](http://docs.gin.elevue.easygoadmin.vip/zh/guide/service.html): service 是业务逻辑的唯一去处。
+- [3.6 接口层开发（handler）](http://docs.gin.elevue.easygoadmin.vip/zh/guide/handler.html): handler 是极薄委托层：router.Bind 反射已完成参数解析与 binding 校验，本层只做一次调用转换。
+- [3.7 路由与元数据注册（RouteSpec）](http://docs.gin.elevue.easygoadmin.vip/zh/guide/route.html): 本项目的路由只有一处声明：router.go 内每个控制器的 RouteSpec 表。
+- [3.8 参数校验与错误上抛](http://docs.gin.elevue.easygoadmin.vip/zh/guide/validation.html): 校验在契约层用标签声明，错误在业务层用哨兵错误上抛——两头都不写手工 if。
+- [3.9 权限节点配置](http://docs.gin.elevue.easygoadmin.vip/zh/guide/permission.html): 接口侧的权限码在 RouteSpec 声明，但"谁能访问"由菜单-角色链路决定：菜单表登记权限节点，角色勾选授权，authz 中间件按元数据校验。
+- [3.10 前端联调指引](http://docs.gin.elevue.easygoadmin.vip/zh/guide/frontend-integration.html): 后端四件套就绪后，前端补两块：API 模块（ui/src/api）与页面（ui/src/views）。
+- [3.11 完整代码清单](http://docs.gin.elevue.easygoadmin.vip/zh/guide/code-list.html): 本页汇总 example 模块的全部文件与职责，作为手工开发的核对清单。
+- [3.12 常见问题与排错](http://docs.gin.elevue.easygoadmin.vip/zh/guide/faq.html): 本页汇总模块开发高频问题。
+
+## 4. 架构设计
+
+- [4.1 整体架构概览](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/overview.html): EasyGoAdmin 是前后端分离的多层架构：Vue3 单页应用通过统一信封与 Gin 后端交互，后端按"契约 → 接口 → 业务 → 数据"四件套分层，横切能力（认证、租户、日志、
+- [4.2 请求处理链路](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/request-flow.html): 一个典型 API 请求经过：浏览器 →（Nginx/Vite 代理）→ 中间件链 → 反射路由绑定 → handler → service → repository → 数据库 → 统一信封返回。
+- [4.3 后端分层架构](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/backend-layer.html): 后端按职责分为五层：契约（dto）、接口（handler）、业务（service）、数据（repository）、横切（middleware + hooks）。
+- [4.4 反射元数据驱动机制](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/bind-mechanism.html): 本项目最核心的机制：RouteSpec 表即路由定义。
+- [4.5 前端分层架构](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/frontend-layer.html): 前端按"视图 → 状态 → 接口 → 信封"分层：views 页面消费 store 与 api 模块，api 模块经 http 封装发请求，拦截器统一处理 Token、信封解包与错误提示。
+- [4.6 目录结构设计](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/directory-design.html): 目录即架构：internal 对外不可见、utility 无业务语义、一模块四文件同名成套。
+- [4.7 基座与公共体系](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/base-system.html): 项目有三个"基座"承担复用：repository.Base（数据访问红线入口）、ModuleSpec（声明式 CRUD）、dto 公共结构（分页/时间/空响应）。
+- [4.8 横切机制](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/cross-cutting.html): 横切关注点不在业务代码中重复出现——认证、租户、日志、审计、软删分别由中间件链与 GORM 全局钩子在固定位置统一执行。
+- [4.9 缓存架构设计](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/cache.html): 缓存层以 Redis 为主、进程内内存为降级：启动时探测 Redis，不可用自动切内存模式并告警，业务代码无感知。
+- [4.10 数据库设计](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/database-design.html): 数据库层有三个设计支点：多方言驱动注册表（一套代码五种数据库）、统一列约定（审计字段 + 软删 + 租户）、全局钩子（红线在 SQL 层执行）。
+- [4.11 安全架构设计](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/security.html): 安全能力分布在四个层面：传输层（CORS、受信代理）、认证层（JWT 双令牌、验证码、限流）、授权层（RBAC + 数据权限 + 租户隔离）、工程层（fail-fast 校验、演示模式、生产模式红线）。
+- [4.12 扩展性设计](http://docs.gin.elevue.easygoadmin.vip/zh/architecture/extensibility.html): 系统的扩展点都是显式声明的：钩子承接业务差异、生成器模板可自定义、任务自注册、驱动可注册、中间件能力可接线裁剪。
+
+## 5. 核心功能
+
+- [5.1 用户认证（JWT）](http://docs.gin.elevue.easygoadmin.vip/zh/core/jwt.html): 认证采用 JWT 双令牌：短时效 access_token 用于常规请求，长时效 refresh_token 用于兑换刷新。
+- [5.2 认证与授权流程](http://docs.gin.elevue.easygoadmin.vip/zh/core/auth-flow.html): 登录是项目里最完整的业务链路：验证码 → 定位用户 → 状态校验 → 密码比对 → 签发双令牌 → 登计日志与在线会话。
+- [5.3 验证码机制](http://docs.gin.elevue.easygoadmin.vip/zh/core/captcha.html): 图形验证码由 utility/captcha 生成 SVG/PNG dataURL，答案存缓存（TTL 300 秒）且一码一用。
+- [5.4 权限管理（RBAC）](http://docs.gin.elevue.easygoadmin.vip/zh/core/rbac.html): 经典三级模型：用户-角色-菜单（权限节点）。
+- [5.5 跨域配置（CORS）](http://docs.gin.elevue.easygoadmin.vip/zh/core/cors.html): CORS 中间件位于链路最前段（trace 之后），保证包括错误响应在内的所有响应都带跨域头——浏览器才能读到 401/403 的业务码。
+- [5.6 密码与加密服务](http://docs.gin.elevue.easygoadmin.vip/zh/core/password.html): 密码存储采用 外部 salt + bcrypt(password+salt)：salt 独立存放、bcrypt 负责哈希。
+- [5.7 接口限流（RateLimit）](http://docs.gin.elevue.easygoadmin.vip/zh/core/ratelimit.html): 限流采用固定窗口计数，位于响应包裹之后、JWT 之前——在身份解析前生效，防住未认证的高频攻击。
+- [5.8 演示模式](http://docs.gin.elevue.easygoadmin.vip/zh/core/demo-mode.html): 演示模式用于对外展示环境：写操作一律拒绝，读操作与登录类公开接口放行。
+- [5.9 多租户隔离](http://docs.gin.elevue.easygoadmin.vip/zh/core/tenant.html): 租户隔离是双侧执行的红线：写侧全局 Create 钩子补齐 tenant_id，读侧 repository Scope 追加租户条件。
+- [5.10 数据权限](http://docs.gin.elevue.easygoadmin.vip/zh/core/data-scope.html): 数据权限是行级过滤：按角色的数据范围档位，在查询链上追加部门/本人条件。
+- [5.11 字典模块](http://docs.gin.elevue.easygoadmin.vip/zh/core/dict.html): 字典承载系统内全部枚举取值的显示名（状态、类型、性别……）。
+- [5.12 系统配置管理](http://docs.gin.elevue.easygoadmin.vip/zh/core/config.html): 系统配置是运行在数据库里的键值对（gin_config + gin_config_item），供业务页面级别的开关与文案使用。
+- [5.13 系统参数管理](http://docs.gin.elevue.easygoadmin.vip/zh/core/param.html): 参数是扁平单表的键值存储（gin_param），适合存放彼此独立、无需分组的系统参数。
+- [5.14 操作日志](http://docs.gin.elevue.easygoadmin.vip/zh/core/operation-log.html): 操作日志由 RouteSpec 声明驱动、中间件链尾采集、异步落库——业务代码零参与。
+- [5.15 登录日志](http://docs.gin.elevue.easygoadmin.vip/zh/core/login-log.html): 登录/登出行为独立留痕（gin_login_log）：成功与失败都记录，失败含错误原因分类。
+- [5.16 异常与统一响应](http://docs.gin.elevue.easygoadmin.vip/zh/core/exception.html): 所有响应（成功、业务失败、校验失败、未认证、panic）都经 Response 中间件输出统一 JSON 信封，绝不出现 HTML 错误页。
+- [5.17 链路追踪与指标](http://docs.gin.elevue.easygoadmin.vip/zh/core/trace-metrics.html): 可观测性由两个轻量机制承担：trace 中间件为每个请求分配 trace_id 并回显响应头，串联全部日志；metrics 中间件按路由模板采集 Prometheus 指标。
+- [5.18 服务与缓存监控](http://docs.gin.elevue.easygoadmin.vip/zh/core/server-monitor.html): 内置三个监控视角：服务监控（主机资源，分平台实现）、缓存监控（Redis 状态与键空间）、在线用户（JWT 会话）。
+- [5.19 定时任务调度机制](http://docs.gin.elevue.easygoadmin.vip/zh/core/job-scheduler.html): 调度基于 robfig/cron：调度器基础设施在 service 的 job 模块，任务实现集中放在 internal/task 包，经 init 自注册、按任务记录的 url 字段数据驱动查找。
+
+## 6. 业务模块
+
+- [6.1 用户管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/user.html): 用户是组织权限体系的核心表（gin_user，租户级）。
+- [6.2 角色管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/role.html): 角色（gin_role，租户级）是权限与数据范围的载体：向上关联用户（gin_user_role），向下关联菜单权限节点（gin_role_menu）。
+- [6.3 菜单管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/menu.html): 菜单（gin_menu，平台级）一张表同时承担三件事：前端路由定义（path/component）、侧边栏展示（树形/图标/排序）、权限节点承载（permission 列）。
+- [6.4 部门管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/dept.html): 部门（gin_dept，租户级）是组织树（parent_id 自关联），同时是数据权限的锚点——用户挂部门、角色数据范围按部门收敛、"本部门及以下"档位依赖树形子孙计算。
+- [6.5 职级管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/level.html): 职级（gin_level，租户级）是组织人事的基础字典型模块：标准 CRUD + 启停状态 + 导入导出，适合作为理解"简单模块完整形态"的参照。
+- [6.6 岗位管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/position.html): 岗位（gin_position，租户级）与职级同形态：标准 CRUD + 启停。
+- [6.7 租户管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/tenant.html): 租户（gin_tenant，平台级表）管理 SaaS 侧的租户生命周期：开户、启停、有效期、租户管理员账号与成员视图。
+- [6.8 文章管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/article.html): 文章（gin_article，租户级）是内容管理的核心表，承载富文本正文与单图封面——完整示范 ModuleSpec 的内容字段（ContentFields）与文件字段（FileFields）组合。
+- [6.9 分类管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/category.html): 分类（gin_category，租户级）为内容提供归类维度：文章按分类组织，分类支持树形层级。
+- [6.10 公告管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/notice.html): 公告（gin_notice，租户级）承载站点通知/公告的发布管理：标准 CRUD + 上下架状态。
+- [6.11 友情链接管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/link.html): 友情链接（gin_link，租户级）管理外部站点互链：名称、URL、图标、排序。
+- [6.12 字典管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/dict.html): 字典管理页维护 gin_dict + gin_dict_item 两表：字典定义与字典项。
+- [6.13 参数管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/param.html): 参数（gin_param）是扁平键值表，管理独立系统参数（协议版本、联系方式、提示文案等）。
+- [6.14 配置管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/config.html): 配置管理维护 gin_config（分组）+ gin_config_item（配置项）的分组树，承载站点级与业务级运营配置。
+- [6.15 行政区划管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/city.html): 行政区划（gin_city）维护省市区三级数据，为地址选择、属地统计提供基础数据。
+- [6.16 定时任务管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/job.html): 任务管理页（gin_job + gin_job_log）管理 cron 任务的定义与执行：新建、启停、手动执行、执行日志。
+- [6.17 在线用户](http://docs.gin.elevue.easygoadmin.vip/zh/modules/online-user.html): 在线用户页展示当前活跃的 JWT 会话（缓存登记，不落库），支持查看明细与强制下线。
+- [6.18 服务监控](http://docs.gin.elevue.easygoadmin.vip/zh/modules/server-monitor.html): 服务监控页展示主机运行指标：CPU、内存、磁盘、goroutine 等。
+- [6.19 缓存监控](http://docs.gin.elevue.easygoadmin.vip/zh/modules/cache-monitor.html): 缓存监控页展示 Redis 运行状态：连接、内存、命中率、键空间规模。
+- [6.20 日志管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/logger.html): 日志管理涵盖两类审计表：操作日志（gin_operation_log，接口调用审计）与登录日志（gin_login_log，登录行为审计）。
+- [6.21 文件模板管理](http://docs.gin.elevue.easygoadmin.vip/zh/modules/file-template.html): 文件模板（gin_file_template）管理可复用的文件模板（导入模板、导出表头模板等）：登记模板元信息、提供按编码获取的入口，配套文件字段的上传转正。
+- [6.22 示例模块（example）](http://docs.gin.elevue.easygoadmin.vip/zh/modules/example.html): gin_example 是全项目的规约参考实现：标准 CRUD + 单图转正 + 字典回填 + 导入导出 + 状态更新，一个模块覆盖 ModuleSpec 常用能力组合。
+- [6.23 首页与个人中心](http://docs.gin.elevue.easygoadmin.vip/zh/modules/index.html): index 模块面向登录后的当前用户：用户信息、菜单下发、个人资料与密码维护。
+
+## 7. 文件处理
+
+- [7.1 文件上传全流程](http://docs.gin.elevue.easygoadmin.vip/zh/tools/upload.html): 上传采用两段式：先传临时目录（temp），表单提交保存时才转正到模块正式目录。
+- [7.2 上传配置详解](http://docs.gin.elevue.easygoadmin.vip/zh/tools/upload-config.html): 上传相关配置集中在 config.yaml 的 file 节。
+- [7.3 富文本处理](http://docs.gin.elevue.easygoadmin.vip/zh/tools/rich-text.html): 富文本持久化遵循占位符契约：正文内本站文件地址统一存 [IMG_URL]/{相对路径}，读侧唯一还原出口是 ExpandContentFields。
+- [7.4 数据导入导出](http://docs.gin.elevue.easygoadmin.vip/zh/tools/excel.html): Excel 能力基于 excelize 封装（utility/excel）：ReadSheet 读表（剥表头、跳空行）、WriteSheet 写表落盘返回文件。
+- [7.5 前端文件组件](http://docs.gin.elevue.easygoadmin.vip/zh/tools/file-components.html): 前端文件能力集中在 ui/src/components 的几个公共组件：Upload（上传）、Editor（富文本）、Cropper（裁剪）、importFile（导入）。
+- [7.6 数据库迁移工具](http://docs.gin.elevue.easygoadmin.vip/zh/tools/db-migrate.html): cmd/migrator 实现跨库整库迁移：源库内省 → 目标方言 DDL 生成 → 分批搬运 → 序列/自增修复。
+
+## 8. 接口规范与对接
+
+- [8.1 统一响应格式](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/response.html): 所有接口返回统一 JSON 信封。
+- [8.2 错误码对照表](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/error-code.html): 业务错误码定义在 utility/apperr，经 internal/consts 别名转出（internal 层只依赖 consts 一个入口）。
+- [8.3 分页查询规范](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/pagination.html): 分页契约三件套：请求内嵌 PageReq、响应为 PageData[T]、默认与上限有兜底。
+- [8.4 请求绑定与参数校验](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/binding.html): 请求绑定由反射路由层统一完成：写入顺序 query → body → path（后写覆盖），校验读 binding 标签、错误消息取 msg 标签。
+- [8.5 文件上传接口](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/upload.html): 上传接口执行两段式的第一段（落临时目录）：multipart 提交文件，返回临时访问 URL；该 URL 随业务表单提交，保存记录时由后端转正。
+- [8.6 字典数据接口](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/dict-api.html): 字典数据分两套入口：别名接口（/api/dictionary/*，登录即可）供业务侧读字典定义与项；字典项快捷接口（getDictItemList）供前端下拉取选项。
+- [8.7 Token 使用说明](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/token.html): 客户端持有 access_token + refresh_token 双令牌：请求携带 access，过期后用 refresh 兑换新令牌。
+- [8.8 API 接口总览](http://docs.gin.elevue.easygoadmin.vip/zh/api-spec/overview.html): 全部接口由 RouteSpec 声明派生，可经 OpenAPI 端点（/api.json）与 Swagger UI（/swagger）在线查看——文档与运行时元数据同源，永不漂移。
+
+## 9. 前端开发
+
+- [9.1 前端工程概述](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/overview.html): 前端为独立 Vite 工程（ui/）：Vue3 + TypeScript + ElementPlus + Pinia。
+- [9.2 目录结构详解](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/directory.html): 本页给出 ui/src 各目录的职责与放置规则。
+- [9.3 环境与构建配置](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/env-config.html): 环境变量经 ui/.env.development / .env.production 管理，键以 VITE_ 开头。
+- [9.4 HTTP 请求封装](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/http.html): utils/http/axios 是自研的 axios 封装层：请求拦截（前缀、Token）、响应拦截（信封解包、错误提示、401 处理）、取消重复请求。
+- [9.5 路由与动态菜单](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/router.html): 路由分两类：静态路由（constant，登录页/异常页等始终存在）与动态路由（登录后由菜单 API 生成注入）。
+- [9.6 状态管理（Pinia）](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/store.html): 全局状态集中在 7 个 Pinia 模块：用户身份、动态路由、标签页、设计设置、项目设置、锁屏、OSS 配置。
+- [9.7 权限控制](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/permission.html): 前端权限三层：路由层（菜单按角色过滤生成）、指令层（v-perm / v-perms 控制按钮）、逻辑层（usePermission 组合式函数供 v-if 使用）。
+- [9.8 登录流程](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/login.html): 登录页提供四种表单：账号密码、手机验证码、扫码登录、注册。
+- [9.9 表格与页面组件](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/table-components.html): 列表页的骨架组件：PageWrapper（页面容器）、BasicForm（查询/表单，components/Form）、BasicTable（数据表格，components/Table）。
+- [9.10 数据录入组件](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/form-components.html): 表单录入类公共组件：Select/BasicSelect（异步数据源下拉）、TableSelect（表格选择器）、Upload（上传）、Editor（富文本）、Cropper（裁剪）、
+- [9.11 数据展示组件](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/display-components.html): 展示类公共组件：CountTo（数字动画）、Qrcode（二维码）、Render（渲染器）、icon（图标）、Application/Websocket/Authority/CheckToken
+- [9.12 Excel 导入导出组件](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/excel-components.html): Excel 能力分前后端两半：后端 excelize 读写（7.4 数据导入导出），前端 Excel/importFile 组件承担交互与浏览器侧解析，downloadFile 工具负责落盘。
+- [9.13 新增页面开发步骤](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/new-page.html): 一个标准业务页面 = api 模块函数 + views 页面五件套 + 菜单配置。
+- [9.14 API 模块编写规范](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/api-module.html): api 模块是前端与后端契约的镜像：按业务域分组、一模块一文件、函数对应后端动作。
+- [9.15 样式与主题定制](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/style.html): 样式分三层：ElementPlus 主题变量覆盖、全局样式（styles/）、组件 scoped 样式。
+- [9.16 布局系统](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/layout.html): 布局在 ui/src/layout/：主框架 index.vue + parentLayout.vue（多级嵌套），components/ 内含侧边栏、顶栏、标签页、面包屑等区域组件。
+- [9.17 工具函数](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/utils.html): ui/src/utils 收敛通用能力：http 封装、存储、鉴权、校验、日期、下载、格式化、DOM、颜色等。
+- [9.18 Hooks 与枚举](http://docs.gin.elevue.easygoadmin.vip/zh/frontend/hooks-enums.html): hooks/ 按 core/event/setting/web 分组沉淀组合式逻辑；enums/ 定义前端常量枚举。
+
+## 10. 代码生成器
+
+- [10.1 概述与架构](http://docs.gin.elevue.easygoadmin.vip/zh/generator/overview.html): 代码生成器内省数据库表结构，一键产出后端四件套、前端页面与 API 模块，并完成菜单创建、字典初始化与路由声明块追加。
+- [10.2 CLI 命令行使用](http://docs.gin.elevue.easygoadmin.vip/zh/generator/cli.html): CLI 入口 cmd/gen，经 make 目标调用。
+- [10.3 Web 管理界面](http://docs.gin.elevue.easygoadmin.vip/zh/generator/web-ui.html): 生成器 Web 界面（tool/generator）提供可视化操作：浏览数据库表、预览产物代码、勾选生成。
+- [10.4 表结构解析与渲染引擎](http://docs.gin.elevue.easygoadmin.vip/zh/generator/code-engine.html): 生成引擎两段：内省（表结构 → 生成模型）与渲染（生成模型 + 模板 → 产物）。
+- [10.5 模板体系](http://docs.gin.elevue.easygoadmin.vip/zh/generator/templates.html): 模板在 templates/：后端四件套 tpl + 前端两套（ui 标准 / ui2 树形）。
+- [10.6 配置与覆盖策略](http://docs.gin.elevue.easygoadmin.vip/zh/generator/config.html): 生成器配置集中在 config.yaml 的 generator 节：总开关、菜单挂载位置、覆盖策略。
+- [10.7 实战案例](http://docs.gin.elevue.easygoadmin.vip/zh/generator/demo.html): 以 gin_example 为对象完整走一遍生成流程：预览 → 生成 → 重启 → 验证。
+- [10.8 常见问题](http://docs.gin.elevue.easygoadmin.vip/zh/generator/faq.html): 生成器问题多集中在"推断不符预期"与"覆盖策略"两类。
+
+## 11. 运维部署
+
+- [11.1 部署 Checklist](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/checklist.html): 生产上线前逐项核对。
+- [11.2 环境规划](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/env-plan.html): 推荐拓扑：Nginx（TLS + 静态 + 反代）→ 应用（:8000）→ MySQL / Redis（内网）。
+- [11.3 数据库初始化与迁移](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/db-migrate.html): 生产数据库两条路径：全新初始化导入种子脚本；存量搬迁用 migrator 跨库迁移。
+- [11.4 后端部署](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/backend.html): 后端是单二进制：make build 产出可执行文件，配合配置与环境变量运行。
+- [11.5 前端部署](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/frontend.html): 前端构建为纯静态产物（dist/），由 Nginx 直接服务。
+- [11.6 Docker 生产部署](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/docker.html): deploy/ 提供三位一体的容器化方案：多阶段 Dockerfile（精简镜像）、docker-compose.yaml（四服务编排）、nginx.conf（上传文件直供）。
+- [11.7 性能调优](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/performance.html): 调优顺序：先观测、再定位、后调参。
+- [11.8 安全加固清单](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/security.html): 安全是分层纵深：应用红线（prod 模式）→ 网络暴露面收敛 → 传输加密 → 数据与账号。
+- [11.9 备份与恢复](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/backup.html): 备份三件套：数据库（核心）、upload 目录（业务资产）、配置与 .env（密钥）。
+- [11.10 故障排查手册](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/troubleshooting.html): 排查总纲：先看启动日志与告警，再按层定位（网络 → 认证 → 业务 → 数据）。
+- [11.11 CI/CD 与质量门禁](http://docs.gin.elevue.easygoadmin.vip/zh/deploy/ci-cd.html): 质量门禁收敛为一条命令：make check（fmt-check + vet + test-short + check-config）。
+
+## 12. 规范标准
+
+- [12.1 API 响应规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/api-response.html): 所有接口一律返回统一 JSON 信封，对外码值只有 0 / 1 / 401 三值语义。
+- [12.2 分页查询规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/pagination.html): 列表查询一律用分页契约：请求内嵌 PageReq，响应为 PageData 五字段。
+- [12.3 数据访问铁律](http://docs.gin.elevue.easygoadmin.vip/zh/standards/data-access.html): 数据访问的四条红线：**禁止裸用 *gorm.DB、一切删除走软删除、Raw 受限使用、事务统一 WithTrans**。
+- [12.4 模块开发规约](http://docs.gin.elevue.easygoadmin.vip/zh/standards/module-code.html): 一个模块固定四个文件（dto / repository / service / handler），对外 JSON 契约（json 标签、字段名、路径、权限码、binding
+- [12.5 Git 提交规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/git.html): 提交信息采用约定式格式：类型(范围): 摘要。
+- [12.6 数据删除规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/deletion.html): 删除的默认形态是软删除；物理删除是受控例外。
+- [12.7 代码审查清单](http://docs.gin.elevue.easygoadmin.vip/zh/standards/code-review.html): 审查按清单走：安全红线 → 契约影响 → 分层纪律 → 规约符合度。
+- [12.8 后端编码规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/backend-code.html): 在数据访问铁律与模块规约之上，后端编码的通用风格约定：命名、注释、错误、并发、依赖方向。
+- [12.9 前端编码规范](http://docs.gin.elevue.easygoadmin.vip/zh/standards/frontend-code.html): 前端通用风格约定：分层隔离、命名一致、组件复用、类型渐进。
+
+## 附录
+
+- [A. 常见问题汇总](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/faq.html): 全项目高频问题的总入口，按主题分组并给出深入链接。
+- [B. 数据库表结构速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/database-tables.html): 25 张 gin_ 表。
+- [C. 配置项速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/config-reference.html): config/config.yaml 全部配置节速查。
+- [D. Utility 函数速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/functions.html): utility/ 13 个基础包的常用入口速查。
+- [E. API 接口速查表](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/api-cheatsheet.html): 按模块速查接口形态。
+- [F. 中间件执行顺序](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/middleware.html): 全局中间件链（顺序勿动）：trace → CORS → metrics → response → ratelimit → demo → JWT → tenant → authz →
+- [G. ModuleSpec 声明速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/module-spec.html): ModuleSpec[Item, LItem, DRes] 全部声明字段速查。
+- [H. 前端组件速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/components.html): ui/src/components 公共组件速查（28 个）。
+- [I. 前端 Store 速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/stores.html): Pinia 7 个 store 模块速查。
+- [J. 前端枚举速查](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/enums.html): ui/src/enums 枚举常量速查。
+- [K. 术语表](http://docs.gin.elevue.easygoadmin.vip/zh/appendix/glossary.html): 项目核心术语速查，按主题排列。
+- [L. 贡献指南](http://docs.gin.elevue.easygoadmin.vip/zh/other/contributing.html): 欢迎贡献代码、报告问题与完善文档。
+- [M. 免责声明](http://docs.gin.elevue.easygoadmin.vip/zh/other/declare.html): 使用本项目及其文档前请阅读以下声明。
@@ -0,0 +1,33 @@
+# EasyGoAdmin Gin+ElementPlus 开发文档
+User-agent: *
+Allow: /
+
+# 显式放行生成式引擎 / AI 爬虫（GEO）
+User-agent: GPTBot
+Allow: /
+
+User-agent: ChatGPT-User
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: Claude-Web
+Allow: /
+
+User-agent: anthropic-ai
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+User-agent: Google-Extended
+Allow: /
+
+User-agent: Bytespider
+Allow: /
+
+User-agent: bingbot
+Allow: /
+
+Sitemap: http://docs.gin.elevue.easygoadmin.vip/sitemap.xml