PROJECT_SPEC.md 33 KB
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 仅维护指针）。