xuanzhi-service/web/.ai-specs/sys-specs/frontend-directory-spec.md

frontend-directory-spec

适用范围

• 涉及新增目录、移动文件、决定代码落点时必读。
• 本文档只定义前端工程目录边界，不定义具体业务规则。

当前主目录职责

目录	职责	默认落点
src/view	页面级目录，负责页面编排、页面级状态、页面生命周期	新页面、新页面内局部子组件
src/components	跨页面复用组件	被多个页面或多个模块复用的 UI 片段
src/hooks	可复用组合逻辑	多页面共享的行为逻辑
src/api	主应用接口函数	主应用页面直接调用的请求封装
src/pinia/modules	跨页面共享状态	登录态、路由态、全局字典、全局配置
src/router	路由入口	静态路由定义
src/plugin	插件化业务目录	插件自己的 api / view / form
src/utils	通用工具	与页面、组件解耦的工具逻辑
src/style	全局样式与覆盖	全局样式、Element Plus 覆盖
src/assets	构建期静态资源	图片、图标、背景资源

强制规则

• 新页面默认放在 src/view/<module>，不要直接放到 src/components。
• 只有跨页面复用的 UI 才进入 src/components；只在单页内使用的组件优先放在页面目录内。
• 共享行为逻辑优先放在 src/hooks；不要把纯逻辑长期堆在页面或组件里。
• 插件相关代码优先留在 src/plugin/<plugin> 内部自洽，只有真正公共的能力才上提。
• 不允许随意新增新的 src/* 顶层目录；必须先评估现有目录是否可以承载。

常见错误

• 把单页面局部组件放进 src/components，导致公共目录堆积业务代码。
• 把页面状态塞进 pinia，导致全局状态污染。
• 为插件单独复制一套请求层、路由层或全局样式层。