---
description: 页面开发规范 - 页面组件结构、数据编排、路由容器。
globs: ["**/pages/*.vue", "**/pages/*/index.vue", "**/views/*.vue", "**/views/*/index.vue", "**/page/*.vue", "**/page/*/index.vue"]
alwaysApply: false
---

# 页面开发规范

该规则用于页面开发：

**当创建新页面时：**

- 页面职责：**路由容器 + 数据编排**
- 页面专用组件放 `pages/{page}/components/`
- 页面只做数据编排，不包含复杂业务逻辑

**当页面逻辑复杂时：**

- 逻辑超过 100 行 → 提取到 Hook
- 禁止超过 200 行逻辑代码

**当管理页面状态时：**

- 临时状态 → 页面 `ref`
- 页面共享 → Hook 或页面级 Store
- 全局共享 → 全局 Store

---

## 📁 文件组织

**方案 A：扁平式**

```
{page目录}/
├── user-list.vue
└── user-detail.vue
```

**方案 B：目录式**（推荐）

```
{page目录}/user/
├── index.vue         # 页面入口
├── components/       # 页面专用组件
│   ├── UserFilter.vue
│   └── UserTable.vue
└── store/            # 页面级 Store（可选）
```

> 📋 具体存放路径详见 @foundation/project.mdc

---

## 🎨 设计策略

### 1. 页面 vs 组件职责

| 类型 | 职责               | 关注点                  | 示例               |
| ---- | ------------------ | ----------------------- | ------------------ |
| 页面 | 数据编排、路由容器 | 调用 API、组合组件      | `UserListPage.vue` |
| 组件 | UI 渲染、交互逻辑  | 接收 Props、触发 Events | `UserTable.vue`    |

```vue
<!-- 页面：编排数据，组合组件 -->
<template>
  <div class="user-page">
    <UserFilter @filter="handleFilter" />
    <UserTable :data="users" :loading="loading" />
    <Pagination :total="total" @change="handlePageChange" />
  </div>
</template>

<script setup lang="ts">
import { useUserList } from "@/hooks/useUserList";

const { users, total, loading, fetchUsers, handleFilter } = useUserList();
fetchUsers();
</script>
```

### 2. 页面分层

| 类型   | 特点                   | 示例                    |
| ------ | ---------------------- | ----------------------- |
| 布局页 | 仅做插槽嵌套，无业务   | `LayoutWithSidebar.vue` |
| 容器页 | 路由嵌套，组合子页面   | `UserContainer.vue`     |
| 业务页 | 具体业务逻辑，调用 API | `UserList.vue`          |

### 3. 数据获取

| 时机       | 适用场景             | 实现方式                      |
| ---------- | -------------------- | ----------------------------- |
| 路由进入前 | 数据必须存在才能渲染 | `beforeRouteEnter` / 路由守卫 |
| 页面挂载后 | 可先展示骨架屏       | `onMounted`                   |
| 用户交互时 | 按需加载             | 事件触发                      |

```typescript
// 路由进入前
beforeEnter: async (to) => {
  await userStore.fetchUser(to.params.id);
};

// 页面挂载后
onMounted(async () => {
  loading.value = true;
  await fetchUsers();
  loading.value = false;
});
```

### 4. 页面状态

| 状态类型   | 存放位置     | 示例               |
| ---------- | ------------ | ------------------ |
| 临时状态   | 页面 `ref`   | 表单输入、筛选条件 |
| 页面级共享 | 页面级 Store | 跨子组件的列表数据 |
| 全局共享   | 全局 Store   | 用户信息、权限     |

---

## ✅ 检查清单

### 职责

- ✅ 页面只做数据编排，不包含复杂业务逻辑
- ✅ 页面逻辑超过 100 行必须提取到 Hook
- ❌ 禁止页面包含超过 200 行的逻辑代码
- ❌ 禁止在页面中直接写大段 API 调用逻辑

### 组织

- ✅ 页面专用组件必须放在页面 `components/` 子目录
- ❌ 禁止页面组件被其他页面 import
- ❌ 禁止页面专用组件与公共组件混放

> 📋 组件规范详见 @modules/components.mdc
> 📋 Hooks 规范详见 @modules/hooks.mdc