2026-11-09 18:25:35 +08:00

181 lines
16 KiB
Markdown
Raw Permalink 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。源码发行和启动方式见[发行版本与快速启动](./distributions)。开发环境与静态在线演示都由 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>
契约从 workspace 包 `@ray-template/api-contracts` 和路由 Schema 生成,含请求体、响应、查询参数、Bearer 认证与权限码。登录与用户契约通过 `/admin` 子路径导入,演示接口通过 `/demo` 导入,路由 Schema 通过 `/routes` 导入,`/openapi` 导出 OpenAPI 生成函数。路由 Schema 的权威来源是 `packages/api-contracts/src/routes.ts`,routing 包中的旧入口保留转导出。包不读取浏览器状态,前端、Mock 和自有服务端可共享类型与运行时校验;包当前随仓库使用,尚未发布到 npm。应用原有 `api/admin/contracts.ts`、`api/demo/contracts.ts` 路径仍为兼容入口。修改后运行 `pnpm api:generate`;全量验证中的 `pnpm api:check` 检查文件与运行时 Schema 一致。
```ts
import type { ApiResponse, UserInput } from '@ray-template/api-contracts/admin'
import { userInputSchema } from '@ray-template/api-contracts/admin'
import type {
DemoOrderQuery,
SearchOptions,
} from '@ray-template/api-contracts/demo'
```
## 接入步骤
在 `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 后,在同一个 MSW 客户端实例上调用 `stop()` / `start()` 恢复,让同一个客户端管理监听器和拦截状态。恢复失败则阻止业务请求继续发送,表单和演示数据保持原样。内部 `GET /admin/mock-health` 仅由 Mock 使用,关闭 Mock 后不请求这个接口。Worker 脚本路径为 `/ray-template/mockServiceWorker.js`,注册 URL 带有当前 MSW 版本的查询参数,作用域为应用 base。静态服务器须在该路径提供脚本。浏览器需要 HTTPS 或 localhost。GitHub Pages 只托管静态文件,这些 API 由已启动的页面中的 Mock 响应;直接在地址栏打开 API 地址会返回 404。真实后端模式不启动 Mock,也不会在请求失败时返回伪造业务数据。当前锁定 MSW 3.0.4,安装不自动执行其 worker 复制脚本;升级时显式运行 `pnpm exec msw init apps/admin/public --save`,再做契约和浏览器验证。
<!-- fullstack:start -->
## 配套 NestJS 服务端
完整源码中的 `apps/server` 实现相同的 `/api/admin/*` 协议,页面层继续使用现有 API 调用。默认开发入口为 `pnpm fullstack:setup`、`pnpm dev:full`;已有 PostgreSQL 和 Redis 时使用 `pnpm fullstack:setup --external`。管理员凭据保存在私有的 `apps/server/.env.local`,不使用 Mock 演示密码,详细步骤见[全栈发行包](./distributions#全栈发行包)。
用户、部门、角色授权、会话、路由配置和操作审计持久化到 PostgreSQL。账号与邮箱通过规范化唯一字段避免大小写冲突;批量写入、账号保护与审计在事务内执行。初始化只补齐初始数据,重复运行保留已有配置、路由与账号。
配套服务用签名 JWT 标识会话,PostgreSQL 只保存令牌摘要;密码使用带随机盐的 scrypt 派生。每次请求校验 JWT 签名、有效期、数据库会话和实时权限。配套的同源 Admin 使用 HttpOnly Cookie,接口客户端仍可用 Bearer。退出撤销当前会话,停用、角色变更和改密撤销该账号的所有会话。
用户资料创建接口不接收密码。管理员可从用户管理设置凭据,运维也可使用 `pnpm server:credential:set` 进行恢复。配套的 `dev:full` 与 Compose 已配置 `VITE_API_AUTH_TRANSPORT=cookie`;手动构建时配合 `VITE_API_BASE_URL=/api/` 使用同源代理,外部 HTTPS 部署启用 Secure Cookie。Cookie 模式请求携带 `X-Ray-Session: cookie`,写请求还必须来自允许的同源页面。
Redis 为 API、登录和改密提供跨进程限流,并缓存可重建的演示读取结果;会话与权限不经过该缓存。请求均带 `X-Request-Id`,JSON 日志记录路由模板、状态和耗时,排除请求体、查询串、凭据和原始连接错误。就绪接口 `/api/health/ready` 检查数据库已初始化且 Redis 可用;存活接口为 `/api/health/live`。
配置要求明确的 CORS 来源和可信代理,默认不信任转发头。非法 JSON、超大请求、限流和依赖故障分别返回标准错误包络。配套后端不提供 `POST /admin/users/reset`。Redis 故障时返回 503,不切回内存认证或 Mock 数据。
`DEMO_ENABLED` 在开发环境默认开启,生产环境默认关闭。开启时,`/admin/demo/*` 提供与 Mock 一致的公开演示数据;关闭时接口返回 404,运行路由移除演示视图及指向它们的重定向。已保存的路由保持完整,有编辑权限的用户可继续维护。
<!-- fullstack:end -->
## 统一响应
成功使用 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 表示账号/邮箱冲突或当前账号保护,413 表示请求体过大,429 表示请求受到限流,503 表示存储或依赖暂时不可用(Mock 中包括演示数据库写入失败)。`error.key` 是稳定的业务错误标识;可选的 `error.fields` 为字段到错误键的映射。API 层把错误转换为 `AdminApiError`,用户页将已约定的错误键翻译为中英文提示。读取响应也会经过 Schema 校验。
## 登录、会话与权限
| 方法和路径 | 输入 | 成功的 data |
| ---------------------------- | ---------------------------------- | -------------------------------------------------------------------------------- |
| `POST /admin/auth/login` | `{ username, password }` | `{ accessToken, expiresAt, user, permissions }`,Cookie 模式不返回 `accessToken` |
| `GET /admin/auth/session` | 会话 | `{ user, permissions, expiresAt? }` |
| `POST /admin/auth/logout` | 会话 | `null` |
| `GET /admin/auth/profile` | 会话 | 当前账号资料与部门 |
| `PATCH /admin/auth/profile` | `{ name, phone }` | 更新后的当前账号资料 |
| `PATCH /admin/auth/password` | `{ currentPassword, newPassword }` | `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` |
| `PUT /admin/users/{id}/credential` | `{ newPassword }`,目标不能是当前账号 | `users:credentials` |
| `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` 可选,用于演示中的中英文翻译;自有后端直接提供名称即可。
批量操作在接口层整体校验后提交,避免一部分成功一部分失败;当前账号不可被删除、停用或通过编辑更换角色。通过编辑修改状态也需要 `users:status`。只有账号管理权限的用户可以维护目标账号及其凭据,管理者不能操作管理员账号。Mock 数据库将用户、路由与会话持久化在当前浏览器;用户页的恢复按钮只在 Mock 模式显示。
## 路由管理
`GET /admin/route-config` 在登录后调用,返回当前会话可用的 `data: { version: 1, routes: [...] }`。服务端同时考虑父子角色约束、视图权限和演示开关;没有可用子项的分组和无法到达授权目标的重定向都会移除。没有 `routes:read` 或没有可用页面时返回 `routes: []`,外壳和个人信息仍可用。携带 `routes:write` 的会话可用 `GET /admin/route-config?view=editor` 读取完整配置,再通过 `PUT /admin/route-config` 保存。
初始菜单表位于 `packages/demo-data/src/routes.json`。标准 API 模式以服务端为准,登录时注入运行路由,保存后重新加载。读取失败不会回退为内置菜单。已被裁剪的业务地址直接访问会进入 404;固定的路由管理入口没有编辑权限时进入 403;业务 API 独立授权。导入、导出与接口使用同一结构,详情见[路由契约](./routing)。
前端 `router/config/views.ts` 保留组件 ID 白名单,接口只返回 ID;后端或 AI 不需要传递组件代码。登录、404 和受保护的路由管理入口由外壳保留。原 `VITE_ROUTE_CONFIG_URL` 仍兼容旧的原始 JSON 读取接口;完整读写接入使用上面的标准 API 基址。
## 在线验证
演示接口同样属于标准 HTTP 契约:
| 方法和路径 | 输入 | 成功的 data |
| ----------------------------------- | ----------------------------------------------- | ------------------------------------- |
| `GET /admin/demo/people` | `page/pageSize/name/email/sortAge/fail` | `{ items: Person[], total }` |
| `GET /admin/demo/route-people` | `page/pageSize/name`,name 精确匹配以兼容旧链接 | `{ items: RouteDemoPerson[], total }` |
| `GET /admin/demo/route-people/{id}` | 从 0 开始的非负整数 id | `RouteDemoPerson`,不存在返回 404 |
| `GET /admin/demo/search-options` | `locale` | 状态、组织、产品类目、仓库与配送选项 |
| `POST /admin/demo/orders/search` | `{ query: DemoOrderQuery, locale, fail? }` | `{ items: DemoOrder[], total }` |
| `POST /admin/demo/owners/search` | `{ orgId, keyword, locale, fail? }` | `{ value, label }[]` |
| `GET /admin/demo/charts` | `refresh` | `DemoCharts` |
| `GET /admin/demo/request` | 无 | 工单与城市数据 |
分页上限为 100。`sortAge` 为 `ascend` 或 `descend`,`refresh` 与演示用 `fail` 为布尔值;非法输入返回 HTTP 400。订单的筛选字段、类型、日期格式和金额下限均在共享 Schema 和 OpenAPI 中定义。`fail=true` 的模拟错误通过 HTTP 503 返回,页面不再直接抛出伪造请求错误。
搜索页从接口获取业务选项,订单响应直接提供仓库与配送名称,不依赖前端样例数组下标。选项加载失败显示可重试状态,切换语言或离开页面会取消旧请求。路由示例的列表和详情也从接口读取;旧的姓名查询链接继续可用。预设演示场景和故障按钮只在 Mock 模式显示。
打开浏览器 Network,依次登录、进入用户管理、查询、新增编辑、打开详情与保存路由,能够看到对应的 HTTP 请求。在线演示响应标记为来自 Service Worker;它模拟服务端协议,静态站点无需另外部署服务进程。接入真实后端后,同样的页面请求直接发往配置的基址。
用户页复用 `RTablePro`、`RForm/useForm` 和 Naive UI。桌面下两个区域填满内容区:组织卡片使用 `contentScrollable`,表格使用 `autoHeight`;窄屏上下排布时分别由现有滚动组件承载,避免页面越长越高。