XiaoDaiGua-Ray bca3f3ff24
feat(admin): add user management and HTTP mock APIs
Add user CRUD, account-scoped navigation history and favorites.

Unify HTTP mocks, backend contracts and route configuration.

Reuse existing scrolling components and add Harness reuse guidance.
2026-11-05 17:21:59 +08:00

131 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 服务端接入与标准契约
登录、会话、用户管理与路由管理使用同一套 HTTP API。开发环境与静态在线演示都由 MSW 在网络层模拟响应;页面和 Store 不直接读取 Mock 数据库。接入自有服务端时,保留页面与调用方法,替换接口地址和实现即可。
<script setup>
import { withBase } from 'vitepress'
</script>
<a :href="withBase('/contracts/admin-api.json')" target="_blank" rel="noreferrer">下载 OpenAPI 3.1 契约</a>
契约从 `apps/admin/src/api/admin/contracts.ts` 和路由 Schema 生成,含请求体、响应、查询参数、Bearer 认证与权限码。修改后运行 `pnpm api:generate`;全量验证中的 `pnpm api:check` 检查文件与运行时 Schema 一致。
## 接入步骤
在 `apps/admin/.env.local` 配置并重新启动或构建:
```dotenv
VITE_API_MOCK=false
VITE_API_BASE_URL=https://your-api.example.com/api/
```
也可以使用同源 `/api/`,由部署代理转发。设置 `VITE_API_BASE_URL` 后默认关闭 Mock,显式 `VITE_API_MOCK=true` 才重新启用。接口基址可以包含版本前缀;页面只通过 `api/admin` 的方法调用,不拼接固定域名。`VITE_*` 会进入浏览器产物,仅用于公开配置。
Mock 在应用启动前完成 Service Worker 注册。每次 API 请求前检查内部健康标记;浏览器回收 worker 后,使用公开 API 恢复,失败则阻止业务请求继续发送,表单和演示数据保持原样。内部 `GET /admin/mock-health` 仅由 Mock 使用,关闭 Mock 后不请求这个接口。默认脚本路径为 `/ray-template/mockServiceWorker.js`,作用域为应用 base;静态服务器必须按原路径提供该文件。浏览器需要 HTTPS 或 localhost。真实后端模式不启动 Mock,也不会在请求失败时返回伪造业务数据。当前锁定 MSW 2.11.6,安装不自动执行其 worker 复制脚本;升级时显式运行 `pnpm exec msw init apps/admin/public --save`,再做契约和浏览器验证。
## 统一响应
成功使用 HTTP 200 和以下包络:
```json
{
"code": 200,
"msg": "OK",
"data": { "items": [], "total": 0 }
}
```
分页请求使用 `page`(从 1 开始)、`pageSize`(1–100);响应 `data.items` 是当前页,`data.total` 是所有条件生效后的总数。筛选在分页前执行。详情和写入直接把单个对象放入 `data`;批量变更返回 `{ "affected": 2 }`。
失败同时使用对应的 HTTP 状态和 `code`,`data` 为 `null`:
```json
{
"code": 409,
"msg": "duplicateUsername",
"data": null,
"error": { "key": "duplicateUsername" }
}
```
400 表示输入不合法,401 表示会话失效,403 表示权限不足,404 表示对象不存在,409 表示账号/邮箱冲突或当前账号保护,503 表示演示数据库写入失败。`error.key` 是稳定的业务错误标识;可选的 `error.fields` 为字段到错误键的映射。API 层把错误转换为 `AdminApiError`,用户页将已约定的错误键翻译为中英文提示。读取响应也会经过 Schema 校验。
## 登录、会话与权限
| 方法和路径 | 输入 | 成功的 data |
| ------------------------- | ------------------------ | ----------------------------------------------- |
| `POST /admin/auth/login` | `{ username, password }` | `{ accessToken, expiresAt, user, permissions }` |
| `GET /admin/auth/session` | Bearer token | `{ user, permissions }` |
| `POST /admin/auth/logout` | Bearer token | `null` |
```json
{
"user": { "id": "u-1", "username": "admin", "name": "Alex", "role": "admin" },
"permissions": [
"users:read",
"users:create",
"users:update",
"routes:read",
"routes:write"
]
}
```
应用使用 `Authorization: Bearer <accessToken>`。每次启动重新请求会话资料与权限,401 清除失效会话;其他启动请求失败保留错误,避免用旧权限继续工作。当前模板的路由角色契约是单个 `user.role`,路由 `meta.role` 为允许访问的角色数组。权限码独立于角色名称,可由自有服务端自由组织。
```tsx
import { useAccess } from '@/hooks'
const { hasPermission } = useAccess()
// 多个权限默认全部满足;第二个参数传 'any' 时任意一个满足即可。
hasPermission('users:create')
hasPermission(['users:update', 'users:delete'], 'any')
```
前端权限用于菜单、导航和操作入口;服务端须独立校验每次业务请求。Mock 也会验证权限,直接发送请求无法绕过只读账号、管理员操作或当前账号保护。演示账号 `admin`(也兼容 `Ray Admin`)、`manager`、`member` 的密码均为 `123456`,分别对应全部权限、用户维护权限、只读权限。Mock token 与演示密码只用于在线体验,不是生产认证实现。
## 用户管理
| 方法和路径 | 输入 | 需要的权限 |
| -------------------------------- | ----------------------------------------------------- | -------------- |
| `GET /admin/users/options` | 无 | `users:read` |
| `GET /admin/users` | 分页及 `name/username/email/departmentId/role/status` | `users:read` |
| `GET /admin/users/{id}` | 路径 id | `users:read` |
| `POST /admin/users` | `UserInput` | `users:create` |
| `PUT /admin/users/{id}` | 完整 `UserInput` | `users:update` |
| `POST /admin/users/batch-delete` | `{ ids: string[] }` | `users:delete` |
| `PATCH /admin/users/status` | `{ ids: string[], status: "enabled" 或 "disabled" }` | `users:status` |
| `POST /admin/users/reset` | 无,仅演示恢复入口 | `users:reset` |
```json
{
"username": "alex",
"name": "Alex",
"email": "alex@example.com",
"phone": "",
"departmentId": "engineering",
"role": "member",
"status": "enabled",
"remark": ""
}
```
响应用户增加稳定的 `id` 与 ISO 8601 `createdAt`。账号与邮箱不区分大小写检查唯一性,更新时保留 id 与创建时间。组织选项由接口返回 `{ departments: [{ id, parentId, name, labelKey? }], roles: [{ value, label, labelKey?, disabled? }] }`,部门过滤包含子组织。`labelKey` 可选,用于演示中的中英文翻译;自有后端直接提供名称即可。
批量操作在接口层整体校验后提交,避免一部分成功一部分失败;当前账号不可被删除、停用或通过编辑更换角色。Mock 数据库将用户、路由与会话持久化在当前浏览器;写入失败时保留原数据并返回错误,编辑表单可重试。用户页的恢复按钮只在 Mock 模式显示。
## 路由管理
`GET /admin/route-config` 是公开的前端启动配置接口,返回 `data: { version: 1, routes: [...] }`;路由元数据不包含业务秘密。`PUT /admin/route-config` 以同一结构提交,需要 `routes:write`。若自有系统需要受保护的菜单读取,可在 API 适配层把读取移到登录后,并保留登录与错误页的启动路由。
现有菜单表已迁到 `apps/admin/src/mocks/data/routes.json`,作为 Mock 初始数据库和显式离线恢复来源。正常在线启动走 GET,路由可视化与 JSON 的接口模式保存走 PUT,成功后重新加载并从接口读回。导入、导出与接口中的路由内容使用同一结构,详情见[路由契约](./routing)。
前端 `router/config/views.ts` 保留组件 ID 白名单,接口只返回 ID;后端或 AI 不需要传递组件代码。登录、404 和受保护的路由管理入口由外壳保留。原 `VITE_ROUTE_CONFIG_URL` 仍兼容旧的原始 JSON 读取接口;完整读写接入使用上面的标准 API 基址。
## 在线验证
打开浏览器 Network,依次登录、进入用户管理、查询、新增编辑、打开详情与保存路由,能够看到对应的 HTTP 请求。在线演示响应标记为来自 Service Worker;它模拟服务端协议,静态站点无需另外部署服务进程。接入真实后端后,同样的页面请求直接发往配置的基址。
用户页复用 `RTablePro`、`RForm/useForm` 和 Naive UI。桌面下两个区域填满内容区:组织卡片使用 `contentScrollable`,表格使用 `autoHeight`;窄屏上下排布时分别由现有滚动组件承载,避免页面越长越高。