chore🔧: gate gofmt in CI

The tree is at zero unformatted files for the first time. Nothing holds it
there: gofmt drift is invisible in review because the common form of it is a
missing newline at the end of a file, which no diff reader notices and no
existing check looks at. That is how the batch cleaned up just now reached 26
files.

`make fmt-check` reports rather than rewrites. CI cannot commit, and a target
that silently reformats hides what it touched; `gofmt -l` names the files and
says nothing when there are none, so its output is both the failure message and
the fix.

The step runs before the tests rather than beside checksilent at the end. A
formatting miss is a one-command fix, and learning about it after five minutes
of tests and an end-to-end install wastes five minutes for nothing.

.github/workflows/build.yml

@@ -1,12 +1,25 @@
 name: Build
 
-# Documentation-only changes skip this workflow entirely.
+# Documentation-only changes, and changes confined to the Kubernetes
+# manifests, skip this workflow entirely.
 #
 # A push to master here does not just build - it pushes an image, runs the
 # migrations and restarts the demo container, so the site takes a short outage.
 # Paying that for a README edit is waste at best; at worst a deploy fails for a
 # reason unrelated to anything in the change. Code coverage is unaffected,
 # because go.yml still builds every push and pull request.
+#
+# scripts/k8s holds deploy.yml, storage.yml and prerun.sh, and the deploy below
+# reads none of them - it is an ssh into one host that runs docker, building the
+# Dockerfile at the repository root. Those manifests are for people deploying to
+# a cluster of their own. The pattern is scripts/k8s/** rather than scripts/**
+# because scripts/Dockerfile is a build input: go.yml builds the release image
+# from it on a tag.
+#
+# A file outside these patterns still runs the workflow even when the rest of
+# the change is ignorable: paths-ignore skips only when every changed path
+# matches. Editing this file is one such case, on purpose - a deploy script
+# that is never exercised by the change that broke it is worse than an outage.
 on:
   push:
     branches: [ master ]
@@ -15,6 +28,7 @@ on:
       - 'docs/**'
       - 'LICENSE*'
       - '.github/ISSUE_TEMPLATE/**'
+      - 'scripts/k8s/**'
   pull_request:
     branches: [ master ]
     paths-ignore:
@@ -22,6 +36,7 @@ on:
       - 'docs/**'
       - 'LICENSE*'
       - '.github/ISSUE_TEMPLATE/**'
+      - 'scripts/k8s/**'
 
 # One deploy at a time. Two merges seconds apart raced here: both runs did
 # docker rm -f then docker run, the second removed the container the first had
@@ -102,7 +117,41 @@ jobs:
 
             test -f "$CFG" || { echo "宿主机配置缺失，中止部署"; exit 1; }
 
+            # Old images of this repository are removed here and nowhere else.
+            # Every deployment pulls one tagged with its commit and nothing ever
+            # removed the previous one, so they only accumulated: 68 of them
+            # filled the disk and the next deployment could not pull.
+            #
+            # Three are kept so a release can be re-run by tag by hand.
+            #
+            # Only this repository's images are listed, because the host runs
+            # other services whose images are not this script's business. The
+            # image the live container is on is excluded by id rather than by
+            # position, so it survives even if the listing order is not what
+            # it looks like. With no container to ask, the function returns
+            # rather than running the pipeline on an empty id - which would
+            # also delete nothing, but by way of grep -v matching every line,
+            # which reads like the opposite of what it does. No -f, so an image
+            # any container still holds - including the one kept for rollback -
+            # is refused rather than taken away from it.
+            prune_old_images() {
+              REPO="${IMG%:*}"
+              LIVE=$(sudo docker inspect -f '{{.Image}}' "$NAME" 2>/dev/null | sed 's/^sha256://' | cut -c1-12)
+              [ -n "$LIVE" ] || return 0
+              sudo docker images "$REPO" --format '{{.ID}} {{.Repository}}:{{.Tag}}' \
+                | grep -v "^$LIVE" \
+                | tail -n +3 \
+                | awk '{print $2}' \
+                | xargs -r -n1 sudo docker rmi >/dev/null 2>&1 || true
+            }
+
             sudo docker login --username=${{ secrets.DOCKER_USERNAME }} registry.ap-northeast-1.aliyuncs.com --password=${{ secrets.DOCKER_PASSWORD }}
+            # Before the pull, not only after a successful deploy. The pull
+            # is the first thing here that needs space and it is where a full
+            # disk stops this script, so a cleanup that only runs afterwards
+            # never runs on the host that needs it: rerunning the workflow
+            # fails at the same pull, and the disk has to be cleared by hand.
+            prune_old_images
             sudo docker pull "$IMG" || { echo "拉取镜像失败，中止部署"; exit 1; }
 
             # 迁移用新镜像跑。失败时线上仍是旧版本配旧 schema，是自洽的；
@@ -115,7 +164,14 @@ jobs:
             if sudo docker ps -a --format '{{.Names}}' | grep -qx "$NAME"; then
               sudo docker rm -f "$PREV" >/dev/null 2>&1 || true
               sudo docker rename "$NAME" "$PREV"
-              sudo docker stop "$PREV" >/dev/null
+              # --timeout, because the default is 10 seconds and the process
+              # spends drain + server + cleanup from extend.shutdown before it
+              # exits - 8 seconds out of the box, and more for anyone who
+              # configures a drain window. Past the deadline docker sends
+              # SIGKILL and the cleanup callbacks are cut off part-way through.
+              # checksilent's docker-stop-cuts-shutdown-short check compares
+              # this number against config/settings.yml.
+              sudo docker stop --timeout 30 "$PREV" >/dev/null
             fi
 
             sudo docker run -d -p 8000:8000 \
@@ -133,6 +189,10 @@ jobs:
 
             if [ "$ok" = "1" ]; then
               sudo docker rm -f "$PREV" >/dev/null 2>&1 || true
+
+              # Again, so the image this deployment replaced falls out of the
+              # window rather than waiting for the next deployment to notice.
+              prune_old_images
             else
               echo "健康检查失败，回滚到上一版本"
               sudo docker logs --tail 40 "$NAME" 2>&1 || true

.github/workflows/go.yml

@@ -15,6 +15,69 @@ 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
+
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: goadmin_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+
+      # The fourth registered driver, and the one that disagrees with the
+      # other three about NULL: its unique index treats two NULLs as equal and
+      # permits one. A migration that builds a unique index over a nullable
+      # column therefore fails here and nowhere else, which is how one shipped
+      # that no SQL Server database could apply at all - not even an empty
+      # one. The password is this container's only credential and the
+      # container lives for the length of one job.
+      sqlserver:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: "Y"
+          MSSQL_SA_PASSWORD: GoAdmin_Test1
+          MSSQL_PID: Developer
+        ports:
+          - 1433:1433
+        options: >-
+          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P GoAdmin_Test1 -C -Q 'SELECT 1'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 20
+          --health-start-period 20s
+
+    env:
+      GO_ADMIN_TEST_REDIS_ADDR: 127.0.0.1:6379
+      # The soft-delete conversion drops an index, and gorm's PostgreSQL driver
+      # produced unparseable SQL for that - on SQLite, where the rest of these
+      # tests run, the same code works. The suite reported success for a
+      # migration that failed on every PostgreSQL database it was pointed at.
+      # See go-admin#919.
+      GO_ADMIN_TEST_POSTGRES_DSN: "host=127.0.0.1 port=5432 user=postgres password=postgres dbname=goadmin_test sslmode=disable"
+      GO_ADMIN_TEST_SQLSERVER_DSN: "sqlserver://sa:GoAdmin_Test1@127.0.0.1:1433?database=goadmin_test"
+
     steps:
 
     - name: Set up Go 1.26
@@ -26,9 +89,23 @@ jobs:
     - name: Check out code into the Go module directory
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+    # SQL Server has no equivalent of POSTGRES_DB, so the database the DSN
+    # names has to be created before the tests run.
+    - name: Create the SQL Server test database
+      run: |
+        docker exec ${{ job.services.sqlserver.id }} /opt/mssql-tools18/bin/sqlcmd \
+          -S localhost -U sa -P GoAdmin_Test1 -C \
+          -Q "IF DB_ID('goadmin_test') IS NULL CREATE DATABASE goadmin_test"
+
     - name: Get dependencies
       run: go mod tidy
 
+    # Before the tests rather than beside checksilent at the end: a formatting
+    # miss is a one-command fix, and finding out about it after five minutes of
+    # tests and an end-to-end install is five minutes nobody gets back.
+    - name: Formatting
+      run: make fmt-check
+
     # go build does not compile _test.go, so building alone never ran a single
     # test. This is the only workflow that fires on every push and pull request,
     # which makes it the one place a test gate belongs.
@@ -38,6 +115,15 @@ jobs:
     - name: Build
       run: make build
 
+    # A separate module, so none of the steps above see it: the main module's
+    # go.mod, its build and its tests are all unaware of the example
+    # application. This is the only thing that exercises an application being
+    # installed at all - everything below it runs against an injected engine
+    # and a hand-built schema, and none of that can catch an application's
+    # init() reaching one registry and not the other.
+    - name: End-to-end install and uninstall
+      run: make test-e2e
+
     # Fails the build on the silent-failure classes listed in
     # tools/checksilent, one of which is the contract boundary: nothing under
     # common/ may import app/. A boundary that is only written down erodes; this

AGENTS.md

@@ -20,7 +20,7 @@ Router  →  Api      →  Service      →  Model
 
 ## 优先使用通用 Action
 
-单表 CRUD **不要手写 Handler 与 Service**。`common/actions` 提供的五个
+单表 CRUD **不要手写 Api 与 Service**。`common/actions` 提供的五个
 Action 已覆盖参数绑定、数据权限过滤、操作人注入、分页与错误响应：
 
 ```go
@@ -49,7 +49,7 @@ r := v1.Group("/demo-product").Use(authMiddleware.MiddlewareFunc()).Use(middlewa
   就地返回会串数据（`app/demo` 的测试锁定了这一点）
 - 详情/删除 DTO 内嵌 `dto.ObjectById` 即可继承 `Bind` 与 `GetId`，无需重写
 
-仅当业务超出单表 CRUD（跨表事务、外部调用、复杂校验）时才自行编写 Handler
+仅当业务超出单表 CRUD（跨表事务、外部调用、复杂校验）时才自行编写 Api
 与 Service，写法见下。
 
 ## Api 层（仅在通用 Action 不适用时）
@@ -167,7 +167,7 @@ sys_menu / sys_menu_api_rule / casbin_rule 四张表如何配齐，用的是幂
 
 ## Swagger
 
-Handler 必须带完整注解，`go generate` 会据此生成文档：
+Api 必须带完整注解，`go generate` 会据此生成文档：
 
 ```go
 // @Summary 岗位列表
@@ -227,8 +227,9 @@ go run -tags sqlite3 . server  -c config/settings.sqlite.yml
 
 ## 静默失败校验
 
-`make checksilent` 检查七类**不报错、不记日志、行为悄悄变得不对**的问题，
-CI 会跑，命中 ERROR 即失败：
+`make checksilent` 逐条检查那些**不报错、不记日志、行为悄悄变得不对**的问题，
+CI 会跑，命中 ERROR 即失败。这里不写条数——写死的数字会悄悄过时，
+真正的清单是 `tools/checksilent/checks.go` 里 `runChecks` 跑的那几个：
 
 | 检查 | 级别 | 静默后果 |
 |---|---|---|
@@ -238,8 +239,15 @@ CI 会跑，命中 ERROR 即失败：
 | `menu-id-collision` | ERROR | 两个模块硬编码同一菜单 ID，互相覆盖 |
 | `contract-import-boundary` | ERROR | 契约包 import `app/`，应用无法独立编译 |
 | `contract-shim-alias` | ERROR | 契约薄壳写成 defined type 而非别名，方法集丢失，本仓可能照常编译、第三方应用编译不过 |
+| `datascope-route-unguarded` | ERROR | handler 读调用方的数据权限，而注册它的路由组没装提供权限的中间件。取不到时拿到零值、走 fail-closed 分支，查询被塞进 `1 = 0`：接口对确实存在的行返回「查不到」，且只在 `enabledp: true` 的部署上出现 |
+| `shutdown-budget-overruns-grace` | ERROR / WARN | `settings.yml` 的 `extend.shutdown` 预算（含清单里的 `preStop`）放不进自带 k8s 清单的 `terminationGracePeriodSeconds`，SIGKILL 在清理回调跑到一半时到达 |
+| `docker-stop-cuts-shutdown-short` | ERROR / WARN | 停止容器的两条路径——脚本/工作流里的 `docker stop`，和 `docker-compose.yml` 的 `stop_grace_period`——没写或写得不够关闭预算用。两边默认都是 10 秒，而这个数字离命令很远，调大预算的人不会想起它 |
 | `menu-name-mismatch` | WARN | 菜单名与前端组件 `name` 不一致，keep-alive 缓存静默失效 |
 
+两条关闭预算检查分两级，用的是同一条算术和同一个 5 秒边际：真的超限报 ERROR，
+放得进但余量不足 5 秒报 WARN。余量不足做 WARN 不做 ERROR，是因为那是个技术上
+跑得通的配置——**一条在正确配置下也会响的 ERROR，训练的是忽略它**。
+
 最后一条要跨仓库比对，只能做正则启发式，因此是 WARN，**不影响退出码**，
 且默认跳过；要跑它得指定前端目录：
 

Dockerfile

@@ -4,10 +4,26 @@ FROM alpine
 
 RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.ustc.edu.cn/g' /etc/apk/repositories
 
-RUN apk update --no-cache
-RUN apk add --update gcc g++ libc6-compat
-RUN apk add --no-cache ca-certificates
-RUN apk add --no-cache tzdata
+# Runtime packages only.
+#
+# gcc and g++ used to be installed here and were 273MB of a 381MB image. The
+# binary this image runs is compiled and linked before the image is built and
+# arrives as a COPY, so nothing in the container ever invokes a compiler -
+# there is no toolchain to drive it with either, since Go itself is not
+# installed.
+#
+# That layer was also why a host could not share storage between images. apk
+# resolves against an index that moves, so the layer digest differed on every
+# build and no two images shared it: a host keeping one image per deployed
+# commit stored a private 273MB copy each time. 68 of them filled the disk
+# and the next deployment could not pull.
+#
+# libc6-compat stays. Nothing measured needs it - the binary CI produces is
+# statically linked, and a container built without libc6-compat resolves a
+# hostname and opens a database connection exactly as one built with it - but
+# it is half a megabyte and it covers a ./main that was linked dynamically,
+# which this Dockerfile has no way to check.
+RUN apk add --no-cache ca-certificates tzdata libc6-compat
 ENV TZ Asia/Shanghai
 
 COPY ./main /main
@@ -15,4 +31,4 @@ COPY ./config/settings.demo.yml /config/settings.yml
 COPY ./go-admin-db.db /go-admin-db.db
 EXPOSE 8000
 RUN  chmod +x /main
-CMD ["/main","server","-c", "/config/settings.yml"]
+CMD ["/main","server","-c", "/config/settings.yml"]

Makefile

@@ -15,7 +15,16 @@ build-sqlite:
 # make run
 run:
     # delete go-admin-api container
-	@if [ $(shell docker ps -aq --filter name=go-admin --filter publish=8000) ]; then docker rm -f go-admin; fi
+    #
+    # stop then rm, rather than `rm -f`. The force flag kills a running
+    # container with SIGKILL and no grace at all, so restarting locally cut
+    # short every shutdown this application does - the drain window was never
+    # once reached on a developer's machine. --timeout has to cover
+    # extend.shutdown's drain + server + cleanup; checksilent's
+    # docker-stop-cuts-shutdown-short check compares it against
+    # config/settings.yml. On a container that has already stopped, stop is a
+    # no-op and the removal is unchanged.
+	@if [ $(shell docker ps -aq --filter name=go-admin --filter publish=8000) ]; then docker stop --timeout 30 go-admin && docker rm go-admin; fi
 
     # 启动方法一 run go-admin-api container  docker-compose 启动方式
     # 进入到项目根目录 执行 make run 命令
@@ -45,6 +54,18 @@ stop:
 test:
 	go test -race -cover ./...
 
+# The end-to-end install, which `test` above cannot reach: test/e2e-apporder
+# is its own module, so `./...` in this one does not include it. It builds a
+# go-admin binary with the example application linked in and drives
+# `migrate install` / `migrate uninstall` against a real database.
+#
+# Its own target rather than a line in the CI workflow, so the one thing in
+# the build that exercises installing an application is also the one thing
+# somebody can run before pushing.
+.PHONY: test-e2e
+test-e2e:
+	cd test/e2e-apporder && go test ./... -count=1
+
 # Reports the failures that do not announce themselves - see
 # tools/checksilent. Exits non-zero on an ERROR; the one WARN-level check
 # prints and does not fail the build.
@@ -59,6 +80,23 @@ else
 	go run ./tools/checksilent
 endif
 
+# gofmt as a gate, not a rewrite. CI cannot commit, and a target that quietly
+# reformats hides what it touched, so this reports and fails instead. `gofmt -l`
+# prints the files it would rewrite and nothing at all when there are none, so
+# that list is both the failure message and the instructions for fixing it.
+#
+# The tree reached zero unformatted files once; without something holding it
+# there it drifts back, which is how the previous batch grew to 26 files -
+# mostly a missing newline at the end of the file, which no reviewer notices.
+.PHONY: fmt-check
+fmt-check:
+	@unformatted=$$(gofmt -l .); \
+	if [ -n "$$unformatted" ]; then \
+		echo "gofmt would rewrite these files. Run 'gofmt -w .' and commit the result:"; \
+		echo "$$unformatted"; \
+		exit 1; \
+	fi
+
 #.PHONY: docker
 #docker:
 #	docker build . -t go-admin:latest

README.Zh-cn.md

@@ -277,15 +277,11 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/ninstein" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/580303?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/kikiyou" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17959053?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/horizonzy" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/22524871?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Cassuis" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/48005724?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/hqcchina" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/5179057?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/nodece" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/16235121?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stephenzhang0713" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/18169290?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/zhouxixi-dev" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/100399679?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/Jalins" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/31172582?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/wkf928592" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6063351?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxxiong6" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6983441?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Silicon-He" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52478309?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/GizmoOAO" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20385106?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/bestgopher" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/36840497?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxb1207" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20775558?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
@@ -299,8 +295,6 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/infnan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38274826?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/d1y" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/45585937?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/qlijin" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/515900?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/logtous
-" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/88697234?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stepway
 " ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9927079?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/NaturalGao

README.ja-JP.md

@@ -277,15 +277,11 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/ninstein" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/580303?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/kikiyou" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17959053?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/horizonzy" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/22524871?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Cassuis" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/48005724?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/hqcchina" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/5179057?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/nodece" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/16235121?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stephenzhang0713" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/18169290?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/zhouxixi-dev" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/100399679?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/Jalins" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/31172582?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/wkf928592" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6063351?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxxiong6" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6983441?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Silicon-He" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52478309?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/GizmoOAO" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20385106?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/bestgopher" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/36840497?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxb1207" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20775558?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
@@ -299,8 +295,6 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/infnan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38274826?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/d1y" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/45585937?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/qlijin" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/515900?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/logtous
-" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/88697234?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stepway
 " ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9927079?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/NaturalGao

README.md

@@ -263,15 +263,11 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/ninstein" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/580303?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/kikiyou" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17959053?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/horizonzy" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/22524871?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Cassuis" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/48005724?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/hqcchina" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/5179057?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/nodece" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/16235121?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stephenzhang0713" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/18169290?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/zhouxixi-dev" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/100399679?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/Jalins" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/31172582?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/wkf928592" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6063351?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxxiong6" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6983441?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Silicon-He" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52478309?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/GizmoOAO" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20385106?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/bestgopher" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/36840497?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxb1207" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20775558?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
@@ -285,8 +281,6 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/infnan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38274826?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/d1y" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/45585937?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/qlijin" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/515900?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/logtous
-" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/88697234?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stepway
 " ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9927079?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/NaturalGao

README.zh-TW.md

@@ -277,15 +277,11 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/ninstein" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/580303?v=4&h=60&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/kikiyou" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/17959053?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/horizonzy" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/22524871?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Cassuis" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/48005724?s=64&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/hqcchina" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/5179057?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/nodece" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/16235121?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stephenzhang0713" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/18169290?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/zhouxixi-dev" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/100399679?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/Jalins" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/31172582?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/wkf928592" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6063351?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxxiong6" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/6983441?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/Silicon-He" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/52478309?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/GizmoOAO" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20385106?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/bestgopher" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/36840497?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/wxb1207" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/20775558?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
@@ -299,8 +295,6 @@ pnpm dev
 <span style="margin: 0 5px;" ><a href="https://github.com/infnan" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/38274826?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/d1y" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/45585937?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/qlijin" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/515900?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
-<span style="margin: 0 5px;" ><a href="https://github.com/logtous
-" ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/88697234?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/stepway
 " ><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/9927079?s=60&v=4&w=60&fit=cover&mask=circle&maxage=7d" /></a></span>
 <span style="margin: 0 5px;" ><a href="https://github.com/NaturalGao

app/admin/apis/sys_api.go

@@ -3,9 +3,9 @@ package apis
 import (
 	"github.com/gin-gonic/gin"
 	"github.com/gin-gonic/gin/binding"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
 	_ "github.com/go-admin-team/go-admin-core/v2/response"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 
 	"go-admin/app/admin/models"
 	"go-admin/app/admin/service"
@@ -145,4 +145,4 @@ func (e SysApi) DeleteSysApi(c *gin.Context) {
 		return
 	}
 	e.OK(req.GetId(), "删除成功")
-}
+}

app/admin/apis/sys_dict_data.go

@@ -3,9 +3,9 @@ package apis
 import (
 	"github.com/gin-gonic/gin"
 	"github.com/gin-gonic/gin/binding"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
 	_ "github.com/go-admin-team/go-admin-core/v2/response"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"go-admin/app/admin/models"
 
 	"go-admin/app/admin/service"
@@ -216,5 +216,5 @@ func (e SysDictData) GetAll(c *gin.Context) {
 		l = append(l, d)
 	}
 
-	e.OK(l,"查询成功")
+	e.OK(l, "查询成功")
 }

app/admin/apis/sys_dict_type.go

@@ -4,9 +4,9 @@ import (
 	"fmt"
 	"github.com/gin-gonic/gin"
 	"github.com/gin-gonic/gin/binding"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
 	_ "github.com/go-admin-team/go-admin-core/v2/response"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"go-admin/app/admin/models"
 
 	"go-admin/app/admin/service"
@@ -31,7 +31,7 @@ type SysDictType struct {
 // @Security Bearer
 func (e SysDictType) GetPage(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeGetPageReq{}
+	req := dto.SysDictTypeGetPageReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.Form).
@@ -62,7 +62,7 @@ func (e SysDictType) GetPage(c *gin.Context) {
 // @Security Bearer
 func (e SysDictType) Get(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeGetReq{}
+	req := dto.SysDictTypeGetReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, nil).
@@ -82,7 +82,7 @@ func (e SysDictType) Get(c *gin.Context) {
 	e.OK(object, "查询成功")
 }
 
-//Insert 字典类型创建
+// Insert 字典类型创建
 // @Summary 添加字典类型
 // @Description 获取JSON
 // @Tags 字典类型
@@ -94,7 +94,7 @@ func (e SysDictType) Get(c *gin.Context) {
 // @Security Bearer
 func (e SysDictType) Insert(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeInsertReq{}
+	req := dto.SysDictTypeInsertReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON).
@@ -109,7 +109,7 @@ func (e SysDictType) Insert(c *gin.Context) {
 	err = s.Insert(&req)
 	if err != nil {
 		e.Logger.Error(err)
-		e.Error(500, err,fmt.Sprintf(" 创建字典类型失败，详情：%s", err.Error()))
+		e.Error(500, err, fmt.Sprintf(" 创建字典类型失败，详情：%s", err.Error()))
 		return
 	}
 	e.OK(req.GetId(), "创建成功")
@@ -127,7 +127,7 @@ func (e SysDictType) Insert(c *gin.Context) {
 // @Security Bearer
 func (e SysDictType) Update(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeUpdateReq{}
+	req := dto.SysDictTypeUpdateReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON, nil).
@@ -157,7 +157,7 @@ func (e SysDictType) Update(c *gin.Context) {
 // @Security Bearer
 func (e SysDictType) Delete(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeDeleteReq{}
+	req := dto.SysDictTypeDeleteReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON, nil).
@@ -189,7 +189,7 @@ func (e SysDictType) Delete(c *gin.Context) {
 // @Security Bearer
 func (e SysDictType) GetAll(c *gin.Context) {
 	s := service.SysDictType{}
-	req :=dto.SysDictTypeGetPageReq{}
+	req := dto.SysDictTypeGetPageReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.Form).
@@ -207,4 +207,4 @@ func (e SysDictType) GetAll(c *gin.Context) {
 		return
 	}
 	e.OK(list, "查询成功")
-}
+}

app/admin/apis/sys_login_log.go

@@ -29,7 +29,7 @@ type SysLoginLog struct {
 // @Security Bearer
 func (e SysLoginLog) GetPage(c *gin.Context) {
 	s := service.SysLoginLog{}
-	req :=dto.SysLoginLogGetPageReq{}
+	req := dto.SysLoginLogGetPageReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.Form).
@@ -60,7 +60,7 @@ func (e SysLoginLog) GetPage(c *gin.Context) {
 // @Security Bearer
 func (e SysLoginLog) Get(c *gin.Context) {
 	s := service.SysLoginLog{}
-	req :=dto.SysLoginLogGetReq{}
+	req := dto.SysLoginLogGetReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req).
@@ -90,7 +90,7 @@ func (e SysLoginLog) Get(c *gin.Context) {
 // @Security Bearer
 func (e SysLoginLog) Delete(c *gin.Context) {
 	s := service.SysLoginLog{}
-	req :=dto.SysLoginLogDeleteReq{}
+	req := dto.SysLoginLogDeleteReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON, nil).
@@ -107,4 +107,4 @@ func (e SysLoginLog) Delete(c *gin.Context) {
 		return
 	}
 	e.OK(req.GetId(), "删除成功")
-}
+}

app/admin/apis/sys_opera_log.go

@@ -65,7 +65,7 @@ func (e SysOperaLog) GetPage(c *gin.Context) {
 // @Security Bearer
 func (e SysOperaLog) Get(c *gin.Context) {
 	s := new(service.SysOperaLog)
-	req :=dto.SysOperaLogGetReq{}
+	req := dto.SysOperaLogGetReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, nil).
@@ -96,7 +96,7 @@ func (e SysOperaLog) Get(c *gin.Context) {
 // @Security Bearer
 func (e SysOperaLog) Delete(c *gin.Context) {
 	s := new(service.SysOperaLog)
-	req :=dto.SysOperaLogDeleteReq{}
+	req := dto.SysOperaLogDeleteReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON).
@@ -111,7 +111,7 @@ func (e SysOperaLog) Delete(c *gin.Context) {
 	err = s.Remove(&req)
 	if err != nil {
 		e.Logger.Error(err)
-		e.Error(500,err, fmt.Sprintf("删除失败！错误详情：%s", err.Error()))
+		e.Error(500, err, fmt.Sprintf("删除失败！错误详情：%s", err.Error()))
 		return
 	}
 	e.OK(req.GetId(), "删除成功")

app/admin/apis/sys_post.go

@@ -2,12 +2,12 @@ package apis
 
 import (
 	"fmt"
-	
+
 	"github.com/gin-gonic/gin"
 	"github.com/gin-gonic/gin/binding"
-	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"github.com/go-admin-team/go-admin-core/v2/jwtauth/user"
 	_ "github.com/go-admin-team/go-admin-core/v2/response"
+	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 
 	"go-admin/app/admin/models"
 	"go-admin/app/admin/service"
@@ -31,7 +31,7 @@ type SysPost struct {
 // @Security Bearer
 func (e SysPost) GetPage(c *gin.Context) {
 	s := service.SysPost{}
-	req :=dto.SysPostPageReq{}
+	req := dto.SysPostPageReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.Form).
@@ -65,7 +65,7 @@ func (e SysPost) GetPage(c *gin.Context) {
 // @Security Bearer
 func (e SysPost) Get(c *gin.Context) {
 	s := service.SysPost{}
-	req :=dto.SysPostGetReq{}
+	req := dto.SysPostGetReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, nil).
@@ -99,7 +99,7 @@ func (e SysPost) Get(c *gin.Context) {
 // @Security Bearer
 func (e SysPost) Insert(c *gin.Context) {
 	s := service.SysPost{}
-	req :=dto.SysPostInsertReq{}
+	req := dto.SysPostInsertReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON).
@@ -131,7 +131,7 @@ func (e SysPost) Insert(c *gin.Context) {
 // @Security Bearer
 func (e SysPost) Update(c *gin.Context) {
 	s := service.SysPost{}
-	req :=dto.SysPostUpdateReq{}
+	req := dto.SysPostUpdateReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON, nil).
@@ -163,7 +163,7 @@ func (e SysPost) Update(c *gin.Context) {
 // @Security Bearer
 func (e SysPost) Delete(c *gin.Context) {
 	s := service.SysPost{}
-	req :=dto.SysPostDeleteReq{}
+	req := dto.SysPostDeleteReq{}
 	err := e.MakeContext(c).
 		MakeOrm().
 		Bind(&req, binding.JSON).
@@ -181,4 +181,4 @@ func (e SysPost) Delete(c *gin.Context) {
 		return
 	}
 	e.OK(req.GetId(), "删除成功")
-}
+}

app/admin/apis/sys_user.go

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

app/admin/models/sys_app.go

@@ -0,0 +1,106 @@
+package models
+
+import (
+	"time"
+
+	"go-admin/common/models"
+)
+
+// The values sys_app.status takes.
+//
+// Three states rather than a single "installed", because an install that
+// stopped partway has to be an observable row rather than the absence of one:
+// the versions an app installs are separate migration files, and on MySQL a
+// DDL statement commits the transaction around it - taking an outer
+// transaction and every savepoint under it with it - so they cannot be
+// wrapped in one.
+//
+// AppInstalling is also what a row reads as after the process was killed
+// mid-install, which is why it is not treated as "installed" by anything.
+const (
+	AppInstalling = 1
+	AppInstalled  = 2
+	AppFailed     = 3
+)
+
+// SysApp is the sys_app row model: one row per installed application (PRD
+// 008 F2). It deliberately does not embed models.ModelTime - see the design
+// doc (docs-prd/008-应用清单与安装器/数据库变更.md) §1.1 for why an
+// installed-app registry does not need the millisecond soft-delete marker
+// every other sys_* table follows. Uninstalling an app deletes its row
+// outright; a later reinstall creates a fresh one.
+type SysApp struct {
+	models.Model // Id int, primary key, autoincrement
+
+	// AppCode is the app.Manifest.Code / migration.ForApp / seed.SeedMenus
+	// identity, already lower-cased by migration.NormalizeAppCode before
+	// anything reaches this table. Unique: row existence alone answers G2
+	// ("is app X installed").
+	AppCode string `json:"appCode" gorm:"type:varchar(64);not null;uniqueIndex:uk_sys_app_app_code;comment:app code"`
+
+	Name string `json:"name" gorm:"size:128;not null;comment:display name, from Manifest.Name"`
+	// Version is the version this row currently reflects - attempted or
+	// confirmed, disambiguated by Status. It does not drive which
+	// migrations run next; sys_migration's per-version rows do that (see
+	// design doc §1.5's resume flow). This field is descriptive, refreshed
+	// from the manifest on every install/upgrade/resume attempt.
+	Version     string `json:"version" gorm:"size:32;not null;comment:version this row currently reflects, see Status"`
+	Description string `json:"description" gorm:"size:255;not null;default:'';comment:from Manifest.Description"`
+	Author      string `json:"author" gorm:"size:128;not null;default:'';comment:from Manifest.Author"`
+
+	// Requires is a comma-separated list of app codes this app declared as
+	// dependencies (Manifest.Requires). Stored as plain VARCHAR CSV, not
+	// JSON - see design doc §1.3 for why. F8 (P1) is what validates and
+	// orders on this; this batch only stores what the manifest declared.
+	Requires string `json:"requires" gorm:"size:255;not null;default:'';comment:declared dependency app codes, comma separated"`
+
+	// Pricing/License are reserved passthrough fields (PRD 003; PRD 008
+	// open question 1). This batch stores whatever the manifest carries and
+	// does not interpret either one.
+	Pricing string `json:"pricing" gorm:"size:64;not null;default:'';comment:reserved, not interpreted by this batch"`
+	License string `json:"license" gorm:"size:64;not null;default:'';comment:reserved, not interpreted by this batch"`
+
+	// Status: 1=installing 2=installed 3=failed. Three states, not a
+	// single "1=installed", because a partial, stuck install has to be an
+	// observable row rather than "the row doesn't exist yet" - see design
+	// doc §1.5 for why cross-migration-file atomicity is not available on
+	// MySQL (implicit commit on DDL).
+	Status int `json:"status" gorm:"size:4;not null;default:1;comment:1=installing 2=installed 3=failed"`
+
+	// FailedVersion and LastError are DIAGNOSTIC TEXT ONLY - what a human
+	// looking at this row is told about the last failure, nothing more. No
+	// code anywhere may read either one to decide what to do next.
+	//
+	// The question "where should a resume pick up" has exactly one
+	// authoritative answer, and it is not these two columns: subtract
+	// sys_migration's applied rows for this app_code from what the app's
+	// own compiled-in code has registered (migration.Snapshot()/ForApp -
+	// the same set F7's `migrate status` already walks). That answer can
+	// never go stale, because it is not stored anywhere to go stale - it is
+	// recomputed from sys_migration every time it is asked. FailedVersion
+	// is a snapshot of what that computation returned at the moment of
+	// failure, kept only so an operator does not have to go find the
+	// process's logs; if it and a fresh recomputation from sys_migration
+	// ever disagree, sys_migration is right and this column is stale, by
+	// definition, and nothing should ever notice or care except a human
+	// reading the row.
+	FailedVersion string `json:"failedVersion" gorm:"size:64;not null;default:'';comment:diagnostic snapshot only, not a judgment basis; meaningful only when status=3"`
+	LastError     string `json:"lastError" gorm:"size:255;not null;default:'';comment:diagnostic text only, not a judgment basis; meaningful only when status=3"`
+
+	// InstalledAt is when this app first reached status=installed - set
+	// once, never moved by a later upgrade (see design doc §1.4). Nullable,
+	// unlike every other column here: a row can exist before it has a
+	// value (a fresh install starts at status=installing). This is not the
+	// deleted_at problem 1786700003000_soft_delete_marker.go fixed - that
+	// column sat inside a unique index, where NULL <> NULL let two live
+	// rows coexist under the same key. InstalledAt is in no index at all,
+	// so nullability here opens no such hole.
+	InstalledAt *time.Time `json:"installedAt" gorm:"comment:first successful install time; null until status first reaches installed"`
+	UpdatedAt   time.Time  `json:"updatedAt" gorm:"comment:last updated time"`
+
+	models.ControlBy // CreateBy/UpdateBy: which operator triggered the attempt
+}
+
+func (*SysApp) TableName() string {
+	return "sys_app"
+}

app/admin/models/sys_app_casbin_grant.go

@@ -0,0 +1,43 @@
+package models
+
+import "time"
+
+// SysAppCasbinGrant is a ledger of casbin_rule rows an app install created,
+// keyed by the exact natural key casbin_rule itself is unique on. It exists
+// because casbin_rule is not a table this project owns (see design doc
+// docs-prd/008-应用清单与安装器/数据库变更.md §2.2): we cannot add an
+// app_code column to it without that column being silently zeroed the first
+// time anything calls the gorm-adapter's SavePolicy/SavePolicyCtx. Recording
+// the natural key here, instead of a foreign key into casbin_rule, is also
+// what survives SysRole.Update's RemoveFilteredPolicy+re-add cycle for a
+// role's policies (app/admin/service/sys_role.go): that cycle replaces the
+// underlying row (a new auto-increment ID) but reproduces the same
+// (ptype,v0,v1,v2) tuple from the same sys_menu/sys_api data, so a
+// natural-key match here still finds it. What it does not survive is the
+// role being renamed, or the tuple being rebuilt from a completely different
+// source (a future SavePolicy call from outside this seeder) - in both cases
+// the match legitimately fails, and business rule 3 says the uninstaller
+// should report and skip, not delete something else that happens to look
+// the same.
+type SysAppCasbinGrant struct {
+	Id int `json:"id" gorm:"primaryKey;autoIncrement"`
+
+	AppCode string `json:"appCode" gorm:"type:varchar(64);not null;index:idx_sys_app_casbin_grant_app_code;comment:app code that created this grant"`
+
+	// Column widths mirror gorm-adapter's own CasbinRule struct exactly, so
+	// a value that fits into casbin_rule always fits here, and the unique
+	// index below matches the one createTable() puts on casbin_rule itself.
+	Ptype string `json:"ptype" gorm:"size:100;not null;uniqueIndex:uk_sys_app_casbin_grant_rule;comment:casbin ptype, 'p' today"`
+	V0    string `json:"v0" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:role_key at grant time"`
+	V1    string `json:"v1" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:api path"`
+	V2    string `json:"v2" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:http method"`
+	V3    string `json:"v3" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:unused today"`
+	V4    string `json:"v4" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:unused today"`
+	V5    string `json:"v5" gorm:"size:100;not null;default:'';uniqueIndex:uk_sys_app_casbin_grant_rule;comment:unused today"`
+
+	CreatedAt time.Time `json:"createdAt" gorm:"comment:when this grant was recorded"`
+}
+
+func (*SysAppCasbinGrant) TableName() string {
+	return "sys_app_casbin_grant"
+}

app/admin/models/sys_menu.go

@@ -32,6 +32,30 @@ type SysMenu struct {
 	// 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"`
+	// SeedCode is the raw seed.MenuSpec.Code this row was created from, kept
+	// so seedMenuTree can ask "did I already write this node" without
+	// relying on MenuName's PascalCase concatenation, which is not
+	// injective (see design doc §1.6). Nullable, unlike AppCode: every row
+	// seed.SeedMenus writes sets a real value, but every pre-existing row -
+	// the host's own hand-placed menus, and every app-seeded row written
+	// before this column existed - has none, and there is no way to
+	// backfill one that means anything. NULL is what lets an unbounded
+	// number of those coexist under the same app_code without tripping the
+	// unique index below: the database never treats two NULLs as equal, so
+	// only rows that do carry a real code participate in the uniqueness
+	// check at all.
+	// uk_sys_menu_app_seed_code_del is created by the migration, not from
+	// this tag, and deliberately: it covers (app_code, seed_code,
+	// deleted_at), and this struct cannot say so. A named uniqueIndex tag
+	// puts every field carrying that name into one index, and deleted_at
+	// comes from the shared ModelTime embed, which no single model can add a
+	// tag to. Naming it here anyway declared a unique index on seed_code
+	// alone under the same name - stricter than the real one, forbidding two
+	// applications from both having a "dir" node - and AutoMigrate on this
+	// model would have created that one first, after which the migration's
+	// HasIndex guard finds the name taken and leaves the wrong index in
+	// place.
+	SeedCode *string `json:"seedCode" gorm:"size:64;comment:raw MenuSpec.Code, null for rows not written through SeedMenus"`
 	models.ControlBy
 	models.ModelTime
 }

app/admin/models/sys_menu_seed_code_test.go

@@ -0,0 +1,49 @@
+package models
+
+import (
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func ptr(s string) *string { return &s }
+
+// uk_sys_menu_app_seed_code_del covers (app_code, seed_code, deleted_at) and
+// is created by 1786700008000, not from a struct tag. It cannot come from a
+// tag: a named uniqueIndex collects every field carrying that name, and
+// deleted_at lives in the shared ModelTime embed that no single model can tag.
+//
+// Naming it on SeedCode alone anyway produced a unique index on seed_code by
+// itself under the same name - stricter than the real one - and AutoMigrate
+// here would create that one, after which the migration's HasIndex guard
+// finds the name taken and leaves the wrong index in place. Nothing in
+// production AutoMigrates this model (the initial table migration uses a
+// frozen snapshot that has neither column), which is why this never showed up
+// as a broken database; it showed up the first time a test built the schema
+// from the live model and seeded two applications.
+func TestSysMenuDeclaresNoSeedCodeIndexOfItsOwn(t *testing.T) {
+	db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(&SysMenu{}); err != nil {
+		t.Fatalf("automigrate: %v", err)
+	}
+	if db.Migrator().HasIndex(&SysMenu{}, "uk_sys_menu_app_seed_code_del") {
+		t.Error("AutoMigrate created uk_sys_menu_app_seed_code_del from a tag; " +
+			"the migration's HasIndex guard will now skip the composite index it should create")
+	}
+
+	// Two applications, the same seed code. The real index allows it because
+	// app_code is part of the key; an index on seed_code alone does not.
+	for _, app := range []string{"order", "crm"} {
+		row := SysMenu{MenuName: app + "Dir", AppCode: app, SeedCode: ptr("dir")}
+		if err := db.Create(&row).Error; err != nil {
+			t.Fatalf("%s could not use the seed code \"dir\": %v", app, err)
+		}
+	}
+}

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/router/sys_dept.go

@@ -29,4 +29,4 @@ func registerSysDeptRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddle
 		r1.GET("/deptTree", api.Get2Tree)
 	}
 
-}
+}

app/admin/router/sys_login_log.go

@@ -21,4 +21,4 @@ func registerSysLoginLogRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMi
 		r.GET("/:id", api.Get)
 		r.DELETE("", api.Delete)
 	}
-}
+}

app/admin/router/sys_menu.go

@@ -30,4 +30,4 @@ func registerSysMenuRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddle
 		//r1.GET("/menuids", api.GetMenuIDS)
 	}
 
-}
+}

app/admin/router/sys_opera_log.go

@@ -20,4 +20,4 @@ func registerSysOperaLogRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMi
 		r.GET("/:id", api.Get)
 		r.DELETE("", api.Delete)
 	}
-}
+}

app/admin/router/sys_post.go

@@ -22,4 +22,4 @@ func registerSyPostRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddlew
 		r.PUT("/:id", api.Update)
 		r.DELETE("", api.Delete)
 	}
-}
+}

app/admin/router/sys_user.go

@@ -36,4 +36,4 @@ func registerSysUserRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddle
 	{
 		v1auth.GET("/getinfo", api.GetInfo)
 	}
-}
+}

app/admin/service/dto/sys_dept.go

@@ -7,15 +7,15 @@ import (
 
 // SysDeptGetPageReq 列表或者搜索使用结构体
 type SysDeptGetPageReq struct {
-	DeptId         int    `form:"deptId" search:"type:exact;column:dept_id;table:sys_dept" comment:"id"`       //id
-	ParentId       int    `form:"parentId" search:"type:exact;column:parent_id;table:sys_dept" comment:"上级部门"` //上级部门
-	DeptPath       string `form:"deptPath" search:"type:exact;column:dept_path;table:sys_dept" comment:""`     //路径
-	DeptName       string `form:"deptName" search:"type:exact;column:dept_name;table:sys_dept" comment:"部门名称"` //部门名称
-	Sort           int    `form:"sort" search:"type:exact;column:sort;table:sys_dept" comment:"排序"`            //排序
-	Leader         string `form:"leader" search:"type:exact;column:leader;table:sys_dept" comment:"负责人"`       //负责人
-	Phone          string `form:"phone" search:"type:exact;column:phone;table:sys_dept" comment:"手机"`          //手机
-	Email          string `form:"email" search:"type:exact;column:email;table:sys_dept" comment:"邮箱"`          //邮箱
-	Status         string `form:"status" search:"type:exact;column:status;table:sys_dept" comment:"状态"`        //状态
+	DeptId   int    `form:"deptId" search:"type:exact;column:dept_id;table:sys_dept" comment:"id"`       //id
+	ParentId int    `form:"parentId" search:"type:exact;column:parent_id;table:sys_dept" comment:"上级部门"` //上级部门
+	DeptPath string `form:"deptPath" search:"type:exact;column:dept_path;table:sys_dept" comment:""`     //路径
+	DeptName string `form:"deptName" search:"type:exact;column:dept_name;table:sys_dept" comment:"部门名称"` //部门名称
+	Sort     int    `form:"sort" search:"type:exact;column:sort;table:sys_dept" comment:"排序"`            //排序
+	Leader   string `form:"leader" search:"type:exact;column:leader;table:sys_dept" comment:"负责人"`       //负责人
+	Phone    string `form:"phone" search:"type:exact;column:phone;table:sys_dept" comment:"手机"`          //手机
+	Email    string `form:"email" search:"type:exact;column:email;table:sys_dept" comment:"邮箱"`          //邮箱
+	Status   string `form:"status" search:"type:exact;column:status;table:sys_dept" comment:"状态"`        //状态
 }
 
 func (m *SysDeptGetPageReq) GetNeedSearch() interface{} {

app/admin/service/dto/sys_login_log.go

@@ -54,4 +54,4 @@ type SysLoginLogDeleteReq struct {
 
 func (s *SysLoginLogDeleteReq) GetId() interface{} {
 	return s.Ids
-}
+}

app/admin/service/seed.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"strconv"
 	"strings"
+	"time"
 
 	"gorm.io/gorm"
 
@@ -76,7 +77,7 @@ func (adminSeeder) SeedMenus(tx *gorm.DB, appCode string, menus []seed.MenuSpec,
 	if len(menuIDs) == 0 && len(apiRows) == 0 {
 		return nil
 	}
-	return grantToAdminRole(tx, menuIDs, apiRows)
+	return grantToAdminRole(tx, appCode, menuIDs, apiRows)
 }
 
 // seedApis writes one sys_api row per ApiSpec and returns them keyed by
@@ -90,6 +91,23 @@ func (adminSeeder) SeedMenus(tx *gorm.DB, appCode string, menus []seed.MenuSpec,
 // 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.
+//
+// The natural key is (app_code, path, action) - the same three columns
+// 1786700002000_remove_refresh_token_api.go already used to identify a
+// single API by hand, and the ones 1786700008000_seed_natural_keys.go put a
+// unique index on. Before inserting, this looks for a live row (deleted_at
+// = 0, applied automatically by the soft-delete plugin on every query
+// against models.SysApi) already holding that key and reuses it instead of
+// inserting a second one - see the design doc §1.6: a migration retried
+// after a partial failure previously re-ran this as a bare tx.Create and
+// produced duplicate rows on the demo site.
+//
+// Unlike seedMenuTree's reuse branch, this one has nothing left to repair
+// after finding an existing row: models.SysApi carries no association
+// (nothing like SysMenu's many2many SysApi field) and this function writes
+// nothing beyond the row itself - no second statement comparable to
+// seedMenuTree's paths UPDATE follows tx.Create below. An interrupted retry
+// can therefore only ever find this row complete or not find it at all.
 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))
@@ -102,6 +120,19 @@ func seedApis(tx *gorm.DB, appCode string, apis []seed.ApiSpec) (map[string]mode
 		}
 		seen[a.Code] = true
 
+		var existing models.SysApi
+		err := tx.Where("app_code = ? AND path = ? AND action = ?", appCode, a.Path, a.Method).
+			First(&existing).Error
+		switch {
+		case err == nil:
+			rows[a.Code] = existing
+			continue
+		case errors.Is(err, gorm.ErrRecordNotFound):
+			// Not seen yet; fall through to insert it.
+		default:
+			return nil, fmt.Errorf("api %q: checking for an existing row: %w", a.Code, err)
+		}
+
 		row := models.SysApi{
 			Handle:  a.Handle,
 			Title:   a.Title,
@@ -153,6 +184,12 @@ func seedMenuTree(tx *gorm.DB, appCode string, specs []seed.MenuSpec, apiRows ma
 				continue
 			}
 
+			// Resolved before the idempotency check below, whether or not
+			// this spec's own row turns out to already exist: repairing an
+			// existing-but-incomplete row's paths needs the parent's
+			// already-resolved Paths exactly as much as creating a fresh
+			// row does (see repairExistingMenu), so both have to wait for
+			// it the same way.
 			var parentRow models.SysMenu
 			if s.Parent != "" {
 				parent, ok := created[s.Parent]
@@ -165,24 +202,42 @@ func seedMenuTree(tx *gorm.DB, appCode string, specs []seed.MenuSpec, apiRows ma
 				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,
+			// Idempotency check: does this node already have a row, from
+			// an earlier, possibly-interrupted attempt? The natural key is
+			// (app_code, seed_code) - menu_name's PascalCase concatenation
+			// is not injective and cannot be used for this (see menuName's
+			// doc comment and the design doc §1.6). Only a live row counts;
+			// the soft-delete plugin scopes deleted_at = 0 automatically on
+			// every query against models.SysMenu.
+			var existing models.SysMenu
+			found := false
+			err := tx.Where("app_code = ? AND seed_code = ?", appCode, s.Code).First(&existing).Error
+			switch {
+			case err == nil:
+				found = true
+			case errors.Is(err, gorm.ErrRecordNotFound):
+				// Nothing under the natural key. It may still be here from
+				// before seed_code existed, under the name that identified
+				// it then.
+				existing, found, err = adoptLegacyMenu(tx, appCode, s)
+				if err != nil {
+					return nil, fmt.Errorf("%q: %w", s.Code, err)
+				}
+			default:
+				return nil, fmt.Errorf("%q: checking for an existing row: %w", s.Code, err)
 			}
+			if found {
+				row, err := repairExistingMenu(tx, existing, appCode, s, parentRow, apiRows)
+				if err != nil {
+					return nil, fmt.Errorf("%q: repairing an existing row: %w", s.Code, err)
+				}
+				created[s.Code] = row
+				ids = append(ids, row.MenuId)
+				progressed = true
+				continue
+			}
+
+			row := menuRowFor(appCode, s, parentRow)
 			for _, code := range s.ApiCodes {
 				api, ok := apiRows[code]
 				if !ok {
@@ -205,11 +260,7 @@ func seedMenuTree(tx *gorm.DB, appCode string, specs []seed.MenuSpec, apiRows ma
 			// 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)
-			}
+			row.Paths = expectedPaths(row.MenuId, s.Parent, parentRow)
 			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)
@@ -226,6 +277,103 @@ func seedMenuTree(tx *gorm.DB, appCode string, specs []seed.MenuSpec, apiRows ma
 	return ids, nil
 }
 
+// expectedPaths is the materialized path a fresh insert of menuID under
+// parent (or at the root, if parent is "") computes - factored out so
+// repairExistingMenu can ask the same question about a row it did not just
+// create.
+func expectedPaths(menuID int, parent string, parentRow models.SysMenu) string {
+	if parent == "" {
+		return "/0/" + strconv.Itoa(menuID)
+	}
+	return parentRow.Paths + "/" + strconv.Itoa(menuID)
+}
+
+// repairExistingMenu brings a row seedMenuTree's idempotency check found up
+// to what a fresh insert of the same spec would have produced.
+//
+// A row can be found and still be incomplete: tx.Create's own association
+// write (the sys_menu_api_rule bindings from row.SysApi) and the paths
+// UPDATE that follows it are each their own statement, and design doc §1.5
+// establishes that nothing after the first DDL in a migration function can
+// be rolled back together - a process interrupted between the row insert
+// and either of those two steps leaves exactly this row: present, findable
+// by its natural key, but missing what makes it a working menu entry. A
+// retry that only checked "does the row exist" and stopped there would
+// report success while the sys_menu_api_rule binding stays missing (the
+// api is granted to no one) or paths stays empty (a materialized-path
+// break that orphans the rest of the subtree from the root) - as silent as
+// the duplicate-row defect the idempotency check itself was written to
+// close.
+//
+// Both checks are read-before-write, so a row that is already complete -
+// the ordinary case on every retry after the first successful one - causes
+// no writes at all: existing.Paths already equals what expectedPaths
+// computes, and the sys_menu_api_rule INSERT is itself guarded by
+// WHERE NOT EXISTS, the same idempotent-insert shape grantToAdminRole
+// already uses for sys_role_menu/casbin_rule. Never DELETEs an existing
+// binding to rebuild it - that is the FullSaveAssociations mistake
+// sys_role.go's SysRole.Update makes for sys_role_menu/casbin_rule
+// (app/admin/service/sys_role.go:148-153), the exact pattern this design
+// went out of its way to avoid for the tables that do use it.
+//
+// Insert-only cuts both ways, deliberately. A binding an administrator
+// added by hand through the menu management UI, for an api never in
+// s.ApiCodes at all, is never touched by this loop and survives every
+// later retry (TestSeedMenusPreservesAHandAddedBinding is the reproduction
+// case for the opposite mistake: delete-then-reinsert wipes it silently,
+// the same shape as sys_role_menu/casbin_rule getting zeroed by a role
+// edit, just with this code as the actor instead of the victim). The
+// converse case - a MenuSpec that used to list an ApiCode and no longer
+// does - is not handled here either, and that half is intentional rather
+// than an oversight: this loop only ever adds rows for codes the *current*
+// call's ApiCodes names, so a binding for a code an earlier version
+// granted and the current one dropped is left in place, stale. Reconciling
+// that is deleting something, which needs the same certainty about
+// ownership uninstall's design (see design doc §5) already requires -
+// this function has no way to tell "stale, from an older version of this
+// same app" apart from "hand-added, for a reason", and business rule 3
+// ("uninstall deletes only what it can attribute with certainty") applies
+// here just as much as it does there. Reconciling stale seed-driven
+// bindings, if it is ever wanted, belongs in the upgrade path with that
+// same ownership check - not silently inside every retry of every install.
+func repairExistingMenu(tx *gorm.DB, existing models.SysMenu, appCode string, s seed.MenuSpec, parentRow models.SysMenu, apiRows map[string]models.SysApi) (models.SysMenu, error) {
+	// Every column the spec decides, not just the two this used to touch. A
+	// menu whose parent was removed and reseeded kept parent_id pointing at
+	// the dead row while its paths named the new one, and the tree is built
+	// from parent_id - so the menu vanished from the sidebar with the
+	// migration reporting success. An application that renamed a menu or
+	// moved its component between versions had its change silently ignored
+	// for the same reason: nothing here wrote those columns.
+	want := menuRowFor(appCode, s, parentRow)
+	if err := tx.Model(&models.SysMenu{}).Where("menu_id = ?", existing.MenuId).
+		Select(specMenuFields).Updates(want).Error; err != nil {
+		return models.SysMenu{}, fmt.Errorf("bringing the row up to the spec: %w", err)
+	}
+	want.MenuId = existing.MenuId
+	want.Paths = existing.Paths
+	want.Visible, want.IsFrame = existing.Visible, existing.IsFrame
+
+	if err := repairPaths(tx, &want, s, parentRow); err != nil {
+		return models.SysMenu{}, err
+	}
+	existing = want
+
+	for _, code := range s.ApiCodes {
+		api, ok := apiRows[code]
+		if !ok {
+			return models.SysMenu{}, fmt.Errorf("ApiCodes references %q, which is not an ApiSpec.Code in this call", code)
+		}
+		if err := tx.Exec(
+			"INSERT INTO sys_menu_api_rule (sys_menu_menu_id, sys_api_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM sys_menu_api_rule WHERE sys_menu_menu_id = ? AND sys_api_id = ?)",
+			existing.MenuId, api.Id, existing.MenuId, api.Id,
+		).Error; err != nil {
+			return models.SysMenu{}, fmt.Errorf("binding %q: %w", code, err)
+		}
+	}
+
+	return existing, 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
@@ -278,7 +426,7 @@ func pascalCase(s string) string {
 // 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 {
+func grantToAdminRole(tx *gorm.DB, appCode string, 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) {
@@ -297,12 +445,177 @@ func grantToAdminRole(tx *gorm.DB, menuIDs []int, apiRows map[string]models.SysA
 	}
 
 	for _, a := range apiRows {
-		if err := tx.Exec(
+		res := 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 {
+		)
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			// The policy was already there, so this install did not create
+			// it and it is not this app's to take away. Leaving it out of
+			// the ledger is what makes an uninstall report it instead of
+			// deleting it.
+			//
+			// The two ways this can be wrong are not equally bad, which is
+			// what settles it. Under-recording leaves a policy behind and
+			// the uninstall says so, because a policy naming an app's own
+			// path with no ledger entry is exactly what it lists as an
+			// orphan. Over-recording deletes a grant somebody else made,
+			// silently. Between a visible leftover and an invisible
+			// deletion of somebody's authorization, take the leftover.
+			continue
+		}
+		if err := recordGrant(tx, appCode, role.RoleKey, a.Path, a.Action); err != nil {
 			return err
 		}
 	}
 	return nil
 }
+
+// recordGrant writes down that this application's install created one casbin
+// policy, keyed by the same tuple casbin_rule is unique on.
+//
+// A ledger rather than a column on casbin_rule, because casbin_rule is not
+// this project's table: the gorm adapter's SavePolicy truncates it and writes
+// it back from memory, which would drop any column added here, and
+// SysRole.Update replaces a role's policy rows wholesale. The tuple survives
+// both, because both rebuild it from the same sys_menu/sys_api data.
+//
+// Written with the same INSERT ... WHERE NOT EXISTS shape as the policy above
+// rather than a plain insert: the ledger's unique index covers the tuple
+// alone, so a duplicate would abort the whole seed instead of being the
+// no-op it should be.
+func recordGrant(tx *gorm.DB, appCode, roleKey, path, action string) error {
+	return tx.Exec(
+		"INSERT INTO sys_app_casbin_grant (app_code, ptype, v0, v1, v2, v3, v4, v5, created_at) "+
+			"SELECT ?, 'p', ?, ?, ?, '', '', '', ? WHERE NOT EXISTS "+
+			"(SELECT 1 FROM sys_app_casbin_grant WHERE ptype='p' AND v0=? AND v1=? AND v2=? AND v3='' AND v4='' AND v5='')",
+		appCode, roleKey, path, action, time.Now(), roleKey, path, action,
+	).Error
+}
+
+// specMenuFields are the sys_menu columns a MenuSpec decides, and the only
+// ones a reseed rewrites on a row that is already there.
+//
+// Visible and IsFrame are not in the list. They are seeding defaults the
+// application never expressed, so an administrator who hid a seeded menu
+// keeps it hidden. app_code and seed_code are not either: they are the
+// natural key the row was found by, and writing them back would be writing
+// what was just matched.
+var specMenuFields = []string{
+	"MenuName", "Title", "Icon", "Path", "MenuType",
+	"Permission", "ParentId", "Component", "Sort",
+}
+
+// menuRowFor is the row a MenuSpec describes. One definition, so the insert
+// path and the repair path cannot drift into disagreeing about what a spec
+// decides.
+func menuRowFor(appCode string, s seed.MenuSpec, parentRow models.SysMenu) models.SysMenu {
+	seedCode := s.Code
+	return 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. Only written when the row is created;
+		// see specMenuFields.
+		Visible:  "0",
+		IsFrame:  "1",
+		AppCode:  appCode,
+		SeedCode: &seedCode,
+	}
+}
+
+// repairPaths writes row.Paths, and moves whatever is underneath it.
+//
+// The subtree matters because it is not all in this call's specs: a menu an
+// administrator added under a seeded one keeps the old prefix, and nothing
+// else in the codebase would ever rewrite it. SysMenu.Update does the same
+// cascade for the same column when somebody moves a menu by hand.
+//
+// The predicate is the row itself or a row strictly under it, rather than
+// `paths LIKE old || '%'`, which also matches /0/10 when old is /0/1.
+func repairPaths(tx *gorm.DB, row *models.SysMenu, s seed.MenuSpec, parentRow models.SysMenu) error {
+	want := expectedPaths(row.MenuId, s.Parent, parentRow)
+	old := row.Paths
+	if old == want {
+		return nil
+	}
+	if old == "" {
+		// A row whose paths was never written - an interrupted create. It
+		// has no subtree to speak of, and `LIKE '/%'` would match the whole
+		// table.
+		if err := tx.Model(&models.SysMenu{}).Where("menu_id = ?", row.MenuId).
+			Update("paths", want).Error; err != nil {
+			return fmt.Errorf("writing paths: %w", err)
+		}
+		row.Paths = want
+		return nil
+	}
+
+	var subtree []models.SysMenu
+	if err := tx.Where("paths = ? OR paths LIKE ?", old, old+"/%").Find(&subtree).Error; err != nil {
+		return fmt.Errorf("reading the subtree under %s: %w", old, err)
+	}
+	for _, d := range subtree {
+		moved := want + strings.TrimPrefix(d.Paths, old)
+		if err := tx.Model(&models.SysMenu{}).Where("menu_id = ?", d.MenuId).
+			Update("paths", moved).Error; err != nil {
+			return fmt.Errorf("moving %d from %s to %s: %w", d.MenuId, d.Paths, moved, err)
+		}
+	}
+	row.Paths = want
+	return nil
+}
+
+// adoptLegacyMenu claims a row this application wrote before sys_menu had a
+// seed_code column, so a reseed repairs it instead of inserting a second copy
+// beside it.
+//
+// 1786700008000 added the column and left it NULL on every row already there,
+// which is right for the host's own hand-placed menus - there is nothing to
+// derive one from. An application's rows are in that population too, and for
+// those the value is derivable, because menu_name is what identified them
+// before the column existed. Without this the natural-key lookup misses them,
+// the seed inserts a duplicate, and the unique index cannot object: NULL
+// never collides.
+//
+// Ambiguity is refused rather than guessed. menuName concatenates two
+// pascalCase strings and pascalCase is not injective, so two specs can land
+// on one name; picking one of several rows would attach an application's
+// menu to whichever the database returned first.
+func adoptLegacyMenu(tx *gorm.DB, appCode string, s seed.MenuSpec) (models.SysMenu, bool, error) {
+	name := menuName(appCode, s.Code)
+	var rows []models.SysMenu
+	if err := tx.Where("app_code = ? AND menu_name = ? AND seed_code IS NULL", appCode, name).
+		Find(&rows).Error; err != nil {
+		return models.SysMenu{}, false, fmt.Errorf("looking for a row written before seed_code existed: %w", err)
+	}
+	switch len(rows) {
+	case 0:
+		return models.SysMenu{}, false, nil
+	case 1:
+	default:
+		return models.SysMenu{}, false, fmt.Errorf(
+			"%d rows carry menu_name %q with no seed_code; which of them belongs to %q cannot be decided here, because menuName is not reversible - reconcile them by hand",
+			len(rows), name, s.Code)
+	}
+
+	seedCode := s.Code
+	if err := tx.Model(&models.SysMenu{}).Where("menu_id = ?", rows[0].MenuId).
+		Update("seed_code", seedCode).Error; err != nil {
+		return models.SysMenu{}, false, fmt.Errorf("claiming the row written before seed_code existed: %w", err)
+	}
+	rows[0].SeedCode = &seedCode
+	return rows[0], true, nil
+}

app/admin/service/seed_test.go

@@ -1,13 +1,18 @@
 package service
 
 import (
+	"context"
 	"errors"
+	"fmt"
 	"strconv"
 	"strings"
+	"sync"
 	"testing"
+	"time"
 
 	"github.com/glebarez/sqlite"
 	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
 
 	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"
@@ -28,7 +33,14 @@ func newSeedTestDB(t *testing.T) *gorm.DB {
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
-	if err := db.AutoMigrate(&models.SysMenu{}, &models.SysApi{}, &models.SysRole{}); err != nil {
+	// sys_app_casbin_grant is where grantToAdminRole records which policies
+	// this install created, so an uninstall can tell them from the ones
+	// somebody granted by hand. In a real database it is created by
+	// 1786700007000, which is a framework migration and therefore runs ahead
+	// of every application's - version strings sort bare digits before any
+	// app-prefixed one.
+	if err := db.AutoMigrate(&models.SysMenu{}, &models.SysApi{}, &models.SysRole{},
+		&models.SysAppCasbinGrant{}); err != nil {
 		t.Fatalf("automigrate: %v", err)
 	}
 	if err := db.Exec(`CREATE TABLE casbin_rule (
@@ -289,3 +301,953 @@ func TestSeedMenusWithNothingRegisteredWritesNothing(t *testing.T) {
 		}
 	}
 }
+
+// newSeedTestDB's AutoMigrate builds a unique index on seed_code alone,
+// because SysMenu.SeedCode is the only field in the struct carrying the
+// uk_sys_menu_app_seed_code_del tag - app_code already carries a different,
+// non-unique index name of its own, and the embedded ModelTime's
+// DeletedAt (aliased from go-admin-core) cannot be given a third one. The
+// real migration (cmd/migrate/migration/version/1786700008000_seed_natural_keys.go)
+// never lets AutoMigrate touch this table for exactly that reason: it
+// builds the composite (app_code, seed_code, deleted_at) index by hand
+// instead. Reproduce that by hand here too, so a test that seeds two rows
+// sharing a seed_code under different deleted_at values sees what a real
+// install would, not gorm's narrower default.
+func useCompositeSeedCodeIndex(t *testing.T, db *gorm.DB) {
+	t.Helper()
+	if db.Migrator().HasIndex(&models.SysMenu{}, "uk_sys_menu_app_seed_code_del") {
+		if err := db.Migrator().DropIndex(&models.SysMenu{}, "uk_sys_menu_app_seed_code_del"); err != nil {
+			t.Fatalf("drop the single-column seed_code index: %v", err)
+		}
+	}
+	if err := db.Exec(
+		"CREATE UNIQUE INDEX uk_sys_menu_app_seed_code_del ON sys_menu (app_code, seed_code, deleted_at)",
+	).Error; err != nil {
+		t.Fatalf("create the composite seed_code index: %v", err)
+	}
+}
+
+// A retried migration - one that failed partway through and is run again,
+// or simply run twice by mistake - must not create a second sys_api or
+// sys_menu row for the same (appCode, natural key). This is the defect the
+// demo site hit in production: duplicate sys_menu/casbin_rule rows from a
+// bare tx.Create on a natural key nothing was checking.
+func TestSeedMenusIsIdempotentAcrossARetry(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	menus := []seed.MenuSpec{
+		{Code: "dir", Kind: contractmodels.Directory, Title: "Order", Sort: 10},
+		{Code: "list", Parent: "dir", Kind: contractmodels.Menu, Title: "Orders", Sort: 1, ApiCodes: []string{"list"}},
+	}
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"},
+	}
+
+	run := func() {
+		t.Helper()
+		if err := db.Transaction(func(tx *gorm.DB) error {
+			return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+		}); err != nil {
+			t.Fatalf("SeedMenus: %v", err)
+		}
+	}
+	run()
+	firstMenuIDs := allMenuIDs(t, db, "order")
+	firstApiIDs := allApiIDs(t, db, "order")
+
+	run() // the retry
+
+	if got := allMenuIDs(t, db, "order"); !sameIDs(got, firstMenuIDs) {
+		t.Errorf("sys_menu ids after retry = %v, want unchanged %v (a second call inserted new rows)", got, firstMenuIDs)
+	}
+	if got := allApiIDs(t, db, "order"); !sameIDs(got, firstApiIDs) {
+		t.Errorf("sys_api ids after retry = %v, want unchanged %v (a second call inserted new rows)", got, firstApiIDs)
+	}
+
+	assertRowCount(t, db, "sys_api", 1)
+	assertRowCount(t, db, "sys_menu", 2)
+	assertRowCount(t, db, "sys_menu_api_rule", 1)
+	assertRowCount(t, db, "sys_role_menu", 2)
+	assertRowCount(t, db, "casbin_rule", 1)
+}
+
+// Only a live row counts as "already written". A row a prior, unrelated
+// soft-delete already retired must not be reused - seedApis/seedMenuTree
+// have to insert a fresh one under the same natural key, the same way the
+// unique indexes 1786700008000_seed_natural_keys.go builds only bind live
+// rows.
+func TestSeedMenusOnlyReusesLiveRows(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	menus := []seed.MenuSpec{{Code: "dir", Kind: contractmodels.Directory, Title: "Order", Sort: 10}}
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	// Soft-delete both rows this first call wrote, as if an operator (or an
+	// earlier uninstall) had retired them, independently of this migration
+	// ever running again.
+	if err := db.Exec("UPDATE sys_menu SET deleted_at = 1").Error; err != nil {
+		t.Fatalf("soft-delete sys_menu: %v", err)
+	}
+	if err := db.Exec("UPDATE sys_api SET deleted_at = 1").Error; err != nil {
+		t.Fatalf("soft-delete sys_api: %v", err)
+	}
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus after soft-delete: %v", err)
+	}
+
+	// Two rows total: the soft-deleted original, plus a fresh one - not the
+	// dead row resurrected in place, and not left with zero live rows.
+	assertRowCount(t, db, "sys_menu", 2)
+	assertRowCount(t, db, "sys_api", 2)
+
+	var liveMenus, liveApis int64
+	db.Model(&models.SysMenu{}).Where("app_code = ?", "order").Count(&liveMenus)
+	db.Model(&models.SysApi{}).Where("app_code = ?", "order").Count(&liveApis)
+	if liveMenus != 1 {
+		t.Errorf("live sys_menu rows = %d, want 1", liveMenus)
+	}
+	if liveApis != 1 {
+		t.Errorf("live sys_api rows = %d, want 1", liveApis)
+	}
+}
+
+// app_code is part of the natural key, not a descriptive column alongside
+// it. Two applications that happen to register an identical (path, action)
+// or seed_code must each get their own row - reusing one app's row for
+// another's install would make an uninstall of the first delete a row the
+// second considers its own.
+func TestSeedMenusScopesTheNaturalKeyByAppCode(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	menus := []seed.MenuSpec{{Code: "dir", Kind: contractmodels.Directory, Title: "Dir", Sort: 10}}
+	apis := []seed.ApiSpec{{Code: "list", Title: "Shared endpoint", Path: "/api/v1/shared", Method: "GET"}}
+
+	for _, appCode := range []string{"order", "billing"} {
+		if err := db.Transaction(func(tx *gorm.DB) error {
+			return adminSeeder{}.SeedMenus(tx, appCode, menus, apis)
+		}); err != nil {
+			t.Fatalf("SeedMenus(%q): %v", appCode, err)
+		}
+	}
+
+	var apiRows []models.SysApi
+	if err := db.Where("path = ? AND action = ?", "/api/v1/shared", "GET").
+		Order("app_code").Find(&apiRows).Error; err != nil {
+		t.Fatalf("read sys_api: %v", err)
+	}
+	if len(apiRows) != 2 {
+		t.Fatalf("sys_api has %d row(s) for the shared (path, action), want 2 - one per app", len(apiRows))
+	}
+	if apiRows[0].AppCode != "billing" || apiRows[1].AppCode != "order" {
+		t.Errorf("sys_api app_codes = [%s %s], want [billing order]", apiRows[0].AppCode, apiRows[1].AppCode)
+	}
+
+	var menuRows []models.SysMenu
+	if err := db.Where("seed_code = ?", "dir").Order("app_code").Find(&menuRows).Error; err != nil {
+		t.Fatalf("read sys_menu: %v", err)
+	}
+	if len(menuRows) != 2 {
+		t.Fatalf("sys_menu has %d row(s) for the shared seed_code, want 2 - one per app", len(menuRows))
+	}
+	if menuRows[0].AppCode != "billing" || menuRows[1].AppCode != "order" {
+		t.Errorf("sys_menu app_codes = [%s %s], want [billing order]", menuRows[0].AppCode, menuRows[1].AppCode)
+	}
+}
+
+func allMenuIDs(t *testing.T, db *gorm.DB, appCode string) []int {
+	t.Helper()
+	var rows []models.SysMenu
+	if err := db.Where("app_code = ?", appCode).Order("menu_id").Find(&rows).Error; err != nil {
+		t.Fatalf("read sys_menu: %v", err)
+	}
+	ids := make([]int, len(rows))
+	for i, r := range rows {
+		ids[i] = r.MenuId
+	}
+	return ids
+}
+
+func allApiIDs(t *testing.T, db *gorm.DB, appCode string) []int {
+	t.Helper()
+	var rows []models.SysApi
+	if err := db.Where("app_code = ?", appCode).Order("id").Find(&rows).Error; err != nil {
+		t.Fatalf("read sys_api: %v", err)
+	}
+	ids := make([]int, len(rows))
+	for i, r := range rows {
+		ids[i] = r.Id
+	}
+	return ids
+}
+
+func sameIDs(a, b []int) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func assertRowCount(t *testing.T, db *gorm.DB, table string, want int64) {
+	t.Helper()
+	var n int64
+	if err := db.Table(table).Count(&n).Error; err != nil {
+		t.Fatalf("count %s: %v", table, err)
+	}
+	if n != want {
+		t.Errorf("%s has %d row(s), want %d", table, n, want)
+	}
+}
+
+// A retried migration does not just risk inserting a second copy of a row
+// it already wrote (that gap is closed above) - the reuse path itself has
+// to leave the row in the same state a fresh insert would have. Before
+// this defect was fixed, the reuse branch (seed.go's "case err == nil")
+// stopped at reusing the row's id and skipped everything a fresh insert
+// does afterwards: the sys_menu_api_rule binding gorm's association save
+// writes as part of Create, and the paths UPDATE that follows Create as a
+// separate statement. A row a prior attempt inserted but did not finish -
+// exactly the shape design doc §1.5 says a non-transactional retry can
+// leave behind - would be "found" and then left broken forever, with the
+// migration reporting success.
+//
+// existingHalfWrittenMenu inserts a sys_menu row the way seedMenuTree's own
+// tx.Create leaves one when interrupted immediately afterwards: the row
+// exists with its natural key, but paths was never computed and no
+// sys_menu_api_rule binding was ever written for it - Create's association
+// save and the paths UPDATE are each a separate statement from the row
+// insert itself.
+func existingHalfWrittenMenu(t *testing.T, db *gorm.DB, appCode, seedCode string, parentID int) models.SysMenu {
+	t.Helper()
+	code := seedCode
+	row := models.SysMenu{
+		MenuName: menuName(appCode, seedCode),
+		AppCode:  appCode,
+		SeedCode: &code,
+		ParentId: parentID,
+		Visible:  "0",
+		IsFrame:  "1",
+		// Paths deliberately left "" - never computed, the same as a row
+		// whose Create succeeded but whose follow-up paths UPDATE never ran.
+	}
+	if err := db.Create(&row).Error; err != nil {
+		t.Fatalf("seed half-written menu %q: %v", seedCode, err)
+	}
+	return row
+}
+
+func bindingCount(t *testing.T, db *gorm.DB, menuID, apiID int) int64 {
+	t.Helper()
+	var n int64
+	if err := db.Table("sys_menu_api_rule").
+		Where("sys_menu_menu_id = ? AND sys_api_id = ?", menuID, apiID).Count(&n).Error; err != nil {
+		t.Fatalf("count sys_menu_api_rule: %v", err)
+	}
+	return n
+}
+
+// TestSeedMenusRepairsAnIncompleteExistingRow is the reproduction case:
+// both paths and the api binding are missing on the row seedMenuTree finds
+// through its idempotency check, the shape a real interrupted retry leaves
+// behind. Run against the unfixed reuse branch, this must fail - that is
+// what proves the defect is real rather than a three-way guess.
+func TestSeedMenusRepairsAnIncompleteExistingRow(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+	apiRows, err := seedApis(db, "order", apis)
+	if err != nil {
+		t.Fatalf("seedApis: %v", err)
+	}
+
+	dir := existingHalfWrittenMenu(t, db, "order", "dir", 0)
+	list := existingHalfWrittenMenu(t, db, "order", "list", dir.MenuId)
+
+	menus := []seed.MenuSpec{
+		{Code: "dir", Kind: contractmodels.Directory, Title: "Order", Sort: 10},
+		{Code: "list", Parent: "dir", Kind: contractmodels.Menu, Title: "Orders", Sort: 1, ApiCodes: []string{"list"}},
+	}
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	wantDirPaths := "/0/" + strconv.Itoa(dir.MenuId)
+	wantListPaths := wantDirPaths + "/" + strconv.Itoa(list.MenuId)
+
+	var gotDir, gotList models.SysMenu
+	if err := db.First(&gotDir, dir.MenuId).Error; err != nil {
+		t.Fatalf("read dir: %v", err)
+	}
+	if err := db.First(&gotList, list.MenuId).Error; err != nil {
+		t.Fatalf("read list: %v", err)
+	}
+	if gotDir.Paths != wantDirPaths {
+		t.Errorf("dir.Paths = %q, want %q - a retried install left a root menu with no materialized path", gotDir.Paths, wantDirPaths)
+	}
+	if gotList.Paths != wantListPaths {
+		t.Errorf("list.Paths = %q, want %q - a retried install left the seeded subtree with a broken materialized path", gotList.Paths, wantListPaths)
+	}
+	if n := bindingCount(t, db, list.MenuId, apiRows["list"].Id); n != 1 {
+		t.Errorf("sys_menu_api_rule binding count for list = %d, want 1 - a retried install left the menu with its api granted to no one", n)
+	}
+}
+
+// soloMenuSpec is a single, parent-less menu with one api binding - the
+// smallest shape that can exhibit "paths wrong" and "binding missing"
+// independently of each other, used by the three tests below to isolate
+// one repair path at a time from TestSeedMenusRepairsAnIncompleteExistingRow's
+// combined (both broken) case.
+func soloMenuSpec() []seed.MenuSpec {
+	return []seed.MenuSpec{{Code: "solo", Kind: contractmodels.Menu, Title: "Solo", Sort: 1, ApiCodes: []string{"list"}}}
+}
+
+// Only the binding is missing; paths is already correct. The repair must
+// add the binding and must not touch the already-correct paths value.
+func TestSeedMenusRepairsOnlyAMissingBinding(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+	apiRows, err := seedApis(db, "order", apis)
+	if err != nil {
+		t.Fatalf("seedApis: %v", err)
+	}
+
+	solo := existingHalfWrittenMenu(t, db, "order", "solo", 0)
+	wantPaths := "/0/" + strconv.Itoa(solo.MenuId)
+	if err := db.Model(&models.SysMenu{}).Where("menu_id = ?", solo.MenuId).
+		Update("paths", wantPaths).Error; err != nil {
+		t.Fatalf("set paths: %v", err)
+	}
+	// The binding is deliberately left unwritten.
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", soloMenuSpec(), apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	var got models.SysMenu
+	if err := db.First(&got, solo.MenuId).Error; err != nil {
+		t.Fatalf("read solo: %v", err)
+	}
+	if got.Paths != wantPaths {
+		t.Errorf("paths changed from %q to %q; repairing a missing binding must not touch an already-correct path", wantPaths, got.Paths)
+	}
+	if n := bindingCount(t, db, solo.MenuId, apiRows["list"].Id); n != 1 {
+		t.Errorf("binding count = %d, want 1", n)
+	}
+}
+
+// Only paths is missing; the binding already exists (as if Create's own
+// association write had succeeded but the paths UPDATE that follows it
+// never ran). The repair must fix paths and must not duplicate the
+// already-correct binding.
+func TestSeedMenusRepairsOnlyMissingPaths(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+	apiRows, err := seedApis(db, "order", apis)
+	if err != nil {
+		t.Fatalf("seedApis: %v", err)
+	}
+
+	solo := existingHalfWrittenMenu(t, db, "order", "solo", 0)
+	if err := db.Exec(
+		"INSERT INTO sys_menu_api_rule (sys_menu_menu_id, sys_api_id) VALUES (?, ?)",
+		solo.MenuId, apiRows["list"].Id,
+	).Error; err != nil {
+		t.Fatalf("seed binding: %v", err)
+	}
+	// solo.Paths is deliberately left "" by existingHalfWrittenMenu.
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", soloMenuSpec(), apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	wantPaths := "/0/" + strconv.Itoa(solo.MenuId)
+	var got models.SysMenu
+	if err := db.First(&got, solo.MenuId).Error; err != nil {
+		t.Fatalf("read solo: %v", err)
+	}
+	if got.Paths != wantPaths {
+		t.Errorf("paths = %q, want %q", got.Paths, wantPaths)
+	}
+	if n := bindingCount(t, db, solo.MenuId, apiRows["list"].Id); n != 1 {
+		t.Errorf("binding count = %d, want 1 - repairing paths must not duplicate an already-correct binding", n)
+	}
+}
+
+// capturingLogger records every SQL statement gorm actually executes, so a
+// test can assert that a fully-consistent retry performs no write at all -
+// not just that its net effect happens to be zero rows changed. Mirrors
+// common/actions/crud_shim_test.go's logger of the same name and shape;
+// duplicated locally rather than exported and shared, matching how small
+// gorm-facing test doubles are kept next to the test that needs them
+// elsewhere in this repository.
+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")
+}
+
+// Both paths and the binding are already correct - the ordinary shape of
+// every retry after the first one succeeds in full. Repairing an
+// already-consistent row must not touch it: paths is read-before-write and
+// so must not be UPDATEd at all (asserted directly, by statement, since the
+// code gates that call behind a value comparison); the binding's own
+// insert is guarded by WHERE NOT EXISTS the same way grantToAdminRole's
+// already are, so its row count staying put is the meaningful claim - the
+// guarded statement itself may still be sent, the same way it already is
+// for sys_role_menu/casbin_rule.
+func TestSeedMenusFullyConsistentRowCausesNoPathsUpdate(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+	menus := soloMenuSpec()
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus (first): %v", err)
+	}
+
+	var apiRows []models.SysApi
+	db.Where("app_code = ?", "order").Find(&apiRows)
+	var soloRow models.SysMenu
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "solo").First(&soloRow).Error; err != nil {
+		t.Fatalf("read solo after first call: %v", err)
+	}
+	if soloRow.Paths == "" {
+		t.Fatalf("solo.Paths is empty after the first call; the fixture itself is broken, not what this test means to check")
+	}
+	wantBindings := bindingCount(t, db, soloRow.MenuId, apiRows[0].Id)
+	if wantBindings != 1 {
+		t.Fatalf("binding count after the first call = %d, want 1; the fixture itself is broken", wantBindings)
+	}
+
+	capturing := &capturingLogger{Interface: gormlogger.Default.LogMode(gormlogger.Info)}
+	captured := db.Session(&gorm.Session{Logger: capturing})
+
+	if err := captured.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus (retry): %v", err)
+	}
+
+	all := strings.ToUpper(capturing.all())
+	if strings.Contains(all, "UPDATE") && strings.Contains(all, "SYS_MENU") && strings.Contains(all, "PATHS") {
+		t.Errorf("a fully consistent retry executed a paths UPDATE against sys_menu:\n%s", capturing.all())
+	}
+	if got := bindingCount(t, db, soloRow.MenuId, apiRows[0].Id); got != 1 {
+		t.Errorf("binding count after the retry = %d, want 1 (unchanged)", got)
+	}
+}
+
+// An administrator can bind a menu to an additional api by hand through
+// the menu management UI - a sys_menu_api_rule row for an api never in
+// s.ApiCodes at all. A retried SeedMenus call must not touch it: deleting
+// every binding for the menu and reinserting only what s.ApiCodes lists
+// would wipe it out silently, the same shape as sys_role_menu/casbin_rule
+// getting zeroed by SysRole.Update's FullSaveAssociations save - just with
+// this code as the actor instead of the victim this time.
+func TestSeedMenusPreservesAHandAddedBinding(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET"}}
+	menus := soloMenuSpec()
+
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus (first): %v", err)
+	}
+
+	var soloRow models.SysMenu
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "solo").First(&soloRow).Error; err != nil {
+		t.Fatalf("read solo: %v", err)
+	}
+
+	// An api this call's ApiSpec list never mentions - standing in for one
+	// belonging to some other feature entirely, bound to this menu by an
+	// administrator, not by any SeedMenus call.
+	handAdded := models.SysApi{Path: "/api/v1/order/export", Action: "GET", Type: "SYS", AppCode: "order"}
+	if err := db.Create(&handAdded).Error; err != nil {
+		t.Fatalf("seed the hand-added api: %v", err)
+	}
+	if err := db.Exec(
+		"INSERT INTO sys_menu_api_rule (sys_menu_menu_id, sys_api_id) VALUES (?, ?)",
+		soloRow.MenuId, handAdded.Id,
+	).Error; err != nil {
+		t.Fatalf("seed the hand-added binding: %v", err)
+	}
+
+	// A retry with the exact same specs - solo's ApiCodes still names only
+	// "list".
+	if err := db.Transaction(func(tx *gorm.DB) error {
+		return adminSeeder{}.SeedMenus(tx, "order", menus, apis)
+	}); err != nil {
+		t.Fatalf("SeedMenus (retry): %v", err)
+	}
+
+	if n := bindingCount(t, db, soloRow.MenuId, handAdded.Id); n != 1 {
+		t.Errorf("hand-added binding count = %d, want 1 - a retry silently deleted a binding it does not own", n)
+	}
+
+	var apiRows []models.SysApi
+	db.Where("app_code = ? AND path = ?", "order", "/api/v1/order").Find(&apiRows)
+	if len(apiRows) != 1 {
+		t.Fatalf("seeded api not found as expected: %+v", apiRows)
+	}
+	if n := bindingCount(t, db, soloRow.MenuId, apiRows[0].Id); n != 1 {
+		t.Errorf("the seed's own binding count = %d, want 1 - it must survive the retry too", n)
+	}
+}
+
+// Every policy grantToAdminRole creates has to be written down, or an
+// uninstall has no way to tell this app's grants from a hand-made one and
+// leaves all of them behind.
+func TestSeedMenusRecordsTheGrantsItCreated(t *testing.T) {
+	db := newSeedTestDB(t)
+	role := seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+		{Code: "create", Title: "Create order", Path: "/api/v1/order", Method: "POST", Handle: "apis.Order.Insert-fm"},
+	}
+	if err := (adminSeeder{}).SeedMenus(db, "order", nil, apis); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	for _, a := range apis {
+		var n int64
+		db.Model(&models.SysAppCasbinGrant{}).
+			Where("app_code = ? AND ptype = 'p' AND v0 = ? AND v1 = ? AND v2 = ?",
+				"order", role.RoleKey, a.Path, a.Method).
+			Count(&n)
+		if n != 1 {
+			t.Errorf("ledger rows for %s %s = %d, want 1", a.Method, a.Path, n)
+		}
+	}
+}
+
+// A policy that was already there was not created by this install, so it is
+// not this app's to take away later. Recording it would mean an uninstall
+// deletes a grant somebody else made, and deletes it silently - the opposite
+// mistake leaves a policy behind, which the uninstall reports.
+func TestSeedMenusDoesNotClaimAPolicyItDidNotCreate(t *testing.T) {
+	db := newSeedTestDB(t)
+	role := seedAdminRole(t, db)
+
+	if err := db.Exec(
+		"INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES ('p', ?, '/api/v1/order', 'GET', '', '', '')",
+		role.RoleKey,
+	).Error; err != nil {
+		t.Fatalf("pre-existing policy: %v", err)
+	}
+
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+		{Code: "create", Title: "Create order", Path: "/api/v1/order", Method: "POST", Handle: "apis.Order.Insert-fm"},
+	}
+	if err := (adminSeeder{}).SeedMenus(db, "order", nil, apis); err != nil {
+		t.Fatalf("SeedMenus: %v", err)
+	}
+
+	var claimed int64
+	db.Model(&models.SysAppCasbinGrant{}).
+		Where("v1 = ? AND v2 = ?", "/api/v1/order", "GET").Count(&claimed)
+	if claimed != 0 {
+		t.Errorf("the ledger claimed a policy that was already there (%d rows)", claimed)
+	}
+	// The one it did create is still recorded: the skip is per policy, not
+	// for the whole call.
+	var created int64
+	db.Model(&models.SysAppCasbinGrant{}).
+		Where("v1 = ? AND v2 = ?", "/api/v1/order", "POST").Count(&created)
+	if created != 1 {
+		t.Errorf("ledger rows for the policy it did create = %d, want 1", created)
+	}
+	// And the pre-existing policy itself is untouched.
+	var policies int64
+	db.Table("casbin_rule").Where("v1 = ? AND v2 = ?", "/api/v1/order", "GET").Count(&policies)
+	if policies != 1 {
+		t.Errorf("casbin_rule rows = %d, want the one that was already there", policies)
+	}
+}
+
+// A migration that failed partway is re-run whole. The ledger must come out
+// of a second run the same as the first, not with a duplicate or an error
+// from its own unique index.
+func TestSeedMenusLedgerSurvivesARetry(t *testing.T) {
+	db := newSeedTestDB(t)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+	}
+	for i := 0; i < 2; i++ {
+		if err := (adminSeeder{}).SeedMenus(db, "order", nil, apis); err != nil {
+			t.Fatalf("SeedMenus run %d: %v", i+1, err)
+		}
+	}
+
+	var n int64
+	db.Model(&models.SysAppCasbinGrant{}).Count(&n)
+	if n != 1 {
+		t.Errorf("ledger has %d rows after two runs, want 1", n)
+	}
+}
+
+// The ledger's own guard against a duplicate, which the plain retry above
+// never reaches: there the policy still exists, so the insert is skipped
+// before the ledger is touched at all. This is the case that does reach it -
+// the policy row was removed while its ledger entry stayed, so the seed
+// creates the policy again and writes a ledger entry that is already there.
+// A plain insert would abort the whole seed on the ledger's unique index.
+func TestSeedMenusLedgerToleratesAnEntryWhosePolicyWasRemoved(t *testing.T) {
+	db := newSeedTestDB(t)
+	seedAdminRole(t, db)
+
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+	}
+	if err := (adminSeeder{}).SeedMenus(db, "order", nil, apis); err != nil {
+		t.Fatalf("first run: %v", err)
+	}
+	if err := db.Exec("DELETE FROM casbin_rule WHERE v1 = ? AND v2 = ?", "/api/v1/order", "GET").Error; err != nil {
+		t.Fatalf("removing the policy: %v", err)
+	}
+	var ledger int64
+	db.Model(&models.SysAppCasbinGrant{}).Count(&ledger)
+	if ledger != 1 {
+		t.Fatalf("the ledger entry is gone, so this test is not set up: %d rows", ledger)
+	}
+
+	if err := (adminSeeder{}).SeedMenus(db, "order", nil, apis); err != nil {
+		t.Fatalf("second run: %v", err)
+	}
+
+	db.Model(&models.SysAppCasbinGrant{}).Count(&ledger)
+	if ledger != 1 {
+		t.Errorf("ledger has %d rows, want 1", ledger)
+	}
+	var policies int64
+	db.Table("casbin_rule").Where("v1 = ? AND v2 = ?", "/api/v1/order", "GET").Count(&policies)
+	if policies != 1 {
+		t.Errorf("the policy was not put back: %d rows", policies)
+	}
+}
+
+// The tree is built from parent_id, not from paths. A menu whose parent was
+// removed and written again kept parent_id on the dead row while its paths
+// named the new one, so the menu was gone from the sidebar and the migration
+// said it had succeeded.
+func TestSeedMenusRepairsParentIdAfterTheParentWasRemoved(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("first seed: %v", err)
+	}
+	var dir models.SysMenu
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "dir").First(&dir).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Delete(&models.SysMenu{}, "menu_id = ?", dir.MenuId).Error; err != nil {
+		t.Fatalf("removing the parent: %v", err)
+	}
+
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("second seed: %v", err)
+	}
+
+	var newDir, list models.SysMenu
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "dir").First(&newDir).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "list").First(&list).Error; err != nil {
+		t.Fatal(err)
+	}
+	if newDir.MenuId == dir.MenuId {
+		t.Fatal("the removed parent was reused, so this test proves nothing")
+	}
+	if list.ParentId != newDir.MenuId {
+		t.Errorf("parent_id = %d, want the new parent %d; the menu hangs off a row that is gone",
+			list.ParentId, newDir.MenuId)
+	}
+	if want := newDir.Paths + "/" + strconv.Itoa(list.MenuId); list.Paths != want {
+		t.Errorf("paths = %q, want %q", list.Paths, want)
+	}
+}
+
+// A menu somebody added under a seeded one is not in any spec, so nothing but
+// this would ever rewrite its path when its ancestor moves.
+func TestSeedMenusMovesTheSubtreeUnderARepairedMenu(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("first seed: %v", err)
+	}
+	var dir, list models.SysMenu
+	db.Where("app_code = ? AND seed_code = ?", "order", "dir").First(&dir)
+	db.Where("app_code = ? AND seed_code = ?", "order", "list").First(&list)
+
+	// By hand, under the seeded menu, the way an administrator would.
+	hand := models.SysMenu{MenuName: "HandMade", Title: "By hand", MenuType: contractmodels.Menu,
+		ParentId: list.MenuId}
+	if err := db.Create(&hand).Error; err != nil {
+		t.Fatal(err)
+	}
+	hand.Paths = list.Paths + "/" + strconv.Itoa(hand.MenuId)
+	db.Model(&models.SysMenu{}).Where("menu_id = ?", hand.MenuId).Update("paths", hand.Paths)
+
+	// Rows whose paths start with the moving one's as a string and are not
+	// underneath it as a path. /0/1/2 is a string prefix of /0/1/20, and a
+	// LIKE on the bare prefix cannot tell the two apart - so these have to
+	// be built against the path that actually moves, which is the one this
+	// repair rewrites.
+	var decoys []models.SysMenu
+	for _, suffix := range []string{"0", "1", "9"} {
+		d := models.SysMenu{MenuName: "Decoy" + suffix, Title: "decoy", MenuType: contractmodels.Menu}
+		if err := db.Create(&d).Error; err != nil {
+			t.Fatal(err)
+		}
+		d.Paths = list.Paths + suffix
+		db.Model(&models.SysMenu{}).Where("menu_id = ?", d.MenuId).Update("paths", d.Paths)
+		decoys = append(decoys, d)
+	}
+
+	if err := db.Delete(&models.SysMenu{}, "menu_id = ?", dir.MenuId).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("second seed: %v", err)
+	}
+
+	var newList, movedHand models.SysMenu
+	db.Where("app_code = ? AND seed_code = ?", "order", "list").First(&newList)
+	db.Where("menu_id = ?", hand.MenuId).First(&movedHand)
+	if want := newList.Paths + "/" + strconv.Itoa(hand.MenuId); movedHand.Paths != want {
+		t.Errorf("the hand-made menu's paths = %q, want %q; it no longer names its ancestors",
+			movedHand.Paths, want)
+	}
+	for _, d := range decoys {
+		var after models.SysMenu
+		db.Where("menu_id = ?", d.MenuId).First(&after)
+		if after.Paths != d.Paths {
+			t.Errorf("decoy %d moved from %q to %q; a prefix match caught a row that is not underneath",
+				d.MenuId, d.Paths, after.Paths)
+		}
+	}
+}
+
+// An application that renames a menu or moves its component in a new version
+// had the change ignored: the row was found and returned untouched.
+func TestSeedMenusRefreshesWhatTheSpecDecides(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("first seed: %v", err)
+	}
+	// An administrator hides it. That is not something the spec expresses,
+	// so a reseed has no business turning it back on.
+	if err := db.Model(&models.SysMenu{}).Where("app_code = ? AND seed_code = ?", "order", "list").
+		Update("visible", "1").Error; err != nil {
+		t.Fatal(err)
+	}
+
+	menus2, apis2 := orderMenuSpecs("Sales orders", "apps/order/list/index")
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus2, apis2); err != nil {
+		t.Fatalf("second seed: %v", err)
+	}
+
+	var list models.SysMenu
+	db.Where("app_code = ? AND seed_code = ?", "order", "list").First(&list)
+	if list.Title != "Sales orders" {
+		t.Errorf("title = %q, want the new one", list.Title)
+	}
+	if list.Component != "apps/order/list/index" {
+		t.Errorf("component = %q, want the new one", list.Component)
+	}
+	if list.Visible != "1" {
+		t.Errorf("visible = %q; a reseed unhid a menu an administrator had hidden", list.Visible)
+	}
+}
+
+// orderMenuSpecs is a two-level tree plus one api, parameterised on the two
+// columns the upgrade test changes.
+func orderMenuSpecs(title, component string) ([]seed.MenuSpec, []seed.ApiSpec) {
+	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: title, Path: "list", Component: component, Sort: 1, ApiCodes: []string{"list"}},
+	}
+	apis := []seed.ApiSpec{
+		{Code: "list", Title: "Order list", Path: "/api/v1/order", Method: "GET", Handle: "apis.Order.GetPage-fm"},
+	}
+	return menus, apis
+}
+
+// 1786700008000 added seed_code and left it NULL on every row already there.
+// An application's rows are in that population, and the natural-key lookup
+// misses them, so the seed used to insert a second copy beside each one -
+// which the unique index cannot object to, because NULL never collides.
+func TestSeedMenusAdoptsARowWrittenBeforeSeedCodeExisted(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	// What an older SeedMenus left: app_code set, seed_code absent, and the
+	// name that identified it then.
+	legacy := models.SysMenu{
+		MenuName: menuName("order", "dir"), AppCode: "order", Title: "the old title",
+		MenuType: contractmodels.Directory, Path: "/apps/order", Component: "Layout", Sort: 10,
+	}
+	if err := db.Create(&legacy).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	var rows []models.SysMenu
+	if err := db.Where("app_code = ? AND menu_name = ?", "order", menuName("order", "dir")).
+		Find(&rows).Error; err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 {
+		t.Fatalf("%d rows carry that name; the row from before the column existed was not found", len(rows))
+	}
+	if rows[0].MenuId != legacy.MenuId {
+		t.Errorf("menu_id = %d, want the row that was already there (%d)", rows[0].MenuId, legacy.MenuId)
+	}
+	if rows[0].SeedCode == nil || *rows[0].SeedCode != "dir" {
+		t.Errorf("seed_code = %v, want it claimed", rows[0].SeedCode)
+	}
+	// Adopted and then repaired, like any other existing row.
+	if rows[0].Title != "Order Example" {
+		t.Errorf("title = %q; the adopted row was not brought up to the spec", rows[0].Title)
+	}
+}
+
+// menuName concatenates two pascalCase strings and pascalCase is not
+// injective, so two specs can land on one name. Picking one of several rows
+// would attach an application's menu to whichever the database returned
+// first.
+func TestSeedMenusRefusesAnAmbiguousAdoption(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	for i := 0; i < 2; i++ {
+		row := models.SysMenu{
+			MenuName: menuName("order", "dir"), AppCode: "order", Title: fmt.Sprintf("copy %d", i),
+			MenuType: contractmodels.Directory,
+		}
+		if err := db.Create(&row).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+	err := (adminSeeder{}).SeedMenus(db, "order", menus, apis)
+	if err == nil {
+		t.Fatal("an ambiguous adoption was accepted")
+	}
+	if !strings.Contains(err.Error(), "2 rows") || !strings.Contains(err.Error(), "by hand") {
+		t.Errorf("error = %q, it has to say how many and that it is not deciding", err)
+	}
+	// And it did not write a third.
+	var n int64
+	db.Model(&models.SysMenu{}).Where("app_code = ? AND menu_name = ?", "order", menuName("order", "dir")).Count(&n)
+	if n != 2 {
+		t.Errorf("%d rows carry that name; the refusal still inserted", n)
+	}
+}
+
+// A row belonging to another application, or to the host, carries a different
+// app_code and is not this application's to claim.
+func TestSeedMenusDoesNotAdoptAnotherApplicationsRow(t *testing.T) {
+	db := newSeedTestDB(t)
+	useCompositeSeedCodeIndex(t, db)
+	seedAdminRole(t, db)
+
+	other := models.SysMenu{
+		MenuName: menuName("order", "dir"), AppCode: "crm", Title: "crm's own",
+		MenuType: contractmodels.Directory,
+	}
+	if err := db.Create(&other).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	menus, apis := orderMenuSpecs("Orders", "apps/order/index")
+	if err := (adminSeeder{}).SeedMenus(db, "order", menus, apis); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	var after models.SysMenu
+	db.Where("menu_id = ?", other.MenuId).First(&after)
+	if after.SeedCode != nil || after.Title != "crm's own" {
+		t.Errorf("another application's row was claimed: %+v", after)
+	}
+	var mine models.SysMenu
+	if err := db.Where("app_code = ? AND seed_code = ?", "order", "dir").First(&mine).Error; err != nil {
+		t.Fatalf("this application's own row was not created: %v", err)
+	}
+}

app/admin/service/sys_role_menu.go

@@ -107,4 +107,4 @@ type SysRoleMenu struct {
 //		return nil, err
 //	}
 //	return r, nil
-//}
+//}

app/admin/service/sys_user.go

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

app/jobs/jobbase.go

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

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/service/sys_job.go

@@ -39,7 +39,7 @@ func (e *SysJob) RemoveJob(c *dto.GeneralDelDto) error {
 		}
 	case <-time.After(time.Second * 1):
 		e.Msg = "操作超时！"
-		return nil
+		return errors.New(e.Msg)
 	}
 	return nil
 }

app/jobs/service/sys_job_test.go

@@ -0,0 +1,88 @@
+package service
+
+import (
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	coreservice "github.com/go-admin-team/go-admin-core/v2/sdk/service"
+	"github.com/robfig/cron/v3"
+	"gorm.io/gorm"
+
+	"go-admin/app/jobs/models"
+	"go-admin/common/dto"
+)
+
+type blockedSchedule struct {
+	started chan struct{}
+	release chan struct{}
+}
+
+func (s blockedSchedule) Next(now time.Time) time.Time {
+	close(s.started)
+	<-s.release
+	return now.Add(time.Hour)
+}
+
+func TestRemoveJob(t *testing.T) {
+	for _, blocked := range []bool{false, true} {
+		name := "success"
+		if blocked {
+			name = "timeout"
+		}
+		t.Run(name, func(t *testing.T) {
+			db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			sqlDB, err := db.DB()
+			if err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = sqlDB.Close() })
+			if err := db.AutoMigrate(&models.SysJob{}); err != nil {
+				t.Fatal(err)
+			}
+
+			c := cron.New()
+			schedule := blockedSchedule{make(chan struct{}), make(chan struct{})}
+			entryID := c.Schedule(schedule, cron.FuncJob(func() {}))
+			if blocked {
+				c.Start()
+				t.Cleanup(func() {
+					close(schedule.release)
+					<-c.Stop().Done()
+				})
+				select {
+				case <-schedule.started:
+				case <-time.After(5 * time.Second):
+					t.Fatal("scheduler did not start")
+				}
+			}
+			job := models.SysJob{EntryId: int(entryID)}
+			if err := db.Create(&job).Error; err != nil {
+				t.Fatal(err)
+			}
+			s := SysJob{Service: coreservice.Service{Orm: db}, Cron: c}
+			err = s.RemoveJob(&dto.GeneralDelDto{Id: job.JobId})
+			if blocked {
+				if err == nil || err.Error() != "操作超时！" {
+					t.Errorf("RemoveJob error = %v, want timeout error", err)
+				}
+			} else if err != nil {
+				t.Fatal(err)
+			}
+			var saved models.SysJob
+			if err := db.First(&saved, job.JobId).Error; err != nil {
+				t.Fatal(err)
+			}
+			wantEntryID := 0
+			if blocked {
+				wantEntryID = int(entryID)
+			}
+			if saved.EntryId != wantEntryID {
+				t.Errorf("entry_id = %d, want %d", saved.EntryId, wantEntryID)
+			}
+		})
+	}
+}

app/other/apis/tools/db_columns.go

@@ -8,6 +8,12 @@ import (
 	"go-admin/app/other/models/tools"
 )
 
+// emptyTableNameMsg is what the generator's endpoints answer with when the
+// request named no table. Declared once because the tests assert on it: spelled
+// out again at each site, a reworded message would leave them asserting on a
+// string the server no longer sends, and still passing.
+const emptyTableNameMsg = "table name cannot be empty！"
+
 // GetDBColumnList 分页列表数据
 // @Summary 分页列表数据 / page list data
 // @Description 数据库表列分页列表 / database table column page list
@@ -41,7 +47,7 @@ func (e Gen) GetDBColumnList(c *gin.Context) {
 	}
 
 	data.TableName = c.Request.FormValue("tableName")
-	pkg.Assert(data.TableName != "", "table name cannot be empty！", 500)
+	pkg.Assert(data.TableName != "", emptyTableNameMsg, 500)
 	result, count, err := data.GetPage(db, pageSize, pageIndex)
 	if err != nil {
 		log.Errorf("GetPage error, %s", err.Error())

app/other/apis/tools/db_columns_test.go

@@ -16,17 +16,21 @@ import (
 	"go-admin/common/middleware"
 )
 
-const emptyTableNameMsg = "table name cannot be empty！"
-
 // bodyOf covers both the success and the CustomError shape: both carry msg.
 type bodyOf struct {
 	Code int    `json:"code"`
 	Msg  string `json:"msg"`
 }
 
-// newColumnListEngine wires the handler the way the router does, including the
+// newEngine wires one generator handler the way the router does, including the
 // middleware that turns pkg.Assert's panic into a response.
-func newColumnListEngine(t *testing.T) *gin.Engine {
+//
+// The generator's queries target MySQL's information_schema and cannot run on
+// the sqlite connection behind them; the driver setting only has to select that
+// branch, since no statement here is expected to succeed. That makes this
+// serviceable for any handler in this package whose behaviour is decided before
+// the query goes out -- which is what these tests are about.
+func newEngine(t *testing.T, method, path string, h gin.HandlerFunc) *gin.Engine {
 	t.Helper()
 	gin.SetMode(gin.TestMode)
 
@@ -35,26 +39,33 @@ func newColumnListEngine(t *testing.T) *gin.Engine {
 		t.Fatalf("open sqlite: %v", err)
 	}
 
-	// The query targets MySQL's information_schema; the driver setting only has
-	// to select that branch, the statement itself is never expected to succeed.
 	previous := config.DatabaseConfig.Driver
 	config.DatabaseConfig.Driver = "mysql"
 	t.Cleanup(func() { config.DatabaseConfig.Driver = previous })
 
 	r := gin.New()
 	r.Use(middleware.CustomError)
-	r.GET("/db/columns/page", func(c *gin.Context) {
+	r.Handle(method, path, func(c *gin.Context) {
 		c.Set("db", db)
 		c.Set(pkg.LoggerKey, logger.NewHelper(logger.DefaultLogger))
-		Gen{}.GetDBColumnList(c)
+		h(c)
 	})
 	return r
 }
 
-func columnListMsg(t *testing.T, r *gin.Engine, query string) bodyOf {
+func newColumnListEngine(t *testing.T) *gin.Engine {
+	t.Helper()
+	return newEngine(t, http.MethodGet, "/db/columns/page", Gen{}.GetDBColumnList)
+}
+
+// serveJSON runs one request through the engine and decodes the envelope every
+// handler here answers with. A body that will not decode fails the test rather
+// than being reported as a mismatched message, which reads as the handler
+// having answered something unexpected instead of not having answered at all.
+func serveJSON(t *testing.T, r *gin.Engine, req *http.Request) bodyOf {
 	t.Helper()
 	w := httptest.NewRecorder()
-	r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/db/columns/page"+query, nil))
+	r.ServeHTTP(w, req)
 
 	var body bodyOf
 	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
@@ -63,6 +74,11 @@ func columnListMsg(t *testing.T, r *gin.Engine, query string) bodyOf {
 	return body
 }
 
+func columnListMsg(t *testing.T, r *gin.Engine, query string) bodyOf {
+	t.Helper()
+	return serveJSON(t, r, httptest.NewRequest(http.MethodGet, "/db/columns/page"+query, nil))
+}
+
 func TestGetDBColumnList_AcceptsATableName(t *testing.T) {
 	body := columnListMsg(t, newColumnListEngine(t), "?tableName=sys_user")
 	if body.Msg == emptyTableNameMsg {

app/other/apis/tools/gen.go

@@ -83,7 +83,7 @@ func (e Gen) Preview(c *gin.Context) {
 		return
 	}
 
-	tab, _ := table.Get(db,false)
+	tab, _ := table.Get(db, false)
 	var b1 bytes.Buffer
 	err = t1.Execute(&b1, tab)
 	var b2 bytes.Buffer
@@ -129,7 +129,7 @@ func (e Gen) GenCode(c *gin.Context) {
 	}
 
 	table.TableId = id
-	tab, _ := table.Get(db,false)
+	tab, _ := table.Get(db, false)
 
 	e.NOActionsGen(c, tab)
 
@@ -155,7 +155,7 @@ func (e Gen) GenApiToFile(c *gin.Context) {
 	}
 
 	table.TableId = id
-	tab, _ := table.Get(db,false)
+	tab, _ := table.Get(db, false)
 	e.genApiToFile(c, tab)
 
 	e.OK("", "Code generated successfully！")
@@ -302,7 +302,7 @@ func (e Gen) GenMenuAndApi(c *gin.Context) {
 	}
 
 	table.TableId = id
-	tab, _ := table.Get(e.Orm,true)
+	tab, _ := table.Get(e.Orm, true)
 	tab.MLTBName = strings.Replace(tab.TBName, "_", "-", -1)
 
 	Mmenu := dto.SysMenuInsertReq{}

app/other/apis/tools/sys_tables.go

@@ -1,12 +1,13 @@
 package tools
 
 import (
+	"errors"
 	"strings"
 
 	"github.com/gin-gonic/gin"
+	_ "github.com/go-admin-team/go-admin-core/v2/response"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/api"
 	"github.com/go-admin-team/go-admin-core/v2/sdk/pkg"
-	_ "github.com/go-admin-team/go-admin-core/v2/response"
 	"gorm.io/gorm"
 
 	"go-admin/app/other/models/tools"
@@ -79,7 +80,7 @@ func (e SysTable) Get(c *gin.Context) {
 
 	var data tools.SysTables
 	data.TableId, _ = pkg.StringToInt(c.Param("tableId"))
-	result, err := data.Get(db,true)
+	result, err := data.Get(db, true)
 	if err != nil {
 		log.Errorf("Get error, %s", err.Error())
 		e.Error(500, err, "")
@@ -106,7 +107,7 @@ func (e SysTable) GetSysTablesInfo(c *gin.Context) {
 	if c.Request.FormValue("tableName") != "" {
 		data.TBName = c.Request.FormValue("tableName")
 	}
-	result, err := data.Get(db,true)
+	result, err := data.Get(db, true)
 	if err != nil {
 		log.Errorf("Get error, %s", err.Error())
 		e.Error(500, err, "抱歉未找到相关信息")
@@ -148,7 +149,8 @@ func (e SysTable) GetSysTablesTree(c *gin.Context) {
 // @Tags 工具 / 生成工具
 // @Accept  application/json
 // @Product application/json
-// @Param tables query string false "tableName / 数据表名称"
+// @Param tables query string false "tableName / 数据表名称，逗号分隔"
+// @Param data body object false "tables / 同上，query 未带时从 JSON body 读"
 // @Success 200 {string} string	"{"code": 200, "message": "添加成功"}"
 // @Success 200 {string} string	"{"code": -1, "message": "添加失败"}"
 // @Router /api/v1/sys/tables/info [post]
@@ -163,7 +165,13 @@ func (e SysTable) Insert(c *gin.Context) {
 		return
 	}
 
-	tablesList := strings.Split(c.Request.FormValue("tables"), ",")
+	tablesList, err := tablesToImport(c)
+	if err != nil {
+		log.Errorf("read the table list, %s", err.Error())
+		e.Error(500, err, "")
+		return
+	}
+
 	for i := 0; i < len(tablesList); i++ {
 
 		data, err := genTableInit(db, tablesList, i, c)
@@ -184,6 +192,45 @@ func (e SysTable) Insert(c *gin.Context) {
 
 }
 
+// tablesToImport reads the comma-separated table list carried by an import
+// request, from the query string or from a JSON body.
+//
+// The list has only ever travelled in the query string, which is the single
+// place FormValue looks once the request declares itself as JSON. A front end
+// that puts it in the body instead therefore left this empty, and the import
+// went on to ask information_schema for a table named "" -- go-admin-ui v3.2.0
+// shipped exactly that, and every import failed with the message below.
+// Reading the body when the query has nothing keeps either front end working.
+func tablesToImport(c *gin.Context) ([]string, error) {
+	raw := c.Request.FormValue("tables")
+	if raw == "" {
+		var body struct {
+			Tables string `json:"tables"`
+		}
+		// A body that is absent, or shaped some other way, is not itself worth
+		// reporting: the list is missing either way, and the message below says
+		// so in the terms the caller asked in.
+		if err := c.ShouldBindJSON(&body); err == nil {
+			raw = body.Tables
+		}
+	}
+
+	parts := strings.Split(raw, ",")
+	names := make([]string, 0, len(parts))
+	for _, name := range parts {
+		// Splitting "" yields one empty name rather than nothing at all, so
+		// without this an empty list reads as a request to import one table
+		// whose name happens to be blank.
+		if name = strings.TrimSpace(name); name != "" {
+			names = append(names, name)
+		}
+	}
+	if len(names) == 0 {
+		return nil, errors.New(emptyTableNameMsg)
+	}
+	return names, nil
+}
+
 func genTableInit(tx *gorm.DB, tablesList []string, i int, c *gin.Context) (tools.SysTables, error) {
 	var data tools.SysTables
 	var dbTable tools.DBTables

app/other/apis/tools/sys_tables_test.go

@@ -0,0 +1,124 @@
+package tools
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// newImportRequest builds the request an import arrives in. Where the table
+// list sits -- query or body -- is exactly what these tests are about, and it
+// is net/http's form parsing that decides what a handler can reach, so these go
+// through a real *http.Request rather than a hand-built one.
+func newImportRequest(target, contentType, body string) *http.Request {
+	req := httptest.NewRequest(http.MethodPost, target, strings.NewReader(body))
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	return req
+}
+
+func TestTablesToImport(t *testing.T) {
+	cases := []struct {
+		name        string
+		target      string
+		contentType string
+		body        string
+		want        []string
+		wantErr     bool
+	}{{
+		name:   "from the query, as every front end before v3.2.0 sent it",
+		target: "/sys/tables/info?tables=sys_user,sys_post",
+		want:   []string{"sys_user", "sys_post"},
+	}, {
+		name:        "from a JSON body, as go-admin-ui v3.2.0 sends it",
+		target:      "/sys/tables/info",
+		contentType: "application/json",
+		body:        `{"tables":"sys_user,sys_post"}`,
+		want:        []string{"sys_user", "sys_post"},
+	}, {
+		name:        "the query wins when a request carries both",
+		target:      "/sys/tables/info?tables=sys_user",
+		contentType: "application/json",
+		body:        `{"tables":"sys_post"}`,
+		want:        []string{"sys_user"},
+	}, {
+		name:   "blank entries are dropped rather than imported as a nameless table",
+		target: "/sys/tables/info?tables=sys_user,,%20,sys_post",
+		want:   []string{"sys_user", "sys_post"},
+	}, {
+		name:        "a body carrying an empty list is an error",
+		target:      "/sys/tables/info",
+		contentType: "application/json",
+		body:        `{"tables":""}`,
+		wantErr:     true,
+	}, {
+		name:        "a body that is not JSON at all is an error, not a panic",
+		target:      "/sys/tables/info",
+		contentType: "application/json",
+		body:        "sys_user",
+		wantErr:     true,
+	}}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c, _ := gin.CreateTestContext(httptest.NewRecorder())
+			c.Request = newImportRequest(tc.target, tc.contentType, tc.body)
+
+			got, err := tablesToImport(c)
+
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected an error, got %q", got)
+				}
+				if err.Error() != emptyTableNameMsg {
+					t.Fatalf("message should be the one the front end shows, got %q", err.Error())
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if strings.Join(got, ",") != strings.Join(tc.want, ",") {
+				t.Fatalf("got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// insertMsg runs one import through the wired handler. It asserts nothing about
+// the import succeeding -- it cannot, over sqlite -- only about how far the
+// request got, which the empty-list message is what distinguishes.
+func insertMsg(t *testing.T, target, contentType, body string) bodyOf {
+	t.Helper()
+	return serveJSON(t,
+		newEngine(t, http.MethodPost, "/sys/tables/info", SysTable{}.Insert),
+		newImportRequest(target, contentType, body))
+}
+
+func TestInsert_ReadsTheTableListFromEitherPlace(t *testing.T) {
+	for _, tc := range []struct {
+		name        string
+		target      string
+		contentType string
+		body        string
+	}{
+		{"query", "/sys/tables/info?tables=sys_user", "", ""},
+		{"JSON body", "/sys/tables/info", "application/json", `{"tables":"sys_user"}`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := insertMsg(t, tc.target, tc.contentType, tc.body); got.Msg == emptyTableNameMsg {
+				t.Fatalf("request carried a table name and was still rejected as empty: %+v", got)
+			}
+		})
+	}
+}
+
+func TestInsert_RejectsAMissingTableList(t *testing.T) {
+	if got := insertMsg(t, "/sys/tables/info", "", ""); got.Msg != emptyTableNameMsg {
+		t.Fatalf("missing table list should be rejected, got %+v", got)
+	}
+}

app/other/router/demo_guard_test.go

@@ -0,0 +1,91 @@
+package router
+
+import (
+	"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/config"
+
+	"go-admin/common/middleware"
+)
+
+// registeredRoutes builds the generator's routes on an engine of its own and
+// reports the patterns they were registered under.
+//
+// The mode has to be given rather than inherited, because it now decides what
+// gets registered: a test that leaves it at the zero value would be asking
+// about a mode no deployment runs in, and would pass whether or not the gate
+// works.
+//
+// It is put back before this returns, not at the end of the test. t.Cleanup
+// would leave the mode set for everything the caller does afterwards, so a
+// caller that went on to assert something mode-dependent would be reading a
+// value this helper left behind rather than one it chose. A caller that does
+// want the mode set has to set it, which is visible where it happens.
+//
+// The JWT middleware is a zero value. MiddlewareFunc only closes over the
+// receiver and is never called here - no request is served, the engine is
+// asked what it has - so nothing dereferences it.
+func registeredRoutes(t *testing.T, mode string) map[string]bool {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	previous := config.ApplicationConfig.Mode
+	defer func() { config.ApplicationConfig.Mode = previous }()
+	config.ApplicationConfig.Mode = mode
+
+	r := gin.New()
+	v1 := r.Group("/api/v1")
+	sysNoCheckRoleRouter(v1, &jwt.GinJWTMiddleware{})
+	registerDBRouter(v1, &jwt.GinJWTMiddleware{})
+
+	out := map[string]bool{}
+	for _, route := range r.Routes() {
+		out[route.Path] = true
+	}
+	return out
+}
+
+// The list of routes demo mode refuses lives in common/middleware, which may
+// not import app/ and therefore cannot see whether any of them is still a
+// route. This is the half that can be checked, and it is checked here because
+// this is where the routes are declared: rename one, and the entry over there
+// stops matching anything, demo mode silently starts serving it again, and
+// nothing else would say so.
+func TestEveryRouteDemoModeRefusesStillExists(t *testing.T) {
+	routes := registeredRoutes(t, "demo")
+	for _, guarded := range middleware.DemoWriteRoutes() {
+		if !routes[guarded] {
+			t.Errorf("demo mode refuses %q, but no route is registered under that pattern - "+
+				"either it was renamed, or it moved to another file; the guard now matches nothing",
+				guarded)
+		}
+	}
+}
+
+// The other direction, and the one the demo host cares about: the generator's
+// read-only routes have to stay reachable, or a demo deployment cannot show
+// the feature at all. Refusing too much is as much of a defect as refusing too
+// little.
+func TestTheGeneratorsReadOnlyRoutesAreNotRefused(t *testing.T) {
+	refused := map[string]bool{}
+	for _, guarded := range middleware.DemoWriteRoutes() {
+		refused[guarded] = true
+	}
+
+	for _, readOnly := range []string{
+		"/api/v1/gen/preview/:tableId",
+		"/api/v1/gen/tabletree",
+		"/api/v1/db/tables/page",
+		"/api/v1/db/columns/page",
+	} {
+		if !registeredRoutes(t, "demo")[readOnly] {
+			t.Fatalf("%s is not registered, so this test is asserting against nothing", readOnly)
+		}
+		if refused[readOnly] {
+			t.Errorf("demo mode refuses %s, which only reads - the demo host needs it to "+
+				"demonstrate the generator", readOnly)
+		}
+	}
+}

app/other/router/gen_router.go

@@ -3,15 +3,49 @@ 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/config"
+
 	"go-admin/app/admin/apis"
 	"go-admin/app/other/apis/tools"
 )
 
+// GenWriteRoutesEnabled reports whether the code generator's writing endpoints
+// are registered in this process.
+//
+// Three of the generator's endpoints do not read. /gen/toproject writes seven
+// Go and Vue source files onto this host, one of them under the path
+// gen.frontpath names; /gen/apitofile writes a migration; /gen/todb inserts
+// menus and APIs. All three are GET, all three are listed in CasbinExclude,
+// and AuthCheckRole skips what is on that list - so Enforce never runs for
+// them and any account that can log in may call them. That is a bargain a
+// workstation can make and a deployment cannot.
+//
+// dev is the shipped default and is where the generator is meant to be used.
+// demo keeps them because demo mode already has a better answer than a 404:
+// DemoEvn refuses these three by name and explains itself, which is the thing
+// the demo exists to show. test and prod get nothing.
+//
+// The mode is read once, while the routes are being built. Changing
+// application.mode in a running process adds and removes nothing - a
+// configuration reload rebuilds neither the engine nor its routes.
+//
+// core has constants for dev, test and prod but none for demo, which this
+// repository spells as a literal in common/middleware/demo.go. Both are
+// literals here so that the two read as one set rather than two conventions.
+func GenWriteRoutesEnabled() bool {
+	switch config.ApplicationConfig.Mode {
+	case "dev", "demo":
+		return true
+	default:
+		return false
+	}
+}
+
 func init() {
 	routerCheckRole = append(routerCheckRole, sysNoCheckRoleRouter, registerDBRouter, registerSysTableRouter)
 }
 
-func sysNoCheckRoleRouter(v1 *gin.RouterGroup ,authMiddleware *jwt.GinJWTMiddleware) {
+func sysNoCheckRoleRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
 	r1 := v1.Group("")
 	{
 		sys := apis.System{}
@@ -22,9 +56,11 @@ func sysNoCheckRoleRouter(v1 *gin.RouterGroup ,authMiddleware *jwt.GinJWTMiddlew
 	{
 		gen := tools.Gen{}
 		r.GET("/gen/preview/:tableId", gen.Preview)
-		r.GET("/gen/toproject/:tableId", gen.GenCode)
-		r.GET("/gen/apitofile/:tableId", gen.GenApiToFile)
-		r.GET("/gen/todb/:tableId", gen.GenMenuAndApi)
+		if GenWriteRoutesEnabled() {
+			r.GET("/gen/toproject/:tableId", gen.GenCode)
+			r.GET("/gen/apitofile/:tableId", gen.GenApiToFile)
+			r.GET("/gen/todb/:tableId", gen.GenMenuAndApi)
+		}
 		sysTable := tools.SysTable{}
 		r.GET("/gen/tabletree", sysTable.GetSysTablesTree)
 	}
@@ -53,4 +89,4 @@ func registerSysTableRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddl
 			tablesInfo.GET("", sysTable.GetSysTablesInfo)
 		}
 	}
-}
+}

app/other/router/gen_router_test.go

@@ -0,0 +1,151 @@
+package router
+
+import (
+	"testing"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+)
+
+// genWritingRoutes are the three that do not read. They write Go and Vue
+// source onto the host, a migration, and rows in sys_menu.
+var genWritingRoutes = []string{
+	"/api/v1/gen/toproject/:tableId",
+	"/api/v1/gen/apitofile/:tableId",
+	"/api/v1/gen/todb/:tableId",
+}
+
+// genReadingRoutes are the rest of the generator's surface. Gating the three
+// above must not cost any of these: a deployment that cannot list its tables
+// or preview a template has lost the feature, not secured it.
+var genReadingRoutes = []string{
+	"/api/v1/gen/preview/:tableId",
+	"/api/v1/gen/tabletree",
+	"/api/v1/db/tables/page",
+	"/api/v1/db/columns/page",
+}
+
+// The endpoints that write are registered where the mode says development and
+// nowhere else.
+//
+// They are in CasbinExclude, so Enforce never runs for them and any account
+// that can log in may call them. dev is the shipped default and is where the
+// generator is meant to be used; demo keeps them because DemoEvn refuses these
+// three by name and saying so is the thing the demo is for. Everything else,
+// including the empty mode a process gets when nothing set one, is refused by
+// not existing.
+func TestGeneratorWritingRoutesExistOnlyWhereTheModeAllowsIt(t *testing.T) {
+	for _, tc := range []struct {
+		mode     string
+		expected bool
+		why      string
+	}{
+		{"dev", true, "the shipped default, and where the generator is used"},
+		{"demo", true, "registered so demo mode can refuse them by name"},
+		{"test", false, "a deployment, however much it is called a test"},
+		{"prod", false, "a deployment"},
+		{"", false, "no mode configured is not a reason to trust the caller"},
+	} {
+		t.Run("mode="+tc.mode, func(t *testing.T) {
+			routes := registeredRoutes(t, tc.mode)
+			for _, writing := range genWritingRoutes {
+				if got := routes[writing]; got != tc.expected {
+					t.Errorf("mode %q: %s registered = %v, want %v (%s)",
+						tc.mode, writing, got, tc.expected, tc.why)
+				}
+			}
+		})
+	}
+}
+
+// The other direction. Refusing too much is as much of a defect as refusing
+// too little, and the read-only half of the generator is what a demo shows.
+func TestGeneratorReadingRoutesExistInEveryMode(t *testing.T) {
+	for _, mode := range []string{"dev", "demo", "test", "prod", ""} {
+		t.Run("mode="+mode, func(t *testing.T) {
+			routes := registeredRoutes(t, mode)
+			for _, reading := range genReadingRoutes {
+				if !routes[reading] {
+					t.Errorf("mode %q: %s is not registered - the gate took a route that only reads",
+						mode, reading)
+				}
+			}
+		})
+	}
+}
+
+// GenWriteRoutesEnabled is what cmd/api reads to decide whether to warn at
+// start-up. If it and the registration ever disagree, the log says one thing
+// and the engine does another, so they are checked against each other rather
+// than each against a list.
+func TestGenWriteRoutesEnabledAgreesWithWhatWasRegistered(t *testing.T) {
+	for _, mode := range []string{"dev", "demo", "test", "prod", ""} {
+		t.Run("mode="+mode, func(t *testing.T) {
+			routes := registeredRoutes(t, mode)
+
+			// registeredRoutes puts the mode back before it returns, so ask
+			// the predicate under a mode set here - about the same value the
+			// engine was just built under.
+			previous := config.ApplicationConfig.Mode
+			t.Cleanup(func() { config.ApplicationConfig.Mode = previous })
+			config.ApplicationConfig.Mode = mode
+
+			claimed := GenWriteRoutesEnabled()
+			actual := routes["/api/v1/gen/todb/:tableId"]
+			if claimed != actual {
+				t.Errorf("mode %q: GenWriteRoutesEnabled() = %v but the route was registered = %v",
+					mode, claimed, actual)
+			}
+		})
+	}
+}
+
+// The helper restores the mode before it returns, so nothing it was asked
+// about leaks into what the caller does next.
+//
+// Worth a test of its own because the failure is silent: a helper that left
+// the mode set would make every assertion after the call read a value the
+// caller did not choose, and each of those assertions would still pass for as
+// long as the leaked value happened to be the right one.
+func TestRegisteredRoutesRestoresTheModeBeforeReturning(t *testing.T) {
+	const sentinel = "not-a-mode"
+
+	previous := config.ApplicationConfig.Mode
+	t.Cleanup(func() { config.ApplicationConfig.Mode = previous })
+	config.ApplicationConfig.Mode = sentinel
+
+	registeredRoutes(t, "prod")
+
+	if got := config.ApplicationConfig.Mode; got != sentinel {
+		t.Errorf("mode after the helper returned = %q, want %q - it was left set to what "+
+			"the helper was asked about", got, sentinel)
+	}
+}
+
+// Changing the mode after the routes were built unregisters nothing.
+//
+// buildRouter has one call site, in run(), and route registration is not on
+// any phase or reload callback - so a configuration reload moves
+// config.ApplicationConfig.Mode without moving the routes. From that moment
+// GenWriteRoutesEnabled answers about a mode the engine was not built under.
+//
+// That gap is why the start-up warning tells the reader to restart rather than
+// only to change the mode. This pins it: if registration ever becomes dynamic,
+// this test fails and the message it justifies has to be revisited.
+func TestChangingTheModeDoesNotUnregisterWhatWasAlreadyBuilt(t *testing.T) {
+	built := registeredRoutes(t, "dev")
+	if !built["/api/v1/gen/todb/:tableId"] {
+		t.Fatal("built under dev without the writing routes, so this test asserts nothing")
+	}
+
+	previous := config.ApplicationConfig.Mode
+	t.Cleanup(func() { config.ApplicationConfig.Mode = previous })
+	config.ApplicationConfig.Mode = "prod"
+
+	if GenWriteRoutesEnabled() {
+		t.Fatal("the predicate still allows prod, so the disagreement below is not the one meant")
+	}
+	if !built["/api/v1/gen/todb/:tableId"] {
+		t.Error("the route left the engine when the mode changed - registration has become " +
+			"dynamic, and the start-up warning's advice to restart is now wrong")
+	}
+}

app/other/router/monitor.go

@@ -1,23 +1,82 @@
 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)
+	routerNoCheckRole = append(routerNoCheckRole, RegisterMonitorRouter)
 }
 
-// 需认证的路由代码
-func registerMonitorRouter(v1 *gin.RouterGroup) {
+// readyTimeout bounds the whole probe. What constrains it is the orchestrator's
+// per-check timeout rather than its polling period: Kubernetes allows a probe
+// one second by default, so a dependency that answers in 1.2s is recorded as a
+// failed check however promptly this handler returns. A manifest that mounts
+// this probe has to raise timeoutSeconds above this value, and
+// scripts/k8s/deploy.yml does.
+const readyTimeout = 2 * time.Second
+
+// HealthPath and ReadyPath are the two probe routes, relative to APIPrefix.
+//
+// Exported for the same reason as the prefix: the rate limiter has to be told
+// to skip them, and it is installed in a package that cannot import this one.
+const (
+	HealthPath = "/health"
+	ReadyPath  = "/ready"
+)
+
+// RegisterMonitorRouter mounts the metrics endpoint and the two probes on v1.
+//
+// Exported so that a test can put the real probes on a server of its own. The
+// alternative - a test that re-implements the handler it means to check - is
+// how a probe comes to be asserted against a copy of itself.
+//
+// 无需认证的路由代码
+func RegisterMonitorRouter(v1 *gin.RouterGroup) {
 	v1.GET("/metrics", transfer.Handler(promhttp.Handler()))
-	//健康检查
-	v1.GET("/health", func(c *gin.Context) {
+
+	// 健康检查（存活）
+	//
+	// 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(HealthPath, 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 - for as long as
+	// extend.shutdown.drain says, which is zero unless it is configured. The
+	// package comment in common/health says what that window is worth, and to
+	// whom.
+	v1.GET(ReadyPath, 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})
+	})
+
+}

app/other/router/router.go

@@ -10,6 +10,13 @@ var (
 	routerCheckRole   = make([]func(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware), 0)
 )
 
+// APIPrefix is the group every route below is registered under.
+//
+// Exported because the middleware chain in cmd/api has to name two of those
+// routes in full - the rate limiter is installed on the engine and must skip
+// the probes - and a prefix spelled in two places is a prefix that drifts.
+const APIPrefix = "/api/v1"
+
 // initRouter 路由示例
 func initRouter(r *gin.Engine, authMiddleware *jwt.GinJWTMiddleware) *gin.Engine {
 
@@ -24,7 +31,7 @@ func initRouter(r *gin.Engine, authMiddleware *jwt.GinJWTMiddleware) *gin.Engine
 // noCheckRoleRouter 无需认证的路由示例
 func noCheckRoleRouter(r *gin.Engine) {
 	// 可根据业务需求来设置接口版本
-	v1 := r.Group("/api/v1")
+	v1 := r.Group(APIPrefix)
 
 	for _, f := range routerNoCheckRole {
 		f(v1)
@@ -34,7 +41,7 @@ func noCheckRoleRouter(r *gin.Engine) {
 // checkRoleRouter 需要认证的路由示例
 func checkRoleRouter(r *gin.Engine, authMiddleware *jwt.GinJWTMiddleware) {
 	// 可根据业务需求来设置接口版本
-	v1 := r.Group("/api/v1")
+	v1 := r.Group(APIPrefix)
 
 	for _, f := range routerCheckRole {
 		f(v1, authMiddleware)

cmd/api/demo.go

@@ -5,4 +5,4 @@ import "go-admin/app/demo/router"
 func init() {
 	//注册路由 fixme 其他应用的路由，在本目录新建文件放在init方法
 	AppRouters = append(AppRouters, router.InitRouter)
-}
+}

cmd/api/gen_warning_test.go

@@ -0,0 +1,38 @@
+package api
+
+import (
+	"testing"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk/config"
+)
+
+// The warning fires exactly where the generator's writing endpoints are served
+// and nothing else refuses them.
+//
+// dev is the case the warning exists for: it is the shipped default, so it is
+// the mode a deployment that changed nothing is running in. demo serves the
+// routes too, but DemoEvn refuses all three by name, so warning there would
+// describe an exposure that is not there.
+func TestGeneratorWriteRoutesWarningFiresWhereTheExposureIs(t *testing.T) {
+	for _, tc := range []struct {
+		mode string
+		want bool
+		why  string
+	}{
+		{"dev", true, "shipped default, endpoints served and not refused"},
+		{"demo", false, "served, but DemoEvn refuses all three"},
+		{"test", false, "not served"},
+		{"prod", false, "not served"},
+		{"", false, "not served"},
+	} {
+		t.Run("mode="+tc.mode, func(t *testing.T) {
+			previous := config.ApplicationConfig.Mode
+			t.Cleanup(func() { config.ApplicationConfig.Mode = previous })
+			config.ApplicationConfig.Mode = tc.mode
+
+			if got := generatorWriteRoutesNeedWarning(); got != tc.want {
+				t.Errorf("mode %q: warning = %v, want %v (%s)", tc.mode, got, tc.want, tc.why)
+			}
+		})
+	}
+}

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

@@ -0,0 +1,117 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+	"gorm.io/gorm"
+
+	"go-admin/cmd/migrate/migration"
+	"go-admin/common/health"
+	commonmodels "go-admin/common/models"
+)
+
+// schemaCheckName is what a failing schema reports itself as in /ready's body.
+const schemaCheckName = "schema"
+
+// registerSchemaCheck adds the pending-migration check to readiness.
+//
+// Readiness rather than a refusal to start, and rather than a log line alone.
+// The two probes answer different questions: liveness is "restart me", and a
+// process whose database is on the wrong schema comes back to the same schema,
+// so restarting is not the answer. Readiness is "send me requests", and with a
+// schema the binary does not match the answer is no.
+//
+// Issue #919 is what the absence of this looked like: the process started,
+// both probes passed, and the first sign of trouble was a login failing with a
+// driver-level encoding error. Refusing to start would have been the wrong fix
+// - a process that exits tells an operator less than one that runs and says
+// why, and under an orchestrator it crash-loops - while a log line alone is
+// not something an orchestrator can act on.
+func registerSchemaCheck() {
+	health.Register(schemaCheckName, schemaCheck)
+}
+
+// schemaCheck fails while any tenant database is behind the migrations this
+// binary registers.
+//
+// Any one of them, rather than only the tenant being served: migrations are
+// applied to every database in one run, so one database behind means that run
+// did not finish. Serving the rest would let a half-applied deploy look like a
+// partial success.
+//
+// Evaluated per request rather than decided at start-up, so that running
+// migrate clears it without a restart.
+func schemaCheck(ctx context.Context) error {
+	registered := migration.RegisteredVersions()
+	if len(registered) == 0 {
+		// Nothing registered means nothing can be pending, which is the honest
+		// answer for a tree with no migrations. It is also what a broken build
+		// would produce - the registry is filled by init() in packages the
+		// binary has to link - so cmd/api's dependency test asserts the real
+		// binary links them.
+		return nil
+	}
+
+	behind := make([]string, 0, 2)
+	for name, db := range sdk.Runtime.GetAllDb() {
+		applied, err := appliedVersions(ctx, db)
+		if err != nil {
+			return fmt.Errorf("reading applied migrations for %q: %w", name, err)
+		}
+		if pending := pendingVersions(registered, applied); len(pending) > 0 {
+			behind = append(behind, fmt.Sprintf("%s is %d behind, first pending %s",
+				name, len(pending), pending[0]))
+		}
+	}
+	if len(behind) == 0 {
+		return nil
+	}
+	sort.Strings(behind)
+	return fmt.Errorf("%s; run `go-admin migrate -c <config>` and see `go-admin migrate status`",
+		strings.Join(behind, "; "))
+}
+
+// appliedVersions reads what sys_migration records for one database.
+//
+// A missing table is not an error: a database that has never been migrated has
+// applied nothing, which is exactly what the caller needs to hear, and is the
+// state a first deploy is in.
+func appliedVersions(ctx context.Context, db *gorm.DB) (map[string]bool, error) {
+	if db == nil {
+		return nil, fmt.Errorf("no database")
+	}
+	db = db.WithContext(ctx)
+	if !db.Migrator().HasTable(&commonmodels.Migration{}) {
+		return map[string]bool{}, nil
+	}
+	var rows []commonmodels.Migration
+	if err := db.Select("version").Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make(map[string]bool, len(rows))
+	for _, r := range rows {
+		out[r.Version] = true
+	}
+	return out, nil
+}
+
+// pendingVersions returns the registered versions applied does not contain.
+//
+// Split out and taking both sides as arguments because the registry is
+// process-wide and filled by init() in packages cmd/api does not import: a
+// test in this package cannot arrange it, so the arranging part is the part
+// that is not tested here.
+func pendingVersions(registered []string, applied map[string]bool) []string {
+	out := make([]string, 0)
+	for _, v := range registered {
+		if !applied[v] {
+			out = append(out, v)
+		}
+	}
+	sort.Strings(out)
+	return out
+}

cmd/api/schema_test.go

@@ -0,0 +1,124 @@
+package api
+
+import (
+	"context"
+	"os/exec"
+	"strings"
+	"testing"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+
+	commonmodels "go-admin/common/models"
+)
+
+func TestPendingVersionsReportsOnlyWhatIsNotApplied(t *testing.T) {
+	registered := []string{"1000_a", "2000_b", "3000_c"}
+	applied := map[string]bool{"1000_a": true, "3000_c": true}
+
+	got := pendingVersions(registered, applied)
+	if len(got) != 1 || got[0] != "2000_b" {
+		t.Errorf("pending = %v, want [2000_b]", got)
+	}
+}
+
+func TestPendingVersionsIsEmptyWhenTheDatabaseIsCurrent(t *testing.T) {
+	registered := []string{"1000_a", "2000_b"}
+	applied := map[string]bool{"1000_a": true, "2000_b": true}
+
+	if got := pendingVersions(registered, applied); len(got) != 0 {
+		t.Errorf("pending = %v, want none", got)
+	}
+}
+
+// A row recorded that this binary no longer registers is not pending. It is
+// the orphan `migrate status` already reports, and readiness has nothing to
+// say about it: the schema is ahead, not behind, and requests will be served
+// correctly.
+func TestPendingVersionsIgnoresAppliedRowsNothingRegisters(t *testing.T) {
+	registered := []string{"1000_a"}
+	applied := map[string]bool{"1000_a": true, "9999_gone": true}
+
+	if got := pendingVersions(registered, applied); len(got) != 0 {
+		t.Errorf("pending = %v, want none - an orphaned row is not a pending migration", got)
+	}
+}
+
+func memoryDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { db.Migrator().DropTable(&commonmodels.Migration{}) })
+	return db
+}
+
+// A first deploy has no sys_migration table. That is "nothing applied", not an
+// error: reporting it as one would make the check fail for a reason the
+// operator cannot act on, on the one deployment where every migration really
+// is pending.
+func TestAppliedVersionsTreatsAMissingTableAsNothingApplied(t *testing.T) {
+	db := memoryDB(t)
+	db.Migrator().DropTable(&commonmodels.Migration{})
+
+	got, err := appliedVersions(context.Background(), db)
+	if err != nil {
+		t.Fatalf("appliedVersions: %v", err)
+	}
+	if len(got) != 0 {
+		t.Errorf("applied = %v, want empty", got)
+	}
+}
+
+func TestAppliedVersionsReadsWhatTheTableHolds(t *testing.T) {
+	db := memoryDB(t)
+	if err := db.AutoMigrate(&commonmodels.Migration{}); err != nil {
+		t.Fatalf("automigrate: %v", err)
+	}
+	db.Create(&commonmodels.Migration{Version: "1000_a"})
+	db.Create(&commonmodels.Migration{Version: "2000_b"})
+
+	got, err := appliedVersions(context.Background(), db)
+	if err != nil {
+		t.Fatalf("appliedVersions: %v", err)
+	}
+	if !got["1000_a"] || !got["2000_b"] || len(got) != 2 {
+		t.Errorf("applied = %v, want the two rows written", got)
+	}
+}
+
+// The check is only worth anything if the registry it reads is populated in
+// the binary that serves requests, and it is filled by init() in packages
+// cmd/api does not import - cmd/migrate blank-imports them, and cmd wires both
+// subcommands into one binary.
+//
+// This cannot be asserted from an ordinary test: importing the version package
+// to look at the registry would put it in the test binary's dependency graph
+// and pass whatever the real binary links. So ask the build instead.
+//
+// Without this, dropping those blank imports leaves a check that reports
+// "nothing pending" for every database forever, and every test above still
+// passes.
+func TestTheServingBinaryLinksTheMigrationRegistry(t *testing.T) {
+	out, err := exec.Command("go", "list", "-deps", "go-admin").Output()
+	if err != nil {
+		t.Skipf("go list unavailable: %v", err)
+	}
+	deps := string(out)
+
+	const versions = "go-admin/cmd/migrate/migration/version"
+	if !strings.Contains(deps, versions+"\n") {
+		t.Errorf("the main package does not link %s, so the schema check would "+
+			"read an empty registry and report every database as current", versions)
+	}
+
+	// Negative control: a package the binary genuinely must not link, so that a
+	// `deps` that somehow contained everything would fail here rather than pass
+	// the assertion above for the wrong reason.
+	const notLinked = "go-admin/tools/checksilent"
+	if strings.Contains(deps, notLinked+"\n") {
+		t.Errorf("%s is in the binary's dependency closure, so this test cannot "+
+			"tell a real link from a query that matches anything", notLinked)
+	}
+}

cmd/api/server.go

@@ -2,10 +2,13 @@ package api
 
 import (
 	"context"
+	"crypto/tls"
 	"fmt"
+	"net"
 	"net/http"
 	"os"
 	"os/signal"
+	"sync/atomic"
 	"syscall"
 	"time"
 
@@ -14,16 +17,21 @@ 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"
 
 	"go-admin/app/admin/models"
 	"go-admin/app/admin/router"
 	"go-admin/app/jobs"
+	otherrouter "go-admin/app/other/router"
 	"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"
@@ -60,30 +68,121 @@ 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)
+
+	// Registered before the configuration is read, because it registers a
+	// callback rather than reading anything: the check runs per request and
+	// asks the databases that exist then.
+	registerSchemaCheck()
+
 	//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 {
+	// Resolved first, and used both for the line it prints and for the
+	// shutdown that spends it. Reading the configuration again at signal time
+	// would let the two disagree, and the sum that gets printed is the whole
+	// point of printing it.
+	//
+	// Refused rather than corrected, and refused before anything is built: a
+	// budget that cannot be spent as written is a configuration error, and the
+	// moment to say so is while nothing depends on this process yet.
+	seconds, err := ext.ExtConfig.Shutdown.Budget()
+	if err != nil {
+		return err
+	}
+	reportShutdownBudget(seconds)
+
 	if config.ApplicationConfig.Mode == pkg.ModeProd.String() {
 		gin.SetMode(gin.ReleaseMode)
 	}
-	initRouter()
-
-	runStartupHooks()
+	buildRouter()
+	reportGeneratorWriteRoutes()
 
 	srv := &http.Server{
 		Addr:         fmt.Sprintf("%s:%d", config.ApplicationConfig.Host, config.ApplicationConfig.Port),
@@ -92,12 +191,6 @@ func run() error {
 		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("")
@@ -122,18 +215,10 @@ func run() error {
 	// arming is separate from waiting.
 	quit, disarmStopSignals := armStopSignals()
 
-	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)
-			}
-		}
-	}()
+	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:"))
@@ -145,26 +230,220 @@ func run() error {
 	fmt.Printf("%s Enter Control + C Shutdown Server \r\n", pkg.GetCurrentTimeStr())
 
 	<-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()
-
-	log.Info("Shutdown Server ... ")
-	if err := shutdownServer(srv, shutdownTimeout); err != nil {
+	serverErr, cleanupErr := gracefulShutdown(srv, quit, disarmStopSignals, budgetFrom(seconds))
+	if serverErr != 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)
+		// which is when the cleanup that ran after it mattered most.
+		log.Error("Server Shutdown: ", serverErr)
+	}
+	if cleanupErr != nil {
+		log.Error("Cleanup: ", cleanupErr)
 	}
-	log.Info("Server exiting")
 
 	return nil
 }
 
-// shutdownTimeout is how long Shutdown waits for in-flight requests. It plus
-// whatever cleanup follows has to stay inside the orchestrator's grace period
-// - `docker stop` allows 10s by default before it sends SIGKILL.
-const shutdownTimeout = 5 * time.Second
+// budget is the three waits a shutdown spends, in the order it spends them.
+type budget struct {
+	drain   time.Duration
+	server  time.Duration
+	cleanup time.Duration
+}
+
+// budgetFrom turns the resolved seconds into the durations the sequence waits
+// on.
+func budgetFrom(s ext.ShutdownBudget) budget {
+	return budget{
+		drain:   time.Duration(s.Drain) * time.Second,
+		server:  time.Duration(s.Server) * time.Second,
+		cleanup: time.Duration(s.Cleanup) * time.Second,
+	}
+}
+
+// defaultBudget is what a process with no extend.shutdown section spends.
+func defaultBudget() budget {
+	return budget{drain: drainTimeout, server: shutdownTimeout, cleanup: cleanupTimeout}
+}
+
+// gracefulShutdown takes the process down in the order that gives something
+// else a chance to notice first.
+//
+// The whole order lives here, and run() is not the only caller: the signal
+// tests run this function rather than reproducing it. A test that reproduces a
+// sequence asserts against its own copy and stays green while the sequence it
+// was written for regresses.
+//
+// The caller has already taken the first signal off quit. quit is handed on
+// because a second signal during the drain window ends the window early -
+// somebody sending another kill wants this over with sooner - and because
+// until the window is over that signal must not reach the default handler and
+// kill the process outright.
+//
+// disarm is therefore called at the end of the window rather than on the first
+// signal. After it, a second signal is handled by the default disposition
+// again, which is the only way out of a Shutdown or a cleanup callback that
+// never returns. Restoring it any earlier would put every ordinary shutdown
+// inside that escape hatch for the whole length of the drain, where before
+// this window existed only a hung callback could reach it.
+//
+// The two waits' errors are returned separately rather than logged: they fail
+// for different reasons, and the caller decides what each is worth.
+func gracefulShutdown(srv *http.Server, quit <-chan os.Signal, disarm func(), b budget) (serverErr, cleanupErr error) {
+	// 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.
+	// That order is necessary and not sufficient: with nothing between this
+	// line and the listener closing, the two are microseconds apart and a
+	// poller on a multi-second interval sees the refused connection instead of
+	// the 503. The window below is what turns the order into something
+	// observable - extend.shutdown.drain, which is zero unless it is
+	// configured.
+	health.BeginDraining()
+
+	// Keep-alive off for the same window, and for the same reason. The server
+	// keeps connections alive while !disableKeepAlives && !shuttingDown(), and
+	// shuttingDown() is only set by Shutdown itself - so without this line
+	// every pooled connection stays open for the whole drain and is cut at the
+	// end of it anyway, which is the cost of the window without its benefit.
+	// This is the switch Shutdown flips, moved earlier by the window's length:
+	// answers now carry Connection: close, and the idle connections a balancer
+	// is holding are closed at once rather than when it next tries to use one.
+	srv.SetKeepAlivesEnabled(false)
+
+	drain(quit, b.drain)
+
+	// Restored here, not on the first signal: from this point a second signal
+	// must reach the default handler, so a shutdown that hangs can still be
+	// interrupted.
+	disarm()
+
+	log.Info("Shutdown Server ... ")
+	serverErr = shutdownServer(srv, b.server)
+	// Runs whether or not the wait above failed, and deliberately so: Shutdown
+	// reports an error exactly when connections were still in flight, which is
+	// when there is most left to clean up after.
+	cleanupErr = runShutdownHooks(b.cleanup)
+	log.Info("Server exiting")
+
+	return serverErr, cleanupErr
+}
+
+// drain keeps serving for d, or until another stop signal arrives.
+//
+// Requests are answered normally throughout. Refusing them would move the
+// outage earlier rather than avoid it - the point of the window is that this
+// instance is still able to work while whoever routes to it stops routing.
+func drain(quit <-chan os.Signal, d time.Duration) {
+	if d <= 0 {
+		return
+	}
+	log.Infof("Draining for %s: still serving, /ready answers 503 from here", d)
+
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-quit:
+		log.Info("Second signal during the drain window, closing the listener now")
+	case <-timer.C:
+	}
+}
+
+// Reference stop grace periods, printed when nothing was configured to compare
+// against. They are three times apart, which is why the check below needs a
+// configured value rather than a constant of its own: a budget that overruns
+// under one of them fits comfortably under the other.
+const (
+	dockerStopGraceSeconds = 10
+	kubernetesGraceSeconds = 30
+)
+
+// reportGeneratorWriteRoutes says whether this process serves the code
+// generator's writing endpoints, and to whom.
+//
+// The endpoints are gated on the mode, and the shipped configuration says dev -
+// so the deployment most likely to be exposed is the one that changed nothing,
+// and the one least likely to go looking. Silence there would leave the gate
+// technically correct and practically useless.
+//
+// Nothing is said in demo mode. The routes are registered, but DemoEvn refuses
+// all three by name, so a warning would describe an exposure that is not there.
+func reportGeneratorWriteRoutes() {
+	if !generatorWriteRoutesNeedWarning() {
+		return
+	}
+	log.Warnf("the code generator's writing endpoints are served in mode %q: "+
+		"/api/v1/gen/{toproject,apitofile,todb} write Go and Vue source onto this host and rows "+
+		"into this database, and they are in CasbinExclude, so any account that can log in may "+
+		"call them. Set application.mode to prod or test on anything that is not a workstation, "+
+		"then restart: these routes were registered at start-up and a configuration reload does "+
+		"not rebuild them.",
+		config.ApplicationConfig.Mode)
+}
+
+// generatorWriteRoutesNeedWarning reports whether there is an exposure to warn
+// about: the endpoints are served, and nothing else is refusing them.
+//
+// Split from the logging so the decision can be tested. A warning nobody can
+// make fire is indistinguishable from no warning at all, and this one exists
+// precisely for the case nobody is looking at.
+func generatorWriteRoutesNeedWarning() bool {
+	return otherrouter.GenWriteRoutesEnabled() && config.ApplicationConfig.Mode != "demo"
+}
+
+// reportShutdownBudget states what a shutdown will spend and whether it fits.
+//
+// The sum is taken from the resolved values, not from the configuration file:
+// a field left out of extend.shutdown still costs its default, so adding up
+// what was written down understates the budget by exactly the fields nobody
+// wrote.
+func reportShutdownBudget(s ext.ShutdownBudget) {
+	log.Infof("shutdown budget: drain %ds + server %ds + cleanup %ds = %ds",
+		s.Drain, s.Server, s.Cleanup, s.Total())
+
+	if s.Grace <= 0 {
+		log.Infof("shutdown budget: extend.shutdown.grace is not set, so nothing is compared against it - "+
+			"for reference `docker stop` allows %ds and Kubernetes terminationGracePeriodSeconds defaults to %ds",
+			dockerStopGraceSeconds, kubernetesGraceSeconds)
+		return
+	}
+	if over := s.Overrun(); over > 0 {
+		// A minimum, not a target. This is somebody else's deployment under
+		// constraints this process cannot see, so the honest thing to state is
+		// how much is missing - the repository's own files are where there is
+		// standing to ask for headroom on top, and checksilent does that.
+		log.Warnf("shutdown budget of %ds does not fit inside the %ds of extend.shutdown.grace: "+
+			"SIGKILL arrives while the cleanup callbacks are still running, and the work they "+
+			"were about to finish is lost. It needs at least %ds more, or %ds less budget.",
+			s.Total(), s.Grace, over, over)
+		return
+	}
+	log.Infof("shutdown budget of %ds fits inside the %ds of extend.shutdown.grace", s.Total(), s.Grace)
+}
+
+// The budgets a shutdown spends when extend.shutdown configures nothing:
+// drainTimeout keeps the process serving after the stop signal, then
+// shutdownTimeout waits for in-flight requests, then cleanupTimeout is what
+// the BeforeExit callbacks get.
+//
+// The seconds come from config, which is where an absent field falls back, so
+// the default is one number rather than two that can drift apart.
+//
+// They are consumed one after the other, so their sum is what has to stay
+// inside the orchestrator's grace period: `docker stop` allows 10s by default
+// before it sends SIGKILL, and 0+5+3 leaves room for the process to finish
+// returning. Raising one without lowering another buys nothing - the budget
+// that runs out is the orchestrator's, and reportShutdownBudget is what says
+// so at start-up.
+var (
+	drainTimeout    = time.Duration(ext.DefaultDrainSeconds) * time.Second
+	shutdownTimeout = time.Duration(ext.DefaultServerSeconds) * time.Second
+	cleanupTimeout  = time.Duration(ext.DefaultCleanupSeconds) * time.Second
+)
 
 // armStopSignals registers for the stop signals and returns the channel they
 // arrive on together with the function that restores the default disposition.
@@ -185,6 +464,66 @@ func armStopSignals() (<-chan os.Signal, func()) {
 	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
@@ -196,6 +535,34 @@ func shutdownServer(srv *http.Server, timeout time.Duration) error {
 	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
@@ -243,10 +610,38 @@ func initRouter() {
 		r.Use(handler.TlsHandler())
 	}
 	//r.Use(middleware.Metrics())
-	r.Use(common.Sentinel()).
+	r.Use(exemptProbes(common.Sentinel())).
 		Use(common.RequestId(pkg.TrafficKey)).
 		Use(api.SetRequestLogger)
 
 	common.InitMiddleware(r)
 
 }
+
+// probePaths are the two routes the rate limiter must not answer for.
+var probePaths = map[string]bool{
+	otherrouter.APIPrefix + otherrouter.HealthPath: true,
+	otherrouter.APIPrefix + otherrouter.ReadyPath:  true,
+}
+
+// exemptProbes wraps a middleware so the health and readiness routes skip it.
+//
+// The limiter is installed on the engine and the probes are routes like any
+// other, so above the threshold they are answered with 429 as well. A liveness
+// probe that collects 429s fails its threshold and the container is restarted,
+// which takes capacity out of a deployment that is already short of it and
+// pushes the rest closer to the threshold - the limiter working exactly as
+// intended is what causes it. It is the argument common/health makes about
+// restarting a process whose database is unreachable, applied to load.
+//
+// Wrapping rather than teaching the limiter about these paths: the limiter
+// lives under common/, which may not import the package that registers them.
+func exemptProbes(h gin.HandlerFunc) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if probePaths[c.FullPath()] {
+			c.Next()
+			return
+		}
+		h(c)
+	}
+}

cmd/api/shutdown_test.go

@@ -0,0 +1,139 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	otherrouter "go-admin/app/other/router"
+	"go-admin/common/health"
+	ext "go-admin/config"
+)
+
+// The seconds in the configuration and the durations the sequence waits on are
+// two spellings of one budget, and only one of them is printed at start-up.
+func TestBudgetFromSeconds(t *testing.T) {
+	got := budgetFrom(ext.ShutdownBudget{Drain: 10, Server: 5, Cleanup: 3})
+	want := budget{
+		drain:   10 * time.Second,
+		server:  5 * time.Second,
+		cleanup: 3 * time.Second,
+	}
+	if got != want {
+		t.Errorf("budgetFrom = %+v, want %+v", got, want)
+	}
+}
+
+// The package variables and config.Default*Seconds have to say the same thing.
+// They are the same default written twice - once as durations for the shutdown
+// and once as seconds for the fallback - and a deployment that configures
+// nothing is entitled to one answer, not two.
+func TestDefaultBudgetIsTheConfiguredFallback(t *testing.T) {
+	unconfigured, err := ext.Shutdown{}.Budget()
+	if err != nil {
+		t.Fatalf("the empty section did not resolve: %v", err)
+	}
+	if got, want := defaultBudget(), budgetFrom(unconfigured); got != want {
+		t.Errorf("defaultBudget = %+v, want the unconfigured budget %+v", got, want)
+	}
+}
+
+// The rate limiter must not answer for the probes.
+//
+// It is installed on the engine, so without this the probes are limited like
+// any other route and answer 429 above the threshold. A liveness probe that
+// collects 429s fails its threshold and the container is restarted - taking
+// capacity out of a deployment that is already short of it and pushing the
+// rest closer to the threshold. The limiter working exactly as designed is
+// what would cause it.
+//
+// The stand-in rejects everything rather than being a real limiter: what is
+// under test is which requests reach it, and a real one would need the traffic
+// to cross a threshold before it said anything.
+func TestTheProbesSkipTheRateLimiter(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	var reached []string
+	r := gin.New()
+	r.Use(exemptProbes(func(c *gin.Context) {
+		reached = append(reached, c.FullPath())
+		c.AbortWithStatus(http.StatusTooManyRequests)
+	}))
+	v1 := r.Group(otherrouter.APIPrefix)
+	otherrouter.RegisterMonitorRouter(v1)
+	v1.GET("/business", func(c *gin.Context) { c.Status(http.StatusOK) })
+
+	for _, tc := range []struct {
+		path    string
+		limited bool
+	}{
+		{otherrouter.APIPrefix + otherrouter.HealthPath, false},
+		{otherrouter.APIPrefix + otherrouter.ReadyPath, false},
+		// Not a probe, and deliberately not exempt: the exemption is for the
+		// two routes an orchestrator acts on, not for everything under
+		// /api/v1 that happens to be unauthenticated.
+		{otherrouter.APIPrefix + "/metrics", true},
+		{otherrouter.APIPrefix + "/business", true},
+	} {
+		t.Run(tc.path, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, tc.path, nil))
+
+			if tc.limited {
+				if w.Code != http.StatusTooManyRequests {
+					t.Errorf("answered %d, want the middleware's 429 - it was skipped for a route that is not a probe", w.Code)
+				}
+				return
+			}
+			if w.Code == http.StatusTooManyRequests {
+				t.Errorf("answered 429; a probe that can be rate-limited gets the container restarted under load")
+			}
+		})
+	}
+
+	// Said separately, because a probe could also answer 429 by itself: what
+	// has to be true is that the middleware never saw the request.
+	for _, p := range reached {
+		if probePaths[p] {
+			t.Errorf("the middleware ran for %s", p)
+		}
+	}
+}
+
+// /health has to stay 200 while draining, and it is the assertion most easily
+// lost by accident: making the liveness probe follow the readiness flag reads
+// like tidying up, and it turns every rolling restart into a kubelet-issued
+// kill part-way through the drain.
+func TestHealthStaysUpWhileDraining(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	v1 := r.Group(otherrouter.APIPrefix)
+	otherrouter.RegisterMonitorRouter(v1)
+
+	ask := func(path string) int {
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+		return w.Code
+	}
+
+	if got := ask(otherrouter.APIPrefix + otherrouter.HealthPath); got != http.StatusOK {
+		t.Fatalf("/health answered %d before draining, want 200", got)
+	}
+
+	// Process-wide and one-way - nothing clears it - so this is the last thing
+	// in this package that may run in-process and care. Everything else that
+	// exercises draining does so in a child process of its own.
+	health.BeginDraining()
+
+	if got := ask(otherrouter.APIPrefix + otherrouter.HealthPath); got != http.StatusOK {
+		t.Errorf("/health answered %d while draining, want 200 - liveness is "+
+			"\"should I restart you\", and the answer during a drain is no", got)
+	}
+	if got := ask(otherrouter.APIPrefix + otherrouter.ReadyPath); got != http.StatusServiceUnavailable {
+		t.Errorf("/ready answered %d while draining, want 503", got)
+	}
+}

cmd/api/signal_test.go

@@ -1,33 +1,65 @@
 package api
 
 import (
+	"context"
 	"fmt"
+	"io"
 	"net"
 	"net/http"
 	"os"
 	"os/exec"
+	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"testing"
 	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-admin-team/go-admin-core/v2/sdk"
+
+	otherrouter "go-admin/app/other/router"
 )
 
 // 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.
+// are global. So the test re-executes itself as a child, and the child runs
+// gracefulShutdown - the same function run() runs, not a second copy of the
+// sequence. A test that reproduces the sequence asserts against its own copy:
+// move BeginDraining after the drain window and the process regresses while
+// the test stays green, which is the failure mode this file exists to avoid.
 //
-// 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.
+// The child serves the real probe routes on an http.Server of its own rather
+// than the configured 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. /ready answers 503 either way - with
+// no database its checks fail - so the assertions below are on the draining
+// answer specifically, not on the status code alone.
 const (
-	childEnv       = "GO_ADMIN_SIGNAL_CHILD"
-	childStuckEnv  = "GO_ADMIN_SIGNAL_CHILD_STUCK"
-	childHangConn  = "GO_ADMIN_SIGNAL_CHILD_HANGCONN"
-	markerReady    = "CHILD-READY"
-	markerSignal   = "CHILD-SIGNAL"
-	markerShutdown = "CHILD-SHUTDOWN-OK"
-	markerExiting  = "CHILD-EXITING"
+	childEnv         = "GO_ADMIN_SIGNAL_CHILD"
+	childStuckEnv    = "GO_ADMIN_SIGNAL_CHILD_STUCK"
+	childHangConn    = "GO_ADMIN_SIGNAL_CHILD_HANGCONN"
+	childSlowCleanup = "GO_ADMIN_SIGNAL_CHILD_SLOWCLEANUP"
+	childDrainMS     = "GO_ADMIN_SIGNAL_CHILD_DRAIN_MS"
+	markerAddr       = "CHILD-ADDR"
+	markerReady      = "CHILD-READY"
+	markerSignal     = "CHILD-SIGNAL"
+	markerShutdown   = "CHILD-SHUTDOWN-OK"
+	markerCleanup    = "CHILD-CLEANUP-RAN"
+	markerTook       = "CHILD-TOOK-NS"
+	markerExiting    = "CHILD-EXITING"
+)
+
+// childPingRoute is an ordinary route, registered beside the probes so the
+// window can be checked for what it promises: requests arriving inside it are
+// served, not refused. Refusing them would move the outage earlier instead of
+// avoiding it.
+const childPingRoute = "/signal-test-ping"
+
+var (
+	readyPath  = otherrouter.APIPrefix + otherrouter.ReadyPath
+	healthPath = otherrouter.APIPrefix + otherrouter.HealthPath
+	pingPath   = otherrouter.APIPrefix + childPingRoute
 )
 
 // TestSignalChild is the child process. It is skipped in a normal run.
@@ -36,6 +68,12 @@ func TestSignalChild(t *testing.T) {
 		t.Skip("child process entry point")
 	}
 
+	gin.SetMode(gin.TestMode)
+	engine := gin.New()
+	v1 := engine.Group(otherrouter.APIPrefix)
+	otherrouter.RegisterMonitorRouter(v1)
+	v1.GET(childPingRoute, func(c *gin.Context) { c.String(http.StatusOK, "pong") })
+
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	if err != nil {
 		fmt.Println("listen:", err)
@@ -47,7 +85,7 @@ func TestSignalChild(t *testing.T) {
 	// finds nothing to wait for and returns immediately.
 	accepted := make(chan struct{}, 1)
 	srv := &http.Server{
-		Handler: http.NewServeMux(),
+		Handler: engine,
 		ConnState: func(_ net.Conn, state http.ConnState) {
 			if state == http.StateNew {
 				select {
@@ -59,6 +97,45 @@ func TestSignalChild(t *testing.T) {
 	}
 	go func() { _ = srv.Serve(ln) }()
 
+	// The budget the child spends. Nothing here calls bootstrap.SetupConfig, so
+	// with no environment set this is the budget of a deployment that
+	// configures no extend.shutdown section at all.
+	b := defaultBudget()
+	if ms := os.Getenv(childDrainMS); ms != "" {
+		n, err := strconv.Atoi(ms)
+		if err != nil {
+			fmt.Println("drain:", err)
+			os.Exit(4)
+		}
+		b.drain = time.Duration(n) * time.Millisecond
+	}
+
+	// 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.
+	sdk.Runtime.SetShutdown(func(ctx context.Context) {
+		switch {
+		case os.Getenv(childStuckEnv) == "1":
+			// Stands in for a cleanup hook that never finishes. The point of
+			// restoring the signal disposition after the drain window is that
+			// a second signal still reaches the default handler and kills this.
+			time.Sleep(2 * time.Minute)
+		case 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()
+	})
+	switch {
+	case os.Getenv(childStuckEnv