ray-template/docs/architecture.md
2026-11-04 16:47:18 +08:00

9.9 KiB
Raw Blame History

架构地图

Ray Template 是一个 pnpm workspace:后台负责宿主集成,文档站解释公开用法,共享包拥有可复用实现。按功能定位文件从任务索引进入;本页用于判断代码归属和追踪跨模块调用。

工作区

目录 职责与权威入口
apps/admin Ray Admin。应用配置、路由注册、Pinia、Provider、页面、演示数据与开发 Mock。Vite 的应用根目录是这里。
apps/docs VitePress 站点。读者指南、API、迁移和交互示例,消费共享包公开入口。
packages 下表列出的共享包;根入口和可导入子路径由各自的 package.json#exports 定义。
test Vitest 回归,按行为分类而非逐一镜像源码目录。通过 Harness 任务域 反查覆盖。
docs、harness 维护者约定与跨模块说明;Harness 管理任务导航、定向验证与证据。对外文档属于 apps/docs。
scripts、vite-helper、unplugin 仓库级检查、Vite 插件辅助和自动导入的生成声明。根目录保留构建、类型和 CI 配置。
共享包 实现归属 宿主边界
@ray-template/utils 精度、类型判断、数据与文件工具、通用 JSON 存储 调用方提供 Storage;应用的 key、缓存后端和旧 AES 格式留在应用。
@ray-template/composables Vue 组合式函数、DOM、元素与作用域工具 应用专用导航、主题和内容区 Hooks 留在应用。
@ray-template/directives Vue 指令与注册器 宿主提供复制提示,并选择何时注册。
@ray-template/icons SVG、清单、图标名类型与查询 构建将资源生成雪碧图,宿主提供图标解析服务。
@ray-template/ui 通用组件、共享主题及 UI 服务接口 后台注入翻译、主题、存储等;应用组件入口转导出通用组件。
@ray-template/http 独立 HTTP 客户端、拦截器和取消机制 应用传入请求配置和拦截器,封装实际业务 API。
@ray-template/routing 路由配置校验、路由展开和菜单遍历 应用持有页面注册表、配置来源、角色、会话和守卫。
@ray-template/admin-shell 布局外壳、布局设置、过渡与页面缓存渲染 宿主提供路由状态、偏好、导航和内容插槽。

应用侧 @/components、@/hooks、@/utils 有兼容入口。跟随实际导出判断实现归属。共享包不可依赖后台别名或跨 workspace 相对导入;包边界检查校验依赖声明、公开入口和循环依赖。

关键运行链路

链路 调用顺序与边界 继续阅读
后台启动 index.html → main.ts → Pinia → 国际化 → Router → Day.js → 指令与自动补全设置 → 挂载 App.tsx。普通和无界模式共用插件注册顺序。 布局与启动
导航与缓存 路由初始化加载来源 → 应用模块展开配置 → 注册守卫和页面 → 应用菜单 Store 与布局消费路由。应用维护缓存名单,共享壳渲染过渡与 KeepAlive。 路由、布局
请求与演示数据 API → 应用 Axios 实例 → 共享客户端。开发 Mock 走 HTTP;静态人员演示可用本地数据。生产会话和资源授权由接入方后端负责。 API
文档示例 文档可直接消费共享包;需要后台上下文时由 AdminExample.vue 嵌入 example.html,使用独立启动、限定路由和内存缓存。 文档与示例
应用配置 Vite 注入 __APP_CFG__ 和 __DEV__;应用配置按设计、请求、路由和缓存分组。 构建与工具链

公开行为变更按应用与文档联动维护指南和可运行示例。页面排版见视觉与排版;代码注释见注释规范。

TypeScript 项目配置

根配置引用四个项目。严格模式、模块解析和类型检查别名集中在共享配置。调整路径别名时同步核对 Vite 和 Vitest。

配置 检查范围
应用 后台 apps/admin/src、Vue JSX 和生成声明。
Node 根构建与测试配置、vite-helper、后台 Mock。
测试 __test__ 与引用源码,加载 Vitest 和 Node 类型。运行时环境由 Vitest 配置及测试文件决定。
共享包 packages/*/src,不继承应用别名或自动导入声明。
文档站 独立检查文档示例,由 pnpm docs:check 执行。

pnpm typecheck 先检查图标同步,再通过 vue-tsc --build 检查根配置引用的四个项目;增量缓存位于 node_modules/.cache/ray-template/。单独检查可使用 pnpm exec vue-tsc -p <配置文件>。

Deployment and search discovery

pnpm build 生成后台 dist/production;pnpm docs:build 生成 apps/docs/.vitepress/dist。pnpm pages:build 将两者合并到 dist/pages,文档放在其 docs/ 下。后台默认 base 为 /ray-template/,文档默认 base 为 /ray-template/docs/。自建根路径或其他子路径时,同步核对后台 base、文档 base和旧站跳转目标。

CI在主分支检查通过后将组合产物发布到 dist 分支。后台 public 中的 .nojekyll会随产物复制;手动部署到 Pages 时保留它,以便加载带下划线前缀的资源。

公开构建用 RAY_TEMPLATE_SITE_ORIGIN 配置实际站点源地址,路径由 base 提供。未设置时,后台生产构建输出 noindex。公开后台首页生成 canonical、分享预览和 sitemap.xml,不把登录后的 hash 路由列为公开页面。域名级抓取规则由站点根目录的 /robots.txt 管理。站内旧链接由 VitePress 映射生成;配置站点源地址时,合并脚本另生成 dist/legacy-docs,供旧站迁移使用。

只阅读已跟踪的源码和配置来判断实现。生成产物、依赖、缓存和 .harness-local/ 报告适合查构建与验证结果。