test✅: fail on an Append error this test does not model

Only ErrQueueClosed was examined and every other error was discarded, so a
run where nothing reached a queue at all would leave the refusal count at
zero and the test green. The first unexpected error is now kept and fails
the test.

The pool is sized so a full queue cannot be one of them: it returns an error
of its own and is expected while the consumer is held, which would otherwise
make the new check fire on the normal path.

.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

@@ -1,6 +1,7 @@
 package apis
 
 import (
+	"errors"
 	"github.com/gin-gonic/gin/binding"
 	"go-admin/app/admin/models"
 	"golang.org/x/crypto/bcrypt"
@@ -15,6 +16,7 @@ import (
 	"go-admin/app/admin/service"
 	"go-admin/app/admin/service/dto"
 	"go-admin/common/actions"
+	"go-admin/common/middleware"
 )
 
 type SysUser struct {
@@ -149,12 +151,34 @@ func (e SysUser) Update(c *gin.Context) {
 		return
 	}
 
-	req.SetUpdateBy(user.GetUserId(c))
+	callerId := user.GetUserId(c)
+
+	// This route is in CasbinExclude so the personal-center screen can edit
+	// the caller's own record without a policy grant (see settings.go). That
+	// exclusion covers the whole route, not just the caller's own record, and
+	// the request carries the target userId in the body - so without this
+	// check here, any authenticated caller could edit any other user, up to
+	// and including their roleId. When the target is someone else, ask Casbin
+	// directly for the permission AuthCheckRole skipped.
+	if req.UserId != callerId {
+		allowed, err := middleware.EnforceRoleFor(c, c.Request.URL.Path, c.Request.Method)
+		if err != nil {
+			e.Logger.Error(err)
+			e.Error(500, err, err.Error())
+			return
+		}
+		if !allowed {
+			e.Error(http.StatusForbidden, errors.New("无权更新其他用户数据"), "对不起，您没有该接口访问权限，请联系管理员")
+			return
+		}
+	}
+
+	req.SetUpdateBy(callerId)
 
 	//数据权限检查
 	p := actions.GetPermissionFromContext(c)
 
-	err = s.Update(&req, p)
+	err = s.Update(&req, p, callerId)
 	if err != nil {
 		e.Logger.Error(err)
 		return
@@ -420,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)
@@ -440,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/apis/sys_user_privesc_test.go

@@ -0,0 +1,175 @@
+package apis
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	mycasbin "github.com/go-admin-team/go-admin-core/v2/casbin"
+	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
+	"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/pkg"
+	"gorm.io/gorm"
+
+	"go-admin/app/admin/models"
+)
+
+// PUT /api/v1/sys-user is in settings.go's CasbinExclude so the
+// personal-center screen (go-admin-ui's userInfo.vue) can edit the caller's
+// own record without holding a policy grant on this route. AuthCheckRole
+// skips Enforce entirely for an excluded route, so this file's job is to pin
+// what the handler itself now has to hold shut: the target userId comes from
+// the request body, and nothing upstream of the handler ever checked it
+// against the caller.
+
+// setupPrivescDB wires an in-memory database and a Casbin enforcer with an
+// empty policy - the state of a fresh install for any role but admin - under
+// a tenant unique to the calling test, so mycasbin's process-wide enforcer
+// cache can't hand one test's database to another.
+func setupPrivescDB(t *testing.T) (*gorm.DB, string) {
+	t.Helper()
+
+	// Fatalf, not Skipf: this database is in-memory sqlite with no external
+	// dependency, so failing to open or migrate it means the environment is
+	// actually broken. Skipping here would let these two anti-privesc
+	// regression tests silently stop running while CI stays green - a
+	// standing assertion that never fires is worse than no assertion.
+	db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("sqlite unavailable: %v", err)
+	}
+	if err := db.AutoMigrate(&models.SysUser{}); err != nil {
+		t.Fatalf("automigrate: %v", err)
+	}
+
+	tenant := "sys-user-privesc-" + t.Name()
+
+	previousInterval := mycasbin.ReloadInterval
+	mycasbin.ReloadInterval = 0 // opt out of the background reload goroutine; the test never writes a policy
+	t.Cleanup(func() { mycasbin.ReloadInterval = previousInterval })
+
+	e := mycasbin.Setup(db, tenant)
+	previousEnforcer := sdk.Runtime.GetCasbinByTenant(tenant)
+	sdk.Runtime.SetCasbinByTenant(tenant, e)
+	t.Cleanup(func() { sdk.Runtime.SetCasbinByTenant(tenant, previousEnforcer) })
+
+	return db, tenant
+}
+
+// callUpdate drives SysUser.Update the way the router does for an
+// authenticated, non-admin caller: JWT claims already decoded into the
+// context (that is jwtauth's job, not this handler's) and a database - but
+// without AuthCheckRole, since that middleware never runs Enforce for this
+// route at all.
+func callUpdate(t *testing.T, db *gorm.DB, tenant string, callerId int, body map[string]interface{}) *httptest.ResponseRecorder {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	raw, err := json.Marshal(body)
+	if err != nil {
+		t.Fatalf("marshal request body: %v", err)
+	}
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPut, "/api/v1/sys-user", bytes.NewReader(raw))
+	c.Request.Host = tenant
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	c.Set("db", db)
+	c.Set(pkg.LoggerKey, logger.NewHelper(logger.DefaultLogger))
+	c.Set(jwt.JwtPayloadKey, jwt.MapClaims{
+		"identity": float64(callerId),
+		"rolekey":  "ordinary-role", // holds no Casbin policy anywhere in this test
+	})
+
+	SysUser{}.Update(c)
+	return w
+}
+
+// TestUpdate_CannotEscalatePrivilegeThroughAnotherUsersRecord is the
+// regression for H6. Before the fix, an ordinary authenticated user could PUT
+// a body naming another user's id and change that user's roleId - the route
+// being Casbin-excluded meant no permission check ever ran, and the data
+// permission scope that would otherwise gate this is off by default.
+func TestUpdate_CannotEscalatePrivilegeThroughAnotherUsersRecord(t *testing.T) {
+	db, tenant := setupPrivescDB(t)
+
+	victim := models.SysUser{Username: "bob", NickName: "Bob", RoleId: 2, DeptId: 1, Status: "1"}
+	if err := db.Create(&victim).Error; err != nil {
+		t.Fatal(err)
+	}
+	attacker := models.SysUser{Username: "alice", NickName: "Alice", RoleId: 2, DeptId: 1, Status: "1"}
+	if err := db.Create(&attacker).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	const elevatedRoleId = 1 // a role the attacker does not hold and has no policy for
+
+	callUpdate(t, db, tenant, attacker.UserId, map[string]interface{}{
+		"userId":   victim.UserId,
+		"username": victim.Username,
+		"nickName": "pwned",
+		"phone":    "13800000000",
+		"email":    "bob@example.com",
+		"roleId":   elevatedRoleId,
+		"deptId":   victim.DeptId,
+		"status":   victim.Status,
+	})
+
+	var after models.SysUser
+	if err := db.First(&after, victim.UserId).Error; err != nil {
+		t.Fatal(err)
+	}
+	if after.RoleId == elevatedRoleId {
+		t.Fatalf("an attacker with no Casbin permission on this route escalated the victim's roleId to %d", after.RoleId)
+	}
+	if after.NickName == "pwned" {
+		t.Fatalf("an attacker with no Casbin permission on this route modified another user's record: %+v", after)
+	}
+}
+
+// TestUpdate_SelfEditCannotChangePrivilegedFields covers the case the
+// CasbinExclude entry exists for: the personal-center screen has to keep
+// working for the caller's own record. The fields that screen exposes
+// (nickName/phone/email/sex) must still save, while roleId/deptId/status stay
+// whatever the database already had even if the request carries something
+// else - a compromised or hand-crafted client is the only way that request
+// would ever differ from what the honest form sends.
+func TestUpdate_SelfEditCannotChangePrivilegedFields(t *testing.T) {
+	db, tenant := setupPrivescDB(t)
+
+	self := models.SysUser{Username: "carol", NickName: "Carol", RoleId: 2, DeptId: 1, Status: "1"}
+	if err := db.Create(&self).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	const elevatedRoleId = 1
+
+	callUpdate(t, db, tenant, self.UserId, map[string]interface{}{
+		"userId":   self.UserId,
+		"username": self.Username,
+		"nickName": "Carol Updated",
+		"phone":    "13900000000",
+		"email":    "carol@example.com",
+		"roleId":   elevatedRoleId, // tampered; must not take effect
+		"deptId":   self.DeptId,
+		"status":   self.Status,
+	})
+
+	var after models.SysUser
+	if err := db.First(&after, self.UserId).Error; err != nil {
+		t.Fatal(err)
+	}
+	if after.RoleId == elevatedRoleId {
+		t.Fatalf("a self-edit changed the caller's own roleId to %d", after.RoleId)
+	}
+	if after.NickName != "Carol Updated" {
+		t.Fatalf("the legitimate personal-center edit did not go through: %+v", after)
+	}
+}

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/init_router.go

@@ -25,11 +25,9 @@ func InitRouter() {
 		os.Exit(-1)
 	}
 
-	// the jwt middleware
-	authMiddleware, err := common.AuthInit()
-	if err != nil {
-		log.Fatalf("JWT Init Error, %s", err.Error())
-	}
+	// the jwt middleware: shared instance InitMiddleware built at startup,
+	// not one built here per module (see common/middleware.GetAuthMiddleware).
+	authMiddleware := common.GetAuthMiddleware()
 
 	// 注册系统路由
 	InitSysRouter(r, authMiddleware)

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
@@ -84,7 +108,16 @@ func (e *SysUser) Insert(c *dto.SysUserInsertReq) error {
 }
 
 // Update 修改SysUser对象
-func (e *SysUser) Update(c *dto.SysUserUpdateReq, p *actions.DataPermission) error {
+//
+// callerId is who is asking, not who SetUpdateBy recorded - that field only
+// says who to blame, it never constrained who could be edited. When the
+// target is the caller themselves, roleId/deptId/status are kept at whatever
+// the database already has no matter what the request body carries: this is
+// the personal-center screen's route (see CasbinExclude in settings.go, and
+// the check in the API handler ahead of this call), and letting a caller
+// grant themselves a different role or department through it would be a
+// privilege escalation the exclusion was never meant to open.
+func (e *SysUser) Update(c *dto.SysUserUpdateReq, p *actions.DataPermission, callerId int) error {
 	var err error
 	var model models.SysUser
 	db := e.Orm.Scopes(
@@ -98,6 +131,11 @@ func (e *SysUser) Update(c *dto.SysUserUpdateReq, p *actions.DataPermission) err
 		return errors.New("无权更新该数据")
 
 	}
+	if model.UserId == callerId {
+		c.RoleId = model.RoleId
+		c.DeptId = model.DeptId
+		c.Status = model.Status
+	}
 	c.Generate(&model)
 	update := e.Orm.Model(&model).Where("user_id = ?", &model.UserId).Omit("password", "salt").Updates(&model)
 	if err = update.Error; err != nil {

app/demo/router/router.go

@@ -33,11 +33,9 @@ func InitRouter() {
 		os.Exit(-1)
 	}
 
-	// the jwt middleware
-	authMiddleware, err := common.AuthInit()
-	if err != nil {
-		log.Fatalf("JWT Init Error, %s", err.Error())
-	}
+	// the jwt middleware: shared instance InitMiddleware built at startup,
+	// not one built here per module (see common/middleware.GetAuthMiddleware).
+	authMiddleware := common.GetAuthMiddleware()
 
 	// 注册业务路由
 	InitBusinessRouter(r, authMiddleware)

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)
+	}
+}

app/jobs/router/init_router.go

@@ -26,10 +26,9 @@ func InitRouter() {
 		os.Exit(-1)
 	}
 
-	authMiddleware, err := common.AuthInit()
-	if err != nil {
-		log.Fatalf("JWT Init Error, %s", err.Error())
-	}
+	// the jwt middleware: shared instance InitMiddleware built at startup,
+	// not one built here per module (see common/middleware.GetAuthMiddleware).
+	authMiddleware := common.GetAuthMiddleware()
 
 	// 注册业务路由
 	initRouter(r, authMiddleware)

app/other/router/init_router.go

@@ -25,10 +25,9 @@ func InitRouter() {
 		os.Exit(-1)
 	}
 	// the jwt middleware
-	authMiddleware, err := common.AuthInit()
-	if err != nil {
-		log.Fatalf("JWT Init Error, %s", err.Error())
-	}
+	// the jwt middleware: shared instance InitMiddleware built at startup,
+	// not one built here per module (see common/middleware.GetAuthMiddleware).
+	authMiddleware := common.GetAuthMiddleware()
 
 	// 注册业务路由
 	// TODO: 这里可存放业务路由，里边并无实际路由只有演示代码

app/other/router/monitor.go

@@ -1,23 +1,63 @@
 package router
 
 import (
+	"context"
 	"net/http"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"github.com/go-admin-team/go-admin-core/v2/tools/transfer"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
+
+	"go-admin/common/health"
 )
 
 func init() {
 	routerNoCheckRole = append(routerNoCheckRole, registerMonitorRouter)
 }
 
-// 需认证的路由代码
+// readyTimeout bounds the whole probe. It has to stay under whatever period
+// the orchestrator polls on, or a slow dependency turns a readiness check into
+// a queue of readiness checks.
+const readyTimeout = 2 * time.Second
+
+// 无需认证的路由代码
 func registerMonitorRouter(v1 *gin.RouterGroup) {
 	v1.GET("/metrics", transfer.Handler(promhttp.Handler()))
-	//健康检查
+
+	// 健康检查（存活）
+	//
+	// Stays a bare 200 on purpose. This is the answer to "should I restart
+	// you", and a process whose database is unreachable does not want
+	// restarting - that turns one outage into a crash loop and throws away the
+	// connection pool, the cache and every in-flight request along the way.
 	v1.GET("/health", func(c *gin.Context) {
 		c.Status(http.StatusOK)
 	})
 
-}
+	// 就绪检查
+	//
+	// The answer to "should I send you requests". It fails while a dependency
+	// is unreachable, and from the moment shutdown begins - which is before
+	// the server stops accepting, so a load balancer can take this instance
+	// out of the pool while it can still finish what it has.
+	v1.GET("/ready", func(c *gin.Context) {
+		if health.Draining() {
+			c.JSON(http.StatusServiceUnavailable, gin.H{
+				"status": "draining",
+				"checks": []health.Check{},
+			})
+			return
+		}
+		ctx, cancel := context.WithTimeout(c.Request.Context(), readyTimeout)
+		defer cancel()
+
+		checks := health.Ready(ctx)
+		status := http.StatusOK
+		if !health.Healthy(checks) {
+			status = http.StatusServiceUnavailable
+		}
+		c.JSON(status, gin.H{"status": http.StatusText(status), "checks": checks})
+	})
+
+}

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"
 
@@ -23,6 +30,7 @@ import (
 	"go-admin/app/jobs"
 	"go-admin/common/database"
 	"go-admin/common/global"
+	"go-admin/common/health"
 	common "go-admin/common/middleware"
 	"go-admin/common/middleware/handler"
 	"go-admin/common/storage"
@@ -59,44 +67,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 +187,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 +207,172 @@ 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()
+	// Readiness fails from here, which is before the server stops accepting.
+	// The order is the whole point: a load balancer that is told "not ready"
+	// while this instance can still finish what it has in flight takes it out
+	// of the pool without dropping anything. Reversed, the connections are cut
+	// first and the health check reports it afterwards.
+	health.BeginDraining()
 
-	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/actions/crud_shim_test.go

@@ -0,0 +1,135 @@
+package actions_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+
+	"go-admin/common/actions"
+	"go-admin/common/dto"
+	"go-admin/common/models"
+)
+
+// capturingLogger records every SQL statement GORM actually executes, so a
+// test can inspect it the way inspecting a *gorm.DB's own Statement cannot:
+// IndexAction builds and executes its query in one unbroken chain
+// (db.Model(...).Scopes(...).Find(...)...Count(...)) and never hands the
+// built statement back to its caller.
+type capturingLogger struct {
+	gormlogger.Interface
+	mu    sync.Mutex
+	stmts []string
+}
+
+func (l *capturingLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error) {
+	sql, _ := fc()
+	l.mu.Lock()
+	l.stmts = append(l.stmts, sql)
+	l.mu.Unlock()
+}
+
+func (l *capturingLogger) all() string {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return strings.Join(l.stmts, "\n")
+}
+
+// probeRow is a minimal model satisfying models.ActiveRecord through the
+// same embeds a real app/admin model uses, so IndexAction sees exactly the
+// shape it is written against.
+type probeRow struct {
+	models.Model
+	models.ControlBy
+	Name string
+}
+
+func (probeRow) TableName() string                { return "action_probe_row" }
+func (e *probeRow) Generate() models.ActiveRecord { o := *e; return &o }
+func (e *probeRow) GetId() interface{}            { return e.Id }
+
+// probeIndexReq is a minimal dto.Index: no search tags, page defaults.
+type probeIndexReq struct {
+	dto.Pagination `search:"-"`
+}
+
+// Generate returns a copy, the way every dto.Index in this repository does:
+// IndexAction closes over one instance and serves every request to the route
+// from it, so returning the receiver would share one struct across them. The
+// probe has to model that faithfully or it is not the shape IndexAction is
+// written against.
+func (p *probeIndexReq) Generate() dto.Index        { o := *p; return &o }
+func (p *probeIndexReq) Bind(*gin.Context) error    { return nil }
+func (p *probeIndexReq) GetNeedSearch() interface{} { return *p }
+
+type pageEnvelope struct {
+	Code int32 `json:"code"`
+}
+
+// TestIndexActionAppliesDataPermission is an end-to-end guard core's own
+// test suite cannot provide. The five generic CRUD actions in this package
+// (create/delete/index/update/view.go) were not lowered to core (PRD 006
+// F3) - they still call actions.Permission directly, in this repository, on
+// a code path core knows nothing about. core's tests pin down what
+// Permission does for a given scope; nothing pinned down whether this
+// package's own Actions still remember to call it at all. This runs
+// IndexAction exactly as a real request would, against a real in-memory
+// database, and inspects the SQL GORM actually executed - not just that
+// the handler returned success, which it would just as happily do with no
+// filter applied at all.
+func TestProbeIndexReqGenerateReturnsAFreshInstance(t *testing.T) {
+	p := &probeIndexReq{}
+	got := p.Generate()
+	if got == dto.Index(p) {
+		t.Fatal("Generate returned the receiver; IndexAction would share one instance across every request to the route")
+	}
+}
+
+func TestIndexActionAppliesDataPermission(t *testing.T) {
+	previous := config.ApplicationConfig.EnableDP
+	config.ApplicationConfig.EnableDP = true
+	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
+
+	cl := &capturingLogger{Interface: gormlogger.Default.LogMode(gormlogger.Silent)}
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{Logger: cl})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(&probeRow{}); err != nil {
+		t.Fatalf("AutoMigrate: %v", err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+	c.Set("db", db)
+	c.Set(actions.PermissionKey, &actions.DataPermission{DataScope: actions.DataScopeSelf, UserId: 7})
+
+	actions.IndexAction(&probeRow{}, &probeIndexReq{}, func() interface{} { return &[]probeRow{} })(c)
+
+	var body pageEnvelope
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decoding response body %q: %v", w.Body.String(), err)
+	}
+	if body.Code != http.StatusOK {
+		t.Fatalf("response code = %d, want %d; body=%s", body.Code, http.StatusOK, w.Body.String())
+	}
+
+	sql := cl.all()
+	const wantFragment = "action_probe_row.create_by = "
+	if !strings.Contains(sql, wantFragment) {
+		t.Fatalf("IndexAction did not apply the data-permission scope to its query; want SQL containing %q, got:\n%s", wantFragment, sql)
+	}
+}

common/actions/permission.go

@@ -1,201 +1,48 @@
 package actions
 
 import (
-	"errors"
-
 	"github.com/gin-gonic/gin"
-	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
-	log "github.com/go-admin-team/go-admin-core/v2/logger"
-	"github.com/go-admin-team/go-admin-core/v2/response"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/pkg"
 	"gorm.io/gorm"
+
+	contractactions "github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
 )
 
-type DataPermission struct {
-	DataScope string
-	UserId    int
-	DeptId    int
-	RoleId    int
-}
+// DataPermission is a thin alias of go-admin-core's sdk/contract/actions
+// (PRD 006 F3/F5).
+type DataPermission = contractactions.DataPermission
 
-func PermissionAction() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		// Permission() below returns the query untouched when data permission
-		// is off, so the lookup that feeds it has nothing to feed. It used to
-		// run anyway: a sys_user join on every list, detail, update and delete,
-		// with the result discarded.
-		if !config.ApplicationConfig.EnableDP {
-			c.Set(PermissionKey, new(DataPermission))
-			c.Next()
-			return
-		}
-
-		userId := user.GetUserIdStr(c)
-		if userId == "" {
-			c.Set(PermissionKey, new(DataPermission))
-			c.Next()
-			return
-		}
-
-		// The token already carries what the scope is decided by. Reading it
-		// there costs nothing, and goes no more stale than rolekey does - which
-		// Casbin has always read from the token.
-		if p, ok := permissionFromClaims(c); ok {
-			c.Set(PermissionKey, p)
-			c.Next()
-			return
-		}
-
-		db, err := pkg.GetOrm(c)
-		if err != nil {
-			log.Error(err)
-			// Same fix as the newDataPermission branch below: without Abort,
-			// gin's "return means continue" semantics send the request on to
-			// the business handler with PermissionKey never set. The caller
-			// then reads a zero-value DataPermission, which used to fall
-			// into Permission()'s fail-open default - a database hiccup
-			// silently turning into "see everything". PRD 006 F14/H1.
-			response.Error(c, 500, err, "权限范围鉴定错误")
-			c.Abort()
-			return
-		}
-		msgID := pkg.GenerateMsgIDFromContext(c)
-		p, err := newDataPermission(db, userId)
-		if err != nil {
-			log.Errorf("MsgID[%s] PermissionAction error: %s", msgID, err)
-			response.Error(c, 500, err, "权限范围鉴定错误")
-			c.Abort()
-			return
-		}
-		c.Set(PermissionKey, p)
-		c.Next()
-	}
-}
-
-// permissionFromClaims builds the scope from the token, reporting false when
-// the token predates deptid being carried. Such a token still exists until it
-// expires, and it has to keep working.
-func permissionFromClaims(c *gin.Context) (*DataPermission, bool) {
-	claims := user.ExtractClaims(c)
-	if claims["deptid"] == nil || claims["datascope"] == nil {
-		return nil, false
-	}
-	scope, ok := claims["datascope"].(string)
-	if !ok {
-		return nil, false
-	}
-	return &DataPermission{
-		DataScope: scope,
-		UserId:    user.GetUserId(c),
-		DeptId:    user.GetDeptId(c),
-		RoleId:    user.GetRoleId(c),
-	}, true
-}
-
-func newDataPermission(tx *gorm.DB, userId interface{}) (*DataPermission, error) {
-	var err error
-	p := &DataPermission{}
-
-	err = tx.Table("sys_user").
-		Select("sys_user.user_id", "sys_role.role_id", "sys_user.dept_id", "sys_role.data_scope").
-		Joins("left join sys_role on sys_role.role_id = sys_user.role_id").
-		Where("sys_user.user_id = ?", userId).
-		Scan(p).Error
-	if err != nil {
-		err = errors.New("获取用户数据出错 msg:" + err.Error())
-		return nil, err
-	}
-	return p, nil
-}
-
-// The five values sys_role.data_scope can hold. Front end's role editor
-// calls them by the same names (go-admin-ui's sys-role/index.vue): "1" is
-// 全部数据权限, "2" 自定义数据权限, "3" 本部门数据权限, "4" 本部门及以下数据权限,
-// "5" 仅本人数据权限.
-//
-// DataScopeAll has to be a named, explicit case in Permission below rather
-// than falling into default: it is a real, intentional configuration, not an
-// absence of one, and default's job after PRD 006 F14/H2 is to catch values
-// that are neither. Folding the two together is what made an unset or
-// corrupted data_scope indistinguishable from "show everything" in the first
-// place.
+// The five values sys_role.data_scope can hold, referenced directly from
+// go-admin-core's sdk/contract/actions rather than restated as literals -
+// see that package's DataScope* doc comment and PRD 006's hard constraint 4.
 const (
-	DataScopeAll      = "1"
-	DataScopeCustom   = "2"
-	DataScopeDept     = "3"
-	DataScopeDeptTree = "4"
-	DataScopeSelf     = "5"
+	DataScopeAll      = contractactions.DataScopeAll
+	DataScopeCustom   = contractactions.DataScopeCustom
+	DataScopeDept     = contractactions.DataScopeDept
+	DataScopeDeptTree = contractactions.DataScopeDeptTree
+	DataScopeSelf     = contractactions.DataScopeSelf
 )
 
-// IsValidDataScope reports whether s is one of the five values Permission
-// recognizes. Anything else lands in Permission's fail-closed default, so
-// code that persists data_scope (sys_role writes) should reject it before it
-// reaches the database rather than let a typo or an empty string surface
-// there silently.
-func IsValidDataScope(s string) bool {
-	switch s {
-	case DataScopeAll, DataScopeCustom, DataScopeDept, DataScopeDeptTree, DataScopeSelf:
-		return true
-	default:
-		return false
-	}
+// PermissionAction, Permission, GetPermissionFromContext and
+// IsValidDataScope forward to go-admin-core's sdk/contract/actions (PRD 006
+// F3/F5). create.go/delete.go/index.go/update.go/view.go in this package
+// (the generic CRUD actions, which do not move to core) call Permission and
+// GetPermissionFromContext by these same names and are unchanged by the
+// move: the names now resolve to forwards instead of local definitions, and
+// the behaviour is identical either way.
+func PermissionAction() gin.HandlerFunc {
+	return contractactions.PermissionAction()
 }
 
 func Permission(tableName string, p *DataPermission) func(db *gorm.DB) *gorm.DB {
-	return func(db *gorm.DB) *gorm.DB {
-		if !config.ApplicationConfig.EnableDP {
-			return db
-		}
-		switch p.DataScope {
-		case DataScopeAll:
-			return db
-		case DataScopeCustom:
-			return db.Where(tableName+".create_by in (select sys_user.user_id from sys_role_dept left join sys_user on sys_user.dept_id=sys_role_dept.dept_id where sys_role_dept.role_id = ?)", p.RoleId)
-		case DataScopeDept:
-			if p.DeptId <= 0 {
-				// A department id of 0 identifies no real department (see
-				// sys_dept.go: dept_path always starts with "/0/", the
-				// reserved root). Matching it literally would mean "every
-				// user whose dept_id happens to be unset", not "no one" -
-				// fail closed instead. PRD 006 F14/H3.
-				return db.Where("1 = 0")
-			}
-			return db.Where(tableName+".create_by in (SELECT user_id from sys_user where dept_id = ? )", p.DeptId)
-		case DataScopeDeptTree:
-			if p.DeptId <= 0 {
-				// dept_path is built as "/0/" + id + "/..." for every
-				// department (sys_dept.go), so a DeptId of 0 turns the LIKE
-				// pattern below into '%/0/%', which matches every row in
-				// sys_dept - full visibility instead of none. PRD 006
-				// F14/H3.
-				return db.Where("1 = 0")
-			}
-			return db.Where(tableName+".create_by in (SELECT user_id from sys_user where sys_user.dept_id in(select dept_id from sys_dept where dept_path like ? ))", "%/"+pkg.IntToString(p.DeptId)+"/%")
-		case DataScopeSelf:
-			return db.Where(tableName+".create_by = ?", p.UserId)
-		default:
-			// Unrecognized scope: never configured, corrupted data, or a
-			// value a future version adds and this one does not know yet.
-			// Fail closed - match nothing - instead of silently falling
-			// back to "see everything". PRD 006 F14/H2.
-			return db.Where("1 = 0")
-		}
-	}
+	return contractactions.Permission(tableName, p)
 }
 
-func getPermissionFromContext(c *gin.Context) *DataPermission {
-	p := new(DataPermission)
-	if pm, ok := c.Get(PermissionKey); ok {
-		switch pm.(type) {
-		case *DataPermission:
-			p = pm.(*DataPermission)
-		}
-	}
-	return p
-}
-
-// GetPermissionFromContext 提供非action写法数据范围约束
 func GetPermissionFromContext(c *gin.Context) *DataPermission {
-	return getPermissionFromContext(c)
+	return contractactions.GetPermissionFromContext(c)
+}
+
+// IsValidDataScope reports whether s is one of the five values Permission
+// recognizes. See go-admin-core's sdk/contract/actions.IsValidDataScope.
+func IsValidDataScope(s string) bool {
+	return contractactions.IsValidDataScope(s)
 }

common/actions/permission_test.go

@@ -1,4 +1,4 @@
-package actions
+package actions_test
 
 import (
 	"net/http"
@@ -6,201 +6,101 @@ import (
 	"testing"
 
 	"github.com/gin-gonic/gin"
-	"github.com/glebarez/sqlite"
+
 	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
-	"gorm.io/gorm"
+
+	"go-admin/common/actions"
 )
 
-// No database is placed in the context on purpose. The middleware needs one
-// only to run the sys_user join, so reaching the handler proves it did not.
-func runPermission(t *testing.T, claims jwt.MapClaims) (*DataPermission, bool) {
-	t.Helper()
-	gin.SetMode(gin.TestMode)
+// The detailed data-permission regression suite (claims parsing, the
+// GetOrm-unavailable abort, the SQL each data scope produces) now lives in
+// go-admin-core's sdk/contract/actions, alongside the logic itself (PRD 006
+// F3). What is left to test here is the shim's own wiring: that this
+// package's exported names still round-trip through the same *gin.Context
+// key core's PermissionAction and GetPermissionFromContext use.
+//
+// This file lives in package actions_test, an external test, deliberately:
+// it exercises PermissionAction and GetPermissionFromContext exactly as an
+// app/admin Service does, through this package's public API only, not
+// through anything internal a forward could paper over.
 
-	c, _ := gin.CreateTestContext(httptest.NewRecorder())
-	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
-	if claims != nil {
-		c.Set(jwt.JwtPayloadKey, claims)
-	}
-
-	PermissionAction()(c)
-
-	value, exists := c.Get(PermissionKey)
-	if !exists {
-		return nil, false
-	}
-	p, _ := value.(*DataPermission)
-	return p, true
-}
-
-// Permission() returns the query untouched when data permission is off, so the
-// lookup feeding it has nothing to feed. It used to run regardless: a sys_user
-// join on every list, detail, update and delete, discarded immediately.
-func TestNoLookupWhenDataPermissionIsOff(t *testing.T) {
-	previous := config.ApplicationConfig.EnableDP
-	config.ApplicationConfig.EnableDP = false
-	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
-
-	if _, ok := runPermission(t, jwt.MapClaims{"identity": float64(7)}); !ok {
-		t.Fatal("the request needed a database even though data permission is off")
-	}
-}
-
-func TestScopeComesFromTheTokenWhenItCarriesOne(t *testing.T) {
+// TestPermissionKeyMatchesWhatPermissionActionSets guards PRD 006's hard
+// constraint 4: PermissionKey must be declared as
+// `const PermissionKey = contractactions.PermissionKey`, a direct
+// reference, never a restated literal (see type.go). PermissionAction is
+// core's middleware and always writes under core's own key. This test reads
+// the value back with actions.PermissionKey exactly as code outside
+// GetPermissionFromContext would - c.Get(actions.PermissionKey) is a real,
+// if uncommon, way to read the value go-admin has always allowed, and it is
+// the one call site where an independently declared PermissionKey would
+// stop working without GetPermissionFromContext's own forward hiding it.
+//
+// If PermissionKey were ever re-declared as an independent literal in this
+// package, a later edit to core's copy would make this test fail without a
+// single byte of this package having changed - which is the silent-failure
+// mode hard constraint 4 exists to rule out (evaluation S2).
+func TestPermissionKeyMatchesWhatPermissionActionSets(t *testing.T) {
 	previous := config.ApplicationConfig.EnableDP
 	config.ApplicationConfig.EnableDP = true
 	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
 
-	p, ok := runPermission(t, jwt.MapClaims{
+	gin.SetMode(gin.TestMode)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+	c.Set(jwt.JwtPayloadKey, jwt.MapClaims{
 		"identity":  float64(7),
 		"roleid":    float64(3),
 		"deptid":    float64(5),
-		"datascope": "4",
+		"datascope": actions.DataScopeDeptTree,
 	})
+
+	actions.PermissionAction()(c)
+
+	value, ok := c.Get(actions.PermissionKey)
 	if !ok {
-		t.Fatal("the token carried the scope and a database was still needed")
+		t.Fatal("PermissionAction did not set the key actions.PermissionKey names; the two have diverged")
 	}
-	if p.DataScope != "4" || p.UserId != 7 || p.DeptId != 5 || p.RoleId != 3 {
-		t.Fatalf("scope read as %+v", p)
+	p, ok := value.(*actions.DataPermission)
+	if !ok || p.DataScope != actions.DataScopeDeptTree || p.DeptId != 5 {
+		t.Fatalf("value under actions.PermissionKey = %#v, want a DataPermission carrying the token's scope", value)
 	}
 }
 
-// A token minted before deptid was carried is still valid until it expires, and
-// has to keep working - by falling back to the query, which needs a database.
-func TestATokenWithoutDeptIdFallsBackToTheQuery(t *testing.T) {
-	previous := config.ApplicationConfig.EnableDP
-	config.ApplicationConfig.EnableDP = true
-	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
-
-	if _, ok := runPermission(t, jwt.MapClaims{
-		"identity":  float64(7),
-		"roleid":    float64(3),
-		"datascope": "4",
-	}); ok {
-		t.Fatal("an old token was served from claims it does not have")
-	}
-}
-
-// PRD 006 F14/H1. A token without deptid/datascope forces the fallback
-// query, which needs pkg.GetOrm(c) - and no "db" key is set in this
-// context, so GetOrm fails exactly as it would if a tenant's database were
-// unreachable. Before the fix, that error was logged and the handler ran
-// anyway with no data permission filter at all.
-func TestPermissionActionAbortsWhenDBIsUnavailable(t *testing.T) {
+// TestGetPermissionFromContextRoundTrips is the same guard from the other
+// exported entry point: GetPermissionFromContext must read back exactly
+// what PermissionAction wrote, both reached through this package's own
+// forwards rather than core's directly.
+func TestGetPermissionFromContextRoundTrips(t *testing.T) {
 	previous := config.ApplicationConfig.EnableDP
 	config.ApplicationConfig.EnableDP = true
 	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
 
 	gin.SetMode(gin.TestMode)
-	r := gin.New()
-	handlerReached := false
-	r.Use(func(c *gin.Context) {
-		c.Set(jwt.JwtPayloadKey, jwt.MapClaims{"identity": float64(7)})
-	})
-	r.Use(PermissionAction())
-	r.GET("/", func(c *gin.Context) {
-		handlerReached = true
-		c.Status(http.StatusOK)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Request = httptest.NewRequest(http.MethodGet, "/", nil)
+	c.Set(jwt.JwtPayloadKey, jwt.MapClaims{
+		"identity":  float64(7),
+		"roleid":    float64(3),
+		"deptid":    float64(5),
+		"datascope": actions.DataScopeSelf,
 	})
 
-	req := httptest.NewRequest(http.MethodGet, "/", nil)
-	w := httptest.NewRecorder()
-	r.ServeHTTP(w, req)
+	actions.PermissionAction()(c)
 
-	if handlerReached {
-		t.Fatal("the business handler ran with no database and no data permission filter set")
+	p := actions.GetPermissionFromContext(c)
+	if p.DataScope != actions.DataScopeSelf || p.UserId != 7 {
+		t.Fatalf("GetPermissionFromContext() = %+v, want DataScope=%q UserId=7", p, actions.DataScopeSelf)
 	}
 }
 
-// PRD 006 F14/H2 and H3. Table-driven over gorm DryRun so the exact SQL
-// Permission produces for each scope is pinned down, not just "some WHERE
-// clause got added".
-func TestPermissionScopes(t *testing.T) {
-	previous := config.ApplicationConfig.EnableDP
-	config.ApplicationConfig.EnableDP = true
-	t.Cleanup(func() { config.ApplicationConfig.EnableDP = previous })
-
-	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{DryRun: true})
-	if err != nil {
-		t.Fatalf("open: %v", err)
+func TestIsValidDataScope(t *testing.T) {
+	for _, s := range []string{actions.DataScopeAll, actions.DataScopeCustom, actions.DataScopeDept, actions.DataScopeDeptTree, actions.DataScopeSelf} {
+		if !actions.IsValidDataScope(s) {
+			t.Errorf("IsValidDataScope(%q) = false, want true", s)
+		}
 	}
-
-	const noRows = "SELECT * FROM `t` WHERE 1 = 0"
-
-	cases := []struct {
-		name string
-		p    *DataPermission
-		want string
-		vars []interface{}
-	}{
-		{
-			name: "all",
-			p:    &DataPermission{DataScope: DataScopeAll},
-			want: "SELECT * FROM `t`",
-		},
-		{
-			name: "custom",
-			p:    &DataPermission{DataScope: DataScopeCustom, RoleId: 3},
-			want: "SELECT * FROM `t` WHERE t.create_by in (select sys_user.user_id from sys_role_dept left join sys_user on sys_user.dept_id=sys_role_dept.dept_id where sys_role_dept.role_id = ?)",
-			vars: []interface{}{3},
-		},
-		{
-			name: "dept",
-			p:    &DataPermission{DataScope: DataScopeDept, DeptId: 5},
-			want: "SELECT * FROM `t` WHERE t.create_by in (SELECT user_id from sys_user where dept_id = ? )",
-			vars: []interface{}{5},
-		},
-		{
-			name: "dept-tree",
-			p:    &DataPermission{DataScope: DataScopeDeptTree, DeptId: 5},
-			want: "SELECT * FROM `t` WHERE t.create_by in (SELECT user_id from sys_user where sys_user.dept_id in(select dept_id from sys_dept where dept_path like ? ))",
-			vars: []interface{}{"%/5/%"},
-		},
-		{
-			name: "self",
-			p:    &DataPermission{DataScope: DataScopeSelf, UserId: 7},
-			want: "SELECT * FROM `t` WHERE t.create_by = ?",
-			vars: []interface{}{7},
-		},
-		// H2: an unrecognized scope must not read like "all data" any more.
-		{name: "unrecognized value", p: &DataPermission{DataScope: "6"}, want: noRows},
-		// H2/H1: the zero-value DataPermission is what getPermissionFromContext
-		// and the two "give up and continue" branches in PermissionAction hand
-		// out when nothing else is available.
-		{name: "zero value (no scope at all)", p: &DataPermission{}, want: noRows},
-		// H3: dept_path always starts with "/0/" (sys_dept.go), so DeptId 0
-		// must not be allowed to build a pattern that matches every row.
-		{name: "dept with DeptId 0", p: &DataPermission{DataScope: DataScopeDept, DeptId: 0}, want: noRows},
-		{name: "dept-tree with DeptId 0", p: &DataPermission{DataScope: DataScopeDeptTree, DeptId: 0}, want: noRows},
-		{name: "dept-tree with negative DeptId", p: &DataPermission{DataScope: DataScopeDeptTree, DeptId: -1}, want: noRows},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			stmt := db.Session(&gorm.Session{DryRun: true}).
-				Table("t").
-				Scopes(Permission("t", tc.p)).
-				Find(&[]map[string]interface{}{}).
-				Statement
-
-			if stmt.SQL.String() != tc.want {
-				t.Errorf("SQL = %q, want %q", stmt.SQL.String(), tc.want)
-			}
-			if tc.vars == nil {
-				if len(stmt.Vars) != 0 {
-					t.Errorf("vars = %v, want none", stmt.Vars)
-				}
-				return
-			}
-			if len(stmt.Vars) != len(tc.vars) {
-				t.Fatalf("vars = %v, want %v", stmt.Vars, tc.vars)
-			}
-			for i := range tc.vars {
-				if stmt.Vars[i] != tc.vars[i] {
-					t.Errorf("vars[%d] = %v, want %v", i, stmt.Vars[i], tc.vars[i])
-				}
-			}
-		})
+	if actions.IsValidDataScope("6") {
+		t.Error(`IsValidDataScope("6") = true, want false`)
 	}
 }

common/actions/type.go

@@ -1,5 +1,13 @@
 package actions
 
-const (
-	PermissionKey = "dataPermission"
-)
+import contractactions "github.com/go-admin-team/go-admin-core/v2/sdk/contract/actions"
+
+// PermissionKey is a direct reference to go-admin-core's sdk/contract/actions
+// constant, not a restated literal - see that package's PermissionKey doc
+// comment. PRD 006's hard constraint 4 requires this form for exactly this
+// symbol: PermissionAction (below) sets the gin context key it owns, and
+// GetPermissionFromContext reads it back; an independently declared literal
+// here would let the two silently drift apart if core's copy ever changed
+// without this one following. common/actions/shim_test.go carries the
+// regression test for that failure mode.
+const PermissionKey = contractactions.PermissionKey

common/dto/auto_form.go

@@ -1,74 +1,15 @@
 package dto
 
-type AutoForm struct {
-	Fields        []Field `json:"fields"`
-	FormRef       string  `json:"formRef"`
-	FormModel     string  `json:"formModel"`
-	Size          string  `json:"size"`
-	LabelPosition string  `json:"labelPosition"`
-	LabelWidth    int     `json:"labelWidth"`
-	FormRules     string  `json:"formRules"`
-	Gutter        int     `json:"gutter"`
-	Disabled      bool    `json:"disabled"`
-	Span          int     `json:"span"`
-	FormBtns      bool    `json:"formBtns"`
-}
+import contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
 
-type Config struct {
-	Label        string        `json:"label"`
-	LabelWidth   interface{}   `json:"labelWidth"`
-	ShowLabel    bool          `json:"showLabel"`
-	ChangeTag    bool          `json:"changeTag"`
-	Tag          string        `json:"tag"`
-	TagIcon      string        `json:"tagIcon"`
-	Required     bool          `json:"required"`
-	Layout       string        `json:"layout"`
-	Span         int           `json:"span"`
-	Document     string        `json:"document"`
-	RegList      []interface{} `json:"regList"`
-	FormId       int           `json:"formId"`
-	RenderKey    int64         `json:"renderKey"`
-	DefaultValue interface{}   `json:"defaultValue"`
-	ShowTip      bool          `json:"showTip,omitempty"`
-	ButtonText   string        `json:"buttonText,omitempty"`
-	FileSize     int           `json:"fileSize,omitempty"`
-	SizeUnit     string        `json:"sizeUnit,omitempty"`
-}
-
-type Option struct {
-	Label string `json:"label"`
-	Value string `json:"value"`
-}
-
-type Slot struct {
-	Prepend  string   `json:"prepend,omitempty"`
-	Append   string   `json:"append,omitempty"`
-	ListType bool     `json:"list-type,omitempty"`
-	Options  []Option `json:"options,omitempty"`
-}
-
-type Field struct {
-	Config        Config      `json:"__config__"`
-	Slot          Slot        `json:"__slot__"`
-	Placeholder   string      `json:"placeholder,omitempty"`
-	Style         Style       `json:"style,omitempty"`
-	Clearable     bool        `json:"clearable,omitempty"`
-	PrefixIcon    string      `json:"prefix-icon,omitempty"`
-	SuffixIcon    string      `json:"suffix-icon,omitempty"`
-	Maxlength     interface{} `json:"maxlength"`
-	ShowWordLimit bool        `json:"show-word-limit,omitempty"`
-	Readonly      bool        `json:"readonly,omitempty"`
-	Disabled      bool        `json:"disabled"`
-	VModel        string      `json:"__vModel__"`
-	Action        string      `json:"action,omitempty"`
-	Accept        string      `json:"accept,omitempty"`
-	Name          string      `json:"name,omitempty"`
-	AutoUpload    bool        `json:"auto-upload,omitempty"`
-	ListType      string      `json:"list-type,omitempty"`
-	Multiple      bool        `json:"multiple,omitempty"`
-	Filterable    bool        `json:"filterable,omitempty"`
-}
-
-type Style struct {
-	Width string `json:"width"`
-}
+// AutoForm and the types below describe a form built by go-admin-ui's form
+// designer. They are thin aliases of go-admin-core's sdk/contract/dto (PRD
+// 006 F2/F5).
+type (
+	AutoForm = contractdto.AutoForm
+	Config   = contractdto.Config
+	Option   = contractdto.Option
+	Slot     = contractdto.Slot
+	Field    = contractdto.Field
+	Style    = contractdto.Style
+)

common/dto/generate.go

@@ -1,106 +1,11 @@
 package dto
 
-import (
-	vd "github.com/bytedance/go-tagexpr/v2/validator"
-	"net/http"
+import contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
 
-	"github.com/gin-gonic/gin"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
+// ObjectById, ObjectGetReq and ObjectDeleteReq are thin aliases of
+// go-admin-core's sdk/contract/dto (PRD 006 F2/F5).
+type (
+	ObjectById      = contractdto.ObjectById
+	ObjectGetReq    = contractdto.ObjectGetReq
+	ObjectDeleteReq = contractdto.ObjectDeleteReq
 )
-
-type ObjectById struct {
-	Id  int   `uri:"id"`
-	Ids []int `json:"ids"`
-}
-
-func (s *ObjectById) Bind(ctx *gin.Context) error {
-	var err error
-	log := api.GetRequestLogger(ctx)
-	err = ctx.ShouldBindUri(s)
-	if err != nil {
-		log.Warnf("ShouldBindUri error: %s", err.Error())
-		return err
-	}
-	if ctx.Request.Method == http.MethodDelete {
-		err = ctx.ShouldBind(&s)
-		if err != nil {
-			log.Warnf("ShouldBind error: %s", err.Error())
-			return err
-		}
-		if len(s.Ids) > 0 {
-			return nil
-		}
-		if s.Ids == nil {
-			s.Ids = make([]int, 0)
-		}
-		if s.Id != 0 {
-			s.Ids = append(s.Ids, s.Id)
-		}
-	}
-	if err = vd.Validate(s); err != nil {
-		log.Errorf("Validate error: %s", err.Error())
-		return err
-	}
-	return err
-}
-
-func (s *ObjectById) GetId() interface{} {
-	if len(s.Ids) > 0 {
-		s.Ids = append(s.Ids, s.Id)
-		return s.Ids
-	}
-	return s.Id
-}
-
-type ObjectGetReq struct {
-	Id int `uri:"id"`
-}
-
-func (s *ObjectGetReq) Bind(ctx *gin.Context) error {
-	var err error
-	log := api.GetRequestLogger(ctx)
-	err = ctx.ShouldBindUri(s)
-	if err != nil {
-		log.Warnf("ShouldBindUri error: %s", err.Error())
-		return err
-	}
-	if err = vd.Validate(s); err != nil {
-		log.Errorf("Validate error: %s", err.Error())
-		return err
-	}
-	return err
-}
-
-func (s *ObjectGetReq) GetId() interface{} {
-	return s.Id
-}
-
-type ObjectDeleteReq struct {
-	Ids []int `json:"ids"`
-}
-
-func (s *ObjectDeleteReq) Bind(ctx *gin.Context) error {
-	var err error
-	log := api.GetRequestLogger(ctx)
-	err = ctx.ShouldBind(&s)
-	if err != nil {
-		log.Warnf("ShouldBind error: %s", err.Error())
-		return err
-	}
-	if len(s.Ids) > 0 {
-		return nil
-	}
-	if s.Ids == nil {
-		s.Ids = make([]int, 0)
-	}
-
-	if err = vd.Validate(s); err != nil {
-		log.Errorf("Validate error: %s", err.Error())
-		return err
-	}
-	return err
-}
-
-func (s *ObjectDeleteReq) GetId() interface{} {
-	return s.Ids
-}

common/dto/order.go

@@ -2,11 +2,13 @@ package dto
 
 import (
 	"gorm.io/gorm"
-	"gorm.io/gorm/clause"
+
+	contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
 )
 
+// OrderDest forwards to go-admin-core's sdk/contract/dto (PRD 006 F2/F5). A
+// function cannot be aliased the way a type can, so this is a pure
+// pass-through rather than a `func X = pkg.X` form Go does not have.
 func OrderDest(sort string, bl bool) func(db *gorm.DB) *gorm.DB {
-	return func(db *gorm.DB) *gorm.DB {
-		return db.Order(clause.OrderByColumn{Column: clause.Column{Name: sort}, Desc: bl})
-	}
+	return contractdto.OrderDest(sort, bl)
 }

common/dto/pagination.go

@@ -1,20 +1,7 @@
 package dto
 
-type Pagination struct {
-	PageIndex int `form:"pageIndex"`
-	PageSize  int `form:"pageSize"`
-}
+import contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
 
-func (m *Pagination) GetPageIndex() int {
-	if m.PageIndex <= 0 {
-		m.PageIndex = 1
-	}
-	return m.PageIndex
-}
-
-func (m *Pagination) GetPageSize() int {
-	if m.PageSize <= 0 {
-		m.PageSize = 10
-	}
-	return m.PageSize
-}
+// Pagination is a thin alias of go-admin-core's sdk/contract/dto (PRD 006
+// F2/F5).
+type Pagination = contractdto.Pagination

common/dto/search.go

@@ -1,80 +1,31 @@
 package dto
 
 import (
-	"github.com/go-admin-team/go-admin-core/v2/tools/search"
-	"go-admin/common/global"
 	"gorm.io/gorm"
+
+	contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
 )
 
-type GeneralDelDto struct {
-	Id  int   `uri:"id" json:"id" validate:"required"`
-	Ids []int `json:"ids"`
-}
-
-func (g GeneralDelDto) GetIds() []int {
-	ids := make([]int, 0)
-	// Id 此前在 else 分支里被重复追加：仅传 Id 时会得到 [5 5]，
-	// 同一条记录被执行两次删除
-	if g.Id > 0 {
-		ids = append(ids, g.Id)
-	}
-	for _, id := range g.Ids {
-		if id > 0 {
-			ids = append(ids, id)
-		}
-	}
-	if len(ids) == 0 {
-		//方式全部删除
-		ids = append(ids, 0)
-	}
-	return ids
-}
-
-type GeneralGetDto struct {
-	Id int `uri:"id" json:"id" validate:"required"`
-}
+// GeneralDelDto and GeneralGetDto are thin aliases of go-admin-core's
+// sdk/contract/dto (PRD 006 F2/F5).
+type (
+	GeneralDelDto = contractdto.GeneralDelDto
+	GeneralGetDto = contractdto.GeneralGetDto
+)
 
+// MakeCondition and Paginate forward to go-admin-core's sdk/contract/dto
+// (PRD 006 F2/F5). This file used to read go-admin/common/global.Driver to
+// pick the SQL dialect MakeCondition resolves search tags against; the
+// lowered version instead reads db.Dialector.Name() from inside the closure
+// it returns, which is always the driver the caller's own *gorm.DB is bound
+// to - correct even when a multi-tenant host has more than one database
+// open with different drivers, which a single package-level variable could
+// never be. global.Driver itself is untouched and still readable, but
+// nothing in this package reads it anymore.
 func MakeCondition(q interface{}) func(db *gorm.DB) *gorm.DB {
-	return func(db *gorm.DB) *gorm.DB {
-		condition := &search.GormCondition{
-			GormPublic: search.GormPublic{},
-			Join:       make([]*search.GormJoin, 0),
-		}
-		search.ResolveSearchQuery(global.Driver, q, condition)
-		for _, join := range condition.Join {
-			if join == nil {
-				continue
-			}
-			db = db.Joins(join.JoinOn)
-			for k, v := range join.Where {
-				db = db.Where(k, v...)
-			}
-			for k, v := range join.Or {
-				db = db.Or(k, v...)
-			}
-			for _, o := range join.Order {
-				db = db.Order(o)
-			}
-		}
-		for k, v := range condition.Where {
-			db = db.Where(k, v...)
-		}
-		for k, v := range condition.Or {
-			db = db.Or(k, v...)
-		}
-		for _, o := range condition.Order {
-			db = db.Order(o)
-		}
-		return db
-	}
+	return contractdto.MakeCondition(q)
 }
 
 func Paginate(pageSize, pageIndex int) func(db *gorm.DB) *gorm.DB {
-	return func(db *gorm.DB) *gorm.DB {
-		offset := (pageIndex - 1) * pageSize
-		if offset < 0 {
-			offset = 0
-		}
-		return db.Offset(offset).Limit(pageSize)
-	}
+	return contractdto.Paginate(pageSize, pageIndex)
 }

common/dto/type.go

@@ -1,21 +1,10 @@
 package dto
 
-import (
-	"github.com/gin-gonic/gin"
-	"go-admin/common/models"
+import contractdto "github.com/go-admin-team/go-admin-core/v2/sdk/contract/dto"
+
+// Index and Control are thin aliases of go-admin-core's sdk/contract/dto
+// (PRD 006 F2/F5).
+type (
+	Index   = contractdto.Index
+	Control = contractdto.Control
 )
-
-type Index interface {
-	Generate() Index
-	Bind(ctx *gin.Context) error
-	GetPageIndex() int
-	GetPageSize() int
-	GetNeedSearch() interface{}
-}
-
-type Control interface {
-	Generate() Control
-	Bind(ctx *gin.Context) error
-	GenerateM() (models.ActiveRecord, error)
-	GetId() interface{}
-}

common/global/adm.go

@@ -7,5 +7,12 @@ const (
 
 var (
 	// Driver 数据库驱动
+	//
+	// Deprecated: common/dto.MakeCondition stopped reading this after PRD
+	// 006 F2/F5 - it now takes the dialect from the *gorm.DB passed to the
+	// scope it returns instead of this process-wide variable. Driver is
+	// still set (common/database/initialize.go) and still readable for fork
+	// code that reads it directly, but it is no longer this framework's own
+	// path to the current SQL dialect.
 	Driver string
 )

common/health/health.go

@@ -0,0 +1,157 @@
+// Package health answers whether this process should be sent traffic.
+//
+// The two questions an orchestrator asks are not the same one, and go-admin
+// answers them at two endpoints:
+//
+//   - /health is liveness: is the process there at all. It stays a bare 200,
+//     because the honest answer to "should I restart you" is almost always no.
+//     Restarting a process because its database is unreachable turns one
+//     outage into a crash loop that also loses the connection pool, the cache
+//     and every in-flight request.
+//   - /ready is readiness: should this instance receive requests now. It fails
+//     while the dependencies are unreachable, and - the part that only exists
+//     because of the life-cycle phases - it fails as soon as shutdown begins,
+//     before the server stops accepting, so a load balancer has a chance to
+//     take the instance out before connections are cut.
+package health
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"sync/atomic"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+)
+
+// draining is set when the process starts shutting down.
+//
+// It is kept here rather than read back from core: BeginShutdown sets a flag on
+// the Application, but nothing exports it, and one host wanting to know is not
+// yet a reason to widen that interface.
+var draining atomic.Bool
+
+// BeginDraining records that shutdown has started, so readiness fails from now
+// on. It is called with BeginShutdown, before anything is taken apart.
+func BeginDraining() { draining.Store(true) }
+
+// Draining reports whether shutdown has begun.
+func Draining() bool { return draining.Load() }
+
+// Check is one dependency and what asking it produced.
+type Check struct {
+	Name string `json:"name"`
+	OK   bool   `json:"ok"`
+	Err  string `json:"error,omitempty"`
+}
+
+// Ready asks every dependency this process cannot serve a request without.
+//
+// The queue is deliberately absent. Nothing on AdapterQueue answers "are you
+// reachable" without publishing something, the memory backend cannot fail, and
+// a queue that is down degrades logging rather than stopping requests - which
+// is a reason to alert, not a reason to leave the load balancer pool.
+func Ready(ctx context.Context) []Check {
+	return []Check{
+		safely("database", func() error { return pingDB(ctx) }),
+		safely("cache", probeCache),
+	}
+}
+
+// safely turns a panic into a failed check.
+//
+// Not defensive habit: the accessors hand back wrappers, not the resources.
+// sdk.Runtime.GetCacheAdapter builds a runtime.Cache around whatever is
+// configured and returns it even when nothing is - so the value is not nil, the
+// cache inside it is, and the first call dereferences it. A nil check cannot
+// see that, and the same is true of GetQueueAdapter.
+//
+// Whatever the reason, a probe is the last thing that should be able to take
+// the process down: the caller is asking whether this instance is well, and
+// killing it to answer is the wrong reply.
+func safely(name string, fn func() error) (c Check) {
+	c = Check{Name: name}
+	defer func() {
+		if r := recover(); r != nil {
+			c.OK, c.Err = false, fmt.Sprintf("the check panicked: %v", r)
+		}
+	}()
+	if err := fn(); err != nil {
+		c.Err = err.Error()
+		return c
+	}
+	c.OK = true
+	return c
+}
+
+// Healthy reports whether every check passed.
+func Healthy(checks []Check) bool {
+	for _, c := range checks {
+		if !c.OK {
+			return false
+		}
+	}
+	return true
+}
+
+func pingDB(ctx context.Context) error {
+	db := sdk.Runtime.GetDb()
+	if db == nil {
+		return errors.New("no database configured")
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	return sqlDB.PingContext(ctx)
+}
+
+// cacheProbePrefix names the probe's keys. The key itself is per probe, not
+// fixed: two /ready requests arriving together - or two instances sharing one
+// redis, which is the normal deployment - would otherwise overwrite each
+// other's value between the write and the read and each conclude the cache was
+// broken. A readiness probe that reports false negatives under load takes
+// healthy instances out of the pool, which is worse than not probing.
+const cacheProbePrefix = "go-admin:health:"
+
+// cacheProbeTTL is short because these keys are write-once and never read
+// again by anyone else; it only has to outlive the read that follows.
+const cacheProbeTTL = 30
+
+func probeCache() error {
+	adapter := sdk.Runtime.GetCacheAdapter()
+	if adapter == nil {
+		return errors.New("no cache configured")
+	}
+
+	suffix := make([]byte, 8)
+	if _, err := rand.Read(suffix); err != nil {
+		return fmt.Errorf("could not build a probe key: %w", err)
+	}
+	key := cacheProbePrefix + hex.EncodeToString(suffix)
+
+	// Written and read back rather than only read: a cache that answers "miss"
+	// for every key - a client pointed at the wrong server - is
+	// indistinguishable from a healthy one on a read alone.
+	want := time.Now().Format(time.RFC3339Nano)
+	if err := adapter.Set(key, want, cacheProbeTTL); err != nil {
+		return err
+	}
+	// Best effort, and its error is deliberately dropped: the verdict is
+	// already decided by the read below, and a cache that cannot delete a key
+	// it just wrote is not a reason to refuse traffic. The TTL is the real
+	// cleanup.
+	defer func() { _ = adapter.Del(key) }()
+
+	got, err := adapter.Get(key)
+	if err != nil {
+		return err
+	}
+	if got != want {
+		return errors.New("the cache returned a different value than was written")
+	}
+	return nil
+}

common/health/health_test.go

@@ -0,0 +1,241 @@
+package health
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/runtime"
+	corestorage "github.com/go-admin-team/go-admin-core/v2/storage"
+)
+
+func freshRuntime(t *testing.T) {
+	t.Helper()
+	previous := sdk.Runtime
+	t.Cleanup(func() { sdk.Runtime = previous })
+	sdk.Runtime = runtime.NewConfig()
+}
+
+// fakeCache answers whatever the test needs it to.
+type fakeCache struct {
+	mu      sync.Mutex
+	setErr  error
+	getErr  error
+	getBack string // returned instead of what was written, when non-empty
+	stored  map[string]string
+
+	// oneSlot makes the cache keep a single value however many keys are
+	// written, which is what a shared probe key turns any cache into.
+	oneSlot bool
+	slot    string
+
+	// setBarrier, when set, holds every writer until all of them have written.
+	// Without it the probes are short enough that the scheduler usually runs
+	// them one after another, and a shared key survives by luck rather than by
+	// design - which would leave the test below asserting nothing.
+	setBarrier *barrier
+}
+
+// barrier releases every waiter once n of them have arrived.
+type barrier struct {
+	n   int
+	mu  sync.Mutex
+	got int
+	ch  chan struct{}
+}
+
+func newBarrier(n int) *barrier { return &barrier{n: n, ch: make(chan struct{})} }
+
+func (b *barrier) wait() {
+	b.mu.Lock()
+	b.got++
+	if b.got == b.n {
+		close(b.ch)
+	}
+	b.mu.Unlock()
+	<-b.ch
+}
+
+func (c *fakeCache) String() string { return "fake" }
+
+func (c *fakeCache) Set(key string, val interface{}, _ int) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.setErr != nil {
+		return c.setErr
+	}
+	v, _ := val.(string)
+	if c.oneSlot {
+		c.slot = v
+		return nil
+	}
+	if c.stored == nil {
+		c.stored = map[string]string{}
+	}
+	c.stored[key] = v
+	c.mu.Unlock()
+	if c.setBarrier != nil {
+		// Outside the lock on purpose: waiting while holding it would deadlock
+		// every other writer before the barrier could fill.
+		c.setBarrier.wait()
+	}
+	c.mu.Lock()
+	return nil
+}
+
+func (c *fakeCache) Get(key string) (string, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.getErr != nil {
+		return "", c.getErr
+	}
+	if c.getBack != "" {
+		return c.getBack, nil
+	}
+	if c.oneSlot {
+		return c.slot, nil
+	}
+	return c.stored[key], nil
+}
+
+func (c *fakeCache) Del(key string) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.stored, key)
+	return nil
+}
+
+func (c *fakeCache) HashGet(_, _ string) (string, error) { return "", nil }
+func (c *fakeCache) HashDel(_, _ string) error           { return nil }
+func (c *fakeCache) Increase(string) error               { return nil }
+func (c *fakeCache) Decrease(string) error               { return nil }
+func (c *fakeCache) Expire(string, time.Duration) error  { return nil }
+
+var _ corestorage.AdapterCache = (*fakeCache)(nil)
+
+func named(checks []Check, name string) Check {
+	for _, c := range checks {
+		if c.Name == name {
+			return c
+		}
+	}
+	return Check{Name: name, Err: "check not reported at all"}
+}
+
+// A cache that accepts writes and answers every read with a different value is
+// the failure this probe exists for - a client pointed at the wrong server, or
+// one that silently drops everything. A read alone cannot tell that apart from
+// a healthy cache with a cold key, which is why the probe writes first.
+func TestCacheProbeFailsWhenTheValueDoesNotComeBack(t *testing.T) {
+	freshRuntime(t)
+	sdk.Runtime.SetCacheAdapter(&fakeCache{getBack: "something else"})
+
+	got := named(Ready(context.Background()), "cache")
+	if got.OK {
+		t.Error("the cache check passed although the value written was not the value read back")
+	}
+	if got.Err == "" {
+		t.Error("the failing check reported no reason")
+	}
+}
+
+func TestCacheProbePassesWhenTheValueComesBack(t *testing.T) {
+	freshRuntime(t)
+	sdk.Runtime.SetCacheAdapter(&fakeCache{})
+
+	if got := named(Ready(context.Background()), "cache"); !got.OK {
+		t.Errorf("the cache check failed for a cache that works: %s", got.Err)
+	}
+}
+
+func TestCacheProbeReportsAWriteFailure(t *testing.T) {
+	freshRuntime(t)
+	sdk.Runtime.SetCacheAdapter(&fakeCache{setErr: errors.New("connection refused")})
+
+	got := named(Ready(context.Background()), "cache")
+	if got.OK {
+		t.Error("the cache check passed although the write failed")
+	}
+}
+
+// Nothing configured is the case that used to take the process down rather
+// than answer. GetCacheAdapter builds a wrapper around whatever is configured
+// and returns it even when nothing is, so the value is not nil, the cache
+// inside it is, and Set dereferences it - a probe that panics is the worst
+// possible answer to "are you well".
+//
+// Every check has to be reported, passing or not. A probe that omits what it
+// could not reach reads as a shorter list of healthy things.
+func TestEveryDependencyIsReportedEvenWithNothingConfigured(t *testing.T) {
+	freshRuntime(t)
+
+	checks := Ready(context.Background())
+	for _, name := range []string{"database", "cache"} {
+		c := named(checks, name)
+		if c.Err == "check not reported at all" {
+			t.Errorf("%s was not reported", name)
+		}
+		if c.OK {
+			t.Errorf("%s passed with nothing configured", name)
+		}
+	}
+	if Healthy(checks) {
+		t.Error("Healthy said yes for a process with no database and no cache")
+	}
+}
+
+// Draining is what makes the shutdown graceful from the outside: it has to be
+// observable before the server stops accepting, or the load balancer learns
+// about the shutdown by having its connections cut.
+func TestDrainingIsObservableOnceItBegins(t *testing.T) {
+	previous := draining.Load()
+	t.Cleanup(func() { draining.Store(previous) })
+
+	draining.Store(false)
+	if Draining() {
+		t.Fatal("Draining reported true before shutdown began")
+	}
+	BeginDraining()
+	if !Draining() {
+		t.Error("Draining still reported false after BeginDraining")
+	}
+}
+
+// Two probes at once must both pass. With one fixed key they overwrite each
+// other's value between the write and the read, and a readiness probe that
+// reports false negatives under load takes healthy instances out of the pool -
+// which is worse than not probing at all.
+func TestConcurrentProbesDoNotOverwriteEachOther(t *testing.T) {
+	freshRuntime(t)
+	const probes = 16
+	sdk.Runtime.SetCacheAdapter(&fakeCache{setBarrier: newBarrier(probes)})
+
+	var wg sync.WaitGroup
+	failures := make(chan string, probes)
+	for i := 0; i < probes; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if c := named(Ready(context.Background()), "cache"); !c.OK {
+				failures <- c.Err
+			}
+		}()
+	}
+	wg.Wait()
+	close(failures)
+
+	var n int
+	var first string
+	for err := range failures {
+		if n == 0 {
+			first = err
+		}
+		n++
+	}
+	if n > 0 {
+		t.Errorf("%d of %d concurrent probes called a healthy cache broken; first: %s", n, probes, first)
+	}
+}

common/middleware/auth.go

@@ -3,11 +3,19 @@ package middleware
 import (
 	"time"
 
-	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
 	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
+	log "github.com/go-admin-team/go-admin-core/v2/logger"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
 	"go-admin/common/middleware/handler"
 )
 
+// authMiddleware is the single JWT middleware instance the whole process
+// shares. InitMiddleware builds it once, before any module registers its
+// routes; GetAuthMiddleware is how a module gets it back instead of calling
+// AuthInit itself and building another, functionally-equivalent-but-distinct
+// instance.
+var authMiddleware *jwt.GinJWTMiddleware
+
 // AuthInit jwt验证new
 func AuthInit() (*jwt.GinJWTMiddleware, error) {
 	timeout := time.Hour
@@ -33,4 +41,23 @@ func AuthInit() (*jwt.GinJWTMiddleware, error) {
 		TimeFunc:        time.Now,
 	})
 
-}
+}
+
+// GetAuthMiddleware returns the shared JWT middleware instance InitMiddleware
+// built at startup. Application modules (app/admin, app/jobs, app/other,
+// app/demo) call this instead of AuthInit so their router chains - which
+// still need the instance itself for authMiddleware.MiddlewareFunc() and
+// authMiddleware.LoginHandler, not just the bound closure registered under
+// sdk.Runtime's JwtTokenCheck key - end up using the same instance the host
+// registered, rather than one each.
+//
+// It fails loudly instead of returning nil: an InitRouter that runs before
+// InitMiddleware has a real startup-ordering bug, not a case to paper over
+// with a nil *jwt.GinJWTMiddleware that would panic much further down the
+// call chain with a far less useful stack trace.
+func GetAuthMiddleware() *jwt.GinJWTMiddleware {
+	if authMiddleware == nil {
+		log.Fatal("JWT middleware not initialized; InitMiddleware must run before any module's InitRouter")
+	}
+	return authMiddleware
+}

common/middleware/init.go

@@ -2,15 +2,20 @@ package middleware
 
 import (
 	"github.com/gin-gonic/gin"
-	jwt "github.com/go-admin-team/go-admin-core/v2/jwtauth"
+	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/runtime"
 	"go-admin/common/actions"
 )
 
+// These alias core's own constants (see sdk/runtime.GetHandlerFunc's contract
+// doc, section 9) rather than redeclaring the same three strings, so a typo
+// here can no longer split registration and lookup into two different keys
+// that both happen to compile.
 const (
-	JwtTokenCheck   string = "JwtToken"
-	RoleCheck       string = "AuthCheckRole"
-	PermissionCheck string = "PermissionAction"
+	JwtTokenCheck   = runtime.JwtTokenCheck
+	RoleCheck       = runtime.RoleCheck
+	PermissionCheck = runtime.PermissionCheck
 )
 
 func InitMiddleware(r *gin.Engine) {
@@ -29,7 +34,26 @@ func InitMiddleware(r *gin.Engine) {
 	r.Use(Secure)
 	// 链路追踪
 	//r.Use(middleware.Trace())
-	sdk.Runtime.SetMiddleware(JwtTokenCheck, (*jwt.GinJWTMiddleware).MiddlewareFunc)
+
+	// Build the shared JWT middleware instance here, before any module
+	// registers routes (initRouter runs ahead of runStartupHooks, which is
+	// what invokes each module's InitRouter - see cmd/api/server.go). Doing
+	// it once here, instead of once per module via AuthInit, is what makes
+	// GetAuthMiddleware and sdk.Runtime.GetHandlerFunc(JwtTokenCheck) both
+	// resolve to a single, meaningful instance instead of "whichever module
+	// happened to initialize last".
+	//
+	// SetMiddleware must be given a bound closure (authMiddleware.MiddlewareFunc()),
+	// not the unbound method expression (*jwt.GinJWTMiddleware).MiddlewareFunc:
+	// the latter has no receiver bound to it, so GetHandlerFunc's type
+	// assertion to gin.HandlerFunc always fails for it.
+	var err error
+	authMiddleware, err = AuthInit()
+	if err != nil {
+		// A process with no JWT middleware must not start serving requests.
+		log.Fatalf("JWT Init Error, %s", err.Error())
+	}
+	sdk.Runtime.SetMiddleware(JwtTokenCheck, authMiddleware.MiddlewareFunc())
 	sdk.Runtime.SetMiddleware(RoleCheck, AuthCheckRole())
 	sdk.Runtime.SetMiddleware(PermissionCheck, actions.PermissionAction())
 }

common/middleware/init_test.go

@@ -0,0 +1,77 @@
+package middleware
+
+import (
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"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"
+)
+
+// freshRuntime hands the test its own Runtime and puts the old one back, the
+// same pattern cmd/api/server_test.go uses: sdk.Runtime is a process-wide
+// singleton, and a test that registers into it would otherwise leak state
+// into every other test in the binary.
+func freshRuntime(t *testing.T) {
+	t.Helper()
+	previous := sdk.Runtime
+	t.Cleanup(func() { sdk.Runtime = previous })
+	sdk.Runtime = runtime.NewConfig()
+}
+
+// TestInitMiddlewareRegistersUsableJwtHandlerFunc is the reverse proof for
+// hoisting the JWT instance's construction into InitMiddleware:
+// sdk.Runtime.GetHandlerFunc(JwtTokenCheck) must hand back ok=true and a
+// non-nil gin.HandlerFunc, not just something GetMiddleware can return as an
+// untyped interface{}.
+//
+// Before this change, InitMiddleware registered the unbound method
+// expression (*jwt.GinJWTMiddleware).MiddlewareFunc under this key - a value
+// with no receiver bound to it, which is not a gin.HandlerFunc no matter how
+// a caller asserts its type. Reverting the registration below to that
+// expression makes GetHandlerFunc report ok=false; it does not fail to
+// compile, because (*jwt.GinJWTMiddleware).MiddlewareFunc has a well-formed,
+// unrelated method-expression type that SetMiddleware's interface{} param
+// happily accepts.
+func TestInitMiddlewareRegistersUsableJwtHandlerFunc(t *testing.T) {
+	freshRuntime(t)
+
+	previousSecret := config.JwtConfig.Secret
+	config.JwtConfig.Secret = "test-secret-key"
+	t.Cleanup(func() { config.JwtConfig.Secret = previousSecret })
+
+	gin.SetMode(gin.TestMode)
+	InitMiddleware(gin.New())
+
+	h, ok := sdk.Runtime.GetHandlerFunc(JwtTokenCheck)
+	if !ok {
+		t.Fatal("GetHandlerFunc(JwtTokenCheck) reported ok=false after InitMiddleware ran")
+	}
+	if h == nil {
+		t.Fatal("GetHandlerFunc(JwtTokenCheck) reported ok=true but returned a nil handler")
+	}
+}
+
+// TestInitMiddlewareBuildsOneSharedJwtInstance locks down the fix for the
+// four-instances problem: GetAuthMiddleware must return the very instance
+// InitMiddleware built and handed to sdk.Runtime, not a lookalike built
+// separately by whichever caller asks first.
+func TestInitMiddlewareBuildsOneSharedJwtInstance(t *testing.T) {
+	freshRuntime(t)
+
+	previousSecret := config.JwtConfig.Secret
+	config.JwtConfig.Secret = "test-secret-key"
+	t.Cleanup(func() { config.JwtConfig.Secret = previousSecret })
+
+	gin.SetMode(gin.TestMode)
+	InitMiddleware(gin.New())
+
+	shared := GetAuthMiddleware()
+	if shared == nil {
+		t.Fatal("GetAuthMiddleware returned nil after InitMiddleware ran")
+	}
+	if shared != authMiddleware {
+		t.Error("GetAuthMiddleware did not return the package-level instance InitMiddleware built")
+	}
+}

common/middleware/permission.go

@@ -59,6 +59,33 @@ func AuthCheckRole() gin.HandlerFunc {
 	}
 }
 
+// EnforceRoleFor reports whether the caller's role has explicit Casbin
+// permission to act on path with method.
+//
+// AuthCheckRole never calls Enforce for a route CasbinExclude lists - that
+// is the whole point of the list. A handler on such a route can still need
+// the real answer for part of what it does: sys_user.go's Update shares its
+// excluded route between the personal-center screen editing the caller's own
+// record (which is why the route is excluded at all) and an admin editing
+// someone else's, and only the second case is meant to require a policy
+// grant. That handler asks here instead of assuming the middleware already
+// checked.
+func EnforceRoleFor(c *gin.Context, path, method string) (bool, error) {
+	data, ok := c.Get(jwtauth.JwtPayloadKey)
+	if !ok {
+		return false, nil
+	}
+	v, ok := data.(jwtauth.MapClaims)
+	if !ok {
+		return false, nil
+	}
+	if v["rolekey"] == "admin" {
+		return true, nil
+	}
+	e := sdk.Runtime.GetCasbinByTenant(c.Request.Host)
+	return e.Enforce(v["rolekey"], path, method)
+}
+
 // excludedFromCasbin reports whether the route skips the permission check.
 //
 // It runs for every non-admin request, so the order matters: the method rules

common/middleware/settings.go

@@ -34,6 +34,7 @@ var CasbinExclude = []UrlInfo{
 	{Url: "/api/v1/user/pwd", Method: "PUT"},
 	{Url: "/api/v1/metrics", Method: "GET"},
 	{Url: "/api/v1/health", Method: "GET"},
+	{Url: "/api/v1/ready", Method: "GET"},
 	{Url: "/", Method: "GET"},
 	{Url: "/api/v1/server-monitor", Method: "GET"},
 	{Url: "/api/v1/public/uploadFile", Method: "POST"},

common/models/by.go

@@ -1,41 +1,13 @@
 package models
 
-import (
-	"time"
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
 
-	"gorm.io/plugin/soft_delete"
+// ControlBy, Model and ModelTime are thin aliases of go-admin-core's
+// sdk/contract/models (PRD 006 F1/F5). A type alias is the same type, not a
+// new one, so every model that embeds these keeps its GORM tags, JSON tags
+// and method set untouched.
+type (
+	ControlBy = contractmodels.ControlBy
+	Model     = contractmodels.Model
+	ModelTime = contractmodels.ModelTime
 )
-
-type ControlBy struct {
-	CreateBy int `json:"createBy" gorm:"index;comment:创建者"`
-	UpdateBy int `json:"updateBy" gorm:"index;comment:更新者"`
-}
-
-// SetCreateBy 设置创建人id
-func (e *ControlBy) SetCreateBy(createBy int) {
-	e.CreateBy = createBy
-}
-
-// SetUpdateBy 设置修改人id
-func (e *ControlBy) SetUpdateBy(updateBy int) {
-	e.UpdateBy = updateBy
-}
-
-type Model struct {
-	Id int `json:"id" gorm:"primaryKey;autoIncrement;comment:主键编码"`
-}
-
-type ModelTime struct {
-	CreatedAt time.Time `json:"createdAt" gorm:"comment:创建时间"`
-	UpdatedAt time.Time `json:"updatedAt" gorm:"comment:最后更新时间"`
-
-	// DeletedAt is milliseconds since the epoch, zero while the row is live,
-	// and never null.
-	//
-	// A nullable marker cannot take part in a unique index. Two live rows are
-	// (name, NULL) and (name, NULL), and NULL is not equal to NULL, so the
-	// index permits both — it looks like a constraint and enforces nothing.
-	// With zero for live rows the pair collides, while two deletions of the
-	// same name differ by their timestamps and both remain.
-	DeletedAt soft_delete.DeletedAt `json:"-" gorm:"softDelete:milli;index;comment:删除时间"`
-}

common/models/menu.go

@@ -1,11 +1,15 @@
 package models
 
-// Menu 菜单中的类型枚举值
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
+
+// Directory, Menu and Button are the menu type enum values used by
+// sys_menu.menu_type, referenced directly from go-admin-core's
+// sdk/contract/models rather than restated as literals: PRD 006's hard
+// constraint 4 requires `const X = pkg.X` for exactly this reason - two
+// independently written copies of the same value can be edited out of step,
+// where a direct reference cannot.
 const (
-	// Directory 目录
-	Directory string = "M"
-	// Menu 菜单
-	Menu      string = "C"
-	// Button 按钮
-	Button    string = "F"
+	Directory = contractmodels.Directory
+	Menu      = contractmodels.Menu
+	Button    = contractmodels.Button
 )

common/models/migrate.go

@@ -1,23 +1,10 @@
 package models
 
-import "time"
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
 
-type Migration struct {
-	Version   string    `gorm:"primaryKey"`
-	ApplyTime time.Time `gorm:"autoCreateTime"`
-
-	// AppCode identifies which app registered this migration. The empty string
-	// means the framework itself.
-	//
-	// NOT NULL DEFAULT '' rather than a nullable column, and the difference is
-	// not cosmetic: on a nullable column the rows that already exist when
-	// AutoMigrate adds it hold NULL, and the first SELECT scanning one into
-	// this string field fails with "converting NULL to string is unsupported".
-	// The default is what makes "existing history belongs to the framework"
-	// true without a backfill script anyone could forget to run.
-	AppCode string `gorm:"type:varchar(64);not null;default:'';index:idx_sys_migration_app_code;comment:AppCode"`
-}
-
-func (Migration) TableName() string {
-	return "sys_migration"
-}
+// Migration is the sys_migration row model (data). It is unrelated to
+// cmd/migrate/migration.Migration, the in-process registration table this
+// package's TableName has nothing to do with - see
+// go-admin-core's sdk/contract/models.Migration doc comment for why the two
+// share a name.
+type Migration = contractmodels.Migration

common/models/response.go

@@ -1,30 +1,10 @@
 package models
 
-type Response struct {
-	// 代码
-	Code int `json:"code" example:"200"`
-	// 数据集
-	Data interface{} `json:"data"`
-	// 消息
-	Msg       string `json:"msg"`
-	RequestId string `json:"requestId"`
-}
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
 
-type Page struct {
-	List      interface{} `json:"list"`
-	Count     int         `json:"count"`
-	PageIndex int         `json:"pageIndex"`
-	PageSize  int         `json:"pageSize"`
-}
-
-// ReturnOK 正常返回
-func (res *Response) ReturnOK() *Response {
-	res.Code = 200
-	return res
-}
-
-// ReturnError 错误返回
-func (res *Response) ReturnError(code int) *Response {
-	res.Code = code
-	return res
-}
+// Response and Page are thin aliases of go-admin-core's sdk/contract/models
+// (PRD 006 F1/F5).
+type (
+	Response = contractmodels.Response
+	Page     = contractmodels.Page
+)

common/models/type.go

@@ -1,11 +1,12 @@
 package models
 
-import "gorm.io/gorm/schema"
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
 
-type ActiveRecord interface {
-	schema.Tabler
-	SetCreateBy(createBy int)
-	SetUpdateBy(updateBy int)
-	Generate() ActiveRecord
-	GetId() interface{}
-}
+// ActiveRecord is self-referencing (Generate() ActiveRecord), which is why
+// it must stay a type alias rather than a defined type: aliasing preserves
+// identity with go-admin-core's sdk/contract/models.ActiveRecord, so a
+// model whose Generate() returns that interface still satisfies this one. A
+// defined type here would break every implementer's method set - see
+// go-admin-core's sdk/contract/models package tests for the counterproof
+// (PRD 006 counterproof A).
+type ActiveRecord = contractmodels.ActiveRecord

common/models/user.go

@@ -1,42 +1,7 @@
 package models
 
-import (
-	"gorm.io/gorm"
+import contractmodels "github.com/go-admin-team/go-admin-core/v2/sdk/contract/models"
 
-	"github.com/go-admin-team/go-admin-core/v2/sdk/pkg"
-)
-
-// BaseUser 密码登录基础用户
-type BaseUser struct {
-	Username     string `json:"username" gorm:"type:varchar(100);comment:用户名"`
-	Salt         string `json:"-" gorm:"type:varchar(255);comment:加盐;<-"`
-	PasswordHash string `json:"-" gorm:"type:varchar(128);comment:密码hash;<-"`
-	Password     string `json:"password" gorm:"-"`
-}
-
-// SetPassword 设置密码
-func (u *BaseUser) SetPassword(value string) {
-	u.Password = value
-	u.generateSalt()
-	u.PasswordHash = u.GetPasswordHash()
-}
-
-// GetPasswordHash 获取密码hash
-func (u *BaseUser) GetPasswordHash() string {
-	passwordHash, err := pkg.SetPassword(u.Password, u.Salt)
-	if err != nil {
-		return ""
-	}
-	return passwordHash
-}
-
-// generateSalt 生成加盐值
-func (u *BaseUser) generateSalt() {
-	u.Salt = pkg.GenerateRandomKey16()
-}
-
-// Verify 验证密码
-func (u *BaseUser) Verify(db *gorm.DB, tableName string) bool {
-	db.Table(tableName).Where("username = ?", u.Username).First(u)
-	return u.GetPasswordHash() == u.PasswordHash
-}
+// BaseUser is a thin alias of go-admin-core's sdk/contract/models (PRD 006
+// F1/F5).
+type BaseUser = contractmodels.BaseUser

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,75 @@ 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()
+
 	queueAdapter, err := config.QueueConfig.Setup()
 	if err != nil {
 		log.Fatalf("queue setup error, %s\n", err.Error())
 	}
+
+	previous := installed
 	sdk.Runtime.SetQueueAdapter(queueAdapter)
-	go queueAdapter.Run()
+	installed = queueAdapter
+	installedGen++
+
+	// The previous adapter goes down after the new one is installed, not
+	// before. Shutdown waits for its consumers to deliver what it still holds,
+	// and for that whole wait the runtime would otherwise be handing producers
+	// a queue that has stopped accepting: every Append in the window comes back
+	// ErrQueueClosed, and both call sites in common/middleware log it. Swapping
+	// first leaves no such window - a producer gets the new queue or the old
+	// one, and both work.
+	//
+	// 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 previous != nil {
+		previous.Shutdown()
+	}
+
+	// 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)
+	}
+}

common/storage/queue_swap_test.go

@@ -0,0 +1,161 @@
+package storage
+
+import (
+	"errors"
+	"sync"
+	"sync/atomic"
+	"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"
+	corestorage "github.com/go-admin-team/go-admin-core/v2/storage"
+	"github.com/go-admin-team/go-admin-core/v2/storage/queue"
+)
+
+// sampleSize is how many publishes have to land inside the reload before the
+// measurement is taken. Waiting on the count rather than on wall clock keeps
+// the window the test covers the same on a loaded runner as on an idle one.
+const sampleSize = 200
+
+func swapMsg() corestorage.Messager {
+	m := new(queue.Message)
+	m.SetStream("t")
+	m.SetValues(map[string]interface{}{"a": "b"})
+	return m
+}
+
+// A reload must never leave producers holding a queue that has stopped
+// accepting.
+//
+// Shutdown waits for its consumers to deliver what the queue still holds. Taking
+// the old adapter down before installing the new one meant the runtime pointed
+// at a closed queue for that entire wait: every Append in the window came back
+// ErrQueueClosed, and both call sites in common/middleware log it at error
+// level. Installing first leaves no window - a producer gets the new queue or
+// the old one, and both accept.
+//
+// The difference is only visible during that wait, which is why the test holds
+// a consumer rather than checking the state after Setup has returned: by then
+// the two orders look identical.
+//
+// One refusal survives the fix and is not something this ordering can reach.
+// GetQueuePrefix hands back a wrapper that captured the adapter, so a producer
+// that fetched before the swap and appends after Shutdown has begun is still
+// holding the old one. That window is one call wide and closing it means
+// resolving the adapter inside Append, which is core's to change. What the
+// ordering removes is the sustained window: every producer that fetches during
+// the wait. The test publishes from a single goroutine, so at most one of its
+// calls can straddle the swap - which is what makes "more than one" the line
+// between the two orders rather than a tolerance.
+func TestAReloadNeverPointsProducersAtAClosedQueue(t *testing.T) {
+	prevQ, prevC := config.QueueConfig, config.CacheConfig
+	prevRuntime := sdk.Runtime
+	prevInstalled, prevGen := installed, installedGen
+	t.Cleanup(func() {
+		config.QueueConfig, config.CacheConfig = prevQ, prevC
+		sdk.Runtime = prevRuntime
+		queueMu.Lock()
+		installed, installedGen = prevInstalled, prevGen
+		queueMu.Unlock()
+	})
+	sdk.Runtime = runtime.NewConfig()
+	config.CacheConfig = &config.Cache{Memory: struct{}{}}
+	// Sized so the buffer cannot fill while the consumer is held: a full queue
+	// returns an error of its own, and this test needs every error other than
+	// ErrQueueClosed to mean something it does not model has happened.
+	config.QueueConfig = &config.Queue{Memory: &config.QueueMemory{PoolSize: 4096}}
+
+	Setup()
+
+	// A consumer that will not finish until this test lets it, so the reload's
+	// Shutdown has something to wait for.
+	release := make(chan struct{})
+	consuming := make(chan struct{})
+	var picked sync.Once
+	first := sdk.Runtime.GetQueuePrefix("")
+	first.Register("t", func(corestorage.Messager) error {
+		picked.Do(func() { close(consuming) })
+		<-release
+		return nil
+	})
+	go first.Run()
+	for i := 0; i < 4; i++ {
+		if err := first.Append(swapMsg()); err != nil {
+			t.Fatalf("seed append %d: %v", i, err)
+		}
+	}
+	select {
+	case <-consuming:
+	case <-time.After(10 * time.Second):
+		t.Fatal("the consumer never picked a message up, so the reload has nothing to wait for")
+	}
+
+	reloaded := make(chan struct{})
+	go func() { Setup(); close(reloaded) }()
+
+	// Publish continuously while the reload is in progress.
+	var refused atomic.Int64
+	var attempts atomic.Int64
+	unexpected := make(chan error, 1)
+	stop := make(chan struct{})
+	// publishing is closed by the producer on its way out. The test joins on it
+	// before returning: t.Cleanup restores sdk.Runtime, and a producer still in
+	// flight would be reading the variable that restore writes.
+	publishing := make(chan struct{})
+	go func() {
+		defer close(publishing)
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+			}
+			attempts.Add(1)
+			err := sdk.Runtime.GetQueuePrefix("").Append(swapMsg())
+			switch {
+			case err == nil:
+			case errors.Is(err, corestorage.ErrQueueClosed):
+				refused.Add(1)
+			default:
+				// Kept rather than counted: an Append refused for some other
+				// reason would otherwise leave refused at zero and the test
+				// green while nothing was reaching a queue at all.
+				select {
+				case unexpected <- err:
+				default:
+				}
+			}
+			time.Sleep(time.Millisecond)
+		}
+	}()
+
+	deadline := time.After(30 * time.Second)
+	for attempts.Load() < sampleSize {
+		select {
+		case <-deadline:
+			t.Fatalf("only %d publishes landed inside the reload; the window was never sampled", attempts.Load())
+		case <-time.After(time.Millisecond):
+		}
+	}
+	close(release)
+
+	select {
+	case <-reloaded:
+	case <-time.After(30 * time.Second):
+		t.Fatal("the reload never finished")
+	}
+	close(stop)
+	<-publishing
+
+	select {
+	case err := <-unexpected:
+		t.Fatalf("a publish failed for a reason this test does not model: %v", err)
+	default:
+	}
+	if n := refused.Load(); n > 1 {
+		t.Errorf("%d of %d publishes during the reload were refused: producers were pointed at the closed queue",
+			n, attempts.Load())
+	}
+}

common/storage/setup_gen_test.go

@@ -0,0 +1,53 @@
+package storage
+
+import (
+	"testing"
+
+	"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"
+)
+
+// Issue #892: a configuration reload replaces the queue adapter and the
+// consumers registered against the previous one are attached to a queue nobody
+// publishes to any more.
+//
+// The fix has two halves. attachQueueConsumers gives a new queue its own
+// consumers and the same queue none, which cmd/api covers against a queue the
+// test controls. This is the other half: that a reload actually produces a new
+// queue for it to notice. Setup is what config re-runs on every change, so
+// calling it twice is what a reload does to this package.
+func TestSetupBumpsTheQueueGenerationOnEveryReload(t *testing.T) {
+	// Setup writes the process-wide sdk.Runtime - the cache and queue adapters -
+	// and this package's own record of what it installed. Restoring all of it
+	// keeps the test from deciding what a later test in this binary sees,
+	// which is the same isolation cmd/api's freshRuntime provides.
+	prevQ, prevC := config.QueueConfig, config.CacheConfig
+	prevRuntime := sdk.Runtime
+	prevInstalled, prevGen := installed, installedGen
+	t.Cleanup(func() {
+		config.QueueConfig, config.CacheConfig = prevQ, prevC
+		sdk.Runtime = prevRuntime
+		queueMu.Lock()
+		installed, installedGen = prevInstalled, prevGen
+		queueMu.Unlock()
+	})
+	sdk.Runtime = runtime.NewConfig()
+
+	config.CacheConfig = &config.Cache{Memory: struct{}{}}
+	config.QueueConfig = &config.Queue{Memory: &config.QueueMemory{PoolSize: 10}}
+
+	before := QueueGeneration()
+	Setup()
+	first := QueueGeneration()
+	Setup()
+	second := QueueGeneration()
+
+	t.Logf("before=%d first=%d second=%d", before, first, second)
+	if first == before {
+		t.Fatal("the first Setup did not install a queue")
+	}
+	if second == first {
+		t.Fatal("a second Setup - which is what a configuration reload does - did not install a new one")
+	}
+}

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.4.1
+	github.com/go-admin-team/go-admin-core/v2 v2.7.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
@@ -32,7 +32,6 @@ require (
 	gorm.io/driver/sqlite v1.6.0
 	gorm.io/driver/sqlserver v1.6.4
 	gorm.io/gorm v1.31.2
-	gorm.io/plugin/soft_delete v1.2.1
 )
 
 require (
@@ -142,6 +141,7 @@ require (
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gorm.io/plugin/dbresolver v1.6.2 // indirect
+	gorm.io/plugin/soft_delete v1.2.1 // indirect
 	modernc.org/fileutil v1.3.40 // indirect
 	modernc.org/libc v1.67.4 // indirect
 	modernc.org/mathutil v1.7.1 // indirect

go.sum

@@ -145,8 +145,12 @@ github.com/glebarez/go-sqlite v1.22.0 h1:uAcMJhaA6r3LHMTFgP0SifzgXg46yJkgxqyuyec
 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.4.1 h1:69QprBVMcQzjVP0UksCwi//A0qh8gwcIHcwHmABPp2U=
-github.com/go-admin-team/go-admin-core/v2 v2.4.1/go.mod h1:YiJr2+vqC9qV5AoGeL+1W55h3XZ99CB5xWnP3Wo8c5g=
+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-admin-team/go-admin-core/v2 v2.7.0 h1:1qV0/5iFBvkE3BRtm4ip0v0QYG9Fgx4UtOTd8zkQT9c=
+github.com/go-admin-team/go-admin-core/v2 v2.7.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 {