11 KiB
Raw Blame History

服务端接入与标准契约

登录、会话、用户管理与路由管理使用同一套 HTTP API。开发环境与静态在线演示都由 MSW 在网络层模拟响应;页面和 Store 不直接读取 Mock 数据库。接入自有服务端时,保留页面与调用方法,替换接口地址和实现即可。

下载 OpenAPI 3.1 契约

契约从 workspace 包 @ray-template/api-contracts 和路由 Schema 生成,含请求体、响应、查询参数、Bearer 认证与权限码。登录与用户契约通过 /admin 子路径导入,演示接口通过 /demo 导入,/openapi 导出 OpenAPI 生成函数。包不读取浏览器状态,前端、Mock 和自有服务端可共享类型与运行时校验;包当前随仓库使用,尚未发布到 npm。应用原有 api/admin/contracts.ts、api/demo/contracts.ts 路径仍为兼容入口。修改后运行 pnpm api:generate;全量验证中的 pnpm api:check 检查文件与运行时 Schema 一致。

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 配置并重新启动或构建:

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 和以下包络:

{
  "code": 200,
  "msg": "OK",
  "data": { "items": [], "total": 0 }
}

分页请求使用 page(从 1 开始)、pageSize(1–100);响应 data.items 是当前页,data.total 是所有条件生效后的总数。筛选在分页前执行。详情和写入直接把单个对象放入 data;批量变更返回 { "affected": 2 }。

失败同时使用对应的 HTTP 状态和 code,data 为 null:

{
  "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
{
  "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 为允许访问的角色数组。权限码独立于角色名称,可由自有服务端自由组织。

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
{
  "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,成功后重新加载并从接口读回。真实后端模式下,远端读取失败会中止启动,不会自动展示内置业务菜单;用户显式选定的本地或静态来源仍可用于离线恢复。导入、导出与接口中的路由内容使用同一结构,详情见路由契约。

前端 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;窄屏上下排布时分别由现有滚动组件承载,避免页面越长越高。