# 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` |

**示例：**

```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` |

**示例：**

```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` |

**示例：**

```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` |

**示例：**

```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。