docs: final spec refinements per second review

- Fix type import syntax in mock example (Scenic[] → Scenic)
- Add pagination example to mock mechanism
- Clarify $uv-placeholder-color placement in uni.scss
- Separate $color-price vs $uv-error in migration table
- Split task 1.1 into 1.1a/1.1b/1.1c sub-tasks
- Add App.vue global style example
- Add SCSS import rules

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jacobxu666
2026-06-26 09:19:09 +08:00
co-authored by Claude
parent 6e27b449bb
commit 1b12c1a6b7
@@ -106,7 +106,7 @@
| `$uv-main-color` | `#111111` | 标题、重要正文 | | `$uv-main-color` | `#111111` | 标题、重要正文 |
| `$uv-content-color` | `#333333` | 正文 | | `$uv-content-color` | `#333333` | 正文 |
| `$uv-tips-color` | `#666666` | 次要说明 | | `$uv-tips-color` | `#666666` | 次要说明 |
| `$uv-placeholder-color` | `#999999` | 占位符(**新增**,uni.scss 缺失) | | `$uv-placeholder-color` | `#999999` | 占位符(**新增**,放在 `$uv-tips-color` 下方) |
| `$uv-disabled-color` | `#c8c9cc` | 不可操作文字 | | `$uv-disabled-color` | `#c8c9cc` | 不可操作文字 |
| `$uv-bg-color` | `#f3f4f6` | 页面背景 | | `$uv-bg-color` | `#f3f4f6` | 页面背景 |
| `$uv-bg-color-hover` | `#f1f1f1` | 按压态背景 | | `$uv-bg-color-hover` | `#f1f1f1` | 按压态背景 |
@@ -166,7 +166,8 @@ rgba(0, 0, 0, 0.12) — 重投影(弹窗)
| `#e5e7eb`, `#E2E8F0` | `$uv-border-color` | | `#e5e7eb`, `#E2E8F0` | `$uv-border-color` |
| `#f7f8fa`, `#f5f5f5`, `#f7f7f7`, `#FAFAFA`, `#F8FAFC` | `$uv-bg-color` | | `#f7f8fa`, `#f5f5f5`, `#f7f7f7`, `#FAFAFA`, `#F8FAFC` | `$uv-bg-color` |
| `#fff`, `#ffffff`, `#FFFFFF` | `$color-card` | | `#fff`, `#ffffff`, `#FFFFFF` | `$color-card` |
| `#e53935`, `#EF4444`, `#f53f3f`, `#E74C3C` | `$uv-error` 或 `$color-price` | | `#e53935`(价格场景) | `$color-price`(价格红,值 = `$uv-error`) |
| `#EF4444`, `#f53f3f`, `#E74C3C`(错误/状态场景) | `$uv-error` |
| `#3c9cff`, `#0052FF`, `#4A90D9`, `#4D7CFF` | `$uv-primary` | | `#3c9cff`, `#0052FF`, `#4A90D9`, `#4D7CFF` | `$uv-primary` |
| `#5ac725`, `#10B981`, `#00b42a` | `$uv-success` 或 `$color-status-success` | | `#5ac725`, `#10B981`, `#00b42a` | `$uv-success` 或 `$color-status-success` |
| `#f9ae3d`, `#F59E0B`, `#ff9500`, `#ff7d00` | `$uv-warning` 或 `$color-status-pending` | | `#f9ae3d`, `#F59E0B`, `#ff9500`, `#ff7d00` | `$uv-warning` 或 `$color-status-pending` |
@@ -434,12 +435,26 @@ export const USE_MOCK = import.meta.env.VITE_USE_MOCK === 'true'
// api/scenic.ts // api/scenic.ts
import { USE_MOCK } from '@/mock' import { USE_MOCK } from '@/mock'
import { mockScenicList } from '@/mock/scenic' import { mockScenicList } from '@/mock/scenic'
import type { Scenic[] } from './types' import type { Scenic } from './types'
export function getScenicList(): Promise<Scenic[]> { export function getScenicList(): Promise<Scenic[]> {
if (USE_MOCK) return Promise.resolve(mockScenicList) if (USE_MOCK) return Promise.resolve(mockScenicList)
return request.get('/mp-api/scenic/list') return request.get('/mp-api/scenic/list')
} }
// 分页示例
export function getScenicListPaged(query: PageQuery): Promise<PageResult<Scenic>> {
if (USE_MOCK) {
const start = (query.page - 1) * query.pageSize
return Promise.resolve({
list: mockScenicList.slice(start, start + query.pageSize),
total: mockScenicList.length,
page: query.page,
pageSize: query.pageSize,
})
}
return request.get('/mp-api/scenic/list', query)
}
``` ```
- `.env` 文件中 `VITE_USE_MOCK=true` 控制开关 - `.env` 文件中 `VITE_USE_MOCK=true` 控制开关
@@ -519,13 +534,35 @@ export const IMG_CARD_BANNER = 'https://...'
| 序号 | 任务 | 验证方式 | | 序号 | 任务 | 验证方式 |
|------|------|---------| |------|------|---------|
| 1.1 | 清理 `uni.scss`:补齐 `$font-size-xxs`、`$font-size-4xl`、`$uv-placeholder-color`、语义色、修改 `$font-family-body` 为系统字体 | 编译通过 | | 1.1a | `uni.scss` 新增缺失变量:`$font-size-xxs` (18rpx)、`$font-size-4xl` (64rpx)、`$uv-placeholder-color` (#999999) | 编译通过 |
| 1.1b | `uni.scss` 新增语义色变量:`$color-price`、`$color-price-highlight`、`$color-status-pending`、`$color-status-success`、`$color-status-cancel` | 编译通过 |
| 1.1c | `uni.scss` 修改 `$font-family-body` 为系统字体(去掉思源宋体前缀) | 编译通过 |
| 1.2 | 处理 `_tokens.scss`:冲突值改为引用 `uni.scss` 或删除 | 编译通过,无变量冲突 | | 1.2 | 处理 `_tokens.scss`:冲突值改为引用 `uni.scss` 或删除 | 编译通过,无变量冲突 |
| 1.3 | `api/types.ts` 补全所有业务 interface | `pnpm run type-check` 通过 | | 1.3 | `api/types.ts` 补全所有业务 interface(含 `PageResult<T>`、`PageQuery`) | `pnpm run type-check` 通过 |
| 1.4 | 创建 `src/mock/` 目录,迁移所有硬编码数据,实现 `USE_MOCK` 开关 | mock 数据可正常 import | | 1.4 | 创建 `src/mock/` 目录,迁移所有硬编码数据,实现 `USE_MOCK` 开关和 MockStore | mock 数据可正常 import |
| 1.5 | `App.vue` 全局字体声明统一为 `$font-family-body` | 构建预览正常 | | 1.5 | `App.vue` 全局样式重置(见下方示例) | 构建预览正常 |
| 1.6 | 删除 14 个页面中的局部 `$font`、`$primary`、`$text-main` 等变量声明 | 编译通过 | | 1.6 | 删除 14 个页面中的局部 `$font`、`$primary`、`$text-main` 等变量声明 | 编译通过 |
**1.5 App.vue 全局样式示例**:
```scss
// App.vue <style lang="scss">
page {
font-family: $font-family-body;
font-size: $font-size-base;
color: $uv-content-color;
background-color: $uv-bg-color;
line-height: $line-height-normal;
-webkit-font-smoothing: antialiased;
}
```
**SCSS 导入规则**:
- `uni.scss`:uni-app 自动注入,所有 `.vue` 文件的 `<style lang="scss">` 可直接使用变量,无需 `@import`
- `App.vue`:通过 `<style>` 设置全局 `page` 样式和默认字体
- 页面/组件中**不需要**再次 `@import uni.scss`
### 第2步:核心链路迁移(4 个页面) ### 第2步:核心链路迁移(4 个页面)
迁移页面:`首页 → 年卡列表 → 年卡详情 → 购买/订单` 迁移页面:`首页 → 年卡列表 → 年卡详情 → 购买/订单`