mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-21 19:03:35 +08:00
5.3 KiB
5.3 KiB
架构地图
Ray Template 是前端中后台模板,包含可运行的组件与路由示例。Mock 只用于演示;接入真实业务时需要自己的后端、会话和权限校验。
启动链路
index.html → 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、mock/shared |
vite-plugin-mock-dev-server,生产环境按实际后端切换 |
| 通用组件 | src/components/base、src/components/pro |
组件、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 统一生成。