docs: 记录系统管理边界与回归流程 (#69)

docs/02-architecture-and-code-map.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Architecture-and-Code-Map.-
-wiki_revision: bdf8a4ce362f9d404fb45a87b9347e2381689f16
-synchronized_at: 2026-08-26T09:59:54Z
+wiki_revision: 8fb1f5622b7cfe6ecb1872623cd51397bfd043b5
+synchronized_at: 2026-08-26T14:50:35Z
 <!-- gitea-wiki-mirror:end -->
 
 # 架构与代码地图
@@ -477,3 +477,13 @@ Migration 000009 将原“Chorus 运营”平铺导航改为四个一级分组
 
 `chorus_operator` 的菜单、菜单 API 和 Casbin 基线全部由 migration 管理。up 在删除旧父菜单前拒绝未知子菜单，down 在删除四个新父菜单前同样拒绝未知子菜单；down 恢复“Chorus 运营”父菜单、8 个业务入口原顺序和“用户管理”旧显示名。生产仍禁止 AutoMigrate。#67 完成后才能开放系统管理页面，因为现有 go-admin handler 的写路由和管理员保护仍需收紧。
 <!-- issue-66:end -->
+
+<!-- issues-67-69-system-admin:start -->
+## #67-#69 管理端系统管理边界
+
+管理端导航由 migration 000009 维护，固定分为“生成配置、运行监控、用户与访问、系统管理”四组，共 13 个叶子入口。系统管理只恢复管理员账号、角色权限、菜单结构、接口清单和登录日志五个模块；部门、岗位、字典、参数、操作日志、任务、监控和开发工具不属于 Chorus 管理端交付范围。
+
+后端入口位于 `admin/app/admin/router`、`admin/app/admin/apis` 和 `admin/app/admin/service`。管理员账号只使用账号、昵称、角色、状态、密码和备注；不依赖部门、岗位、手机号或邮箱。菜单、接口、登录日志只注册 GET 路由；管理员和角色保留受保护的写操作。前端页面位于 `admin-ui/src/views/admin/sys-*`，动态组件仍由 `admin-ui/src/store/modules/permission.js` 的视图索引解析。
+
+管理员与终端用户继续分表：管理端使用 `sys_user`，Portal 使用 `users`，两者凭据和权限不得复用。保护判断在后端 service 中执行，前端禁用按钮只是交互提示。
+<!-- issues-67-69-system-admin:end -->

docs/03-business-rules-and-glossary.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 565ea24330f7bda365a3a067b7fe535368ceb8e5
-synchronized_at: 2026-08-26T10:00:00Z
+wiki_revision: a56ba63d7962719016a38ae85e22f8b00af765ea
+synchronized_at: 2026-08-26T14:50:42Z
 <!-- gitea-wiki-mirror:end -->
 
 # 业务规则与术语
@@ -217,3 +217,14 @@ synchronized_at: 2026-08-26T10:00:00Z
 - 部门、岗位、字典、参数、操作日志、定时任务、服务监控和开发工具不属于 Chorus 管理端范围。
 - 菜单、API、角色菜单和 Casbin 关系只经版本化 migration 演进；页面不得成为这些记录的配置事实来源。
 <!-- issue-66:end -->
+
+<!-- issues-67-69-admin-protection:start -->
+## 管理员与内置角色保护
+
+- 状态值 `2` 表示有效，`1` 表示停用。
+- 当前登录管理员不得停用或删除；后端返回稳定标识 `ADMIN_CURRENT_ACCOUNT_PROTECTED`。
+- 停用或删除有效管理员后必须至少剩余一个有效管理员；后端在事务中锁定有效管理员行并返回 `ADMIN_LAST_ACTIVE_ACCOUNT_PROTECTED`。
+- 内置角色 `chorus_operator` 的角色名、权限字符和有效状态不得改变，也不得删除；允许调整菜单授权。拒绝标识为 `ADMIN_BUILT_IN_ROLE_PROTECTED`。
+- 菜单结构、接口清单和登录日志是只读管理资料。前端不提供写入口，后端不注册对应写路由；不得通过恢复 go-admin 默认按钮绕过。
+- 管理端管理员、终端用户、真实凭据、请求正文和 JWT 不得写入错误、日志、测试、工单、Wiki 或截图。
+<!-- issues-67-69-admin-protection:end -->

docs/04-local-development-and-verification.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.-
-wiki_revision: 15b778ecf22e191fb196ca94f73141b385a1c941
-synchronized_at: 2026-08-25T07:09:22Z
+wiki_revision: e2281f6e17e04a96cc98e0111c87464e37bead9a
+synchronized_at: 2026-08-26T14:50:51Z
 <!-- gitea-wiki-mirror:end -->
 
 # 本地开发与验证
@@ -571,3 +571,36 @@ $env:NODE_OPTIONS = $null
 #47、#52 和 #53 已由用户于 2026-08-25 明确验收通过；上述未执行项继续作为已知验证限制保留。
 
 <!-- issue-47-integration:end -->
+
+<!-- issues-67-69-system-verification:start -->
+## 管理端系统管理回归
+
+常规回归从仓库根目录执行：
+
+```powershell
+go test ./...
+go vet ./...
+go build ./...
+go -C admin test ./...
+go -C admin vet ./...
+go -C admin build ./...
+corepack pnpm --dir admin-ui lint
+corepack pnpm --dir admin-ui test:unit -- --runInBand
+$env:NODE_OPTIONS = "--max-old-space-size=4096"
+corepack pnpm --dir admin-ui build:prod
+$env:NODE_OPTIONS = $null
+corepack pnpm --dir admin-ui exec playwright test tests/e2e/system-management.spec.ts --reporter=line
+```
+
+MySQL 保护与迁移测试只允许指向精确命名的可丢弃库 `chorus_test`：
+
+```powershell
+$env:CHORUS_MIGRATION_TEST_DATABASE = "chorus_test"
+$env:CHORUS_RUN_MIGRATION_TESTS = "1"
+go test -count=1 -run '^TestMigrationsUpDownUpMySQL$' ./migrations
+$env:CHORUS_RUN_ADMIN_TESTS = "1"
+go -C admin test -count=1 -run '^TestAdminProtectionMySQL$' ./app/admin/service
+```
+
+两项测试都会在连接后再次核对数据库名；迁移测试会重置目标库。浏览器测试使用合成导航、账号和空列表响应，不需要真实登录凭据，也不调用 Provider。
+<!-- issues-67-69-system-verification:end -->

docs/05-common-changes.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Common-Changes
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Common-Changes.-
-wiki_revision: af13a8db3609a2b85b9dc46441bc3bd716b93c8e
-synchronized_at: 2026-08-24T07:59:44Z
+wiki_revision: de39b6a62635619c240fcbb68d2d94d76e95b38c
+synchronized_at: 2026-08-26T14:51:06Z
 <!-- gitea-wiki-mirror:end -->
 
 # 常见修改指南
@@ -114,3 +114,13 @@ python dev_scripts/harness.py check --strict
 - 改变已确认原型的结构、流程、状态、权限或异常处理；
 - 真实上游测试可能反复消耗额度；
 - 无法判断风险或同一位置两次仍无根因。
+
+<!-- issues-67-69-common-changes:start -->
+## 修改管理端系统模块
+
+1. 导航名称、分组、路径或组件变化先修改版本化 migration，并保持 up/down 可验证；不要在运行时使用 AutoMigrate 或手工改共享库。
+2. 新系统页面必须同时核对 `sys_menu`、`sys_api`、`sys_menu_api_rule`、`sys_role_menu` 和 `sys_casbin_rule`。动态组件写为相对 `src/views` 的路径，不带 `@/views`、前导斜杠或 `.vue`。
+3. 菜单、接口和登录日志保持只读。需要新增写能力时必须另建工单并重新做权限、安全和 UI 设计，不得只恢复旧 API 模块中的函数。
+4. 管理员状态和角色保护必须在 service 层保留；修改时同时覆盖当前管理员、最后管理员、内置角色改名/停用/删除。
+5. 最小验证包括 Admin Go 全量测试、Admin UI lint/单测/生产构建、系统管理 Playwright E2E，以及 migration 静态测试。涉及 migration 时追加隔离 MySQL up/down/up。
+<!-- issues-67-69-common-changes:end -->

docs/06-troubleshooting.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Troubleshooting
-wiki_revision: 9803ea981876455054c5598a38b21fd030211d4c
-synchronized_at: 2026-08-26T01:08:16Z
+wiki_revision: 24b997f29b1dc7d9955f0e0a03223a3944f508c9
+synchronized_at: 2026-08-26T14:51:18Z
 <!-- gitea-wiki-mirror:end -->
 
 # 故障排查
@@ -150,3 +150,13 @@ LIMIT 10;
 5. `last_used_at` 在一分钟内不变化是节流行为，不代表认证未发生。判断调用结果使用请求状态和对应提交审计。
 6. go-admin 鉴权失败可能使用 HTTP 200 包装 JSON `code=401|403`；排查权限时同时检查 JSON 业务码、JWT 和 Casbin，不把 HTTP 200 误判为已授权。
 7. 任何 summary 出现 Prompt、完整 Key、`public_id`、`secret_hash`、Authorization、Cookie、响应正文或原始 IP 都属于安全缺陷，应立即停止相关入口并建立缺陷工单，不直接清理审计数据。
+
+<!-- issues-67-69-system-troubleshooting:start -->
+## 系统管理页面排错
+
+- 点击导航出现“Cannot find module”：先核对 migration 的 `component` 是否对应 `admin-ui/src/views/<component>.vue`，再运行 route-view 单测；不要拼接 `@/views`。
+- 系统页面返回 403：核对角色是否关联对应菜单、菜单是否关联 GET API、Casbin 是否存在同路径和方法。菜单、接口、登录日志不应出现 POST、PUT 或 DELETE 授权。
+- 停用或删除管理员返回 409：检查响应中的三个稳定保护标识；这是安全拒绝，不应通过改数据库或隐藏错误绕过。
+- Admin UI 默认双 bundle 构建出现 V8 OOM：先停止本项目开发服务、释放内存并设置 `NODE_OPTIONS=--max-old-space-size=4096` 后重跑。不得把只完成 legacy bundle 记录成完整构建通过。
+- Supervisor 被强制结束后无法重启：确认 PID 文件指向的进程确实不存在后，才能清理过期 PID 并重新启动；随后核对 Portal、Admin API、Admin UI 三个监听端口。
+<!-- issues-67-69-system-troubleshooting:end -->