mirror of
https://github.com/XiaoDaiGua-Ray/ray-template.git
synced 2026-11-20 02:03:35 +08:00
Add interactive hook examples, shared Pinia runtime state, and configurable layouts. Generate typed namespaced icons during development, HMR, and builds. Refine the UI and establish project comment and design conventions. Validation: typecheck, ESLint, 181 tests, and production build passed.
5.1 KiB
5.1 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/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/c仍使用 CryptoJS 4.2.0 的同步 AES 格式。改用 Web Crypto 前需设计异步接口和历史密文迁移,不能直接替换并让既有数据无法解密。- 演示页与业务组件同样属于模板能力。删除 demo 或更换第三方库前需要明确任务范围;升级工具链时应保留示例功能。
布局模式、配置与插槽见 布局说明。图标按包生成独立雪碧图,完整名称和严格类型由 scripts/icons.mjs 统一生成。