fix🐛: check the certificate before announcing that the port is reachable

AfterListen promises a hook that the port answers. The bind was moved onto the
caller's goroutine to keep that promise, but with ssl enabled there was a second
way to fail after the announcement: ServeTLS reads the certificate files itself,
on the serving goroutine, so a bad path or an unreadable key surfaced once the
hooks had already run.

tls.LoadX509KeyPair now runs before anything is announced, and its error is
returned from startServing the way a failed bind is. ServeTLS still does the
real work - handing it a tls.Listener built here instead would take over the
HTTP/2 negotiation it sets up, and quietly drop h2 for every TLS deployment. The
cost is one extra read of the certificate at startup.

The fatal in the serving goroutine said "listen:". Neither the bind nor the
certificate reaches it any more, so it says "serve:".

The test covers the certificate path alongside the bind: neither may announce
the phase, and neither may seal it.

The counter-proof is not clean, and saying so is the point. Removing the check
does turn the run red, but through log.Fatal killing the process from the
serving goroutine - "fatal serve: open no-such.pem: no such file or directory" -
rather than through the assertion. That still demonstrates the defect, because
the process could only get there after startServing had returned successfully
and the phase had been announced; it cannot be observed from inside the test,
because the fatal races the assertion that would report it.

Also: the redis-backed queue tests now fail instead of skipping when CI is set
and GO_ADMIN_TEST_REDIS_ADDR is not. A workflow that renamed the variable or
dropped the service would otherwise stay green while those two tests quietly did
nothing - the same shape as the defect they exist to cover. Locally, with no CI
in the environment, they still skip.

.github/workflows/go.yml

@@ -15,6 +15,27 @@ jobs:
   build:
     name: Build
     runs-on: ubuntu-latest
+
+    # The queue's ordering rule - consumers registered before the queue is
+    # started - is invisible on the memory backend, which is the default and
+    # therefore what every other test runs on: queue.Memory's Register starts a
+    # consumer goroutine whatever the state. Only redis refuses a late
+    # registration, so without a server here the tests that cover it would skip
+    # and the suite would report success for a queue that accepts no consumers.
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+
+    env:
+      GO_ADMIN_TEST_REDIS_ADDR: 127.0.0.1:6379
+
     steps:
 
     - name: Set up Go 1.26

AGENTS.md

@@ -125,9 +125,12 @@ func (SysPost) TableName() string { return "sys_post" }
 两条与主仓贡献者直接相关的：
 
 - **`common/`、`core/` 不得 import `app/`** —— `make checksilent` 在 CI 里守着，违反即红。
+- **从 core 契约包声明出来的类型必须写成别名**（`type X = pkg.Y`，不是 `type X pkg.Y`）
+  —— `contract-shim-alias` 检查守着。defined type 会丢掉整个方法集，
+  而且**不一定在本仓编译失败**，理由见 `docs/contract.md` 末节。
 - **注册类 API（`AppRouters` / `sdk.Runtime.SetAppRouters` / `migration.ForApp`）
-  只允许在 `init()` 中调用** —— 注册期靠 Go 的包初始化顺序保证无并发写，
-  core 侧的 setter 没有加锁。
+  必须在 `runStartupHooks()` 之前调用完** —— `init()` 是最省事的位置，
+  但约束的是**顺序**，不是写在哪个函数里；晚到的注册会被丢弃并只记一条 ERROR。
 
 ## 路由注册
 
@@ -191,7 +194,8 @@ go run -tags sqlite3 . server  -c config/settings.sqlite.yml
 
 ## 数据库迁移
 
-文件名前 13 位为时间戳版本号。**已执行过的迁移文件不可修改** ——
+文件名前 13 位为毫秒时间戳版本号，不合规的名字会在启动时 panic 并报出该文件名。
+**已执行过的迁移文件不可修改** ——
 `sys_migration` 表按版本号去重，改动不会重跑，只能新增一个迁移来修正。
 
 放哪个目录取决于身份：
@@ -223,7 +227,7 @@ go run -tags sqlite3 . server  -c config/settings.sqlite.yml
 
 ## 静默失败校验
 
-`make checksilent` 检查六类**不报错、不记日志、行为悄悄变得不对**的问题，
+`make checksilent` 检查七类**不报错、不记日志、行为悄悄变得不对**的问题，
 CI 会跑，命中 ERROR 即失败：
 
 | 检查 | 级别 | 静默后果 |
@@ -233,6 +237,7 @@ CI 会跑，命中 ERROR 即失败：
 | `config-value-truncation` | ERROR | `sys_config.config_value` 超 255 字符被静默截断 |
 | `menu-id-collision` | ERROR | 两个模块硬编码同一菜单 ID，互相覆盖 |
 | `contract-import-boundary` | ERROR | 契约包 import `app/`，应用无法独立编译 |
+| `contract-shim-alias` | ERROR | 契约薄壳写成 defined type 而非别名，方法集丢失，本仓可能照常编译、第三方应用编译不过 |
 | `menu-name-mismatch` | WARN | 菜单名与前端组件 `name` 不一致，keep-alive 缓存静默失效 |
 
 最后一条要跨仓库比对，只能做正则启发式，因此是 WARN，**不影响退出码**，

app/admin/apis/sys_user.go

@@ -444,7 +444,6 @@ func (e SysUser) GetInfo(c *gin.Context) {
 		e.Error(500, err, err.Error())
 		return
 	}
-	p := actions.GetPermissionFromContext(c)
 	var roles = make([]string, 1)
 	roles[0] = user.GetRoleName(c)
 	var permissions = make([]string, 1)
@@ -464,7 +463,14 @@ func (e SysUser) GetInfo(c *gin.Context) {
 	}
 	sysUser := models.SysUser{}
 	req.Id = user.GetUserId(c)
-	err = s.Get(&req, p, &sysUser)
+	// Unscoped on purpose: the id is the caller's own, taken from the token.
+	// This used to go through Get with whatever GetPermissionFromContext
+	// returned - and this route installs no PermissionAction, so that was the
+	// zero value. An unset scope is not a recognised one, so once unknown
+	// scopes started failing closed rather than silently matching everything,
+	// every login on a deployment with enabledp: true ended here with a 401
+	// and the browser went straight back to the login page.
+	err = s.GetSelf(&req, &sysUser)
 	if err != nil {
 		e.Error(http.StatusUnauthorized, err, "登录失败")
 		return

app/admin/models/sys_api.go

@@ -23,6 +23,10 @@ type SysApi struct {
 	Path   string `json:"path" gorm:"size:128;comment:地址"`
 	Action string `json:"action" gorm:"size:16;comment:请求类型"`
 	Type   string `json:"type" gorm:"size:16;comment:接口类型"`
+	// AppCode identifies which application's seed.SeedMenus call wrote this
+	// row; empty for the host's own built-in APIs. Same NOT NULL DEFAULT ''
+	// reasoning as SysMenu.AppCode.
+	AppCode string `json:"appCode" gorm:"type:varchar(64);not null;default:'';index:idx_sys_api_app_code;comment:AppCode"`
 	models.ModelTime
 	models.ControlBy
 }

app/admin/models/sys_menu.go

@@ -26,6 +26,12 @@ type SysMenu struct {
 	RoleId     int       `gorm:"-"`
 	Children   []SysMenu `json:"children,omitempty" gorm:"-"`
 	IsSelect   bool      `json:"is_select" gorm:"-"`
+	// AppCode identifies which application's seed.SeedMenus call wrote this
+	// row; empty for the host's own built-in menus. NOT NULL DEFAULT '' for
+	// the same reason sys_migration.app_code is (see contract/models.Migration):
+	// AutoMigrate adding this column to an existing table leaves every
+	// pre-existing row reading back as "" rather than NULL.
+	AppCode string `json:"appCode" gorm:"type:varchar(64);not null;default:'';index:idx_sys_menu_app_code;comment:AppCode"`
 	models.ControlBy
 	models.ModelTime
 }

app/admin/router/sys_api.go

@@ -5,6 +5,7 @@ import (
 	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
 
 	"go-admin/app/admin/apis"
+	"go-admin/common/actions"
 	"go-admin/common/middleware"
 )
 
@@ -15,7 +16,10 @@ func init() {
 // registerSysApiRouter
 func registerSysApiRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
 	api := apis.SysApi{}
-	r := v1.Group("/sys-api").Use(authMiddleware.MiddlewareFunc()).Use(middleware.AuthCheckRole())
+	// PermissionAction is not optional here: all three handlers below read the
+	// data permission out of the context, and without it they read the zero
+	// value - an unset scope, which Permission now fails closed on.
+	r := v1.Group("/sys-api").Use(authMiddleware.MiddlewareFunc()).Use(middleware.AuthCheckRole()).Use(actions.PermissionAction())
 	{
 		r.GET("", api.GetPage)
 		r.GET("/:id", api.Get)

app/admin/service/seed.go

@@ -0,0 +1,308 @@
+package service
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gorm.io/gorm"
+
+	contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/seed"
+
+	"go-admin/app/admin/models"
+)
+
+// adminSeeder is go-admin's own implementation of seed.Seeder: it turns the
+// MenuSpec/ApiSpec values a third-party application asks for into rows
+// across the four tables a visible, working menu entry needs - sys_api,
+// sys_menu, sys_menu_api_rule, and sys_role_menu/casbin_rule - following the
+// same shape cmd/migrate/migration/version/1786700001000_demo_menu.go
+// already hand-writes for the host's own demo module.
+//
+// See go-admin-core's docs/contract.md, "Application-supplied menu and API
+// entries", for the requirements this satisfies, and the security note on
+// seed.Seeder for what this boundary does and does not protect against: an
+// application already holds the same *gorm.DB this receives and could write
+// sys_menu/sys_api/casbin_rule directly, bypassing this entirely.
+type adminSeeder struct{}
+
+func init() {
+	seed.RegisterSeeder(adminSeeder{})
+}
+
+// adminRoleKey is the role every seeded menu is granted to. This mirrors
+// 1786700001000_demo_menu.go's own convention rather than inventing a
+// second one: MenuSpec carries no "which roles should see this" field for a
+// Seeder to consult instead, and admin is the one role guaranteed to exist
+// once the framework's own seed data has run.
+const adminRoleKey = "admin"
+
+// menuSortRange is what sys_menu.sort's column type actually holds.
+//
+// sort is `gorm:"size:4"`, which MySQL builds as a tinyint (-128..127);
+// sqlite ignores the width and accepts anything, so this only ever surfaces
+// on a real install, mid-migration, as Error 1264 - by which point the
+// migration has already run other, non-transactional DDL that will not be
+// retried. tools/checksilent's menu-sort-overflow check catches this for
+// every MenuSpec-shaped literal committed to this repository, but it walks
+// the repository's own source tree: a third-party application living in the
+// module cache is invisible to it. This is the equivalent check for that
+// application, run when its migration actually calls SeedMenus rather than
+// never.
+const (
+	menuSortMin = -128
+	menuSortMax = 127
+)
+
+func (adminSeeder) SeedMenus(tx *gorm.DB, appCode string, menus []seed.MenuSpec, apis []seed.ApiSpec) error {
+	apiRows, err := seedApis(tx, appCode, apis)
+	if err != nil {
+		return fmt.Errorf("seed: app %q: apis: %w", appCode, err)
+	}
+
+	menuIDs, err := seedMenuTree(tx, appCode, menus, apiRows)
+	if err != nil {
+		return fmt.Errorf("seed: app %q: menus: %w", appCode, err)
+	}
+
+	// Not `len(menuIDs) == 0`: grantToAdminRole grants two independent
+	// things, and an application is free to register apis without menus -
+	// endpoints another service calls, or a UI mounted somewhere else.
+	// Skipping the whole call on an empty menu list wrote the sys_api rows
+	// and then no casbin rule for them, so those endpoints were denied to
+	// everyone, admin included, with a migration that reported success.
+	if len(menuIDs) == 0 && len(apiRows) == 0 {
+		return nil
+	}
+	return grantToAdminRole(tx, menuIDs, apiRows)
+}
+
+// seedApis writes one sys_api row per ApiSpec and returns them keyed by
+// ApiSpec.Code, so seedMenuTree can resolve a MenuSpec's ApiCodes into the
+// rows sys_menu_api_rule needs to reference.
+//
+// sys_api.id is left to autoincrement rather than assigned by the caller,
+// unlike 1786700001000_demo_menu.go's hand-picked ids: that migration is
+// the one file tools/checksilent's menu-id-collision check can see, because
+// it lives in this repository; nothing plays that role for a third-party
+// application's ids in the module cache. Never accepting a caller-chosen id
+// here removes the collision this Seeder has no way to detect instead of
+// trying to detect it after the fact.
+func seedApis(tx *gorm.DB, appCode string, apis []seed.ApiSpec) (map[string]models.SysApi, error) {
+	seen := make(map[string]bool, len(apis))
+	rows := make(map[string]models.SysApi, len(apis))
+	for _, a := range apis {
+		if a.Code == "" {
+			return nil, errors.New("ApiSpec.Code must not be empty")
+		}
+		if seen[a.Code] {
+			return nil, fmt.Errorf("duplicate ApiSpec.Code %q", a.Code)
+		}
+		seen[a.Code] = true
+
+		row := models.SysApi{
+			Handle:  a.Handle,
+			Title:   a.Title,
+			Path:    a.Path,
+			Action:  a.Method,
+			Type:    "SYS",
+			AppCode: appCode,
+		}
+		if err := tx.Create(&row).Error; err != nil {
+			return nil, fmt.Errorf("api %q: %w", a.Code, err)
+		}
+		rows[a.Code] = row
+	}
+	return rows, nil
+}
+
+// seedMenuTree writes one sys_menu row per MenuSpec, resolving Parent/Code
+// references into parent_id/paths, and returns every menu id created so the
+// caller can grant them to a role.
+//
+// Specs do not have to be given in parent-before-child order: this makes
+// repeated passes over the remaining specs, creating whichever ones have
+// their Parent (if any) already created, until every spec is placed. A
+// spec whose Parent never resolves - naming a Code missing from this call,
+// or only reachable through a cycle - stops making progress and is reported
+// rather than looping forever.
+func seedMenuTree(tx *gorm.DB, appCode string, specs []seed.MenuSpec, apiRows map[string]models.SysApi) ([]int, error) {
+	byCode := make(map[string]seed.MenuSpec, len(specs))
+	for _, s := range specs {
+		if s.Code == "" {
+			return nil, errors.New("MenuSpec.Code must not be empty")
+		}
+		if _, dup := byCode[s.Code]; dup {
+			return nil, fmt.Errorf("duplicate MenuSpec.Code %q", s.Code)
+		}
+		if err := validateMenuSpec(s); err != nil {
+			return nil, fmt.Errorf("%q: %w", s.Code, err)
+		}
+		byCode[s.Code] = s
+	}
+
+	created := make(map[string]models.SysMenu, len(specs))
+	ids := make([]int, 0, len(specs))
+
+	for len(created) < len(specs) {
+		progressed := false
+		for _, s := range specs {
+			if _, done := created[s.Code]; done {
+				continue
+			}
+
+			var parentRow models.SysMenu
+			if s.Parent != "" {
+				parent, ok := created[s.Parent]
+				if !ok {
+					if _, exists := byCode[s.Parent]; !exists {
+						return nil, fmt.Errorf("%q: Parent %q is not a Code in this call", s.Code, s.Parent)
+					}
+					continue // s.Parent exists but has not been created yet; retry next pass
+				}
+				parentRow = parent
+			}
+
+			row := models.SysMenu{
+				MenuName:   menuName(appCode, s.Code),
+				Title:      s.Title,
+				Icon:       s.Icon,
+				Path:       s.Path,
+				MenuType:   s.Kind,
+				Permission: s.Permission,
+				ParentId:   parentRow.MenuId,
+				Component:  s.Component,
+				Sort:       s.Sort,
+				// Visible "0" is shown, not hidden - the same defaults
+				// 1786700001000_demo_menu.go seeds its own menu with. A
+				// freshly installed application's menu should not need an
+				// administrator to first find and unhide it.
+				Visible: "0",
+				IsFrame: "1",
+				AppCode: appCode,
+			}
+			for _, code := range s.ApiCodes {
+				api, ok := apiRows[code]
+				if !ok {
+					return nil, fmt.Errorf("%q: ApiCodes references %q, which is not an ApiSpec.Code in this call", s.Code, code)
+				}
+				// The full row, not just {Id: api.Id}: gorm's many2many
+				// association save upserts an associated row whose primary
+				// key is already set, so a stub carrying only Id would
+				// overwrite every other column of an sys_api row this same
+				// call just wrote with zero values.
+				row.SysApi = append(row.SysApi, api)
+			}
+
+			if err := tx.Create(&row).Error; err != nil {
+				return nil, fmt.Errorf("%q: %w", s.Code, err)
+			}
+
+			// paths is a materialized path from the root ("/0"), built from
+			// ids that only exist once the row above is created - the same
+			// two-step create-then-update 1786700001000_demo_menu.go's
+			// hand-assigned ids let it do in one literal, sequenced here
+			// instead.
+			if s.Parent == "" {
+				row.Paths = "/0/" + strconv.Itoa(row.MenuId)
+			} else {
+				row.Paths = parentRow.Paths + "/" + strconv.Itoa(row.MenuId)
+			}
+			if err := tx.Model(&models.SysMenu{}).Where("menu_id = ?", row.MenuId).
+				Update("paths", row.Paths).Error; err != nil {
+				return nil, fmt.Errorf("%q: writing paths: %w", s.Code, err)
+			}
+
+			created[s.Code] = row
+			ids = append(ids, row.MenuId)
+			progressed = true
+		}
+		if !progressed {
+			return nil, fmt.Errorf("unresolved Parent reference(s) among %d remaining spec(s); check for a cycle", len(specs)-len(created))
+		}
+	}
+	return ids, nil
+}
+
+// validateMenuSpec rejects the malformed input tools/checksilent's
+// menu-sort-overflow and Kind-adjacent checks would catch for an in-tree
+// seed but cannot for a third-party application's - see menuSortRange's doc
+// comment.
+func validateMenuSpec(s seed.MenuSpec) error {
+	switch s.Kind {
+	case contractmodels.Directory, contractmodels.Menu, contractmodels.Button:
+	default:
+		return fmt.Errorf("Kind %q is not one of Directory/Menu/Button", s.Kind)
+	}
+	if s.Sort < menuSortMin || s.Sort > menuSortMax {
+		return fmt.Errorf("Sort %d does not fit sys_menu.sort's tinyint column (%d..%d)", s.Sort, menuSortMin, menuSortMax)
+	}
+	return nil
+}
+
+// menuName synthesizes sys_menu.menu_name from appCode and the spec's Code,
+// since MenuSpec carries no field of its own for it - contract/seed's
+// package doc says a MenuSpec is what rendering a menu and checking a
+// button permission need, not a mirror of sys_menu's columns.
+//
+// PascalCasing both and concatenating them, rather than using Code alone,
+// is what keeps two applications that both picked the plain word "list" as
+// a Code from producing the identical menu_name: the frontend's keep-alive
+// cache matches a route by this exact string, not by (appCode, Code), so a
+// collision there is a UI bug, not a database error, and nothing else here
+// would ever surface it.
+func menuName(appCode, code string) string {
+	return pascalCase(appCode) + pascalCase(code)
+}
+
+func pascalCase(s string) string {
+	var b strings.Builder
+	for _, part := range strings.FieldsFunc(s, func(r rune) bool { return r == '-' || r == '_' }) {
+		b.WriteString(strings.ToUpper(part[:1]))
+		b.WriteString(part[1:])
+	}
+	return b.String()
+}
+
+// grantToAdminRole is sys_role_menu and casbin_rule: the two tables
+// go-admin-core's contract.md requires alongside sys_menu/sys_api, without
+// which a seeded menu is invisible to every role and its apis are
+// authorized for no one.
+//
+// It follows 1786700001000_demo_menu.go's exact pattern, including
+// tolerating a missing admin role: a database that has not yet run the
+// framework's own seed data (config/db.sql, inside 1599190683659_tables.go)
+// has nothing to grant to yet, and namespacedKey's ordering guarantee - every
+// framework migration sorts before every app-prefixed one - means that
+// should not happen in practice, but failing this call over it would be
+// worse than a menu with no grant yet.
+func grantToAdminRole(tx *gorm.DB, menuIDs []int, apiRows map[string]models.SysApi) error {
+	var role models.SysRole
+	if err := tx.Where("role_key = ?", adminRoleKey).First(&role).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		return err
+	}
+
+	for _, id := range menuIDs {
+		if err := tx.Exec(
+			"INSERT INTO sys_role_menu (role_id, menu_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM sys_role_menu WHERE role_id = ? AND menu_id = ?)",
+			role.RoleId, id, role.RoleId, id,
+		).Error; err != nil {
+			return err
+		}
+	}
+
+	for _, a := range apiRows {
+		if err := tx.Exec(
+			"INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5) SELECT 'p', ?, ?, ?, '', '', '' WHERE NOT EXISTS (SELECT 1 FROM casbin_rule WHERE ptype='p' AND v0=? AND v1=? AND v2=?)",
+			role.RoleKey, a.Path, a.Action, role.RoleKey, a.Path, a.Action,
+		).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}

app/admin/service/seed_test.go

@@ -0,0 +1,291 @@
+package service
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/seed"
+
+	"go-admin/app/admin/models"
+)
+
+// newSeedTestDB builds the tables adminSeeder.SeedMenus writes to. sys_menu,
+// sys_api, sys_role and sys_role_menu (GORM's own join table for
+// SysRole.SysMenu) come from AutoMigrate; casbin_rule does not have a GORM
+// model anywhere in this codebase - see 1786700001000_demo_menu.go's own
+// comment on why models.CasbinRule (-> sys_casbin_rule) is the wrong table -
+// so it is created directly, matching the columns grantToAdminRole's INSERT
+// addresses.
+func newSeedTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(&models.SysMenu{}, &models.SysApi{}, &models.SysRole{}); err != nil {
+		t.Fatalf("automigrate: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE casbin_rule (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		ptype TEXT, v0 TEXT, v1 TEXT, v2 TEXT, v3 TEXT, v4 TEXT, v5 TEXT
+	)`).Error; err != nil {
+		t.Fatalf("create casbin_rule: %v", err)
+	}
+	return db
+}
+
+func seedAdminRole(t *testing.T, db *gorm.DB) models.SysRole {
+	t.Helper()
+	role := models.SysRole{RoleName: "Administrator", RoleKey: adminRoleKey}
+	if err := db.Create(&role).Error; err != nil {
+		t.Fatalf("seed admin role: %v", err)
+	}
+	return role
+}
+
+// This is the acceptance case go-admin-core's docs/contract.md requires: one
+// SeedMenus call populates all four tables a visible, working menu entry
+// needs, every row tagged with the appCode it was called with, and the
+// parent/child tree resolved into sys_menu's parent_id/paths.
+func TestSeedMenusPopulatesAllFourTables(t *testing.T) {
+	db := newSeedTestDB(t)
+	seedAdminRole(t, db)
+
+	menus := []seed.MenuSpec{
+		{Code: "dir", Kind: contractmodels.Directory, Title: "Order Example", Path: "/apps/order", Component: "Layout", Sort: 10},
+		{Code: "list", Parent: "dir", Kind: contractmodels.Menu, Title: "Orders", Path: "list", Component: "apps/order/order/index", Sort: 1, ApiCodes: []string{"list"}},
+		{Code: "btn-create", Parent: "list", Kind: contractmodels.Button, Title: "Create", Permission: "order:order:create", Sort: 1},
+	}
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+	}
+
+	err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	})
+	if err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	var apiRows []models.SysApi
+	if err := db.Find(&apiRows).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(apiRows) != 1 || apiRows[0].AppCode != "order" || apiRows[0].Path != "/api/v1/order" {
+		t.Fatalf("sys_api = %+v", apiRows)
+	}
+
+	var menuRows []models.SysMenu
+	if err := db.Order("sort").Find(&menuRows).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(menuRows) != 3 {
+		t.Fatalf("sys_menu has %d rows, want 3: %+v", len(menuRows), menuRows)
+	}
+	byName := map[string]models.SysMenu{}
+	for _, m := range menuRows {
+		if m.AppCode != "order" {
+			t.Errorf("menu %q app_code = %q, want order", m.MenuName, m.AppCode)
+		}
+		byName[m.MenuName] = m
+	}
+	dir, ok := byName[menuName("order", "dir")]
+	if !ok || dir.ParentId != 0 || dir.Paths != "/0/"+strconv.Itoa(dir.MenuId) {
+		t.Fatalf("dir menu = %+v", dir)
+	}
+	list, ok := byName[menuName("order", "list")]
+	if !ok || list.ParentId != dir.MenuId || list.Paths != dir.Paths+"/"+strconv.Itoa(list.MenuId) {
+		t.Fatalf("list menu = %+v (dir=%+v)", list, dir)
+	}
+	btn, ok := byName[menuName("order", "btn-create")]
+	if !ok || btn.ParentId != list.MenuId {
+		t.Fatalf("btn menu = %+v (list=%+v)", btn, list)
+	}
+
+	// sys_menu_api_rule: gorm's own many2many join table for SysMenu.SysApi.
+	var joinCount int64
+	if err := db.Table("sys_menu_api_rule").
+		Where("sys_menu_menu_id = ? AND sys_api_id = ?", list.MenuId, apiRows[0].Id).
+		Count(&joinCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if joinCount != 1 {
+		t.Errorf("sys_menu_api_rule has %d row(s) linking list to its api, want 1", joinCount)
+	}
+
+	// sys_role_menu: every seeded menu granted to the admin role.
+	var roleMenuCount int64
+	if err := db.Table("sys_role_menu").Count(&roleMenuCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if roleMenuCount != 3 {
+		t.Errorf("sys_role_menu has %d row(s), want 3 (one per seeded menu)", roleMenuCount)
+	}
+
+	// casbin_rule: the api's path/method granted to the admin role.
+	var casbinCount int64
+	if err := db.Table("casbin_rule").
+		Where("ptype = 'p' AND v0 = ? AND v1 = ? AND v2 = ?", adminRoleKey, "/api/v1/order", "GET").
+		Count(&casbinCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if casbinCount != 1 {
+		t.Errorf("casbin_rule has %d matching row(s), want 1", casbinCount)
+	}
+}
+
+// A database that has not run the framework's own seed data yet (no admin
+// role) must not fail SeedMenus - 1786700001000_demo_menu.go tolerates
+// exactly the same condition for the host's own demo module.
+func TestSeedMenusToleratesMissingAdminRole(t *testing.T) {
+	db := newSeedTestDB(t)
+
+	err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", []seed.MenuSpec{
+			{Code: "dir", Kind: contractmodels.Directory, Title: "Order"},
+		}, nil)
+	})
+	if err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	var roleMenuCount int64
+	if err := db.Table("sys_role_menu").Count(&roleMenuCount).Error; err != nil {
+		t.Fatal(err)
+	}
+	if roleMenuCount != 0 {
+		t.Errorf("sys_role_menu has %d row(s) with no role to grant to", roleMenuCount)
+	}
+}
+
+func TestSeedMenusRejectsMalformedSpecs(t *testing.T) {
+	cases := []struct {
+		name  string
+		menus []seed.MenuSpec
+		apis  []seed.ApiSpec
+		want  string
+	}{
+		{
+			name:  "duplicate menu code",
+			menus: []seed.MenuSpec{{Code: "a", Kind: contractmodels.Directory}, {Code: "a", Kind: contractmodels.Directory}},
+			want:  `duplicate MenuSpec.Code "a"`,
+		},
+		{
+			name:  "unresolved parent",
+			menus: []seed.MenuSpec{{Code: "a", Parent: "missing", Kind: contractmodels.Menu}},
+			want:  `Parent "missing" is not a Code in this call`,
+		},
+		{
+			name:  "unresolved api code",
+			menus: []seed.MenuSpec{{Code: "a", Kind: contractmodels.Menu, ApiCodes: []string{"missing"}}},
+			want:  `ApiCodes references "missing"`,
+		},
+		{
+			name:  "unknown kind",
+			menus: []seed.MenuSpec{{Code: "a", Kind: "X"}},
+			want:  `Kind "X" is not one of Directory/Menu/Button`,
+		},
+		{
+			name:  "sort overflows a tinyint",
+			menus: []seed.MenuSpec{{Code: "a", Kind: contractmodels.Directory, Sort: 900}},
+			want:  `Sort 900 does not fit sys_menu.sort's tinyint column`,
+		},
+		{
+			name: "duplicate api code",
+			apis: []seed.ApiSpec{{Code: "x"}, {Code: "x"}},
+			want: `duplicate ApiSpec.Code "x"`,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			db := newSeedTestDB(t)
+			err := db.Transaction(func(tx *gorm.DB) error {
+				return adminSeeder{}.SeedMenus(tx, "order", tc.menus, tc.apis)
+			})
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("err = %v, want it to contain %q", err, tc.want)
+			}
+		})
+	}
+}
+
+// TestSeederIsRegistered pins the registration itself, not the behaviour.
+//
+// Every other test here calls adminSeeder{}.SeedMenus directly, which proves
+// the implementation is right and proves nothing about whether anything ever
+// reaches it: delete the RegisterSeeder call in init() and they all stay
+// green, while a real migrate fails with ErrNoSeeder and no menu is written.
+// Going through the package-level SeedMenus is what closes that gap - it is
+// the door an application actually knocks on.
+func TestSeederIsRegistered(t *testing.T) {
+	db := newSeedTestDB(t)
+	err := db.Transaction(func(tx *gorm.DB) error {
+		return seed.SeedMenus(tx, "probe", []seed.MenuSpec{{
+			Code: "root", Kind: contractmodels.Directory, Title: "Probe", Sort: 1,
+		}}, nil)
+	})
+	if errors.Is(err, seed.ErrNoSeeder) {
+		t.Fatal("no Seeder is registered: an application's SeedMenus would write no menu at all")
+	}
+	if err != nil {
+		t.Fatalf("SeedMenus through the package-level entry point: %v", err)
+	}
+}
+
+// An application is free to register apis with no menus at all - endpoints
+// another service calls, or a UI mounted somewhere else. Skipping
+// grantToAdminRole on an empty menu list wrote the sys_api rows and then no
+// casbin rule for them, so every one of those endpoints was denied to
+// everyone including admin, from a migration that reported success.
+func TestSeedMenusGrantsApisWhenThereAreNoMenus(t *testing.T) {
+	db := newSeedTestDB(t)
+	role := seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{
+		{Code: "hook", Title: "Inbound hook", Path: "/api/v1/hook", Method: "POST", Handle: "hook.Receive"},
+		{Code: "sync", Title: "Sync", Path: "/api/v1/sync", Method: "GET", Handle: "hook.Sync"},
+	}
+	if err := (adminSeeder{}).SeedMenus(db, "hooks", nil, apis); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	var apiCount int64
+	db.Model(&models.SysApi{}).Where("app_code = ?", "hooks").Count(&apiCount)
+	if apiCount != int64(len(apis)) {
+		t.Fatalf("sys_api rows = %d, want %d", apiCount, len(apis))
+	}
+
+	for _, a := range apis {
+		var n int64
+		db.Table("casbin_rule").
+			Where("ptype = 'p' AND v0 = ? AND v1 = ? AND v2 = ?", role.RoleKey, a.Path, a.Method).
+			Count(&n)
+		if n != 1 {
+			t.Errorf("casbin_rule for %s %s = %d rows, want 1: the endpoint is denied to admin", a.Method, a.Path, n)
+		}
+	}
+}
+
+// The other half of the same guard: nothing registered at all must stay a
+// no-op rather than start touching sys_role_menu or casbin_rule.
+func TestSeedMenusWithNothingRegisteredWritesNothing(t *testing.T) {
+	db := newSeedTestDB(t)
+	seedAdminRole(t, db)
+
+	if err := (adminSeeder{}).SeedMenus(db, "empty", nil, nil); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+	for _, table := range []string{"casbin_rule", "sys_role_menu"} {
+		var n int64
+		db.Table(table).Count(&n)
+		if n != 0 {
+			t.Errorf("%s has %d rows, want 0", table, n)
+		}
+	}
+}

app/admin/service/sys_user.go

@@ -38,6 +38,30 @@ func (e *SysUser) GetPage(c *dto.SysUserGetPageReq, p *actions.DataPermission, l
 	return nil
 }
 
+// GetSelf 获取调用者自己的 SysUser 对象，不套数据权限
+//
+// The data scope answers "whose rows may this user see"; the caller here is
+// reading their own, and the id comes from the token, so there is nothing left
+// for a scope to restrict. Applying one is not a stricter version of this
+// query - it is a broken one. DataScopeSelf matches on create_by, and a user
+// account is created by whoever added it, so a scoped self-read would fail for
+// every user who did not create their own account.
+//
+// GetProfile has always read the same row this way, with no scope at all.
+func (e *SysUser) GetSelf(d *dto.SysUserById, model *models.SysUser) error {
+	err := e.Orm.First(model, d.GetId()).Error
+	if err != nil && errors.Is(err, gorm.ErrRecordNotFound) {
+		err = errors.New("查看对象不存在或无权查看")
+		e.Log.Errorf("db error: %s", err)
+		return err
+	}
+	if err != nil {
+		e.Log.Errorf("db error: %s", err)
+		return err
+	}
+	return nil
+}
+
 // Get 获取SysUser对象
 func (e *SysUser) Get(d *dto.SysUserById, p *actions.DataPermission, model *models.SysUser) error {
 	var data models.SysUser

app/jobs/jobbase.go

@@ -1,6 +1,7 @@
 package jobs
 
 import (
+	"context"
 	"fmt"
 	log "github.com/go-admin-team/go-admin-core/v2/logger"
 	"github.com/go-admin-team/go-admin-core/v2/sdk"
@@ -145,11 +146,36 @@ func setup(key string, db *gorm.DB) {
 	}
 
 	// 其中任务
-	crontab.Start()
+	startCrontab(crontab)
+}
+
+// startCrontab starts c and arranges for it to be stopped on the way out.
+//
+// The stop used to be `defer crontab.Stop()` followed by `select {}`. The
+// select never returned, so the defer never ran and the scheduler was never
+// stopped; and because setup never returned, the loop in Setup never reached
+// the second tenant - only whichever database came first out of the map ever
+// got a scheduler at all. cron.Start is itself `go c.run()`, so the select was
+// blocking for nothing.
+//
+// cron.Stop returns a context that closes once the jobs already running have
+// finished. That is the wait the shutdown budget exists to bound: giving up on
+// it leaves those jobs running until the process exits, which is better than
+// holding the whole shutdown open for one job that will not end.
+func startCrontab(c *cron.Cron) {
+	c.Start()
 	fmt.Println(time.Now().Format(timeFormat), " [INFO] JobCore start success.")
+
 	// 关闭任务
-	defer crontab.Stop()
-	select {}
+	sdk.Runtime.SetShutdown(func(ctx context.Context) {
+		stopped := c.Stop()
+		select {
+		case <-stopped.Done():
+			fmt.Println(time.Now().Format(timeFormat), " [INFO] JobCore stopped.")
+		case <-ctx.Done():
+			fmt.Println(time.Now().Format(timeFormat), " [WARN] JobCore stop gave up waiting for running jobs")
+		}
+	})
 }
 
 // AddJob 添加任务 AddJob(invokeTarget string, jobId int, jobName string, cronExpression string)

app/jobs/jobbase_test.go

@@ -0,0 +1,52 @@
+package jobs
+
+import (
+	"context"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/pkg/cronjob"
+)
+
+// The scheduler had never been stopped. `defer crontab.Stop()` sat directly
+// above a `select {}` that never returned, so the deferred call was
+// unreachable for the life of the process.
+//
+// There is one test rather than several because BeforeExit closes to further
+// registration once it has run: a second RunShutdown in this binary would find
+// an empty registry and pass while proving nothing.
+func TestTheSchedulerIsStoppedOnTheWayOut(t *testing.T) {
+	var ticks atomic.Int64
+
+	c := cronjob.NewWithSeconds()
+	if _, err := c.AddFunc("* * * * * *", func() { ticks.Add(1) }); err != nil {
+		t.Fatalf("AddFunc: %v", err)
+	}
+
+	startCrontab(c)
+
+	// It has to be running before stopping it can mean anything.
+	deadline := time.Now().Add(5 * time.Second)
+	for ticks.Load() == 0 && time.Now().Before(deadline) {
+		time.Sleep(20 * time.Millisecond)
+	}
+	if ticks.Load() == 0 {
+		t.Fatal("the scheduler never ran the job, so this test cannot show it was stopped")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if err := sdk.Runtime.RunShutdown(ctx); err != nil {
+		t.Fatalf("RunShutdown: %v", err)
+	}
+
+	// Two and a half seconds is two more firings of a job that runs every
+	// second, so silence here is the assertion.
+	at := ticks.Load()
+	time.Sleep(2500 * time.Millisecond)
+	if n := ticks.Load() - at; n > 0 {
+		t.Errorf("the job fired %d more times after shutdown: the scheduler is still running", n)
+	}
+}

cmd/api/phase_test.go

@@ -0,0 +1,160 @@
+package api
+
+import (
+	"fmt"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/runtime"
+)
+
+// freePort returns a port nothing is listening on. It is inherently a guess -
+// the port is free when it is handed back and could be taken a moment later -
+// but every alternative needs the caller to hold the listener, which is the one
+// thing these tests cannot do.
+func freePort(t *testing.T) int {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("probe listen: %v", err)
+	}
+	port := ln.Addr().(*net.TCPAddr).Port
+	_ = ln.Close()
+	return port
+}
+
+// AfterListen promises a hook that the port is reachable. Both halves of that
+// are asserted here, and in one test rather than two, because the phase seals
+// itself once it has run: a second test calling RunPhase again would find a
+// closed registry and pass while proving nothing.
+//
+// The failing bind comes first for the same reason. It must leave the phase
+// unsealed, which is only visible if nothing has sealed it yet.
+func TestAfterListenIsAnnouncedOnlyOnceThePortIsBound(t *testing.T) {
+	// The pause makes the "announced synchronously" claim testable: if the
+	// announcement were moved onto a goroutine, startServing would return
+	// while the hook was still sleeping and the count below would be zero.
+	var ran int
+	sdk.Runtime.SetPhase(runtime.AfterListen, func() {
+		time.Sleep(50 * time.Millisecond)
+		ran++
+	})
+
+	// Somebody else already has the port. Under ListenAndServe this surfaced
+	// on the serving goroutine, far too late to stop the announcement.
+	taken, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("occupy: %v", err)
+	}
+	defer func() { _ = taken.Close() }()
+
+	blocked := &http.Server{Addr: taken.Addr().String(), Handler: http.NewServeMux()}
+	if err := startServing(blocked, false, "", ""); err == nil {
+		t.Fatal("startServing returned no error for a port that was already taken")
+	}
+	if ran != 0 {
+		t.Errorf("AfterListen ran %d times after a failed bind; a hook there is told the port is reachable", ran)
+	}
+	if sdk.Runtime.PhaseSealed(runtime.AfterListen) {
+		t.Error("a failed bind sealed AfterListen, so the phase could never run for a server that did start")
+	}
+
+	// A certificate that cannot be read is the other way to fail before there
+	// is anything to announce. ServeTLS reads it on the serving goroutine, so
+	// without the check in startServing this would be a hook told the port was
+	// reachable while the server was already on its way down.
+	if err := startServing(&http.Server{Addr: "127.0.0.1:0"}, true, "no-such.pem", "no-such.key"); err == nil {
+		t.Fatal("startServing returned no error for a certificate that does not exist")
+	}
+	if ran != 0 {
+		t.Errorf("AfterListen ran %d times after a certificate failure", ran)
+	}
+	if sdk.Runtime.PhaseSealed(runtime.AfterListen) {
+		t.Error("a certificate failure sealed AfterListen")
+	}
+
+	// And now a bind that works.
+	port := freePort(t)
+	srv := &http.Server{Addr: fmt.Sprintf("127.0.0.1:%d", port), Handler: http.NewServeMux()}
+	if err := startServing(srv, false, "", ""); err != nil {
+		t.Fatalf("startServing on a free port: %v", err)
+	}
+	defer func() { _ = srv.Close() }()
+
+	// Checked the instant startServing returns, so this is also the assertion
+	// that it did not return early: an asynchronous announcement would still
+	// be inside the sleep. Synchrony matters because an announcement that
+	// overlaps the wait below could, on a fast SIGTERM, have the shutdown
+	// callbacks finish before the startup ones.
+	if ran != 1 {
+		t.Fatalf("AfterListen ran %d times, want 1", ran)
+	}
+
+	// The claim is not "Serve was called" but "the port answers". Dial it.
+	c, err := net.DialTimeout("tcp", srv.Addr, 5*time.Second)
+	if err != nil {
+		t.Fatalf("AfterListen ran but the port does not answer: %v", err)
+	}
+	_ = c.Close()
+}
+
+// BeforeRouter is the last point at which a module can still affect how routes
+// are built, so it has to run while there is no engine yet. The before registry
+// is a different moment despite the name: those callbacks run after initRouter
+// has built the engine.
+//
+// The two are two lines apart in buildRouter, and calling them equivalent is a
+// mistake this repository has already made in writing. Until this test the
+// ordering was checked by reading - which is how the stop signals came to be
+// armed after the readiness banner in the same file.
+func TestBeforeRouterRunsWhileThereIsNoEngine(t *testing.T) {
+	freshRuntime(t)
+
+	// AuthInit reads these two package-level values and nothing else. No
+	// database is involved in building a router: the handlers are registered,
+	// not called.
+	config.ApplicationConfig.Mode = "dev"
+	config.JwtConfig.Secret = "test-secret-for-the-router-build"
+
+	type observation struct {
+		ran        int
+		engineWas  interface{}
+		engineSeen bool
+	}
+	var phase, before observation
+
+	sdk.Runtime.SetPhase(runtime.BeforeRouter, func() {
+		phase.ran++
+		phase.engineWas = sdk.Runtime.GetEngine()
+		phase.engineSeen = true
+	})
+	sdk.Runtime.SetBefore(func() {
+		before.ran++
+		before.engineWas = sdk.Runtime.GetEngine()
+		before.engineSeen = true
+	})
+
+	buildRouter()
+
+	if phase.ran != 1 {
+		t.Fatalf("BeforeRouter ran %d times, want 1", phase.ran)
+	}
+	if !phase.engineSeen || phase.engineWas != nil {
+		t.Errorf("BeforeRouter saw engine %v, want nil: it is meant to run before initRouter builds one", phase.engineWas)
+	}
+
+	if before.ran != 1 {
+		t.Fatalf("the before registry ran %d times, want 1", before.ran)
+	}
+	if before.engineWas == nil {
+		t.Error("a before callback saw no engine; that registry is meant to run after initRouter, and describing it as equivalent to BeforeRouter is the error this asserts against")
+	}
+
+	if sdk.Runtime.GetEngine() == nil {
+		t.Error("buildRouter returned with no engine built")
+	}
+}

cmd/api/queue_test.go

@@ -0,0 +1,167 @@
+package api
+
+import (
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	corestorage "github.com/go-admin-team/go-admin-core/v2/storage"
+)
+
+// recordingQueue records what was done to it, in order. Register and Run are
+// the two calls whose order is the point of this file; Append and Shutdown are
+// here to satisfy the interface.
+type recordingQueue struct {
+	mu     sync.Mutex
+	events []string
+	ran    chan struct{}
+}
+
+func newRecordingQueue() *recordingQueue {
+	return &recordingQueue{ran: make(chan struct{}, 4)}
+}
+
+func (q *recordingQueue) record(e string) {
+	q.mu.Lock()
+	q.events = append(q.events, e)
+	q.mu.Unlock()
+}
+
+func (q *recordingQueue) seen() []string {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	return append([]string(nil), q.events...)
+}
+
+func (q *recordingQueue) String() string                    { return "recording" }
+func (q *recordingQueue) Append(corestorage.Messager) error { return nil }
+func (q *recordingQueue) Register(name string, _ corestorage.ConsumerFunc) {
+	q.record("register:" + name)
+}
+func (q *recordingQueue) Shutdown() {}
+
+func (q *recordingQueue) Run() {
+	q.record("run")
+	select {
+	case q.ran <- struct{}{}:
+	default:
+	}
+}
+
+// waitForRun waits for Run, which is started on a goroutine.
+func (q *recordingQueue) waitForRun(t *testing.T) {
+	t.Helper()
+	select {
+	case <-q.ran:
+	case <-time.After(5 * time.Second):
+		t.Fatalf("Run was never called; saw: %v", q.seen())
+	}
+}
+
+// The consumers must be registered before the queue is started. A queue that
+// is already running refuses further registration - the contract
+// implementations answer storage.ErrQueueAlreadyStarted - and the legacy
+// adapter this path goes through drops that error, so the wrong order loses
+// consumers with nothing said about it. The memory backend does not care,
+// which is exactly why this cannot be left to be noticed in use.
+func TestConsumersAreRegisteredBeforeTheQueueIsStarted(t *testing.T) {
+	attachedQueue.Store(0)
+	t.Cleanup(func() { attachedQueue.Store(0) })
+
+	q := newRecordingQueue()
+	attachConsumersOnce(1, q)
+	q.waitForRun(t)
+
+	seen := q.seen()
+	runAt := -1
+	registers := 0
+	for i, e := range seen {
+		switch {
+		case e == "run":
+			if runAt < 0 {
+				runAt = i
+			}
+		case strings.HasPrefix(e, "register:"):
+			registers++
+			if runAt >= 0 {
+				t.Errorf("%q came after Run; a running queue refuses registration", e)
+			}
+		}
+	}
+	if registers != 3 {
+		t.Errorf("registered %d consumers, want 3; saw %v", registers, seen)
+	}
+	if runAt < 0 {
+		t.Errorf("the queue was never started; saw %v", seen)
+	}
+}
+
+// AfterResource runs again on every configuration reload, so the hook has to
+// be idempotent with respect to a given queue - not "does nothing the second
+// time". Registering twice on the same queue would give every message two
+// consumers and write every log row twice.
+func TestTheSameQueueIsNotGivenConsumersTwice(t *testing.T) {
+	attachedQueue.Store(0)
+	t.Cleanup(func() { attachedQueue.Store(0) })
+
+	q := newRecordingQueue()
+	attachConsumersOnce(1, q)
+	q.waitForRun(t)
+	attachConsumersOnce(1, q)
+
+	// Nothing to wait for on the second call, so give a wrong implementation
+	// the time it would need to show up.
+	time.Sleep(200 * time.Millisecond)
+	if n := len(q.seen()); n != 4 {
+		t.Errorf("%d calls after attaching twice to the same queue, want 4 (3 registers + 1 run); saw %v", n, q.seen())
+	}
+}
+
+// The other half of the same rule: a reload builds a new adapter, and the
+// consumers on the old one are attached to a queue nobody publishes to any
+// more. A new generation must get its own set.
+func TestANewQueueGetsItsOwnConsumers(t *testing.T) {
+	attachedQueue.Store(0)
+	t.Cleanup(func() { attachedQueue.Store(0) })
+
+	first := newRecordingQueue()
+	attachConsumersOnce(1, first)
+	first.waitForRun(t)
+
+	second := newRecordingQueue()
+	attachConsumersOnce(2, second)
+	second.waitForRun(t)
+
+	if n := len(second.seen()); n != 4 {
+		t.Errorf("the queue from the second generation saw %d calls, want 4; saw %v", n, second.seen())
+	}
+	if n := len(first.seen()); n != 4 {
+		t.Errorf("the queue from the first generation saw %d calls, want 4 - it should not have been touched again; saw %v", n, first.seen())
+	}
+}
+
+// Generation 0 means the configuration has no queue section at all, so nothing
+// was installed and the runtime hands back its own memory queue. That case
+// still has to get consumers - the registration it replaces was unconditional,
+// and dropping it would stop the login and operation logs for anyone who
+// commented the section out.
+func TestAnUnconfiguredQueueStillGetsConsumers(t *testing.T) {
+	attachedQueue.Store(0)
+	t.Cleanup(func() { attachedQueue.Store(0) })
+
+	q := newRecordingQueue()
+	attachConsumersOnce(0, q)
+	q.waitForRun(t)
+
+	if n := len(q.seen()); n != 4 {
+		t.Errorf("an unconfigured queue saw %d calls, want 4; saw %v", n, q.seen())
+	}
+
+	// And still only once.
+	attachConsumersOnce(0, q)
+	time.Sleep(200 * time.Millisecond)
+	if n := len(q.seen()); n != 4 {
+		t.Errorf("generation 0 was attached to twice: %d calls, want 4; saw %v", n, q.seen())
+	}
+}

cmd/api/server.go

@@ -2,10 +2,14 @@ package api
 
 import (
 	"context"
+	"crypto/tls"
 	"fmt"
+	"net"
 	"net/http"
 	"os"
 	"os/signal"
+	"sync/atomic"
+	"syscall"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -13,8 +17,11 @@ import (
 	log "github.com/go-admin-team/go-admin-core/v2/logger"
 	"github.com/go-admin-team/go-admin-core/v2/sdk"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/bootstrap"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/pkg"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/runtime"
+	corestorage "github.com/go-admin-team/go-admin-core/v2/storage"
 	"github.com/pkg/errors"
 	"github.com/spf13/cobra"
 
@@ -59,44 +66,109 @@ func init() {
 func setup() {
 	// 注入配置扩展项
 	config.ExtendConfig = &ext.ExtConfig
+
+	// Registered before the configuration is read. SetupConfig announces
+	// AfterResource as soon as the callbacks that build the resources have
+	// run, so a hook added after that call would miss the first round and the
+	// queue would have no consumers until somebody edited the config file.
+	sdk.Runtime.SetPhase(runtime.AfterResource, attachQueueConsumers)
+
+	// On AfterListen rather than on a bare goroutine from run(). Two reasons:
+	// the phase runs behind core's panic guard, which does not reach across a
+	// goroutine boundary - a panic while loading jobs used to take the whole
+	// process down with a stack that named this file - and the jobs it starts
+	// can call the API, which is only true once the socket is accepting.
+	sdk.Runtime.SetPhase(runtime.AfterListen, startCronJobs)
+
 	//1. 读取配置
-	config.Setup(
+	bootstrap.SetupConfig(
 		file.NewSource(file.WithPath(configYml)),
 		database.Setup,
 		storage.Setup,
 	)
-	//注册监听函数
-	queue := sdk.Runtime.GetQueuePrefix("")
-	queue.Register(global.LoginLog, models.SaveLoginLog)
-	queue.Register(global.OperateLog, models.SaveOperaLog)
-	queue.Register(global.ApiCheck, models.SaveSysApi)
-	go queue.Run()
 
 	usageStr := `starting api server...`
 	log.Info(usageStr)
 }
 
+// startCronJobs registers the job implementations and starts a scheduler for
+// every tenant database.
+//
+// It is synchronous, like the phase that runs it. jobs.Setup returns now that
+// the `select {}` at the end of its per-tenant setup is gone, which is what
+// makes that possible; while it was there this could only be a goroutine, and
+// a goroutine is outside the panic guard.
+func startCronJobs() {
+	jobs.InitJob()
+	jobs.Setup(sdk.Runtime.GetAllDb())
+}
+
+// attachedQueue is the queue generation the consumers are attached to, plus
+// one, so that the zero value means "attached to nothing yet". Written from
+// the goroutine running the phase, read from the next one - rounds never
+// overlap, but they are not the same goroutine.
+var attachedQueue atomic.Uint64
+
+// attachQueueConsumers registers the log consumers against the queue that is
+// current, and starts it.
+//
+// It runs on AfterResource, so it runs again after every configuration reload
+// - and it has to. A reload rebuilds the queue adapter, and consumers
+// registered against the one that existed at start-up are attached to an
+// adapter nobody publishes to any more, so the login and operation logs stop
+// being written with nothing said about it.
+//
+// It is therefore idempotent with respect to a given queue rather than "does
+// nothing the second time": a new adapter gets a fresh set of consumers, the
+// same one gets none. Registering twice on the same queue would give every
+// message two consumers and write every log row twice.
+//
+// Generation 0 means the configuration has no queue section, so nothing was
+// installed and GetQueuePrefix hands back the runtime's own memory queue.
+// That case still gets consumers - it is what the previous unconditional
+// registration did, and dropping it would silently stop logging for anyone who
+// commented the section out - it just never gets them twice.
+func attachQueueConsumers() {
+	attachConsumersOnce(storage.QueueGeneration(), sdk.Runtime.GetQueuePrefix(""))
+}
+
+// attachConsumersOnce puts the log consumers on q and starts it, unless gen
+// says this queue already has them.
+//
+// Split out from attachQueueConsumers so that the order and the once-ness can
+// be checked against a queue the test controls: the sequence that matters here
+// cannot be read back out of a real adapter.
+func attachConsumersOnce(gen uint64, q corestorage.AdapterQueue) {
+	if attachedQueue.Load() == gen+1 {
+		return
+	}
+	attachedQueue.Store(gen + 1)
+
+	//注册监听函数
+	q.Register(global.LoginLog, models.SaveLoginLog)
+	q.Register(global.OperateLog, models.SaveOperaLog)
+	q.Register(global.ApiCheck, models.SaveSysApi)
+
+	// Started only now, and by whoever registered. setupQueue deliberately
+	// leaves it stopped: a queue that is already running refuses further
+	// registration, and the adapter in this path drops that error on the
+	// floor, so starting first loses consumers without a word.
+	go q.Run()
+}
+
 func run() error {
 	if config.ApplicationConfig.Mode == pkg.ModeProd.String() {
 		gin.SetMode(gin.ReleaseMode)
 	}
-	initRouter()
-
-	runStartupHooks()
+	buildRouter()
 
 	srv := &http.Server{
-		Addr:    fmt.Sprintf("%s:%d", config.ApplicationConfig.Host, config.ApplicationConfig.Port),
-		Handler: sdk.Runtime.GetEngine(),
+		Addr:         fmt.Sprintf("%s:%d", config.ApplicationConfig.Host, config.ApplicationConfig.Port),
+		Handler:      sdk.Runtime.GetEngine(),
 		ReadTimeout:  time.Duration(config.ApplicationConfig.ReadTimeout) * time.Second,
 		WriteTimeout: time.Duration(config.ApplicationConfig.WriterTimeout) * time.Second,
 	}
 
-	go func() {
-		jobs.InitJob()
-		jobs.Setup(sdk.Runtime.GetAllDb())
-
-	}()
-
 	if apiCheck {
 		var routers = sdk.Runtime.GetRouter()
 		q := sdk.Runtime.GetQueuePrefix("")
@@ -114,18 +186,17 @@ func run() error {
 		}
 	}
 
-	go func() {
-		// 服务连接
-		if config.SslConfig.Enable {
-			if err := srv.ListenAndServeTLS(config.SslConfig.Pem, config.SslConfig.KeyStr); err != nil && !errors.Is(err, http.ErrServerClosed) {
-				log.Fatal("listen: ", err)
-			}
-		} else {
-			if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
-				log.Fatal("listen: ", err)
-			}
-		}
-	}()
+	// Armed before the server starts serving, and well before the readiness
+	// banner: a signal arriving between "the process is up" and "the process
+	// is listening for signals" reaches the default handler and kills it
+	// without any of the shutdown below. That window is the whole reason
+	// arming is separate from waiting.
+	quit, disarmStopSignals := armStopSignals()
+
+	if err := startServing(srv, config.SslConfig.Enable, config.SslConfig.Pem, config.SslConfig.KeyStr); err != nil {
+		return err
+	}
+
 	fmt.Println(pkg.Red(string(global.LogoContent)))
 	tip()
 	fmt.Println(pkg.Green("Server run at:"))
@@ -135,23 +206,166 @@ func run() error {
 	fmt.Printf("-  Local:   http://localhost:%d/swagger/admin/index.html \r\n", config.ApplicationConfig.Port)
 	fmt.Printf("-  Network: %s://%s:%d/swagger/admin/index.html \r\n", "http", pkg.GetLocalHost(), config.ApplicationConfig.Port)
 	fmt.Printf("%s Enter Control + C Shutdown Server \r\n", pkg.GetCurrentTimeStr())
-	// 等待中断信号以优雅地关闭服务器（设置 5 秒的超时时间）
-	quit := make(chan os.Signal, 1)
-	signal.Notify(quit, os.Interrupt)
+
 	<-quit
+	// Restored here, not deferred: from this point a second signal must reach
+	// the default handler, so a shutdown that hangs can still be interrupted.
+	disarmStopSignals()
+
+	// Said before anything is taken apart. A configuration reload arriving in
+	// this window would otherwise re-run AfterResource - rebuilding the pool
+	// and the queue adapter, and re-registering consumers - on top of cleanup
+	// that has already run.
+	sdk.Runtime.BeginShutdown()
 
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
 	log.Info("Shutdown Server ... ")
+	if err := shutdownServer(srv, shutdownTimeout); err != nil {
+		// Not log.Fatal: that is an unconditional os.Exit(1), and Shutdown
+		// reports an error exactly when connections were still in flight -
+		// which is when the cleanup that follows matters most.
+		log.Error("Server Shutdown: ", err)
+	}
 
-	if err := srv.Shutdown(ctx); err != nil {
-		log.Fatal("Server Shutdown:", err)
+	// Runs whether or not the line above reported an error, for that reason.
+	if err := runShutdownHooks(cleanupTimeout); err != nil {
+		log.Error("Cleanup: ", err)
 	}
 	log.Info("Server exiting")
 
 	return nil
 }
 
+// shutdownTimeout is how long Shutdown waits for in-flight requests, and
+// cleanupTimeout how long the BeforeExit callbacks get after it.
+//
+// They are consumed one after the other, so the two together are what has to
+// stay inside the orchestrator's grace period: `docker stop` allows 10s by
+// default before it sends SIGKILL, and 5+3 leaves room for the process to
+// finish returning. Raising either without lowering the other buys nothing -
+// the budget that runs out is the orchestrator's.
+const (
+	shutdownTimeout = 5 * time.Second
+	cleanupTimeout  = 3 * time.Second
+)
+
+// armStopSignals registers for the stop signals and returns the channel they
+// arrive on together with the function that restores the default disposition.
+//
+// SIGTERM is what actually arrives in production: `docker stop`, a Kubernetes
+// pod deletion and `systemctl stop` all send it, and Go terminates the process
+// immediately for a signal nobody listens for. Registering only os.Interrupt
+// meant every graceful shutdown below the wait was dead code outside a
+// terminal.
+//
+// Registering is separate from waiting so a caller can arm before it announces
+// that it is ready: a signal that arrives between the two is delivered to the
+// default handler, which for both of these means the process dies without
+// running any of this.
+func armStopSignals() (<-chan os.Signal, func()) {
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, os.Interrupt, syscall.SIGTERM)
+	return quit, func() { signal.Stop(quit) }
+}
+
+// startServing binds srv.Addr, hands the listener to srv on its own goroutine,
+// and announces AfterListen.
+//
+// The bind is done here rather than left to ListenAndServe, which binds on the
+// goroutine that serves. That put the failure every deployment actually hits -
+// "address already in use" - on a goroutine nobody was reading, so the banner
+// went on to claim the server was up, and there would be no way to keep
+// AfterListen from announcing a socket that does not exist. A hook there is
+// promised a reachable port; the only way to keep that promise is for the bind
+// to have already happened on this goroutine.
+//
+// AfterListen is announced synchronously. Running it in a goroutine to save the
+// few milliseconds would let it overlap the shutdown: on a fast SIGTERM the
+// cleanup callbacks could finish before the startup ones had.
+//
+// Both ways of failing to start are therefore checked before the announcement:
+// the bind, and - with ssl enabled - the certificate.
+func startServing(srv *http.Server, useTLS bool, pem, key string) error {
+	if useTLS {
+		// Read the certificate before anything is announced. ServeTLS reads
+		// these files itself, but on the serving goroutine - so a bad
+		// certificate used to surface after AfterListen had already promised a
+		// reachable port. Loading it here costs one extra read and moves the
+		// failure onto this goroutine, where run() can return it.
+		//
+		// ServeTLS still does the real work below rather than this handing it a
+		// tls.Listener: that is what sets up HTTP/2 negotiation, and taking it
+		// over here would quietly drop h2 for every TLS deployment.
+		if _, err := tls.LoadX509KeyPair(pem, key); err != nil {
+			return errors.Wrap(err, "tls certificate")
+		}
+	}
+
+	ln, err := net.Listen("tcp", srv.Addr)
+	if err != nil {
+		return errors.Wrap(err, "listen")
+	}
+
+	go func() {
+		// 服务连接
+		var err error
+		if useTLS {
+			err = srv.ServeTLS(ln, pem, key)
+		} else {
+			err = srv.Serve(ln)
+		}
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			// Still fatal, as it was. Neither the bind nor the certificate is
+			// among the errors that reach here any more - both are checked
+			// above, on the caller's goroutine. What is left is a serve that
+			// failed after the port was taken, and carrying on would park the
+			// process on <-quit with nothing serving.
+			log.Fatal("serve: ", err)
+		}
+	}()
+
+	sdk.Runtime.RunPhase(runtime.AfterListen)
+	return nil
+}
+
+// shutdownServer stops srv, giving in-flight requests up to timeout to finish.
+//
+// It returns the error instead of exiting on it. A caller that exits here skips
+// its own cleanup, and Shutdown fails precisely when there was something left
+// to clean up after.
+func shutdownServer(srv *http.Server, timeout time.Duration) error {
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	return srv.Shutdown(ctx)
+}
+
+// runShutdownHooks runs the BeforeExit callbacks with timeout to share.
+//
+// What the budget bounds is the wait, not the work. When it is gone RunShutdown
+// stops waiting and returns; a callback that never looks at its context carries
+// on until the process exits, and may leave a partial write behind. Go cannot
+// cancel a function that does not check for cancellation, which is why the
+// callbacks are handed a context at all.
+func runShutdownHooks(timeout time.Duration) error {
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+	return sdk.Runtime.RunShutdown(ctx)
+}
+
+// buildRouter announces BeforeRouter, builds the engine, and then drains the
+// startup registries.
+//
+// The order is the contract. BeforeRouter is the last point at which a module
+// can still affect how routes are built, so it has to run while there is no
+// engine yet. The before registry runStartupHooks drains is a different moment
+// despite the name: those callbacks run after initRouter has built the engine.
+// Two lines apart, and describing them as equivalent is a mistake this
+// repository has already made once in writing.
+func buildRouter() {
+	sdk.Runtime.RunPhase(runtime.BeforeRouter)
+	initRouter()
+	runStartupHooks()
+}
+
 // runStartupHooks runs the router registries and then the before callbacks.
 //
 // The package-level slice runs first and in its existing order, so a fork that

cmd/api/signal_test.go

@@ -0,0 +1,369 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+)
+
+// The signal path cannot be exercised in-process: delivering a signal to the
+// test binary would race with the test framework, and the disposition changes
+// are global. So the test re-executes itself as a child, and the child runs the
+// same armStopSignals / shutdownServer the server does.
+//
+// The child deliberately serves an empty http.Server rather than the real one:
+// this repository's CI has no database (.github/workflows/go.yml runs neither
+// MySQL nor a sqlite-tagged build), and none of what is under test needs one.
+const (
+	childEnv         = "GO_ADMIN_SIGNAL_CHILD"
+	childStuckEnv    = "GO_ADMIN_SIGNAL_CHILD_STUCK"
+	childHangConn    = "GO_ADMIN_SIGNAL_CHILD_HANGCONN"
+	childSlowCleanup = "GO_ADMIN_SIGNAL_CHILD_SLOWCLEANUP"
+	markerReady      = "CHILD-READY"
+	markerSignal     = "CHILD-SIGNAL"
+	markerShutdown   = "CHILD-SHUTDOWN-OK"
+	markerCleanup    = "CHILD-CLEANUP-RAN"
+	markerExiting    = "CHILD-EXITING"
+)
+
+// TestSignalChild is the child process. It is skipped in a normal run.
+func TestSignalChild(t *testing.T) {
+	if os.Getenv(childEnv) != "1" {
+		t.Skip("child process entry point")
+	}
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		fmt.Println("listen:", err)
+		os.Exit(3)
+	}
+	// accepted fires once the server has taken a connection off the listener.
+	// Dialling is not enough: Shutdown only waits for connections the server
+	// has already accepted, so calling it between the dial and the accept
+	// finds nothing to wait for and returns immediately.
+	accepted := make(chan struct{}, 1)
+	srv := &http.Server{
+		Handler: http.NewServeMux(),
+		ConnState: func(_ net.Conn, state http.ConnState) {
+			if state == http.StateNew {
+				select {
+				case accepted <- struct{}{}:
+				default:
+				}
+			}
+		},
+	}
+	go func() { _ = srv.Serve(ln) }()
+
+	// A BeforeExit callback, registered the way a module would. What the tests
+	// below care about is whether it runs at all - after a Shutdown that
+	// failed, and after its own budget has been spent.
+	cleanupBudget := cleanupTimeout
+	sdk.Runtime.SetShutdown(func(ctx context.Context) {
+		if os.Getenv(childSlowCleanup) == "1" {
+			// Outlasts the budget on purpose, and does not consult ctx -
+			// which is the case the contract is explicit about: what the
+			// context bounds is the wait, not the work.
+			time.Sleep(2 * time.Second)
+		}
+		fmt.Println(markerCleanup)
+		os.Stdout.Sync()
+	})
+	if os.Getenv(childSlowCleanup) == "1" {
+		cleanupBudget = 300 * time.Millisecond
+	}
+
+	// Arm before announcing readiness. Doing it the other way round leaves a
+	// window in which the parent's signal reaches the default handler and
+	// kills the child before any of this runs - which is exactly the failure
+	// this whole change is about, so the test must not reproduce it by
+	// accident.
+	quit, disarm := armStopSignals()
+
+	fmt.Println(markerReady)
+	os.Stdout.Sync()
+
+	sig := <-quit
+	disarm()
+	fmt.Println(markerSignal, sig)
+	os.Stdout.Sync()
+
+	if os.Getenv(childStuckEnv) == "1" {
+		// Stand in for a cleanup hook that never finishes. The point of
+		// restoring the signal disposition is that a second signal still
+		// reaches the default handler and kills this.
+		time.Sleep(2 * time.Minute)
+	}
+
+	timeout := shutdownTimeout
+	if os.Getenv(childHangConn) == "1" {
+		// Dialled here, not at start-up. net/http stops counting a StateNew
+		// connection against Shutdown once it is more than five seconds old,
+		// so a connection opened before the wait would age out on a slow CI
+		// run and Shutdown would succeed - leaving the test asserting nothing.
+		c, err := net.Dial("tcp", ln.Addr().String())
+		if err != nil {
+			fmt.Println("dial:", err)
+			os.Exit(5)
+		}
+		defer func() { _ = c.Close() }()
+
+		// And wait for the accept, for the opposite reason: an unaccepted
+		// connection is not one Shutdown waits for either.
+		select {
+		case <-accepted:
+		case <-time.After(10 * time.Second):
+			fmt.Println("the server never accepted the stalling connection")
+			os.Exit(6)
+		}
+
+		// A connection that has sent nothing keeps Shutdown busy: net/http
+		// only treats a StateNew connection as idle once it is more than five
+		// seconds old. A short budget makes the timeout deterministic without
+		// waiting out the real one.
+		timeout = 300 * time.Millisecond
+	}
+
+	sdk.Runtime.BeginShutdown()
+
+	if err := shutdownServer(srv, timeout); err != nil {
+		// Deliberately not fatal, and deliberately not a bare return: the
+		// point is that whatever follows still runs.
+		fmt.Println("shutdown error:", err)
+	} else {
+		fmt.Println(markerShutdown)
+	}
+
+	if err := runShutdownHooks(cleanupBudget); err != nil {
+		fmt.Println("cleanup error:", err)
+	}
+	fmt.Println(markerExiting)
+	os.Stdout.Sync()
+}
+
+func startChild(t *testing.T, stuck bool, extraEnv ...string) (*exec.Cmd, *os.File, chan string) {
+	t.Helper()
+
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	cmd := exec.Command(os.Args[0], "-test.run=TestSignalChild", "-test.v")
+	cmd.Env = append(os.Environ(), childEnv+"=1")
+	if stuck {
+		cmd.Env = append(cmd.Env, childStuckEnv+"=1")
+	}
+	cmd.Env = append(cmd.Env, extraEnv...)
+	cmd.Stdout = w
+	cmd.Stderr = w
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("start child: %v", err)
+	}
+	_ = w.Close()
+
+	lines := make(chan string, 64)
+	go func() {
+		defer close(lines)
+		buf := make([]byte, 4096)
+		var acc strings.Builder
+		for {
+			n, err := r.Read(buf)
+			if n > 0 {
+				acc.Write(buf[:n])
+				for {
+					s := acc.String()
+					i := strings.IndexByte(s, '\n')
+					if i < 0 {
+						break
+					}
+					lines <- s[:i]
+					acc.Reset()
+					acc.WriteString(s[i+1:])
+				}
+			}
+			if err != nil {
+				if acc.Len() > 0 {
+					lines <- acc.String()
+				}
+				return
+			}
+		}
+	}()
+
+	t.Cleanup(func() {
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+		_ = r.Close()
+	})
+	return cmd, r, lines
+}
+
+// await drains lines until one contains want, or the deadline passes. It
+// returns everything it saw, so a failure says what the child actually did.
+func await(t *testing.T, lines chan string, want string, d time.Duration) []string {
+	t.Helper()
+	var seen []string
+	deadline := time.After(d)
+	for {
+		select {
+		case l, ok := <-lines:
+			if !ok {
+				t.Fatalf("child output ended before %q; saw:\n%s", want, strings.Join(seen, "\n"))
+			}
+			seen = append(seen, l)
+			if strings.Contains(l, want) {
+				return seen
+			}
+		case <-deadline:
+			t.Fatalf("timed out waiting for %q; saw:\n%s", want, strings.Join(seen, "\n"))
+		}
+	}
+}
+
+// Acceptance 19. Registering only os.Interrupt meant SIGTERM - the signal
+// `docker stop`, Kubernetes and systemd all send - terminated the process
+// before any of the shutdown path ran. Both must now reach it.
+func TestBothSignalsRunTheShutdownPath(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		sig  syscall.Signal
+	}{
+		{"SIGINT", syscall.SIGINT},
+		{"SIGTERM", syscall.SIGTERM},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd, _, lines := startChild(t, false)
+			await(t, lines, markerReady, 30*time.Second)
+
+			if err := cmd.Process.Signal(tc.sig); err != nil {
+				t.Fatalf("signal: %v", err)
+			}
+
+			await(t, lines, markerSignal, 10*time.Second)
+			await(t, lines, markerShutdown, 10*time.Second)
+			await(t, lines, markerExiting, 10*time.Second)
+
+			if err := cmd.Wait(); err != nil {
+				t.Fatalf("child exited with %v, want a clean exit", err)
+			}
+		})
+	}
+}
+
+// Acceptance 20. quit is a buffered channel and signal.Notify stays armed, so
+// without restoring the disposition a second signal only refills the buffer:
+// once SIGTERM is registered, a shutdown that hangs could not be interrupted by
+// anything short of SIGKILL.
+func TestASecondSignalStillKillsAStuckShutdown(t *testing.T) {
+	cmd, _, lines := startChild(t, true)
+	await(t, lines, markerReady, 30*time.Second)
+
+	if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
+		t.Fatalf("first signal: %v", err)
+	}
+	await(t, lines, markerSignal, 10*time.Second)
+
+	// The child is now inside a cleanup that will not finish on its own.
+	if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
+		t.Fatalf("second signal: %v", err)
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+
+	select {
+	case err := <-done:
+		if err == nil {
+			t.Fatal("child exited cleanly; it was supposed to be killed by the second signal")
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("the second signal did not kill a stuck shutdown - the escape hatch is gone")
+	}
+}
+
+// Acceptance 21. srv.Shutdown reports an error exactly when connections were
+// still in flight, and the old code answered that with log.Fatal - an
+// unconditional os.Exit(1). Everything after it, which is where the cleanup
+// hooks will hang, never ran. A failed Shutdown must not end the process.
+func TestShutdownTimeoutDoesNotStopWhatFollows(t *testing.T) {
+	cmd, _, lines := startChild(t, false, childHangConn+"=1")
+	await(t, lines, markerReady, 30*time.Second)
+
+	if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
+		t.Fatalf("signal: %v", err)
+	}
+	await(t, lines, markerSignal, 10*time.Second)
+
+	seen := await(t, lines, markerExiting, 20*time.Second)
+
+	var timedOut bool
+	for _, l := range seen {
+		if strings.Contains(l, "shutdown error:") {
+			timedOut = true
+		}
+	}
+	if !timedOut {
+		t.Fatalf("Shutdown did not time out, so this test proves nothing; saw:\n%s",
+			strings.Join(seen, "\n"))
+	}
+	var cleaned bool
+	for _, l := range seen {
+		if strings.Contains(l, markerCleanup) {
+			cleaned = true
+		}
+	}
+	if !cleaned {
+		t.Fatalf("the BeforeExit callback did not run after a failed Shutdown; saw:\n%s",
+			strings.Join(seen, "\n"))
+	}
+	if err := cmd.Wait(); err != nil {
+		t.Fatalf("child exited with %v after a failed Shutdown, want a clean exit", err)
+	}
+}
+
+// A callback that outlasts its budget must not take the process with it, and
+// must not be waited for: RunShutdown reports the deadline and returns, the
+// callback carries on, and the process still exits cleanly. This is the half of
+// the contract that is easy to get backwards - the context bounds the wait, not
+// the work, because Go cannot cancel a function that does not check for it.
+func TestACleanupThatOutlastsItsBudgetIsAbandonedNotAwaited(t *testing.T) {
+	cmd, _, lines := startChild(t, false, childSlowCleanup+"=1")
+	await(t, lines, markerReady, 30*time.Second)
+
+	if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
+		t.Fatalf("signal: %v", err)
+	}
+	await(t, lines, markerSignal, 10*time.Second)
+
+	// The budget is 300ms and the callback sleeps two seconds. If RunShutdown
+	// waited for it, this marker would not arrive for two seconds; the one
+	// second here is what makes "abandoned, not awaited" the thing asserted.
+	seen := await(t, lines, markerExiting, 1*time.Second)
+
+	var reported bool
+	for _, l := range seen {
+		if strings.Contains(l, "cleanup error:") {
+			reported = true
+		}
+		if strings.Contains(l, markerCleanup) {
+			t.Fatalf("the slow callback finished before the process moved on, so nothing was abandoned; saw:\n%s",
+				strings.Join(seen, "\n"))
+		}
+	}
+	if !reported {
+		t.Fatalf("RunShutdown returned no error for a callback that outlasted the budget; saw:\n%s",
+			strings.Join(seen, "\n"))
+	}
+	if err := cmd.Wait(); err != nil {
+		t.Fatalf("child exited with %v, want a clean exit despite the abandoned callback", err)
+	}
+}

cmd/migrate/migration/init.go

@@ -3,7 +3,6 @@ package migration
 import (
 	"fmt"
 	"log"
-	"path/filepath"
 	"sort"
 	"strings"
 	"sync"
@@ -11,11 +10,21 @@ import (
 
 	"gorm.io/gorm"
 
+	contractmigration "github.com/go-admin-team/go-admin-core/v2/sdk/contract/migration"
+
 	common "go-admin/common/models"
 )
 
 var Migrate = newMigration()
 
+// contractSnapshot is contractmigration.Snapshot, indirected through a
+// package-level variable so tests can substitute an isolated
+// *contractmigration.Registry's Snapshot instead of reaching into
+// go-admin-core's single process-wide registry, which every *Migration in
+// this process - test-local or the package-level Migrate - reads through the
+// same call. See mergedEntries.
+var contractSnapshot = contractmigration.Snapshot
+
 func newMigration() *Migration {
 	return &Migration{version: make(map[string]versionEntry)}
 }
@@ -135,6 +144,47 @@ func namespacedKey(appCode, k string) string {
 	return appCode + "-" + k
 }
 
+// mergedEntries returns every migration this process knows about: the
+// host's own registry (e.version, filled by version/*.go and
+// version-local/*.go through SetVersion/ForApp) plus whatever a third-party
+// application registered through go-admin-core's sdk/contract/migration
+// package (PRD 006, F9's host wiring).
+//
+// That package keeps its own process-wide registry, entirely separate from
+// e.version, because a third-party application cannot reach into this
+// process to call an unexported method on *Migration - contract/migration's
+// package-level ForApp/Snapshot are the only door open to it. Without this
+// merge, migrate/status/--dry-run would only ever see the host's own
+// migrations: an application's ForApp("crm").SetVersion(...) would compile,
+// register successfully into contract/migration's registry, and then never
+// run, with no error anywhere - the exact silent gap this method closes.
+//
+// Entry and versionEntry are structurally identical (an app code plus a
+// func(db, version) error); the conversion below exists only because they
+// are two distinct named types, one per package, not because the data
+// differs.
+func (e *Migration) mergedEntries() map[string]versionEntry {
+	e.mutex.Lock()
+	out := make(map[string]versionEntry, len(e.version))
+	for k, v := range e.version {
+		out[k] = v
+	}
+	e.mutex.Unlock()
+
+	for k, entry := range contractSnapshot() {
+		if _, exists := out[k]; exists {
+			// contract/migration.ForApp namespaces every app-owned key as
+			// appCode + "-" + k, and appCode is reserved from ""/"core", so
+			// this should never collide with a host-registered key. If it
+			// somehow does, the host's own registration wins rather than
+			// silently overwriting it.
+			continue
+		}
+		out[k] = versionEntry{appCode: entry.AppCode, fn: entry.Fn}
+	}
+	return out
+}
+
 // StatusEntry is one row of migrate status.
 type StatusEntry struct {
 	AppCode    string
@@ -156,12 +206,11 @@ func (e *Migration) Status() ([]StatusEntry, error) {
 		return nil, fmt.Errorf("migration: no database configured")
 	}
 
-	e.mutex.Lock()
-	registered := make(map[string]string, len(e.version))
-	for k, v := range e.version {
+	all := e.mergedEntries()
+	registered := make(map[string]string, len(all))
+	for k, v := range all {
 		registered[k] = v.appCode
 	}
-	e.mutex.Unlock()
 
 	applied := make(map[string]common.Migration)
 	// A database that has never been migrated has no sys_migration table.
@@ -247,12 +296,11 @@ func DisplayAppCode(code string) string {
 // AppCodes lists the app codes with at least one registered migration, framework
 // included under its display name, sorted.
 func (e *Migration) AppCodes() []string {
-	e.mutex.Lock()
+	all := e.mergedEntries()
 	seen := map[string]struct{}{}
-	for _, v := range e.version {
+	for _, v := range all {
 		seen[DisplayAppCode(v.appCode)] = struct{}{}
 	}
-	e.mutex.Unlock()
 
 	out := make([]string, 0, len(seen))
 	for code := range seen {
@@ -263,17 +311,16 @@ func (e *Migration) AppCodes() []string {
 }
 
 func (e *Migration) run(appCode string) {
-	e.mutex.Lock()
-	versions := make([]string, 0, len(e.version))
-	entries := make(map[string]versionEntry, len(e.version))
-	for k, v := range e.version {
+	all := e.mergedEntries()
+	versions := make([]string, 0, len(all))
+	entries := make(map[string]versionEntry, len(all))
+	for k, v := range all {
 		if appCode != allApps && v.appCode != appCode {
 			continue
 		}
 		versions = append(versions, k)
 		entries[k] = v
 	}
-	e.mutex.Unlock()
 	sort.Strings(versions)
 
 	// A mistyped --app would otherwise select nothing and report "no
@@ -315,7 +362,10 @@ func (e *Migration) run(appCode string) {
 // from the empty app code, which selects the framework's own migrations.
 const allApps = "\x00all"
 
+// GetFilename derives a migration's version from its file name. The rule
+// lives in contract/migration, because an application registering through
+// that package names its files by the same convention and must land on the
+// same version string; a second copy here is a second thing to keep in step.
 func GetFilename(s string) string {
-	s = filepath.Base(s)
-	return s[:13]
+	return contractmigration.GetFilename(s)
 }

cmd/migrate/migration/init_test.go

@@ -12,9 +12,26 @@ import (
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
 
+	contractmigration "github.com/go-admin-team/go-admin-core/v2/sdk/contract/migration"
+
 	common "go-admin/common/models"
 )
 
+// withContractRegistry points contractSnapshot at an isolated
+// *contractmigration.Registry for the duration of one test, instead of
+// go-admin-core's single process-wide one - see contractSnapshot's doc
+// comment for why that indirection exists. Restored on cleanup so other
+// tests in this package keep seeing an empty contract registry regardless of
+// run order.
+func withContractRegistry(t *testing.T) *contractmigration.Registry {
+	t.Helper()
+	reg := contractmigration.NewRegistry()
+	orig := contractSnapshot
+	contractSnapshot = reg.Snapshot
+	t.Cleanup(func() { contractSnapshot = orig })
+	return reg
+}
+
 func newTestDB(t *testing.T) *gorm.DB {
 	t.Helper()
 	db, err := gorm.Open(sqlite.Open("file:"+t.Name()+"?mode=memory&cache=shared"), &gorm.Config{
@@ -388,3 +405,178 @@ func TestMigrateAppOnAnUnknownCodeSaysSo(t *testing.T) {
 		t.Errorf("a typo ran %v", rows)
 	}
 }
+
+// This is the acceptance test for PRD 006's host-wiring gap: a migration
+// registered through contract/migration.ForApp - the only door open to a
+// third-party application - must actually run, be recorded under its app
+// code, and show up in AppCodes/Status/--app the same as one registered
+// through the host's own m.ForApp. Before mergedEntries existed, m.Migrate()
+// never looked at contract/migration's registry at all, so this compiled,
+// registered, and silently never ran.
+func TestMergedEntriesRunsAContractRegisteredAppMigration(t *testing.T) {
+	reg := withContractRegistry(t)
+	db := newTestDB(t)
+	m := newMigration()
+	m.SetDb(db)
+
+	ran := false
+	reg.ForApp("order").SetVersion("1793800000000", func(db *gorm.DB, version, appCode string) error {
+		ran = true
+		return recordFor(db, version, appCode)
+	})
+
+	m.Migrate()
+
+	if !ran {
+		t.Fatal("contract-registered migration did not run")
+	}
+	rows := rowsByVersion(t, db)
+	row, ok := rows["order-1793800000000"]
+	if !ok {
+		t.Fatalf("no row for order-1793800000000; got %v", rows)
+	}
+	if row.AppCode != "order" {
+		t.Errorf("app_code = %q, want %q", row.AppCode, "order")
+	}
+}
+
+// migrate status and --dry-run both read Status; a contract-registered
+// migration has to appear there under its app code exactly like a
+// host-registered one, both before and after it is applied.
+func TestMergedEntriesStatusIncludesContractRegisteredMigrations(t *testing.T) {
+	reg := withContractRegistry(t)
+	db := newTestDB(t)
+	m := newMigration()
+	m.SetDb(db)
+
+	reg.ForApp("order").SetVersion("1793800000000", func(db *gorm.DB, version, appCode string) error {
+		return recordFor(db, version, appCode)
+	})
+
+	entries, err := m.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	byVersion := map[string]StatusEntry{}
+	for _, e := range entries {
+		byVersion[e.Version] = e
+	}
+	e, ok := byVersion["order-1793800000000"]
+	if !ok || !e.Registered || e.Applied || e.AppCode != "order" {
+		t.Fatalf("pending contract entry = %+v (ok=%v)", e, ok)
+	}
+
+	m.Migrate()
+
+	entries, err = m.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	byVersion = map[string]StatusEntry{}
+	for _, e := range entries {
+		byVersion[e.Version] = e
+	}
+	if e := byVersion["order-1793800000000"]; !e.Applied {
+		t.Errorf("applied contract entry = %+v", e)
+	}
+}
+
+// AppCodes feeds both --app's typo detection (appRegistrationError) and the
+// group headings status prints; a contract-registered app has to appear
+// there or a real "go-admin migrate --app order" would be told the app does
+// not exist.
+func TestMergedEntriesAppCodesIncludesContractRegisteredApps(t *testing.T) {
+	reg := withContractRegistry(t)
+	m := newMigration()
+	m.SetVersion("1786700009000", func(db *gorm.DB, version string) error { return nil })
+	reg.ForApp("order").SetVersion("1793800000000", func(db *gorm.DB, version, appCode string) error { return nil })
+
+	got := m.AppCodes()
+	want := []string{"core", "order"}
+	if len(got) != len(want) {
+		t.Fatalf("AppCodes = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("AppCodes = %v, want %v", got, want)
+		}
+	}
+}
+
+// --app order has to actually run only order's migrations - the same
+// per-app isolation MigrateApp already gives host-registered apps - even
+// though order is registered in a different registry entirely.
+func TestMergedEntriesMigrateAppRunsOnlyThatContractApp(t *testing.T) {
+	reg := withContractRegistry(t)
+	db := newTestDB(t)
+	m := newMigration()
+	m.SetDb(db)
+
+	ran := map[string]bool{}
+	m.SetVersion("1786700009000", func(db *gorm.DB, version string) error {
+		ran["core"] = true
+		return db.Create(&common.Migration{Version: version}).Error
+	})
+	reg.ForApp("order").SetVersion("1793800000000", func(db *gorm.DB, version, appCode string) error {
+		ran["order"] = true
+		return recordFor(db, version, appCode)
+	})
+
+	m.MigrateApp("order")
+
+	if !ran["order"] {
+		t.Error("order did not run")
+	}
+	if ran["core"] {
+		t.Errorf("MigrateApp(order) also ran %v", ran)
+	}
+}
+
+// A host-registered key is not supposed to collide with a namespaced
+// contract key (see mergedEntries' doc comment), but if it somehow did, the
+// host's own registration must win rather than a third-party application
+// silently overwriting a framework migration under the same key.
+func TestMergedEntriesHostRegistrationWinsOnKeyCollision(t *testing.T) {
+	reg := withContractRegistry(t)
+	db := newTestDB(t)
+	m := newMigration()
+	m.SetDb(db)
+
+	hostRan, contractRan := false, false
+	m.ForApp("dup").SetVersion("1786800001000", func(db *gorm.DB, version, appCode string) error {
+		hostRan = true
+		return recordFor(db, version, appCode)
+	})
+	reg.ForApp("dup").SetVersion("1786800001000", func(db *gorm.DB, version, appCode string) error {
+		contractRan = true
+		return recordFor(db, version, appCode)
+	})
+
+	m.Migrate()
+
+	if !hostRan {
+		t.Error("host registration did not run")
+	}
+	if contractRan {
+		t.Error("contract registration ran; host registration should have won the collision")
+	}
+}
+
+// GetFilename must stay the same rule the contract package applies, since an
+// application registering through contract/migration names its files by that
+// convention and has to land on the same version string. Pinning the reject
+// case is what catches a re-divergence: a local copy that only sliced would
+// return "add_orders.go" here and register a migration under a key that never
+// matches anything.
+func TestGetFilenameDelegatesToTheContractRule(t *testing.T) {
+	if got := GetFilename("version/1786700001000_demo_menu.go"); got != "1786700001000" {
+		t.Fatalf("GetFilename = %q, want %q", got, "1786700001000")
+	}
+
+	defer func() {
+		if recover() == nil {
+			t.Fatal("a file name carrying no version did not panic")
+		}
+	}()
+	GetFilename("version/add_orders.go")
+}

cmd/migrate/migration/version/1786700006000_app_code_columns.go

@@ -0,0 +1,46 @@
+package version
+
+import (
+	"runtime"
+
+	"gorm.io/gorm"
+
+	adminmodels "go-admin/app/admin/models"
+	"go-admin/cmd/migrate/migration"
+	common "go-admin/common/models"
+)
+
+// Add sys_menu.app_code and sys_api.app_code ahead of PRD 006 F9's Seeder.
+//
+// Every row a third-party application's migration writes through
+// seed.SeedMenus must be attributable to the app that wrote it, so
+// installing, auditing, or removing one application does not require
+// guessing which rows belong to it - see go-admin-core's docs/contract.md,
+// "Application-supplied menu and API entries", for the requirement this
+// satisfies.
+//
+// Ordered after 1786700003000, so importing cmd/migrate/migration/models is
+// banned here (see schema_coverage_test.go's
+// TestPostConversionMigrationsAvoidFrozenSeedModels): AddColumn instead
+// reads the runtime models' own gorm tags directly, which is also what
+// makes the column this adds match the one the admin Seeder writes through
+// those same structs.
+func init() {
+	_, fileName, _, _ := runtime.Caller(0)
+	migration.Migrate.SetVersion(migration.GetFilename(fileName), _1786700006000AppCodeColumns)
+}
+
+func _1786700006000AppCodeColumns(db *gorm.DB, version string) error {
+	m := db.Migrator()
+	if !m.HasColumn(&adminmodels.SysMenu{}, "AppCode") {
+		if err := m.AddColumn(&adminmodels.SysMenu{}, "AppCode"); err != nil {
+			return err
+		}
+	}
+	if !m.HasColumn(&adminmodels.SysApi{}, "AppCode") {
+		if err := m.AddColumn(&adminmodels.SysApi{}, "AppCode"); err != nil {
+			return err
+		}
+	}
+	return db.Create(&common.Migration{Version: version}).Error
+}

common/storage/initialize.go

@@ -9,10 +9,11 @@ package storage
 
 import (
 	"log"
+	"sync"
 
+	"github.com/go-admin-team/go-admin-core/v2/captcha"
 	"github.com/go-admin-team/go-admin-core/v2/sdk"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
-	"github.com/go-admin-team/go-admin-core/v2/captcha"
 )
 
 // Setup 配置storage组件
@@ -34,17 +35,65 @@ func setupCaptcha() {
 	captcha.SetStore(captcha.NewCacheStore(sdk.Runtime.GetCacheAdapter(), 600))
 }
 
+var (
+	queueMu sync.Mutex
+	// installed is the adapter setupQueue built, kept so the next reload can
+	// shut it down, and counted so a consumer can tell one from the next.
+	installed    interface{ Shutdown() }
+	installedGen uint64
+)
+
+// QueueGeneration reports how many times this package has installed a queue
+// adapter. It changes every time setupQueue builds a new one, which is on
+// every configuration reload, and stays 0 for as long as the configuration has
+// no queue section at all - in which case nothing is installed and callers are
+// working with the runtime's own fallback queue.
+//
+// It exists because there is no way to ask for the adapter's identity from the
+// outside. sdk.Runtime.GetQueueAdapter and GetQueuePrefix build a fresh
+// runtime.Queue wrapper on every call, so comparing what two calls return
+// compares two wrappers and never matches, however many times the underlying
+// adapter has been replaced. This package creates the adapter, so this is the
+// only place that knows. A counter rather than the adapter itself keeps the
+// comparison on a uint64: an adapter type that is not comparable would panic
+// an `==` between two interface values.
+func QueueGeneration() uint64 {
+	queueMu.Lock()
+	defer queueMu.Unlock()
+	return installedGen
+}
+
 func setupQueue() {
 	if config.QueueConfig.Empty() {
 		return
 	}
-	if q := sdk.Runtime.GetQueueAdapter(); q != nil {
-		q.Shutdown()
+
+	queueMu.Lock()
+	defer queueMu.Unlock()
+
+	// Only an adapter this package installed. GetQueueAdapter never returns
+	// nil - with nothing configured the runtime falls back to its own memory
+	// queue and wraps that - so the `if q := GetQueueAdapter(); q != nil` this
+	// replaces was always true, and shut down the fallback queue on the very
+	// first start, before anything had used it.
+	if installed != nil {
+		installed.Shutdown()
 	}
+
 	queueAdapter, err := config.QueueConfig.Setup()
 	if err != nil {
 		log.Fatalf("queue setup error, %s\n", err.Error())
 	}
 	sdk.Runtime.SetQueueAdapter(queueAdapter)
-	go queueAdapter.Run()
+	installed = queueAdapter
+	installedGen++
+
+	// Deliberately not started here. Run has to come after the consumers have
+	// registered: the contract implementations refuse a registration once the
+	// queue is running (storage.ErrQueueAlreadyStarted), and the legacy
+	// adapter this repository still goes through swallows that error rather
+	// than reporting it - its own comment says the interface gives it no way
+	// to tell the caller. Starting here and registering afterwards is
+	// therefore a race that loses consumers in silence. Whoever registers is
+	// the one that starts it.
 }

common/storage/queue_redis_test.go

@@ -0,0 +1,130 @@
+package storage
+
+import (
+	"errors"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+	corestorage "github.com/go-admin-team/go-admin-core/v2/storage"
+	"github.com/go-admin-team/go-admin-core/v2/storage/queue"
+)
+
+// redisAddrEnv points these tests at a server. They are skipped without it, so
+// a developer with no redis running still gets a green run - and CI sets it,
+// which is the point: the ordering rule they cover is invisible on the memory
+// backend, and memory is the default. A suite that only ever exercised the
+// default would report success for a queue that silently drops every consumer.
+const redisAddrEnv = "GO_ADMIN_TEST_REDIS_ADDR"
+
+func redisAddr(t *testing.T) string {
+	t.Helper()
+	addr := os.Getenv(redisAddrEnv)
+	if addr != "" {
+		return addr
+	}
+	// Skipping locally is the point; skipping in CI is the failure this whole
+	// file exists to prevent. A workflow that renamed the variable, or dropped
+	// the service, would otherwise go green while these two tests quietly did
+	// nothing - which is the same shape as the defect they cover.
+	if os.Getenv("CI") != "" {
+		t.Fatalf("%s is not set while CI is: the redis-backed queue tests must not skip here", redisAddrEnv)
+	}
+	t.Skipf("%s is not set; skipping the redis-backed queue tests", redisAddrEnv)
+	return ""
+}
+
+// newRedisQueue builds the queue the same way setupQueue does - through
+// config.QueueConfig.Setup - so that what is under test is the adapter this
+// repository actually gets, LegacyQueueAdapter and all, rather than a redis
+// client wired up by the test.
+func newRedisQueue(t *testing.T, prefix string) corestorage.AdapterQueue {
+	t.Helper()
+	previous := config.QueueConfig
+	t.Cleanup(func() { config.QueueConfig = previous })
+
+	config.QueueConfig = &config.Queue{
+		Redis: &config.RedisQueue{
+			RedisOptions: config.RedisOptions{Addr: redisAddr(t)},
+			Group:        prefix,
+			KeyPrefix:    prefix,
+		},
+	}
+	q, err := config.QueueConfig.Setup()
+	if err != nil {
+		t.Fatalf("queue setup: %v", err)
+	}
+	t.Cleanup(q.Shutdown)
+	return q
+}
+
+func message(t *testing.T, stream string) corestorage.Messager {
+	t.Helper()
+	m := &queue.Message{}
+	m.SetStream(stream)
+	m.SetValues(map[string]interface{}{"hello": "world"})
+	return m
+}
+
+// Registered first, then started: the consumer gets the message. This is the
+// order setupQueue and attachQueueConsumers now produce between them.
+func TestRedisQueueDeliversToAConsumerRegisteredBeforeTheStart(t *testing.T) {
+	stream := "t-ordered"
+	q := newRedisQueue(t, "gotest-ordered")
+
+	got := make(chan struct{}, 1)
+	q.Register(stream, func(corestorage.Messager) error {
+		select {
+		case got <- struct{}{}:
+		default:
+		}
+		return nil
+	})
+	go q.Run()
+
+	// Give Start a moment to reach its read loop before publishing.
+	time.Sleep(500 * time.Millisecond)
+	if err := q.Append(message(t, stream)); err != nil {
+		t.Fatalf("append: %v", err)
+	}
+
+	select {
+	case <-got:
+	case <-time.After(15 * time.Second):
+		t.Fatal("the consumer never received the message")
+	}
+}
+
+// Started first, then registered: the registration is refused and every
+// publish afterwards fails.
+//
+// Subscribe answers ErrQueueAlreadyStarted, and LegacyQueueAdapter.Register
+// returns nothing, so the caller cannot know - that part is silent. What is not
+// silent is the consequence: no consumer group was created, so Publish refuses
+// the topic with ErrNoHandler on every single request, and go-admin's call
+// sites log that at error level while the login and operation log rows are
+// never written.
+//
+// This is the test the memory backend cannot provide. queue.Memory's Register
+// starts another consumer goroutine whatever the state, so the same code passes
+// there - which is how the defect survived, memory being the default.
+func TestRedisQueueRefusesAConsumerRegisteredAfterTheStart(t *testing.T) {
+	stream := "t-late"
+	q := newRedisQueue(t, "gotest-late")
+
+	go q.Run()
+	time.Sleep(500 * time.Millisecond)
+
+	q.Register(stream, func(corestorage.Messager) error { return nil })
+
+	err := q.Append(message(t, stream))
+	if err == nil {
+		t.Fatal("a message was accepted for a topic whose registration came after Start; " +
+			"if the backend now accepts late registration, the ordering rule in setupQueue can be revisited")
+	}
+	if !errors.Is(err, corestorage.ErrNoHandler) {
+		t.Fatalf("append failed with %v, want %v - the test is meant to pin the "+
+			"missing-consumer path, not any error at all", err, corestorage.ErrNoHandler)
+	}
+}

docs/contract.md

@@ -1,64 +1,453 @@
 # 公共契约面
 
 > 本文写给**第三方应用作者**：你写一个装进 go-admin 的业务模块，可以依赖什么、
-> 怎么注册进来、哪些东西随时可能变。
+> 怎么接进来、哪些约定不遵守会**不报错地出错**。
 >
 > 主仓贡献者的编码约定见根目录 `AGENTS.md`，设计取舍见 `docs/architecture.md`。
 
 ---
 
-## 承诺稳定的包
+## 契约面在 core，不在 go-admin
 
-| 包 | 用途 |
-|---|---|
-| `common/actions` | 通用 CRUD Action（Index / View / Create / Update / Delete / Permission） |
-| `common/dto` | 分页、`search` tag 解析、`Control` / `Index` 接口 |
-| `common/models` | `ActiveRecord`、`ControlBy`、`ModelTime`、`Model` |
-| `common/middleware` | `AuthCheckRole`、`InitMiddleware` 等 |
+这份文档以前列的是 go-admin 自己的四个包（`common/actions` 等），依据写的是
+「把 `app/demo` 的 import 去重之后恰好就是这四个」。
 
-**依据不是拍脑袋列的**：`app/demo` 是一个可编译、有测试、CI 会跑的标准 CRUD 模块，
-把它的 `go-admin/` 前缀 import 全部去重之后，恰好就是这四个包 —— 它代表
-"写一个标准模块所需要的最小依赖面"。你的模块如果需要第五个包，先在 issue 里说一声，
-那多半意味着契约面缺了什么。
+**那个依据是错的，而且错的方向是把人引向依赖宿主。**
 
-"稳定"的含义：**在 `2.x` 内不做破坏性变更**。新增导出符号不算破坏；改签名、
-改语义、删除导出符号算，会走 major 版本并在 release note 里单列。
+go-admin 的使用方式是 clone / fork：每个使用者拿到的是一整份代码，然后**改它**。
+应用如果依赖 `go-admin/common/actions`，它依赖的是一个**每个使用者都不一样、
+而且随时在变**的东西——你没有办法测试自己的应用在别人改过的 fork 上能不能编译。
 
-### 没有已知例外
+还有一条更硬的：`go-admin` 这个 module path 没有点号，
+按 Go 的规则**不是合法的可解析模块路径**：
 
-这四个包**不 import `app/` 下的任何东西**，2026-08-31 起由 CI 强制
-（见下方「边界由 CI 守着」）。在此之前有两处反向依赖，都已根治：
+```
+$ go get go-admin/common/models
+go: malformed module path "go-admin/common/models": missing dot in first path element
+```
 
-| 原位置 | 反向依赖 | 处理 |
-|---|---|---|
-| `common/middleware/logger.go` | `app/admin/service/dto` 的两个操作日志状态常量 | 常量下沉到 `common/global`，`dto` 侧保留同名常量作为 deprecated 别名，fork 不受影响 |
-| `common/middleware/handler/auth.go` | `app/admin/models` 的 `SysUser` / `SysRole` | 该段断言恒失败、设的是零值且开源版无人读取，属死代码，已删除 |
+想 import 它就必须写 `replace`，而**非主模块的 `replace` 会被忽略**——
+你在自己应用里写的 replace 对使用者不生效。所以「应用 require go-admin」
+这条路不是不优雅，是走不通。
 
-之所以不把它们记成"已知例外"：这份文档的作用就是告诉你哪些包可以依赖，
-如果第一条下面就挂着例外脚注，后来人会照着例外抄，边界从第一天起就是脏的。
+契约面因此落在 **go-admin-core**：那是唯一一个大家都一样、有版本号、
+不会被使用者随手改的东西。
 
 ---
 
-## 其余包不保证稳定
+## 承诺稳定的包
 
-`common/` 下没有出现在上表里的包（`common/global`、`common/storage`、
-`common/database`、`common/file_store`、`common/response`、`common/service`、
-`common/apis`、`common/middleware/handler`、根 `common` 包……）以及
-`app/admin` 的内部实现，**均不承诺稳定**。
+全部在 `github.com/go-admin-team/go-admin-core/v2` 下：
 
-其中 `common/global`、`common/middleware/handler`、根 `common` 包是
-`common/middleware` 的编译期依赖 —— 它们会被一起拉进你的依赖图，但这不代表
-它们的 API 稳定。**不要因为"都在 `common/` 目录下"就认为是契约面。**
+| 包 | 用途 |
+|---|---|
+| `sdk/contract/models` | `Model` / `ControlBy` / `ModelTime` / `ActiveRecord` / `BaseUser` / `Migration`、`sys_menu.menu_type` 的三个枚举值 |
+| `sdk/contract/dto` | `Pagination` / `MakeCondition` / `Paginate` / `OrderDest` / `ObjectById`、`Index` 与 `Control` 接口 |
+| `sdk/contract/actions` | 数据权限设施：`DataPermission` / `Permission` / `PermissionAction` / `GetPermissionFromContext`、五个 `DataScope*` 常量与 `IsValidDataScope` |
+| `sdk/contract/migration` | `Registry` / `AppRegistrar` / `ForApp` / `SetVersion` / `GetFilename` |
+| `sdk/contract/seed` | `MenuSpec` / `ApiSpec` / `Seeder` / `SeedMenus`——往侧边栏和接口表里登记自己 |
+| `sdk/pkg` | `GetOrm(c)`：从请求上下文取本租户的数据库连接 |
+| `sdk/api`、`sdk/service` | 可选的 Api / Service 基类 |
+| `response` | `OK` / `Error` / `PageOK`：响应格式 |
+| `jwtauth/user` | 从 token 取当前用户身份 |
+| `sdk/runtime` | 中间件 key 常量与 `GetHandlerFunc`：复用宿主已注册的鉴权链 |
 
-规划中的 001（模块路径改名）会把非契约包移进 `internal/`，由编译器强制这条边界。
-届时上表之外的包对外部模块直接不可见 —— 现在就照上表写，那次改动对你零成本。
+`sdk/contract/` 这个前缀的含义就是「**承诺对应用稳定**的那一面」。core 里
+`sdk/` 下的其他包是框架基础设施，语义不同——上表逐个列了名字，
+**不要因为「都在 core 里」就认为是契约面**。
+
+"稳定"的含义：**在 core 的 `v2.x` 内不做破坏性变更**。新增导出符号不算破坏；
+改签名、改语义、删除导出符号算，会走 major 版本并在 release note 里单列。
+
+准确的语义以 core 那份文档为准：
+[go-admin-core `docs/contract.md`](https://github.com/go-admin-team/go-admin-core/blob/main/docs/contract.md)。
+本文写的是宿主这一侧——它管不着的那些。
+
+### go-admin 自己的包
+
+`go-admin/common/models`、`common/dto`、`common/actions` 里的契约类型现在是
+**指向 core 的类型别名**（`type X = corepkg.X`），主仓和所有 fork 的存量代码
+一行不用改。别名在编译期就是同一个类型，不是"兼容层"。
+
+但**新写的应用不要 import 它们**——那样就又依赖上宿主了。
+
+---
+
+## 契约面是三层，不是一层
+
+划分依据不是"应用会 import 哪些包"，而是**"哪一条不遵守会静默出错"**：
+
+| 层 | 内容 | 判据 |
+|---|---|---|
+| **一 · 必须遵守** | 路由注册、从 context 取库、响应 shape、`ControlBy`/`ModelTime`、鉴权、数据权限、事务范式 | 不遵守 → **不报错，行为悄悄不对** |
+| **二 · 可选便利** | `api.Api`、`service.Service`、CRUD Action、`MakeCondition` | 用不用都对 |
+| **三 · 今天空白** | 应用间调用、领域事件、缓存租户隔离 | **没有。别自己发明** |
+
+**框架不强制任何一层抽象。** 一个不用任何便利层的 handler 完全合法：
+
+```go
+func handler(c *gin.Context) {
+    db, err := pkg.GetOrm(c)
+    if err != nil {
+        response.Error(c, 500, err, "")
+        return
+    }
+    var list []MyModel
+    if err := db.Find(&list).Error; err != nil {
+        response.Error(c, 500, err, "")
+        return
+    }
+    response.OK(c, list, "")
+}
+```
+
+第一层则是不管你用不用便利层都要遵守的，逐条写在下面，每条都附**不遵守会怎样**。
+
+---
+
+## 第一层：不遵守就静默出错
+
+### 1. 路由注册
+
+见下方「注册路由」一节。
+
+**不遵守会怎样**：注册表在 `RunAppRouters()` 之后就封闭了，晚到的注册被丢弃，
+只记一条 ERROR 日志。包级 `AppRouters` 连这个都没有——它就是一个普通 slice，
+什么时候 append 都"成功"，启动钩子之后 append 的那些永远不会执行，**且不出声**。
+
+### 2. 数据库连接从 context 取，不用全局变量
+
+```go
+db, err := pkg.GetOrm(c)          // 唯一正确的取法
+```
+
+`common/middleware/db.go` 在每个请求上按 `c.Request.Host` 挑出本租户的连接
+放进 context：
+
+```go
+c.Set("db", sdk.Runtime.GetDbByTenant(c.Request.Host).WithContext(c))
+```
+
+**不遵守会怎样**：连接是**按租户注册**的（`SetDbByTenant(host, db)`），
+`GetOrm(c)` 按 `c.Request.Host` 挑。你要是在启动时把某个连接存进包级变量再一直用，
+多租户部署下所有租户的读写就都落到那一个库上——不报错、不告警，数据串了才发现。
+
+这个坑在本仓库真踩过：`common/global.Driver` 取的是启动循环
+**迭代到的第一个**库的驱动（`common/database/initialize.go`），
+而 Go 的 map 迭代顺序是随机的——两个库用不同驱动时，那个值每次启动都可能不一样。
+所以「一个进程一个库」这个假设不要写进任何一行代码。
+
+### 3. 响应 shape
+
+一律用 `response.OK` / `response.Error` / `response.PageOK`，不要自己
+`c.JSON`。它们发出去的形状是：
+
+```jsonc
+// 成功
+{"requestId": "...", "code": 200, "data": {...}}
+// 分页：data 里再套一层
+{"requestId": "...", "code": 200, "data": {"count": 42, "pageIndex": 1, "pageSize": 10, "list": [...]}}
+// 失败
+{"requestId": "...", "code": 500, "msg": "...", "status": "error"}
+```
+
+**HTTP 状态码永远是 200**，业务码在 body 的 `code` 里——这是既定行为，
+`response.Error` 走的是 `c.AbortWithStatusJSON(http.StatusOK, res)`。
+
+**不遵守会怎样**：前端 `src/utils/request.ts` 的响应拦截器只读 body 的 `code`，
+`code !== 200` 就弹一条 `msg` 内容的 error toast 并 reject。你自己
+`c.JSON(200, myThing)` 的话 `code` 是 `undefined`，界面上弹出来的是**一条空的
+错误提示**，数据到不了页面。列表更安静：`useTable.ts` 读的是
+`page?.list ?? []` 和 `page?.count ?? 0`，形状对不上就是**一张空表，零报错**。
+
+### 4. `ControlBy` 与 `ModelTime`
+
+每张业务表的 model 都嵌这三个：
+
+```go
+type Order struct {
+    models.Model        // Id
+    // ... 你的字段 ...
+    models.ControlBy    // CreateBy / UpdateBy
+    models.ModelTime    // CreatedAt / UpdatedAt / DeletedAt
+}
+
+func (Order) TableName() string { return "app_order" }   // 必须显式声明
+```
+
+`ControlBy` 提供 `create_by` 列，**数据权限的每一条 SQL 都 join 在它上面**。
+`ModelTime` 的 `DeletedAt` 是 `soft_delete.DeletedAt`（毫秒时间戳，活行为 0，
+永不为 NULL），不是 `gorm.DeletedAt`。
+
+**不遵守会怎样**：
+
+- 嵌了 `ControlBy` 但写入时忘了 `SetCreateBy(user.GetUserId(c))`，
+  `create_by` 就是 0。除「全部数据权限」外的每一档都**查不到任何数据**，
+  而且不报错——看起来像"这个用户还没建过数据"。
+- 用错 `ModelTime` 版本（可空的 `gorm.DeletedAt`）：gorm 按
+  `deleted_at IS NULL` 过滤，而活行里存的是 0，于是**整张表一行都查不出来**。
+  主仓的 `sys_columns` / `sys_tables` 真在这个状态下待过——代码生成器
+  一张表都列不出来，没有任何报错。`make checksilent` 的 `modeltime-mix`
+  就是为这条加的。
+- `TableName()` 忘了写：GORM 配了 `SingularTable`，不会推导复数，表名会是
+  你没预料的那个。
+
+### 5. 鉴权：用宿主已注册的中间件，不要自己造
+
+```go
+jwtCheck, ok := sdk.Runtime.GetHandlerFunc(runtime.JwtTokenCheck)
+if !ok {
+    log.Fatal("JwtTokenCheck is not registered; is the host started via cmd/api?")
+}
+roleCheck, _ := sdk.Runtime.GetHandlerFunc(runtime.RoleCheck)
+permCheck, _ := sdk.Runtime.GetHandlerFunc(runtime.PermissionCheck)
+
+g := v1.Group("/order").Use(jwtCheck).Use(roleCheck).Use(permCheck)
+```
+
+三个 key 的常量在 `sdk/runtime`，宿主启动时把三个中间件注册进去。
+
+**不遵守会怎样**：`GetHandlerFunc` 在"没注册"和"注册成了别的类型"两种情况下
+都返回 `ok=false` 而不是 panic——**因为路由注册跑在 core 的 panic 护栏里面，
+裸类型断言 panic 之后日志报的是"这个模块一条路由都没注册上"，跟真实原因对不上**。
+所以 `ok` 必须自己判，判出来要**大声失败**：一个跳过鉴权继续注册的路由，
+就是一条静默的匿名可访问接口。
+
+**宿主必须注册绑定过的闭包。** 三个 key 存的都得是 `gin.HandlerFunc`——
+比如 `authMiddleware.MiddlewareFunc()`，**不是** `(*jwt.GinJWTMiddleware).MiddlewareFunc`。
+后者是方法表达式，没有接收者绑在上面，取回来断言不成 `gin.HandlerFunc`，
+怎么断言都做不成一个能用的 handler。
+
+> **当前状态**：`common/middleware/init.go` 里 `RoleCheck` 与 `PermissionCheck`
+> 注册的是 `AuthCheckRole()` 和 `actions.PermissionAction()`，都是绑定过的闭包，
+> 取回来就能用；**`JwtTokenCheck` 注册的还是那个方法表达式**，所以今天对它
+> `GetHandlerFunc` 拿到的是 `ok=false`。上面那段 `log.Fatal` 会在启动时打出来——
+> 这是有意的，宁可起不来也不要一条没鉴权的路由。主仓这一处的修复见 F10，
+> 修完之后本段可以删掉。
+
+还有一条**不影响行为但影响理解**的：主仓今天四个模块各自调一次 `AuthInit()`
+（`app/admin`、`app/jobs`、`app/other`、`app/demo`），也就是有四个 JWT 实例。
+这不产生行为差异——配置同源（`config.JwtConfig`），JWT 校验是无状态的，
+不看实例身份。但它意味着 `GetHandlerFunc(runtime.JwtTokenCheck)` 取回来的是
+**最后注册进去的那一个**。要让应用拿到一个有意义的共享实例，宿主应当在注册路由
+之前构造一次，而不是每个模块构造一次。
+
+**测的时候别用 `admin` 账号。** `AuthCheckRole` 里 `rolekey == "admin"` 直接
+`c.Next()`，**完全跳过 Casbin**。拿 admin 压任何鉴权路径都测不到东西。
+
+### 6. 数据权限
+
+两件事都要做：
+
+```go
+// 路由上挂中间件（上一节的 permCheck 就是它）
+g := v1.Group("/order").Use(permCheck)
+
+// 查询里组合 scope
+p := actions.GetPermissionFromContext(c)
+db.Scopes(actions.Permission(Order{}.TableName(), p)).Find(&list)
+```
+
+`sys_role.data_scope` 有五档，`Permission()` 按它拼 WHERE 条件：
+
+| 值 | 常量 | 含义 | 条件 |
+|---|---|---|---|
+| `1` | `DataScopeAll` | 全部数据权限 | 不加条件 |
+| `2` | `DataScopeCustom` | 自定义数据权限 | `create_by` 属于 `sys_role_dept` 关联到的部门 |
+| `3` | `DataScopeDept` | 本部门 | `create_by` 属于本部门 |
+| `4` | `DataScopeDeptTree` | 本部门及以下 | `create_by` 属于 `dept_path` 匹配的子树 |
+| `5` | `DataScopeSelf` | 仅本人 | `create_by = 当前用户` |
+
+自己往 `sys_role.data_scope` 写值的话先过一遍 `IsValidDataScope`——
+写进去的非法值不会在写入时报错，只会在**每一次查询**里静默地什么都查不到。
+
+**不遵守会怎样**，两种漏法的方向相反，值得分清：
+
+- **查询里忘了组合 `Permission()`** —— 就是**全量可见**，每个角色都看得到所有人
+  的数据，不报错、不记日志。**这是本框架里最贵的一类静默失败**，所以那一行
+  `db.Scopes(...)` 不是"最佳实践"，是契约。
+- **组合了 `Permission()` 但路由上漏挂中间件** —— 上下文里没有 `PermissionKey`，
+  拿到的是零值，`DataScope` 是空串，落进下面那个 fail-closed 的 default，
+  结果是**一行都查不到**。方向反了，至少还看得见。
+
+五档之外的值（空串、拼错的、还没迁移的老数据）落到 `default` 分支，
+那里是 **fail closed**：加一条 `1 = 0`，什么都不返回。注意 `1`（全部数据权限）
+是**显式列出的一个 case**，不是"落到 default"——两者曾经是同一条路，
+于是"没配置"和"配置成看全部"产出的 SQL 一个字都不差。
+
+`3` / `4` 两档在 `DeptId <= 0` 时同样 fail closed。原因是
+`sys_dept.dept_path` 一律以 `/0/` 开头，`dept_id=0` 会把 LIKE 模式变成
+`'%/0/%'`，**命中全表**——本来想表达"没有部门"，实际表达的是"全部部门"。
+
+数据权限还有一个**全局开关** `application.enabledp`，默认是 `false`。
+关掉时 `Permission()` 原样返回查询、`PermissionAction()` 直接放行——
+**你的应用在默认配置下测不出数据权限的任何行为**，要验证得先把它打开。
+
+**不要自己重写这段 SQL。** 那 20 行里埋着 8 项内部知识：JWT claims 的私有键名
+（`datascope` / `deptid`）、`sys_user`↔`sys_role` 的 join、`sys_role_dept`
+关联表、`sys_dept.dept_path` 的 `/0/1/2/` 编码、`create_by` 的归属约定、
+`enabledp` 开关、老 token 的回落逻辑。**而且写错的方向是越权。**
+仓库里有过一份第二实现，`dept_path` 的匹配写成 `"%"+id+"%"` 少了两个斜杠，
+`dept_id=1` 会匹配上 `/11/`、`/21/`、`/100/`——写它的人比第三方更懂这套约定，
+仍然写错了。那份实现已经删掉了。
+
+### 7. 事务范式
+
+**业务层的事务一律用 `Transaction()` 闭包形式**：
+
+```go
+err := db.Transaction(func(tx *gorm.DB) error {
+    if err := tx.Create(&order).Error; err != nil {
+        return err   // rolled back
+    }
+    return tx.Model(&stock).Where("qty >= ?", n).
+        UpdateColumn("qty", gorm.Expr("qty - ?", n)).Error
+})
+```
+
+GORM 自己处理提交、回滚，以及 **panic 时的回滚**。
+
+**不要照抄 `app/admin/service/sys_role.go`。** 那里有 5 处手写的
+`Begin` / `defer` 写法，三个缺陷都是静默的：
+
+```go
+tx := e.Orm
+if config.DatabaseConfig.Driver != "sqlite3" {   // 缺陷 2
+    tx = e.Orm.Begin()
+    defer func() {
+        if err != nil { tx.Rollback() } else { tx.Commit() }   // 缺陷 1
+    }()
+}
+```
+
+1. **panic 时提交半截事务**——defer 只看 `err`，panic 时 `err` 仍是 nil，走的是
+   `Commit()`
+2. **sqlite 下根本不开事务**——那一整个特判让 `tx` 就是 `e.Orm` 本身，
+   写一半失败留一半
+3. **读 `config.DatabaseConfig.Driver`**——那是全局单库配置，多租户下不是
+   当前租户的驱动
+
+缺陷 1 不止那一处：`app/admin/service/sys_dept.go`、`sys_menu.go`、
+`app/other/models/tools/sys_tables.go` 用的是同一个 `defer` 写法
+（没有 sqlite 特判，所以只有缺陷 1）。**整个 `Begin`/`defer` 家族都别照抄。**
+
+同一个仓库里就有正确的参照：`cmd/migrate/migration/version/` 下 7 个迁移里
+5 个用的是闭包形式（另外两个是纯 DDL 标记，DDL 在 MySQL 下本来就不进事务），
+且这条路在 sqlite 下实测跑得通（`make build-sqlite`）。
+主仓那些写法本批次不改，单独跟。
+
+**并发保护用条件更新 + `RowsAffected`**，不要"先查后改"：
+
+```go
+res := tx.Model(&Order{}).Where("id = ? AND status = ?", id, StatusPending).
+    Update("status", StatusPaid)
+if res.Error != nil { return res.Error }
+if res.RowsAffected == 0 { return ErrAlreadyPaid }   // 别人先改了
+```
+
+---
+
+## 第二层：可选便利
+
+用不用都对，**不用不会出任何问题**：
+
+| 东西 | 在哪 | 是什么 |
+|---|---|---|
+| `api.Api` | core `sdk/api` | 一条链式糖：`MakeContext` / `Bind` / `MakeOrm` / `OK` / `PageOK` / `Error` |
+| `service.Service` | core `sdk/service` | 一个装 `Orm` / `Log` / `Cache` / `Error` 的结构体加一个 `AddError` |
+| `MakeCondition` / `search` tag | core `sdk/contract/dto` | 把 DTO 上的 `search:"type:exact;column:name;table:xx"` 翻成 WHERE |
+| 通用 CRUD Action | go-admin `common/actions` | `IndexAction` 等五个。**留在 go-admin，没有下沉** |
+
+最后一行是有意的：CRUD Action 是最需要演进的一类东西（分页参数、批量操作、
+软删语义、字段级权限），而 core 的每一个导出都是永久承诺——放进去容易，
+拿出来不可能。想用就把那 294 行抄走，抄走的那份还能按你自己的需要改。
+主仓唯一的真实业务模块 `app/admin` **一个 CRUD Action 都没用**，全是手写 Service。
+
+`MakeCondition` 返回的是 `func(db *gorm.DB) *gorm.DB` 闭包，方言从闭包里那个
+`db.Dialector.Name()` 读，**必然是本租户那个库的驱动**，不需要你设置任何东西。
+
+---
+
+## 第三层：今天没有的
+
+**明说没有，别自己发明**：
+
+| 能力 | 现状 |
+|---|---|
+| 应用间调用 | 零定义。A 应用要调 B 应用只能直接 import 对方的包，循环依赖就回来了 |
+| 领域事件 / EventBus | 无 |
+| 缓存的租户隔离 | `service.Service` 有 `Cache` 字段，**是否按租户隔离未验证**。当作没隔离来写 |
+| 生命周期钩子之外的时点 | 只有下面那四个。没有「路由装好之后、开始监听之前」这一档 |
+
+这几条留给后续批次，按真实需求补——现在凭空设计只会设计错。
+如果你的应用卡在这里，在 issue 里说一声，那正是我们要的输入。
+
+---
+
+## 装一个应用要接两处线
+
+后端**两处**，漏掉第二处是**静默失败**：
+
+```go
+// 1. 路由：cmd/api/<name>.go
+import _ "github.com/acme/go-admin-app-order/router"
+
+// 2. 迁移：cmd/migrate/server.go 的 import 块里
+import _ "github.com/acme/go-admin-app-order/migration"
+```
+
+两个都是空导入，作用只是让那个包的 `init()` 跑起来。
+
+**漏了第二处会怎样**：不报错。`migrate` 命令照常跑完、照常打印成功，
+你的建表和种子数据**就是不执行**。等到第一个请求打过来才会看到
+"表不存在"，而那时排查方向已经跑偏了。
+
+`migrate --dry-run` 是确认接线成功的最快方式——它只读，可以直接对生产库跑：
+
+```bash
+go-admin migrate --dry-run -c config/settings.yml    # 你的迁移应该出现在列表里
+```
+
+带界面的应用还有第三处，在前端仓库，见下一节。
+
+---
+
+## 前端：菜单 `component` 必须以 `apps/` 开头
+
+前端那一处接线是 `go-admin-ui` 的 `apps.config.mjs`——加一条
+`{ code: 'order', source: '...' }`，`source` 指到你的页面目录
+（兄弟目录的相对路径，或 `./node_modules/@scope/app-order/views/order`）。
+`scripts/sync-apps.mjs` 会在 `pnpm dev` 与 `pnpm build` 之前把它复制进
+`src/apps/<code>/`，不需要手工跑。
+
+`src/stores/permission.ts` 的 `appPath()` **只认路径第一段是 `apps`**，
+其余一律当成主仓内置视图去 `src/views/` 下找。
+
+所以你的菜单种子里 `Component` 必须写成：
+
+```
+apps/<code>/<该应用内的相对路径>/index
+```
+
+比如 `code` 是 `order` 的应用写 `apps/order/index`（开头带不带 `/` 都行，
+只看第一段）。**不能**写成 `/order/index`。
+
+**写错会怎样**：第一段是 `order` 而不是 `apps`，前端会去找一个不存在的
+`src/views/order/index.vue`，页面摔到 `AppNotInstalled` 占位组件。
+但控制台打印的是 `no component at src/views/order/index.vue`——
+**跟真实原因（漏了 `apps/` 前缀）对不上**，排查时很容易被这条日志带偏。
+
+对应的前端约定写在 go-admin-ui 的 `AGENTS.md`。另外一条：`source` 目录的内容
+**原样**搬进 `src/apps/<code>/`，不会在 `code` 之外再自动插一层——想要
+`apps/order/index` 这种最短形式，`source` 就要直接指到该应用**这一个页面模块**
+的目录，而不是应用仓库的 `views` 根目录。
 
 ---
 
 ## 注册路由
 
-一个应用模块要注册自己的路由，写一个 `func()` 签名的 `InitRouter`
-（照抄 `app/demo/router/router.go`），然后二选一接进来：
+写一个 `func()` 签名的 `InitRouter`（照抄 `app/demo/router/router.go`），
+然后二选一接进来：
 
 ```go
 // 方式一（历史写法，仍然有效）：在主仓 cmd/api/<name>.go 里
@@ -68,36 +457,30 @@ AppRouters = append(AppRouters, router.InitRouter)
 sdk.Runtime.SetAppRouters(router.InitRouter)
 ```
 
-方式二是本次新接上的。差别只有一个但很关键：方式一要求你的模块
-`import "go-admin/cmd/api"` —— 那是主程序的命令包，让业务模块依赖它很别扭，
-也正是"主仓要为每个模块加一个七行文件"的根源。
+**第三方应用只能走方式二**——方式一要求 `import "go-admin/cmd/api"`，
+那就又依赖上宿主了。
 
-**执行顺序**：先跑完包级 `AppRouters`，再由 core 的 `sdk.Runtime.RunAppRouters()`
-跑它自己的注册表，各自内部保持注册顺序。别依赖跨来源的相对顺序，各模块的
-`RouterGroup` 前缀互不相同，本来就不该有顺序依赖。
+走方式二还多拿到两样东西，都在 core 那边实现：
 
-走方式二还多拿到两样东西，都在 core 那边实现（见
-[core 的 `docs/contract.md`](https://github.com/go-admin-team/go-admin-core/blob/main/docs/contract.md)）：
-**panic 护栏**——你的 `InitRouter` panic 了，其余模块照常注册、进程不退出，日志里会写明
-是哪一行注册的；**失败分级**——`sdk.Runtime.SetAppRoutersWith(f, runtime.WithFatal())`
-声明「我起不来就别启动」。方式一（包级 `AppRouters`）没有护栏，panic 直接掀桌。
+- **panic 护栏**——你的 `InitRouter` panic 了，其余模块照常注册、进程不退出，
+  日志里会写明是哪一行注册的
+- **失败分级**——`sdk.Runtime.SetAppRoutersWith(f, runtime.WithFatal())`
+  声明「我起不来就别启动」
 
-`InitRouter()` 内部的约定：自己拿 `sdk.Runtime.GetEngine()`，按需建
+方式一（包级 `AppRouters`）没有护栏，panic 直接掀桌。
+
+**执行顺序**：先跑完包级 `AppRouters`，再由 `sdk.Runtime.RunAppRouters()`
+跑 core 自己的注册表，各自内部保持注册顺序。别依赖跨来源的相对顺序。
+
+`InitRouter()` 内部：自己拿 `sdk.Runtime.GetEngine()`，按需建
 `gin.RouterGroup`，通过 `init()` 自注册到你自己包内的
-`routerCheckRole` / `routerNoCheckRole` 列表，不在任何中心文件手工列举
-（与 `AGENTS.md`「路由注册」一节一致）。
+`routerCheckRole` / `routerNoCheckRole` 列表，不在任何中心文件手工列举。
 
 ---
 
 ## 注册数据库迁移
 
-框架自身的迁移不变：
-
-```go
-migration.Migrate.SetVersion(migration.GetFilename(fileName), _1786700001000DemoMenu)
-```
-
-应用的迁移走 `ForApp`：
+框架自身的迁移用 `SetVersion`；应用的迁移走 `ForApp`：
 
 ```go
 func init() {
@@ -108,12 +491,20 @@ func init() {
 func initCrmTables(db *gorm.DB, version, appCode string) error {
     return db.Transaction(func(tx *gorm.DB) error {
         // ... schema / data changes ...
-        return tx.Create(&common.Migration{Version: version, AppCode: appCode}).Error
+        return tx.Create(&models.Migration{Version: version, AppCode: appCode}).Error
     })
 }
 ```
 
-四条必须知道的规则：
+注册面（`ForApp` / `SetVersion` / `GetFilename`）在 core 的
+`sdk/contract/migration`，是一个**进程级的包级注册表**——`ForApp` 直接当包级函数
+调，不需要从宿主手里接过什么句柄。**执行面**——读 `sys_migration`、排序、跑事务、
+`migrate` 与 `migrate status` 两个命令——留在宿主，它通过 `Snapshot()` 读那张表。
+
+仓库内的模块继续经 `go-admin/cmd/migrate/migration` 走，那个包现在是薄壳，
+导入路径不变；外置应用直接 import core 的那个包，**两边写法一模一样**。
+
+五条必须知道的规则：
 
 1. **完成记录由迁移函数自己写**，而且要写在自己的事务里。框架的调度循环只做
    "这个 version 在 `sys_migration` 里有没有" 的判断，从不代你插入 —— 这样
@@ -122,12 +513,17 @@ func initCrmTables(db *gorm.DB, version, appCode string) error {
    schema 上那一列等于白加，你的迁移会被记成框架的。
 3. **落库的 `version` 是加了前缀的**。`ForApp("crm")` 注册 `1786800001000`，
    实际写进 `sys_migration.version` 的是 `crm-1786800001000`，函数收到的
-   `version` 参数已经是这个带前缀的值，照抄进 `common.Migration{Version: version}`
+   `version` 参数已经是这个带前缀的值，照抄进 `models.Migration{Version: version}`
    即可。前缀的意义是：两个来源不同的应用哪怕碰巧生成同一个毫秒时间戳，也不会撞主键、
    不会有一方被误判为"已应用"。
 4. **应用 code 一律小写**，`ForApp` 会自己 `strings.ToLower` 一遍。`core` 是保留字
    （`migrate status` 用它表示框架自身，`--app core` 选中框架），`ForApp("core")`
    会 panic。
+5. **文件名前 13 位必须是毫秒时间戳**，`GetFilename` 就是从这里取版本号的。
+   不合规的名字会 panic，并把违规文件名报出来 —— 这是**故意的**：调用点全在
+   `init()` 里，没有 error 可返回，而另一条路是把文件名本身注册成"版本号"
+   （`add_orders.go` 恰好 13 个字符，只查长度是拦不住的），那样这条迁移
+   永远不会被执行，且不会有任何提示。宁可启动失败。
 
 顺序保证：**同一应用内按版本号严格有序**。跨应用顺序不做承诺 —— 由于前缀的存在，
 今天的实际顺序是"先跑完全部框架迁移，再按 appCode 字母序逐个应用跑完"，
@@ -146,6 +542,98 @@ go-admin migrate --app crm -c config/settings.yml       # 只跑 crm 的迁移
 
 ---
 
+## 菜单与接口种子
+
+一个带界面的应用要在侧边栏里出现，需要往四类数据里写东西：`sys_api`、
+`sys_menu`、`sys_menu_api_rule`（菜单与接口的关联）、以及角色授权与 Casbin
+策略（`sys_role_menu` / `casbin_rule`）。
+
+**你不需要知道这些表长什么样。** `sdk/contract/seed` 让你只描述"我要什么"，
+由宿主决定"怎么写进它自己的表"：
+
+```go
+// 在你自己的迁移里，用它自己的那个事务
+err := seed.SeedMenus(tx, "order", []seed.MenuSpec{
+    {Code: "root", Kind: models.Directory, Title: "订单"},
+    {Code: "list", Parent: "root", Kind: models.Menu, Title: "订单列表",
+        Path: "/order", Component: "apps/order/index", ApiCodes: []string{"list"}},
+}, []seed.ApiSpec{
+    {Code: "list", Title: "订单列表", Path: "/api/v1/order", Method: "GET"},
+})
+```
+
+`Kind` 用的就是 `sdk/contract/models` 里 `sys_menu.menu_type` 的那三个值
+（`Directory` / `Menu` / `Button`），不是另一套同值的常量。
+
+`Component` 的写法见上面「前端」一节——**这里是最容易写错的一个字段**。
+
+core 里**没有** `SysMenu`、没有 `SysApi`、没有任何表名。这是刻意划的边界：
+这个框架的宿主里本来就已经有两份 `SysMenu`（一份冻结在迁移期、一份运行期），
+两者在软删语义上不一致，害过人，为此专门建了一个仓库内的工具来守。
+往 core 里再放第三份表结构，就等于在**唯一没有工具守着**的地方重造同一类 bug。
+
+### `Sort` 有上界，越界会中断整场迁移
+
+`sys_menu.sort` 声明为 `gorm:"size:4"`，MySQL 据此建成 **tinyint，取值 -128..127**。
+sqlite 忽略宽度，所以越界值在本地测试里一路绿灯，到真实安装时是 Error 1264 ——
+而且发生在一次迁移的**中途**，后面的迁移全部不再执行。
+
+`make checksilent` 的 `menu-sort-overflow` 会扫出仓库树里的越界字面量，
+**但它扫不到 module cache 里的应用**。外置应用只有宿主 Seeder 的运行期校验兜底。
+
+### `MenuSpec` 没有菜单名字段，名字由宿主合成
+
+前端用菜单名做 keep-alive 的缓存键。两个应用如果都取 `Code: "list"`，
+缓存键就会撞在一起 —— 后打开的那个页面会拿到前一个的缓存实例。
+
+所以宿主的 Seeder 不直接用 `Code` 当菜单名，而是用
+**PascalCase(appCode) + PascalCase(Code)** 合成（`order` + `list` → `OrderList`）。
+你不需要做什么，但要知道两件事：
+
+- 菜单名不是你能指定的，也不必与 `Title` 一致 —— `Title` 才是界面上显示的文字
+- 前端组件的 `name` 若要与菜单名对齐（`checksilent` 的 `menu-name-mismatch` 会比对），
+  按合成后的名字写，不是按 `Code`
+
+---
+
+## 应用配置节
+
+不要改宿主的源码去加配置。`sdk/config.RegisterExtend` 让你认领
+`extend:` 下自己那一节：
+
+```go
+type orderConfig struct {
+    PaymentEndpoint string
+    Timeout         int
+}
+
+// 在 init() 里调，与 SetAppRouters / ForApp 同一约定
+var getOrderConfig = config.RegisterExtend[orderConfig]("order")
+
+func handler(c *gin.Context) {
+    cfg := getOrderConfig()
+    _ = cfg.PaymentEndpoint
+}
+```
+
+```yaml
+extend:
+  order:
+    PaymentEndpoint: https://payment.internal
+    Timeout: 30
+```
+
+每个 key 各自解码，互不覆盖。**同一个 key 注册两次会立刻 panic**——
+注册期没有"封闭时刻"可以用来拒绝迟到的注册，所以重复只能在注册的那一刻
+大声报出来，而不是让第二个人静默顶掉第一个人的配置节。
+
+配置文件是被监听的，改动会触发重载。`RegisterExtend` 每次重载解码进一个全新的
+`T` 再原子换指针，所以访问器拿到的永远是一个自洽的快照，请求路径上读它不需要加锁。
+唯一要注意的：**不要跨两次调用拼一个视图**——从同一个返回值上读两个字段是一致的，
+调两次访问器各读一个字段，中间夹一次重载就不是了。
+
+---
+
 ## 硬约束：注册要赶在启动钩子之前
 
 三个注册入口——`AppRouters`、`sdk.Runtime.SetAppRouters`、`migration.ForApp`——
@@ -153,18 +641,16 @@ go-admin migrate --app crm -c config/settings.yml       # 只跑 crm 的迁移
 
 `init()` 是最省事的位置：Go 规范保证包级变量初始化与 `init()` 在 `main()` 之前
 **单 goroutine 顺序执行**，注册期天然没有并发写。但它不是唯一合法位置——
-在 `run()` 之类早于启动钩子的地方注册同样成立。这条规则约束的是**顺序**，
-不是你写在哪个函数里。
+在 `run()` 之类早于启动钩子的地方注册同样成立。**这条规则约束的是顺序，
+不是你写在哪个函数里。**
 
-`sdk.Runtime.SetAppRouters` 的准确语义以 core 为准：
+想在代码里判断注册窗口是否还开着：
 
-> [go-admin-core `docs/contract.md`](https://github.com/go-admin-team/go-admin-core/blob/main/docs/contract.md)
+```go
+if sdk.Runtime.AppRoutersSealed() { /* RunAppRouters 已经跑过了 */ }
+```
 
-那份文档写明了注册类与资源类的划分、封闭时刻、护栏边界（**只覆盖同步 panic，
-你自己 `go func()` 出去的 panic 框架够不着**）、以及配置热更新会在运行期
-重新执行 setup 回调这件事。
-
-主仓这边只补三条它管不着的：
+主仓这边补三条 core 那份文档管不着的：
 
 1. **`RunAppRouters()` 跑过之后，core 的注册表就封闭了**，再调
    `sdk.Runtime.SetAppRouters` 会被丢弃并记一条 ERROR 日志。包级 `AppRouters`
@@ -181,19 +667,141 @@ go-admin migrate --app crm -c config/settings.yml       # 只跑 crm 的迁移
    ```
 
    `cmd/api/server_test.go` 里的 `freshRuntime` 就是这个。
-3. **`migration.ForApp` 是主仓的东西**，core 不认识它，上面那份文档不覆盖它。
-   它的约束仍然是"注册要在迁移调度循环跑起来之前"，实践上就是 `init()`。
+3. **迁移的调度循环是主仓的东西**，core 只有注册面。迁移注册的约束仍然是
+   "赶在调度循环跑起来之前"，实践上就是 `init()`。
+
+---
+
+## 生命周期挂载点
+
+除了注册路由和迁移，应用还可以把工作挂在进程生命的四个时点上，不必等宿主按名字来调自己。
+契约本身在 core，见
+[go-admin-core `docs/contract.md`](https://github.com/go-admin-team/go-admin-core/blob/main/docs/contract.md)
+的「Life-cycle phases」一节。这里只写**在本仓里它们分别落在哪一行**。
+
+| 阶段 | 在 `cmd/api/server.go` 的位置 | 此时可用 |
+|---|---|---|
+| `AfterResource` | `bootstrap.SetupConfig` 跑完 `database.Setup` / `storage.Setup` 之后 | 配置、库、缓存、队列、casbin |
+| `BeforeRouter` | `initRouter()` **之前** | 以上，加引擎尚未构建这一事实 |
+| `AfterListen` | `startServing()` 里，`net.Listen` 返回之后 | 全部，端口**已绑定**、连接进得来 |
+| `BeforeExit` | `srv.Shutdown` 返回之后（无论它是否报错） | 全部，正在被拆掉 |
+
+`AfterListen` 承诺的是**端口已绑定**，不是「`Serve` 已经在 accept 循环里」——
+`srv.Serve` 在另一个 goroutine 上。这个区别是真实的：绑定成功之后内核就会把连接排进
+backlog，所以钩子里去连自己的端口不会被拒;但此刻 `Serve` 可能还没跑到第一次 `Accept`。
+绑定失败则**根本不会有这个阶段**：`net.Listen` 的错误直接从 `run()` 返回，
+横幅不打印，进程非零退出。
+
+```go
+sdk.Runtime.SetPhase(runtime.AfterResource, func() { /* ... */ })
+sdk.Runtime.SetShutdown(func(ctx context.Context) { /* ... */ })
+```
+
+### `BeforeRouter` 不等于 `before` 注册表
+
+**这两个不是同一个时点，文档里别混着写。** `SetBefore` 的回调由
+`runStartupHooks()` 执行，而那是在 `initRouter()` **之后**——引擎已经建好了。
+`BeforeRouter` 在它之前。
+
+顺带：`BeforeRouter` 是「硬约束：注册要赶在启动钩子之前」那一节所说的合法注册窗口之一。
+它早于 `runStartupHooks()`，所以在这里调 `sdk.Runtime.SetAppRouters` 仍然来得及。
+
+### `AfterResource` 会跑很多次，回调必须扛得住
+
+它在**每次配置热更新之后**都会再跑一遍，因为热更新会重建它所命名的那些资源。
+所以这里的回调要求是**「对同一个资源幂等」，不是「第二次什么都不做」**。
+
+本仓自己的队列消费者就是这条规则的样板，也是它存在的理由
+（`cmd/api/server.go` 的 `attachQueueConsumers`）：
+
+- 热更新重建了队列适配器，挂在旧适配器上的消费者连着一个**再没人往里发消息**的队列，
+  登录日志和操作日志就此停写且不出声。所以新适配器**必须**重新注册。
+- 但同一个适配器不能注册两次，否则每条消息有两个消费者，每行日志写两遍。
+
+**身份不能从访问器取。** `sdk.Runtime.GetQueueAdapter()` 与 `GetQueuePrefix()`
+每次调用都新造一个 `runtime.Queue` 包装，比较两次返回等于比较两个包装，
+**底层适配器换过多少次都不相等**。要在**创建资源的地方**记身份——
+本仓是 `common/storage.QueueGeneration()`。
+
+### 注册消费者要赶在队列启动之前
+
+走哪条实现，取决于配置里有没有 `redis:` 段（`config.QueueConfig.Setup()`）：
+
+| 配置 | 实际类型 | 启动后还能注册吗 |
+|---|---|---|
+| `queue: memory:` | `queue.NewMemory` | **能**。它的 `Register` 每次起一个消费 goroutine，不看是否已 `Run` |
+| `queue: redis:` | `storage.LegacyQueueAdapter` 包着新契约实现 | **不能**。`Register` 内部调 `Subscribe`，启动后返回 `storage.ErrQueueAlreadyStarted` |
+
+而 `LegacyQueueAdapter.Register` **没有返回值**——它只能把这个错误写进 slog，
+core 里那行注释自己写着「The interface has no way to report this to the caller」。
+**静默的是注册这一步，不是之后。** 没有建立消费组，redis 会用
+`storage.ErrNoHandler` 拒绝**之后的每一次投递**，而本仓两个调用点
+（`common/middleware/logger.go`、`common/middleware/handler/auth.go`）
+都把它记为 error——于是日志行一条都不落库，同时每个请求刷一条错误日志。
+
+所以顺序是硬的：**先 `Register` 完，再由注册方 `Run()`。**
+`common/storage` 的 `setupQueue` 有意不启动队列。
+
+默认配置选的是 memory 后端,它不在乎顺序——**这个缺陷在默认部署里看不见,
+只在配了 redis 的部署上发作**,而丢掉的正是登录日志、操作日志和 api 检查。
+
+### `BeforeExit` 反序执行，预算约束的是等待
+
+清理按**注册的逆序**执行。`SetShutdown` 拿到宿主剩余的预算，
+但**它约束的是等待，不是工作**：预算用尽时 `RunShutdown` 停止等待并返回，
+而不检查 context 的回调会一直跑到进程退出。Go 没法取消一个不检查取消的函数。
+
+本仓的样板是 cron（`app/jobs/jobbase.go` 的 `startCrontab`）：
+`cron.Stop()` 返回一个在**已经在跑的任务结束时**关闭的 context，
+钩子在它和预算之间二选一。
+
+---
+
+## 安全边界：装一个应用等于信任它
+
+**这一层划不出安全边界，本文不假装划得出。**
+
+第三方应用的代码在**宿主进程内**运行，与宿主**同权限**。它持有的是裸的
+`*gorm.DB`——`seed.SeedMenus` 用的就是你自己迁移里那个 `tx`，绕开 `Seeder`
+直写 `sys_menu`、`sys_api`、甚至 `casbin_rule` 一直都做得到，Go 的类型系统
+拦不住，本框架的任何一层也拦不住。
+
+还有一条**不碰 `casbin_rule` 也能走通**的间接路径：把自己的菜单通过
+`ApiCodes` 关联到别人的接口，然后等管理员在后台把这个菜单授权给某个角色——
+策略是后台自己生成的，记在管理员头上。
+
+所以：
+
+> **装一个应用，等于信任它。** 这和 `import _` 一个 Go 库是同一量级的信任。
+> `Seeder` 这类设计的目的是让**守规矩的应用不必知道宿主的表结构**，
+> 不是把不守规矩的应用关起来。
+
+给使用者的实际建议只有一条：**按信任 Go 依赖的标准来审应用**——看源码、
+钉版本、认作者。不要因为它叫"应用"就以为它跑在沙箱里。
 
 ---
 
 ## 边界由 CI 守着
 
-`common/`、`core/` 不得 import `app/`，这条由 `tools/checksilent` 的
-`contract-import-boundary` 检查固化，`make checksilent` 在 CI 里跑，违反即失败
-（测试文件同样算 —— 一个删掉 `app/admin` 的 fork 也应该能跑 `go test ./...`）。
+`tools/checksilent` 里有两条盯契约面的检查，`make checksilent` 在 CI 里跑，
+命中 ERROR 即失败：
 
-靠人工评审列契约面会漏。上面那两处反向依赖里，第二处就是评审没发现、
-靠机器全量扫描才找出来的。
+| 检查 | 盯的是 |
+|---|---|
+| `contract-import-boundary` | `common/`、`core/` 不得 import `app/`——否则一个删掉 `app/admin` 的 fork 就编译不了它被告知可以依赖的那一面 |
+| `contract-shim-alias` | 从 core 契约包声明出来的类型必须是**别名**（`type X = pkg.Y`），不能是 defined type。判据是右手边，不是一份包名清单，所以谁在哪加的都算 |
 
-`tools/checksilent` 还检查另外五类"不出声的失败"，写模块时值得先看一眼
+第二条守的是一条一个字符的差别。`type X = pkg.Y` 和 `type X pkg.Y`
+看着几乎一样，但后者只拿走底层结构、**丢掉整个方法集**，于是嵌了它的 model
+不再满足 `ActiveRecord`。麻烦在于这**不一定在本仓编译失败**——本仓只用接口
+使唤其中一部分类型，没被使唤到的那些在这里编译得好好的，
+**到第三方应用或某个 fork 里才炸**，而那里没人看着。
+
+测试文件同样算——一个删掉 `app/admin` 的 fork 也应该能跑 `go test ./...`。
+
+**这两条工具都只扫仓库树。** 装在 module cache 里的第三方应用，
+`checksilent` 一个文件都看不到。所以它保的是**这个仓库和它的 fork**，
+不是你的应用——你的应用要自己跑自己的检查。
+
+`checksilent` 还检查另外五类"不出声的失败"，写模块时值得先看一眼
 `go run ./tools/checksilent -h`。

example/app-order/apis/order.go

@@ -0,0 +1,167 @@
+// Package apis is app-order's HTTP layer: four hand-written gin handlers,
+// none of them a wrapper around core's generic CRUD Actions. See
+// service/order.go's package doc for why.
+package apis
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+
+	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
+
+	// models.Response in the @Success annotations below resolves to
+	// go-admin-core's sdk/contract/models.Response, not to this package -
+	// swaggo finds it through --parseDependency. It is the envelope with a
+	// data field; core's response.Response, which the framework's own
+	// handlers name, has no data field and would document these endpoints
+	// as returning none.
+	"github.com/go-admin-team/example-app-order/models"
+	"github.com/go-admin-team/example-app-order/service"
+	orderdto "github.com/go-admin-team/example-app-order/service/dto"
+)
+
+// Order embeds api.Api the same way every hand-written go-admin handler
+// does (see app/admin/apis/sys_post.go): MakeContext/MakeOrm/Bind/
+// MakeService/OK/Error/PageOK are all core, imported with no dependency on
+// go-admin itself.
+type Order struct {
+	api.Api
+}
+
+// GetPage
+// @Summary List orders visible to the caller's data scope
+// @Tags order
+// @Param status query string false "status"
+// @Param orderNo query string false "orderNo"
+// @Param pageIndex query int false "pageIndex"
+// @Param pageSize query int false "pageSize"
+// @Success 200 {object} models.Response
+// @Router /api/v1/order [get]
+// @Security Bearer
+func (e Order) GetPage(c *gin.Context) {
+	s := service.Order{}
+	req := orderdto.OrderSearchReq{}
+	err := e.MakeContext(c).
+		MakeOrm().
+		Bind(&req, binding.Form).
+		MakeService(&s.Service).
+		Errors
+	if err != nil {
+		e.Error(http.StatusUnprocessableEntity, err, err.Error())
+		return
+	}
+
+	p := actions.GetPermissionFromContext(c)
+	list := make([]models.Order, 0)
+	count, err := s.GetPage(&req, p, &list)
+	if err != nil {
+		e.Logger.Error(err)
+		e.Error(http.StatusInternalServerError, err, "failed to list orders")
+		return
+	}
+	e.PageOK(list, int(count), req.GetPageIndex(), req.GetPageSize(), "ok")
+}
+
+// Get
+// @Summary Get one order and its items
+// @Tags order
+// @Param id path int true "order id"
+// @Success 200 {object} models.Response
+// @Router /api/v1/order/{id} [get]
+// @Security Bearer
+func (e Order) Get(c *gin.Context) {
+	s := service.Order{}
+	req := orderdto.OrderIdReq{}
+	err := e.MakeContext(c).
+		MakeOrm().
+		Bind(&req, nil).
+		MakeService(&s.Service).
+		Errors
+	if err != nil {
+		e.Error(http.StatusUnprocessableEntity, err, err.Error())
+		return
+	}
+
+	p := actions.GetPermissionFromContext(c)
+	var order models.Order
+	if err = s.Get(req.Id, p, &order); err != nil {
+		e.Error(http.StatusNotFound, err, "order not found")
+		return
+	}
+	e.OK(order, "ok")
+}
+
+// Create
+// @Summary Place a new order
+// @Tags order
+// @Accept application/json
+// @Param data body orderdto.OrderCreateReq true "data"
+// @Success 200 {object} models.Response
+// @Router /api/v1/order [post]
+// @Security Bearer
+func (e Order) Create(c *gin.Context) {
+	s := service.Order{}
+	req := orderdto.OrderCreateReq{}
+	err := e.MakeContext(c).
+		MakeOrm().
+		Bind(&req, binding.JSON).
+		MakeService(&s.Service).
+		Errors
+	if err != nil {
+		e.Error(http.StatusUnprocessableEntity, err, err.Error())
+		return
+	}
+
+	order, err := s.Create(&req, user.GetUserId(c))
+	if err != nil {
+		if errors.Is(err, service.ErrOrderEmpty) {
+			e.Error(http.StatusBadRequest, err, err.Error())
+			return
+		}
+		e.Logger.Error(err)
+		e.Error(http.StatusInternalServerError, err, "failed to create order")
+		return
+	}
+	e.OK(order, "created")
+}
+
+// Pay
+// @Summary Mark a pending order as paid
+// @Tags order
+// @Param id path int true "order id"
+// @Success 200 {object} models.Response
+// @Router /api/v1/order/{id}/pay [put]
+// @Security Bearer
+func (e Order) Pay(c *gin.Context) {
+	s := service.Order{}
+	req := orderdto.OrderIdReq{}
+	err := e.MakeContext(c).
+		MakeOrm().
+		Bind(&req, nil).
+		MakeService(&s.Service).
+		Errors
+	if err != nil {
+		e.Error(http.StatusUnprocessableEntity, err, err.Error())
+		return
+	}
+
+	p := actions.GetPermissionFromContext(c)
+	if err = s.Pay(req.Id, p); err != nil {
+		if errors.Is(err, service.ErrOrderNotPending) {
+			// Deliberately the same response whether the order does not
+			// exist, is already paid, or is outside p's data scope - see
+			// service.Order.Pay's doc comment.
+			e.Error(http.StatusConflict, err, err.Error())
+			return
+		}
+		e.Logger.Error(err)
+		e.Error(http.StatusInternalServerError, err, "payment failed")
+		return
+	}
+	e.OK(nil, "paid")
+}

example/app-order/go.mod

@@ -0,0 +1,81 @@
+module github.com/go-admin-team/example-app-order
+
+go 1.25.13
+
+require (
+	github.com/gin-gonic/gin v1.12.0
+	github.com/glebarez/sqlite v1.11.0
+	github.com/go-admin-team/go-admin-core/v2 v2.5.0
+	gorm.io/gorm v1.31.2
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/BurntSushi/toml v1.5.0 // indirect
+	github.com/andeya/ameda v1.5.3 // indirect
+	github.com/andeya/goutil v1.0.1 // indirect
+	github.com/bitly/go-simplejson v0.5.1 // indirect
+	github.com/bmatcuk/doublestar/v4 v4.9.1 // indirect
+	github.com/bytedance/go-tagexpr/v2 v2.9.11 // indirect
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.15.0 // indirect
+	github.com/bytedance/sonic/loader v0.5.0 // indirect
+	github.com/casbin/casbin/v3 v3.8.1 // indirect
+	github.com/casbin/govaluate v1.10.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/chanxuehong/rand v0.0.0-20211009035549-2f07823e8e99 // indirect
+	github.com/chanxuehong/wechat v0.0.0-20230222024006-36f0325263cd // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
+	github.com/ghodss/yaml v1.0.0 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
+	github.com/glebarez/go-sqlite v1.22.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.19.2 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/nyaruka/phonenumbers v1.2.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/quic-go/quic-go v0.59.1 // indirect
+	github.com/redis/go-redis/v9 v9.22.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/robfig/cron/v3 v3.0.1 // indirect
+	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/spf13/cast v1.7.1 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	go.uber.org/zap v1.27.1 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/crypto v0.53.0 // indirect
+	golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.39.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
+	gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gorm.io/plugin/soft_delete v1.2.1 // indirect
+	modernc.org/libc v1.67.4 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.42.2 // indirect
+)

example/app-order/go.sum

@@ -0,0 +1,252 @@
+dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
+dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+github.com/BurntSushi/toml v1.5.0 h1:W5quZX/G/csjUnuI8SUYlsHs9M38FC7znL0lIO+DvMg=
+github.com/BurntSushi/toml v1.5.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/andeya/ameda v1.5.3 h1:SvqnhQPZwwabS8HQTRGfJwWPl2w9ZIPInHAw9aE1Wlk=
+github.com/andeya/ameda v1.5.3/go.mod h1:FQDHRe1I995v6GG+8aJ7UIUToEmbdTJn/U26NCPIgXQ=
+github.com/andeya/goutil v1.0.1 h1:eiYwVyAnnK0dXU5FJsNjExkJW4exUGn/xefPt3k4eXg=
+github.com/andeya/goutil v1.0.1/go.mod h1:jEG5/QnnhG7yGxwFUX6Q+JGMif7sjdHmmNVjn7nhJDo=
+github.com/bitly/go-simplejson v0.5.1 h1:xgwPbetQScXt1gh9BmoJ6j9JMr3TElvuIyjR8pgdoow=
+github.com/bitly/go-simplejson v0.5.1/go.mod h1:YOPVLzCfwK14b4Sff3oP1AmGhI9T9Vsg84etUnlyp+Q=
+github.com/bmatcuk/doublestar/v4 v4.6.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/bmatcuk/doublestar/v4 v4.9.1 h1:X8jg9rRZmJd4yRy7ZeNDRnM+T3ZfHv15JiBJ/avrEXE=
+github.com/bmatcuk/doublestar/v4 v4.9.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/bytedance/go-tagexpr/v2 v2.9.11 h1:jJgmoDKPKacGl0llPYbYL/+/2N+Ng0vV0ipbnVssXHY=
+github.com/bytedance/go-tagexpr/v2 v2.9.11/go.mod h1:UAyKh4ZRLBPGsyTRFZoPqTni1TlojMdOJXQnEIPCX84=
+github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
+github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
+github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
+github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
+github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
+github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
+github.com/casbin/casbin/v3 v3.8.1 h1:D4dEY4knePPR4YgNP5WZtWNaOxD0UK0LpPy9+zxtBwo=
+github.com/casbin/casbin/v3 v3.8.1/go.mod h1:5rJbQr2e6AuuDDNxnPc5lQlC9nIgg6nS1zYwKXhpHC8=
+github.com/casbin/govaluate v1.3.0/go.mod h1:G/UnbIjZk/0uMNaLwZZmFQrR72tYRZWQkO70si/iR7A=
+github.com/casbin/govaluate v1.10.0 h1:ffGw51/hYH3w3rZcxO/KcaUIDOLP84w7nsidMVgaDG0=
+github.com/casbin/govaluate v1.10.0/go.mod h1:G/UnbIjZk/0uMNaLwZZmFQrR72tYRZWQkO70si/iR7A=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/chanxuehong/rand v0.0.0-20211009035549-2f07823e8e99 h1:K62Lb6bsgLOB++z/VAvRvtiEBdNCuMfmQGTGGWMdPpM=
+github.com/chanxuehong/rand v0.0.0-20211009035549-2f07823e8e99/go.mod h1:9+sJ9zvvkXC5sPjPEZM3Jpb9n2Q2VtcrGZly0UHYF5I=
+github.com/chanxuehong/util v0.0.0-20200304121633-ca8141845b13/go.mod h1:XEYt99iTxMqkv+gW85JX/DdUINHUe43Sbe5AtqSaDAQ=
+github.com/chanxuehong/wechat v0.0.0-20230222024006-36f0325263cd h1:v3JNsFZmplLO/Cmiyr/rGvR7lW1ld9lB+d5h4yR0MTI=
+github.com/chanxuehong/wechat v0.0.0-20230222024006-36f0325263cd/go.mod h1:mysjrtCs9MmN8hqDf4/mc4eQ26Rt9s1p5oO+fhJlLB4=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
+github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk=
+github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
+github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
+github.com/glebarez/go-sqlite v1.22.0 h1:uAcMJhaA6r3LHMTFgP0SifzgXg46yJkgxqyuyec+ruQ=
+github.com/glebarez/go-sqlite v1.22.0/go.mod h1:PlBIdHe0+aUEFn+r2/uthrWq4FxbzugL0L8Li6yQJbc=
+github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
+github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
+github.com/go-admin-team/go-admin-core/v2 v2.5.0 h1:aD1SALklBxizGB9u8cOgm4OT8z656FM83F4fD6dMz9g=
+github.com/go-admin-team/go-admin-core/v2 v2.5.0/go.mod h1:LG/XvEfOplbuadKrPTPm0Nu5pN06aQUNZZC3ao4B4gs=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy06ntQJp0BBvFG0w=
+github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gopherjs/gopherjs v1.17.2 h1:fQnZVsXk8uxXIStYb0N4bGk7jeyTalG/wsZjQ25dO0g=
+github.com/gopherjs/gopherjs v1.17.2/go.mod h1:pRRIvn/QzFLrKfvEz3qUuEhtE/zLCWfreZ6J5gM2i+k=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.1/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/jinzhu/now v1.1.4/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/jtolds/gls v4.20.0+incompatible h1:xdiiI2gbIgH/gLH7ADydsJ1uDOEzR8yvV7C0MuV77Wo=
+github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.3/go.mod h1:WVKg1VTActs4Qso6iwGbiFih2UIHo0ENGwNd0Lj+XmI=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/nyaruka/phonenumbers v1.0.55/go.mod h1:sDaTZ/KPX5f8qyV9qN+hIm+4ZBARJrupC6LuhshJq1U=
+github.com/nyaruka/phonenumbers v1.2.2 h1:OwVjf7Y4uHoK9VJUrA8ebR0ha2yc6sEYbfrwkq0asCY=
+github.com/nyaruka/phonenumbers v1.2.2/go.mod h1:wzk2qq7qwsaBKrfbkWKdgHYOOH+QFTesSpIq53ELw8M=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
+github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
+github.com/quic-go/quic-go v0.59.1 h1:0Gmua0HW1Tv7ANR7hUYwRyD0MG5OJfgvYSZasGZzBic=
+github.com/quic-go/quic-go v0.59.1/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
+github.com/redis/go-redis/v9 v9.22.0 h1:laDvpYXTJtZLloinw1fA5Kqd6HAEH2XKxOkG/PDq2F0=
+github.com/redis/go-redis/v9 v9.22.0/go.mod h1:y2g0Wj8rQvuK0ELM+oxSudcLtC09JScs98I/X9gRWY4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
+github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/smarty/assertions v1.15.0 h1:cR//PqUBUiQRakZWqBiFFQ9wb8emQGDb0HeGdqGByCY=
+github.com/smarty/assertions v1.15.0/go.mod h1:yABtdzeQs6l1brC900WlRNwj6ZR55d7B+E8C6HtKdec=
+github.com/smartystreets/goconvey v1.8.1 h1:qGjIddxOk4grTu9JPOU31tVfq3cNdBlNa5sSznIX1xY=
+github.com/smartystreets/goconvey v1.8.1/go.mod h1:+/u4qLyY6x1jReYOp7GOM2FSt8aP9CzCZL03bI28W60=
+github.com/spf13/cast v1.7.1 h1:cuNEagBQEHWN1FnbGEjCXL2szYEXqfJPbP2HNUaca9Y=
+github.com/spf13/cast v1.7.1/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.5/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
+github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
+github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
+go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 h1:fQsdNF2N+/YewlRZiricy4P1iimyPKZ/xwniHj8Q2a0=
+golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93/go.mod h1:EPRbTFwzwjXj9NpYyyrvenVh9Y+GFeEvMNh7Xuz7xgU=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.39.0 h1:UbZz4pLOvn600D6Oh6GGEI6VAmndrEBLv8/6BEXzyus=
+golang.org/x/text v0.39.0/go.mod h1:3UwRclnC2g0TU9x8PZiyfOajCd1zaUNHF9cvqcQZ+ZM=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
+gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/sqlite v1.1.3/go.mod h1:AKDgRWk8lcSQSw+9kxCJnX/yySj8G3rdwYlU57cB45c=
+gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
+gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
+gorm.io/gorm v1.20.1/go.mod h1:0HFTzE/SqkGTzK6TlDPPQbAYCluiVvhzoA1+aVyzenw=
+gorm.io/gorm v1.23.0/go.mod h1:l2lP/RyAtc1ynaTjFksBde/O8v9oOGIApu2/xRitmZk=
+gorm.io/gorm v1.31.2 h1:3o8FXNo9v9S858gil+3LlZA1LkCOzgb4g5BL64FgaCo=
+gorm.io/gorm v1.31.2/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
+gorm.io/plugin/soft_delete v1.2.1 h1:qx9D/c4Xu6w5KT8LviX8DgLcB9hkKl6JC9f44Tj7cGU=
+gorm.io/plugin/soft_delete v1.2.1/go.mod h1:Zv7vQctOJTGOsJ/bWgrN1n3od0GBAZgnLjEx+cApLGk=
+modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
+modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
+modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=
+modernc.org/ccgo/v4 v4.30.1/go.mod h1:bIOeI1JL54Utlxn+LwrFyjCx2n2RDiYEaJVSrgdrRfM=
+modernc.org/fileutil v1.3.40 h1:ZGMswMNc9JOCrcrakF1HrvmergNLAmxOPjizirpfqBA=
+modernc.org/fileutil v1.3.40/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.1 h1:k8T3gkXWY9sEiytKhcgyiZ2L0DTyCQ/nvX+LoCljoRE=
+modernc.org/gc/v3 v3.1.1/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.67.4 h1:zZGmCMUVPORtKv95c2ReQN5VDjvkoRm9GWPTEPuvlWg=
+modernc.org/libc v1.67.4/go.mod h1:QvvnnJ5P7aitu0ReNpVIEyesuhmDLQ8kaEoyMjIFZJA=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.42.2 h1:7hkZUNJvJFN2PgfUdjni9Kbvd4ef4mNLOu0B9FGxM74=
+modernc.org/sqlite v1.42.2/go.mod h1:+VkC6v3pLOAE0A0uVucQEcbVW0I5nHCeDaBf+DpsQT8=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

example/app-order/migration/migration.go

@@ -0,0 +1,89 @@
+// Package migration registers app-order's one migration: create its two
+// tables and seed the menu/API entries the admin UI needs to expose them.
+//
+// It registers through contract/migration.ForApp - the package-level
+// facade, not a private NewRegistry() - because that is the only registry a
+// third-party app, which cannot reach into the host process, can register
+// against and have any hope of the host's own execution engine picking up.
+// Whether it actually does, today, is a different question: see this
+// package's test file and the gap list in the accompanying report.
+package migration
+
+import (
+	"gorm.io/gorm"
+
+	contractmigration "github.com/go-admin-team/go-admin-core/v2/sdk/contract/migration"
+	contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/seed"
+
+	"github.com/go-admin-team/example-app-order/models"
+)
+
+// AppCode is app-order's migration.ForApp / seed.SeedMenus identity.
+const AppCode = "order"
+
+// version is this migration's sys_migration key before ForApp namespaces
+// it (see contract/migration.ForApp's doc comment: the stored key becomes
+// "order-" + version). It follows the framework's own 13-digit millisecond
+// timestamp convention purely so a human reading sys_migration.version
+// alongside the framework's own rows can still eyeball roughly when it was
+// authored; contract/migration.ForApp does not require that shape, just
+// uniqueness within this app's own namespace.
+const version = "1793800000000"
+
+func init() {
+	contractmigration.ForApp(AppCode).SetVersion(version, createOrderSchema)
+}
+
+// createOrderSchema creates app_order/app_order_item and seeds the menu and
+// API entries a host's Seeder turns into sys_menu/sys_api/sys_menu_api_rule
+// rows (and, once an administrator grants the menu to a role through the
+// ordinary admin UI, casbin_rule). See seed.Seeder's security note: this
+// call does not sandbox anything, it only saves app-order from needing to
+// know go-admin's own schema.
+func createOrderSchema(db *gorm.DB, migrationVersion, appCode string) error {
+	return db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.AutoMigrate(&models.Order{}, &models.OrderItem{}); err != nil {
+			return err
+		}
+
+		menus := []seed.MenuSpec{
+			{
+				Code: "dir", Kind: contractmodels.Directory,
+				Title: "Order Example", Path: "/apps/order", Component: "Layout",
+				Icon: "shopping", Sort: 20,
+			},
+			{
+				Code: "list", Parent: "dir", Kind: contractmodels.Menu,
+				Title: "Orders", Path: "list",
+				// Component must start with "apps/<code>/" - see
+				// seed.MenuSpec.Component's doc comment. This is the one
+				// concrete rule the report's gap list has nothing bad to
+				// say about: it is documented exactly where a caller
+				// building a MenuSpec would look.
+				Component: "apps/order/order/index",
+				Sort:      1,
+				ApiCodes:  []string{"list", "get", "create", "pay"},
+			},
+			{
+				Code: "btn-create", Parent: "list", Kind: contractmodels.Button,
+				Title: "Create", Permission: "order:order:create", Sort: 1,
+			},
+			{
+				Code: "btn-pay", Parent: "list", Kind: contractmodels.Button,
+				Title: "Pay", Permission: "order:order:pay", Sort: 2,
+			},
+		}
+		apis := []seed.ApiSpec{
+			{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+			{Code: "get", Title: "Order detail", Path: "/api/v1/order/:id", Method: "GET", Handle: "apis.Order.Get-fm"},
+			{Code: "create", Title: "Create order", Path: "/api/v1/order", Method: "POST", Handle: "apis.Order.Create-fm"},
+			{Code: "pay", Title: "Pay order", Path: "/api/v1/order/:id/pay", Method: "PUT", Handle: "apis.Order.Pay-fm"},
+		}
+		if err := seed.SeedMenus(tx, appCode, menus, apis); err != nil {
+			return err
+		}
+
+		return tx.Create(&contractmodels.Migration{Version: migrationVersion, AppCode: appCode}).Error
+	})
+}

example/app-order/migration/migration_test.go

@@ -0,0 +1,153 @@
+package migration
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	contractmigration "github.com/go-admin-team/go-admin-core/v2/sdk/contract/migration"
+	contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/seed"
+
+	"github.com/go-admin-team/example-app-order/models"
+)
+
+// fakeSeeder stands in for a host's real Seeder (the one wt-shim, as of
+// this writing, never registers - see the accompanying report's gap list).
+// It records what it received instead of writing to any table, which is
+// enough to check app-order's own MenuSpec/ApiSpec assembly without
+// depending on go-admin's sys_menu/sys_api schema.
+type fakeSeeder struct {
+	appCode string
+	menus   []seed.MenuSpec
+	apis    []seed.ApiSpec
+}
+
+func (f *fakeSeeder) SeedMenus(tx *gorm.DB, appCode string, menus []seed.MenuSpec, apis []seed.ApiSpec) error {
+	f.appCode = appCode
+	f.menus = menus
+	f.apis = apis
+	return nil
+}
+
+// seed.RegisterSeeder panics on a second call in the same process (see its
+// doc comment) - by design, there is no public way to unregister one. This
+// package's tests share the one registration below rather than each
+// registering their own.
+var fake = &fakeSeeder{}
+
+func init() {
+	seed.RegisterSeeder(fake)
+}
+
+// TestRegistersUnderContractMigrationForApp is this package's core claim:
+// that createOrderSchema is reachable through contract/migration's
+// package-level Snapshot, the only registry a third-party module can
+// register against. It does not confirm any host actually calls Snapshot
+// today - see the report.
+func TestRegistersUnderContractMigrationForApp(t *testing.T) {
+	entries := contractmigration.Snapshot()
+	entry, ok := entries[AppCode+"-"+version]
+	if !ok {
+		t.Fatalf("no entry for %s-%s; registered: %v", AppCode, version, keysOf(entries))
+	}
+	if entry.AppCode != AppCode {
+		t.Errorf("Entry.AppCode = %q, want %q", entry.AppCode, AppCode)
+	}
+}
+
+func keysOf(m map[string]contractmigration.Entry) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
+// TestMigrationCreatesTablesSeedsMenusAndRecordsItself runs the registered
+// migration function directly against a fresh sqlite database - standing in
+// for the host's execution engine, which (see the report) does not exist
+// yet for an externally-registered app. It is the closest thing to an
+// end-to-end run this example can do without wt-shim's cooperation.
+func TestMigrationCreatesTablesSeedsMenusAndRecordsItself(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	// sys_migration itself is created by the framework's own first
+	// migration (go-admin's cmd/migrate/migration/version/*_tables.go),
+	// which by the time any app's migration runs has always already run -
+	// simulate that precondition rather than app-order's own migration
+	// creating a table it does not own.
+	if err := db.AutoMigrate(&contractmodels.Migration{}); err != nil {
+		t.Fatalf("automigrate sys_migration: %v", err)
+	}
+
+	entries := contractmigration.Snapshot()
+	entry, ok := entries[AppCode+"-"+version]
+	if !ok {
+		t.Fatalf("no entry for %s-%s", AppCode, version)
+	}
+	if err := entry.Fn(db, AppCode+"-"+version); err != nil {
+		t.Fatalf("running the registered migration: %v", err)
+	}
+
+	if !db.Migrator().HasTable(&models.Order{}) {
+		t.Error("app_order was not created")
+	}
+	if !db.Migrator().HasTable(&models.OrderItem{}) {
+		t.Error("app_order_item was not created")
+	}
+
+	var migrationRow contractmodels.Migration
+	if err := db.Where("version = ?", AppCode+"-"+version).First(&migrationRow).Error; err != nil {
+		t.Fatalf("sys_migration row: %v", err)
+	}
+	if migrationRow.AppCode != AppCode {
+		t.Errorf("sys_migration.app_code = %q, want %q", migrationRow.AppCode, AppCode)
+	}
+
+	if fake.appCode != AppCode {
+		t.Errorf("Seeder saw appCode %q, want %q", fake.appCode, AppCode)
+	}
+	assertMenuGraphIsConsistent(t, fake.menus, fake.apis)
+}
+
+// assertMenuGraphIsConsistent checks the two rules that would otherwise
+// only surface as a broken admin UI at install time: every Parent
+// reference resolves to a Code in the same batch, and the frontend's
+// apps/<code>/ convention for a packaged page's Component (documented on
+// MenuSpec.Component, enforced by nothing - see the report) is actually
+// followed.
+func assertMenuGraphIsConsistent(t *testing.T, menus []seed.MenuSpec, apis []seed.ApiSpec) {
+	t.Helper()
+
+	codes := make(map[string]seed.MenuSpec, len(menus))
+	for _, m := range menus {
+		codes[m.Code] = m
+	}
+	apiCodes := make(map[string]bool, len(apis))
+	for _, a := range apis {
+		apiCodes[a.Code] = true
+	}
+
+	for _, m := range menus {
+		if m.Parent != "" {
+			if _, ok := codes[m.Parent]; !ok {
+				t.Errorf("menu %q has Parent %q, which is not a Code in this batch", m.Code, m.Parent)
+			}
+		}
+		for _, ac := range m.ApiCodes {
+			if !apiCodes[ac] {
+				t.Errorf("menu %q references ApiCode %q, which is not in this batch's apis", m.Code, ac)
+			}
+		}
+		if m.Kind == contractmodels.Menu && m.Component != "" {
+			if !strings.HasPrefix(m.Component, "apps/"+AppCode+"/") {
+				t.Errorf("menu %q has Component %q, want it to start with apps/%s/", m.Code, m.Component, AppCode)
+			}
+		}
+	}
+}

example/app-order/models/order.go

@@ -0,0 +1,52 @@
+// Package models holds app-order's two GORM row models.
+package models
+
+import (
+	contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+)
+
+// The two values Order.Status can hold. Kept as narrow strings rather than
+// an int enum to match sys_role.data_scope's own convention in core, and to
+// leave room for a future status without a schema change.
+const (
+	StatusPending = "1" // awaiting payment
+	StatusPaid    = "2" // paid; set only by a successful Pay
+)
+
+// orderTable is passed to actions.Permission and repeated as
+// Order.TableName's return value. It is not literally the word "order":
+// that is a reserved SQL keyword, and actions.Permission builds its WHERE
+// clause by string-concatenating tableName straight into raw SQL
+// (`tableName+".create_by = ?"`, see permission.go) with no quoting at all.
+// A table named exactly "order" would make every data-scope query a syntax
+// error on MySQL's default (non-ANSI-quotes) mode. This is not something
+// core enforces or even mentions - Permission's tableName parameter is an
+// opaque string as far as it is concerned - so avoiding reserved words is
+// entirely on the caller.
+const orderTable = "app_order"
+
+// Order is one customer order. ControlBy is required, not decorative:
+// actions.Permission's data-scope SQL joins against create_by, so an Order
+// without it would make every data-scope rule silently match nothing.
+type Order struct {
+	contractmodels.Model
+
+	OrderNo    string `json:"orderNo" gorm:"type:varchar(64);uniqueIndex;comment:order number"`
+	UserId     int    `json:"userId" gorm:"index;comment:buyer user id"`
+	Status     string `json:"status" gorm:"type:varchar(4);index;comment:order status: 1 pending, 2 paid"`
+	TotalCents int64  `json:"totalCents" gorm:"comment:total amount in cents, sum of item price*quantity at creation time"`
+
+	// Items is populated by Preload; it is never set by Order's own migrator
+	// column set (OrderItem.OrderId is the foreign key, not a column here).
+	Items []OrderItem `json:"items,omitempty" gorm:"foreignKey:OrderId"`
+
+	contractmodels.ControlBy
+	contractmodels.ModelTime
+}
+
+// TableName pins the row model to app_order regardless of any global
+// singular/plural table naming strategy the host configures. See orderTable
+// above for why this is not simply "order".
+func (Order) TableName() string {
+	return orderTable
+}

example/app-order/models/order_item.go

@@ -0,0 +1,29 @@
+package models
+
+// orderItemTable mirrors orderTable's naming rationale: not a reserved word,
+// and namespaced under app_ so a host scanning its schema can tell at a
+// glance which tables an installed app owns.
+const orderItemTable = "app_order_item"
+
+// OrderItem is one line item of an Order. It carries no ControlBy of its
+// own: data-scope is enforced once, on the parent Order, and an item is
+// never queried on its own outside that parent (see service.Order.Get's
+// Preload).
+//
+// OrderId+ProductName is unique on purpose, not just to have some index: it
+// is what OrderService_test.go's mid-transaction-failure test relies on to
+// force a real constraint violation after the parent Order row has already
+// been inserted in the same transaction, proving the rollback actually
+// undoes both writes rather than leaving the Order behind.
+type OrderItem struct {
+	Id          int    `json:"id" gorm:"primaryKey;autoIncrement;comment:primary key"`
+	OrderId     int    `json:"orderId" gorm:"uniqueIndex:uk_app_order_item_product;comment:parent order id"`
+	ProductName string `json:"productName" gorm:"type:varchar(255);uniqueIndex:uk_app_order_item_product;comment:product name"`
+	Quantity    int    `json:"quantity" gorm:"comment:quantity"`
+	PriceCents  int64  `json:"priceCents" gorm:"comment:unit price in cents"`
+}
+
+// TableName pins the row model to app_order_item; see orderItemTable.
+func (OrderItem) TableName() string {
+	return orderItemTable
+}

example/app-order/router/router.go

@@ -0,0 +1,67 @@
+// Package router wires app-order's four routes onto a host's gin engine.
+package router
+
+import (
+	"github.com/gin-gonic/gin"
+
+	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
+	coreruntime "github.com/go-admin-team/go-admin-core/v2/sdk/runtime"
+
+	"github.com/go-admin-team/example-app-order/apis"
+)
+
+// RegisterRouter mounts app-order's routes under v1.
+//
+// Its signature - (v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware)
+// - is not app-order's own invention: it is the exact shape every in-tree
+// go-admin app router package already registers into its own routerCheckRole
+// slice (see app/demo/router/demo_product.go), so a host installs this
+// exactly where it installs its own app/*/router packages: one file under
+// cmd/api/ that imports this package and appends RegisterRouter (adjusted to
+// the host's own registration slice's calling convention) - see
+// cmd/api/demo.go for the pattern.
+//
+// authMiddleware is taken as an explicit parameter rather than fetched
+// through sdk.Runtime.GetHandlerFunc(coreruntime.JwtTokenCheck). As of this
+// writing the reference host (go-admin's common/middleware/init.go) registers
+// that key with an unbound method expression -
+// sdk.Runtime.SetMiddleware(JwtTokenCheck, (*jwt.GinJWTMiddleware).MiddlewareFunc)
+// - which is exactly the shape GetHandlerFunc's own doc comment warns
+// against: the stored value's type is func(*jwt.GinJWTMiddleware)
+// gin.HandlerFunc, not gin.HandlerFunc, so GetHandlerFunc's type assertion
+// fails and it reports ok=false every time, for every caller, not just this
+// one. Taking authMiddleware directly sidesteps that live bug and matches
+// what every in-tree app already does.
+func RegisterRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
+	roleCheck, ok := sdk.Runtime.GetHandlerFunc(coreruntime.RoleCheck)
+	if !ok {
+		// A host that has not wired up RoleCheck has not wired up Casbin
+		// authorization at all. Registering these routes without it would
+		// silently serve every order to every authenticated caller
+		// regardless of role - fail loud at startup instead, the same way
+		// PermissionAction fails loud (Abort, not c.Next) when its own
+		// database lookup errors. See contract/actions.PermissionAction's
+		// doc comment for the same reasoning applied to data-scope instead
+		// of role.
+		panic("app-order: host has not registered core's " + coreruntime.RoleCheck +
+			" middleware (sdk.Runtime.SetMiddleware); refusing to mount unauthorized order routes")
+	}
+
+	e := apis.Order{}
+	r := v1.Group("/order").
+		Use(authMiddleware.MiddlewareFunc()).
+		Use(roleCheck)
+	{
+		// actions.PermissionAction is imported directly from core - a plain
+		// function, not something fetched through sdk.Runtime - because
+		// unlike RoleCheck's Casbin policy tables (host-owned; see
+		// contract/actions's package doc), the data-scope machinery it
+		// installs has no host-specific state at all.
+		r.GET("", actions.PermissionAction(), e.GetPage)
+		r.GET("/:id", actions.PermissionAction(), e.Get)
+		r.POST("", e.Create)
+		r.PUT("/:id/pay", actions.PermissionAction(), e.Pay)
+	}
+}

example/app-order/router/router_test.go

@@ -0,0 +1,80 @@
+package router
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	coreruntime "github.com/go-admin-team/go-admin-core/v2/sdk/runtime"
+)
+
+func testAuthMiddleware(t *testing.T) *jwt.GinJWTMiddleware {
+	t.Helper()
+	mw, err := jwt.New(&jwt.GinJWTMiddleware{
+		Realm:            "test",
+		Key:              []byte("test-signing-key"),
+		SigningAlgorithm: "HS256",
+		Timeout:          0,
+		TokenLookup:      "header: Authorization",
+		TokenHeadName:    "Bearer",
+	})
+	if err != nil {
+		t.Fatalf("building a test JWT middleware: %v", err)
+	}
+	return mw
+}
+
+// sdk.Runtime is a single process-wide instance (see its doc comment) with no
+// way to unregister a middleware key, so this test needs RoleCheck to be
+// unset - which makes it look order-dependent. It is not: the test that does
+// register RoleCheck puts it back in a t.Cleanup, and the guard below turns a
+// wrong order into a loud failure rather than a silent pass. Verified with
+// `go test -shuffle=<seed>` on seeds that run the two in either order.
+func TestRegisterRouterPanicsWithoutHostRoleCheck(t *testing.T) {
+	if _, ok := sdk.Runtime.GetHandlerFunc(coreruntime.RoleCheck); ok {
+		t.Fatal("RoleCheck is already registered; this test must run before any test that registers it")
+	}
+
+	defer func() {
+		if recover() == nil {
+			t.Fatal("RegisterRouter did not panic with no host RoleCheck middleware registered")
+		}
+	}()
+
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	v1 := r.Group("/api/v1")
+	RegisterRouter(v1, testAuthMiddleware(t))
+}
+
+func TestRegisterRouterMountsRoutesOnceRoleCheckIsRegistered(t *testing.T) {
+	sdk.Runtime.SetMiddleware(coreruntime.RoleCheck, gin.HandlerFunc(func(c *gin.Context) { c.Next() }))
+	// sdk.Runtime has no way to unregister a middleware key (SetMiddleware
+	// only ever adds or overwrites - see its doc comment), so restore the
+	// "as far as GetHandlerFunc is concerned, unregistered" state other
+	// tests in this package depend on: a nil interface{} fails
+	// GetHandlerFunc's gin.HandlerFunc type assertion the same way a never-
+	// set key does. Needed for `go test -count=2` and similar re-runs
+	// within one process, not for a single run.
+	t.Cleanup(func() { sdk.Runtime.SetMiddleware(coreruntime.RoleCheck, nil) })
+
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	v1 := r.Group("/api/v1")
+	RegisterRouter(v1, testAuthMiddleware(t))
+
+	// A route that exists returns something other than 404, even if the
+	// JWT/Casbin/PermissionAction chain in front of it then rejects the
+	// unauthenticated test request - proving RegisterRouter actually wired
+	// the route up is the point, not exercising the auth chain itself.
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/order", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	if w.Code == http.StatusNotFound {
+		t.Errorf("GET /api/v1/order was not registered (404)")
+	}
+}

example/app-order/service/dto/order.go

@@ -0,0 +1,57 @@
+// Package dto holds app-order's request-binding types.
+//
+// None of them implement core's dto.Index / dto.Control, and none of them
+// define their own Bind method: those interfaces (and the Bind method they
+// require) exist so the framework's generic CRUD Actions
+// (Create/Delete/Index/Update/ViewAction) can bind a request without
+// knowing its concrete type - Action itself calls req.Bind(c). app-order's
+// handlers (apis/order.go) call api.Api.Bind directly on the raw struct
+// instead, exactly as go-admin's own hand-written handlers do (see
+// app/admin/apis/sys_post.go and its service/dto/sys_post.go, which is the
+// same shape: plain structs, no Bind method), so a Bind method here would
+// never be called by anything and would only mislead a reader into thinking
+// it is.
+//
+// What these types do reuse is dto.Pagination (for the list request's page
+// index/size) and the `search` struct-tag convention dto.MakeCondition
+// resolves; both are plain data shapes, not an interface a hand-written
+// handler would otherwise have to reimplement.
+package dto
+
+import (
+	contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
+)
+
+// OrderItemReq is one line item in a create-order request.
+type OrderItemReq struct {
+	ProductName string `json:"productName" validate:"required"`
+	Quantity    int    `json:"quantity" validate:"gte=1"`
+	PriceCents  int64  `json:"priceCents" validate:"gte=0"`
+}
+
+// OrderCreateReq is the create-order request body.
+type OrderCreateReq struct {
+	Items []OrderItemReq `json:"items" validate:"required"`
+}
+
+// OrderSearchReq is the list-order query.
+//
+// contractdto.MakeCondition reads q's `search` tags through
+// reflect.TypeOf(q).NumField(), which is only valid for a struct Kind - a
+// pointer panics rather than returning an error (see
+// service/order.go:GetPage, which is careful to pass *req, not req). That
+// distinction is not documented on MakeCondition's exported doc comment.
+// Pagination `search:"-"` here follows the same convention the framework's
+// own generic DTOs use to keep Pagination's two fields out of the WHERE
+// clause the tags on Status/OrderNo build.
+type OrderSearchReq struct {
+	contractdto.Pagination `search:"-"`
+
+	Status  string `form:"status" search:"type:exact;column:status;table:app_order"`
+	OrderNo string `form:"orderNo" search:"type:exact;column:order_no;table:app_order"`
+}
+
+// OrderIdReq binds a single :id, for a detail lookup or a Pay request.
+type OrderIdReq struct {
+	Id int `uri:"id" validate:"required"`
+}

example/app-order/service/order.go

@@ -0,0 +1,176 @@
+// Package service is app-order's business logic: everything the PRD asked
+// this example to prove out by hand rather than by wiring up core's generic
+// CRUD Actions (Create/Delete/Index/Update/ViewAction stay in go-admin, not
+// in core - see contract/actions's package doc for why). An order's write
+// path is a cross-table transaction and its one state change needs a
+// concurrency guard neither generic Action was ever built for, which is
+// exactly the class of logic real third-party apps almost always have.
+package service
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
+	contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/service"
+
+	"github.com/go-admin-team/example-app-order/models"
+	orderdto "github.com/go-admin-team/example-app-order/service/dto"
+)
+
+// ErrOrderEmpty is returned by Create when the request has no line items.
+var ErrOrderEmpty = errors.New("app-order: an order must have at least one item")
+
+// ErrOrderNotPending is returned by Pay when the order could not be paid:
+// it does not exist, it is not in models.StatusPending, or the caller's
+// data scope does not include it. Deliberately one error for all three -
+// see Pay's doc comment for why collapsing them is the fail-closed choice,
+// not a shortcut.
+var ErrOrderNotPending = errors.New("app-order: order is not awaiting payment")
+
+// Order is app-order's hand-written service. It embeds core's
+// sdk/service.Service purely for the Orm/Log/Cache fields every
+// api.Api.MakeService caller already wires up the same way go-admin's own
+// hand-written services do (see app/admin/apis/sys_post.go) - not because
+// anything here calls a method Service defines.
+type Order struct {
+	service.Service
+}
+
+// Create places a new order. The order row and every item row commit
+// together: db.Transaction's closure form is what makes that true even
+// across a panic (it recovers, rolls back, and re-panics - see gorm's own
+// Transaction implementation), unlike the hand-rolled Begin/defer pattern
+// go-admin's sys_role.go/sys_dept.go/sys_menu.go/sys_tables.go use, which
+// commits a half-written transaction on panic, never opens a real
+// transaction under sqlite, and reads a single global DB handle regardless
+// of which tenant the request is for.
+func (e *Order) Create(req *orderdto.OrderCreateReq, userId int) (*models.Order, error) {
+	if len(req.Items) == 0 {
+		return nil, ErrOrderEmpty
+	}
+
+	items := make([]models.OrderItem, 0, len(req.Items))
+	var total int64
+	for _, it := range req.Items {
+		total += it.PriceCents * int64(it.Quantity)
+		items = append(items, models.OrderItem{
+			ProductName: it.ProductName,
+			Quantity:    it.Quantity,
+			PriceCents:  it.PriceCents,
+		})
+	}
+
+	order := &models.Order{
+		OrderNo:    generateOrderNo(),
+		UserId:     userId,
+		Status:     models.StatusPending,
+		TotalCents: total,
+	}
+	order.SetCreateBy(userId)
+	order.SetUpdateBy(userId)
+
+	err := e.Orm.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Create(order).Error; err != nil {
+			return err
+		}
+		for i := range items {
+			items[i].OrderId = order.Id
+		}
+		// A single batch Create, not one Create per item: on the unique
+		// (order_id, product_name) violation the test suite exercises, the
+		// whole statement fails, and nothing about this order - not the
+		// order row created two lines above, not any item before the
+		// duplicate - survives the rollback.
+		if err := tx.Create(&items).Error; err != nil {
+			return err
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	order.Items = items
+	return order, nil
+}
+
+// Get loads one order, scoped to p's data permission, with its items.
+func (e *Order) Get(id int, p *actions.DataPermission, out *models.Order) error {
+	return e.Orm.
+		Scopes(actions.Permission(orderTableName, p)).
+		Preload("Items").
+		Where("id = ?", id).
+		First(out).Error
+}
+
+// GetPage lists orders visible to p's data scope, filtered by req's search
+// tags and paginated. The Find-then-Count-on-the-same-chain shape mirrors
+// go-admin's own common/actions.IndexAction: Limit(-1).Offset(-1) undoes
+// Paginate's LIMIT/OFFSET before the count runs, on the same *gorm.DB
+// session, so the WHERE clause built by MakeCondition and Permission is not
+// re-resolved a second time.
+func (e *Order) GetPage(req *orderdto.OrderSearchReq, p *actions.DataPermission, list *[]models.Order) (int64, error) {
+	var count int64
+	// *req, not req: contractdto.MakeCondition resolves search tags through
+	// reflect.TypeOf(q).NumField(), which panics on a pointer. See
+	// service/dto/order.go's doc comment on OrderSearchReq.
+	err := e.Orm.Model(&models.Order{}).
+		Scopes(
+			contractdto.MakeCondition(*req),
+			contractdto.Paginate(req.GetPageSize(), req.GetPageIndex()),
+			actions.Permission(orderTableName, p),
+		).
+		Find(list).Limit(-1).Offset(-1).
+		Count(&count).Error
+	return count, err
+}
+
+// Pay transitions a pending order to paid.
+//
+// The concurrency guard is the WHERE clause, not an application-level lock:
+// two concurrent payment attempts against the same order both issue this
+// UPDATE, but only the one that actually flips a row from pending to paid
+// sees RowsAffected == 1 - the loser's WHERE matches nothing (the row is
+// already 'paid' by the time its UPDATE runs) and sees 0, becoming
+// ErrOrderNotPending rather than a second, silently-accepted payment.
+//
+// The same RowsAffected==0 outcome also covers "no such order" and "this
+// order exists but is outside p's data scope" - actions.Permission's own
+// scope is one of the Scopes below, so a caller paying an order they
+// cannot see gets the identical error a caller paying an already-paid
+// order gets. That collapse is deliberate: a distinguishable "exists but
+// not yours" response would leak which order ids exist to a caller who
+// should not be able to tell.
+func (e *Order) Pay(id int, p *actions.DataPermission) error {
+	result := e.Orm.
+		Scopes(actions.Permission(orderTableName, p)).
+		Model(&models.Order{}).
+		Where("id = ? AND status = ?", id, models.StatusPending).
+		Updates(map[string]interface{}{"status": models.StatusPaid})
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return ErrOrderNotPending
+	}
+	return nil
+}
+
+// orderTableName is models.Order{}.TableName(), repeated here as a plain
+// string because actions.Permission takes the table name as a bare string,
+// not a model - see models/order.go's orderTable doc comment for why it is
+// not literally "order".
+const orderTableName = "app_order"
+
+// generateOrderNo is a placeholder good enough for this example: real
+// production code would want a collision-proof id source (a sequence, a
+// snowflake id, or similar). Nothing about the transaction or the
+// concurrency guard above depends on how this string is built.
+func generateOrderNo() string {
+	return fmt.Sprintf("ORD%d", time.Now().UnixNano())
+}

example/app-order/service/order_test.go

@@ -0,0 +1,352 @@
+package service
+
+import (
+	"errors"
+	"sync"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
+	coreservice "github.com/go-admin-team/go-admin-core/v2/sdk/service"
+
+	"github.com/go-admin-team/example-app-order/models"
+	orderdto "github.com/go-admin-team/example-app-order/service/dto"
+)
+
+// testDB returns a fresh, isolated in-memory sqlite database with
+// app_order/app_order_item created, following the same
+// glebarez/sqlite-and-no-build-tag setup core's own contract package tests
+// use (see sdk/contract/actions/permission_test.go and
+// sdk/contract/seed/seed_test.go).
+func testDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&models.Order{}, &models.OrderItem{}); err != nil {
+		t.Fatalf("automigrate: %v", err)
+	}
+	return db
+}
+
+// enableDataPermission flips on the switch actions.Permission checks before
+// applying any data-scope filtering at all, restoring the previous value
+// after the test - the same pattern
+// sdk/contract/actions/permission_test.go uses.
+func enableDataPermission(t *testing.T) {
+	t.Helper()
+	previous := config.ApplicationConfig.EnableDP
+	config.ApplicationConfig.EnableDP = true
+	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
+}
+
+func newOrderService(t *testing.T, db *gorm.DB) *Order {
+	t.Helper()
+	return &Order{Service: coreservice.Service{Orm: db}}
+}
+
+// -- cross-table transaction ------------------------------------------------
+
+func TestCreate_CommitsOrderAndItemsTogether(t *testing.T) {
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	req := &orderdto.OrderCreateReq{Items: []orderdto.OrderItemReq{
+		{ProductName: "widget", Quantity: 2, PriceCents: 500},
+		{ProductName: "gadget", Quantity: 1, PriceCents: 1200},
+	}}
+
+	order, err := s.Create(req, 42)
+	if err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	if order.TotalCents != 2*500+1200 {
+		t.Errorf("TotalCents = %d, want %d", order.TotalCents, 2*500+1200)
+	}
+	if order.Status != models.StatusPending {
+		t.Errorf("Status = %q, want pending", order.Status)
+	}
+	if order.CreateBy != 42 || order.UpdateBy != 42 {
+		t.Errorf("CreateBy/UpdateBy = %d/%d, want 42/42", order.CreateBy, order.UpdateBy)
+	}
+
+	var itemCount int64
+	db.Model(&models.OrderItem{}).Where("order_id = ?", order.Id).Count(&itemCount)
+	if itemCount != 2 {
+		t.Errorf("persisted %d items, want 2", itemCount)
+	}
+}
+
+func TestCreate_EmptyItemsReturnsErrorAndWritesNothing(t *testing.T) {
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	_, err := s.Create(&orderdto.OrderCreateReq{}, 1)
+	if !errors.Is(err, ErrOrderEmpty) {
+		t.Fatalf("got error %v, want ErrOrderEmpty", err)
+	}
+
+	var count int64
+	db.Model(&models.Order{}).Count(&count)
+	if count != 0 {
+		t.Errorf("an order was written despite the empty-items error")
+	}
+}
+
+// A mid-transaction failure must roll back everything written before it in
+// the same transaction, including the parent row. The duplicate product
+// name is what forces a real, DB-enforced constraint violation on the
+// second item's insert - see OrderItem's doc comment.
+func TestCreate_MidTransactionFailureRollsBackEverything(t *testing.T) {
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	req := &orderdto.OrderCreateReq{Items: []orderdto.OrderItemReq{
+		{ProductName: "widget", Quantity: 1, PriceCents: 100},
+		{ProductName: "widget", Quantity: 1, PriceCents: 100}, // duplicate: violates uk_app_order_item_product
+	}}
+
+	_, err := s.Create(req, 1)
+	if err == nil {
+		t.Fatal("Create succeeded despite a duplicate line item; the unique constraint did not fire")
+	}
+
+	var orderCount, itemCount int64
+	db.Model(&models.Order{}).Count(&orderCount)
+	db.Model(&models.OrderItem{}).Count(&itemCount)
+	if orderCount != 0 {
+		t.Errorf("the order row survived the rollback: %d rows in app_order", orderCount)
+	}
+	if itemCount != 0 {
+		t.Errorf("an item row survived the rollback: %d rows in app_order_item", itemCount)
+	}
+}
+
+// A panic partway through the transaction must roll back exactly as
+// cleanly as a returned error does. This is not testing app-order's own
+// code so much as the primitive Create is built on: gorm's db.Transaction
+// recovers a panic, rolls back, and re-panics, which is what makes it safe
+// to use in place of go-admin's hand-rolled Begin/defer pattern (see
+// Create's doc comment) - a pattern that, on a panic, commits whatever the
+// transaction had written so far instead of undoing it.
+func TestCreate_PanicInsideTransactionRollsBackEverything(t *testing.T) {
+	db := testDB(t)
+
+	func() {
+		defer func() {
+			if recover() == nil {
+				t.Fatal("db.Transaction did not propagate the panic")
+			}
+		}()
+		_ = db.Transaction(func(tx *gorm.DB) error {
+			if err := tx.Create(&models.Order{OrderNo: "panic-test", Status: models.StatusPending}).Error; err != nil {
+				t.Fatalf("Create inside transaction: %v", err)
+			}
+			panic("simulated failure after a partial write")
+		})
+	}()
+
+	var count int64
+	db.Model(&models.Order{}).Count(&count)
+	if count != 0 {
+		t.Errorf("the order row survived a panic mid-transaction: %d rows in app_order", count)
+	}
+}
+
+// -- status transition / concurrency guard ----------------------------------
+
+func createPendingOrder(t *testing.T, s *Order, userId int) *models.Order {
+	t.Helper()
+	order, err := s.Create(&orderdto.OrderCreateReq{Items: []orderdto.OrderItemReq{
+		{ProductName: "widget", Quantity: 1, PriceCents: 100},
+	}}, userId)
+	if err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	return order
+}
+
+func TestPay_TransitionsPendingToPaid(t *testing.T) {
+	db := testDB(t)
+	s := newOrderService(t, db)
+	order := createPendingOrder(t, s, 1)
+
+	if err := s.Pay(order.Id, &actions.DataPermission{DataScope: actions.DataScopeAll}); err != nil {
+		t.Fatalf("Pay: %v", err)
+	}
+
+	var got models.Order
+	db.First(&got, order.Id)
+	if got.Status != models.StatusPaid {
+		t.Errorf("Status = %q, want paid", got.Status)
+	}
+}
+
+func TestPay_AlreadyPaidReturnsErrOrderNotPending(t *testing.T) {
+	db := testDB(t)
+	s := newOrderService(t, db)
+	order := createPendingOrder(t, s, 1)
+	all := &actions.DataPermission{DataScope: actions.DataScopeAll}
+
+	if err := s.Pay(order.Id, all); err != nil {
+		t.Fatalf("first Pay: %v", err)
+	}
+	if err := s.Pay(order.Id, all); !errors.Is(err, ErrOrderNotPending) {
+		t.Fatalf("second Pay returned %v, want ErrOrderNotPending", err)
+	}
+}
+
+// Two concurrent payment attempts against the same pending order: exactly
+// one must succeed. MaxOpenConns(1) is set on the underlying *sql.DB so the
+// two goroutines' UPDATEs serialize the way two independent connections
+// would under MySQL, rather than one of them failing outright with
+// SQLITE_BUSY - sqlite is a single-writer database with no useful
+// concurrency of its own to exercise here. What the test actually verifies
+// is unaffected by that: the guard is the UPDATE ... WHERE status =
+// 'pending' clause and the RowsAffected check on its result (Pay's doc
+// comment), and that logic runs once per goroutine regardless of how the
+// pool schedules the two connections.
+func TestPay_ConcurrentPaymentsOnlyOneSucceeds(t *testing.T) {
+	db := testDB(t)
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("DB(): %v", err)
+	}
+	sqlDB.SetMaxOpenConns(1)
+
+	s := newOrderService(t, db)
+	order := createPendingOrder(t, s, 1)
+	all := &actions.DataPermission{DataScope: actions.DataScopeAll}
+
+	var wg sync.WaitGroup
+	errs := make([]error, 2)
+	for i := 0; i < 2; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			errs[i] = s.Pay(order.Id, all)
+		}(i)
+	}
+	wg.Wait()
+
+	successes, failures := 0, 0
+	for _, err := range errs {
+		switch {
+		case err == nil:
+			successes++
+		case errors.Is(err, ErrOrderNotPending):
+			failures++
+		default:
+			t.Fatalf("unexpected error from a concurrent Pay: %v", err)
+		}
+	}
+	if successes != 1 || failures != 1 {
+		t.Fatalf("got %d successes and %d failures, want exactly 1 and 1", successes, failures)
+	}
+}
+
+// -- data permission ---------------------------------------------------------
+
+func TestGetPage_SelfScopeOnlySeesOwnOrders(t *testing.T) {
+	enableDataPermission(t)
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	createPendingOrder(t, s, 1) // belongs to user 1
+	createPendingOrder(t, s, 2) // belongs to user 2
+
+	var list []models.Order
+	count, err := s.GetPage(&orderdto.OrderSearchReq{}, &actions.DataPermission{
+		DataScope: actions.DataScopeSelf,
+		UserId:    1,
+	}, &list)
+	if err != nil {
+		t.Fatalf("GetPage: %v", err)
+	}
+	if count != 1 || len(list) != 1 {
+		t.Fatalf("got %d orders, want exactly the 1 belonging to user 1", count)
+	}
+	if list[0].UserId != 1 {
+		t.Errorf("returned order belongs to user %d, not the caller", list[0].UserId)
+	}
+}
+
+func TestGetPage_AllScopeSeesEveryOrder(t *testing.T) {
+	enableDataPermission(t)
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	createPendingOrder(t, s, 1)
+	createPendingOrder(t, s, 2)
+
+	var list []models.Order
+	count, err := s.GetPage(&orderdto.OrderSearchReq{}, &actions.DataPermission{DataScope: actions.DataScopeAll}, &list)
+	if err != nil {
+		t.Fatalf("GetPage: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("got %d orders, want 2", count)
+	}
+}
+
+// An invalid/unrecognized data_scope must fail closed - match nothing -
+// never fall back to "see everything". This is core's own documented
+// contract (contract/actions.Permission's default case), exercised here
+// against app-order's own table to confirm the fail-closed behaviour
+// actually reaches a hand-written Service's query, not just core's own
+// unit tests.
+func TestGetPage_InvalidScopeSeesNothing(t *testing.T) {
+	enableDataPermission(t)
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	createPendingOrder(t, s, 1)
+	createPendingOrder(t, s, 2)
+
+	var list []models.Order
+	count, err := s.GetPage(&orderdto.OrderSearchReq{}, &actions.DataPermission{DataScope: "not-a-real-scope"}, &list)
+	if err != nil {
+		t.Fatalf("GetPage: %v", err)
+	}
+	if count != 0 || len(list) != 0 {
+		t.Fatalf("an invalid data scope returned %d orders, want 0 (fail closed)", count)
+	}
+}
+
+func TestGet_ReturnsOrderWithItemsPreloaded(t *testing.T) {
+	enableDataPermission(t)
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	created := createPendingOrder(t, s, 1)
+
+	var got models.Order
+	err := s.Get(created.Id, &actions.DataPermission{DataScope: actions.DataScopeSelf, UserId: 1}, &got)
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+	if len(got.Items) != 1 {
+		t.Fatalf("got %d items, want the 1 created with the order", len(got.Items))
+	}
+	if got.Items[0].ProductName != "widget" {
+		t.Errorf("item ProductName = %q, want widget", got.Items[0].ProductName)
+	}
+}
+
+func TestGet_ScopedOutOrderReportsNotFoundNotForbidden(t *testing.T) {
+	enableDataPermission(t)
+	db := testDB(t)
+	s := newOrderService(t, db)
+
+	other := createPendingOrder(t, s, 2)
+
+	var got models.Order
+	err := s.Get(other.Id, &actions.DataPermission{DataScope: actions.DataScopeSelf, UserId: 1}, &got)
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("Get on another user's order returned %v, want gorm.ErrRecordNotFound", err)
+	}
+}

go.mod

@@ -11,7 +11,7 @@ require (
 	github.com/casbin/casbin/v3 v3.8.1
 	github.com/gin-gonic/gin v1.12.0
 	github.com/glebarez/sqlite v1.11.0
-	github.com/go-admin-team/go-admin-core/v2 v2.5.0
+	github.com/go-admin-team/go-admin-core/v2 v2.6.0
 	github.com/google/uuid v1.6.0
 	github.com/huaweicloud/huaweicloud-sdk-go-obs v3.26.6+incompatible
 	github.com/mssola/user_agent v0.6.0

go.sum

@@ -147,6 +147,8 @@ github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GM
 github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
 github.com/go-admin-team/go-admin-core/v2 v2.5.0 h1:aD1SALklBxizGB9u8cOgm4OT8z656FM83F4fD6dMz9g=
 github.com/go-admin-team/go-admin-core/v2 v2.5.0/go.mod h1:LG/XvEfOplbuadKrPTPm0Nu5pN06aQUNZZC3ao4B4gs=
+github.com/go-admin-team/go-admin-core/v2 v2.6.0 h1:sRoZaxniTpbe287uR/uWpA14Jl1GTAcfGXLKoBLph2w=
+github.com/go-admin-team/go-admin-core/v2 v2.6.0/go.mod h1:LG/XvEfOplbuadKrPTPm0Nu5pN06aQUNZZC3ao4B4gs=
 github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-kit/kit v0.10.0/go.mod h1:xUsJbQ/Fp4kEt7AFgCuvyX4a71u8h9jB8tj/ORgOZ7o=

tools/checksilent/checks.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+	"go/ast"
 	"go/token"
 	"path"
 	"sort"
@@ -18,6 +19,8 @@ const (
 	checkConfigValue    = "config-value-truncation"
 	checkMenuIDConflict = "menu-id-collision"
 	checkImportBoundary = "contract-import-boundary"
+	checkShimAlias      = "contract-shim-alias"
+	checkDataScopeRoute = "datascope-route-unguarded"
 )
 
 // Package paths, relative to the module. Spelled once so a module rename
@@ -44,6 +47,8 @@ func runChecks(s *snapshot, opt options) ([]Finding, error) {
 	out = append(out, checkConfigValueLength(s)...)
 	out = append(out, checkMenuIDCollisions(s)...)
 	out = append(out, checkContractImportBoundary(s)...)
+	out = append(out, checkContractShimAlias(s)...)
+	out = append(out, checkDataScopeRoutes(s)...)
 
 	if opt.UIDir != "" {
 		fs, err := checkMenuNames(s, opt.UIDir)
@@ -109,6 +114,9 @@ func checkModelTimeMixing(s *snapshot) []Finding {
 	frozen := s.pkg(pkgFrozenModels)
 
 	for _, sf := range s.Files {
+		if sf.isTest() {
+			continue
+		}
 		if strings.HasPrefix(sf.Path, "app/") && sf.Imports(frozen) {
 			tables := tableNames(sf)
 			for name, st := range structTypes(sf) {
@@ -166,6 +174,9 @@ func checkMenuSortOverflow(s *snapshot) []Finding {
 	)
 	var out []Finding
 	for _, sf := range s.Files {
+		if sf.isTest() {
+			continue
+		}
 		forEachStructLiteral(sf, func(lit structLiteral) {
 			if !s.isMenuModel(lit) {
 				return
@@ -204,6 +215,9 @@ func checkConfigValueLength(s *snapshot) []Finding {
 	const limit = 255
 	var out []Finding
 	for _, sf := range s.Files {
+		if sf.isTest() {
+			continue
+		}
 		forEachStructLiteral(sf, func(lit structLiteral) {
 			if lit.Name != "SysConfig" || !s.isModelPackage(lit.PkgPath) {
 				return
@@ -251,6 +265,9 @@ func checkMenuIDCollisions(s *snapshot) []Finding {
 	sites := map[int64][]site{}
 
 	for _, sf := range s.Files {
+		if sf.isTest() {
+			continue
+		}
 		forEachStructLiteral(sf, func(lit structLiteral) {
 			if !s.isMenuModel(lit) {
 				return
@@ -379,6 +396,135 @@ func checkContractImportBoundary(s *snapshot) []Finding {
 	return out
 }
 
+// ---------------------------------------------------------------------------
+// check 7: a shim of a core contract type must be an alias
+// ---------------------------------------------------------------------------
+
+// coreModulePrefix and coreContractSegment together identify a package under
+// core's contract namespace. Matched as prefix plus segment rather than as one
+// literal path so that a major-version bump of core - which rewrites the
+// /v2 in every import - does not quietly turn this check off.
+const (
+	coreModulePrefix    = "github.com/go-admin-team/go-admin-core/"
+	coreContractSegment = "/sdk/contract/"
+)
+
+// isCoreContractPkg reports whether an import path names one of core's
+// contract packages.
+func isCoreContractPkg(path string) bool {
+	return strings.HasPrefix(path, coreModulePrefix) && strings.Contains(path, coreContractSegment)
+}
+
+// checkContractShimAlias reports a shim of a core contract type that was
+// written as a defined type instead of an alias.
+//
+//	type ControlBy = models.ControlBy   // alias: same type, same method set
+//	type ControlBy models.ControlBy     // defined type: methods are gone
+//
+// The two lines differ by one character and by everything else. A defined type
+// takes the underlying struct and none of the methods declared on it, so a
+// model embedding the second one no longer has SetCreateBy or SetUpdateBy and
+// no longer satisfies ActiveRecord - which is not a warning, it is a compile
+// error, but only in code that actually uses the method set.
+//
+// That is why the compiler is not enough on its own. This repository exercises
+// some of the contract types through interfaces and some not at all; the ones
+// it does not exercise compile perfectly well as defined types here and break
+// in a third-party application, or in a fork's own module, which is where
+// nobody is looking. The check costs one field of the AST - a type alias
+// records the position of its '=' - and covers the surface uniformly rather
+// than covering whatever app/demo happens to touch this month.
+//
+// The trigger is the right-hand side, not a list of names: any type declared
+// from a core contract package is one of these, whoever wrote it and whenever
+// it was added. A type declared from a local struct literal is not caught by
+// this - see ScannedShimAliases, which is what stops a run over a tree with no
+// shims in it from reading as a clean bill of health.
+func checkContractShimAlias(s *snapshot) []Finding {
+	var out []Finding
+	for _, sf := range s.Files {
+		forEachTypeSpec(sf, func(ts *ast.TypeSpec) {
+			qualifier, pkg, name, ok := qualifiedType(sf, ts.Type)
+			if !ok || !isCoreContractPkg(pkg) {
+				return
+			}
+			if ts.Assign.IsValid() {
+				return // "type X = pkg.Y", which is what it must be
+			}
+			out = append(out, s.finding(Error, checkShimAlias, sf, ts,
+				"%s is declared from %s.%s as a defined type, not an alias;\n"+
+					"    a defined type keeps the fields and drops the method set, so anything embedding it stops satisfying\n"+
+					"    the interfaces it satisfied before - here it may still compile, in a fork or a third-party app it does not.\n"+
+					"    Write it as: type %s = %s.%s",
+				ts.Name.Name, qualifier, name, ts.Name.Name, qualifier, name))
+		})
+	}
+	return out
+}
+
+// ScannedShimAliases counts the type aliases into core's contract packages the
+// snapshot holds, so the summary can say whether checkContractShimAlias found
+// anything to guard at all.
+//
+// Reported for the same reason ScannedContractRoots is: before the contract
+// packages are lowered into core there are no shims here, the check has
+// nothing to look at, and a run that printed nothing would look exactly like a
+// run over a tree that passed.
+func ScannedShimAliases(s *snapshot) int {
+	n := 0
+	for _, sf := range s.Files {
+		forEachTypeSpec(sf, func(ts *ast.TypeSpec) {
+			_, pkg, _, ok := qualifiedType(sf, ts.Type)
+			if ok && isCoreContractPkg(pkg) && ts.Assign.IsValid() {
+				n++
+			}
+		})
+	}
+	return n
+}
+
+// forEachTypeSpec visits every type declaration in the file, including the
+// ones inside a parenthesised type block.
+func forEachTypeSpec(sf *sourceFile, fn func(*ast.TypeSpec)) {
+	for _, decl := range sf.Syntax.Decls {
+		gen, ok := decl.(*ast.GenDecl)
+		if !ok || gen.Tok != token.TYPE {
+			continue
+		}
+		for _, spec := range gen.Specs {
+			if ts, ok := spec.(*ast.TypeSpec); ok {
+				fn(ts)
+			}
+		}
+	}
+}
+
+// qualifiedType resolves a type expression that names a type in another
+// package, returning that package's import path and the type name. A bare
+// identifier, a struct literal or anything else reports false: this asks
+// specifically "is the right-hand side pkg.Name", which is the shape both a
+// correct shim and the mistake it guards against are written in.
+// The qualifier returned is the one written in this file, which is not
+// path.Base of the import path whenever the import is aliased - and the shim
+// files alias every one of them (contractmodels, contractdto). A message that
+// suggests a fix has to spell it the way the file already does, or the line it
+// tells the author to write does not compile.
+func qualifiedType(sf *sourceFile, typ ast.Expr) (qualifier, pkgPath, name string, ok bool) {
+	sel, isSel := typ.(*ast.SelectorExpr)
+	if !isSel {
+		return "", "", "", false
+	}
+	ident, isIdent := sel.X.(*ast.Ident)
+	if !isIdent {
+		return "", "", "", false
+	}
+	p, found := sf.imports[ident.Name]
+	if !found {
+		return "", "", "", false
+	}
+	return ident.Name, p, sel.Sel.Name, true
+}
+
 // migrationVersion reads the 13-digit timestamp a migration file name starts
 // with. Files outside the two migration directories are not migrations, however
 // they are named.
@@ -398,9 +544,23 @@ func migrationVersion(rel string) (int64, bool) {
 	return v, true
 }
 
-// isMenuModel reports whether a literal is one of the SysMenu models rather
-// than, say, the SysMenu service struct that shares the name.
+// isMenuModel reports whether a literal describes a menu row, whichever of
+// the two shapes it is written in.
+//
+// A host module seeds a menu by building the SysMenu model directly. An
+// application installed from outside this repository cannot reach that type,
+// so it describes the same row as a seed.MenuSpec and hands it to the host's
+// Seeder. Both end up in sys_menu and both are subject to its column widths,
+// so a check that knew only the first shape would go quiet exactly when the
+// author is furthest from the schema it protects.
+//
+// That is not hypothetical: this repository's own reference application was
+// written with a Sort of 200 - past the tinyint sys_menu.sort is built as -
+// and this check passed it, because a MenuSpec is not a SysMenu.
 func (s *snapshot) isMenuModel(lit structLiteral) bool {
+	if lit.Name == "MenuSpec" && isCoreContractPkg(lit.PkgPath) {
+		return true
+	}
 	return lit.Name == "SysMenu" && s.isModelPackage(lit.PkgPath)
 }
 

tools/checksilent/checks_test.go

@@ -452,3 +452,219 @@ func TestComponentNameParsesBothVueStyles(t *testing.T) {
 		t.Error("a component with no declared name must not be compared")
 	}
 }
+
+// ---------------------------------------------------------------------------
+
+const coreContractModels = "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+
+// shimFixture writes one shim file declaring ControlBy from core's contract
+// package, in whichever of the two forms the caller asks for.
+func shimFixture(t *testing.T, decl string) string {
+	t.Helper()
+	return fixture(t, map[string]string{
+		"common/models/by.go": "package models\n\nimport \"" + coreContractModels + "\"\n\n" + decl + "\n",
+	})
+}
+
+func TestShimAliasDetectsADefinedType(t *testing.T) {
+	root := shimFixture(t, "type ControlBy models.ControlBy")
+
+	f := requireOne(t, check(t, root, options{}), checkShimAlias)
+	if f.Severity != "ERROR" {
+		t.Errorf("severity = %s", f.Severity)
+	}
+	if !strings.Contains(f.Message, "type ControlBy = models.ControlBy") {
+		t.Errorf("the message must spell out the fix; got %s", f.Message)
+	}
+	if f.File != "common/models/by.go" || f.Line != 5 {
+		t.Errorf("position = %s:%d", f.File, f.Line)
+	}
+}
+
+// The counterproof for the check above: the same fixture with the one
+// character that makes it correct must produce nothing. Without this the check
+// could be reporting every type declaration it sees and the test above would
+// still pass.
+func TestShimAliasAcceptsAnAlias(t *testing.T) {
+	root := shimFixture(t, "type ControlBy = models.ControlBy")
+	if got := only(t, check(t, root, options{}), checkShimAlias); len(got) != 0 {
+		t.Errorf("reported %v", got)
+	}
+}
+
+// A parenthesised type block is how a shim package with more than one type
+// tends to get written, and a walker that only looked at single-spec
+// declarations would skip all but the first.
+func TestShimAliasReadsAParenthesisedBlock(t *testing.T) {
+	root := shimFixture(t, `type (
+	Model     = models.Model
+	ControlBy models.ControlBy
+	ModelTime = models.ModelTime
+)`)
+	f := requireOne(t, check(t, root, options{}), checkShimAlias)
+	if !strings.Contains(f.Message, "ControlBy") {
+		t.Errorf("message = %s", f.Message)
+	}
+}
+
+// A defined type over a package that is not core's contract namespace is
+// somebody's ordinary code. The check exists for the surface core promises to
+// keep stable, and reporting anything else would make it a style rule.
+func TestShimAliasIgnoresOtherPackages(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/demo/models/product.go": `package models
+
+import "go-admin/common/models"
+
+type Product models.Model
+`,
+	})
+	if got := only(t, check(t, root, options{}), checkShimAlias); len(got) != 0 {
+		t.Errorf("reported %v", got)
+	}
+}
+
+// The version is part of core's import path and changes on every major bump.
+// Matching the whole path literally would turn the check off on that day and
+// say nothing about it.
+func TestShimAliasSurvivesACoreMajorVersionBump(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"common/models/by.go": `package models
+
+import "github.com/go-admin-team/go-admin-core/v9/sdk/contract/models"
+
+type ControlBy models.ControlBy
+`,
+	})
+	if got := only(t, check(t, root, options{}), checkShimAlias); len(got) != 1 {
+		t.Errorf("findings = %v", got)
+	}
+}
+
+// A tree with no shims in it is the state of this repository until the
+// contract packages are lowered, and the check saying nothing there must not
+// be reported as a boundary being guarded.
+func TestShimAliasCoverageIsReportedAsZeroWhenThereAreNoShims(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"common/models/by.go": "package models\n\ntype ControlBy struct{}\n",
+	})
+	s, err := load(root)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if n := ScannedShimAliases(s); n != 0 {
+		t.Errorf("ScannedShimAliases = %d, want 0", n)
+	}
+
+	var buf strings.Builder
+	if _, err := run(&buf, root, options{}, false); err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if !strings.Contains(buf.String(), "guarded nothing") {
+		t.Errorf("the summary must say the check covered nothing; got:\n%s", buf.String())
+	}
+}
+
+func TestShimAliasCoverageCountsTheAliasesItGuards(t *testing.T) {
+	root := shimFixture(t, `type (
+	Model     = models.Model
+	ControlBy = models.ControlBy
+)`)
+	s, err := load(root)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if n := ScannedShimAliases(s); n != 2 {
+		t.Errorf("ScannedShimAliases = %d, want 2", n)
+	}
+}
+
+// A menu written as a seed.MenuSpec lands in the same sys_menu.sort column as
+// one written as a SysMenu, so the same tinyint bound applies. Until this was
+// covered, an application - the one author furthest from the schema - was the
+// one the check went quiet for.
+func TestMenuSortOverflowIsDetectedInAContractMenuSpec(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"example/app-order/migration/migration.go": `package migration
+
+import "github.com/go-admin-team/go-admin-core/v2/sdk/contract/seed"
+
+func menus() []seed.MenuSpec {
+	return []seed.MenuSpec{
+		{Code: "dir", Sort: 200},
+		{Code: "ok", Sort: 20},
+	}
+}
+`,
+	})
+
+	f := requireOne(t, check(t, root, options{}), checkMenuSort)
+	if !strings.Contains(f.Message, "200") {
+		t.Errorf("finding should name the offending value, got: %s", f.Message)
+	}
+}
+
+// Every guard against a bad seeded value needs a test that writes the very
+// value it rejects. Scanning _test.go made each of those guards report its
+// own test - the check firing on the proof that it works.
+func TestSeededValueChecksSkipTestFiles(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"cmd/migrate/migration/models/models.go": frozenModelsPkg,
+		"app/admin/service/seed_test.go": `package service
+
+import "go-admin/cmd/migrate/migration/models"
+
+func fixtureMenus() []models.SysMenu {
+	return []models.SysMenu{
+		{MenuId: 9000, Sort: 900},
+	}
+}
+`,
+	})
+
+	if got := only(t, check(t, root, options{}), checkMenuSort); len(got) != 0 {
+		t.Fatalf("%s fired on a test fixture: %v", checkMenuSort, got)
+	}
+}
+
+// The other direction: the exemption must not turn the check off. A real
+// seed - the thing that actually reaches MySQL - is still reported.
+func TestSeededValueChecksStillCoverNonTestFiles(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"cmd/migrate/migration/models/models.go": frozenModelsPkg,
+		"cmd/migrate/migration/version/1786700001000_seed.go": `package version
+
+import "go-admin/cmd/migrate/migration/models"
+
+func seed() []models.SysMenu {
+	return []models.SysMenu{
+		{MenuId: 9000, Sort: 900},
+	}
+}
+`,
+	})
+
+	f := requireOne(t, check(t, root, options{}), checkMenuSort)
+	if !strings.Contains(f.Message, "900") {
+		t.Errorf("finding = %+v", f)
+	}
+}
+
+// The suggested fix has to use the qualifier the file actually writes. Every
+// shim in this repository aliases its import (contractmodels, contractdto),
+// so building the message from path.Base of the import path told the author
+// to write a line that does not compile.
+func TestShimAliasSuggestionUsesTheInSourceQualifier(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"common/models/by.go": "package models\n\nimport contractmodels \"" + coreContractModels +
+			"\"\n\ntype ControlBy contractmodels.ControlBy\n",
+	})
+
+	f := requireOne(t, check(t, root, options{}), checkShimAlias)
+	if !strings.Contains(f.Message, "type ControlBy = contractmodels.ControlBy") {
+		t.Errorf("the fix must name the import as this file spells it; got %s", f.Message)
+	}
+	if strings.Contains(f.Message, "= models.ControlBy") {
+		t.Errorf("the fix names a qualifier this file does not bind; got %s", f.Message)
+	}
+}

tools/checksilent/datascope.go

@@ -0,0 +1,390 @@
+package main
+
+import (
+	"go/ast"
+	"strings"
+)
+
+// ---------------------------------------------------------------------------
+// check 8: a handler that reads the data permission, on a route that never
+// installs the middleware which puts one there
+// ---------------------------------------------------------------------------
+
+// permissionGetter is the function a handler calls to obtain the caller's data
+// scope, and permissionMiddleware is the middleware that puts one in the
+// context. Matched by name rather than by resolved symbol: the tool parses
+// without type checking, and both names are distinctive enough that a
+// same-named function from somewhere else would still be worth a look.
+const (
+	permissionGetter     = "GetPermissionFromContext"
+	permissionMiddleware = "PermissionAction"
+)
+
+// actionsPkgSuffix identifies the package the two names above live in - this
+// repository's common/actions shim and core's sdk/contract/actions both end
+// this way, and a module rename changes neither.
+const actionsPkgSuffix = "/actions"
+
+// handlerKey identifies one handler method uniquely across packages, so that
+// two types named SysUser in different packages are not confused.
+type handlerKey struct {
+	Pkg  string
+	Type string
+	Func string
+}
+
+// checkDataScopeRoutes reports a route whose handler asks for the caller's data
+// permission while the group it is registered on never installs the middleware
+// that supplies one.
+//
+// GetPermissionFromContext cannot fail. When nothing put a *DataPermission in
+// the context it hands back a zero value, whose DataScope is the empty string -
+// and the empty string is not one of the five scopes Permission recognises, so
+// it takes the default branch. That branch fails closed: the query is given
+// `1 = 0` and matches nothing.
+//
+// The result is an endpoint that answers "not found" or "no permission" for
+// rows that plainly exist, and only on deployments that set enabledp: true -
+// with data permissions off, Permission returns the query untouched and the
+// missing middleware costs nothing. That is the shape this check exists for: a
+// default configuration where the mistake is invisible, and a test suite that
+// runs on it.
+//
+// It happened. /api/v1/getinfo read the permission on a group carrying only the
+// JWT middleware, so every login on a deployment with data permissions enabled
+// ended in a 401 from the endpoint the browser calls immediately after signing
+// in - and went back to the login page.
+//
+// Either half is a fix, and which one depends on the route. A handler that
+// reads somebody else's rows wants the middleware. A handler reading the
+// caller's own row - where the id comes from the token - wants no scope at all,
+// because a scope has nothing left to restrict there and DataScopeSelf, which
+// matches on create_by, would reject every user who did not create their own
+// account. The check reports the mismatch and leaves the choice.
+func checkDataScopeRoutes(s *snapshot) []Finding {
+	handlers := permissionReadingHandlers(s)
+	if len(handlers) == 0 {
+		return nil
+	}
+
+	var out []Finding
+	for _, sf := range s.Files {
+		if sf.isTest() {
+			continue
+		}
+		for _, decl := range sf.Syntax.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok || fn.Body == nil {
+				continue
+			}
+			out = append(out, s.routeFindings(sf, fn, handlers)...)
+		}
+	}
+	return out
+}
+
+// permissionReadingHandlers collects every method whose body calls the getter.
+//
+// Test files are included deliberately: a handler is a handler wherever it is
+// declared, and skipping them would let a route registered from a test fixture
+// go unchecked while the fixture is exactly where a new one gets written first.
+func permissionReadingHandlers(s *snapshot) map[handlerKey]bool {
+	out := map[handlerKey]bool{}
+	for _, sf := range s.Files {
+		for _, decl := range sf.Syntax.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok || fn.Body == nil || fn.Recv == nil || len(fn.Recv.List) == 0 {
+				continue
+			}
+			recv := receiverTypeName(fn.Recv.List[0].Type)
+			if recv == "" {
+				continue
+			}
+			if callsPackageFunc(sf, fn.Body, permissionGetter) {
+				out[handlerKey{Pkg: sf.Pkg, Type: recv, Func: fn.Name.Name}] = true
+			}
+		}
+	}
+	return out
+}
+
+// routeFindings walks one function looking for group definitions and the routes
+// registered on them.
+func (s *snapshot) routeFindings(sf *sourceFile, fn *ast.FuncDecl, handlers map[handlerKey]bool) []Finding {
+	// Local variable bindings for the whole function. The first pass below
+	// fills these and the second reads them, so a registration sees every
+	// binding in the function rather than only the ones written above it -
+	// deliberately, because a `.Use` can be written below a route and still be
+	// part of the chain. The cost is that a name reused for two different
+	// things in one function resolves to whichever assignment came last.
+	apiVars := map[string]handlerKey{} // var -> the type it holds
+	guarded := map[string]bool{}       // group var -> middleware installed
+	known := map[string]bool{}         // group var -> is a router group at all
+	prefix := map[string]string{}      // group var -> the path it was declared with
+
+	var out []Finding
+	ast.Inspect(fn.Body, func(n ast.Node) bool {
+		switch stmt := n.(type) {
+		case *ast.AssignStmt:
+			for i, lhs := range stmt.Lhs {
+				id, ok := lhs.(*ast.Ident)
+				if !ok || i >= len(stmt.Rhs) {
+					continue
+				}
+				rhs := stmt.Rhs[i]
+				if key, ok := apiTypeOf(sf, rhs); ok {
+					apiVars[id.Name] = key
+					continue
+				}
+				if parent, isGroup := groupSource(rhs); isGroup {
+					known[id.Name] = true
+					prefix[id.Name] = prefix[parent] + groupPath(rhs)
+					// A subgroup inherits whatever its parent already had:
+					// gin copies the parent's handler chain into the child.
+					guarded[id.Name] = guarded[parent] || containsCallNamed(rhs, permissionMiddleware)
+				}
+			}
+		case *ast.ExprStmt:
+			// A separate `g.Use(...)` after the group was defined.
+			call, ok := stmt.X.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+			if target, ok := receiverIdentOf(call, "Use"); ok && known[target] {
+				if containsCallNamed(call, permissionMiddleware) {
+					guarded[target] = true
+				}
+			}
+		}
+		return true
+	})
+
+	// Second pass for the registrations, so that a `.Use` written below a route
+	// still counts - the middleware chain is assembled before any request is
+	// served, not in source order.
+	ast.Inspect(fn.Body, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		gvar, method, ok := routeRegistration(call)
+		if !ok || !known[gvar] || guarded[gvar] {
+			return true
+		}
+		route, handlerVar, handlerName, ok := routeArgs(call)
+		if !ok {
+			return true
+		}
+		key, ok := apiVars[handlerVar]
+		if !ok {
+			return true
+		}
+		key.Func = handlerName
+		if !handlers[key] {
+			return true
+		}
+		out = append(out, s.finding(Error, checkDataScopeRoute, sf, call,
+			"%s %q is handled by %s.%s, which reads the caller's data permission,\n"+
+				"    but the group it is registered on never installs %s.\n"+
+				"    GetPermissionFromContext then returns the zero value, whose empty DataScope is not a\n"+
+				"    recognised scope, so Permission fails closed and the query matches nothing - on any\n"+
+				"    deployment with enabledp: true. With data permissions off the route works, which is\n"+
+				"    why this does not show up in the default configuration or in CI.\n"+
+				"    Add %s() to the group, or stop scoping a query that is already limited to the caller.",
+			method, prefix[gvar]+route, key.Type, handlerName, permissionMiddleware, permissionMiddleware))
+		return true
+	})
+	return out
+}
+
+// receiverTypeName returns the bare type name of a method receiver, for both
+// `(e SysUser)` and `(e *SysUser)`.
+func receiverTypeName(expr ast.Expr) string {
+	if star, ok := expr.(*ast.StarExpr); ok {
+		expr = star.X
+	}
+	if id, ok := expr.(*ast.Ident); ok {
+		return id.Name
+	}
+	return ""
+}
+
+// callsPackageFunc reports whether body calls name on a package whose import
+// path ends in actionsPkgSuffix.
+func callsPackageFunc(sf *sourceFile, body ast.Node, name string) bool {
+	found := false
+	ast.Inspect(body, func(n ast.Node) bool {
+		if found {
+			return false
+		}
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != name {
+			return true
+		}
+		pkg, ok := sel.X.(*ast.Ident)
+		if !ok {
+			return true
+		}
+		if path, ok := sf.imports[pkg.Name]; ok && strings.HasSuffix(path, actionsPkgSuffix) {
+			found = true
+			return false
+		}
+		return true
+	})
+	return found
+}
+
+// apiTypeOf recognises `apis.SysUser{}` and returns the package path and type.
+func apiTypeOf(sf *sourceFile, expr ast.Expr) (handlerKey, bool) {
+	lit, ok := expr.(*ast.CompositeLit)
+	if !ok {
+		return handlerKey{}, false
+	}
+	sel, ok := lit.Type.(*ast.SelectorExpr)
+	if !ok {
+		return handlerKey{}, false
+	}
+	pkg, ok := sel.X.(*ast.Ident)
+	if !ok {
+		return handlerKey{}, false
+	}
+	path, ok := sf.imports[pkg.Name]
+	if !ok {
+		return handlerKey{}, false
+	}
+	return handlerKey{Pkg: path, Type: sel.Sel.Name}, true
+}
+
+// groupSource reports whether expr builds a router group, and names the
+// variable it was built from when there is one.
+func groupSource(expr ast.Expr) (string, bool) {
+	parent := ""
+	isGroup := false
+	ast.Inspect(expr, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "Group" {
+			return true
+		}
+		isGroup = true
+		if id, ok := sel.X.(*ast.Ident); ok {
+			parent = id.Name
+		}
+		return true
+	})
+	return parent, isGroup
+}
+
+// groupPath returns the literal path a group was declared with, or "" when it
+// is not a literal - a computed prefix is left out of the message rather than
+// printed as something it is not.
+func groupPath(expr ast.Expr) string {
+	out := ""
+	ast.Inspect(expr, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || sel.Sel.Name != "Group" || len(call.Args) == 0 {
+			return true
+		}
+		if lit, ok := call.Args[0].(*ast.BasicLit); ok {
+			out = strings.Trim(lit.Value, `"`)
+		}
+		return true
+	})
+	return out
+}
+
+// containsCallNamed reports whether expr contains a call to a function with
+// this name, at any depth of a method chain or argument list.
+func containsCallNamed(expr ast.Node, name string) bool {
+	found := false
+	ast.Inspect(expr, func(n ast.Node) bool {
+		if found {
+			return false
+		}
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		switch fun := call.Fun.(type) {
+		case *ast.SelectorExpr:
+			if fun.Sel.Name == name {
+				found = true
+				return false
+			}
+		case *ast.Ident:
+			if fun.Name == name {
+				found = true
+				return false
+			}
+		}
+		return true
+	})
+	return found
+}
+
+// receiverIdentOf returns the variable a `x.method(...)` call was made on.
+func receiverIdentOf(call *ast.CallExpr, method string) (string, bool) {
+	sel, ok := call.Fun.(*ast.SelectorExpr)
+	if !ok || sel.Sel.Name != method {
+		return "", false
+	}
+	id, ok := sel.X.(*ast.Ident)
+	if !ok {
+		return "", false
+	}
+	return id.Name, true
+}
+
+// httpMethods are the registration calls this check understands. Any and Match
+// are absent on purpose: they take the method as data, and a check that half
+// understands a registration is worse than one that says nothing about it.
+var httpMethods = map[string]bool{
+	"GET": true, "POST": true, "PUT": true, "DELETE": true, "PATCH": true, "HEAD": true, "OPTIONS": true,
+}
+
+// routeRegistration recognises `g.GET(...)` and names the group and method.
+func routeRegistration(call *ast.CallExpr) (string, string, bool) {
+	sel, ok := call.Fun.(*ast.SelectorExpr)
+	if !ok || !httpMethods[sel.Sel.Name] {
+		return "", "", false
+	}
+	id, ok := sel.X.(*ast.Ident)
+	if !ok {
+		return "", "", false
+	}
+	return id.Name, sel.Sel.Name, true
+}
+
+// routeArgs pulls the path and the `api.Handler` argument out of a
+// registration, ignoring any middleware written between them.
+func routeArgs(call *ast.CallExpr) (route, handlerVar, handlerName string, ok bool) {
+	if len(call.Args) < 2 {
+		return "", "", "", false
+	}
+	lit, isLit := call.Args[0].(*ast.BasicLit)
+	if !isLit {
+		return "", "", "", false
+	}
+	route = strings.Trim(lit.Value, `"`)
+	// The handler is the last argument; anything before it is middleware.
+	sel, isSel := call.Args[len(call.Args)-1].(*ast.SelectorExpr)
+	if !isSel {
+		return "", "", "", false
+	}
+	id, isIdent := sel.X.(*ast.Ident)
+	if !isIdent {
+		return "", "", "", false
+	}
+	return route, id.Name, sel.Sel.Name, true
+}

tools/checksilent/datascope_test.go

@@ -0,0 +1,163 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+// apisFile is a handler package with two methods: one that reads the caller's
+// data permission and one that does not.
+const apisFile = `package apis
+
+import (
+	"github.com/gin-gonic/gin"
+	"go-admin/common/actions"
+)
+
+type SysUser struct{}
+
+func (e SysUser) Scoped(c *gin.Context) {
+	p := actions.GetPermissionFromContext(c)
+	_ = p
+}
+
+func (e SysUser) Unscoped(c *gin.Context) {}
+`
+
+func routerFile(uses string) string {
+	return `package router
+
+import (
+	"github.com/gin-gonic/gin"
+	"go-admin/app/admin/apis"
+	"go-admin/common/actions"
+)
+
+var _ = actions.PermissionAction
+
+func register(v1 *gin.RouterGroup) {
+	api := apis.SysUser{}
+	r := v1.Group("/sys-user")` + uses + `
+	{
+		r.GET("/:id", api.Scoped)
+	}
+}
+`
+}
+
+// The mistake itself: a handler that reads the permission, on a group that
+// never installs the middleware which puts one there.
+func TestDataScopeRouteWithoutTheMiddlewareIsReported(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/admin/apis/sys_user.go":   apisFile,
+		"app/admin/router/sys_user.go": routerFile(`.Use(gin.Logger())`),
+	})
+	f := requireOne(t, check(t, root, options{}), checkDataScopeRoute)
+	for _, want := range []string{`GET "/sys-user/:id"`, "SysUser.Scoped", "PermissionAction"} {
+		if !strings.Contains(f.Message, want) {
+			t.Errorf("message does not mention %q:\n%s", want, f.Message)
+		}
+	}
+}
+
+// The middleware installed in the chain is the fix, and must silence it.
+func TestDataScopeRouteWithTheMiddlewareIsQuiet(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/admin/apis/sys_user.go":   apisFile,
+		"app/admin/router/sys_user.go": routerFile(`.Use(gin.Logger()).Use(actions.PermissionAction())`),
+	})
+	if got := only(t, check(t, root, options{}), checkDataScopeRoute); len(got) != 0 {
+		t.Errorf("reported %d findings for a guarded group:\n%v", len(got), got)
+	}
+}
+
+// The other fix - the handler stops reading the permission - must silence it
+// too. Reporting a route whose handler needs no scope would push people to
+// install middleware they do not want, which is how /getinfo would have been
+// "fixed" into rejecting every user who did not create their own account.
+func TestARouteWhoseHandlerReadsNoPermissionIsQuiet(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/admin/apis/sys_user.go": apisFile,
+		"app/admin/router/sys_user.go": `package router
+
+import (
+	"github.com/gin-gonic/gin"
+	"go-admin/app/admin/apis"
+)
+
+func register(v1 *gin.RouterGroup) {
+	api := apis.SysUser{}
+	r := v1.Group("")
+	{
+		r.GET("/getinfo", api.Unscoped)
+	}
+}
+`,
+	})
+	if got := only(t, check(t, root, options{}), checkDataScopeRoute); len(got) != 0 {
+		t.Errorf("reported %d findings for a handler that reads no permission:\n%v", len(got), got)
+	}
+}
+
+// gin copies the parent's handler chain into a subgroup, so a group carved out
+// of a guarded one is guarded. Reporting it would be a false positive, and a
+// check that cries wolf is one people switch off.
+func TestASubgroupInheritsTheMiddleware(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/admin/apis/sys_user.go": apisFile,
+		"app/admin/router/sys_user.go": `package router
+
+import (
+	"github.com/gin-gonic/gin"
+	"go-admin/app/admin/apis"
+	"go-admin/common/actions"
+)
+
+func register(v1 *gin.RouterGroup) {
+	api := apis.SysUser{}
+	parent := v1.Group("/sys").Use(actions.PermissionAction())
+	child := parent.Group("/user")
+	{
+		child.GET("/:id", api.Scoped)
+	}
+}
+`,
+	})
+	if got := only(t, check(t, root, options{}), checkDataScopeRoute); len(got) != 0 {
+		t.Errorf("reported %d findings for a subgroup of a guarded group:\n%v", len(got), got)
+	}
+}
+
+// Two packages can both declare a SysUser. Only the one whose method reads the
+// permission may be reported, or the check becomes a name search.
+func TestAHandlerIsMatchedByPackageNotJustName(t *testing.T) {
+	root := fixture(t, map[string]string{
+		"app/admin/apis/sys_user.go": apisFile,
+		"app/other/apis/sys_user.go": `package apis
+
+import "github.com/gin-gonic/gin"
+
+type SysUser struct{}
+
+func (e SysUser) Scoped(c *gin.Context) {}
+`,
+		"app/other/router/sys_user.go": `package router
+
+import (
+	"github.com/gin-gonic/gin"
+	"go-admin/app/other/apis"
+)
+
+func register(v1 *gin.RouterGroup) {
+	api := apis.SysUser{}
+	r := v1.Group("/other")
+	{
+		r.GET("/:id", api.Scoped)
+	}
+}
+`,
+	})
+	if got := only(t, check(t, root, options{}), checkDataScopeRoute); len(got) != 0 {
+		t.Errorf("reported %d findings for a same-named handler in another package:\n%v", len(got), got)
+	}
+}

tools/checksilent/main.go

@@ -1,9 +1,9 @@
 // Command checksilent reports the failures in this repository that do not
 // announce themselves: no error, no log line, behaviour quietly wrong.
 //
-// Six checks, five of them ERROR and one WARN. An ERROR fails the run; a WARN
+// Seven checks, six of them ERROR and one WARN. An ERROR fails the run; a WARN
 // prints and does not. The split is not about how bad the consequence is - all
-// six are bad - but about how certain the detection is. Everything reported as
+// seven are bad - but about how certain the detection is. Everything reported as
 // an ERROR is decided from this repository's own syntax. The one WARN compares
 // against a second repository through a regular expression, and a check that
 // can be wrong must not be able to stop a build, or the first response to it
@@ -102,4 +102,16 @@ func printSummary(w io.Writer, findings []Finding, opt options, s *snapshot) {
 		fmt.Fprintf(w, "The %s check covered %s; %s does not exist here and was not scanned.\n",
 			checkImportBoundary, strings.Join(scanned, ", "), strings.Join(absent, ", "))
 	}
+	// Same reason: a tree with no alias into core's contract packages gives
+	// this check nothing to look at, and its silence must not be read as a
+	// pass. That is now the interesting case rather than the expected one -
+	// the shims exist, so a count of zero means they stopped being aliases,
+	// or stopped being here.
+	if n := ScannedShimAliases(s); n == 0 {
+		fmt.Fprintf(w, "The %s check found no type alias into core's contract packages and guarded nothing.\n",
+			checkShimAlias)
+	} else {
+		fmt.Fprintf(w, "The %s check covered %d type alias(es) into core's contract packages.\n",
+			checkShimAlias, n)
+	}
 }

tools/checksilent/snapshot.go

@@ -38,6 +38,19 @@ type sourceFile struct {
 	consts  map[string]int64  // package-level integer constants, filled per package
 }
 
+// isTest reports whether this file is a _test.go.
+//
+// The checks about a seeded value - a menu sort, a config value, a menu id, a
+// soft-delete shape - are all about what reaches a real database through a
+// migration, and a test fixture reaches none. Worse, each of those guards
+// needs a test that writes the very value it rejects, so scanning test files
+// makes every such guard report its own test. The import and alias checks do
+// not skip tests: those are about the dependency graph, where a test file's
+// import is as real as any other.
+func (f *sourceFile) isTest() bool {
+	return strings.HasSuffix(f.Path, "_test.go")
+}
+
 // snapshot is every Go file under the root, parsed once and shared by all the
 // checks.
 type snapshot struct {