|
@@ -0,0 +1,534 @@
|
|
|
|
|
+# 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 仅维护指针)。
|