SunAdmin 开发文档

主题

✅ 开发检查清单 ​

📌 新增后端接口 ​

  • 确认接口属于 Admin 还是 Api。
  • 控制器放入正确目录。
  • 使用正确路由注解：Get/Post/OpenGet/OpenPost。
  • Api 普通 Get/Post 默认必须登录；公开接口必须使用 OpenGet / OpenPost。
  • 允许游客访问但需要识别登录态时，使用 OpenGet/OpenPost + api.try-auth。
  • 编写 FormRequest 校验字段。
  • 复杂业务放 Action / Service。
  • 数据查询放 Dao。
  • 返回 success()，业务错误返回明确 code/message。
  • 同步前端 API 文件。
  • 运行 php artisan route:list --path=... 检查接口是否已被路由系统识别。

🖱️ 新增后台页面 ​

  • 页面放 frontend/admin/src/views/{Module}。
  • API 封装放 src/views/{Module}/api。
  • 可安装模块先放入 modules/{Module}/Resources/admin，再通过安装器发布。
  • 菜单初始数据增加页面记录。
  • component 与真实页面路径一致。
  • 按钮权限写入菜单或权限表。
  • 页面中处理空数据、加载中、保存后刷新。
  • 执行 npm run type-check 和 npm run build。

📡 新增 uni-app 页面 ​

  • 页面放 src/pages/{module}。
  • 使用 <script lang="ts" setup>。
  • 更新 src/pages.json，页面项包含 path 和稳定 name。
  • 允许游客访问时声明 guest: true；未声明时默认需要登录。
  • 可安装模块的页面片段写入 Resources/publish-manifest.json，优先使用 subPackages。
  • 跳转使用 toRouter()。
  • API 按模块放置。
  • H5、小程序至少各构建一次。

🧩 新增可安装模块 ​

  • 新增 modules/{Module}/module.json，声明 slug、dependencies、resources。
  • 数据表放入模块自己的 Database/Migrations。
  • 菜单、权限、默认配置放入模块 Seeder 或安装器。
  • admin、uni-app 源码放入 Resources，不要直接长期写死在主工程。
  • 在 Resources/publish-manifest.json 中声明文件发布、admin 链接、uni-app 页面片段。
  • 需要生产环境安装后直接加载 Admin 页面时，执行 php artisan module:build-runtime {Module} 生成运行包；批量构建可用 php artisan module:build-runtime --all。
  • 执行 php artisan module:install {Module} 验证模块迁移、Seeder、资源发布和启用状态。
  • 需要覆盖已发布资源时，执行 php artisan module:install {Module} --force。
  • 验证 php artisan module:enable {Module} 与 php artisan module:disable {Module} 只切换启用状态，不删除业务数据。
  • 执行 php artisan route:list --path=adminapi/{slug} 和 --path=api/{slug} 验证后台接口、用户端接口是否已注册。
  • 卸载会删除模块安装记录并保留业务数据，只有确认可删除数据时才使用 --drop-data。
  • 删除模块文件前必须先卸载模块。

🛠️ 新增配置项 ​

  • 确认配置属于 .env、config/sunadmin.php 还是后台配置表。
  • 后台配置表字段设置正确 type。
  • 需要前端读取时确认公开配置接口返回。
  • 保存后清理缓存或 bump 版本。
  • 文档同步到配置索引。

📖 新增字典 ​

  • 定义稳定 type_key。
  • 增加字典类型和字典项。
  • 前端通过接口读取，不写死文案。
  • 修改字典后清理对应缓存。
  • 确认历史数据是否引用旧 value。

💳 新增支付业务 ​

  • 业务订单先创建。
  • 调用 PayOrderService 创建统一支付单。
  • module/scene/biz_type/biz_no 语义明确。
  • 实现 PayBusinessHandlerInterface。
  • 注册到 pay.biz_handlers。
  • 回调处理幂等。
  • 测试重复回调和异常回滚。

💾 新增上传场景 ​

  • 确认 type 是否已有。
  • 如需新 type，同步 config/sunadmin.php 上传配置。
  • 前端传入正确 type/module/tag。
  • 后端保存业务字段时不要手动截 URL。
  • 本地存储确认 storage:link。
  • 云存储确认 domain 和密钥配置完整。