Skip to content

架构与扩展边界 ​

模板通过少量稳定入口隔离项目差异。业务项目优先实现这些入口,不直接修改页面、Store、守卫或布局内部实现。

稳定边界 ​

能力稳定入口项目侧扩展方式
认证src/adapters/auth/AuthAdapter实现项目适配器并替换注入点
页面认证调用src/api/auth.ts保持页面、Store 和守卫调用不变
HTTPsrc/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、应用配置或路径别名。

修改公共边界 ​

确实需要修改公共边界时:

  1. 先确认需求不能通过现有适配器、配置、插槽或路由元数据完成;
  2. 为新行为增加自动化测试;
  3. 将模板变更与业务模块变更分开;
  4. 同步、检查并独立发布 @kevairy/template;
  5. 记录兼容性影响和迁移方式。

模板版本基线与历史冻结清单属于维护资料,见模板 v0.1.0 基线。