mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-20 02:03:35 +08:00
41 lines
31 KiB
JavaScript
41 lines
31 KiB
JavaScript
import{o as a,c as t,j as i,a as e,k as d,g as n,a3 as o}from"./chunks/framework.D8G7yXPy.js";const p=["href"],c=JSON.parse('{"title":"服务端接入与标准契约","description":"","frontmatter":{},"headers":[],"relativePath":"guide/backend.md","filePath":"guide/backend.md"}'),h={name:"guide/backend.md"},E=Object.assign(h,{setup(l){return(k,s)=>(a(),t("div",null,[s[0]||(s[0]=i("h1",{id:"服务端接入与标准契约",tabindex:"-1"},[e("服务端接入与标准契约 "),i("a",{class:"header-anchor",href:"#服务端接入与标准契约","aria-label":'Permalink to "服务端接入与标准契约"'},"")],-1)),s[1]||(s[1]=i("p",null,[e("登录、会话、用户管理与路由管理使用同一套 HTTP API。源码发行和启动方式见"),i("a",{href:"./distributions.html"},"发行版本与快速启动"),e("。开发环境与静态在线演示都由 MSW 在网络层模拟响应;页面和 Store 不直接读取 Mock 数据库。接入自有服务端时,保留页面与调用方法,替换接口地址和实现即可。")],-1)),i("p",null,[i("a",{href:d(n)("/contracts/admin-api.json"),target:"_blank",rel:"noreferrer"},"下载 OpenAPI 3.1 契约",8,p)]),s[2]||(s[2]=o(`<p>契约从 workspace 包 <code>@ray-template/api-contracts</code> 和路由 Schema 生成,含请求体、响应、查询参数、Bearer 认证与权限码。登录与用户契约通过 <code>/admin</code> 子路径导入,演示接口通过 <code>/demo</code> 导入,路由 Schema 通过 <code>/routes</code> 导入,<code>/openapi</code> 导出 OpenAPI 生成函数。路由 Schema 的权威来源是 <code>packages/api-contracts/src/routes.ts</code>,routing 包中的旧入口保留转导出。包不读取浏览器状态,前端、Mock 和自有服务端可共享类型与运行时校验;包当前随仓库使用,尚未发布到 npm。应用原有 <code>api/admin/contracts.ts</code>、<code>api/demo/contracts.ts</code> 路径仍为兼容入口。修改后运行 <code>pnpm api:generate</code>;全量验证中的 <code>pnpm api:check</code> 检查文件与运行时 Schema 一致。</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { ApiResponse, UserInput } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '@ray-template/api-contracts/admin'</span></span>
|
||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { userInputSchema } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '@ray-template/api-contracts/admin'</span></span>
|
||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> DemoOrderQuery,</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> SearchOptions,</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '@ray-template/api-contracts/demo'</span></span></code></pre></div><h2 id="接入步骤" tabindex="-1">接入步骤 <a class="header-anchor" href="#接入步骤" aria-label="Permalink to "接入步骤""></a></h2><p>在 <code>apps/admin/.env.local</code> 配置并重新启动或构建:</p><div class="language-dotenv vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">dotenv</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">VITE_API_MOCK</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">false</span></span>
|
||
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">VITE_API_BASE_URL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://your-api.example.com/api/</span></span></code></pre></div><p>也可以使用同源 <code>/api/</code>,由部署代理转发。设置 <code>VITE_API_BASE_URL</code> 后默认关闭 Mock,显式 <code>VITE_API_MOCK=true</code> 才重新启用。接口基址可以包含版本前缀;页面只通过 <code>api/admin</code> 的方法调用,不拼接固定域名。<code>VITE_*</code> 会进入浏览器产物,仅用于公开配置。</p><p>Mock 在应用启动前完成 Service Worker 注册。每次 API 请求前检查内部健康标记;浏览器回收 worker 后,在同一个 MSW 客户端实例上调用 <code>stop()</code> / <code>start()</code> 恢复,避免旧实例残留的监听器将请求放行。恢复失败则阻止业务请求继续发送,表单和演示数据保持原样。内部 <code>GET /admin/mock-health</code> 仅由 Mock 使用,关闭 Mock 后不请求这个接口。默认脚本路径为 <code>/ray-template/mockServiceWorker.js</code>,作用域为应用 base;静态服务器必须按原路径提供该文件。浏览器需要 HTTPS 或 localhost。GitHub Pages 只托管静态文件,这些 API 由已启动的页面中的 Mock 响应;直接在地址栏打开 API 地址会返回 404。真实后端模式不启动 Mock,也不会在请求失败时返回伪造业务数据。当前锁定 MSW 2.11.6,安装不自动执行其 worker 复制脚本;升级时显式运行 <code>pnpm exec msw init apps/admin/public --save</code>,再做契约和浏览器验证。</p><h2 id="配套-nestjs-服务端" tabindex="-1">配套 NestJS 服务端 <a class="header-anchor" href="#配套-nestjs-服务端" aria-label="Permalink to "配套 NestJS 服务端""></a></h2><p>完整源码中的 <code>apps/server</code> 实现相同的 <code>/api/admin/*</code> 协议,页面层继续使用现有 API 调用。默认开发入口为 <code>pnpm fullstack:setup</code>、<code>pnpm dev:full</code>;已有 PostgreSQL 和 Redis 时使用 <code>pnpm fullstack:setup --external</code>。管理员凭据保存在私有的 <code>apps/server/.env.local</code>,不使用 Mock 演示密码,详细步骤见<a href="./distributions.html#全栈发行包">全栈发行包</a>。</p><p>用户、部门、角色授权、会话、路由配置和操作审计持久化到 PostgreSQL。账号与邮箱通过规范化唯一字段避免大小写冲突;批量写入、账号保护与审计在事务内执行。初始化只补齐初始数据,重复运行保留已有配置、路由与账号。</p><p>配套服务用签名 JWT 标识会话,PostgreSQL 只保存令牌摘要;密码使用带随机盐的 scrypt 派生。每次请求校验 JWT 签名、有效期、数据库会话和实时权限。配套的同源 Admin 使用 HttpOnly Cookie,接口客户端仍可用 Bearer。退出撤销当前会话,停用、角色变更和改密撤销该账号的所有会话。</p><p>用户资料创建接口不接收密码。管理员可从用户管理设置凭据,运维也可使用 <code>pnpm server:credential:set</code> 进行恢复。配套的 <code>dev:full</code> 与 Compose 已配置 <code>VITE_API_AUTH_TRANSPORT=cookie</code>;手动构建时配合 <code>VITE_API_BASE_URL=/api/</code> 使用同源代理,外部 HTTPS 部署启用 Secure Cookie。Cookie 模式请求携带 <code>X-Ray-Session: cookie</code>,写请求还必须来自允许的同源页面。</p><p>Redis 为 API、登录和改密提供跨进程限流,并缓存可重建的演示读取结果;会话与权限不经过该缓存。请求均带 <code>X-Request-Id</code>,JSON 日志记录路由模板、状态和耗时,排除请求体、查询串、凭据和原始连接错误。就绪接口 <code>/api/health/ready</code> 检查数据库已初始化且 Redis 可用;存活接口为 <code>/api/health/live</code>。</p><p>配置要求明确的 CORS 来源和可信代理,默认不信任转发头。非法 JSON、超大请求、限流和依赖故障分别返回标准错误包络。配套后端不提供 <code>POST /admin/users/reset</code>。Redis 故障时返回 503,不切回内存认证或 Mock 数据。</p><p><code>DEMO_ENABLED</code> 在开发环境默认开启,生产环境默认关闭。开启时,<code>/admin/demo/*</code> 提供与 Mock 一致的公开演示数据;关闭时接口返回 404,运行路由移除演示视图及指向它们的重定向。已保存的路由保持完整,有编辑权限的用户可继续维护。</p><h2 id="统一响应" tabindex="-1">统一响应 <a class="header-anchor" href="#统一响应" aria-label="Permalink to "统一响应""></a></h2><p>成功使用 HTTP 200 和以下包络:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "code"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "msg"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"OK"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "data"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"items"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"total"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>分页请求使用 <code>page</code>(从 1 开始)、<code>pageSize</code>(1–100);响应 <code>data.items</code> 是当前页,<code>data.total</code> 是所有条件生效后的总数。筛选在分页前执行。详情和写入直接把单个对象放入 <code>data</code>;批量变更返回 <code>{ "affected": 2 }</code>。</p><p>失败同时使用对应的 HTTP 状态和 <code>code</code>,<code>data</code> 为 <code>null</code>:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "code"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">409</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "msg"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"duplicateUsername"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "data"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "error"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"key"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"duplicateUsername"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>400 表示输入不合法,401 表示会话失效,403 表示权限不足,404 表示对象不存在,409 表示账号/邮箱冲突或当前账号保护,413 表示请求体过大,429 表示请求受到限流,503 表示存储或依赖暂时不可用(Mock 中包括演示数据库写入失败)。<code>error.key</code> 是稳定的业务错误标识;可选的 <code>error.fields</code> 为字段到错误键的映射。API 层把错误转换为 <code>AdminApiError</code>,用户页将已约定的错误键翻译为中英文提示。读取响应也会经过 Schema 校验。</p><h2 id="登录、会话与权限" tabindex="-1">登录、会话与权限 <a class="header-anchor" href="#登录、会话与权限" aria-label="Permalink to "登录、会话与权限""></a></h2><table tabindex="0"><thead><tr><th>方法和路径</th><th>输入</th><th>成功的 data</th></tr></thead><tbody><tr><td><code>POST /admin/auth/login</code></td><td><code>{ username, password }</code></td><td><code>{ accessToken, expiresAt, user, permissions }</code>,Cookie 模式不返回 <code>accessToken</code></td></tr><tr><td><code>GET /admin/auth/session</code></td><td>会话</td><td><code>{ user, permissions, expiresAt? }</code></td></tr><tr><td><code>POST /admin/auth/logout</code></td><td>会话</td><td><code>null</code></td></tr><tr><td><code>GET /admin/auth/profile</code></td><td>会话</td><td>当前账号资料与部门</td></tr><tr><td><code>PATCH /admin/auth/profile</code></td><td><code>{ name, phone }</code></td><td>更新后的当前账号资料</td></tr><tr><td><code>PATCH /admin/auth/password</code></td><td><code>{ currentPassword, newPassword }</code></td><td><code>null</code>,需要重新登录</td></tr></tbody></table><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "user"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"u-1"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"username"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"admin"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Alex"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"admin"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "permissions"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "users:read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "users:create"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "users:update"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "routes:read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "routes:write"</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>自有后端默认用 <code>Authorization: Bearer <accessToken></code>。每次启动重新请求会话资料与权限,401 清除失效会话;其他错误保留为失败状态。当前模板的路由角色契约是单个 <code>user.role</code>,路由 <code>meta.role</code> 为允许访问的角色数组。权限码独立于角色名称,可由自有服务端自由组织。个人资料只允许用户自行编辑姓名和电话,用户名、邮箱、角色和部门由用户管理维护。</p><div class="language-tsx vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tsx</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { useAccess } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '@/hooks'</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">hasPermission</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> useAccess</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// 多个权限默认全部满足;第二个参数传 'any' 时任意一个满足即可。</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">hasPermission</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'users:create'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">hasPermission</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'users:update'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'users:delete'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">], </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'any'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><p>前端权限用于菜单、导航和操作入口;服务端须独立校验每次业务请求。Mock 也会验证权限,直接发送请求无法绕过只读账号、管理员操作或当前账号保护。演示账号 <code>admin</code>(也兼容 <code>Ray Admin</code>)、<code>manager</code>、<code>member</code> 的密码均为 <code>123456</code>,分别对应全部权限、用户维护权限、只读权限。Mock token 与演示密码只用于在线体验,不是生产认证实现。</p><h2 id="用户管理" tabindex="-1">用户管理 <a class="header-anchor" href="#用户管理" aria-label="Permalink to "用户管理""></a></h2><table tabindex="0"><thead><tr><th>方法和路径</th><th>输入</th><th>需要的权限</th></tr></thead><tbody><tr><td><code>GET /admin/users/options</code></td><td>无</td><td><code>users:read</code></td></tr><tr><td><code>GET /admin/users</code></td><td>分页及 <code>name/username/email/departmentId/role/status</code></td><td><code>users:read</code></td></tr><tr><td><code>GET /admin/users/{id}</code></td><td>路径 id</td><td><code>users:read</code></td></tr><tr><td><code>POST /admin/users</code></td><td><code>UserInput</code></td><td><code>users:create</code></td></tr><tr><td><code>PUT /admin/users/{id}</code></td><td>完整 <code>UserInput</code></td><td><code>users:update</code></td></tr><tr><td><code>POST /admin/users/batch-delete</code></td><td><code>{ ids: string[] }</code></td><td><code>users:delete</code></td></tr><tr><td><code>PATCH /admin/users/status</code></td><td><code>{ ids: string[], status: "enabled" 或 "disabled" }</code></td><td><code>users:status</code></td></tr><tr><td><code>PUT /admin/users/{id}/credential</code></td><td><code>{ newPassword }</code>,目标不能是当前账号</td><td><code>users:credentials</code></td></tr><tr><td><code>POST /admin/users/reset</code></td><td>无,仅演示恢复入口</td><td><code>users:reset</code></td></tr></tbody></table><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "username"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"alex"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Alex"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "email"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"alex@example.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "phone"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">""</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "departmentId"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"engineering"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"member"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "status"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"enabled"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "remark"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">""</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>响应用户增加稳定的 <code>id</code> 与 ISO 8601 <code>createdAt</code>。账号与邮箱不区分大小写检查唯一性,更新时保留 id 与创建时间。组织选项由接口返回 <code>{ departments: [{ id, parentId, name, labelKey? }], roles: [{ value, label, labelKey?, disabled? }] }</code>,部门过滤包含子组织。<code>labelKey</code> 可选,用于演示中的中英文翻译;自有后端直接提供名称即可。</p><p>批量操作在接口层整体校验后提交,避免一部分成功一部分失败;当前账号不可被删除、停用或通过编辑更换角色。通过编辑修改状态也需要 <code>users:status</code>。只有账号管理权限的用户可以维护目标账号及其凭据,管理者不能操作管理员账号。Mock 数据库将用户、路由与会话持久化在当前浏览器;用户页的恢复按钮只在 Mock 模式显示。</p><h2 id="路由管理" tabindex="-1">路由管理 <a class="header-anchor" href="#路由管理" aria-label="Permalink to "路由管理""></a></h2><p><code>GET /admin/route-config</code> 在登录后调用,返回当前会话可用的 <code>data: { version: 1, routes: [...] }</code>。服务端同时考虑父子角色约束、视图权限和演示开关;没有可用子项的分组和无法到达授权目标的重定向都会移除。没有 <code>routes:read</code> 或没有可用页面时返回 <code>routes: []</code>,外壳和个人信息仍可用。携带 <code>routes:write</code> 的会话可用 <code>GET /admin/route-config?view=editor</code> 读取完整配置,再通过 <code>PUT /admin/route-config</code> 保存。</p><p>初始菜单表位于 <code>packages/demo-data/src/routes.json</code>。标准 API 模式以服务端为准,登录时注入运行路由,保存后重新加载。读取失败不会回退为内置菜单。已被裁剪的业务地址直接访问会进入 404;固定的路由管理入口没有编辑权限时进入 403;业务 API 独立授权。导入、导出与接口使用同一结构,详情见<a href="./routing.html">路由契约</a>。</p><p>前端 <code>router/config/views.ts</code> 保留组件 ID 白名单,接口只返回 ID;后端或 AI 不需要传递组件代码。登录、404 和受保护的路由管理入口由外壳保留。原 <code>VITE_ROUTE_CONFIG_URL</code> 仍兼容旧的原始 JSON 读取接口;完整读写接入使用上面的标准 API 基址。</p><h2 id="在线验证" tabindex="-1">在线验证 <a class="header-anchor" href="#在线验证" aria-label="Permalink to "在线验证""></a></h2><p>演示接口同样属于标准 HTTP 契约:</p><table tabindex="0"><thead><tr><th>方法和路径</th><th>输入</th><th>成功的 data</th></tr></thead><tbody><tr><td><code>GET /admin/demo/people</code></td><td><code>page/pageSize/name/email/sortAge/fail</code></td><td><code>{ items: Person[], total }</code></td></tr><tr><td><code>GET /admin/demo/route-people</code></td><td><code>page/pageSize/name</code>,name 精确匹配以兼容旧链接</td><td><code>{ items: RouteDemoPerson[], total }</code></td></tr><tr><td><code>GET /admin/demo/route-people/{id}</code></td><td>从 0 开始的非负整数 id</td><td><code>RouteDemoPerson</code>,不存在返回 404</td></tr><tr><td><code>GET /admin/demo/search-options</code></td><td><code>locale</code></td><td>状态、组织、产品类目、仓库与配送选项</td></tr><tr><td><code>POST /admin/demo/orders/search</code></td><td><code>{ query: DemoOrderQuery, locale, fail? }</code></td><td><code>{ items: DemoOrder[], total }</code></td></tr><tr><td><code>POST /admin/demo/owners/search</code></td><td><code>{ orgId, keyword, locale, fail? }</code></td><td><code>{ value, label }[]</code></td></tr><tr><td><code>GET /admin/demo/charts</code></td><td><code>refresh</code></td><td><code>DemoCharts</code></td></tr><tr><td><code>GET /admin/demo/request</code></td><td>无</td><td>工单与城市数据</td></tr></tbody></table><p>分页上限为 100。<code>sortAge</code> 为 <code>ascend</code> 或 <code>descend</code>,<code>refresh</code> 与演示用 <code>fail</code> 为布尔值;非法输入返回 HTTP 400。订单的筛选字段、类型、日期格式和金额下限均在共享 Schema 和 OpenAPI 中定义。<code>fail=true</code> 的模拟错误通过 HTTP 503 返回,页面不再直接抛出伪造请求错误。</p><p>搜索页从接口获取业务选项,订单响应直接提供仓库与配送名称,不依赖前端样例数组下标。选项加载失败显示可重试状态,切换语言或离开页面会取消旧请求。路由示例的列表和详情也从接口读取;旧的姓名查询链接继续可用。预设演示场景和故障按钮只在 Mock 模式显示。</p><p>打开浏览器 Network,依次登录、进入用户管理、查询、新增编辑、打开详情与保存路由,能够看到对应的 HTTP 请求。在线演示响应标记为来自 Service Worker;它模拟服务端协议,静态站点无需另外部署服务进程。接入真实后端后,同样的页面请求直接发往配置的基址。</p><p>用户页复用 <code>RTablePro</code>、<code>RForm/useForm</code> 和 Naive UI。桌面下两个区域填满内容区:组织卡片使用 <code>contentScrollable</code>,表格使用 <code>autoHeight</code>;窄屏上下排布时分别由现有滚动组件承载,避免页面越长越高。</p>`,44))]))}});export{c as __pageData,E as default};
|