# 🚀 快速开始指南 - 使用新规范开发

## 📖 目录

1. [快速创建新页面](#快速创建新页面)
2. [遵循编码规范](#遵循编码规范)
3. [常见问题](#常见问题)
4. [参考资料](#参考资料)

## 快速创建新页面

### 方法 1: 使用模板 (推荐) ⭐

#### 步骤 1: 复制模板

从 `pages/mall/admin/_TEMPLATE_simple-page.uvue` 复制

#### 步骤 2: 创建新文件

```bash
pages/mall/admin/your-new-page.uvue
```

#### 步骤 3: 修改模板值

```uvue
<script setup lang="uts">
// 改这三个值
const currentPage = ref<string>('your-page-id')    // 修改此处
const title = ref<string>('你的页面标题')          // 修改此处
const subtitle = ref<string>('你的副标题')        // 修改此处
const params = ref<string>('')

onLoad((options: Record<string, string | undefined>) => {
  params.value = JSON.stringify(options ?? {})
})
</script>
```

#### 步骤 4: 添加页面内容

在 `<view class="card">` 中添加你的内容

#### 完成！✅

### 方法 2: 手动创建

如果需要复杂的页面结构，遵循以下规范:

#### 1. 模板结构

```uvue
<template>
  <AdminLayout :currentPage="currentPage">
    <view class="page">
      <!-- 页面标题 -->
      <view class="header">
        <text class="title">{{ title }}</text>
        <text class="sub-title">{{ subtitle }}</text>
      </view>

      <!-- 页面内容 -->
      <view class="card">
        <!-- 你的内容 -->
      </view>
    </view>
  </AdminLayout>
</template>
```

#### 2. 脚本编写

```uts
<script setup lang="uts">
import { ref } from 'vue'
import { onLoad } from '@dcloudio/uni-app'
import AdminLayout from '@/layouts/admin/AdminLayout.uvue'

// 声明页面状态（都要有类型）
const currentPage = ref<string>('page-id')
const title = ref<string>('页面标题')
const subtitle = ref<string>('副标题')

// 处理路由参数
onLoad((options: Record<string, string | undefined>) => {
  // options 中可以获取路由参数
})

// 事件处理
const handleAction = (id: string) => {
  // 处理点击事件
}
</script>
```

#### 3. 样式编写

```scss
<style scoped lang="scss">
// 使用设计变量，不要硬编码！
.page {
  padding: $space-lg;  // 不要写 padding: 24rpx;
}

.header {
  padding: $space-lg;
  border-radius: $radius;
  background: $background-primary;  // 不要写 background: #ffffff;
  box-shadow: $shadow-xs;
}

.title {
  font-size: $font-size-lg;         // 不要写 font-size: 36rpx;
  font-weight: $font-weight-bold;
  color: $text-primary;             // 不要写 color: #000;
}

.card {
  margin-top: $space-lg;
  padding: $space-lg;
  background: $background-primary;
  border-radius: $radius;
}
</style>
```

## 遵循编码规范

### ✅ 必须做的事

#### 1. 类型注解 (Type Annotations)

```uts
// ✅ 好的
const title = ref<string>('标题')
const count = ref<number>(0)
const items = ref<Array<Item>>([])
const config = ref<Record<string, any>>({})

// ❌ 不好 - 没有类型
const title = ref('标题')
const count = ref(0)
```

#### 2. CSS 命名规范 (Naming Convention)

```scss
// ✅ 好的 - kebab-case
.page-header {
}
.user-list {
}
.action-button {
}
.form-field {
}

// ❌ 不好 - PascalCase
.PageHeader {
}
.UserList {
}
.ActionButton {
}
.FormField {
}
```

#### 3. 设计变量 (Design Variables)

```scss
// ✅ 好的 - 使用变量
.header {
  padding: $space-lg;
  background: $background-primary;
  color: $text-primary;
  font-size: $font-size-lg;
}

// ❌ 不好 - 硬编码
.header {
  padding: 24rpx;
  background: #ffffff;
  color: #000000;
  font-size: 36rpx;
}
```

### ❌ 不要做的事

#### 1. 不要使用硬编码颜色

```uts
// ❌ 错误
background: #ffffff
color: #333333
border-color: #dddddd

// ✅ 正确
background: $background-primary
color: $text-primary
border-color: $border-default
```

#### 2. 不要硬编码间距

```uts
// ❌ 错误
margin-top: 20rpx
padding: 30rpx

// ✅ 正确
margin-top: $space-md
padding: $space-lg
```

#### 3. 不要混合命名规范

```uts
// ❌ 错误 - 混合 kebab-case 和 camelCase
.page-header { }
.PageContent { }
.footer-bar { }

// ✅ 正确 - 统一 kebab-case
.page-header { }
.page-content { }
.footer-bar { }
```

## 常见问题

### Q: 我该在哪里声明 ref?

A: 在 `<script setup>` 中，在组件逻辑之前声明：

```uts
const title = ref<string>('标题')      // ✅
const count = ref<number>(0)            // ✅
// ... 其他逻辑
```

### Q: 如何添加多个卡片？

A: 为每个卡片创建一个 `.card` div：

```uvue
<view class="card">
  <text class="label">卡片 1</text>
  <!-- 内容 -->
</view>

<view class="card">
  <text class="label">卡片 2</text>
  <!-- 内容 -->
</view>
```

### Q: 我可以修改 $space-lg 的值吗?

A: 可以，在 `uni.scss` 中修改，所有页面会自动更新：

```scss
// 在 uni.scss 中
$space-lg: 32rpx; // 所有使用 $space-lg 的页面都会变化
```

### Q: 我该如何处理条件样式?

A: 使用 Vue 的动态绑定：

```uvue
<view :class="{ 'is-active': isActive }">
  内容
</view>

<style scoped lang="scss">
.is-active {
  background: $primary;
  color: #ffffff;
}
</style>
```

### Q: 如何定义自定义颜色变量?

A: 在 `uni.scss` 中添加新变量：

```scss
// 在 uni.scss 中
$my-brand-color: #ff5722;
$my-light-bg: #fff3e0;

// 然后在页面中使用
.brand-header {
  background: $my-brand-color;
}
```

### Q: 我可以使用内联样式吗?

A: 不推荐，使用 CSS 类更好：

```uvue
<!-- ❌ 不推荐 -->
<view style="padding: 20rpx; background: #fff;">

<!-- ✅ 推荐 -->
<view class="my-card">

<style scoped lang="scss">
.my-card {
  padding: $space-md;
  background: $background-primary;
}
</style>
```

## 参考资料

### 核心设计变量

#### 颜色系统

```scss
$primary: #1677ff; // 主色
$success: #52c41a; // 成功
$warning: #faad14; // 警告
$danger: #ff4d4f; // 危险

$background-primary: #ffffff; // 主背景
$background-secondary: #fafafa; // 次要背景
$text-primary: #000000; // 主文本
$text-secondary: #666666; // 次要文本
$text-tertiary: #999999; // 弱化文本
```

#### 间距系统 (8px 基准)

```scss
$space-xs: 8rpx; // 最小间距
$space-md: 16rpx; // 中等间距
$space-lg: 24rpx; // 大间距
$space-xl: 32rpx; // 超大间距
```

#### 字体系统

```scss
$font-size-sm: 24rpx; // 小字体
$font-size-md: 26rpx; // 正常字体
$font-size-lg: 36rpx; // 大字体

$font-weight-normal: 400;
$font-weight-semibold: 600;
$font-weight-bold: 700;
```

#### 其他常用变量

```scss
$radius: 16rpx; // 圆角半径
$shadow-xs: 0 2px 8px rgba(0, 0, 0, 0.06);
$line-height: 1.5; // 行高
```

### 已改版页面参考

所有这些页面都遵循新规范，可以作为参考：

**P0 主页面:**

- user-management.uvue
- product-management.uvue
- order-management.uvue
- system-settings.uvue
- marketing-management.uvue

**P1 维护页面:** (maintain 文件夹中的所有文件)

- maintain/data/\*.uvue
- maintain/dev-config/\*.uvue
- maintain/dev-tools/\*.uvue
- maintain/security/\*.uvue
- maintain/i18n/\*.uvue

**P2 产品页面:**

- product-specifications.uvue
- product-classification.uvue
- product-parameters.uvue
- 等等...

### 查看完整文档

- [ADMIN_REFACTOR_PROGRESS.md](./ADMIN_REFACTOR_PROGRESS.md) - 详细的重构列表
- [REFACTOR_SUMMARY.md](./REFACTOR_SUMMARY.md) - 重构总结
- [REFACTOR_BEFORE_AFTER.md](./REFACTOR_BEFORE_AFTER.md) - 改进对比

## 💡 最佳实践清单

在开始开发前，检查以下项目:

- [ ] 使用了 `ref<Type>()` 声明所有状态
- [ ] 所有 CSS 类名都是 kebab-case
- [ ] 没有硬编码的颜色值
- [ ] 没有硬编码的间距值
- [ ] 添加了 `lang="scss"` 到 style 标签
- [ ] 添加了 `lang="uts"` 到 script 标签
- [ ] 函数参数都有类型定义
- [ ] 使用了 AdminLayout 布局
- [ ] 遵循了 page/header/card 的结构

## 🎉 开始编码吧!

现在你已经准备好使用新规范开发了！

记住：

1. 使用模板作为起点
2. 遵循编码规范
3. 参考已改版的页面
4. 有问题查看文档

祝你编码愉快！🚀