# PROJECT_SPEC.md — 项目规格说明书

本文档与 [AGENTS.md](./AGENTS.md) 配合使用：

- **AGENTS.md**：项目背景、技术栈、架构说明、接口调用约定、环境与部署。
- **PROJECT_SPEC.md（本文档）**：**完整项目目录结构** 与 **编码规范**。

> 目录结构、编码规范类内容统一维护在本文件中，AGENTS.md 只保留指针，避免重复。

---

## 1. 完整项目目录结构

### 1.1 AdminFrontEnd（后台管理系统前端）

```
AdminFrontEnd/
├── .vscode/                      # 编辑器配置（含 MCP 配置 mcp.json）
├── .github/                      # GitHub 相关
├── config/
│   └── plugins/
│       └── index.ts              # Rsbuild 插件：envType 注入、类型生成
├── public/                       # 公共静态资源
├── src/
│   ├── main.ts                   # 应用入口
│   ├── App.vue                   # 根组件
│   ├── api/                      # ★ 接口层（按业务域分目录）
│   │   ├── app-manage/           #   应用管理
│   │   ├── auths/                #   认证授权
│   │   │   ├── user/             #     用户（index.ts + model.d.ts）
│   │   │   ├── role/             #     角色
│   │   │   ├── dept/             #     部门
│   │   │   ├── menu/             #     菜单（含 menu-tree.json、icon-migration.ts）
│   │   │   └── post/             #     岗位
│   │   ├── database/             #   数据库（manage）
│   │   ├── interface/            #   接口（manage）
│   │   ├── market/               #   市场（modal）
│   │   ├── project/              #   项目
│   │   ├── resource/             #   资源
│   │   ├── system/               #   系统（字典/参数/日志）
│   │   ├── workflow/             #   工作流
│   │   └── typings.d.ts          #   公共接口类型
│   ├── assets/                   # 静态资源
│   │   ├── svg/                  #   图标（logo/theme/系统图标…）
│   │   ├── images/               #   图片（bg/logo）
│   │   ├── analysis.svg
│   │   └── 404.gif
│   ├── components/
│   │   └── common/               # ★ 通用组件（Omega 系列）
│   │       ├── echarts/          #   Echarts 封装（Echarts.vue、echats-config.ts）
│   │       ├── help-info/
│   │       ├── lock-page/        #   锁屏组件
│   │       ├── omega-code-editor/   # CodeMirror 代码编辑器
│   │       ├── omega-code-preview/  # 代码预览
│   │       ├── omega-form/       #   动态表单（types/utils/hooks/components/form-item）
│   │       ├── omega-list/       #   列表
│   │       ├── omega-page/       #   页面容器
│   │       ├── omega-section/    #   区块容器
│   │       ├── omega-table/      #   ★ 动态表格（types/hooks/components/table-settings）
│   │       ├── omega-toolbar/    #   工具栏
│   │       ├── omega-upload/     #   上传
│   │       ├── svg-icon/         #   SVG 图标
│   │       ├── vertify/          #   验证码
│   │       └── dia-text-reveal/  #   文本动画
│   ├── directives/
│   │   ├── index.ts
│   │   └── v-role/index.ts       # ★ 按钮级权限指令
│   ├── enums/
│   │   ├── index.ts
│   │   ├── breakpoint_enum.ts
│   │   ├── http_enum.ts          #   ContentTypeEnum
│   │   ├── menu_enum.ts          #   MenuType
│   │   ├── role_enum.ts
│   │   └── size_enum.ts
│   ├── hooks/                    # ★ 组合式函数
│   │   ├── event/                #   useEventListener/useBreakpoint/useScroll/useScrollTo/
│   │   │                         #   useWindowSizeFn/useIntersectionObserver
│   │   ├── useForm.tsx           #   动态表单 hook
│   │   ├── useFormModal.tsx      #   表单弹窗 hook
│   │   ├── useTable.tsx          #   表格 hook
│   │   ├── useLoad.ts / useOnline.ts / useTime.ts / useTiming.ts
│   │   └── ...
│   ├── layout/                   # ★ 布局
│   │   ├── index.vue
│   │   ├── content/
│   │   ├── header/               #   顶栏（components: setting/lock-screen/fullscreen/
│   │   │                         #   breadcrumb/lightOrDark/user/search）
│   │   ├── logo/
│   │   ├── menu/                 #   菜单（components: menu-item/menu-item-content）
│   │   └── tabs/                 #   标签页（components: Tabs/ChromeTabBg）
│   ├── lib/
│   │   └── json-render/          # ★ JSON 动态渲染引擎
│   │       ├── component/JsonRenderDevtools/   # 渲染调试工具
│   │       ├── element-plus-docs/*.md          # Element Plus 组件文档索引
│   │       ├── example/crud.spec.ts            # CRUD 示例 spec
│   │       ├── catalog.ts / components.catalog.ts / element-plus.catalog.ts
│   │       ├── registry.ts / spec.ts / render-spec.ts / vue-sfc.ts / actions.ts
│   │       ├── use-fetch-ai.ts
│   │       └── api-tree.json / test.openapi.json
│   ├── plugins/                  # 插件注册
│   │   ├── index.ts
│   │   ├── assets.ts             #   svg 自动注册
│   │   ├── customComponents.ts   #   自定义组件注册
│   │   ├── directives.ts
│   │   └── globalMethods.ts      #   全局方法
│   ├── router/
│   │   ├── index.ts              # 路由实例
│   │   ├── constant.ts           # 常量
│   │   ├── modules/
│   │   │   ├── staticModules/index.ts     # 静态路由
│   │   │   ├── asyncModules/index.ts      # 异步路由（动态生成）
│   │   │   └── externalModules/           # 外部路由（error/redirect/outside）
│   │   └── utils/generator-router.tsx     # ★ 由后端菜单生成动态路由
│   ├── store/                    # ★ Pinia
│   │   └── modules/
│   │       ├── user.ts           #   登录态/权限/菜单
│   │       ├── url.ts            #   ★ 接口 URL 字典
│   │       ├── tabsView.ts       #   标签页
│   │       ├── keepAlive.ts      #   页面缓存
│   │       ├── lockscreen.ts     #   锁屏
│   │       └── layoutSetting.ts  #   布局设置
│   ├── styles/                   # 全局样式（theme/transition/tailwind）
│   ├── theme/                    # 主题
│   ├── utils/
│   │   ├── http/                 # ★ 请求封装（勿随意改动）
│   │   │   ├── request.ts        #   入口：http.request(match, params, options)
│   │   │   ├── type.ts           #   类型与 paramsHelper
│   │   │   └── utils/
│   │   │       ├── fetch.ts      #   底层 fetch 封装
│   │   │       ├── getUrl.ts     #   URL 解析
│   │   │       ├── encrypt.ts    #   DES 加密
│   │   │       ├── abortController.ts  # 重复请求合并
│   │   │       ├── responseCache.ts    # 响应缓存
│   │   │       ├── status.ts     #   状态码
│   │   │       └── logPrint.ts
│   │   ├── permission/           #   权限（access/role/utils）
│   │   ├── rules/                #   表单校验（index/validate）
│   │   ├── file/                 #   文件（download/translate）
│   │   └── *.ts                  #   clone/copy/dateUtil/is/polling/toExcel/tsxHelper/
│   │                             #   upload/url/checkUpdate/index
│   └── views/                    # ★ 页面（与 api 业务域对应）
│       ├── account/settings.vue
│       ├── dashboard/
│       │   ├── welcome/
│       │   ├── demo/             #   组件示例（form/modal/table/COMPONENTS.md）
│       │   └── workflow-demo/    #   流程图示例
│       ├── database/
│       │   ├── manage/
│       │   └── manage-details/
│       ├── error/404.vue
│       ├── interface/manage/
│       ├── login/                #   index.vue + LoginForm.vue
│       ├── market/modal/
│       ├── permission/           #   user/dept/menu/post/role
│       ├── project/
│       │   ├── manage/
│       │   └── manage-details/   #   含 config-pane/*、app-page-config/*、components/*
│       ├── resource/             #   application-config/data-config/env-config/middle-config/
│       │                         #   node-config/script-config/server-config/template-config
│       └── system/               #   dict/log/params
│           └── <view>/           #   页面标准结构：
│               ├── index.vue     #     页面入口
│               ├── hooks/        #     use_form.ts / use_columns.tsx / use_context.ts
│               └── components/   #     页面私有组件
├── types/                        # 全局类型声明（env.d.ts 由构建生成、global.d.ts、shims-*.d.ts）
├── .drone.yml                    # CI/CD 流水线
├── .env / .env.development / .env.test / .env.production   # 环境变量
├── rsbuild.config.ts             # Rsbuild 构建配置（dev 端口 9906）
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json / tsconfig.app.json / tsconfig.node.json
├── eslint.config.mjs
├── prettier.config.mjs
└── stylelint.config.mjs
```

### 1.2 BackEnd（后端微服务，共 9 个）

#### 通用服务骨架（9 个服务均包含，结构一致）

```
<Service>/
├── App/                          # App.cs（OptionsSetting 静态入口）、InternalApp.cs（SP/IConfig）
├── Attribute/                    # AppServiceAttribute（自动注册）、LogAttribute（操作日志）
├── Base/                         # AppSettings、GlobalConstant
├── Common/                       # Function、JwtUtil、Tools、dbconn、JsonConverterUtil、
│                                 # StringConverter、Cache/（RedisServer、CacheHelper）
├── Constant/                     # HttpStatus、Helper/DateTimeHelper
├── Controllers/
│   ├── Admin/                    # 管理端接口（供后台管理系统调用）
│   ├── Client/                   # 客户端/开放接口
│   ├── Base/                     # BaseController、HomeController（部分服务）
│   └── Feign/                    # 服务间调用接口（部分服务）
├── Extensions/                   # Extension.{Convert,Enum,Linq,Validate,Exception}、StringExtension、
│                                 # RequestLimitExtension、IPRateExtension、HttpContextExtension、
│                                 # EntityExtension、AppServiceExtensions
├── Filters/                      # GlobalActionMonitor、AuthorizationFilter、ActionPermissionFilter、VerifyAttribute
├── Middleware/                   # GlobalExceptionMiddleware（全局异常）
├── Model/
│   ├── Base/                     # 实体（Sys*）、ApiResult、PagerInfo、PagedInfo、TokenModel、UserConstants、OptionsSetting
│   ├── Database/                 # ★ 数据库实体（SugarTable）
│   ├── Dto/                      # 请求入参（*Dto，含 Base/Admin/Client 子目录）
│   ├── Enums/                    # BusinessType、MenuStatus、MenuType、StoreType、ProteryConstant
│   ├── Exception/                # CustomException、ResultCode
│   ├── Vo/                       # 响应出参（*Vo，含 Admin/Client/Base 子目录）
│   └── (Custom/Source/Project/…) # 各服务特有模型
├── Repository/                   # BaseRepository、IBaseRepository
├── Services/
│   ├── Base/                     # BaseService、CacheService（+ IService/）
│   └── <Domain>Service.cs        # 业务服务（+ IService/ 接口，同目录）
├── SqlSugar/                     # SqlsugarSetup（AddDb）、DataPermi、DataPermiSevice、InitTable、SqlSugarCache
├── Task/Quartz/                  # MyJob、StartJob（部分服务）
├── Util/                         # PublicFunction、Utils、RefreshService 等（部分服务）
├── Feign/                        # 服务间 Feign 定义（部分服务）
├── Program.cs                    # 启动配置
├── appsettings*.json             # 环境配置（含 NacosConfig）
├── GlobalUsing.cs
└── <Service>.csproj
```

#### OmegaAdmin（系统管理 / 权限核心，端口 8003，Nacos: omega_admin）

```
Controllers/
├── Base/        # HomeController、BaseController、SysLoginController、SysUserController、SysDeptController、
│                # SysPostController、SysRoleController、SysMenuController、SysUserRoleController
├── Admin/       # SysDictController、SysDictItemController、SysPublicParamController、SysLogController
└── Feign/       # SysMenuController、VsCodeController
Services/
├── Base/        # SysLoginService、SysUserService、SysDeptService、SysPostService、SysRoleService、SysMenuService、
│                # SysUserRoleService、SysUserPostService、SysRoleMenuService、SysPermissionService、
│                # SysOauthClientDetailsService（+ IService/）
└── (Admin)      # SysDictService、SysDictItemService、SysPublicParamService、SysLogService（+ IService/）
Model/Database/  # SysUser、SysRole、SysMenu、SysDept、SysPost、SysDict、SysDictItem、
                 # SysPublicParam、SysLog、SysUserRole、SysUserPost、SysRoleMenu、SysOauthClientDetails 等
DLL/             # 本地引用的第三方 DLL
```

#### OmegaConfig（App 配置 / 版本 / 更新，Nacos: omega_config）

```
Controllers/
├── Admin/       # AppSourceSetController、AppSourceVersionController
├── Client/      # AppController、OssController
├── Base/        # HomeController、BaseController
└── (根目录)     # AppVersionController、AppBottomNavsController、AppReportRecordController、
                 # FileUpdateInfoController、PageUpdateInfoController
Services/
├── Base/        # OssService（+ IService/）
├── Client/      # FileUpdateInfoService、PageUpdateInfoService、AppBottomNavsService（+ IService/）
└── (根目录)     # AppVersionService、AppSourceSetService、AppSourceVersionService、
                 # AppReportRecordService、FileUpdateInfoService、PageUpdateInfoService、AppBottomNavsService（+ IService/）
Model/Database/  # AppVersion、AppSourceSet、AppSourceVersion、AppBottomNavs、AppReportRecord、
                 # FileUpdateInfo、PageUpdateInfo 等
```

#### OmegaGateway（YARP API 网关，端口 8000，Nacos: omega_gateway）

```
├── Program.cs              # YARP + Nacos 启动
├── Util/
│   ├── RefreshYarp.cs      # ★ 60s 轮询 Nacos 服务实例，动态刷新 routes/clusters
│   └── Utils.cs / PublicFunction.cs
├── Common/                 # Function、CacheHelper 等
└── appsettings*.json       # 网关配置
```

#### OmegaLogic（逻辑 / 服务 / 测试编排，Nacos: omega_logic）

```
Controllers/
├── Admin/       # LogicProjectController、LogicNodeController、LogicNodeKindController、LogicLogRecordController、
│                # ServerProjectController、ServerNodeController、ServerNodeKindController、ServerLogRecordController、
│                # TestProjectController、TestNodeController、TestNodeKindController、TestLogRecordController
├── Client/      # LogicNodeController
└── Base/        # HomeController、BaseController
Services/        # LogicProject/LogicProjectVersion/LogicProjectVersionNode/LogicNode/LogicNodeKind/
                 # LogicLogRecord/ServerProject/ServerNode/ServerNodeKind/ServerLogRecord/
                 # TestProject/TestNode/TestNodeKind/TestLogRecord +（IService/）
Model/
├── Database/    # LogicProject、LogicProjectVersion、LogicProjectVersionNode、LogicNode、LogicNodeKind、
│                # LogicLogRecord、ServerProject、ServerNode、ServerNodeKind、ServerLogRecord、
│                # TestProject、TestNode、TestNodeKind、TestLogRecord
├── Custom/      # ApiInfo、EdgeList、LogItem
├── Source/      # DatabaseInfo、DatabaseTable、DatabaseField（来自 OmegaSource 的数据模型）
└── Project/     # Project
Util/Logic/      # ★ 各类型节点执行器：LogicNodeHelper、LogicDatabaseNodeHelper、LogicDocNodeHelper、
                 # LogicCacheNodeHelper、LogicBasicNodeHelper、LogicToolNodeHelper、TestApiNodeHelper、
                 # LogicHelper、LogicHelperBak
Feign/           # IProject、ISource
Task/Quartz/     # MyJob、StartJob
```

#### OmegaMake（代码 / 模板生成，Nacos: omega_make）

```
Controllers/
├── Admin/       # MakeTemplateController、MakeTemplateGategoryController、MakeDataController
├── Feign/       # VsCodeController
└── Base/        # HomeController、BaseController
Services/        # MakeTemplate/MakeTemplateGategory/MakeData/Versions/VersionForProject/MakeFiles/FilesForAll（+ IService/）
Model/
├── Database/    # MakeTemplate、MakeTemplateGategory、MakeData、Versions、VersionForProject、MakeFiles、FilesForAll
└── Customer/Source/   # AppProject、AppProjectModule、AppProjectPage、AppProjectVersion、AppProjectParam、
                       # AppProjectStatic、AppProjectBottom、AppProjectPageStyle、AppModule、AppModuleFile、
                       # AppModuleAndroidCode、AppModuleIosCode
Util/MakeApp/    # ★ MakeAppCodePub、MakeAndroidCode、MakeAppleCode、MakeAppCodePub 生成器
Common/          # GitHelper、OssHelper、RabbitMQClient、FileHelper
Task/            # MakeAppHelper、MakeHelper、Quartz/（MyJob、StartJob）
Feign/           # ISource
```

#### OmegaProject（项目管理，Nacos: omega_project）

```
Controllers/Admin/   # ProjectController、ProjectServiceController、ProjectGroupController、ProjectMemberController、
                     # ProjectRoleController、ProjectWorkerController、ProjectBusinessModuleController、
                     # FeatureModuleController、BusinessModuleController、ProjectApiVersionController、DeveloperController
Controllers/Feign/   # VsCodeController
Services/            # Project/ProjectService/ProjectGroup/ProjectMember/ProjectRole/ProjectWorker/
                     # ProjectBusinessModule/FeatureModule/BusinessModule/ProjectApiVersion/Developer（+ IService/）
Model/Database/      # Project、ProjectService、ProjectGroup、ProjectMember、ProjectRole、ProjectWorker、
                     # ProjectBusinessModule、FeatureModule、BusinessModule、ProjectApiVersion、Developer
Common/              # RabbitMQClient
Feign/               # SysDeptFeign
Task/Quartz/         # MyJob、StartJob
```

#### OmegaRouter（API 路由注册 / 前端 URL 字典，Nacos: omega_router）

```
Controllers/
├── Admin/       # ApiGroupController、ApiInfoController
├── Client/      # ApiPubController（对外提供 URL 字典：/v1/router/api/groups、/v1/router/api/list）
└── Base/        # HomeController、BaseController
Services/        # ApiGroupService、ApiInfoService（+ IService/）
Model/
├── Database/    # ApiGroup、ApiInfo
├── Dto/         # ApiGroup*Dto、ApiInfo*Dto、Client/（ApiGroupListDto、ApiListDto、NoticeGroupDto）、Feign/AddMenuFromApiDto
└── Vo/          # ApiGroup*Vo、ApiInfo*Vo、Client/ApiListVo、Sub/ApiGroupVo
Feign/           # IAdmin
```

#### OmegaSource（数据源 / 资源管理，Nacos: omega_source）

```
Controllers/
├── Admin/       # 数据源：DatabaseInfoController、DatabaseTableController、DatabaseFieldController、
│                # DatabaseFieldIndexController、DatabaseFieldTabsController、DatabaseMakeLogController、
│                # DatabaseOperateLogController
│                # 服务器/环境/中间件/应用：ServerController、ServerScriptController、ServerScriptKindController、
│                # ServerScriptLogController、EnvironmentController、MiddlewareController、ApplicationController
│                # App 工程：AppProjectController、AppProjectParamController、AppProjectPageController、
│                # AppProjectPageStyleController、AppProjectBottomController、AppProjectStaticController、
│                # AppProjectVersionController、AppModuleController、AppModuleFileController、
│                # AppModuleAndroidCodeController、AppModuleIosCodeController
│                # API：ApiGroupController、ApiInfoController、ApiInfoParamController、ApiControllerController
│                # 模板：MakeTemplateController、MakeTemplateGategoryController
│                # 后台工程：BackgroundProjectController、BackgroundProjectMenuController、BackgroundProjectMenuPageController
├── Client/      # MakeCodeController
└── Base/        # HomeController、BaseController
Services/        # 与上面对应（+ IService/），另有 ApiControllerService、MakeTemplateService 等
Model/
├── Database/    # DatabaseInfo/Table/Field/FieldIndex/FieldTabs/MakeLog/OperateLog、Server/ServerScript*/…、
│                # Environment、Middleware、Application、AppProject*/AppModule*、ApiGroup/ApiInfo/ApiInfoParam/ApiController、
│                # MakeTemplate*、BackgroundProject*
└── Custom/      # ProjectService、EditTypeFrontend、Versions、Project、MakeData
```

#### OmegaUpload（文件上传，Nacos: omega_upload）

```
Controllers/Client/   # UploadController
Controllers/Base/     # HomeController、BaseController
Services/             # UploadService（+ IService/）
Common/               # OssHelper（阿里云 OSS）、RabbitMQClient
Task/Quartz/          # MyJob、StartJob
```

---

## 2. 编码规范

### 2.1 通用规范

- **代码风格**：前后端均启用 ESLint / Stylelint / Prettier（前端）与 .editorconfig 约定（后端 4 空格缩进）。提交前必须通过 `pnpm lint && pnpm format`（前端）。
- **命名**：统一使用有意义的业务名称，禁止无意义缩写（`a`、`temp1` 等）。
- **注释**：关键逻辑、复杂算法、跨服务调用处必须写清「做什么 / 为什么」；中文注释。
- **禁止**：提交本地环境相关配置（连接串、密钥）、`.env*`、`node_modules/`、`bin/`、`obj/` 等。
- **提交规范**：功能/修复拆分提交；提交信息遵循 `type(scope): 描述`（如 `feat(user): 新增用户列表导出`）。
- **复用优先**：新增功能前先搜索现有工具/组件/hook/服务，避免重复实现。

### 2.2 前端编码规范（AdminFrontEnd）

**语言与框架**

- TypeScript 严格模式；优先 `Composition API + <script setup lang="ts">`。
- 组件命名 PascalCase；普通工具文件、目录使用 **kebab-case**（如 `use_form.ts`、`manage-details`）。
- 业务页面代码中**禁用 any**（必要时用具体类型或 `unknown` + 类型守卫）。

**目录与页面结构（强制约定）**

- 页面统一组织为（见 `src/views/system/dict` 示例）：
  ```
  views/<业务域>/<页面>/
  ├── index.vue            # 页面入口
  ├── hooks/
  │   ├── use_form.ts      # 表单 schema（OmegaForm 的 items）
  │   ├── use_columns.tsx  # 表格列定义（OmegaTable 的 columns）
  │   └── use_context.ts   # 页面上下文（跨组件共享状态）
  └── components/          # 页面私有组件
  ```
- 新增 CRUD 页面**必须**优先复用 `useTable` + `useFormModal` + `OmegaTable` / `OmegaForm`，不要从零手写表格/表单。

**接口层（api/）规范**

- 每个业务域一个目录：`index.ts`（接口定义）+ `model.d.ts`（类型）。
- 类型命名：入参 `API_<域>_P.*`（P = Params），出参 `API_<域>_R.*`（R = Result）；公共类型放 `src/api/typings.d.ts`。
- 接口方法统一 `http.request('<服务名>.<方法名>', params, options)`（match 与 OmegaRouter 注册 key 必须一致）。
- 服务名前缀：`omegaAdmin.` / `omegaConfig.` / `omegaRouter.` 等（小驼峰服务名.方法名）。
- 列表接口入参固定含 `pageNum`/`pageSize`，与 `useTable` 配合；新增/修改分别用 `*Add` / `*Update` 语义接口。

**状态与存储**

- 全局状态用 Pinia（`src/store/modules/`）；持久化通过 `persist` 配置（zipson + secure-ls），敏感数据走加密存储。
- 业务页面内部状态优先本地 ref / `use_context`，不要滥用全局 store。

**请求层红线**

- `src/utils/http/` 为请求链路核心，**未经确认不得改动** request.ts 的拦截逻辑、加密逻辑（`isEncrypt`）、合并/缓存机制。
- 请求参数默认 DES 加密；临时调试可传 `isEncrypt: false`，但不得提交到正式代码。

**权限**

- 按钮/操作权限统一用 `v-role` 指令（`directives/v-role`），权限点字符串与后端 `[ActionPermissionFilter(Permission=...)]` 一致。
- 页面路由权限由后端菜单动态下发，前端 `generator-router.tsx` 自动生成，不要在前端硬编码业务路由。

**样式**

- 优先 Tailwind 原子类；复杂样式用 `<style scoped lang="scss">`。
- 主题变量走 `src/theme/`，禁止页面写死颜色值。

**构建 / 规范校验**

- 新增环境变量必须以 `VUE_APP_` 前缀，修改 `.env.*` 后需重启 dev/build（自动重新生成 `types/env.d.ts`）。
- 提交前必跑：`pnpm lint`、`pnpm format`、`pnpm type:check`。

### 2.3 后端编码规范（BackEnd）

**分层与职责（强制约定）**

```
Controller（入参校验/鉴权） → IService/Service（业务逻辑） → Repository/BaseService（SqlSugar 数据访问）
```

- Controller 只做参数接收与返回，**不写业务逻辑**；业务一律下沉 Service。
- 每个 Service 对应一个接口 `IService/I<Name>Service.cs` 与实现 `<Name>Service.cs`，放同一目录。
- Service 类标注 `[AppService]`（AppServiceAttribute）由 SummerBoot 自动注册；通过构造函数注入依赖。

**命名规范**

- 数据库实体：`Model/Database/` 下，表名 `Sys*` 或业务名（如 `ServerProject`），用 SqlSugar `[SugarTable/SugarColumn]` 建模；公共字段继承 `SysBase`（CreateBy/UpdateBy/DelFlag 等）。
- 入参 DTO：`XxxDto`；出参 VO：`XxxVo`。
- 列表：`Get<Xxx>QueryVo`（查询入参）、`Get<Xxx>ListVo`（列表出参）；新增/更新：`Add<Xxx>Vo` / `Update<Xxx>Vo`（对应 `AddXxxDto`）。
- Controller 路由：优先**特性路由** `[HttpXxx("/v1/<admin|client|feign>/<模块>/<资源>/<动作>")]`，动作用 REST 语义（`page/list/get/add/update/remove`）。

**Controller 规范**

- 继承 `BaseController`；成功返回 `SUCCESS(data)`，失败返回 `ApiResult.Error(code, msg)` 或抛 `CustomException`。
- 需要登录的 Controller 类标注 `[Verify]`；方法级权限用 `[ActionPermissionFilter(Permission = "system:user:query")]`（权限点格式 `模块:资源:动作`）。
- 内部 Feign 接口：`[AllowAnonymous]` + 路由以 `/v1/feign/` 开头，放 `Controllers/Feign/` 或 `Feign/` 目录。
- 需记录操作日志的方法加 `[Log]`（配合 `BusinessType` 枚举）。
- 用户信息统一从 `JwtUtil.GetLoginUser(HttpContext)` 获取；写操作必须填充 CreateBy/UpdateBy。

**数据访问（SqlSugar）**

- 一律使用 `Queryable()` / 表达式查询，**禁止拼接原生 SQL**（防注入）。
- 查询用表达式 & `DataPermi.FilterData` 做数据权限过滤。
- 软删除约定：`DelFlag`（"0" 正常 / "1" 删除）；所有列表查询默认过滤 `DelFlag = "0"`。
- 多数据源：通过 `OptionsSetting.DbConfigs` 配置，`ConfigId` 区分；实体归属对应库。
- 复杂查询结果用 Mapster `Adapt<>` 映射到 Vo。

**安全与异常**

- 密码存储：`Function.MD532(明文 + salt)`，salt 随机 6 位，禁止明文入库。
- 全局异常由 `GlobalExceptionMiddleware` 统一处理；业务错误抛 `CustomException`（ResultCode）返回统一格式。
- 对外接口必须做参数校验（DataAnnotations / 手写校验），数据库异常不直接暴露给前端。

**配置与启动**

- 业务配置（DB/Redis/OSS/路由）一律放 Nacos（DataId `omega`），通过 `App.OptionsSetting` 读取；**禁止把业务连接串写死在 appsettings 提交**。
- appsettings 仅保留 Logging、NacosConfig 等基础项；环境相关用 `appsettings.{Environment}.json`。
- JSON 统一 camelCase（后端已配置全局），新增模型无需重复配置。

**数据库脚本与迁移**

- 结构变更：新增/修改 `Model/Database/` 实体即可（Development 环境 `InitTable` 自动建表）；生产环境变更须走数据库迁移脚本，不依赖自动建表。

**代码风格（以 `BackEnd/.editorconfig` 为准）**

- 所有后端微服务共用 `BackEnd/.editorconfig` 固化格式规则，**后期新增/修改代码按此规范**，提交前可执行 `dotnet format` 校验。
- 缩进：4 空格（不用 Tab）；换行：LF；文件末尾保留换行；行尾不留空白。
- 大括号：Allman 风格（左大括号独占一行）；`else`/`catch`/`finally` 换行。
- using：System 优先、按字母序分组排序，`dotnet format` 自动处理（`dotnet_sort_system_directives_first`、`dotnet_separate_import_directive_groups`）。
- 命名：类/方法 PascalCase，局部变量/参数 camelCase，常量 UPPER_CASE 或按现有 `Constant/` 约定；**不强制自动重命名**（IDE1006 关闭）。
- 命名空间保持 block-scoped（IDE0161 关闭），不自动改为 file-scoped。
- 异步方法以 `Async` 结尾，避免同步阻塞（`.Result`/`.Wait()`）；长方法拆小。
- 统一在 `GlobalUsing.cs` 维护全局 using，单个文件头部不堆叠 using。

执行格式统一（在仓库根目录）：

```bash
dotnet format BackEnd/OmegaAdmin/OmegaAdmin.csproj whitespace --include "BackEnd/OmegaAdmin/Controllers/**/*.cs" "BackEnd/OmegaAdmin/Services/**/*.cs" "BackEnd/OmegaAdmin/Model/**/*.cs"
dotnet format BackEnd/OmegaAdmin/OmegaAdmin.csproj style --include "BackEnd/OmegaAdmin/Controllers/**/*.cs" "BackEnd/OmegaAdmin/Services/**/*.cs" "BackEnd/OmegaAdmin/Model/**/*.cs"
```

**新建文件参考模板（以 `samples/` 目录为准）**

新增 Controller / Service / IService / 实体 / Dto / Vo 时，直接参照 `samples/` 下的模板编写（示例实体为 `Project`，替换为实际业务实体名即可）：

| 新建文件 | 参考模板 | 模板要点 |
| --- | --- | --- |
| Controller | [samples/SampleController.cs](./samples/SampleController.cs) | 继承 `BaseController`；私有只读 `I<Name>Service _<Name>Service`（构造函数注入）；返回统一用 `SUCCESS(data)`；标准五个动作：`get<Name>List`(GET+分页)、`get<Name>Query`(GET+详情)、`add<Name>`(POST)、`update<Name>`(PUT)、`delete<Name>/{id}`(DELETE)；路由 `/v1/<服务名>/<实体>/<动作>` |
| Service | [samples/SampleService.cs](./samples/SampleService.cs) | 标注 `[AppService(ServiceType = typeof(I<Name>Service), ServiceLifetime = LifeTime.Transient)]`；继承 `BaseService<T>` 并实现 `I<Name>Service`；查询条件用 `Expressionable.Create<T>()` + `AndIF` 拼接；列表用 `Queryable().Where(...).OrderByDescending(...).ToPage<T, <Xxx>ListVo>(page)` 分页 |
| IService | [samples/ISampleService.cs](./samples/ISampleService.cs) | 继承 `IBaseService<T>`；每个业务方法声明 XML 注释（`<summary>` / `<param>` / `<returns>`） |
| Model 实体 | [samples/Sample.cs](./samples/Sample.cs) | `[SugarTable("表名","说明")]` + `[Tenant("0")]`；主键 `[SugarColumn(..., IsPrimaryKey = true, IsIdentity = true, ColumnName = "id")]`；每个字段配 `/// <summary>` 注释与 `SugarColumn(ColumnDescription/Length/ColumnName)`；公共字段（delFlag/createTime/updateTime/createBy/updateBy 等）按模板统一命名 |
| Dto | [samples/SampleDto.cs](./samples/SampleDto.cs) | 命名 `Add<Name>Dto` / `Update<Name>Dto` / `Get<Name>QueryDto`；放 `Dto.Admin` 等命名空间；属性可空 `string?`、集合 `string[]` 按需 |
| Vo | [samples/SampleVo.cs](./samples/SampleVo.cs) | 命名 `Get<Name>ListVo` 等；放 `Vo.Admin` 等命名空间；属性对应出参字段，配 `<summary>` 注释 |

> 命名规范：实体名替换 `Project` 为业务名（如 `SysDict`），Service/IService 为 `<Name>Service` / `I<Name>Service`，Vo 为 `Get<Name>ListVo`，Dto 为 `Add<Name>Dto` / `Get<Name>QueryDto`。新建后须同步在 OmegaRouter 注册 `服务名.方法名`（见 AGENTS.md §6）。

---

> 提示：目录与规范以实际代码为准。若代码演进导致本文档与仓库不一致，请同步更新本文档（AGENTS.md 仅维护指针）。