后端业务开发

业务代码放在应用的 server/app，平台实现由 github.com/igwen6w/modu/server 提供。开始新模块时，可参考 starter/server/app/product 的完整商品样板。

bootstrap.Options 装配

server/application/options.go 是应用唯一装配入口：

字段	注册内容
Configure	应用配置覆盖
Routes、Menus	业务 API、菜单与权限声明
Migrations、Seeders	应用表结构与初始化数据
Resources、FakeScenarios	Agent 资源与开发测试场景
Extensions	应用自有扩展声明及惰性注册

应用只追加自己的能力。核心自动提供平台内置扩展，无需复制注册清单。

声明 API 路由

下面是商品样板中列表与创建路由的写法：

func Routes() []sdk.Route {
    c := NewProductController()
    return []sdk.Route{
        {
            Method: "GET",
            Path: "products",
            Permission: "example:product:list",
            Handler: c.Index,
        },
        {
            Method: "POST",
            Path: "products",
            Permission: "example:product:create",
            Handler: c.Store,
        },
    }
}

此代码位于商品 package，导入 github.com/igwen6w/modu/server/sdk。路径相对 /api/v1，实际地址为 /api/v1/products。普通业务路由必须有非空权限，统一继承 JWT、操作日志与权限检查。

装配阶段拒绝核心、应用及扩展之间的路由冲突。不要另开绕过装配的业务入口。

控制器与服务

控制器负责校验输入、获取当前用户和返回统一响应；服务负责查询、事务和业务规则。常用 SDK 包括：

• sdk.CurrentUserID(ctx)：读取已认证的当前用户。
• sdk.Pagination(ctx)：读取 page 与 pageSize。
• sdk.Success、sdk.Error：返回统一响应。
• sdk.VisibleOwnerIDs：获取当前用户可见的记录拥有者集合。

DataScope 需要在业务服务中显式应用。列表筛选、详情、更新、删除和批量操作均应检查范围，不能只过滤列表。

菜单、迁移与资源

通过同一 Options 注册 sdk.Menu、迁移和种子。页面路径遵守父目录前缀，业务权限码与路由声明一致。

Agent 业务通过 sdk.ResourceDescriptor 注册。HTTP 与 Agent 复用同一个业务用例，保持权限、数据范围、字段规则与幂等行为一致。

依赖边界

普通业务依赖 Goravel 公开 contracts、facades 与核心 sdk。应用装配使用 bootstrap，扩展使用公开扩展合同。

不导入核心 app/models、app/services 或 Goravel 内部实现包。缺少必要接口时，在核心定义窄接口并通过新包版本交付，避免业务与核心源码重新耦合。