SunAdmin 开发文档

主题

📐 编码规范清单 ​

🔬 后端 ​

  • 新业务优先放到 modules/{Module}，不要把业务控制器散落到 app/Http。
  • 普通业务模块的安装记录存放在 system_modules；status=1 表示启用，status=0 表示停用；没有记录表示未安装。module.json 只描述模块包信息。
  • module.json.type 只允许 core、business、feature、payment；可复用横向能力使用 feature，后台显示为“功能模块”。
  • 可安装模块的数据表放入模块自己的 Database/Migrations。
  • 可安装模块的菜单、权限、默认配置放入模块 Seeder 或安装器。
  • Admin 控制器放 Http/Controllers/Admin，用户端控制器放 Http/Controllers/Api。
  • Admin 接口默认管理员认证，Api 普通 Get/Post 默认用户认证。
  • 公开接口使用 OpenGet / OpenPost；允许游客访问但需要识别登录态时，使用 api.try-auth。
  • Controller 只做入口、校验、响应；复杂业务放 Action / Service。
  • 列表分页优先走 Dao 的 getList()。
  • 成功响应使用 success()，业务失败抛业务异常或返回明确错误码。
  • 新增异常码时同步更新后端映射、Admin 请求拦截器、uni-app 请求封装和文档。
  • 配置、装修页、语言包缓存优先使用版本号失效。

📝 Admin ​

  • API 文件放在对应模块 src/views/{Module}/api 下。
  • 可安装模块的 Admin 源码先放 modules/{Module}/Resources/admin，由安装器发布到 frontend/admin/src/views/{Module}。
  • 请求 URL 不写 adminapi 前缀。
  • 菜单组件路径必须匹配 src/views 下的真实 .vue 文件。
  • 新增菜单、按钮权限时同步维护后端初始数据。
  • 登录态、菜单、权限刷新走 user store，不在页面里手写路由注册。

🔨 uni-app ​

  • Vue 文件统一使用 <script lang="ts" setup> 与组合式 API。
  • 业务能力通过按需导入 API、组合式函数和 Pinia store 引入。
  • System 公共接口放在 src/apis/system。
  • 新增业务模块页面放 src/pages/{module}。
  • 模块私有 API、组件、Store、类型放 src/modules/{module}。
  • 跨模块复用接口、组件或类型才上提到公共目录。
  • 可安装模块的 uni-app 源码先放 modules/{Module}/Resources/uniapp，由安装器发布到 frontend/uniapp/src。
  • 可安装模块的页面登记写入 Resources/publish-manifest.json，优先使用 subPackages。
  • 新增页面同步更新 src/pages.json，页面项包含稳定 name；页面默认需要登录，允许游客访问时声明 guest: true；业务代码跳转固定页面时使用 toRouter('页面 name')。
  • 小程序 / App 的 VITE_APP_BASE_URL 必须配置完整域名。
  • src/uni_modules 视为第三方插件目录，业务规范检查时排除。