用途:指导构建、移植或重构不属于单个组件的中型 Vue 3 功能,即一个页面/视图加上其背后的展示组件、组合式函数、数据访问与路由如何跨文件协作。内容与具体库无关。
核心原则:视图是唯一编排者,持有数据、状态与处理器,通过实例化功能组合式函数获得;组件为 props 进、事件出,只使用 defineProps、defineEmits、defineModel,不自行取数。块级标记(工具栏、筛选、卡片、列表、合计、空状态)应拆为独立组件。
分层:数据访问(类型/模型与服务)、组合式函数(取数、加载/错误与派生状态)、组件(特性文件夹加 barrel 导出)、视图/页面、路由,以及横切的工具、图标与 i18n 文本。分层方式因项目而异,但“组件内不取数”是恒定约束。
构建顺序自底向上:数据访问、组合式函数、展示组件、视图、路由、横切关注点。
结构与导入:组件按 component/<domain>/<feature>/ 归组,含 types.ts 与 index.ts;域共享组件放在 component/<domain>/,通用组件放 component/common/。域共享组件按自身路径导入以避免循环依赖;统一使用路径别名导入,仅同特性子文件用相对路径。新建文件即接入 barrel。
取数:放入 use<Feature> 组合式函数,暴露 data、isLoading、isEmpty、error、reload;isEmpty 应派生为 loaded && !isLoading && count === 0,渲染顺序为骨架、错误、空、数据。优先复用项目已有数据辅助器;若使用 @basmilius/common,其 useDataTable、useDataReport 即为该辅助器。
状态重置:模块级(单例)或 store 状态需提供 reset() 并在列表视图 onUnmounted 调用;组件作用域状态无需重置。reset() 不得触发重新取数。
路由:一个屏幕一条路由,视图用动态 import() 懒加载;守卫、权限、标题放入 meta 并在导航守卫中读取。弹层/覆盖屏可建模为列表的子路由以支持深链与返回,通过嵌套 RouterView 渲染,参数用 props: true 传递,关闭时导航至父路由。权限细节依项目 CLAUDE.md。
横切:图标注册到中央注册表并类型化名称;格式化器放 util/ 并 barrel 导出;面向用户文本走 i18n,覆盖所有语言。
相关技能:vue-component-anatomy(单文件写法)、flux-ui(选用 Flux 组件时)、basmilius(使用其包时的数据与状态层)、仓库的 CLAUDE.md / AGENTS.md(项目特定规则)。
限制:资料未提供具体价格、平台与效果说明;权限模型、状态库、i18n 位置等项目特定规则需查阅仓库文档。