ray-template/apps/docs/guide/architecture.md
2026-11-19 15:17:29 +08:00

228 lines
15 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.

# v6 Monorepo 架构
Ray Template v6 使用同一个 pnpm workspace 管理 Ray Admin、VitePress 文档站和 10 个共享包。Ray Admin 负责登录、业务页面和应用状态。文档站用同一份组件源码运行示例,共享包通过公开入口提供可复用的实现。
## 工作区总览
```text
ray-template/
├─ apps/
│ ├─ admin/ Ray Admin
│ │ ├─ index.html 后台入口
│ │ ├─ example.html 文档示例入口
│ │ └─ src/
│ │ ├─ main.ts 应用启动
│ │ ├─ App.tsx 全局服务
│ │ ├─ app-config/ 应用配置
│ │ ├─ app-components/ 宿主组件
│ │ ├─ locales/ 中英文资源
│ │ ├─ router/ 路由与守卫
│ │ │ └─ config/ 配置源与视图表
│ │ ├─ store/ Pinia 状态
│ │ │ ├─ modules/ 会话/菜单/偏好
│ │ │ └─ hooks/ 状态读写入口
│ │ ├─ layout/ 外壳适配
│ │ ├─ views/ 业务和演示页面
│ │ ├─ api/ 业务端点
│ │ │ ├─ admin/ 管理端点
│ │ │ └─ demo/ 示例查询
│ │ ├─ axios/ 请求和拦截器
│ │ └─ mocks/ MSW 与演示状态
│ └─ docs/ VitePress
│ ├─ .vitepress/
│ │ ├─ config.mts 站点配置
│ │ ├─ sidebar.mts 文档侧栏
│ │ ├─ legacy.mts 旧链接映射
│ │ └─ theme/ 主题和样式
│ ├─ guide/ 开发指南
│ ├─ reference/ API 参考
│ ├─ examples/ Vue 交互示例
│ └─ playground/ 布局预览页面
├─ packages/
│ ├─ admin-shell/ 布局外壳
│ ├─ routing/ 路由与导航
│ ├─ ui/ 组件与主题
│ ├─ icons/ SVG 图标
│ ├─ http/ 请求与取消
│ ├─ api-contracts/ API 与路由契约
│ ├─ demo-data/ 演示数据与查询
│ ├─ composables/ Vue Hooks
│ ├─ directives/ Vue 指令
│ └─ utils/ 工具函数
├─ harness/ 任务索引与检查
└─ pnpm-lock.yaml 工作区锁文件
```
Ray Admin 使用图中的全部共享包。文档站直接引入组件、布局、路由等示例所需的包,需要完整后台上下文时通过 iframe 打开独立的示例入口。各应用在自己的 `package.json` 声明依赖,共用一份锁文件。 [工作区配置](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/pnpm-workspace.yaml) · [完整工程地图](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/docs/architecture.md)
<!-- fullstack:start -->
全栈源码还包含独立运行的 `apps/server`。 [服务端架构](#可选服务端怎样分层)
<!-- fullstack:end -->
## Ray Admin 怎么组装
### 启动与全局服务
```text
index.html → main.ts
↓
安装 Pinia 和中英文语言包
↓
恢复会话 → 初始化 Vue Router
↓
安装 Day.js 和指令 → 挂载 App
↓
App.tsx → 全局 Provider
↓
RouterView → 当前路由页面
```
独立运行和无界子应用使用同一套插件安装流程。启动时先恢复会话,再决定是否加载账户路由。`src/app-config/` 集中提供主题、路由、请求和缓存配置。 [启动入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/main.ts) · [应用配置](../reference/configuration)
`App.tsx` 装配 Naive UI、全局样式、水印和加载状态,通过 `@ray-template/ui/services` 注入主题、翻译、图标地址、消息回调和列偏好存储。共享 UI 组件通过 `UiServices` 读取这些能力,因此文档示例也可以按自己的上下文使用组件。 [App 源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/App.tsx)
### 从路由配置到菜单和页面
```text
内置 JSON / 本地配置 / 远端配置
↓
router/config/source.ts 选择配置源
↓
api-contracts 校验路由结构
↓
routing + config/views.ts
将 view ID 绑定到页面加载函数
↓
Vue Router + 应用守卫
├─→ store/menu → 菜单、标签、面包屑
└─→ RLayout → AdminShell → 页面
```
- `router/` 负责注册登录页、系统页和当前账户的路由。内置配置来自 `demo-data`,应用在 `router/config/views.ts` 登记可加载的 `views/` 页面。导航守卫根据已核验的会话和路由权限判断能否进入页面。 [路由、菜单与权限](./routing)
- `store/` 按职责维护状态。`signing` 管理会话,`menu` 根据权限生成菜单并随路由同步标签和面包屑,`keep-alive` 维护页面缓存名单。`setting` 持久化选定的偏好字段,`runtime` 中的加载、抽屉和最大化状态随应用重新挂载而重建。应用通过 Store Hooks 读写这些状态。 [Store 参考](../reference/store)
- `layout/` 是后台对共享外壳的适配层。`RLayout` 将布局偏好和导航、内容等插槽交给 `AdminShell`。默认内容槽装配请求取消和路由过渡,过渡组件根据缓存配置和名单渲染 `KeepAlive`。 [应用布局与状态](./layout)
### 一次业务请求经过哪些层
```text
views/ 或 store/
↓ 调用业务接口
api/admin/ 或 api/demo/
↓
axios/ 应用拦截器
↓
@ray-template/http Axios 实例
├─→ MSW → mocks/ → 演示数据
└─→ HTTP → 接入的 API
```
`api/` 封装端点,管理端客户端处理会话传输,并用 `api-contracts` 校验响应。`axios/` 根据应用配置装配请求、响应和错误拦截器。`http` 为每个实例创建取消器,调用方可传入自己的 `AbortSignal`。 [接口、取消与 Mock](./requests)
本地开发和静态在线演示可走同一套 MSW HTTP Mock。`mocks/handlers.ts` 实现接口,`mocks/database.ts` 管理演示会话、用户和路由的读写,`demo-data` 提供初始数据和查询辅助。接入真实 API 后,由服务端核验会话并授权资源访问。 [服务端接入与标准契约](./backend)
## 文档怎样运行组件
```text
文档页面
├─ 直接渲染 examples/*.vue
│ └─ 共享包入口(如 ui/table-pro)
└─ 通过 AdminExample.vue 嵌入页面
└─ admin/example.html
└─ documentation-example.tsx
└─ 允许展示的后台示例路由
```
- **直接运行。** 精度运算、条形码和 TablePro 等 Vue 示例导入共享包,Markdown 引用同一份 `.vue` 文件展示源码。TablePro 由示例传入本地行数据或可取消的模拟查询。布局实验使用单独的预览页面和内存路由。 [精度运算](../reference/utils/core#交互示例) · [条形码](../reference/components/barcode#交互示例) · [TablePro 示例](../reference/table-pro#交互示例) · [布局实验](./layout#在线布局实验)
- **嵌入后台示例。** 依赖后台布局或应用上下文的例子使用 `AdminExample.vue`。后台的 `example.html` 有独立启动入口、受限的示例路由和独立 Pinia 实例,普通应用缓存走内存,表格列显隐走单独的会话存储命名空间。 [文档站源码说明](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/docs/README.md)
<!-- fullstack:start -->
## 可选服务端怎样分层
`apps/server/src/main.ts` 启动独立的 NestJS HTTP 服务。`app.ts` 注册业务模块、平台中间件以及全局响应拦截器和异常过滤器。
```text
浏览器 /api 请求
↓
platform/ ─────────→ Redis
↓ 限流、演示缓存
NestJS 守卫与控制器
├─ auth / users / routes
│ └─ Prisma → PostgreSQL
└─ demo(按配置启用)
└─ @ray-template/demo-data
```
- `modules/auth/` 管理认证与会话,并安装全局权限守卫。`modules/users/` 负责账户管理和部门、角色选项,`modules/routes/` 读取、过滤和保存路由配置。业务模块通过共享的 `api-contracts` 定义和校验 HTTP 数据。
- `infrastructure/database.ts` 封装 Prisma 访问。`prisma/` 下的 schema 和迁移定义 PostgreSQL 中的用户、凭据、权限、会话、路由配置和操作审计。会话及权限以数据库为准。
- `platform/` 管理 Redis、请求 ID、日志、安全中间件与健康检查。Redis 用于限流和部分可重建的演示读请求缓存。演示端点按部署配置启用,共用 `demo-data`。
`apps/server` 独立构建,包含在全栈源码发行包中。 [服务端源码说明](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/server/README.md) · [发行版本与快速启动](./distributions)
<!-- fullstack:end -->
## 各包负责什么
下图只画共享包之间的直接依赖,箭头从使用方指向被依赖方。图中的短目录名对应 `@ray-template/<包名>`。
```text
admin-shell
├─→ ui ───────┬─→ composables
│ ├─→ icons
│ └─→ utils
├─→ routing ──┬─→ api-contracts
│ ├─→ icons
│ └─→ utils
├─→ composables
└─→ icons
directives ──┬─→ composables
└─→ utils
composables ───→ utils
http ──────────→ utils
demo-data ─────→ api-contracts
```
包通过 `package.json#exports` 声明可导入的入口。跨工作区优先按功能导入,例如 `@ray-template/ui/table-pro` 或 `@ray-template/utils/precision`。`rayTemplate.runtime` 区分 `browser`、`server` 与 `universal`。`api-contracts` 和 `demo-data` 是通用包,可供浏览器端和服务端使用,且只依赖同为通用的工作区。应用位于依赖图的消费端,各自通过公开入口组装功能。`pnpm packages:check` 检查工作区依赖、公开入口和循环依赖。 [包边界检查](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/scripts/check-package-boundaries.mjs)
### 界面、布局与路由
- **`@ray-template/admin-shell`** 以 `AdminShell.tsx` 实现布局模式和插槽位置,`TopNavigation.tsx`、`ShellTab.tsx` 和 `menu-keyboard.ts` 封装导航、标签和键盘交互。`LayoutSettings.tsx` 提供布局选项,`RouteTransition.vue` 负责过渡与缓存渲染。宿主传入布局状态、菜单项、导航动作和页面内容。 [外壳公开入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/admin-shell/src/index.ts)
- **`@ray-template/routing`** 通过 `/contract` 接收宿主注册的视图、保留路径和权限规则,把可序列化配置转换为 Vue Router 记录,并支持导出。`/expand-routes`、`/order-routes` 和 `/navigation` 提供展开、排序和菜单树遍历。`/schema` 和 `/json-schema` 保留兼容入口,对应实现来自 `api-contracts`。 [路由包公开入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/routing/package.json)
- **`@ray-template/ui`** 按组件组织实现、类型和样式,提供 `/table-pro`、`/form`、`/chart`、`/barcode` 等入口。`/theme.css` 和 `/theme-presets` 提供设计变量与主题预设,`/services` 把宿主的主题、翻译、消息和存储适配接入组件。 [组件参考](../reference/components)
- **`@ray-template/icons`** 按目录组织 SVG,由生成的 `/manifest` 提供完整图标名、类型和分组资源地址。后台构建按组生成精灵图。`RIcon` 和路由配置复用同一套名称,例如 `navigation/table`。 [SVG 图标](../reference/icons)
以 TablePro 为例,`TablePro.tsx` 组合筛选、分页、查询和实例 API,`useTableSearch` 管理搜索草稿与提交条件,`useTableRequest` 管理远端请求状态和取消,`TablePanel` 负责 Naive UI 表格、列设置与表格工具。宿主决定查询实现和列偏好存储。 [TablePro 参考](../reference/table-pro) · [组件源码入口](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/ui/src/RTablePro/index.ts)
```text
搜索提交 / 切换分页
↓
TablePro → useTableRequest
↓
宿主 request(params, signal)
↓
本页 data + 筛选后的 total
↓
TablePanel → Naive UI NDataTable
```
### HTTP、契约与演示数据
- **`@ray-template/http`** 通过 `client.ts` 的 `createHttpClient` 装配独立的 Axios 实例。实例解析并返回 HTTP 响应体,`RequestCanceler` 跟踪和清理待处理请求。宿主配置地址、请求头和拦截策略。 [请求客户端源码](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/http/src/client.ts)
- **`@ray-template/api-contracts`** 在 `/admin` 定义通用响应、会话和管理接口模型,在 `/demo` 定义演示查询和响应。`routes.ts` 是路由 Schema 的源文件,`/route-validation` 提供结构校验,`/route-json-schema` 和 `/openapi` 生成供编辑器和 API 集成使用的描述。前端、Mock 和服务端共用这套 Valibot 契约。 [契约包说明](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/api-contracts/README.md)
- **`@ray-template/demo-data`** 在 `routes.json` 提供内置路由,并提供初始选项、图表、订单和人员数据,以及搜索、筛选和分页辅助函数。调用方决定何时启用演示,并负责自己的会话和写入。 [演示数据包说明](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/demo-data/README.md)
### Hooks、指令与工具
- **`@ray-template/composables`** 在 `/vue` 提供 Vue 生命周期与元素引用等辅助函数,功能 Hook 按入口拆分,例如 `/useDevice`、`/useElementFullscreen`、`/useDomToImage` 和 `/usePrint`。后台特有的导航、布局和状态 Hooks 由 `apps/admin/src/hooks/template/` 维护。 [Hooks 参考](../reference/hooks)
- **`@ray-template/directives`** 在 `src/modules/` 按指令组织实现和类型。宿主可按需导入 `/copy`、`/debounce`、`/throttle` 等入口,Ray Admin 的 `src/directives/index.ts` 统一注册模板所用指令。 [指令参考](../reference/directives)
- **`@ray-template/utils`** 通过 `/precision` 提供精度运算,`/core`、`/files` 和 `/types` 提供对象、文件和类型工具。`/storage` 接收宿主提供的存储实现后执行带命名空间的 JSON 读写,应用负责选择存储位置与缓存键。 [工具函数参考](../reference/utils)
## 构建与部署
`pnpm dev` 启动后台,`pnpm docs:dev` 启动文档。`pnpm build` 输出后台,`pnpm docs:build` 输出文档,`pnpm pages:build` 组装两者到 `dist/pages`。官方部署路径分别是 `/ray-template/` 和 `/ray-template/docs/`。 [构建与部署指南](./tooling)
如果当前项目基于 v5,请先查看兼容范围和接入方式。 [版本分界](../migration)