# AGENTS.md

本文件为 AI 编码助手提供本仓库（OmegaAi）的项目背景、技术栈、架构约定、接口调用约定与常见任务速查，帮助在修改代码时保持正确性与一致性。

> **完整项目目录结构、编码规范统一维护在 [PROJECT_SPEC.md](./PROJECT_SPEC.md)**，本文件不再重复存放。

---

## 1. 项目概览

OmegaAi 是一个**低代码 / 微服务后端管理系统**，采用 **Monorepo** 结构，包含两大模块：

| 目录 | 说明 |
| --- | --- |
| `AdminFrontEnd/` | 后台管理系统前端（Vue 3 + TypeScript + Rsbuild） |
| `BackEnd/` | 后端微服务项目（.NET 7，共 9 个服务） |

前端通过 `OmegaGateway` 网关访问各个微服务；前后端通过 **Nacos 服务发现 + URL 字典映射** 的方式约定接口调用（见下文「前后端接口调用约定」）。

---

## 2. 仓库结构

OmegaAi 采用 **Monorepo** 结构，包含两大模块：

| 目录 | 说明 |
| --- | --- |
| `AdminFrontEnd/` | 后台管理系统前端（Vue 3 + TypeScript + Rsbuild） |
| `BackEnd/` | 后端微服务项目（.NET 7，共 9 个服务） |

> 完整目录结构（前端各目录职责、9 个后端服务明细与通用服务骨架）见 [PROJECT_SPEC.md §1](./PROJECT_SPEC.md#1-完整项目目录结构)。

---

## 3. 技术栈

### 3.1 前端（AdminFrontEnd）

| 类别 | 技术 |
| --- | --- |
| 框架 | Vue 3.5（Composition API + `<script setup>`）、TypeScript ~5.8 |
| 构建 | Rsbuild 2（rsbuild.config.ts，dev 端口 **9906**）、Rspack |
| 包管理 | **pnpm**（pnpm@10.33.0），Node `^20.19 || ^22.13 || >=24` |
| UI 库 | Element Plus 2.13、vue-element-plus-x、Tailwind CSS 4 |
| 状态 | Pinia 3 + `pinia-plugin-persistedstate`（zipson 序列化 + secure-ls 加密存储） |
| 路由 | vue-router 4（**Hash 模式**），动态路由由后端菜单生成 |
| 请求 | 自定义 fetch 封装（`src/utils/http/request.ts`），支持请求合并/缓存/取消/响应缓存 |
| 组件 | unplugin-auto-import、unplugin-vue-components、unplugin-icons 自动引入 |
| 其他 | echarts（图表）、@vue-flow（流程图）、codemirror（代码编辑器）、json-render（动态渲染）、dayjs、write-excel-file（导出） |
| 代码规范 | ESLint（eslint.config.mjs）+ Prettier + Stylelint；`pnpm lint` / `pnpm format` / `pnpm type:check` |

### 3.2 后端（BackEnd）

| 类别 | 技术 |
| --- | --- |
| 框架 | **.NET 7** / ASP.NET Core Web API（net7.0，可空启用、隐式 using） |
| ORM | SqlSugar（SqlSugarCoreNoDrive 5.1.4.136 + SqlSugar.IOC），多数据源、支持 MySQL/PostgreSQL（Npgsql） |
| DI / 自动注册 | **SummerBoot**（`AppServiceAttribute` 标注的服务自动注入） |
| 配置中心 / 注册发现 | **Nacos**（nacos-sdk-csharp，NacosConfig 配置，DataId `omega`） |
| API 网关 | **OmegaGateway**：YARP Reverse Proxy + Nacos 服务发现，动态同步路由（RefreshYarp，60s 刷新） |
| 认证授权 | JWT（JwtUtil）、`AuthorizationFilter` / `VerifyAttribute` / `ActionPermissionFilter`（权限点） |
| 缓存 | CSRedisCore（RedisServer / CacheHelper），按 `RedisServer:open` 开关 |
| 日志 | NLog（SQL 日志按读写分级：SELECT→Info、UPDATE/INSERT→Warn、DELETE→Error） |
| 限流 | AspNetCoreRateLimit + IPRate（iprate.json，`AddIPRate`） |
| 对象映射 | Mapster（`Adapt<>`） |
| 文件存储 | 阿里云 OSS（本地 DLL 引用 `DLL/Aliyun.OSS.dll`） |
| 其他 | MiniExcel（导入导出）、ThoughtWorks.QRCode（二维码）、UAParser（UA 解析）、IPTools.China |
| 序列化 | System.Text.Json：CamelCase 属性命名策略、DateTime 自定义转换器、StringConverter |

---

## 4. 前端架构（AdminFrontEnd）

### 4.1 启动与脚本（package.json）

```bash
pnpm install        # 安装依赖（pnpm-lock.yaml）
pnpm dev            # 开发环境，端口 9906
pnpm build          # 生产构建
pnpm build:test     # 测试环境构建（--env-mode test）
pnpm preview        # 预览构建产物
pnpm lint           # ESLint + Stylelint
pnpm format         # Prettier 格式化
pnpm type:check     # vue-tsc 类型检查
pnpm check          # lint + format:check
```

### 4.2 环境变量（.env 系列）

| 变量 | 说明 |
| --- | --- |
| `VUE_APP_TITLE` | 站点标题 |
| `VUE_APP_CONFIG_API` | 配置中心/网关接口地址（开发为 test 网关，生产为正式网关） |
| `VUE_APP_STORAGE_ENCRYPT_KEY` | 本地存储加密 key |
| `VUE_APP_IS_MOCK` / `VUE_APP_MOCK_API` | 是否开启 mock（apifox）及地址 |
| `VUE_APP_API_ENCRYPT_KEY` / `VUE_APP_API_ENCRYPT_IV` | 请求参数 DES 加密密钥 |
| `VUE_APP_AUTH_USERNAME` / `VUE_APP_AUTH_PSW` | 登录 OAuth2 HTTP Basic Auth 凭证 |
| `VUE_APP_DROP_CONSOLE` | 打包时是否移除 console |

环境文件：`.env`（通用）、`.env.development`、`.env.production`、`.env.test`。Rsbuild 通过 `config/plugins/plugin_envType` 生成 `types/env.d.ts`。

### 4.3 目录约定

- **api/**：按业务域建目录，每个目录下 `index.ts`（接口定义）+ `model.d.ts`（入参/出参类型，前缀 `API_xxx_P` / `API_xxx_R`）。
- **views/**：与 api 目录对应；页面多用 `useTable` + `useFormModal` hooks + `OmegaTable` 组件快速搭建 CRUD。
- **store/modules/**：Pinia store；`user.ts` 保存登录态/权限/动态路由；`url.ts` 保存接口 URL 字典；持久化通过 `persist` 配置。
- **router/**：静态路由在 `constant.ts`；动态路由由后端菜单通过 `generator-router` 生成。
- **utils/http/**：请求封装核心，**不要随意改动拦截器链路**。
- **enums/**：`menu_enum.ts`（MenuType：目录/菜单/按钮/权限）、`http_enum.ts`（ContentTypeEnum）等。

### 4.4 请求层（重要）

`src/utils/http/request.ts` 提供 `http.request(match, params, options)`：

- `match` 支持两种形式：
  1. 完整 URL（`isUrl` 直接命中，如登录接口）；
  2. **服务方法名** `服务名.方法名`（如 `omegaAdmin.sysDictgetSysDictList`），实际 URL 通过 `useUrlStore().urlList`（URL 字典）解析（`getValueByPath`）。
- 支持 `onFetchBefore`（如登录时追加 Basic Auth 头）、`onFetchResponse`、`onFetchError` 钩子。
- 内置：重复请求合并（AbortApi）、响应缓存（CatchApi）、请求参数 DES 加密（`isEncrypt` 默认 true）、错误提示（`showError` 默认 true）。
- 返回结构 `{ data, error, loading }`；业务成功以 `res.status === 1` 判断。

### 4.5 登录与权限

- 登录：`FETCH_USER.login` → OAuth2 密码模式（jwt-bearer grant_type）+ Basic Auth；获取 `access_token` / `refresh_token`。
- 登录后 `afterLogin()` 拉取菜单（`FETCH_MENU.menus`）→ `setMenuInfo` → `generatorDynamicRouter` 动态注册路由。
- 权限：后端菜单返回权限点，前端以 `v-role` 指令（`directives/v-role`）控制按钮显示。
- token 过期由 `refreshTokenFn` 自动刷新，失败则登出回登录页。

---

## 5. 后端架构（BackEnd）

### 5.1 服务清单与职责

| 服务 | 端口 | Nacos ServiceName | 职责 |
| --- | --- | --- | --- |
| OmegaAdmin | 8003 | omega_admin | 系统管理核心：用户/角色/部门/岗位/菜单/字典/参数/日志/登录/权限；向其他服务提供 Feign 接口 |
| OmegaConfig | - | omega_config | App 版本管理、App 数据源设置、文件/页面更新、底部导航、上报记录、OSS 上传 |
| OmegaGateway | 8000 | omega_gateway | YARP 网关：按 Nacos 服务实例动态生成路由/集群，统一入口 |
| OmegaLogic | - | omega_logic | 逻辑编排：server/test/logic 三类项目与节点、日志记录、Quartz 定时任务 |
| OmegaMake | - | omega_make | 代码/模板生成（MakeTemplate、MakeData、生成分类） |
| OmegaProject | - | omega_project | 项目管理：项目/分组/成员/角色/业务模块/功能模块/API 版本 |
| OmegaRouter | - | omega_router | API 路由注册：API 分组、API 信息，为前端提供 URL 字典（`/v1/router/api/groups`、`/v1/router/api/list`） |
| OmegaSource | - | omega_source | 资源/数据源：数据库信息/表/字段、服务器、脚本、App 项目/模块/页面、环境、中间件、模板 |
| OmegaUpload | - | omega_upload | 文件上传服务 |

### 5.2 通用目录结构与分层约定

每个服务采用一致的目录骨架与「Controller → IService/Service → Repository」分层，命名约定统一（实体 `Sys*`、Dto 以 `XxxDto` 结尾、Vo 以 `XxxVo` 结尾等）。

> 完整服务骨架（App/Attribute/Common/Controllers/Model/Repository/Services/…）、分层细节与命名规范见 [PROJECT_SPEC.md §1.2 / §2.3](./PROJECT_SPEC.md#12-backend后端微服务共-9-个)。

### 5.4 启动配置要点（Program.cs，各服务一致）

- Nacos 配置中心 + 服务注册（`AddNacosV2Configuration`、`AddNacosAspNet`），ServiceName/端口在 appsettings 中声明。
- MVC 全局过滤器：`GlobalActionMonitor`（操作监控/日志）、`AuthorizationFilter`（JWT 鉴权）。
- JSON：CamelCase 属性命名策略 + DateTime 转换器 + StringConverter（空字符串处理）。
- SummerBoot 注册：`AddSummerBoot()`、`AddSummerBootFeign()`。
- Redis 按 `RedisServer:open == "1"` 初始化。
- Kestrel 请求体上限 100MB；`ThreadPool.SetMinThreads(200, 200)`。
- DB 初始化：`AddDb(app.Environment)`（SqlSugar 多数据源 `omega_admin`，`InitDb` 且仅 Development 时建表）。

### 5.5 数据库（SqlSugar）

- 实体用 SqlSugar 特性建模（SugarTable/SugarColumn），`SysBase` 提供公共字段（CreateBy/UpdateBy/DelFlag 等）。
- 多数据源按 `OptionsSetting.DbConfigs` 配置，ConfigId 区分库。
- **数据权限**：`DataPermi.FilterData` 在查询时按用户部门自动过滤。
- **软删除**：`DelFlag` 字段约定（"0" 正常 / "1" 删除）。
- SQL 日志分级写入 NLog，便于排查慢查询/异常 SQL。

### 5.6 网关（OmegaGateway）

- 基于 YARP + Nacos 动态路由：`RefreshYarp` 后台服务每 60s 从 Nacos 拉取各服务健康实例，`provider.Update(routes, clusters)` 实时生效。
- 服务路径在 Nacos 配置 `OptionsSetting.Services`（Name + Path）中声明，网关按路径前缀将请求转发到对应微服务。
- 是前端 `VUE_APP_CONFIG_API` 的统一入口。

---

## 6. 前后端接口调用约定（重要）

1. 后端每个服务在 Nacos 注册（ServiceName + 服务路径）。
2. **OmegaRouter** 服务维护 API 分组与 API 信息（`ApiGroupController` / `ApiInfoController`），对外提供 URL 字典接口（`/v1/router/api/groups`、`/v1/router/api/list`），键格式为 `服务名.方法名`（如 `omegaAdmin.sysDictgetSysDictList`），值为 `{ url, method, name }`。
3. 前端首次启动通过 `useUrlStore().updateUrl()` 拉取 URL 字典并持久化。
4. 前端请求一律使用 `http.request('服务名.方法名', params)`，由 URL 字典解析出真实网关地址再发起请求；网关按路径转发到对应微服务。

**新增/修改接口时的要求：**

- 后端新增 Controller 方法 → 同步在 OmegaRouter 的 API 信息中注册 `服务名.方法名`。
- 前端 api 目录新增方法时，`match` 字符串必须与 OmegaRouter 注册的 key 一致，否则报「url 为空」。

---

## 7. 环境与配置

### 7.1 前端

- dev 端口 9906（rsbuild.config.ts）；如需本地代理可启用 `config/proxy.ts`（默认注释）。
- 网关地址：开发 `https://test-omega-gateway.kexiaoshuang.com`、生产 `https://omega-gateway.kexiaoshuang.com`（.env 文件配置）。

### 7.2 后端

- Nacos 配置中心 DataId：`omega`（Group：DEFAULT）；包含数据库、Redis、OSS、服务路由等业务配置。
- 每个服务 appsettings.json 仅保留 Logging/NacosConfig 等基础项，业务配置从 Nacos 动态获取（`App.OptionsSetting`）。
- 环境配置文件：`appsettings.Development.json`、`appsettings.Test.json`、`appsettings.Production.json` 等。

### 7.3 CI/CD

- 各服务与前端均有 `.drone.yml`（Drone CI）：`.NET SDK 7.0` 构建 → Docker 镜像（Harbor `harbor.kexiaoshuang.com`）→ 部署脚本触发 k8s 部署。
- 触发分支：`develop`（测试环境）；`build:test` 构建测试前端。

---

## 8. 开发规范与注意事项

前端（复用 hooks/OmegaTable、`model.d.ts` 类型约定、提交前 lint/type:check、`VUE_APP_` 前缀、勿改 http 拦截器）与后端（分层、权限、密码存储、数据权限、软删除、异常处理、操作日志）的完整规范统一维护在 [PROJECT_SPEC.md §2](./PROJECT_SPEC.md#2-编码规范)，此处不再重复。

---

## 9. 常见任务速查

| 任务 | 步骤 |
| --- | --- |
| 新增一个管理端 CRUD | 后端：实体 `Model/Base` → Dto/Vo → Service(+IService) → Controller(Admin) → 注册到 OmegaRouter；前端：`api/<域>/` 增加接口 → `views/<域>/` 新建页面（useTable + useFormModal）→ 在菜单中挂载 |
| 排查接口「url 为空」 | 检查 `match` 的 `服务名.方法名` 是否已在 OmegaRouter 注册、URL 字典是否已刷新（`useUrlStore().updateUrl()`） |
| 排查请求被加密 | 请求参数默认 DES 加密（`VUE_APP_API_ENCRYPT_KEY/IV`），调试时可在请求 options 传 `isEncrypt: false` |
| 新增环境变量 | 修改对应 `.env.*` 文件 → 重启 dev/build（会重新生成 types/env.d.ts） |
| 本地起后端 | 保证可访问 Nacos（appsettings 的 ServerAddresses），启动对应服务 Program.cs 即可，业务配置从 Nacos 拉取 |
| 部署 | 推送对应分支触发 Drone CI（`.drone.yml`），自动构建镜像并部署 |