Startsida Utforska Hjälp
Registrera dig Logga in
lichunlei
/
OmegaAi
1
0
Fork 0
Filer Ärenden 0 Pull-förfrågningar 0 Wiki
Gren: master
Grenar Taggar
OmegaAi
/
PROJECT_SPEC.md

PROJECT_SPEC.md 33 KB
Permalänk Historik Rå

PROJECT_SPEC.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。

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

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 继承 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 标注 [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 继承 IBaseService<T>；每个业务方法声明 XML 注释（<summary> / <param> / <returns>）
Model 实体 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 命名 Add<Name>Dto / Update<Name>Dto / Get<Name>QueryDto；放 Dto.Admin 等命名空间；属性可空 string?、集合 string[] 按需
Vo 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 仅维护指针）。