AGENTS.md

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

完整项目目录结构、编码规范统一维护在 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。

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
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）

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。

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. 前后端接口调用约定（重要）

后端每个服务在 Nacos 注册（ServiceName + 服务路径）。
OmegaRouter 服务维护 API 分组与 API 信息（ApiGroupController / ApiInfoController），对外提供 URL 字典接口（/v1/router/api/groups、/v1/router/api/list），键格式为 服务名.方法名（如 omegaAdmin.sysDictgetSysDictList），值为 { url, method, name }。
前端首次启动通过 useUrlStore().updateUrl() 拉取 URL 字典并持久化。
前端请求一律使用 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，此处不再重复。

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`），自动构建镜像并部署

AGENTS.md 13 KB Permalink Riwayat Mentahan