外观
架构与扩展边界
模板通过少量稳定入口隔离项目差异。业务项目优先实现这些入口,不直接修改页面、Store、守卫或布局内部实现。
稳定边界
| 能力 | 稳定入口 | 项目侧扩展方式 |
|---|---|---|
| 认证 | src/adapters/auth/AuthAdapter | 实现项目适配器并替换注入点 |
| 页面认证调用 | src/api/auth.ts | 保持页面、Store 和守卫调用不变 |
| HTTP | src/utils/http/index.ts | 配置地址、鉴权方案和响应转换;取消、去重和重试 |
| 路由 | AppRouteRecord | 新增路由模块或实现服务端路由标准化器 |
| 权限 | usePermission、UserInfo.permissions | 适配项目授权数据,复用统一判断与导航校验 |
| 搜索表格 | KvSearchTablePage | 页面只配置字段、列、请求和业务插槽 |
| 页面状态 | KvStatus | 通过属性配置文案、状态和恢复动作 |
布局动效
布局入场由 src/views/index/index.vue 与同目录的 style.scss 统一管理,路由过渡由 src/assets/styles/core/router-transition.scss 管理。首次进入或浏览器刷新时,等待全屏 Loading 移除后播放菜单、工具栏和内容区块的错峰入场;日常导航与页面内刷新只过渡内容区。
内容外层只淡入,内部区块的位移在入场期间局部裁剪,避免扩大页面滚动范围。不要给撑满剩余高度的内容外层增加向下位移。移动端菜单保留独立抽屉行为;“页面切换动画”选择“无”或系统开启“减少动态效果”时,布局入场不播放。
依赖方向
text
业务页面
├── 项目 API 与适配器
├── 模板提供的应用基础设施
└── @kevairy/components 公共组件模板基础设施不能反向依赖具体业务页面或后端协议;公共组件不能依赖模板的 Pinia、Router、应用配置或路径别名。
修改公共边界
确实需要修改公共边界时:
- 先确认需求不能通过现有适配器、配置、插槽或路由元数据完成;
- 为新行为增加自动化测试;
- 将模板变更与业务模块变更分开;
- 同步、检查并独立发布
@kevairy/template; - 记录兼容性影响和迁移方式。
模板版本基线与历史冻结清单属于维护资料,见模板 v0.1.0 基线。