ray-template/docs/architecture.md
XiaoDaiGua-Ray 403fdd589a feat!: rebuild Ray Template as a monorepo
Share workspace packages between Ray Admin and the interactive docs.

BREAKING CHANGE: v6 is a new major line. v5 stays on legacy/v5.
2026-11-04 14:01:28 +08:00

10 KiB
Raw Blame History

架构地图

Ray Template 是前端中后台模板,包含可运行的组件与路由示例。Mock 只用于演示;接入真实业务时需要自己的后端、会话和权限校验。

Ray Template 由一个 pnpm workspace 管理。Ray Admin 位于 apps/admin,在应用入口接入路由、会话、主题和数据。文档位于 apps/docs,直接使用共享包的公开入口。

工作区 公开职责
@ray-template/utils 精度、类型判断、数据与文件工具,以及接收存储实现的 JSON 读写。
@ray-template/composables 可独立使用的 Vue Hooks、元素与作用域工具。
@ray-template/directives Vue 指令与注册器。复制提示由宿主提供。
@ray-template/icons SVG 资源、清单、图标名称类型与查询。
@ray-template/ui 可复用组件及主题样式。TablePro、图表和条码支持按入口导入。
@ray-template/http 每个客户端独立的请求拦截和取消。
@ray-template/routing 路由配置校验、路由展开和菜单遍历。页面注册表由应用传入。
@ray-template/admin-shell 布局框架、布局设置、路由过渡和页面缓存渲染。宿主传入导航、内容、偏好和路由状态。

应用的 @/components、@/hooks 和 @/utils 继续作为模板中的导入入口。共享包声明直接依赖,公开入口通过 exports 控制。pnpm packages:check 检查跨包导入和循环依赖,独立 TypeScript 项目检查共享包能脱离应用的路径别名和全局声明。

启动链路

apps/admin/index.html → apps/admin/src/main.ts → Pinia → 国际化 → Router → Day.js → 全局指令 → App.tsx。main.ts 同时保留无界微前端挂载和卸载入口;调整启动顺序时检查这两条路径。

src/App.tsx 组合全局 Provider 与布局。布局位于 src/layout;全局 Naive UI 消息等实例由 src/app-components/provider 提供。不要在 Provider 初始化前使用 window.$message 等对象。

模块与扩展入口

需求 入口 相关约定
新增页面与菜单 src/views、src/router/modules 路由文档,菜单由路由生成
权限与守卫 src/router/utils/vue-router-register.ts、src/router/utils/permission.ts 同时检查菜单显示与实际导航;前端权限不能替代后端授权
全局状态 src/store/modules、src/store/hooks Store 文档,持久化配置使用 pick/omit
请求与接口 src/api、src/axios 请求文档,请求/响应拦截器分开注册
演示接口 mock/demo、src/demo-data vite-plugin-mock-dev-server,生产环境按实际后端切换
通用组件 src/components 组件、props、types、hook、样式放在同一功能目录
模板绑定组件 src/app-components 组件说明
公共工具 src/utils 分包、兼容入口和测试
组合式函数 src/hooks/web、template、components 19 个 Hook 的示例与生命周期,回归测试在 __test__/hooks
国际化 src/locales/lang、src/hooks/web/useI18n.ts 国际化说明,中文和英文成对维护
主题与全局样式 src/app-config/design-config.ts、src/styles 保留 CSS 变量和 Naive UI 明暗主题配置
SVG 图标 src/icons、RIcon 图标说明,名称与分包约定影响 symbol ID
全局指令 src/directives/modules 注册约定、用法
构建与插件 vite.config.ts、vite.plugin.config.ts、vite.custom.config.ts 部署 base、输出目录、CDN、开发代理均在配置中管理
自动导入 vite.plugin.config.ts、unplugin 首次构建可更新生成声明;生成声明需要随对应依赖变化一起提交
测试 __test__、vitest.config.ts Happy DOM 单元测试,不能证明真实浏览器布局、下载或打印正确

数据与调用约束

  • src/app-config 管理模板配置。运行时 __APP_CFG__ 由 Vite 注入;__DEV__ 表示 development 模式。
  • 路径别名 @、@api、@images、@mock 在 Vite 和 TypeScript 中必须一致。
  • src/store/hooks 是已有业务对 Store 的访问层;所有全局可变 UI 状态统一归入 Pinia:临时状态由 runtime 管理且不持久化,布局偏好在 setting.layoutConfig 中沿用原缓存 key。
  • src/utils/legacy-crypto(原 src/utils/c)仍使用 CryptoJS 4.2.0 的同步 AES 格式。改用 Web Crypto 前需设计异步接口和历史密文迁移,不能直接替换并让既有数据无法解密。
  • 演示页与业务组件同样属于模板能力。删除 demo 或更换第三方库前需要明确任务范围;升级工具链时应保留示例功能。

布局模式、配置与插槽见 布局说明。图标按包生成独立雪碧图,完整名称和严格类型由 scripts/icons.mjs 统一生成。

页面标题、配色与示例排版见 视觉与排版;注释位置与格式遵循 注释规范。

TypeScript 项目配置

根配置 引用应用、Node 和测试项目。严格模式、模块解析和类型检查别名集中在 共享配置。修改别名时同步更新 vite.custom.config.ts。

配置 检查范围
应用 src、Vue JSX 与自动生成声明
Node 构建与测试配置、vite-helper、mock
测试 __test__ 与引用源码,加载 Happy DOM 和 Node 类型

pnpm typecheck 通过 vue-tsc --build 检查三个项目,增量缓存存放于 node_modules/.cache/ray-template/。需要完整重查时使用 pnpm exec vue-tsc --build --force。单独检查应用或测试可用 pnpm exec vue-tsc -p tsconfig.app.json 或 pnpm exec vue-tsc -p tsconfig.test.json,Node 配置可用 pnpm exec tsc -p tsconfig.node.json。

Deployment and search discovery

pnpm build 生成 dist/production,pnpm pages:build 将后台与文档组合到 dist/pages;将该目录的内容部署到 vite.custom.config.ts 中 base 对应的路径。默认路径为 /ray-template/,部署在域名根目录时改用 /。

从 dist 分支发布 GitHub Pages 时,Vite 会将 public/.nojekyll 复制到产物根目录。手动上传产物时也要保留此文件,让 Pages 跳过 Jekyll,避免过滤 _toKey-*.js 等以下划线开头的文件。GitHub Pages 发布说明

官方 GitHub Pages 部署会设置 RAY_TEMPLATE_SITE_ORIGIN=https://xiaodaigua-ray.github.io。如需让自己的公开部署被搜索引擎检索,在生产构建中设置该变量为实际站点源地址,例如 https://example.com,路径由 Vite 的 base 提供。在 fork 的 GitHub Actions 中可以使用同名的仓库变量。未设置时,构建输出 noindex,适合预览和内部部署。

公开构建在 HTML 中输出页面描述、规范链接(canonical)和分享预览,并生成 sitemap.xml。站点地图只列出公开首页;登录后的 hash 路由仍用作交互演示。可在 Google Search Console 提交部署路径下的 sitemap。若管理整个域名,也可从域名根目录的 /robots.txt 指向 sitemap;子目录里的 robots.txt 不会被识别。