ray-template/docs/guide/backend.html

65 lines
52 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.

<!DOCTYPE html>
<html lang="zh-CN" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>服务端接入与标准契约 · Ray Template 文档</title>
<meta name="description" content="Ray Template 6.0.1 的 Monorepo 架构、版本分界、组件与交互示例。">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/ray-template/docs/assets/style.6J0m3LtX.css" as="style">
<link rel="preload stylesheet" href="/ray-template/docs/vp-icons.css" as="style">
<script type="module" src="/ray-template/docs/assets/app.DZGstFSm.js"></script>
<link rel="preload" href="/ray-template/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/ray-template/docs/assets/chunks/theme.DuEXda0y.js">
<link rel="modulepreload" href="/ray-template/docs/assets/chunks/framework.D8G7yXPy.js">
<link rel="modulepreload" href="/ray-template/docs/assets/guide_backend.md.DpcumSyL.lean.js">
<link rel="icon" type="image/svg+xml" href="/ray-template/docs/ray-mark.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-f9c03b6e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-770676c7></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-770676c7>跳转到正文</a><!--]--><!----><header class="VPNav" data-v-f9c03b6e data-v-b2a7789c><div class="VPNavBar" data-v-b2a7789c data-v-d231c45b><div class="wrapper" data-v-d231c45b><div class="container" data-v-d231c45b><div class="title" data-v-d231c45b><div class="VPNavBarTitle has-sidebar" data-v-d231c45b data-v-49754884><a class="title" href="/ray-template/docs/" data-v-49754884><!--[--><!--]--><!--[--><img class="VPImage logo" src="/ray-template/docs/ray-mark.svg" alt data-v-a9cdc337><!--]--><span data-v-49754884>Ray Template</span><!--[--><!--]--></a></div></div><div class="content" data-v-d231c45b><div class="content-body" data-v-d231c45b><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d231c45b><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="搜索文档"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">搜索文档</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d231c45b data-v-49bcf2ef><span id="main-nav-aria-label" class="visually-hidden" data-v-49bcf2ef> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink active" href="/ray-template/docs/guide/start.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>指南</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/guide/architecture.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>架构</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/migration.html" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>版本分界</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/ray-template/docs/reference/" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>API 参考</span><!--]--></a><!--]--><!--[--><a class="VPLink link vp-external-link-icon VPNavBarMenuLink" href="https://xiaodaigua-ray.github.io/ray-template/" target="_blank" rel="noreferrer" tabindex="0" data-v-49bcf2ef data-v-991603b8><!--[--><span data-v-991603b8>Ray Admin</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d231c45b data-v-a4a103b4><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-a4a103b4 data-v-2b76c23f data-v-54e91c08><span class="check" data-v-54e91c08><span class="icon" data-v-54e91c08><!--[--><span class="vpi-sun sun" data-v-2b76c23f></span><span class="vpi-moon moon" data-v-2b76c23f></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-d231c45b data-v-584f2254 data-v-91f5f172><!--[--><a class="VPSocialLink no-icon" href="https://github.com/XiaoDaiGua-Ray/ray-template" aria-label="github" target="_blank" rel="noopener" data-v-91f5f172 data-v-976d6037><span class="vpi-social-github"></span></a><!--]--></div><div class="VPFlyout VPNavBarExtra extra" data-v-d231c45b data-v-766dd493 data-v-57202eaf><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-57202eaf><span class="vpi-more-horizontal icon" data-v-57202eaf></span></button><div class="menu" data-v-57202eaf><div class="VPMenu" data-v-57202eaf data-v-80746065><!----><!--[--><!--[--><!----><div class="group" data-v-766dd493><div class="item appearance" data-v-766dd493><p class="label" data-v-766dd493>主题</p><div class="appearance-action" data-v-766dd493><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-766dd493 data-v-2b76c23f data-v-54e91c08><span class="check" data-v-54e91c08><span class="icon" data-v-54e91c08><!--[--><span class="vpi-sun sun" data-v-2b76c23f></span><span class="vpi-moon moon" data-v-2b76c23f></span><!--]--></span></span></button></div></div></div><div class="group" data-v-766dd493><div class="item social-links" data-v-766dd493><div class="VPSocialLinks social-links-list" data-v-766dd493 data-v-91f5f172><!--[--><a class="VPSocialLink no-icon" href="https://github.com/XiaoDaiGua-Ray/ray-template" aria-label="github" target="_blank" rel="noopener" data-v-91f5f172 data-v-976d6037><span class="vpi-social-github"></span></a><!--]--></div></div></div><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d231c45b data-v-0ee194e1><span class="container" data-v-0ee194e1><span class="top" data-v-0ee194e1></span><span class="middle" data-v-0ee194e1></span><span class="bottom" data-v-0ee194e1></span></span></button></div></div></div></div><div class="divider" data-v-d231c45b><div class="divider-line" data-v-d231c45b></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-f9c03b6e data-v-60478e07><div class="container" data-v-60478e07><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-60478e07><span class="vpi-align-left menu-icon" data-v-60478e07></span><span class="menu-text" data-v-60478e07>文档目录</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-60478e07 data-v-debc629b><button data-v-debc629b>回到顶部</button><!----></div></div></div><aside class="VPSidebar" data-v-f9c03b6e data-v-efe03c19><div class="curtain" data-v-efe03c19></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-efe03c19><span class="visually-hidden" id="sidebar-aria-label" data-v-efe03c19> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0" data-v-90a0702d data-v-d34e54b2><div class="item" role="button" tabindex="0" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><h2 class="text" data-v-d34e54b2>入门</h2><!----></div><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/start.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>快速开始</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/distributions.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>发行版本与快速启动</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/architecture.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>v6 Monorepo 架构</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/migration.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>v5 与 v6 的版本分界</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/first-page.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>第一个业务页面</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0 has-active" data-v-90a0702d data-v-d34e54b2><div class="item" role="button" tabindex="0" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><h2 class="text" data-v-d34e54b2>开发指南</h2><!----></div><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/routing.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>路由、菜单与权限</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/layout.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>应用布局与状态</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/requests.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>接口、取消与 Mock</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/backend.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>服务端接入与标准契约</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/appearance.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>主题与国际化</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/guide/tooling.html" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>工程检查与部署</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-90a0702d><section class="VPSidebarItem level-0" data-v-90a0702d data-v-d34e54b2><!----><div class="items" data-v-d34e54b2><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d34e54b2><div class="item" data-v-d34e54b2><div class="indicator" data-v-d34e54b2></div><a class="VPLink link link" href="/ray-template/docs/reference/" data-v-d34e54b2><!--[--><p class="text" data-v-d34e54b2>API 参考</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-f9c03b6e data-v-7ec33352><div class="VPDoc has-sidebar has-aside" data-v-7ec33352 data-v-b0483432><!--[--><!--]--><div class="container" data-v-b0483432><div class="aside" data-v-b0483432><div class="aside-curtain" data-v-b0483432></div><div class="aside-container" data-v-b0483432><div class="aside-content" data-v-b0483432><div class="VPDocAside" data-v-b0483432 data-v-6d31e1a2><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-6d31e1a2 data-v-a849a091><div class="content" data-v-a849a091><div class="outline-marker" data-v-a849a091></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-a849a091>本页目录</div><ul class="VPDocOutlineItem root" data-v-a849a091 data-v-78a615b5><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-6d31e1a2></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-b0483432><div class="content-container" data-v-b0483432><!--[--><!--[--><!--[--><div class="ray-doc-meta"><span>开发指南</span><a href="/ray-template/docs/reference/source.html">版本 <code>6.0.1</code></a></div><!--]--><!--]--><!--]--><main class="main" data-v-b0483432><div style="position:relative;" class="vp-doc _ray-template_docs_guide_backend" data-v-b0483432><div><h1 id="服务端接入与标准契约" tabindex="-1">服务端接入与标准契约 <a class="header-anchor" href="#服务端接入与标准契约" aria-label="Permalink to &quot;服务端接入与标准契约&quot;">​</a></h1><p>登录、会话、用户管理与路由管理使用同一套 HTTP API。源码发行和启动方式见<a href="./distributions.html">发行版本与快速启动</a>。开发环境与静态在线演示都由 MSW 在网络层模拟响应;页面和 Store 不直接读取 Mock 数据库。接入自有服务端时,保留页面与调用方法,替换接口地址和实现即可。</p><p><a href="/ray-template/docs/contracts/admin-api.json" target="_blank" rel="noreferrer">下载 OpenAPI 3.1 契约</a></p><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;"> &#39;@ray-template/api-contracts/admin&#39;</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;"> &#39;@ray-template/api-contracts/admin&#39;</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;"> &#39;@ray-template/api-contracts/demo&#39;</span></span></code></pre></div><h2 id="接入步骤" tabindex="-1">接入步骤 <a class="header-anchor" href="#接入步骤" aria-label="Permalink to &quot;接入步骤&quot;">​</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 &quot;配套 NestJS 服务端&quot;">​</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 &quot;统一响应&quot;">​</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;"> &quot;code&quot;</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;"> &quot;msg&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;OK&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;data&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;items&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;total&quot;</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>{ &quot;affected&quot;: 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;"> &quot;code&quot;</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;"> &quot;msg&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;duplicateUsername&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;data&quot;</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;"> &quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;key&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;duplicateUsername&quot;</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 &quot;登录、会话与权限&quot;">​</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;"> &quot;user&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;u-1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;username&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;admin&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Alex&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;role&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;admin&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;permissions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;users:read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;users:create&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;users:update&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;routes:read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;routes:write&quot;</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 &lt;accessToken&gt;</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;"> &#39;@/hooks&#39;</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;">// 多个权限默认全部满足;第二个参数传 &#39;any&#39; 时任意一个满足即可。</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;">&#39;users:create&#39;</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;">&#39;users:update&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;users:delete&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">], </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;any&#39;</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 &quot;用户管理&quot;">​</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: &quot;enabled&quot; 或 &quot;disabled&quot; }</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;"> &quot;username&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alex&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Alex&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;email&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alex@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;phone&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;departmentId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;engineering&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;role&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;member&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;status&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;enabled&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;remark&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&quot;</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 &quot;路由管理&quot;">​</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 &quot;在线验证&quot;">​</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></div></div></main><footer class="VPDocFooter" data-v-b0483432 data-v-028296d9><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-028296d9><span class="visually-hidden" id="doc-footer-aria-label" data-v-028296d9>Pager</span><div class="pager" data-v-028296d9><a class="VPLink link pager-link prev" href="/ray-template/docs/guide/requests.html" data-v-028296d9><!--[--><span class="desc" data-v-028296d9>上一页</span><span class="title" data-v-028296d9>接口、取消与 Mock</span><!--]--></a></div><div class="pager" data-v-028296d9><a class="VPLink link pager-link next" href="/ray-template/docs/guide/appearance.html" data-v-028296d9><!--[--><span class="desc" data-v-028296d9>下一页</span><span class="title" data-v-028296d9>主题与国际化</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-f9c03b6e data-v-20a32aa3><div class="container" data-v-20a32aa3><!----><p class="copyright" data-v-20a32aa3>© 2022–至今 Ray · MIT License</p></div></footer><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"guide_appearance.md\":\"CbhgFuQy\",\"guide_architecture.md\":\"C5f_dStb\",\"guide_backend.md\":\"DpcumSyL\",\"guide_distributions.md\":\"CquuxHZi\",\"guide_first-page.md\":\"DHqwAt4V\",\"guide_layout.md\":\"DahQh0oB\",\"guide_requests.md\":\"CZYqS1G0\",\"guide_routing.md\":\"CGQ9b6Or\",\"guide_start.md\":\"Dyl7ULXt\",\"guide_tooling.md\":\"B1a_atZw\",\"index.md\":\"B3Ji-_c4\",\"migration.md\":\"YnSE1eTb\",\"playground_shell.md\":\"jNpqmXOa\",\"reference_components.md\":\"Bj8x64hc\",\"reference_components_app.md\":\"C7wJGrLN\",\"reference_components_barcode.md\":\"05kFYpfB\",\"reference_components_chart.md\":\"CmF0yQj-\",\"reference_components_collapse-grid.md\":\"ef3DmpmT\",\"reference_components_draggable-card.md\":\"DDSUCtdc\",\"reference_components_flow.md\":\"3NC8SRXL\",\"reference_components_form.md\":\"Cm6Gckyr\",\"reference_components_iframe.md\":\"DMWNIbE9\",\"reference_components_modal.md\":\"ti54dHz0\",\"reference_components_more-dropdown.md\":\"X2TUbUVU\",\"reference_components_qr-code.md\":\"UBtVbqXa\",\"reference_components_route-transition.md\":\"DiLEQcKJ\",\"reference_components_segment.md\":\"BNEEW09r\",\"reference_configuration.md\":\"ZPlSg6sS\",\"reference_directives.md\":\"CpZHS1Mm\",\"reference_hooks.md\":\"B7r2QBiR\",\"reference_hooks_appearance.md\":\"CHWjp8Rw\",\"reference_hooks_browser.md\":\"BF1b28Me\",\"reference_hooks_interaction.md\":\"9MI9QLxG\",\"reference_hooks_layout.md\":\"ZBgUvajf\",\"reference_hooks_navigation.md\":\"UCy1Te6m\",\"reference_hooks_output.md\":\"9qljHfmL\",\"reference_icons.md\":\"DXUtpdoz\",\"reference_index.md\":\"B02Licr3\",\"reference_source.md\":\"BoVc3275\",\"reference_store.md\":\"BWJxztnK\",\"reference_store_navigation.md\":\"DGO1GZ0U\",\"reference_store_runtime.md\":\"BHW5rI8i\",\"reference_store_setting.md\":\"CF5XUyTp\",\"reference_store_signing.md\":\"DLMf-30Z\",\"reference_table-pro-examples.md\":\"Bw8WoLY8\",\"reference_table-pro.md\":\"D91H49U1\",\"reference_utils.md\":\"CFovP9sb\",\"reference_utils_browser.md\":\"WqdwCNPp\",\"reference_utils_core.md\":\"BRV-numN\",\"reference_utils_storage.md\":\"DZTFQ860\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"zh-CN\",\"dir\":\"ltr\",\"title\":\"Ray Template\",\"titleTemplate\":\":title · Ray Template 文档\",\"description\":\"Ray Template 6.0.1 的 Monorepo 架构、版本分界、组件与交互示例。\",\"base\":\"/ray-template/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":{\"src\":\"/ray-mark.svg\",\"alt\":\"\"},\"siteTitle\":\"Ray Template\",\"nav\":[{\"text\":\"指南\",\"link\":\"/guide/start\",\"activeMatch\":\"^/guide/\"},{\"text\":\"架构\",\"link\":\"/guide/architecture\"},{\"text\":\"版本分界\",\"link\":\"/migration\"},{\"text\":\"API 参考\",\"link\":\"/reference/\",\"activeMatch\":\"^/reference/\"},{\"text\":\"Ray Admin\",\"link\":\"https://xiaodaigua-ray.github.io/ray-template/\"}],\"sidebar\":{\"/reference/\":[{\"text\":\"API 参考总览\",\"link\":\"/reference/\"},{\"text\":\"组件\",\"link\":\"/reference/components\",\"collapsed\":true,\"items\":[{\"text\":\"TablePro\",\"link\":\"/reference/table-pro\"},{\"text\":\"TablePro 在线示例\",\"link\":\"/reference/table-pro-examples\"},{\"text\":\"RForm 与 useForm\",\"link\":\"/reference/components/form\"},{\"text\":\"RModal\",\"link\":\"/reference/components/modal\"},{\"text\":\"RChart 与 useChart\",\"link\":\"/reference/components/chart\"},{\"text\":\"RFlow 与 useFlow\",\"link\":\"/reference/components/flow\"},{\"text\":\"RCollapseGrid\",\"link\":\"/reference/components/collapse-grid\"},{\"text\":\"RSegment\",\"link\":\"/reference/components/segment\"},{\"text\":\"RMoreDropdown\",\"link\":\"/reference/components/more-dropdown\"},{\"text\":\"RIframe\",\"link\":\"/reference/components/iframe\"},{\"text\":\"RBarcode\",\"link\":\"/reference/components/barcode\"},{\"text\":\"RDraggableCard\",\"link\":\"/reference/components/draggable-card\"},{\"text\":\"RTransitionComponent\",\"link\":\"/reference/components/route-transition\"},{\"text\":\"RIcon 与 SVG 图标\",\"link\":\"/reference/icons\"},{\"text\":\"二维码\",\"link\":\"/reference/components/qr-code\"},{\"text\":\"应用组件与 Provider\",\"link\":\"/reference/components/app\"}]},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\",\"collapsed\":true,\"items\":[{\"text\":\"导航与菜单\",\"link\":\"/reference/hooks/navigation\"},{\"text\":\"布局与滚动\",\"link\":\"/reference/hooks/layout\"},{\"text\":\"主题、语言和水印\",\"link\":\"/reference/hooks/appearance\"},{\"text\":\"分页与右键菜单\",\"link\":\"/reference/hooks/interaction\"},{\"text\":\"窗口、全屏和日期\",\"link\":\"/reference/hooks/browser\"},{\"text\":\"DOM 截图与打印\",\"link\":\"/reference/hooks/output\"}]},{\"text\":\"指令\",\"link\":\"/reference/directives\"},{\"text\":\"Store\",\"link\":\"/reference/store\",\"collapsed\":true,\"items\":[{\"text\":\"Setting\",\"link\":\"/reference/store/setting\"},{\"text\":\"Menu 与 KeepAlive\",\"link\":\"/reference/store/navigation\"},{\"text\":\"Runtime 与 Lock Screen\",\"link\":\"/reference/store/runtime\"},{\"text\":\"Signing\",\"link\":\"/reference/store/signing\"}]},{\"text\":\"工具函数\",\"link\":\"/reference/utils\",\"collapsed\":true,\"items\":[{\"text\":\"基础、日期和数值\",\"link\":\"/reference/utils/core\"},{\"text\":\"缓存与兼容加密\",\"link\":\"/reference/utils/storage\"},{\"text\":\"Vue 与浏览器工具\",\"link\":\"/reference/utils/browser\"}]},{\"text\":\"应用配置\",\"link\":\"/reference/configuration\"},{\"text\":\"文档与源码版本\",\"link\":\"/reference/source\"}],\"/\":[{\"text\":\"入门\",\"items\":[{\"text\":\"快速开始\",\"link\":\"/guide/start\"},{\"text\":\"发行版本与快速启动\",\"link\":\"/guide/distributions\"},{\"text\":\"v6 Monorepo 架构\",\"link\":\"/guide/architecture\"},{\"text\":\"v5 与 v6 的版本分界\",\"link\":\"/migration\"},{\"text\":\"第一个业务页面\",\"link\":\"/guide/first-page\"}]},{\"text\":\"开发指南\",\"items\":[{\"text\":\"路由、菜单与权限\",\"link\":\"/guide/routing\"},{\"text\":\"应用布局与状态\",\"link\":\"/guide/layout\"},{\"text\":\"接口、取消与 Mock\",\"link\":\"/guide/requests\"},{\"text\":\"服务端接入与标准契约\",\"link\":\"/guide/backend\"},{\"text\":\"主题与国际化\",\"link\":\"/guide/appearance\"},{\"text\":\"工程检查与部署\",\"link\":\"/guide/tooling\"}]},{\"text\":\"API 参考\",\"link\":\"/reference/\"}]},\"outline\":{\"label\":\"本页目录\",\"level\":[2,3]},\"search\":{\"provider\":\"local\",\"options\":{\"translations\":{\"button\":{\"buttonText\":\"搜索文档\",\"buttonAriaLabel\":\"搜索文档\"},\"modal\":{\"noResultsText\":\"未找到相关内容\",\"resetButtonTitle\":\"清除搜索\",\"footer\":{\"selectText\":\"打开\",\"navigateText\":\"切换\",\"closeText\":\"关闭\"}}}}},\"skipToContentLabel\":\"跳转到正文\",\"docFooter\":{\"prev\":\"上一页\",\"next\":\"下一页\"},\"returnToTopLabel\":\"回到顶部\",\"sidebarMenuLabel\":\"文档目录\",\"darkModeSwitchLabel\":\"主题\",\"lightModeSwitchTitle\":\"切换到浅色\",\"darkModeSwitchTitle\":\"切换到深色\",\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/XiaoDaiGua-Ray/ray-template\"}],\"footer\":{\"copyright\":\"© 2022–至今 Ray · MIT License\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
</body>
</html>