Cursor rule

1---
2description: uni-app 聚鑫助手（@apps/uni）页面、API、样式与 wot-ui
3globs: apps/uni/**/*
4alwaysApply: false
5---
6 
7# Uni（uni-app + Vue 3 + Vite）
8 
9## 栈与别名
10 
11- **uni-app** + **Vue 3** + **TypeScript** + **Vite** + **UnoCSS** + **wot-ui**（`wd-*`）+ **Pinia**。
12- 路径别名：`@/` → `src/`。
13- 配置：`vite.config.ts`、`pages.config.ts`、`manifest.config.ts`、`uno.config.ts`；环境变量在 `env/`。
14 
15## 开发命令（monorepo 根目录）
16 
17| 场景 | 命令 |
18|------|------|
19| H5 | `pnpm dev:uni` |
20| 微信小程序 | `pnpm dev:uni:mp` |
21| 构建 H5 / 小程序 | `pnpm build:uni:h5` / `pnpm build:uni:mp` |
22| Lint / 类型 | `pnpm --filter @apps/uni lint` / `type-check` |
23 
24## 目录
25 
26- `src/pages/` — 主包页面；`src/pages-sub/` — 分包
27- `src/components/`、`src/layouts/`、`src/tabbar/`
28- `src/api/`、`src/http/`、`src/store/`
29- `src/App.ku.vue` — 全局根组件
30 
31## 生成文件（勿手改提交）
32 
33- `src/pages.json`、`src/manifest.json` 由 `scripts/create-base-files.js` + uni-pages 插件生成（见 `.gitignore`）。
34- 改路由/页面配置：编辑页面内 **`definePage`** 或 `pages.config.ts`，不要直接改 `pages.json`。
35 
36## 路由与拦截
37 
38- 路由拦截（登录/白名单）：`src/router/interceptor.ts`。
39- HTTP 拦截（token、错误）：`src/http/interceptor.ts`。
40- Tabbar 配置：`src/tabbar/config.ts`。
41 
42## Vue / TypeScript
43 
44- **Composition API** + `<script setup lang="ts">`；SFC 顺序：script → template → style（可选）。
45- 避免 `any`；类型用 `import type`；Pinia store 在 `src/store/`。
46- 页面用宏 **`definePage`**（写在 script 最上方）。
47- 平台差异用条件编译（`#ifdef H5` / `#ifdef MP-WEIXIN`）；API 用 `uni.xxx`。
48- 页面生命周期：`onLoad`、`onShow`、`onReady`、`onHide`、`onUnload`。
49 
50## API / HTTP
51 
52- 封装：`src/http/http.ts`（简单 http）、`alova.ts`、`vue-query.ts`。
53- 接口：`src/api/**`，类型 `src/api/types/`。
54- **后端现状**：API 仍指向 **laf.run**（`env/.env` 的 `VITE_SERVER_BASEURL`），**未对接 @apps/server**；迁移为独立任务。
55 
56## 日期与工具复用
57 
58- 日期解析、月份推导、展示格式化统一用 **day.js**；不要在业务代码里重复写原生 `Date` 计算逻辑。
59- 优先复用已有工具（如 `src/utils/formatTime.ts`、`src/utils/payPeriod.ts`），不要在页面内再写同类 `formatTime`/月份计算函数。
60- 仅在非日历语义场景（性能计时、随机后缀、请求去重时间戳）可保留 `Date.now()`。
61 
62## 样式
63 
64- 优先 **UnoCSS** 原子类；需自定义时用 `lang="scss"` + `scoped`，全局样式 `src/style/`。
65- 750 设计稿：**N px → 2N rpx**（如 24px → `px-48rpx`），勿写 `px-24px`。
66- **语义色禁止硬编码**：成功/警告/危险/主色须用 wot-ui CSS 变量（或 Uno 别名），勿写 Ant Design / 随意 hex。
67 
68| 用途 | CSS 变量 | Uno 原子类 |
69|------|----------|------------|
70| 主色 | `var(--wot-primary-6)` | `text-primary` / `bg-primary` |
71| 成功文字 | `var(--wot-success-main)` | `text-success` |
72| 成功浅底 / 浅边 | `--wot-success-surface` / `-particular` | — |
73| 警告文字 | `var(--wot-warning-main)` | `text-warning` |
74| 警告浅底 / 浅边 | `--wot-warning-surface` / `-particular` | — |
75| 危险（删除等） | `var(--wot-danger-main)` | `text-danger` / `bg-danger` |
76 
77主色阶 `--wot-primary-1..10` 在 `src/style/index.scss` 覆盖；勿使用已废弃的 `--wot-color-theme`。组件 `type="success|warning|danger|primary"` 已走主题，业务自定义样式也应对齐上表。
78 
79## wot-ui（必须遵守）
80 
81easycom 已配置，**无需 import**。能用 wot-ui 必须用，禁止原生标签重复造轮子。
82 
83| 场景 | ❌ | ✅ |
84|------|----|----|
85| 按钮 | `<button>` | `wd-button` |
86| 表单 | cell 手写 | `wd-form` + `wd-form-item` |
87| 输入 | `<input>` | `wd-input` |
88| 列表 | 手写 flex | `wd-cell` + `wd-cell-group` |
89| 弹层 | 手写遮罩 | `wd-popup` |
90| 空态 | 手写文案 | `wd-empty` |
91| 选择 | 原生 picker | `wd-picker` / `wd-select-picker` |
92 
93例外：`view`、`scroll-view`、`canvas`、`image` 等布局/平台能力；wot-ui 无对应能力的原生 API。
94 
95- 复杂表单标准写法：`wd-form` 绑 `:model` + `:schema`，提交前 **`formRef.validate()`**。
96- 外观优先 props（`type`、`size`、`variant`）；布局用 UnoCSS；微调用 `custom-class`。
97 
98参考：`src/pages-sub/wifi/generate.vue`、`src/pages/salary/calc.vue`、`src/pages/salary/history.vue`。
99 
100## 注释约定
101 
102遵循全仓 **`comment-standards.mdc`**。Uni 侧额外强调：
103 
104- **`src/composables/`**：跨页面复用的 Composable 文件头写 JSDoc（流程、依赖的 store/API、副作用）；导出函数说明入参含义与平台限制。
105- **`src/store/`**：action 注释业务意图（如「写入本地历史，最多保留 50 条」），state 字段含义不显而易见的加行内注释。
106- **`src/utils/`**（如 `salaryCalculator.ts`、`salarySlipFieldMap.ts`）：税率/基数/字段映射等**计算与映射规则**用块注释列出，勿只写变量名。
107- **平台差异**（`#ifdef H5` / `#ifdef MP-WEIXIN`）：必须注释**为何分平台**（API 差异、权限、包体积、已知 bug），避免后人合并分支时误删。
108- **表单与校验**（`wd-form` + `schema`）：非标准校验规则、与后端字段不一致的转换逻辑，注释业务原因。
109- **页面 `.vue`**：复杂页面（如 `verify.vue`）在 `script` 顶部用简短块注释说明页面职责与主流程；模板里不写注释，逻辑放 script。
110- **勿注释**：wot-ui 常规用法、UnoCSS 类名含义、`definePage` 路由元数据等自解释代码。
111