# 学业邑规划 - 组件文档

本文档定义了小程序中需要开发的公共组件和业务组件。

---

## 一、组件分类

```
components/
├── common/             # 通用组件（与业务无关）
├── business/           # 业务组件（与业务相关）
└── layout/             # 布局组件
```

---

## 二、通用组件

### 2.1 AppButton 按钮

**文件**：`components/common/AppButton.vue`

**功能**：统一的按钮组件，支持多种样式和状态

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| type | string | 'primary' | 按钮类型：primary / secondary / text |
| size | string | 'medium' | 按钮大小：small / medium / large |
| disabled | boolean | false | 是否禁用 |
| loading | boolean | false | 是否加载中 |
| block | boolean | false | 是否块级按钮 |

**使用示例**：
```vue
<AppButton type="primary" @click="handleSubmit">提交</AppButton>
<AppButton type="secondary" size="small">取消</AppButton>
<AppButton :disabled="!isValid" :loading="submitting">
  支付￥99元 开始测评
</AppButton>
```

---

### 2.2 AppModal 弹窗

**文件**：`components/common/AppModal.vue`

**功能**：统一的弹窗组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| visible | boolean | false | 是否显示 |
| title | string | '' | 标题 |
| showClose | boolean | true | 是否显示关闭按钮 |
| maskClosable | boolean | true | 点击遮罩是否关闭 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| update:visible | boolean | 显示状态变化 |
| close | - | 关闭事件 |

**使用示例**：
```vue
<AppModal v-model:visible="showModal" title="提示">
  <text>确定要退出登录吗？</text>
  <template #footer>
    <AppButton type="secondary" @click="showModal = false">取消</AppButton>
    <AppButton type="primary" @click="handleConfirm">确定</AppButton>
  </template>
</AppModal>
```

---

### 2.3 AppEmpty 空状态

**文件**：`components/common/AppEmpty.vue`

**功能**：列表为空时的占位组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| image | string | 默认图片 | 空状态图片 |
| text | string | '暂无数据' | 提示文字 |
| showButton | boolean | false | 是否显示按钮 |
| buttonText | string | '' | 按钮文字 |

**使用示例**：
```vue
<AppEmpty text="暂无订单" />
<AppEmpty 
  text="暂无测评记录" 
  :showButton="true" 
  buttonText="去测评" 
  @click="goAssessment" 
/>
```

---

### 2.4 AppLoading 加载

**文件**：`components/common/AppLoading.vue`

**功能**：加载状态组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| loading | boolean | false | 是否加载中 |
| text | string | '加载中...' | 加载文字 |
| fullscreen | boolean | false | 是否全屏 |

**使用示例**：
```vue
<AppLoading :loading="isLoading" />
<AppLoading :loading="isLoading" text="报告生成中..." :fullscreen="true" />
```

---

### 2.5 AppNavbar 导航栏

**文件**：`components/common/AppNavbar.vue`

**功能**：自定义导航栏（用于 navigationStyle: custom 的页面）

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| title | string | '' | 标题 |
| showBack | boolean | true | 是否显示返回按钮 |
| showHome | boolean | false | 是否显示首页按钮 |
| bgColor | string | '#fff' | 背景色 |
| textColor | string | '#333' | 文字颜色 |

**使用示例**：
```vue
<AppNavbar title="测评结果" :showBack="true" />
<AppNavbar title="首页" :showBack="false" bgColor="transparent" textColor="#fff" />
```

---

### 2.6 AppInput 输入框

**文件**：`components/common/AppInput.vue`

**功能**：统一的输入框组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| modelValue | string | '' | 输入值 |
| type | string | 'text' | 输入类型 |
| placeholder | string | '' | 占位文字 |
| disabled | boolean | false | 是否禁用 |
| maxlength | number | -1 | 最大长度 |
| error | string | '' | 错误提示 |

**使用示例**：
```vue
<AppInput 
  v-model="form.name" 
  placeholder="请输入姓名" 
  :error="errors.name" 
/>
```

---

### 2.7 AppPicker 选择器

**文件**：`components/common/AppPicker.vue`

**功能**：统一的选择器组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| modelValue | any | null | 选中值 |
| options | array | [] | 选项列表 |
| placeholder | string | '请选择' | 占位文字 |
| labelKey | string | 'label' | 显示字段 |
| valueKey | string | 'value' | 值字段 |

**使用示例**：
```vue
<AppPicker 
  v-model="form.age" 
  :options="ageOptions" 
  placeholder="请选择年龄" 
/>
```

---

### 2.8 AppRegionPicker 地区选择器

**文件**：`components/common/AppRegionPicker.vue`

**功能**：省市区三级联动选择器

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| province | string | '' | 省份 |
| city | string | '' | 城市 |
| district | string | '' | 区县 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| change | { province, city, district } | 选择变化 |

**使用示例**：
```vue
<AppRegionPicker 
  :province="form.province"
  :city="form.city"
  :district="form.district"
  @change="handleRegionChange"
/>
```

---

## 三、业务组件

### 3.1 UserAvatar 用户头像

**文件**：`components/business/UserAvatar.vue`

**功能**：用户头像展示组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| src | string | '' | 头像地址 |
| size | string | 'medium' | 大小：small / medium / large |
| showLevel | boolean | false | 是否显示等级标识 |
| level | number | 1 | 用户等级 |

**使用示例**：
```vue
<UserAvatar :src="userInfo.avatar" size="large" />
<UserAvatar :src="userInfo.avatar" :showLevel="true" :level="userInfo.userLevel" />
```

---

### 3.2 OrderCard 订单卡片

**文件**：`components/business/OrderCard.vue`

**功能**：订单列表项组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| order | OrderItem | required | 订单数据 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| action | { type, order } | 操作按钮点击 |

**使用示例**：
```vue
<OrderCard 
  v-for="order in orderList" 
  :key="order.id" 
  :order="order" 
  @action="handleOrderAction" 
/>
```

---

### 3.3 AssessmentCard 测评入口卡片

**文件**：`components/business/AssessmentCard.vue`

**功能**：首页测评入口组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| assessment | AssessmentType | required | 测评类型数据 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| click | AssessmentType | 点击事件 |

**使用示例**：
```vue
<AssessmentCard 
  v-for="item in assessmentList" 
  :key="item.id" 
  :assessment="item" 
  @click="handleAssessmentClick" 
/>
```

---

### 3.4 PlannerCard 规划师卡片

**文件**：`components/business/PlannerCard.vue`

**功能**：规划师列表项组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| planner | PlannerInfo | required | 规划师数据 |
| selected | boolean | false | 是否选中 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| select | PlannerInfo | 选择事件 |

**使用示例**：
```vue
<PlannerCard 
  v-for="planner in plannerList" 
  :key="planner.id" 
  :planner="planner" 
  :selected="selectedId === planner.id"
  @select="handleSelect" 
/>
```

---

### 3.5 QuestionItem 题目组件

**文件**：`components/business/QuestionItem.vue`

**功能**：测评答题页的题目组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| question | Question | required | 题目数据 |
| answer | number | null | 当前答案 |
| index | number | required | 题目序号 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| change | { questionId, value } | 答案变化 |

**使用示例**：
```vue
<QuestionItem 
  v-for="(question, index) in questionList" 
  :key="question.id" 
  :question="question" 
  :answer="answers[question.id]"
  :index="index"
  @change="handleAnswerChange" 
/>
```

---

### 3.6 InviteRecord 邀请记录项

**文件**：`components/business/InviteRecord.vue`

**功能**：邀请记录列表项组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| record | InviteRecord | required | 邀请记录数据 |

**使用示例**：
```vue
<InviteRecord 
  v-for="record in recordList" 
  :key="record.id" 
  :record="record" 
/>
```

---

### 3.7 WithdrawRecord 提现记录项

**文件**：`components/business/WithdrawRecord.vue`

**功能**：提现记录列表项组件

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| record | WithdrawRecord | required | 提现记录数据 |

**使用示例**：
```vue
<WithdrawRecord 
  v-for="record in withdrawList" 
  :key="record.id" 
  :record="record" 
/>
```

---

## 四、布局组件

### 4.1 PageContainer 页面容器

**文件**：`components/layout/PageContainer.vue`

**功能**：统一的页面容器，处理安全区域

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| safeBottom | boolean | true | 是否适配底部安全区域 |
| bgColor | string | '#f5f5f5' | 背景色 |

**使用示例**：
```vue
<PageContainer>
  <!-- 页面内容 -->
</PageContainer>
```

---

### 4.2 ListContainer 列表容器

**文件**：`components/layout/ListContainer.vue`

**功能**：带下拉刷新和上拉加载的列表容器

**Props**：
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| loading | boolean | false | 是否加载中 |
| finished | boolean | false | 是否加载完成 |
| emptyText | string | '暂无数据' | 空状态文字 |

**Emits**：
| 事件 | 参数 | 说明 |
|------|------|------|
| refresh | - | 下拉刷新 |
| loadMore | - | 上拉加载 |

**使用示例**：
```vue
<ListContainer 
  :loading="loading" 
  :finished="finished"
  @refresh="handleRefresh"
  @loadMore="handleLoadMore"
>
  <OrderCard v-for="order in orderList" :key="order.id" :order="order" />
</ListContainer>
```

---

## 五、组件开发规范

### 5.1 组件命名

- 通用组件以 `App` 开头：`AppButton`, `AppModal`
- 业务组件使用业务名词：`UserAvatar`, `OrderCard`
- 布局组件以 `Container` 结尾：`PageContainer`, `ListContainer`

### 5.2 Props 规范

- 使用 TypeScript 接口定义
- 必填属性标注 `required`
- 提供合理的默认值
- 添加 JSDoc 注释

### 5.3 样式规范

- 使用 BEM 命名
- 使用 `scoped` 限制作用域
- 引用全局变量
- 避免使用 `!important`

### 5.4 事件规范

- 使用 `emit` 定义类型
- 事件名使用 kebab-case
- 提供完整的事件参数类型