From ef3ad272b5e47b63728f3192fc2a9ade058cbb7e Mon Sep 17 00:00:00 2001 From: ila Date: Wed, 26 Aug 2026 22:55:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E7=B3=BB=E7=BB=9F?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E8=BE=B9=E7=95=8C=E4=B8=8E=E5=9B=9E=E5=BD=92?= =?UTF-8?q?=E6=B5=81=E7=A8=8B=20(#69)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/02-architecture-and-code-map.md | 14 ++++++- docs/03-business-rules-and-glossary.md | 15 +++++++- docs/04-local-development-and-verification.md | 37 ++++++++++++++++++- docs/05-common-changes.md | 14 ++++++- docs/06-troubleshooting.md | 14 ++++++- 5 files changed, 84 insertions(+), 10 deletions(-) diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 7397615..35d396e 100644 --- a/docs/02-architecture-and-code-map.md +++ b/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 # 架构与代码地图 @@ -477,3 +477,13 @@ Migration 000009 将原“Chorus 运营”平铺导航改为四个一级分组 `chorus_operator` 的菜单、菜单 API 和 Casbin 基线全部由 migration 管理。up 在删除旧父菜单前拒绝未知子菜单，down 在删除四个新父菜单前同样拒绝未知子菜单；down 恢复“Chorus 运营”父菜单、8 个业务入口原顺序和“用户管理”旧显示名。生产仍禁止 AutoMigrate。#67 完成后才能开放系统管理页面，因为现有 go-admin handler 的写路由和管理员保护仍需收紧。 + + +## #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 中执行，前端禁用按钮只是交互提示。 + diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index 1cbc153..d24a3b6 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/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 # 业务规则与术语 @@ -217,3 +217,14 @@ synchronized_at: 2026-08-26T10:00:00Z - 部门、岗位、字典、参数、操作日志、定时任务、服务监控和开发工具不属于 Chorus 管理端范围。 - 菜单、API、角色菜单和 Casbin 关系只经版本化 migration 演进；页面不得成为这些记录的配置事实来源。 + + +## 管理员与内置角色保护 + +- 状态值 `2` 表示有效，`1` 表示停用。 +- 当前登录管理员不得停用或删除；后端返回稳定标识 `ADMIN_CURRENT_ACCOUNT_PROTECTED`。 +- 停用或删除有效管理员后必须至少剩余一个有效管理员；后端在事务中锁定有效管理员行并返回 `ADMIN_LAST_ACTIVE_ACCOUNT_PROTECTED`。 +- 内置角色 `chorus_operator` 的角色名、权限字符和有效状态不得改变，也不得删除；允许调整菜单授权。拒绝标识为 `ADMIN_BUILT_IN_ROLE_PROTECTED`。 +- 菜单结构、接口清单和登录日志是只读管理资料。前端不提供写入口，后端不注册对应写路由；不得通过恢复 go-admin 默认按钮绕过。 +- 管理端管理员、终端用户、真实凭据、请求正文和 JWT 不得写入错误、日志、测试、工单、Wiki 或截图。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 0efdf00..10731c0 100644 --- a/docs/04-local-development-and-verification.md +++ b/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 # 本地开发与验证 @@ -571,3 +571,36 @@ $env:NODE_OPTIONS = $null #47、#52 和 #53 已由用户于 2026-08-25 明确验收通过；上述未执行项继续作为已知验证限制保留。 + + +## 管理端系统管理回归 + +常规回归从仓库根目录执行： + +```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。 + diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index 93e252f..c862d42 100644 --- a/docs/05-common-changes.md +++ b/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 # 常见修改指南 @@ -114,3 +114,13 @@ python dev_scripts/harness.py check --strict - 改变已确认原型的结构、流程、状态、权限或异常处理； - 真实上游测试可能反复消耗额度； - 无法判断风险或同一位置两次仍无根因。 + + +## 修改管理端系统模块 + +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。 + diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index 036fa28..1ea88e5 100644 --- a/docs/06-troubleshooting.md +++ b/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 # 故障排查 @@ -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 都属于安全缺陷，应立即停止相关入口并建立缺陷工单，不直接清理审计数据。 + + +## 系统管理页面排错 + +- 点击导航出现“Cannot find module”：先核对 migration 的 `component` 是否对应 `admin-ui/src/views/.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 三个监听端口。 +