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

80 lines
10 KiB
Markdown
Raw 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.

# 架构地图
Ray Template 是前端中后台模板,包含可运行的组件与路由示例。Mock 只用于演示;接入真实业务时需要自己的后端、会话和权限校验。
Ray Template 由一个 pnpm workspace 管理。**Ray Admin** 位于 `apps/admin`,在应用入口接入路由、会话、主题和数据。**文档**位于 [apps/docs](../apps/docs/README.md),直接使用共享包的公开入口。
| 工作区 | 公开职责 |
| --------------------------- | -------------------------------------------------------------------------------- |
| `@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` | [路由文档](../apps/admin/src/router/README.md),菜单由路由生成 |
| 权限与守卫 | `src/router/utils/vue-router-register.ts`、`src/router/utils/permission.ts` | 同时检查菜单显示与实际导航;前端权限不能替代后端授权 |
| 全局状态 | `src/store/modules`、`src/store/hooks` | [Store 文档](../apps/admin/src/store/README.md),持久化配置使用 `pick`/`omit` |
| 请求与接口 | `src/api`、`src/axios` | [请求文档](../apps/admin/src/axios/README.md),请求/响应拦截器分开注册 |
| 演示接口 | `mock/demo`、`src/demo-data` | `vite-plugin-mock-dev-server`,生产环境按实际后端切换 |
| 通用组件 | `src/components` | 组件、props、types、hook、样式放在同一功能目录 |
| 模板绑定组件 | `src/app-components` | [组件说明](../apps/admin/src/app-components/README.md) |
| 公共工具 | `src/utils` | [分包、兼容入口和测试](../apps/admin/src/utils/README.md) |
| 组合式函数 | `src/hooks/web`、`template`、`components` | [19 个 Hook 的示例与生命周期](../apps/admin/src/hooks/README.md),回归测试在 `__test__/hooks` |
| 国际化 | `src/locales/lang`、`src/hooks/web/useI18n.ts` | [国际化说明](../apps/admin/src/locales/README.md),中文和英文成对维护 |
| 主题与全局样式 | `src/app-config/design-config.ts`、`src/styles` | 保留 CSS 变量和 Naive UI 明暗主题配置 |
| SVG 图标 | `src/icons`、`RIcon` | [图标说明](../packages/icons/src/A_README.md),名称与分包约定影响 symbol ID |
| 全局指令 | `src/directives/modules` | [注册约定](../apps/admin/src/directives/README.md)、[用法](../apps/admin/src/directives/README.DIR.md) |
| 构建与插件 | `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 或更换第三方库前需要明确任务范围;升级工具链时应保留示例功能。
布局模式、配置与插槽见 [布局说明](../apps/admin/src/layout/README.md)。图标按包生成独立雪碧图,完整名称和严格类型由 `scripts/icons.mjs` 统一生成。
页面标题、配色与示例排版见 [视觉与排版](ui-design.md);注释位置与格式遵循 [注释规范](comment-style.md)。
## TypeScript 项目配置
[根配置](../tsconfig.json) 引用应用、Node 和测试项目。严格模式、模块解析和类型检查别名集中在 [共享配置](../tsconfig.base.json)。修改别名时同步更新 `vite.custom.config.ts`。
| 配置 | 检查范围 |
| ----------------------------- | -------------------------------------------------- |
| [应用](../tsconfig.app.json) | `src`、Vue JSX 与自动生成声明 |
| [Node](../tsconfig.node.json) | 构建与测试配置、`vite-helper`、`mock` |
| [测试](../tsconfig.test.json) | `__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 发布说明](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site)
官方 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](https://search.google.com/search-console/about) 提交部署路径下的 sitemap。若管理整个域名,也可从域名根目录的 `/robots.txt` 指向 sitemap;子目录里的 `robots.txt` 不会被识别。