feat:登录页面
This commit is contained in:
李伊帆
262
docs/src-directory-convention.md
Normal file
262
docs/src-directory-convention.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user