docs: 后台管理 API 说明与变更记录（AGENTS.md / change-log）

AGENTS.md

@@ -44,6 +44,18 @@ service.xpcool.com/
 └── utility/        # （预留）跨切面辅助
 ```
 
+## 后台管理 API（api/admin/v1）
+
+- 三层路由隔离（`internal/cmd/cmd.go`）：
+  - **公开**（无鉴权）：`POST /auth/login`
+  - **仅登录** `AdminAuthOnly`：`GET /auth/info`（个人资料）、`GET /auth/codes`（按钮权限码）、`GET /menu/routes`（vben 动态路由）
+  - **接口级鉴权** `AdminAuth`：RBAC 管理、日志等
+- **接口鉴权机制（重要）**：中间件按「请求方法+路径」从 `admin_menu`（type=2 行，path 存 `"METHOD /path"`，`{id}` 为动态段）反查所需权限码，再校验用户是否拥有。**前端无需传 X-Permission**；未配置映射的接口一律拒绝。
+- RBAC 管理：`/admins`、`/roles`、`/menus/tree`（权限码 `system:admin:*`、`system:role:*`、`system:menu:*`）
+- 日志监控：`GET /log/files`、`GET /log/tail?file=&lines=&keyword=`（权限码 `monitor:log:*`；file 参数防路径穿越）
+- 新增受保护接口三步：① `api/admin/v1/<xxx>.go` 写 Req/Res；② `internal/controller/admin/<xxx>.go` 加方法；③ 在 `admin_menu` 加 type=2 行：`permission` 填权限码、`path` 填 `"METHOD /路径"` 映射。
+- 迁移脚本：`003_schema_ext.sql`（admin_menu 加 icon/component/hidden）、`004_seed.sql`（初始 admin/admin123、super_admin、22 条菜单）、`005_menu_paths.sql`（按钮-接口路径映射）。
+
 ## 开放接口（api/open/v1，前端调用）与命名规则
 
 - **命名决策**：公共接口前缀用 **open**（不用 common）。理由：`common` 语义偏"内部公共代码"，`open` 是开放接口业界惯例（支付宝 /open/api 等），更能表达"对外暴露、无鉴权"。同属"公开"语义的备选还有 `public`。

docs/change-log/2026-08-24.md

@@ -153,3 +153,38 @@
 ### 待办与风险
 
 - 无新增风险；后续新增子功能统一按 `tools/<name>/<name>.go` 建文件。
+
+---
+
+## 追加（22:40）：后台管理功能开发（后端完成）
+
+### 请求
+
+使用 goframe-v2 开发登录、菜单、按钮级权限等常规后台管理功能（前端 vben5 对接，backend 动态路由模式）；登录后台后开发服务器日志管理功能。
+
+### 变更（commit 8fdb25e，35 文件）
+
+- `manifest/sql/003_schema_ext.sql`：admin_menu 加 `icon/component/hidden` 列
+- `manifest/sql/004_seed.sql`：初始 admin/admin123、super_admin 角色、22 条菜单（含按钮权限码）、角色/用户绑定
+- `manifest/sql/005_menu_paths.sql`：按钮行 path 填 `"METHOD /路径"` 接口映射（{id} 动态段）
+- auth：`/auth/info`、`/auth/codes`；路由拆分公开(NewAuth)/仅登录(NewProfile)/受保护(New)三组；新增 `AdminAuthOnly` 中间件
+- menu：`/menu/routes` 返回 vben backend 动态路由树（按角色过滤+排序）
+- RBAC：`/admins`、`/roles`、`/menus/tree` 及 CRUD（含角色绑定、重置密码、菜单授权、删除校验子节点）
+- log：`/log/files`、`/log/tail`（反向块扫描读尾部+关键词过滤+路径穿越防护）
+- 安全：接口鉴权改为「方法+路径→权限码」自动映射（`PermissionForPath`+`matchRoute`），**不再信任前端 X-Permission**
+- 修复：gf v2.10.2 `${ENV}` 不自动替换 → cmd.injectEnv 注入；MySQL driver 需 blank import `contrib/drivers/mysql/v2`；gtime Format(PHP) 与 Layout(Go) 区分再次踩坑（CreatedAt 输出 layout 原样）
+- `log/` 加入 .gitignore；config.dev.yaml logger.path=log（日志落盘）
+
+### 决策与理由
+
+- **接口鉴权用路径映射而非 X-Permission**：原实现用户可用自己拥有的任意权限码访问任意受保护接口（越权漏洞）；改为后端按 method+path 查 admin_menu 映射，未配置即拒绝。
+- **受保护接口分三层**：公开 login；AdminAuthOnly（info/codes/routes，登录即可取，vben 登录后立即调用）；AdminAuth（RBAC/日志）。
+- **admin_menu 按钮行 path 存接口映射**：与 type=1 菜单行的路由 path 语义区分开，避免冲突。
+- **gf gen dao 不可用**：本机 gf CLI 为公司定制版（生成 com.lib.gf.v2 import），与项目官方 gf 不兼容；本次手动补齐 admin_menu 三字段（entity/do/table），后续换官方 CLI 或脚本化处理。
+
+### 待办与风险
+
+- **前端对接（vben5）**：admin.xpcool.com 需配置 accessMode=backend、登录/信息/权限码/动态路由对接、系统管理三页面+日志监控页面、按钮级 v-access:code。
+- 冒烟测试已建 opuser/op 测试角色，可清理。
+- 菜单管理接口的 assignMenu 权限码暂无独立接口（角色授权在 role update 中完成），保留扩展位。
+- 生产环境 JWT_SECRET/DB_DSN 必须通过环境变量提供（${ENV} 不会自动替换）。