{"owner":"flipped-aurora","repo":"gin-vue-admin","hasSkills":true,"totalSkillsCount":5,"totalTokensCount":12608,"categories":["anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".cursor/rules/project_rules.md",".trae/rules/project_rules.md",".claude/rules/project_rules.md",".codex/rules/project_rules.md",".aone_copilot/rules/project_rules.md"],"skills":{".cursor/rules/project_rules.md":"---\ntool: cursor\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Cursor 规则适配层\n\n本文件只用于兼容 Cursor 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".trae/rules/project_rules.md":"---\ntool: trae\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Trae 规则适配层\n\n本文件只用于兼容 Trae 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".claude/rules/project_rules.md":"---\ntool: claude\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Claude 规则适配层\n\n本文件只用于兼容 Claude 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n- 代码读取约束以 `/AGENT.MD` 为准，其中包括：无论什么情况，都不要直接读取 `node_modules/` 中的代码\n",".codex/rules/project_rules.md":"---\ntool: codex\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Codex 规则适配层\n\n本文件只用于兼容 Codex 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".aone_copilot/rules/project_rules.md":"### 功能描述以及必要性描述\n\n---\nname: gin-vue-admin\ndescription: |\n  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。\n  \n  前端技术栈：\n  - Vue 3.5.7 + Composition API\n  - Vite 6.2.3 构建工具\n  - Pinia 2.2.2 状态管理\n  - Element Plus 2.10.2 UI组件库\n  - UnoCSS 66.4.2 原子化CSS框架\n  - Vue Router 4.4.3 路由管理\n  - Axios 1.8.2 HTTP客户端\n  - ECharts 5.5.1 数据可视化\n  - @vueuse/core Vue组合式API工具集\n  \n  后端技术栈：\n  - Go 1.23 + Gin 1.10.0 Web框架\n  - GORM 1.25.12 ORM框架\n  - Casbin 2.103.0 权限管理\n  - Viper 1.19.0 配置管理\n  - Zap 1.27.0 日志系统\n  - Redis 9.7.0 缓存\n  - JWT 5.2.2 认证授权\n  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库\n  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务\n  \n  核心特性：\n  - 完整的RBAC权限控制系统\n  - 代码自动生成功能\n  - 丰富的中间件支持\n  - 插件化架构设计\n  - Swagger API文档\n---\n\n#### **角色与目标**\n\n你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。\n\n你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n---\n\n### **🚀 重要提示：GVA Helper MCP 支持**\n\n**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**\n\n1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力\n\n2. **GVA Helper**: 通常会有一个名为 \"**GVA Helper**\" 的MCP助手，专门为GVA框架开发提供支持\n\n3. **开发流程**: \n   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**\n   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作\n   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范\n\n4. **优势**: 通过GVA Helper可以获得：\n   - 最新的GVA框架特性和最佳实践\n   - 符合项目规范的代码模板\n   - 避免常见的开发陷阱和错误\n   - 确保代码质量和一致性\n\n**请始终记住：GVA Helper → 获得支持 → 开始开发**\n\n---\n\n### **核心开发指令：绝不可违背的原则**\n\n\n## **项目结构说明**\n\n### **整体架构**\n\ngin-vue-admin 采用前后端分离架构：\n- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务\n- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用\n- **部署 (deploy/)**：Docker、Kubernetes 等部署配置\n\n### **后端目录结构 (server/)**\n\n```\nserver/\n├── api/                    # API控制器层\n│   └── v1/                # API版本控制\n│       ├── enter.go       # API组入口文件\n│       ├── system/        # 系统模块API\n│       └──example/       # 示例模块API\n├── config/                # 配置结构体定义\n├── core/                  # 核心启动文件\n├── docs/                  # Swagger文档\n├── global/                # 全局变量和模型\n├── initialize/            # 初始化模块\n├── middleware/            # 中间件\n├── model/                 # 数据模型层\n│   ├── system/           # 系统模块模型\n│   ├── example/          # 示例模块模型\n│   └── common/           # 通用模型\n├── plugin/               # 插件目录\n│   ├── announcement/     # 公告插件\n│   └── email/           # 邮件插件\n├── router/               # 路由层\n│   ├── enter.go         # 路由组入口\n│   ├── system/          # 系统路由\n│   └──example/         # 示例路由\n├── service/              # 服务层\n│   ├── enter.go         # 服务组入口\n│   ├── system/          # 系统服务\n│   └──  example/         # 示例服务\n├── source/               # 数据初始化\n├── utils/                # 工具包\n├── config.yaml          # 配置文件\n└── main.go              # 程序入口\n```\n\n### **前端目录结构 (web/)**\n\n```\nweb/\n├── public/               # 静态资源\n├── src/\n│   ├── api/             # API接口定义\n│   │   ├── user.js      # 用户相关API\n│   │   ├── menu.js      # 菜单相关API\n│   │   └── cattery/     # 业务模块API\n│   ├── assets/          # 资源文件\n│   │   ├── icons/       # 图标\n│   │   └── images/      # 图片\n│   ├── core/            # 核心配置\n│   ├── directive/       # 自定义指令\n│   ├── hooks/           # 组合式API钩子\n│   ├── pinia/           # 状态管理\n│   │   ├── index.js     # Pinia入口\n│   │   └── modules/     # 状态模块\n│   ├── plugin/          # 前端插件\n│   │   ├── announcement/ # 公告插件\n│   │   └── email/       # 邮件插件\n│   ├── router/          # 路由配置\n│   ├── style/           # 样式文件\n│   ├── utils/           # 工具函数\n│   ├── view/            # 页面组件\n│   │   ├── dashboard/   # 仪表盘\n│   │   ├── layout/      # 布局组件\n│   │   ├── login/       # 登录页\n│   │   ├── superAdmin/  # 超级管理员\n│   │   ├── systemTools/ # 系统工具\n│   │   └── cattery/     # 业务页面\n│   ├── App.vue          # 根组件\n│   └── main.js          # 程序入口\n├── package.json         # 依赖配置\n├── vite.config.js       # Vite配置\n└── uno.config.js        # UnoCSS配置\n```\n\n---\n\n#### 后端规则\n\n在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的分层架构**:\n    \n    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。\n        \n    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。\n        \n2. **`enter.go` 组管理模式**:\n    \n    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。\n        \n    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。\n        \n3. **详尽的 Swagger 注释 (API层强制要求)**:\n    \n    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。\n        \n4. **统一的响应与错误处理**:\n    \n    - Service 层函数遇到业务错误时，应返回 `error` 对象。\n        \n    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。\n        \n\n---\n\n### **各层级代码实现规范**\n\n#### **1. 模型层 (`model/`)**\n\n- **数据模型 (`model/xxx.go`)**:\n\n   - 用于定义与数据库表映射的 GORM 结构体。\n\n   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。\n\n   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`\n\n   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。\n\n   - **⚠️ 重要提醒：数据类型一致性**\n      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致\n      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型\n      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常\n      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致\n      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段\n      - **⚠️ 指针类型处理**：\n         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换\n         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址\n         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`\n\n- **请求模型 (`model/request/xxx.go`)**:\n    \n    - 用于定义接收前端请求参数的结构体（DTOs）。\n        \n    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。\n        \n    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。\n        \n\n#### **2. 服务层 (`service/`)**\n\n- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。\n    \n- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。\n    \n- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。\n\n- **⚠️ 数据类型处理注意事项**:\n   - 在进行数据模型转换时，**必须确保**字段类型的一致性\n   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型\n   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑\n\n\n#### **3. API层 (`api/`)**\n\n- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。\n    \n- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。\n    \n- **Swagger 示例 (必须遵循)**:\n    \n    Go\n    \n    ```\n    // CreateXxx 创建XXX\n    // @Tags     XxxModule\n    // @Summary  创建一个新的XXX\n    // @Security ApiKeyAuth\n    // @accept   application/json\n    // @Produce  application/json\n    // @Param    data body request.CreateXxxRequest true \"XXX的名称和描述\"\n    // @Success  200  {object} response.Response{msg=string} \"创建成功\"\n    // @Router   /xxx/createXxx [post]\n    func (a *XxxApi) CreateXxx(c *gin.Context) {\n        // ...\n    }\n    ```\n    \n\n#### **4. 路由层 (`router/`)**\n\n- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。\n    \n- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。\n    \n- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。\n\n#### **5. 初始化层 (`initialize/`)**\n\n- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。\n    \n- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。\n    \n- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。\n    \n- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。\n- viper.go: 加载插件配置文件\n-  api.go: 注册API到系统\n    \n\n#### **6. 插件入口 (`plugin.go`) \n\n- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。\n    \n- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。\n\n- **插件注册**: **必须**调用 ```\nfunc init() {\n\tinterfaces.Register(Plugin)\n}\n```\n方法，让插件自动注册到本体中\n    \n- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。\n    \n- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `\"/myPlugin\"`。\n\n### 模块间引用关系：\n- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`\n- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`\n- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`\n- 各模块通过enter.go文件组织和暴露功能，避免循环引用\n\n### 插件默认注册功能\n\n`plugin/register.go` 文件下用 `\t_ \"github.com/flipped-aurora/gin-vue-admin/server/plugin/插件\"\n` 的方式匿名引用用于激活插件本体的init\n\n### 代码组织示例：\n\n1. Service入口 (service/enter.go):\n```go\npackage service\n\ntype ServiceGroup struct {\n    XxxService\n    YyyService\n    // 其他服务...\n}\n\nvar ServiceGroupApp = new(ServiceGroup)\n```\n\n2. API入口 (api/enter.go):\n```go\npackage api\n\ntype ApiGroup struct {\n    XxxApi\n    YyyApi\n    // 其他API...\n}\n\nvar ApiGroupApp = new(ApiGroup)\n```\n\n3. Router入口 (router/enter.go):\n```go\npackage router\n\ntype RouterGroup struct {\n    XxxRouter\n    YyyRouter\n    // 其他路由...\n}\n\nvar RouterGroupApp = new(RouterGroup)\n```\n\n### Swagger注释规范：\n- @Tags: 接口所属的分组\n- @Summary: 接口功能简述\n- @Security: 安全认证方式（如需认证则添加）\n- @accept/@Produce: 请求/响应格式\n- @Param: 请求参数，包括名称、来源、类型、是否必须、描述\n- @Success: 成功响应，包括状态码、返回类型、描述\n- @Router: 接口路径和HTTP方法\n\nAPI函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。\n\n\n---\n\n### **开发工作流**\n\n1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。\n    \n2. **【第一步】模型设计 (奠定基础)**:\n    \n    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。\n        \n3. **【第二步】自下而上，分层实现**:\n    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！\n\n    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。\n        \n    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。\n        \n4. **【第三步】插件初始化与注册**:\n    \n    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。\n        \n5. **【第四步】提供完整代码**:\n    \n    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。\n\n\n---\n\n## **前端开发规范**\n\n### **角色与目标**\n\n你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。\n\n你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n### **核心开发指令：绝不可违背的原则**\n\n#### 前端规则\n\n在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的模块化架构**:\n   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**\n   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`\n\n2. **统一的API调用模式**:\n   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装\n   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求\n   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值\n\n3. **组件化开发原则**:\n   - **每一个**可复用的UI元素都**必须**封装为组件\n   - 组件**必须**遵循单一职责原则，功能明确\n   - **必须**为组件添加完整的props定义和事件说明\n\n4. **统一的状态管理**:\n   - 全局状态**必须**使用Pinia进行管理\n   - 状态模块**必须**按业务功能进行划分\n   - **严禁**在组件中直接修改全局状态，必须通过actions\n\n### **各层级代码实现规范**\n\n#### **1. API层 (`src/api/`)**\n\n- **职责**: 封装所有后端API调用，提供统一的接口服务\n- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`\n- **规范**:\n  ```javascript\n  import service from '@/utils/request'\n  \n  /**\n   * 获取用户列表\n   * @param {Object} data 查询参数\n   * @param {number} data.page 页码\n   * @param {number} data.pageSize 每页数量\n   * @returns {Promise} 用户列表数据\n   */\n  export const getUserList = (data) => {\n    return service({\n      url: '/user/getUserList',\n      method: 'post',\n      data: data\n    })\n  }\n  ```\n\n#### **2. 组件层 (`src/components/`)**\n\n- **职责**: 提供可复用的UI组件\n- **结构**: 按功能分类组织，每个组件一个文件夹\n- **规范**:\n  ```vue\n  <template>\n    <div class=\"gva-table\">\n      <!-- 组件内容 -->\n    </div>\n  </template>\n  \n  <script setup>\n  /**\n   * 通用表格组件\n   * @component GvaTable\n   * @description 提供统一的表格展示功能\n   */\n  \n  // Props定义\n  const props = defineProps({\n    data: {\n      type: Array,\n      required: true,\n      default: () => []\n    },\n    loading: {\n      type: Boolean,\n      default: false\n    }\n  })\n  \n  // 事件定义\n  const emit = defineEmits(['refresh', 'edit', 'delete'])\n  </script>\n  ```\n\n#### **3. 页面层 (`src/view/`)**\n\n- **职责**: 实现具体的业务页面\n- **结构**: 按业务模块组织，每个页面一个Vue文件\n- **规范**:\n  - **必须**使用Composition API\n  - **必须**进行响应式数据管理\n  - **必须**处理加载状态和错误状态\n  - **必须**遵循Element Plus组件规范\n  - **必须**优先使用UnoCSS原子化类名进行样式设计\n  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作\n  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染\n\n#### **4. 状态管理 (`src/pinia/`)**\n\n- **职责**: 管理全局状态和业务逻辑\n- **结构**: 按业务模块创建store文件\n- **规范**:\n  ```javascript\n  import { defineStore } from 'pinia'\n  import { ref, computed } from 'vue'\n  import { useStorage } from '@vueuse/core'\n  \n  export const useUserStore = defineStore('user', () => {\n    // 状态定义 - 使用 ref() 创建响应式状态\n    const userInfo = ref({\n      uuid: '',\n      nickName: '',\n      headerImg: '',\n      authority: {}\n    })\n    const token = useStorage('token', '')\n    \n    // 计算属性 - 使用 computed() 定义\n    const isLogin = computed(() => !!token.value)\n    \n    // 方法定义 - 直接定义函数作为 actions\n    const setUserInfo = (val) => {\n      userInfo.value = val\n    }\n    \n    const setToken = (val) => {\n      token.value = val\n    }\n    \n    const login = async (loginForm) => {\n      // 登录逻辑\n      try {\n        const res = await loginApi(loginForm)\n        if (res.code === 0) {\n          setUserInfo(res.data.user)\n          setToken(res.data.token)\n          return true\n        }\n        return false\n      } catch (error) {\n        console.error('Login error:', error)\n        return false\n      }\n    }\n    \n    const logout = async () => {\n      // 登出逻辑\n      token.value = ''\n      userInfo.value = {}\n    }\n    \n    // 返回所有需要暴露的状态和方法\n    return {\n      userInfo,\n      token,\n      isLogin,\n      setUserInfo,\n      setToken,\n      login,\n      logout\n    }\n  })\n  ```\n\n#### **5. 路由管理 (`src/router/`)**\n\n- **职责**: 管理页面路由和权限控制\n- **规范**:\n  - **必须**配置路由元信息\n  - **必须**实现权限验证\n  - **必须**支持动态路由\n\n### **前端插件开发规范**\n\n#### **插件目录结构**\n\n```\nsrc/plugin/[插件名]/\n├── api/                # 插件API接口\n│   └── [模块].js\n├── components/         # 插件组件（可选）\n│   └── [组件名].vue\n├── view/              # 插件页面\n│   └── [页面名].vue\n├── form/              # 插件表单（可选）\n│   └── [表单名].vue\n└── index.js           # 插件入口文件（可选）\n```\n\n#### **插件开发原则**\n\n1. **独立性**: 插件应该是自包含的，不依赖其他业务模块\n2. **可配置性**: 插件应该支持配置化，便于定制\n3. **可扩展性**: 插件应该预留扩展接口\n4. **一致性**: 插件UI风格应与主系统保持一致\n\n### **代码质量要求**\n\n1. **命名规范**:\n   - 文件名：kebab-case（短横线命名）\n   - 组件名：PascalCase（大驼峰）\n   - 变量名：camelCase（小驼峰）\n   - 常量名：UPPER_SNAKE_CASE（大写下划线）\n\n2. **注释规范**:\n   - **必须**为所有API函数添加JSDoc注释\n   - **必须**为复杂组件添加功能说明\n   - **必须**为关键业务逻辑添加行内注释\n\n3. **样式规范**:\n   - **优先**使用UnoCSS原子化类名\n   - **必须**遵循Element Plus设计规范\n   - **禁止**使用内联样式\n   - **必须**使用CSS变量进行主题定制\n\n4. **性能要求**:\n   - **必须**使用懒加载优化路由\n   - **必须**对大列表进行虚拟滚动优化\n   - **必须**合理使用缓存机制\n   - **必须**优化图片和资源加载\n\n---\n\n## **⚠️ 前端工具库使用规范（强制）**\n\n> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**\n\n`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：\n\n### **工具文件清单**\n\n#### `request.js` — HTTP 请求封装（核心）\n- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截\n- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**\n- 用法：`import service from '@/utils/request'`\n\n#### `date.js` — 日期格式化\n- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`\n- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串\n- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**\n- 用法：`import { formatTimeToStr } from '@/utils/date'`\n\n#### `format.js` — 数据展示格式化（综合工具）\n- `formatBoolean(bool)` — 将布尔值转为 \"是\"/\"否\" 中文展示\n- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串\n- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label\n- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找\n- `getDictFunc(type)` — 异步获取指定类型的字典数据\n- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀\n- `onDownloadFile(url)` — 触发文件下载\n- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）\n- `CreateUUID()` — 生成 UUID v4 字符串\n- `getBaseUrl()` — 获取当前环境的 API BaseURL\n- **以上所有格式化场景优先使用此文件中的工具函数**\n- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`\n\n#### `dictionary.js` — 字典数据获取\n- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求\n- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**\n- 用法：`import { getDict } from '@/utils/dictionary'`\n\n#### `stringFun.js` — 字符串处理\n- `toUpperCase(str)` — 首字母转大写\n- `toLowerCase(str)` — 首字母转小写\n- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`\n- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`\n- **进行命名格式转换时必须使用此工具，禁止使用正则手写**\n- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`\n\n#### `params.js` — 系统参数获取\n- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存\n- **获取系统配置参数时，优先使用此工具**\n- 用法：`import { getParams } from '@/utils/params'`\n\n#### `bus.js` — 全局事件总线\n- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信\n- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**\n- 用法：`import { emitter } from '@/utils/bus'`\n\n#### `closeThisPage.js` — 关闭当前标签页\n- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）\n- **在需要程序化关闭当前页面时，必须使用此工具**\n- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`\n\n#### `downloadImg.js` — 图片下载\n- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域\n- **需要下载图片时，优先使用此工具**\n- 用法：`import { downloadImage } from '@/utils/downloadImg'`\n\n#### `image.js` — 图片压缩\n- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小\n- **上传图片前需要做压缩处理时，使用此工具**\n- 用法：`import ImageCompress from '@/utils/image'`\n\n#### `event.js` — DOM 事件监听管理\n- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听\n- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听\n- **手动操作 DOM 事件时，使用此工具以确保安全性**\n- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`\n\n#### `env.js` — 环境判断\n- `isDev` — 是否为开发环境（Boolean）\n- `isProd` — 是否为生产环境（Boolean）\n- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**\n- 用法：`import { isDev, isProd } from '@/utils/env'`\n\n#### `doc.js` — 外部文档跳转\n- `toDoc(url)` — 在新标签页打开指定 URL\n- 用法：`import { toDoc } from '@/utils/doc'`\n\n#### `fmtRouterTitle.js` — 路由标题格式化\n- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）\n- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`\n\n#### `page.js` — 页面标题生成\n- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）\n- 用法：`import getPageTitle from '@/utils/page'`\n\n#### `asyncRouter.js` — 异步路由处理\n- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录\n- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**\n- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`\n\n#### `btnAuth.js` — 按钮权限\n- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示\n- **实现按钮级别权限控制时，必须使用此 Hook**\n- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`\n\n### **使用强制要求**\n\n| 场景 | 必须使用的工具 |\n|------|----------------|\n| 发送 HTTP 请求 | `@/utils/request` |\n| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |\n| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |\n| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |\n| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |\n| 驼峰/下划线命名转换 | `@/utils/stringFun` |\n| 获取系统参数 | `@/utils/params` 中的 `getParams` |\n| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |\n| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |\n| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |\n| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |\n| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |\n\n---\n\n## **前后端协作规范**\n\n### **接口协作规范**\n\n1. **接口文档**:\n   - 后端**必须**提供完整的Swagger API文档\n   - 前端**必须**基于Swagger文档进行接口调用\n   - 接口变更**必须**提前通知并更新文档\n\n2. **数据格式**:\n   - **统一**使用JSON格式进行数据交换\n   - **统一**响应格式：`{code, data, msg}`\n   - **统一**分页格式：`{page, pageSize, total, list}`\n   - **统一**时间格式：ISO 8601标准\n   - **⚠️ 数据类型一致性**：\n      - 前后端对于同一字段**必须**使用相同的数据类型\n      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致\n      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段\n      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型\n      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值\n\n3. **错误处理**:\n   - 后端**必须**返回标准化的错误码和错误信息\n   - 前端**必须**统一处理HTTP状态码和业务错误码\n   - **必须**提供用户友好的错误提示\n\n### **开发流程规范**\n\n1. **需求分析阶段**:\n   - 确定功能需求和接口设计\n   - 定义数据模型和业务流程\n   - 制定前后端开发计划\n\n2. **开发阶段**:\n   - 后端优先开发API接口\n   - 前端基于Mock数据进行并行开发\n   - 定期进行接口联调测试\n\n3. **测试阶段**:\n   - 单元测试：前后端各自负责\n   - 集成测试：前后端协作完成\n   - 用户验收测试：产品团队主导\n\n### **版本管理规范**\n\n1. **分支策略**:\n   - `main`：生产环境分支\n   - `develop`：开发环境分支\n   - `feature/*`：功能开发分支\n   - `hotfix/*`：紧急修复分支\n\n2. **提交规范**:\n   - 使用语义化提交信息\n   - 格式：`type(scope): description`\n   - 类型：feat, fix, docs, style, refactor, test, chore\n\n---\n\n## **插件开发完整规范**\n\n### **后端插件结构**\n\n```\nserver/plugin/[插件名]/\n├── api/                # API控制器\n│   ├── enter.go       # API组入口\n│   └── [模块].go      # 具体API实现\n├── config/            # 插件配置\n│   └── config.go\n├── initialize/        # 初始化模块\n│   ├── api.go        # API注册\n│   ├── gorm.go       # 数据库初始化\n│   ├── menu.go       # 菜单初始化\n│   ├── router.go     # 路由初始化\n│   └── viper.go      # 配置初始化\n├── model/             # 数据模型\n│   ├── [模型].go     # 数据库模型\n│   └── request/      # 请求模型\n├── router/            # 路由定义\n│   ├── enter.go      # 路由组入口\n│   └── [模块].go     # 具体路由\n├── service/           # 业务服务\n│   ├── enter.go      # 服务组入口\n│   └── [模块].go     # 具体服务\n└── plugin.go          # 插件入口\n```\n\n### **前端插件结构**\n\n```\nweb/src/plugin/[插件名]/\n├── api/               # API接口\n│   └── [模块].js\n├── components/        # 插件组件\n│   └── [组件].vue\n├── view/             # 插件页面\n│   └── [页面].vue\n├── form/             # 表单组件\n│   └── [表单].vue\n└── config.js         # 插件配置\n```\n\n### **插件开发工作流**\n\n1. **【第一步】需求分析**:\n   - 明确插件功能和业务需求\n   - 设计数据模型和接口规范\n   - 规划前端页面和交互流程\n\n2. **【第二步】后端开发**:\n   - 创建数据模型和请求模型\n   - 实现服务层业务逻辑\n   - 开发API控制器和路由\n   - 编写初始化和配置代码\n\n3. **【第三步】前端开发**:\n   - 创建API接口封装\n   - 开发页面组件和表单\n   - 实现业务逻辑和状态管理\n   - 集成到主系统菜单\n\n4. **【第四步】测试集成**:\n   - 单元测试和集成测试\n   - 前后端联调测试\n   - 用户体验测试\n   - 性能和安全测试\n\n### **插件质量标准**\n\n1. **功能完整性**: 插件功能完整，满足业务需求\n2. **代码质量**: 代码规范，注释完整，易于维护\n3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误\n4. **性能表现**: 响应速度快，资源占用合理\n5. **用户体验**: 界面友好，操作流畅，错误处理完善\n6. **兼容性**: 与主系统兼容，不影响其他功能\n7. **安全性**: 数据安全，权限控制，防止安全漏洞\n\n---\n\n### **建议和方案**\n\n基于以上规范，建议AI在开发gin-vue-admin项目时：\n\n1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织\n2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格\n3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性\n4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理\n5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强\n6. **重视安全性**：实现完善的权限控制和数据验证机制"},"files":{".cursor/rules/project_rules.md":"---\ntool: cursor\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Cursor 规则适配层\n\n本文件只用于兼容 Cursor 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".trae/rules/project_rules.md":"---\ntool: trae\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Trae 规则适配层\n\n本文件只用于兼容 Trae 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".claude/rules/project_rules.md":"---\ntool: claude\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Claude 规则适配层\n\n本文件只用于兼容 Claude 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n- 代码读取约束以 `/AGENT.MD` 为准，其中包括：无论什么情况，都不要直接读取 `node_modules/` 中的代码\n",".codex/rules/project_rules.md":"---\ntool: codex\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Codex 规则适配层\n\n本文件只用于兼容 Codex 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n",".aone_copilot/rules/project_rules.md":"### 功能描述以及必要性描述\n\n---\nname: gin-vue-admin\ndescription: |\n  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。\n  \n  前端技术栈：\n  - Vue 3.5.7 + Composition API\n  - Vite 6.2.3 构建工具\n  - Pinia 2.2.2 状态管理\n  - Element Plus 2.10.2 UI组件库\n  - UnoCSS 66.4.2 原子化CSS框架\n  - Vue Router 4.4.3 路由管理\n  - Axios 1.8.2 HTTP客户端\n  - ECharts 5.5.1 数据可视化\n  - @vueuse/core Vue组合式API工具集\n  \n  后端技术栈：\n  - Go 1.23 + Gin 1.10.0 Web框架\n  - GORM 1.25.12 ORM框架\n  - Casbin 2.103.0 权限管理\n  - Viper 1.19.0 配置管理\n  - Zap 1.27.0 日志系统\n  - Redis 9.7.0 缓存\n  - JWT 5.2.2 认证授权\n  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库\n  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务\n  \n  核心特性：\n  - 完整的RBAC权限控制系统\n  - 代码自动生成功能\n  - 丰富的中间件支持\n  - 插件化架构设计\n  - Swagger API文档\n---\n\n#### **角色与目标**\n\n你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。\n\n你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n---\n\n### **🚀 重要提示：GVA Helper MCP 支持**\n\n**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**\n\n1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力\n\n2. **GVA Helper**: 通常会有一个名为 \"**GVA Helper**\" 的MCP助手，专门为GVA框架开发提供支持\n\n3. **开发流程**: \n   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**\n   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作\n   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范\n\n4. **优势**: 通过GVA Helper可以获得：\n   - 最新的GVA框架特性和最佳实践\n   - 符合项目规范的代码模板\n   - 避免常见的开发陷阱和错误\n   - 确保代码质量和一致性\n\n**请始终记住：GVA Helper → 获得支持 → 开始开发**\n\n---\n\n### **核心开发指令：绝不可违背的原则**\n\n\n## **项目结构说明**\n\n### **整体架构**\n\ngin-vue-admin 采用前后端分离架构：\n- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务\n- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用\n- **部署 (deploy/)**：Docker、Kubernetes 等部署配置\n\n### **后端目录结构 (server/)**\n\n```\nserver/\n├── api/                    # API控制器层\n│   └── v1/                # API版本控制\n│       ├── enter.go       # API组入口文件\n│       ├── system/        # 系统模块API\n│       └──example/       # 示例模块API\n├── config/                # 配置结构体定义\n├── core/                  # 核心启动文件\n├── docs/                  # Swagger文档\n├── global/                # 全局变量和模型\n├── initialize/            # 初始化模块\n├── middleware/            # 中间件\n├── model/                 # 数据模型层\n│   ├── system/           # 系统模块模型\n│   ├── example/          # 示例模块模型\n│   └── common/           # 通用模型\n├── plugin/               # 插件目录\n│   ├── announcement/     # 公告插件\n│   └── email/           # 邮件插件\n├── router/               # 路由层\n│   ├── enter.go         # 路由组入口\n│   ├── system/          # 系统路由\n│   └──example/         # 示例路由\n├── service/              # 服务层\n│   ├── enter.go         # 服务组入口\n│   ├── system/          # 系统服务\n│   └──  example/         # 示例服务\n├── source/               # 数据初始化\n├── utils/                # 工具包\n├── config.yaml          # 配置文件\n└── main.go              # 程序入口\n```\n\n### **前端目录结构 (web/)**\n\n```\nweb/\n├── public/               # 静态资源\n├── src/\n│   ├── api/             # API接口定义\n│   │   ├── user.js      # 用户相关API\n│   │   ├── menu.js      # 菜单相关API\n│   │   └── cattery/     # 业务模块API\n│   ├── assets/          # 资源文件\n│   │   ├── icons/       # 图标\n│   │   └── images/      # 图片\n│   ├── core/            # 核心配置\n│   ├── directive/       # 自定义指令\n│   ├── hooks/           # 组合式API钩子\n│   ├── pinia/           # 状态管理\n│   │   ├── index.js     # Pinia入口\n│   │   └── modules/     # 状态模块\n│   ├── plugin/          # 前端插件\n│   │   ├── announcement/ # 公告插件\n│   │   └── email/       # 邮件插件\n│   ├── router/          # 路由配置\n│   ├── style/           # 样式文件\n│   ├── utils/           # 工具函数\n│   ├── view/            # 页面组件\n│   │   ├── dashboard/   # 仪表盘\n│   │   ├── layout/      # 布局组件\n│   │   ├── login/       # 登录页\n│   │   ├── superAdmin/  # 超级管理员\n│   │   ├── systemTools/ # 系统工具\n│   │   └── cattery/     # 业务页面\n│   ├── App.vue          # 根组件\n│   └── main.js          # 程序入口\n├── package.json         # 依赖配置\n├── vite.config.js       # Vite配置\n└── uno.config.js        # UnoCSS配置\n```\n\n---\n\n#### 后端规则\n\n在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的分层架构**:\n    \n    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。\n        \n    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。\n        \n2. **`enter.go` 组管理模式**:\n    \n    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。\n        \n    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。\n        \n3. **详尽的 Swagger 注释 (API层强制要求)**:\n    \n    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。\n        \n4. **统一的响应与错误处理**:\n    \n    - Service 层函数遇到业务错误时，应返回 `error` 对象。\n        \n    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。\n        \n\n---\n\n### **各层级代码实现规范**\n\n#### **1. 模型层 (`model/`)**\n\n- **数据模型 (`model/xxx.go`)**:\n\n   - 用于定义与数据库表映射的 GORM 结构体。\n\n   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。\n\n   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`\n\n   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。\n\n   - **⚠️ 重要提醒：数据类型一致性**\n      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致\n      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型\n      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常\n      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致\n      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段\n      - **⚠️ 指针类型处理**：\n         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换\n         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址\n         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`\n\n- **请求模型 (`model/request/xxx.go`)**:\n    \n    - 用于定义接收前端请求参数的结构体（DTOs）。\n        \n    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。\n        \n    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。\n        \n\n#### **2. 服务层 (`service/`)**\n\n- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。\n    \n- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。\n    \n- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。\n\n- **⚠️ 数据类型处理注意事项**:\n   - 在进行数据模型转换时，**必须确保**字段类型的一致性\n   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型\n   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑\n\n\n#### **3. API层 (`api/`)**\n\n- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。\n    \n- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。\n    \n- **Swagger 示例 (必须遵循)**:\n    \n    Go\n    \n    ```\n    // CreateXxx 创建XXX\n    // @Tags     XxxModule\n    // @Summary  创建一个新的XXX\n    // @Security ApiKeyAuth\n    // @accept   application/json\n    // @Produce  application/json\n    // @Param    data body request.CreateXxxRequest true \"XXX的名称和描述\"\n    // @Success  200  {object} response.Response{msg=string} \"创建成功\"\n    // @Router   /xxx/createXxx [post]\n    func (a *XxxApi) CreateXxx(c *gin.Context) {\n        // ...\n    }\n    ```\n    \n\n#### **4. 路由层 (`router/`)**\n\n- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。\n    \n- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。\n    \n- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。\n\n#### **5. 初始化层 (`initialize/`)**\n\n- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。\n    \n- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。\n    \n- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。\n    \n- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。\n- viper.go: 加载插件配置文件\n-  api.go: 注册API到系统\n    \n\n#### **6. 插件入口 (`plugin.go`) \n\n- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。\n    \n- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。\n\n- **插件注册**: **必须**调用 ```\nfunc init() {\n\tinterfaces.Register(Plugin)\n}\n```\n方法，让插件自动注册到本体中\n    \n- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。\n    \n- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `\"/myPlugin\"`。\n\n### 模块间引用关系：\n- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`\n- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`\n- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`\n- 各模块通过enter.go文件组织和暴露功能，避免循环引用\n\n### 插件默认注册功能\n\n`plugin/register.go` 文件下用 `\t_ \"github.com/flipped-aurora/gin-vue-admin/server/plugin/插件\"\n` 的方式匿名引用用于激活插件本体的init\n\n### 代码组织示例：\n\n1. Service入口 (service/enter.go):\n```go\npackage service\n\ntype ServiceGroup struct {\n    XxxService\n    YyyService\n    // 其他服务...\n}\n\nvar ServiceGroupApp = new(ServiceGroup)\n```\n\n2. API入口 (api/enter.go):\n```go\npackage api\n\ntype ApiGroup struct {\n    XxxApi\n    YyyApi\n    // 其他API...\n}\n\nvar ApiGroupApp = new(ApiGroup)\n```\n\n3. Router入口 (router/enter.go):\n```go\npackage router\n\ntype RouterGroup struct {\n    XxxRouter\n    YyyRouter\n    // 其他路由...\n}\n\nvar RouterGroupApp = new(RouterGroup)\n```\n\n### Swagger注释规范：\n- @Tags: 接口所属的分组\n- @Summary: 接口功能简述\n- @Security: 安全认证方式（如需认证则添加）\n- @accept/@Produce: 请求/响应格式\n- @Param: 请求参数，包括名称、来源、类型、是否必须、描述\n- @Success: 成功响应，包括状态码、返回类型、描述\n- @Router: 接口路径和HTTP方法\n\nAPI函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。\n\n\n---\n\n### **开发工作流**\n\n1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。\n    \n2. **【第一步】模型设计 (奠定基础)**:\n    \n    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。\n        \n3. **【第二步】自下而上，分层实现**:\n    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！\n\n    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。\n        \n    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。\n        \n4. **【第三步】插件初始化与注册**:\n    \n    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。\n        \n5. **【第四步】提供完整代码**:\n    \n    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。\n\n\n---\n\n## **前端开发规范**\n\n### **角色与目标**\n\n你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。\n\n你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n### **核心开发指令：绝不可违背的原则**\n\n#### 前端规则\n\n在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的模块化架构**:\n   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**\n   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`\n\n2. **统一的API调用模式**:\n   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装\n   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求\n   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值\n\n3. **组件化开发原则**:\n   - **每一个**可复用的UI元素都**必须**封装为组件\n   - 组件**必须**遵循单一职责原则，功能明确\n   - **必须**为组件添加完整的props定义和事件说明\n\n4. **统一的状态管理**:\n   - 全局状态**必须**使用Pinia进行管理\n   - 状态模块**必须**按业务功能进行划分\n   - **严禁**在组件中直接修改全局状态，必须通过actions\n\n### **各层级代码实现规范**\n\n#### **1. API层 (`src/api/`)**\n\n- **职责**: 封装所有后端API调用，提供统一的接口服务\n- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`\n- **规范**:\n  ```javascript\n  import service from '@/utils/request'\n  \n  /**\n   * 获取用户列表\n   * @param {Object} data 查询参数\n   * @param {number} data.page 页码\n   * @param {number} data.pageSize 每页数量\n   * @returns {Promise} 用户列表数据\n   */\n  export const getUserList = (data) => {\n    return service({\n      url: '/user/getUserList',\n      method: 'post',\n      data: data\n    })\n  }\n  ```\n\n#### **2. 组件层 (`src/components/`)**\n\n- **职责**: 提供可复用的UI组件\n- **结构**: 按功能分类组织，每个组件一个文件夹\n- **规范**:\n  ```vue\n  <template>\n    <div class=\"gva-table\">\n      <!-- 组件内容 -->\n    </div>\n  </template>\n  \n  <script setup>\n  /**\n   * 通用表格组件\n   * @component GvaTable\n   * @description 提供统一的表格展示功能\n   */\n  \n  // Props定义\n  const props = defineProps({\n    data: {\n      type: Array,\n      required: true,\n      default: () => []\n    },\n    loading: {\n      type: Boolean,\n      default: false\n    }\n  })\n  \n  // 事件定义\n  const emit = defineEmits(['refresh', 'edit', 'delete'])\n  </script>\n  ```\n\n#### **3. 页面层 (`src/view/`)**\n\n- **职责**: 实现具体的业务页面\n- **结构**: 按业务模块组织，每个页面一个Vue文件\n- **规范**:\n  - **必须**使用Composition API\n  - **必须**进行响应式数据管理\n  - **必须**处理加载状态和错误状态\n  - **必须**遵循Element Plus组件规范\n  - **必须**优先使用UnoCSS原子化类名进行样式设计\n  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作\n  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染\n\n#### **4. 状态管理 (`src/pinia/`)**\n\n- **职责**: 管理全局状态和业务逻辑\n- **结构**: 按业务模块创建store文件\n- **规范**:\n  ```javascript\n  import { defineStore } from 'pinia'\n  import { ref, computed } from 'vue'\n  import { useStorage } from '@vueuse/core'\n  \n  export const useUserStore = defineStore('user', () => {\n    // 状态定义 - 使用 ref() 创建响应式状态\n    const userInfo = ref({\n      uuid: '',\n      nickName: '',\n      headerImg: '',\n      authority: {}\n    })\n    const token = useStorage('token', '')\n    \n    // 计算属性 - 使用 computed() 定义\n    const isLogin = computed(() => !!token.value)\n    \n    // 方法定义 - 直接定义函数作为 actions\n    const setUserInfo = (val) => {\n      userInfo.value = val\n    }\n    \n    const setToken = (val) => {\n      token.value = val\n    }\n    \n    const login = async (loginForm) => {\n      // 登录逻辑\n      try {\n        const res = await loginApi(loginForm)\n        if (res.code === 0) {\n          setUserInfo(res.data.user)\n          setToken(res.data.token)\n          return true\n        }\n        return false\n      } catch (error) {\n        console.error('Login error:', error)\n        return false\n      }\n    }\n    \n    const logout = async () => {\n      // 登出逻辑\n      token.value = ''\n      userInfo.value = {}\n    }\n    \n    // 返回所有需要暴露的状态和方法\n    return {\n      userInfo,\n      token,\n      isLogin,\n      setUserInfo,\n      setToken,\n      login,\n      logout\n    }\n  })\n  ```\n\n#### **5. 路由管理 (`src/router/`)**\n\n- **职责**: 管理页面路由和权限控制\n- **规范**:\n  - **必须**配置路由元信息\n  - **必须**实现权限验证\n  - **必须**支持动态路由\n\n### **前端插件开发规范**\n\n#### **插件目录结构**\n\n```\nsrc/plugin/[插件名]/\n├── api/                # 插件API接口\n│   └── [模块].js\n├── components/         # 插件组件（可选）\n│   └── [组件名].vue\n├── view/              # 插件页面\n│   └── [页面名].vue\n├── form/              # 插件表单（可选）\n│   └── [表单名].vue\n└── index.js           # 插件入口文件（可选）\n```\n\n#### **插件开发原则**\n\n1. **独立性**: 插件应该是自包含的，不依赖其他业务模块\n2. **可配置性**: 插件应该支持配置化，便于定制\n3. **可扩展性**: 插件应该预留扩展接口\n4. **一致性**: 插件UI风格应与主系统保持一致\n\n### **代码质量要求**\n\n1. **命名规范**:\n   - 文件名：kebab-case（短横线命名）\n   - 组件名：PascalCase（大驼峰）\n   - 变量名：camelCase（小驼峰）\n   - 常量名：UPPER_SNAKE_CASE（大写下划线）\n\n2. **注释规范**:\n   - **必须**为所有API函数添加JSDoc注释\n   - **必须**为复杂组件添加功能说明\n   - **必须**为关键业务逻辑添加行内注释\n\n3. **样式规范**:\n   - **优先**使用UnoCSS原子化类名\n   - **必须**遵循Element Plus设计规范\n   - **禁止**使用内联样式\n   - **必须**使用CSS变量进行主题定制\n\n4. **性能要求**:\n   - **必须**使用懒加载优化路由\n   - **必须**对大列表进行虚拟滚动优化\n   - **必须**合理使用缓存机制\n   - **必须**优化图片和资源加载\n\n---\n\n## **⚠️ 前端工具库使用规范（强制）**\n\n> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**\n\n`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：\n\n### **工具文件清单**\n\n#### `request.js` — HTTP 请求封装（核心）\n- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截\n- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**\n- 用法：`import service from '@/utils/request'`\n\n#### `date.js` — 日期格式化\n- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`\n- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串\n- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**\n- 用法：`import { formatTimeToStr } from '@/utils/date'`\n\n#### `format.js` — 数据展示格式化（综合工具）\n- `formatBoolean(bool)` — 将布尔值转为 \"是\"/\"否\" 中文展示\n- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串\n- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label\n- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找\n- `getDictFunc(type)` — 异步获取指定类型的字典数据\n- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀\n- `onDownloadFile(url)` — 触发文件下载\n- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）\n- `CreateUUID()` — 生成 UUID v4 字符串\n- `getBaseUrl()` — 获取当前环境的 API BaseURL\n- **以上所有格式化场景优先使用此文件中的工具函数**\n- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`\n\n#### `dictionary.js` — 字典数据获取\n- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求\n- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**\n- 用法：`import { getDict } from '@/utils/dictionary'`\n\n#### `stringFun.js` — 字符串处理\n- `toUpperCase(str)` — 首字母转大写\n- `toLowerCase(str)` — 首字母转小写\n- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`\n- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`\n- **进行命名格式转换时必须使用此工具，禁止使用正则手写**\n- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`\n\n#### `params.js` — 系统参数获取\n- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存\n- **获取系统配置参数时，优先使用此工具**\n- 用法：`import { getParams } from '@/utils/params'`\n\n#### `bus.js` — 全局事件总线\n- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信\n- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**\n- 用法：`import { emitter } from '@/utils/bus'`\n\n#### `closeThisPage.js` — 关闭当前标签页\n- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）\n- **在需要程序化关闭当前页面时，必须使用此工具**\n- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`\n\n#### `downloadImg.js` — 图片下载\n- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域\n- **需要下载图片时，优先使用此工具**\n- 用法：`import { downloadImage } from '@/utils/downloadImg'`\n\n#### `image.js` — 图片压缩\n- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小\n- **上传图片前需要做压缩处理时，使用此工具**\n- 用法：`import ImageCompress from '@/utils/image'`\n\n#### `event.js` — DOM 事件监听管理\n- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听\n- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听\n- **手动操作 DOM 事件时，使用此工具以确保安全性**\n- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`\n\n#### `env.js` — 环境判断\n- `isDev` — 是否为开发环境（Boolean）\n- `isProd` — 是否为生产环境（Boolean）\n- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**\n- 用法：`import { isDev, isProd } from '@/utils/env'`\n\n#### `doc.js` — 外部文档跳转\n- `toDoc(url)` — 在新标签页打开指定 URL\n- 用法：`import { toDoc } from '@/utils/doc'`\n\n#### `fmtRouterTitle.js` — 路由标题格式化\n- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）\n- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`\n\n#### `page.js` — 页面标题生成\n- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）\n- 用法：`import getPageTitle from '@/utils/page'`\n\n#### `asyncRouter.js` — 异步路由处理\n- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录\n- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**\n- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`\n\n#### `btnAuth.js` — 按钮权限\n- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示\n- **实现按钮级别权限控制时，必须使用此 Hook**\n- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`\n\n### **使用强制要求**\n\n| 场景 | 必须使用的工具 |\n|------|----------------|\n| 发送 HTTP 请求 | `@/utils/request` |\n| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |\n| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |\n| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |\n| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |\n| 驼峰/下划线命名转换 | `@/utils/stringFun` |\n| 获取系统参数 | `@/utils/params` 中的 `getParams` |\n| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |\n| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |\n| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |\n| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |\n| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |\n\n---\n\n## **前后端协作规范**\n\n### **接口协作规范**\n\n1. **接口文档**:\n   - 后端**必须**提供完整的Swagger API文档\n   - 前端**必须**基于Swagger文档进行接口调用\n   - 接口变更**必须**提前通知并更新文档\n\n2. **数据格式**:\n   - **统一**使用JSON格式进行数据交换\n   - **统一**响应格式：`{code, data, msg}`\n   - **统一**分页格式：`{page, pageSize, total, list}`\n   - **统一**时间格式：ISO 8601标准\n   - **⚠️ 数据类型一致性**：\n      - 前后端对于同一字段**必须**使用相同的数据类型\n      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致\n      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段\n      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型\n      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值\n\n3. **错误处理**:\n   - 后端**必须**返回标准化的错误码和错误信息\n   - 前端**必须**统一处理HTTP状态码和业务错误码\n   - **必须**提供用户友好的错误提示\n\n### **开发流程规范**\n\n1. **需求分析阶段**:\n   - 确定功能需求和接口设计\n   - 定义数据模型和业务流程\n   - 制定前后端开发计划\n\n2. **开发阶段**:\n   - 后端优先开发API接口\n   - 前端基于Mock数据进行并行开发\n   - 定期进行接口联调测试\n\n3. **测试阶段**:\n   - 单元测试：前后端各自负责\n   - 集成测试：前后端协作完成\n   - 用户验收测试：产品团队主导\n\n### **版本管理规范**\n\n1. **分支策略**:\n   - `main`：生产环境分支\n   - `develop`：开发环境分支\n   - `feature/*`：功能开发分支\n   - `hotfix/*`：紧急修复分支\n\n2. **提交规范**:\n   - 使用语义化提交信息\n   - 格式：`type(scope): description`\n   - 类型：feat, fix, docs, style, refactor, test, chore\n\n---\n\n## **插件开发完整规范**\n\n### **后端插件结构**\n\n```\nserver/plugin/[插件名]/\n├── api/                # API控制器\n│   ├── enter.go       # API组入口\n│   └── [模块].go      # 具体API实现\n├── config/            # 插件配置\n│   └── config.go\n├── initialize/        # 初始化模块\n│   ├── api.go        # API注册\n│   ├── gorm.go       # 数据库初始化\n│   ├── menu.go       # 菜单初始化\n│   ├── router.go     # 路由初始化\n│   └── viper.go      # 配置初始化\n├── model/             # 数据模型\n│   ├── [模型].go     # 数据库模型\n│   └── request/      # 请求模型\n├── router/            # 路由定义\n│   ├── enter.go      # 路由组入口\n│   └── [模块].go     # 具体路由\n├── service/           # 业务服务\n│   ├── enter.go      # 服务组入口\n│   └── [模块].go     # 具体服务\n└── plugin.go          # 插件入口\n```\n\n### **前端插件结构**\n\n```\nweb/src/plugin/[插件名]/\n├── api/               # API接口\n│   └── [模块].js\n├── components/        # 插件组件\n│   └── [组件].vue\n├── view/             # 插件页面\n│   └── [页面].vue\n├── form/             # 表单组件\n│   └── [表单].vue\n└── config.js         # 插件配置\n```\n\n### **插件开发工作流**\n\n1. **【第一步】需求分析**:\n   - 明确插件功能和业务需求\n   - 设计数据模型和接口规范\n   - 规划前端页面和交互流程\n\n2. **【第二步】后端开发**:\n   - 创建数据模型和请求模型\n   - 实现服务层业务逻辑\n   - 开发API控制器和路由\n   - 编写初始化和配置代码\n\n3. **【第三步】前端开发**:\n   - 创建API接口封装\n   - 开发页面组件和表单\n   - 实现业务逻辑和状态管理\n   - 集成到主系统菜单\n\n4. **【第四步】测试集成**:\n   - 单元测试和集成测试\n   - 前后端联调测试\n   - 用户体验测试\n   - 性能和安全测试\n\n### **插件质量标准**\n\n1. **功能完整性**: 插件功能完整，满足业务需求\n2. **代码质量**: 代码规范，注释完整，易于维护\n3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误\n4. **性能表现**: 响应速度快，资源占用合理\n5. **用户体验**: 界面友好，操作流畅，错误处理完善\n6. **兼容性**: 与主系统兼容，不影响其他功能\n7. **安全性**: 数据安全，权限控制，防止安全漏洞\n\n---\n\n### **建议和方案**\n\n基于以上规范，建议AI在开发gin-vue-admin项目时：\n\n1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织\n2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格\n3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性\n4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理\n5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强\n6. **重视安全性**：实现完善的权限控制和数据验证机制"},"items":[{"name":"project_rules.md","path":".aone_copilot/rules/project_rules.md","rawUrl":"https://raw.githubusercontent.com/flipped-aurora/gin-vue-admin/HEAD/.aone_copilot/rules/project_rules.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"### 功能描述以及必要性描述\n\n---\nname: gin-vue-admin\ndescription: |\n  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。\n  \n  前端技术栈：\n  - Vue 3.5.7 + Composition API\n  - Vite 6.2.3 构建工具\n  - Pinia 2.2.2 状态管理\n  - Element Plus 2.10.2 UI组件库\n  - UnoCSS 66.4.2 原子化CSS框架\n  - Vue Router 4.4.3 路由管理\n  - Axios 1.8.2 HTTP客户端\n  - ECharts 5.5.1 数据可视化\n  - @vueuse/core Vue组合式API工具集\n  \n  后端技术栈：\n  - Go 1.23 + Gin 1.10.0 Web框架\n  - GORM 1.25.12 ORM框架\n  - Casbin 2.103.0 权限管理\n  - Viper 1.19.0 配置管理\n  - Zap 1.27.0 日志系统\n  - Redis 9.7.0 缓存\n  - JWT 5.2.2 认证授权\n  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库\n  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务\n  \n  核心特性：\n  - 完整的RBAC权限控制系统\n  - 代码自动生成功能\n  - 丰富的中间件支持\n  - 插件化架构设计\n  - Swagger API文档\n---\n\n#### **角色与目标**\n\n你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。\n\n你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n---\n\n### **🚀 重要提示：GVA Helper MCP 支持**\n\n**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**\n\n1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力\n\n2. **GVA Helper**: 通常会有一个名为 \"**GVA Helper**\" 的MCP助手，专门为GVA框架开发提供支持\n\n3. **开发流程**: \n   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**\n   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作\n   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范\n\n4. **优势**: 通过GVA Helper可以获得：\n   - 最新的GVA框架特性和最佳实践\n   - 符合项目规范的代码模板\n   - 避免常见的开发陷阱和错误\n   - 确保代码质量和一致性\n\n**请始终记住：GVA Helper → 获得支持 → 开始开发**\n\n---\n\n### **核心开发指令：绝不可违背的原则**\n\n\n## **项目结构说明**\n\n### **整体架构**\n\ngin-vue-admin 采用前后端分离架构：\n- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务\n- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用\n- **部署 (deploy/)**：Docker、Kubernetes 等部署配置\n\n### **后端目录结构 (server/)**\n\n```\nserver/\n├── api/                    # API控制器层\n│   └── v1/                # API版本控制\n│       ├── enter.go       # API组入口文件\n│       ├── system/        # 系统模块API\n│       └──example/       # 示例模块API\n├── config/                # 配置结构体定义\n├── core/                  # 核心启动文件\n├── docs/                  # Swagger文档\n├── global/                # 全局变量和模型\n├── initialize/            # 初始化模块\n├── middleware/            # 中间件\n├── model/                 # 数据模型层\n│   ├── system/           # 系统模块模型\n│   ├── example/          # 示例模块模型\n│   └── common/           # 通用模型\n├── plugin/               # 插件目录\n│   ├── announcement/     # 公告插件\n│   └── email/           # 邮件插件\n├── router/               # 路由层\n│   ├── enter.go         # 路由组入口\n│   ├── system/          # 系统路由\n│   └──example/         # 示例路由\n├── service/              # 服务层\n│   ├── enter.go         # 服务组入口\n│   ├── system/          # 系统服务\n│   └──  example/         # 示例服务\n├── source/               # 数据初始化\n├── utils/                # 工具包\n├── config.yaml          # 配置文件\n└── main.go              # 程序入口\n```\n\n### **前端目录结构 (web/)**\n\n```\nweb/\n├── public/               # 静态资源\n├── src/\n│   ├── api/             # API接口定义\n│   │   ├── user.js      # 用户相关API\n│   │   ├── menu.js      # 菜单相关API\n│   │   └── cattery/     # 业务模块API\n│   ├── assets/          # 资源文件\n│   │   ├── icons/       # 图标\n│   │   └── images/      # 图片\n│   ├── core/            # 核心配置\n│   ├── directive/       # 自定义指令\n│   ├── hooks/           # 组合式API钩子\n│   ├── pinia/           # 状态管理\n│   │   ├── index.js     # Pinia入口\n│   │   └── modules/     # 状态模块\n│   ├── plugin/          # 前端插件\n│   │   ├── announcement/ # 公告插件\n│   │   └── email/       # 邮件插件\n│   ├── router/          # 路由配置\n│   ├── style/           # 样式文件\n│   ├── utils/           # 工具函数\n│   ├── view/            # 页面组件\n│   │   ├── dashboard/   # 仪表盘\n│   │   ├── layout/      # 布局组件\n│   │   ├── login/       # 登录页\n│   │   ├── superAdmin/  # 超级管理员\n│   │   ├── systemTools/ # 系统工具\n│   │   └── cattery/     # 业务页面\n│   ├── App.vue          # 根组件\n│   └── main.js          # 程序入口\n├── package.json         # 依赖配置\n├── vite.config.js       # Vite配置\n└── uno.config.js        # UnoCSS配置\n```\n\n---\n\n#### 后端规则\n\n在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的分层架构**:\n    \n    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。\n        \n    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。\n        \n2. **`enter.go` 组管理模式**:\n    \n    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。\n        \n    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。\n        \n3. **详尽的 Swagger 注释 (API层强制要求)**:\n    \n    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。\n        \n4. **统一的响应与错误处理**:\n    \n    - Service 层函数遇到业务错误时，应返回 `error` 对象。\n        \n    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。\n        \n\n---\n\n### **各层级代码实现规范**\n\n#### **1. 模型层 (`model/`)**\n\n- **数据模型 (`model/xxx.go`)**:\n\n   - 用于定义与数据库表映射的 GORM 结构体。\n\n   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。\n\n   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`\n\n   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。\n\n   - **⚠️ 重要提醒：数据类型一致性**\n      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致\n      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型\n      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常\n      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致\n      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段\n      - **⚠️ 指针类型处理**：\n         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换\n         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址\n         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`\n\n- **请求模型 (`model/request/xxx.go`)**:\n    \n    - 用于定义接收前端请求参数的结构体（DTOs）。\n        \n    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。\n        \n    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。\n        \n\n#### **2. 服务层 (`service/`)**\n\n- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。\n    \n- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。\n    \n- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。\n\n- **⚠️ 数据类型处理注意事项**:\n   - 在进行数据模型转换时，**必须确保**字段类型的一致性\n   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型\n   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑\n\n\n#### **3. API层 (`api/`)**\n\n- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。\n    \n- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。\n    \n- **Swagger 示例 (必须遵循)**:\n    \n    Go\n    \n    ```\n    // CreateXxx 创建XXX\n    // @Tags     XxxModule\n    // @Summary  创建一个新的XXX\n    // @Security ApiKeyAuth\n    // @accept   application/json\n    // @Produce  application/json\n    // @Param    data body request.CreateXxxRequest true \"XXX的名称和描述\"\n    // @Success  200  {object} response.Response{msg=string} \"创建成功\"\n    // @Router   /xxx/createXxx [post]\n    func (a *XxxApi) CreateXxx(c *gin.Context) {\n        // ...\n    }\n    ```\n    \n\n#### **4. 路由层 (`router/`)**\n\n- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。\n    \n- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。\n    \n- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。\n\n#### **5. 初始化层 (`initialize/`)**\n\n- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。\n    \n- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。\n    \n- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。\n    \n- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。\n- viper.go: 加载插件配置文件\n-  api.go: 注册API到系统\n    \n\n#### **6. 插件入口 (`plugin.go`) \n\n- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。\n    \n- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。\n\n- **插件注册**: **必须**调用 ```\nfunc init() {\n\tinterfaces.Register(Plugin)\n}\n```\n方法，让插件自动注册到本体中\n    \n- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。\n    \n- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `\"/myPlugin\"`。\n\n### 模块间引用关系：\n- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`\n- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`\n- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`\n- 各模块通过enter.go文件组织和暴露功能，避免循环引用\n\n### 插件默认注册功能\n\n`plugin/register.go` 文件下用 `\t_ \"github.com/flipped-aurora/gin-vue-admin/server/plugin/插件\"\n` 的方式匿名引用用于激活插件本体的init\n\n### 代码组织示例：\n\n1. Service入口 (service/enter.go):\n```go\npackage service\n\ntype ServiceGroup struct {\n    XxxService\n    YyyService\n    // 其他服务...\n}\n\nvar ServiceGroupApp = new(ServiceGroup)\n```\n\n2. API入口 (api/enter.go):\n```go\npackage api\n\ntype ApiGroup struct {\n    XxxApi\n    YyyApi\n    // 其他API...\n}\n\nvar ApiGroupApp = new(ApiGroup)\n```\n\n3. Router入口 (router/enter.go):\n```go\npackage router\n\ntype RouterGroup struct {\n    XxxRouter\n    YyyRouter\n    // 其他路由...\n}\n\nvar RouterGroupApp = new(RouterGroup)\n```\n\n### Swagger注释规范：\n- @Tags: 接口所属的分组\n- @Summary: 接口功能简述\n- @Security: 安全认证方式（如需认证则添加）\n- @accept/@Produce: 请求/响应格式\n- @Param: 请求参数，包括名称、来源、类型、是否必须、描述\n- @Success: 成功响应，包括状态码、返回类型、描述\n- @Router: 接口路径和HTTP方法\n\nAPI函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。\n\n\n---\n\n### **开发工作流**\n\n1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。\n    \n2. **【第一步】模型设计 (奠定基础)**:\n    \n    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。\n        \n3. **【第二步】自下而上，分层实现**:\n    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！\n\n    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。\n        \n    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。\n        \n4. **【第三步】插件初始化与注册**:\n    \n    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。\n        \n5. **【第四步】提供完整代码**:\n    \n    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。\n\n\n---\n\n## **前端开发规范**\n\n### **角色与目标**\n\n你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。\n\n你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n### **核心开发指令：绝不可违背的原则**\n\n#### 前端规则\n\n在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的模块化架构**:\n   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**\n   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`\n\n2. **统一的API调用模式**:\n   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装\n   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求\n   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值\n\n3. **组件化开发原则**:\n   - **每一个**可复用的UI元素都**必须**封装为组件\n   - 组件**必须**遵循单一职责原则，功能明确\n   - **必须**为组件添加完整的props定义和事件说明\n\n4. **统一的状态管理**:\n   - 全局状态**必须**使用Pinia进行管理\n   - 状态模块**必须**按业务功能进行划分\n   - **严禁**在组件中直接修改全局状态，必须通过actions\n\n### **各层级代码实现规范**\n\n#### **1. API层 (`src/api/`)**\n\n- **职责**: 封装所有后端API调用，提供统一的接口服务\n- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`\n- **规范**:\n  ```javascript\n  import service from '@/utils/request'\n  \n  /**\n   * 获取用户列表\n   * @param {Object} data 查询参数\n   * @param {number} data.page 页码\n   * @param {number} data.pageSize 每页数量\n   * @returns {Promise} 用户列表数据\n   */\n  export const getUserList = (data) => {\n    return service({\n      url: '/user/getUserList',\n      method: 'post',\n      data: data\n    })\n  }\n  ```\n\n#### **2. 组件层 (`src/components/`)**\n\n- **职责**: 提供可复用的UI组件\n- **结构**: 按功能分类组织，每个组件一个文件夹\n- **规范**:\n  ```vue\n  <template>\n    <div class=\"gva-table\">\n      <!-- 组件内容 -->\n    </div>\n  </template>\n  \n  <script setup>\n  /**\n   * 通用表格组件\n   * @component GvaTable\n   * @description 提供统一的表格展示功能\n   */\n  \n  // Props定义\n  const props = defineProps({\n    data: {\n      type: Array,\n      required: true,\n      default: () => []\n    },\n    loading: {\n      type: Boolean,\n      default: false\n    }\n  })\n  \n  // 事件定义\n  const emit = defineEmits(['refresh', 'edit', 'delete'])\n  </script>\n  ```\n\n#### **3. 页面层 (`src/view/`)**\n\n- **职责**: 实现具体的业务页面\n- **结构**: 按业务模块组织，每个页面一个Vue文件\n- **规范**:\n  - **必须**使用Composition API\n  - **必须**进行响应式数据管理\n  - **必须**处理加载状态和错误状态\n  - **必须**遵循Element Plus组件规范\n  - **必须**优先使用UnoCSS原子化类名进行样式设计\n  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作\n  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染\n\n#### **4. 状态管理 (`src/pinia/`)**\n\n- **职责**: 管理全局状态和业务逻辑\n- **结构**: 按业务模块创建store文件\n- **规范**:\n  ```javascript\n  import { defineStore } from 'pinia'\n  import { ref, computed } from 'vue'\n  import { useStorage } from '@vueuse/core'\n  \n  export const useUserStore = defineStore('user', () => {\n    // 状态定义 - 使用 ref() 创建响应式状态\n    const userInfo = ref({\n      uuid: '',\n      nickName: '',\n      headerImg: '',\n      authority: {}\n    })\n    const token = useStorage('token', '')\n    \n    // 计算属性 - 使用 computed() 定义\n    const isLogin = computed(() => !!token.value)\n    \n    // 方法定义 - 直接定义函数作为 actions\n    const setUserInfo = (val) => {\n      userInfo.value = val\n    }\n    \n    const setToken = (val) => {\n      token.value = val\n    }\n    \n    const login = async (loginForm) => {\n      // 登录逻辑\n      try {\n        const res = await loginApi(loginForm)\n        if (res.code === 0) {\n          setUserInfo(res.data.user)\n          setToken(res.data.token)\n          return true\n        }\n        return false\n      } catch (error) {\n        console.error('Login error:', error)\n        return false\n      }\n    }\n    \n    const logout = async () => {\n      // 登出逻辑\n      token.value = ''\n      userInfo.value = {}\n    }\n    \n    // 返回所有需要暴露的状态和方法\n    return {\n      userInfo,\n      token,\n      isLogin,\n      setUserInfo,\n      setToken,\n      login,\n      logout\n    }\n  })\n  ```\n\n#### **5. 路由管理 (`src/router/`)**\n\n- **职责**: 管理页面路由和权限控制\n- **规范**:\n  - **必须**配置路由元信息\n  - **必须**实现权限验证\n  - **必须**支持动态路由\n\n### **前端插件开发规范**\n\n#### **插件目录结构**\n\n```\nsrc/plugin/[插件名]/\n├── api/                # 插件API接口\n│   └── [模块].js\n├── components/         # 插件组件（可选）\n│   └── [组件名].vue\n├── view/              # 插件页面\n│   └── [页面名].vue\n├── form/              # 插件表单（可选）\n│   └── [表单名].vue\n└── index.js           # 插件入口文件（可选）\n```\n\n#### **插件开发原则**\n\n1. **独立性**: 插件应该是自包含的，不依赖其他业务模块\n2. **可配置性**: 插件应该支持配置化，便于定制\n3. **可扩展性**: 插件应该预留扩展接口\n4. **一致性**: 插件UI风格应与主系统保持一致\n\n### **代码质量要求**\n\n1. **命名规范**:\n   - 文件名：kebab-case（短横线命名）\n   - 组件名：PascalCase（大驼峰）\n   - 变量名：camelCase（小驼峰）\n   - 常量名：UPPER_SNAKE_CASE（大写下划线）\n\n2. **注释规范**:\n   - **必须**为所有API函数添加JSDoc注释\n   - **必须**为复杂组件添加功能说明\n   - **必须**为关键业务逻辑添加行内注释\n\n3. **样式规范**:\n   - **优先**使用UnoCSS原子化类名\n   - **必须**遵循Element Plus设计规范\n   - **禁止**使用内联样式\n   - **必须**使用CSS变量进行主题定制\n\n4. **性能要求**:\n   - **必须**使用懒加载优化路由\n   - **必须**对大列表进行虚拟滚动优化\n   - **必须**合理使用缓存机制\n   - **必须**优化图片和资源加载\n\n---\n\n## **⚠️ 前端工具库使用规范（强制）**\n\n> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**\n\n`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：\n\n### **工具文件清单**\n\n#### `request.js` — HTTP 请求封装（核心）\n- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截\n- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**\n- 用法：`import service from '@/utils/request'`\n\n#### `date.js` — 日期格式化\n- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`\n- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串\n- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**\n- 用法：`import { formatTimeToStr } from '@/utils/date'`\n\n#### `format.js` — 数据展示格式化（综合工具）\n- `formatBoolean(bool)` — 将布尔值转为 \"是\"/\"否\" 中文展示\n- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串\n- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label\n- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找\n- `getDictFunc(type)` — 异步获取指定类型的字典数据\n- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀\n- `onDownloadFile(url)` — 触发文件下载\n- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）\n- `CreateUUID()` — 生成 UUID v4 字符串\n- `getBaseUrl()` — 获取当前环境的 API BaseURL\n- **以上所有格式化场景优先使用此文件中的工具函数**\n- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`\n\n#### `dictionary.js` — 字典数据获取\n- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求\n- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**\n- 用法：`import { getDict } from '@/utils/dictionary'`\n\n#### `stringFun.js` — 字符串处理\n- `toUpperCase(str)` — 首字母转大写\n- `toLowerCase(str)` — 首字母转小写\n- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`\n- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`\n- **进行命名格式转换时必须使用此工具，禁止使用正则手写**\n- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`\n\n#### `params.js` — 系统参数获取\n- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存\n- **获取系统配置参数时，优先使用此工具**\n- 用法：`import { getParams } from '@/utils/params'`\n\n#### `bus.js` — 全局事件总线\n- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信\n- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**\n- 用法：`import { emitter } from '@/utils/bus'`\n\n#### `closeThisPage.js` — 关闭当前标签页\n- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）\n- **在需要程序化关闭当前页面时，必须使用此工具**\n- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`\n\n#### `downloadImg.js` — 图片下载\n- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域\n- **需要下载图片时，优先使用此工具**\n- 用法：`import { downloadImage } from '@/utils/downloadImg'`\n\n#### `image.js` — 图片压缩\n- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小\n- **上传图片前需要做压缩处理时，使用此工具**\n- 用法：`import ImageCompress from '@/utils/image'`\n\n#### `event.js` — DOM 事件监听管理\n- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听\n- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听\n- **手动操作 DOM 事件时，使用此工具以确保安全性**\n- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`\n\n#### `env.js` — 环境判断\n- `isDev` — 是否为开发环境（Boolean）\n- `isProd` — 是否为生产环境（Boolean）\n- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**\n- 用法：`import { isDev, isProd } from '@/utils/env'`\n\n#### `doc.js` — 外部文档跳转\n- `toDoc(url)` — 在新标签页打开指定 URL\n- 用法：`import { toDoc } from '@/utils/doc'`\n\n#### `fmtRouterTitle.js` — 路由标题格式化\n- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）\n- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`\n\n#### `page.js` — 页面标题生成\n- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）\n- 用法：`import getPageTitle from '@/utils/page'`\n\n#### `asyncRouter.js` — 异步路由处理\n- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录\n- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**\n- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`\n\n#### `btnAuth.js` — 按钮权限\n- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示\n- **实现按钮级别权限控制时，必须使用此 Hook**\n- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`\n\n### **使用强制要求**\n\n| 场景 | 必须使用的工具 |\n|------|----------------|\n| 发送 HTTP 请求 | `@/utils/request` |\n| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |\n| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |\n| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |\n| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |\n| 驼峰/下划线命名转换 | `@/utils/stringFun` |\n| 获取系统参数 | `@/utils/params` 中的 `getParams` |\n| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |\n| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |\n| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |\n| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |\n| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |\n\n---\n\n## **前后端协作规范**\n\n### **接口协作规范**\n\n1. **接口文档**:\n   - 后端**必须**提供完整的Swagger API文档\n   - 前端**必须**基于Swagger文档进行接口调用\n   - 接口变更**必须**提前通知并更新文档\n\n2. **数据格式**:\n   - **统一**使用JSON格式进行数据交换\n   - **统一**响应格式：`{code, data, msg}`\n   - **统一**分页格式：`{page, pageSize, total, list}`\n   - **统一**时间格式：ISO 8601标准\n   - **⚠️ 数据类型一致性**：\n      - 前后端对于同一字段**必须**使用相同的数据类型\n      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致\n      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段\n      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型\n      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值\n\n3. **错误处理**:\n   - 后端**必须**返回标准化的错误码和错误信息\n   - 前端**必须**统一处理HTTP状态码和业务错误码\n   - **必须**提供用户友好的错误提示\n\n### **开发流程规范**\n\n1. **需求分析阶段**:\n   - 确定功能需求和接口设计\n   - 定义数据模型和业务流程\n   - 制定前后端开发计划\n\n2. **开发阶段**:\n   - 后端优先开发API接口\n   - 前端基于Mock数据进行并行开发\n   - 定期进行接口联调测试\n\n3. **测试阶段**:\n   - 单元测试：前后端各自负责\n   - 集成测试：前后端协作完成\n   - 用户验收测试：产品团队主导\n\n### **版本管理规范**\n\n1. **分支策略**:\n   - `main`：生产环境分支\n   - `develop`：开发环境分支\n   - `feature/*`：功能开发分支\n   - `hotfix/*`：紧急修复分支\n\n2. **提交规范**:\n   - 使用语义化提交信息\n   - 格式：`type(scope): description`\n   - 类型：feat, fix, docs, style, refactor, test, chore\n\n---\n\n## **插件开发完整规范**\n\n### **后端插件结构**\n\n```\nserver/plugin/[插件名]/\n├── api/                # API控制器\n│   ├── enter.go       # API组入口\n│   └── [模块].go      # 具体API实现\n├── config/            # 插件配置\n│   └── config.go\n├── initialize/        # 初始化模块\n│   ├── api.go        # API注册\n│   ├── gorm.go       # 数据库初始化\n│   ├── menu.go       # 菜单初始化\n│   ├── router.go     # 路由初始化\n│   └── viper.go      # 配置初始化\n├── model/             # 数据模型\n│   ├── [模型].go     # 数据库模型\n│   └── request/      # 请求模型\n├── router/            # 路由定义\n│   ├── enter.go      # 路由组入口\n│   └── [模块].go     # 具体路由\n├── service/           # 业务服务\n│   ├── enter.go      # 服务组入口\n│   └── [模块].go     # 具体服务\n└── plugin.go          # 插件入口\n```\n\n### **前端插件结构**\n\n```\nweb/src/plugin/[插件名]/\n├── api/               # API接口\n│   └── [模块].js\n├── components/        # 插件组件\n│   └── [组件].vue\n├── view/             # 插件页面\n│   └── [页面].vue\n├── form/             # 表单组件\n│   └── [表单].vue\n└── config.js         # 插件配置\n```\n\n### **插件开发工作流**\n\n1. **【第一步】需求分析**:\n   - 明确插件功能和业务需求\n   - 设计数据模型和接口规范\n   - 规划前端页面和交互流程\n\n2. **【第二步】后端开发**:\n   - 创建数据模型和请求模型\n   - 实现服务层业务逻辑\n   - 开发API控制器和路由\n   - 编写初始化和配置代码\n\n3. **【第三步】前端开发**:\n   - 创建API接口封装\n   - 开发页面组件和表单\n   - 实现业务逻辑和状态管理\n   - 集成到主系统菜单\n\n4. **【第四步】测试集成**:\n   - 单元测试和集成测试\n   - 前后端联调测试\n   - 用户体验测试\n   - 性能和安全测试\n\n### **插件质量标准**\n\n1. **功能完整性**: 插件功能完整，满足业务需求\n2. **代码质量**: 代码规范，注释完整，易于维护\n3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误\n4. **性能表现**: 响应速度快，资源占用合理\n5. **用户体验**: 界面友好，操作流畅，错误处理完善\n6. **兼容性**: 与主系统兼容，不影响其他功能\n7. **安全性**: 数据安全，权限控制，防止安全漏洞\n\n---\n\n### **建议和方案**\n\n基于以上规范，建议AI在开发gin-vue-admin项目时：\n\n1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织\n2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格\n3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性\n4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理\n5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强\n6. **重视安全性**：实现完善的权限控制和数据验证机制","isInternal":false,"tokens":11645,"sizeBytes":35583},{"name":"project_rules.md","path":".claude/rules/project_rules.md","rawUrl":"https://raw.githubusercontent.com/flipped-aurora/gin-vue-admin/HEAD/.claude/rules/project_rules.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntool: claude\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Claude 规则适配层\n\n本文件只用于兼容 Claude 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n- 代码读取约束以 `/AGENT.MD` 为准，其中包括：无论什么情况，都不要直接读取 `node_modules/` 中的代码\n","frontmatter":{"tool":"claude","role":"compatibility-adapter","canonical_source":"/AGENT.MD","structured_context":"/aiDoc"},"isInternal":false,"tokens":276,"sizeBytes":770},{"name":"project_rules.md","path":".codex/rules/project_rules.md","rawUrl":"https://raw.githubusercontent.com/flipped-aurora/gin-vue-admin/HEAD/.codex/rules/project_rules.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntool: codex\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Codex 规则适配层\n\n本文件只用于兼容 Codex 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n","frontmatter":{"tool":"codex","role":"compatibility-adapter","canonical_source":"/AGENT.MD","structured_context":"/aiDoc"},"isInternal":false,"tokens":230,"sizeBytes":635},{"name":"project_rules.md","path":".cursor/rules/project_rules.md","rawUrl":"https://raw.githubusercontent.com/flipped-aurora/gin-vue-admin/HEAD/.cursor/rules/project_rules.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntool: cursor\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Cursor 规则适配层\n\n本文件只用于兼容 Cursor 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n","frontmatter":{"tool":"cursor","role":"compatibility-adapter","canonical_source":"/AGENT.MD","structured_context":"/aiDoc"},"isInternal":false,"tokens":227,"sizeBytes":638},{"name":"project_rules.md","path":".trae/rules/project_rules.md","rawUrl":"https://raw.githubusercontent.com/flipped-aurora/gin-vue-admin/HEAD/.trae/rules/project_rules.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntool: trae\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Trae 规则适配层\n\n本文件只用于兼容 Trae 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n","frontmatter":{"tool":"trae","role":"compatibility-adapter","canonical_source":"/AGENT.MD","structured_context":"/aiDoc"},"isInternal":false,"tokens":230,"sizeBytes":632}],"systemPromptSnippet":"<yakaai_skills repo=\"flipped-aurora/gin-vue-admin\">\n<!-- File: .aone_copilot/rules/project_rules.md (Tokens: ~11645 | Category: anthropic-skill) -->\n### 功能描述以及必要性描述\n\n---\nname: gin-vue-admin\ndescription: |\n  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。\n  \n  前端技术栈：\n  - Vue 3.5.7 + Composition API\n  - Vite 6.2.3 构建工具\n  - Pinia 2.2.2 状态管理\n  - Element Plus 2.10.2 UI组件库\n  - UnoCSS 66.4.2 原子化CSS框架\n  - Vue Router 4.4.3 路由管理\n  - Axios 1.8.2 HTTP客户端\n  - ECharts 5.5.1 数据可视化\n  - @vueuse/core Vue组合式API工具集\n  \n  后端技术栈：\n  - Go 1.23 + Gin 1.10.0 Web框架\n  - GORM 1.25.12 ORM框架\n  - Casbin 2.103.0 权限管理\n  - Viper 1.19.0 配置管理\n  - Zap 1.27.0 日志系统\n  - Redis 9.7.0 缓存\n  - JWT 5.2.2 认证授权\n  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库\n  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务\n  \n  核心特性：\n  - 完整的RBAC权限控制系统\n  - 代码自动生成功能\n  - 丰富的中间件支持\n  - 插件化架构设计\n  - Swagger API文档\n---\n\n#### **角色与目标**\n\n你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。\n\n你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n---\n\n### **🚀 重要提示：GVA Helper MCP 支持**\n\n**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**\n\n1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力\n\n2. **GVA Helper**: 通常会有一个名为 \"**GVA Helper**\" 的MCP助手，专门为GVA框架开发提供支持\n\n3. **开发流程**: \n   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**\n   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作\n   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范\n\n4. **优势**: 通过GVA Helper可以获得：\n   - 最新的GVA框架特性和最佳实践\n   - 符合项目规范的代码模板\n   - 避免常见的开发陷阱和错误\n   - 确保代码质量和一致性\n\n**请始终记住：GVA Helper → 获得支持 → 开始开发**\n\n---\n\n### **核心开发指令：绝不可违背的原则**\n\n\n## **项目结构说明**\n\n### **整体架构**\n\ngin-vue-admin 采用前后端分离架构：\n- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务\n- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用\n- **部署 (deploy/)**：Docker、Kubernetes 等部署配置\n\n### **后端目录结构 (server/)**\n\n```\nserver/\n├── api/                    # API控制器层\n│   └── v1/                # API版本控制\n│       ├── enter.go       # API组入口文件\n│       ├── system/        # 系统模块API\n│       └──example/       # 示例模块API\n├── config/                # 配置结构体定义\n├── core/                  # 核心启动文件\n├── docs/                  # Swagger文档\n├── global/                # 全局变量和模型\n├── initialize/            # 初始化模块\n├── middleware/            # 中间件\n├── model/                 # 数据模型层\n│   ├── system/           # 系统模块模型\n│   ├── example/          # 示例模块模型\n│   └── common/           # 通用模型\n├── plugin/               # 插件目录\n│   ├── announcement/     # 公告插件\n│   └── email/           # 邮件插件\n├── router/               # 路由层\n│   ├── enter.go         # 路由组入口\n│   ├── system/          # 系统路由\n│   └──example/         # 示例路由\n├── service/              # 服务层\n│   ├── enter.go         # 服务组入口\n│   ├── system/          # 系统服务\n│   └──  example/         # 示例服务\n├── source/               # 数据初始化\n├── utils/                # 工具包\n├── config.yaml          # 配置文件\n└── main.go              # 程序入口\n```\n\n### **前端目录结构 (web/)**\n\n```\nweb/\n├── public/               # 静态资源\n├── src/\n│   ├── api/             # API接口定义\n│   │   ├── user.js      # 用户相关API\n│   │   ├── menu.js      # 菜单相关API\n│   │   └── cattery/     # 业务模块API\n│   ├── assets/          # 资源文件\n│   │   ├── icons/       # 图标\n│   │   └── images/      # 图片\n│   ├── core/            # 核心配置\n│   ├── directive/       # 自定义指令\n│   ├── hooks/           # 组合式API钩子\n│   ├── pinia/           # 状态管理\n│   │   ├── index.js     # Pinia入口\n│   │   └── modules/     # 状态模块\n│   ├── plugin/          # 前端插件\n│   │   ├── announcement/ # 公告插件\n│   │   └── email/       # 邮件插件\n│   ├── router/          # 路由配置\n│   ├── style/           # 样式文件\n│   ├── utils/           # 工具函数\n│   ├── view/            # 页面组件\n│   │   ├── dashboard/   # 仪表盘\n│   │   ├── layout/      # 布局组件\n│   │   ├── login/       # 登录页\n│   │   ├── superAdmin/  # 超级管理员\n│   │   ├── systemTools/ # 系统工具\n│   │   └── cattery/     # 业务页面\n│   ├── App.vue          # 根组件\n│   └── main.js          # 程序入口\n├── package.json         # 依赖配置\n├── vite.config.js       # Vite配置\n└── uno.config.js        # UnoCSS配置\n```\n\n---\n\n#### 后端规则\n\n在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的分层架构**:\n    \n    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。\n        \n    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。\n        \n2. **`enter.go` 组管理模式**:\n    \n    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。\n        \n    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。\n        \n3. **详尽的 Swagger 注释 (API层强制要求)**:\n    \n    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。\n        \n4. **统一的响应与错误处理**:\n    \n    - Service 层函数遇到业务错误时，应返回 `error` 对象。\n        \n    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。\n        \n\n---\n\n### **各层级代码实现规范**\n\n#### **1. 模型层 (`model/`)**\n\n- **数据模型 (`model/xxx.go`)**:\n\n   - 用于定义与数据库表映射的 GORM 结构体。\n\n   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。\n\n   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`\n\n   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。\n\n   - **⚠️ 重要提醒：数据类型一致性**\n      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致\n      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型\n      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常\n      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致\n      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段\n      - **⚠️ 指针类型处理**：\n         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换\n         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址\n         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`\n\n- **请求模型 (`model/request/xxx.go`)**:\n    \n    - 用于定义接收前端请求参数的结构体（DTOs）。\n        \n    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。\n        \n    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。\n        \n\n#### **2. 服务层 (`service/`)**\n\n- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。\n    \n- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。\n    \n- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。\n\n- **⚠️ 数据类型处理注意事项**:\n   - 在进行数据模型转换时，**必须确保**字段类型的一致性\n   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型\n   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑\n\n\n#### **3. API层 (`api/`)**\n\n- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。\n    \n- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。\n    \n- **Swagger 示例 (必须遵循)**:\n    \n    Go\n    \n    ```\n    // CreateXxx 创建XXX\n    // @Tags     XxxModule\n    // @Summary  创建一个新的XXX\n    // @Security ApiKeyAuth\n    // @accept   application/json\n    // @Produce  application/json\n    // @Param    data body request.CreateXxxRequest true \"XXX的名称和描述\"\n    // @Success  200  {object} response.Response{msg=string} \"创建成功\"\n    // @Router   /xxx/createXxx [post]\n    func (a *XxxApi) CreateXxx(c *gin.Context) {\n        // ...\n    }\n    ```\n    \n\n#### **4. 路由层 (`router/`)**\n\n- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。\n    \n- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。\n    \n- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。\n    \n- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。\n\n#### **5. 初始化层 (`initialize/`)**\n\n- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。\n    \n- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。\n    \n- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。\n    \n- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。\n- viper.go: 加载插件配置文件\n-  api.go: 注册API到系统\n    \n\n#### **6. 插件入口 (`plugin.go`) \n\n- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。\n    \n- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。\n\n- **插件注册**: **必须**调用 ```\nfunc init() {\n\tinterfaces.Register(Plugin)\n}\n```\n方法，让插件自动注册到本体中\n    \n- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。\n    \n- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `\"/myPlugin\"`。\n\n### 模块间引用关系：\n- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`\n- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`\n- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`\n- 各模块通过enter.go文件组织和暴露功能，避免循环引用\n\n### 插件默认注册功能\n\n`plugin/register.go` 文件下用 `\t_ \"github.com/flipped-aurora/gin-vue-admin/server/plugin/插件\"\n` 的方式匿名引用用于激活插件本体的init\n\n### 代码组织示例：\n\n1. Service入口 (service/enter.go):\n```go\npackage service\n\ntype ServiceGroup struct {\n    XxxService\n    YyyService\n    // 其他服务...\n}\n\nvar ServiceGroupApp = new(ServiceGroup)\n```\n\n2. API入口 (api/enter.go):\n```go\npackage api\n\ntype ApiGroup struct {\n    XxxApi\n    YyyApi\n    // 其他API...\n}\n\nvar ApiGroupApp = new(ApiGroup)\n```\n\n3. Router入口 (router/enter.go):\n```go\npackage router\n\ntype RouterGroup struct {\n    XxxRouter\n    YyyRouter\n    // 其他路由...\n}\n\nvar RouterGroupApp = new(RouterGroup)\n```\n\n### Swagger注释规范：\n- @Tags: 接口所属的分组\n- @Summary: 接口功能简述\n- @Security: 安全认证方式（如需认证则添加）\n- @accept/@Produce: 请求/响应格式\n- @Param: 请求参数，包括名称、来源、类型、是否必须、描述\n- @Success: 成功响应，包括状态码、返回类型、描述\n- @Router: 接口路径和HTTP方法\n\nAPI函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。\n\n\n---\n\n### **开发工作流**\n\n1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。\n    \n2. **【第一步】模型设计 (奠定基础)**:\n    \n    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。\n        \n3. **【第二步】自下而上，分层实现**:\n    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！\n\n    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。\n        \n    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。\n        \n4. **【第三步】插件初始化与注册**:\n    \n    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。\n        \n5. **【第四步】提供完整代码**:\n    \n    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。\n\n\n---\n\n## **前端开发规范**\n\n### **角色与目标**\n\n你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。\n\n你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。\n\n### **核心开发指令：绝不可违背的原则**\n\n#### 前端规则\n\n在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：\n\n1. **严格的模块化架构**:\n   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**\n   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`\n\n2. **统一的API调用模式**:\n   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装\n   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求\n   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值\n\n3. **组件化开发原则**:\n   - **每一个**可复用的UI元素都**必须**封装为组件\n   - 组件**必须**遵循单一职责原则，功能明确\n   - **必须**为组件添加完整的props定义和事件说明\n\n4. **统一的状态管理**:\n   - 全局状态**必须**使用Pinia进行管理\n   - 状态模块**必须**按业务功能进行划分\n   - **严禁**在组件中直接修改全局状态，必须通过actions\n\n### **各层级代码实现规范**\n\n#### **1. API层 (`src/api/`)**\n\n- **职责**: 封装所有后端API调用，提供统一的接口服务\n- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`\n- **规范**:\n  ```javascript\n  import service from '@/utils/request'\n  \n  /**\n   * 获取用户列表\n   * @param {Object} data 查询参数\n   * @param {number} data.page 页码\n   * @param {number} data.pageSize 每页数量\n   * @returns {Promise} 用户列表数据\n   */\n  export const getUserList = (data) => {\n    return service({\n      url: '/user/getUserList',\n      method: 'post',\n      data: data\n    })\n  }\n  ```\n\n#### **2. 组件层 (`src/components/`)**\n\n- **职责**: 提供可复用的UI组件\n- **结构**: 按功能分类组织，每个组件一个文件夹\n- **规范**:\n  ```vue\n  <template>\n    <div class=\"gva-table\">\n      <!-- 组件内容 -->\n    </div>\n  </template>\n  \n  <script setup>\n  /**\n   * 通用表格组件\n   * @component GvaTable\n   * @description 提供统一的表格展示功能\n   */\n  \n  // Props定义\n  const props = defineProps({\n    data: {\n      type: Array,\n      required: true,\n      default: () => []\n    },\n    loading: {\n      type: Boolean,\n      default: false\n    }\n  })\n  \n  // 事件定义\n  const emit = defineEmits(['refresh', 'edit', 'delete'])\n  </script>\n  ```\n\n#### **3. 页面层 (`src/view/`)**\n\n- **职责**: 实现具体的业务页面\n- **结构**: 按业务模块组织，每个页面一个Vue文件\n- **规范**:\n  - **必须**使用Composition API\n  - **必须**进行响应式数据管理\n  - **必须**处理加载状态和错误状态\n  - **必须**遵循Element Plus组件规范\n  - **必须**优先使用UnoCSS原子化类名进行样式设计\n  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作\n  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染\n\n#### **4. 状态管理 (`src/pinia/`)**\n\n- **职责**: 管理全局状态和业务逻辑\n- **结构**: 按业务模块创建store文件\n- **规范**:\n  ```javascript\n  import { defineStore } from 'pinia'\n  import { ref, computed } from 'vue'\n  import { useStorage } from '@vueuse/core'\n  \n  export const useUserStore = defineStore('user', () => {\n    // 状态定义 - 使用 ref() 创建响应式状态\n    const userInfo = ref({\n      uuid: '',\n      nickName: '',\n      headerImg: '',\n      authority: {}\n    })\n    const token = useStorage('token', '')\n    \n    // 计算属性 - 使用 computed() 定义\n    const isLogin = computed(() => !!token.value)\n    \n    // 方法定义 - 直接定义函数作为 actions\n    const setUserInfo = (val) => {\n      userInfo.value = val\n    }\n    \n    const setToken = (val) => {\n      token.value = val\n    }\n    \n    const login = async (loginForm) => {\n      // 登录逻辑\n      try {\n        const res = await loginApi(loginForm)\n        if (res.code === 0) {\n          setUserInfo(res.data.user)\n          setToken(res.data.token)\n          return true\n        }\n        return false\n      } catch (error) {\n        console.error('Login error:', error)\n        return false\n      }\n    }\n    \n    const logout = async () => {\n      // 登出逻辑\n      token.value = ''\n      userInfo.value = {}\n    }\n    \n    // 返回所有需要暴露的状态和方法\n    return {\n      userInfo,\n      token,\n      isLogin,\n      setUserInfo,\n      setToken,\n      login,\n      logout\n    }\n  })\n  ```\n\n#### **5. 路由管理 (`src/router/`)**\n\n- **职责**: 管理页面路由和权限控制\n- **规范**:\n  - **必须**配置路由元信息\n  - **必须**实现权限验证\n  - **必须**支持动态路由\n\n### **前端插件开发规范**\n\n#### **插件目录结构**\n\n```\nsrc/plugin/[插件名]/\n├── api/                # 插件API接口\n│   └── [模块].js\n├── components/         # 插件组件（可选）\n│   └── [组件名].vue\n├── view/              # 插件页面\n│   └── [页面名].vue\n├── form/              # 插件表单（可选）\n│   └── [表单名].vue\n└── index.js           # 插件入口文件（可选）\n```\n\n#### **插件开发原则**\n\n1. **独立性**: 插件应该是自包含的，不依赖其他业务模块\n2. **可配置性**: 插件应该支持配置化，便于定制\n3. **可扩展性**: 插件应该预留扩展接口\n4. **一致性**: 插件UI风格应与主系统保持一致\n\n### **代码质量要求**\n\n1. **命名规范**:\n   - 文件名：kebab-case（短横线命名）\n   - 组件名：PascalCase（大驼峰）\n   - 变量名：camelCase（小驼峰）\n   - 常量名：UPPER_SNAKE_CASE（大写下划线）\n\n2. **注释规范**:\n   - **必须**为所有API函数添加JSDoc注释\n   - **必须**为复杂组件添加功能说明\n   - **必须**为关键业务逻辑添加行内注释\n\n3. **样式规范**:\n   - **优先**使用UnoCSS原子化类名\n   - **必须**遵循Element Plus设计规范\n   - **禁止**使用内联样式\n   - **必须**使用CSS变量进行主题定制\n\n4. **性能要求**:\n   - **必须**使用懒加载优化路由\n   - **必须**对大列表进行虚拟滚动优化\n   - **必须**合理使用缓存机制\n   - **必须**优化图片和资源加载\n\n---\n\n## **⚠️ 前端工具库使用规范（强制）**\n\n> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**\n\n`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：\n\n### **工具文件清单**\n\n#### `request.js` — HTTP 请求封装（核心）\n- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截\n- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**\n- 用法：`import service from '@/utils/request'`\n\n#### `date.js` — 日期格式化\n- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`\n- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串\n- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**\n- 用法：`import { formatTimeToStr } from '@/utils/date'`\n\n#### `format.js` — 数据展示格式化（综合工具）\n- `formatBoolean(bool)` — 将布尔值转为 \"是\"/\"否\" 中文展示\n- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串\n- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label\n- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找\n- `getDictFunc(type)` — 异步获取指定类型的字典数据\n- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀\n- `onDownloadFile(url)` — 触发文件下载\n- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）\n- `CreateUUID()` — 生成 UUID v4 字符串\n- `getBaseUrl()` — 获取当前环境的 API BaseURL\n- **以上所有格式化场景优先使用此文件中的工具函数**\n- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`\n\n#### `dictionary.js` — 字典数据获取\n- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求\n- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**\n- 用法：`import { getDict } from '@/utils/dictionary'`\n\n#### `stringFun.js` — 字符串处理\n- `toUpperCase(str)` — 首字母转大写\n- `toLowerCase(str)` — 首字母转小写\n- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`\n- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`\n- **进行命名格式转换时必须使用此工具，禁止使用正则手写**\n- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`\n\n#### `params.js` — 系统参数获取\n- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存\n- **获取系统配置参数时，优先使用此工具**\n- 用法：`import { getParams } from '@/utils/params'`\n\n#### `bus.js` — 全局事件总线\n- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信\n- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**\n- 用法：`import { emitter } from '@/utils/bus'`\n\n#### `closeThisPage.js` — 关闭当前标签页\n- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）\n- **在需要程序化关闭当前页面时，必须使用此工具**\n- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`\n\n#### `downloadImg.js` — 图片下载\n- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域\n- **需要下载图片时，优先使用此工具**\n- 用法：`import { downloadImage } from '@/utils/downloadImg'`\n\n#### `image.js` — 图片压缩\n- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小\n- **上传图片前需要做压缩处理时，使用此工具**\n- 用法：`import ImageCompress from '@/utils/image'`\n\n#### `event.js` — DOM 事件监听管理\n- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听\n- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听\n- **手动操作 DOM 事件时，使用此工具以确保安全性**\n- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`\n\n#### `env.js` — 环境判断\n- `isDev` — 是否为开发环境（Boolean）\n- `isProd` — 是否为生产环境（Boolean）\n- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**\n- 用法：`import { isDev, isProd } from '@/utils/env'`\n\n#### `doc.js` — 外部文档跳转\n- `toDoc(url)` — 在新标签页打开指定 URL\n- 用法：`import { toDoc } from '@/utils/doc'`\n\n#### `fmtRouterTitle.js` — 路由标题格式化\n- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）\n- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`\n\n#### `page.js` — 页面标题生成\n- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）\n- 用法：`import getPageTitle from '@/utils/page'`\n\n#### `asyncRouter.js` — 异步路由处理\n- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录\n- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**\n- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`\n\n#### `btnAuth.js` — 按钮权限\n- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示\n- **实现按钮级别权限控制时，必须使用此 Hook**\n- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`\n\n### **使用强制要求**\n\n| 场景 | 必须使用的工具 |\n|------|----------------|\n| 发送 HTTP 请求 | `@/utils/request` |\n| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |\n| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |\n| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |\n| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |\n| 驼峰/下划线命名转换 | `@/utils/stringFun` |\n| 获取系统参数 | `@/utils/params` 中的 `getParams` |\n| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |\n| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |\n| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |\n| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |\n| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |\n\n---\n\n## **前后端协作规范**\n\n### **接口协作规范**\n\n1. **接口文档**:\n   - 后端**必须**提供完整的Swagger API文档\n   - 前端**必须**基于Swagger文档进行接口调用\n   - 接口变更**必须**提前通知并更新文档\n\n2. **数据格式**:\n   - **统一**使用JSON格式进行数据交换\n   - **统一**响应格式：`{code, data, msg}`\n   - **统一**分页格式：`{page, pageSize, total, list}`\n   - **统一**时间格式：ISO 8601标准\n   - **⚠️ 数据类型一致性**：\n      - 前后端对于同一字段**必须**使用相同的数据类型\n      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致\n      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段\n      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型\n      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值\n\n3. **错误处理**:\n   - 后端**必须**返回标准化的错误码和错误信息\n   - 前端**必须**统一处理HTTP状态码和业务错误码\n   - **必须**提供用户友好的错误提示\n\n### **开发流程规范**\n\n1. **需求分析阶段**:\n   - 确定功能需求和接口设计\n   - 定义数据模型和业务流程\n   - 制定前后端开发计划\n\n2. **开发阶段**:\n   - 后端优先开发API接口\n   - 前端基于Mock数据进行并行开发\n   - 定期进行接口联调测试\n\n3. **测试阶段**:\n   - 单元测试：前后端各自负责\n   - 集成测试：前后端协作完成\n   - 用户验收测试：产品团队主导\n\n### **版本管理规范**\n\n1. **分支策略**:\n   - `main`：生产环境分支\n   - `develop`：开发环境分支\n   - `feature/*`：功能开发分支\n   - `hotfix/*`：紧急修复分支\n\n2. **提交规范**:\n   - 使用语义化提交信息\n   - 格式：`type(scope): description`\n   - 类型：feat, fix, docs, style, refactor, test, chore\n\n---\n\n## **插件开发完整规范**\n\n### **后端插件结构**\n\n```\nserver/plugin/[插件名]/\n├── api/                # API控制器\n│   ├── enter.go       # API组入口\n│   └── [模块].go      # 具体API实现\n├── config/            # 插件配置\n│   └── config.go\n├── initialize/        # 初始化模块\n│   ├── api.go        # API注册\n│   ├── gorm.go       # 数据库初始化\n│   ├── menu.go       # 菜单初始化\n│   ├── router.go     # 路由初始化\n│   └── viper.go      # 配置初始化\n├── model/             # 数据模型\n│   ├── [模型].go     # 数据库模型\n│   └── request/      # 请求模型\n├── router/            # 路由定义\n│   ├── enter.go      # 路由组入口\n│   └── [模块].go     # 具体路由\n├── service/           # 业务服务\n│   ├── enter.go      # 服务组入口\n│   └── [模块].go     # 具体服务\n└── plugin.go          # 插件入口\n```\n\n### **前端插件结构**\n\n```\nweb/src/plugin/[插件名]/\n├── api/               # API接口\n│   └── [模块].js\n├── components/        # 插件组件\n│   └── [组件].vue\n├── view/             # 插件页面\n│   └── [页面].vue\n├── form/             # 表单组件\n│   └── [表单].vue\n└── config.js         # 插件配置\n```\n\n### **插件开发工作流**\n\n1. **【第一步】需求分析**:\n   - 明确插件功能和业务需求\n   - 设计数据模型和接口规范\n   - 规划前端页面和交互流程\n\n2. **【第二步】后端开发**:\n   - 创建数据模型和请求模型\n   - 实现服务层业务逻辑\n   - 开发API控制器和路由\n   - 编写初始化和配置代码\n\n3. **【第三步】前端开发**:\n   - 创建API接口封装\n   - 开发页面组件和表单\n   - 实现业务逻辑和状态管理\n   - 集成到主系统菜单\n\n4. **【第四步】测试集成**:\n   - 单元测试和集成测试\n   - 前后端联调测试\n   - 用户体验测试\n   - 性能和安全测试\n\n### **插件质量标准**\n\n1. **功能完整性**: 插件功能完整，满足业务需求\n2. **代码质量**: 代码规范，注释完整，易于维护\n3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误\n4. **性能表现**: 响应速度快，资源占用合理\n5. **用户体验**: 界面友好，操作流畅，错误处理完善\n6. **兼容性**: 与主系统兼容，不影响其他功能\n7. **安全性**: 数据安全，权限控制，防止安全漏洞\n\n---\n\n### **建议和方案**\n\n基于以上规范，建议AI在开发gin-vue-admin项目时：\n\n1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织\n2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格\n3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性\n4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理\n5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强\n6. **重视安全性**：实现完善的权限控制和数据验证机制\n\n<!-- File: .claude/rules/project_rules.md (Tokens: ~276 | Category: anthropic-skill) -->\n---\ntool: claude\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Claude 规则适配层\n\n本文件只用于兼容 Claude 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n- 代码读取约束以 `/AGENT.MD` 为准，其中包括：无论什么情况，都不要直接读取 `node_modules/` 中的代码\n\n<!-- File: .codex/rules/project_rules.md (Tokens: ~230 | Category: anthropic-skill) -->\n---\ntool: codex\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Codex 规则适配层\n\n本文件只用于兼容 Codex 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n\n<!-- File: .cursor/rules/project_rules.md (Tokens: ~227 | Category: anthropic-skill) -->\n---\ntool: cursor\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Cursor 规则适配层\n\n本文件只用于兼容 Cursor 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n\n<!-- File: .trae/rules/project_rules.md (Tokens: ~230 | Category: anthropic-skill) -->\n---\ntool: trae\nrole: compatibility-adapter\ncanonical_source: /AGENT.MD\nstructured_context: /aiDoc\n---\n\n# Trae 规则适配层\n\n本文件只用于兼容 Trae 现有的自动加载路径。\n\n## 真实规则入口\n\n请按下面顺序读取：\n\n1. `/AGENT.MD`\n2. `/aiDoc/README.md`\n3. `/aiDoc/relations/`、`/aiDoc/modules/`、`/aiDoc/frontend-backend/`、`/aiDoc/examples/`、`/aiDoc/memory/` 中与当前任务相关的文件\n\n## 适配层约束\n\n- 不要在这里扩写项目级规则\n- 项目级规则变更时，先更新 `/AGENT.MD` 与 `/aiDoc/`\n- 工具目录只保留薄适配层职责，不再保存独立 project rule 副本\n</yakaai_skills>"}