cz-app/docs/src-directory-convention.md

src 目录结构规范

本文档定义 src 目录下的文件组织方式与命名规范。后续新增与修改的代码必须严格遵循本规范。

目录总览

src/
├── pages/              # 页面组件
├── components/         # 全局公共组件
├── business-cmp/       # 业务组件（页面专用）
├── static/             # 静态资源
├── api/                # 网络请求接口
├── stores/             # 状态管理（Pinia）
├── utils/              # 工具函数
├── types/              # TypeScript 类型定义
├── hooks/              # Vue Composition API Hooks
└── styles/             # 全局样式

---

各目录说明

pages — 页面组件

存放应用页面级组件，每个页面独立一个文件夹。

规则	说明
文件夹命名	kebab-case（小写 + 连字符）
示例	user-login/、home-index/

推荐结构：

pages/
├── user-login/
│   ├── index.vue           # 页面入口
│   └── components/         # 仅该页面使用的组件（可选）
│       └── LoginForm.vue
└── home-index/
    └── index.vue

页面专属组件优先放在 pages/<page-name>/components/ 下；若业务组件较多、需跨页面复用但又不属于全局公共组件，可使用 business-cmp/。

---

components — 全局公共组件

存放可在多个页面复用的通用 UI 组件。

规则	说明
文件命名	PascalCase（大驼峰）
文件扩展名	.vue
示例	AppFooter.vue、InputEntry.vue

适用场景：

• 按钮、输入框、弹窗等基础 UI 封装
• 布局类组件（Header、Footer、Sidebar 等）
• 与具体业务无关、可在任意页面引用的组件

---

business-cmp — 业务组件

存放与特定业务逻辑绑定、不对外全局复用的组件。

规则	说明
组织方式	按业务模块或页面分子目录
文件命名	PascalCase
示例	business-cmp/order/OrderCard.vue

与 components 的区别：

目录	复用范围	示例
components/	全局、跨业务复用	AppFooter.vue
business-cmp/	特定业务/页面	OrderCard.vue
pages/xxx/components/	仅单个页面	LoginForm.vue

选择原则：

1. 仅一个页面使用 → pages/<page>/components/
2. 同一业务模块内多页面复用 → business-cmp/<module>/
3. 跨业务、通用 UI → components/

---

static — 静态资源

存放图片、字体、图标等静态文件。

规则	说明
文件/文件夹命名	小写（可用连字符分隔）
示例	logo.png、github.svg、icon-arrow.png

推荐结构：

static/
├── images/
│   └── banner.png
├── icons/
│   └── home.svg
└── fonts/
    └── custom-font.woff2

---

api — 网络请求接口

封装所有后端 API 调用，按业务模块拆分文件。

规则	说明
文件命名	kebab-case 或按模块命名
文件扩展名	.ts
示例	user.ts、order.ts

示例：

// api/user.ts
export function login(data: LoginParams) {
  return request.post<LoginResult>('/user/login', data)
}

---

stores — 状态管理

使用 Pinia 管理全局状态，按功能模块拆分 Store。

规则	说明
文件命名	kebab-case 或 useXxxStore 风格
文件扩展名	.ts
示例	user.ts、cart.ts

示例：

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  // ...
})

---

utils — 工具函数

存放与业务无关的纯函数工具。

规则	说明
文件命名	kebab-case
文件扩展名	.ts
示例	format-date.ts、storage.ts

适用场景：

• 日期/金额格式化
• 本地存储封装
• 通用校验、防抖节流等

---

types — TypeScript 类型定义

集中管理项目中的 TypeScript 类型与接口。

规则	说明
文件命名	kebab-case
文件扩展名	.ts（必须）
示例	user.ts、api-response.ts

示例：

// types/user.ts
export interface UserInfo {
  id: number
  name: string
}

---

hooks — Composition API Hooks

封装可复用的 Vue Composition API 逻辑。

规则	说明
文件命名	kebab-case，以 use 开头
文件扩展名	.ts
示例	use-auth.ts、use-pagination.ts

示例：

// hooks/use-auth.ts
export function useAuth() {
  // ...
}

---

styles — 全局样式

存放全局样式、变量、混入等。

规则	说明
文件命名	kebab-case
文件扩展名	.scss / .css
示例	variables.scss、reset.scss

---

命名规范速查表

类型	命名风格	示例
页面文件夹	kebab-case	user-login/
全局组件文件	PascalCase	AppFooter.vue
业务/页面组件文件	PascalCase	OrderCard.vue
静态资源	小写	logo.png
API / Store / Utils / Types / Hooks	kebab-case	user.ts、use-auth.ts
样式文件	kebab-case	variables.scss

---

导入路径约定

• 全局组件：从 @/components/ 引入
• 业务组件：从 @/business-cmp/ 或页面相对路径引入
• API：从 @/api/ 引入
• 类型：从 @/types/ 引入
• 工具：从 @/utils/ 引入
• Hooks：从 @/hooks/ 引入

---

注意事项

1. 禁止在 components/ 中放置与具体业务强耦合的组件。
2. 禁止在页面目录外散落页面专属组件。
3. 新增目录或调整规范前，需同步更新本文档。
4. 所有 TypeScript 类型定义统一放在 types/，避免在业务文件中重复定义相同类型。
5. 网络请求逻辑统一通过 api/ 层调用，页面与组件中不直接写请求 URL。