xuanzhi-service/web/.ai-specs/sys-specs/naming-import-path-spec.md

naming-import-path-spec

适用范围

• 涉及新增目录、文件命名、导入路径和导出命名时必读。

命名规则

• 目录命名优先跟随现有项目风格；当前项目以 lowerCamelCase 目录较多，例如 superAdmin、systemTools。
• 页面目录默认使用业务语义命名，页面入口文件优先使用 index.vue。
• pinia/modules 中的文件名使用模块名，例如 user.js、router.js、dictionary.js。
• store 导出统一使用 useXxxStore。
• 新增 hooks 优先使用 useXxx.js；若扩展现有文件族，跟随邻近文件风格。
• API 函数命名使用动词开头，优先使用 get、list、create、update、delete、set。

导入路径规则

• src 下的跨目录导入优先使用 @/ 别名。
• 同目录或紧邻目录的小范围导入可以使用相对路径。
• 禁止新增深层级 ../../../ 风格导入来绕过别名。
• 插件目录内引用主应用公共能力时，优先使用 @/components、@/utils、@/style、@/pinia。

常见错误

• 同一种概念在不同文件中使用不同命名，例如 getUserList 和 fetchUsers 混用。
• 新增 hooks 没有 use 前缀，导致和普通工具函数混淆。
• 同一功能有的用相对路径，有的用 @/，导致导入风格失控。