148 lines
6.6 KiB
Plaintext
148 lines
6.6 KiB
Plaintext
---
|
||
description: nl-admin uniapp（Vue3 + TS + Pinia + wot-design-uni）代码规范，含分包策略
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 基础规范（所有项目通用）
|
||
|
||
1. 写代码的时候要补充详细的中文注释（每个方法是干嘛的，为什么要这样写），如果是工作区，则所有项目都适用该规则
|
||
2. 注意不要生成太多的空行，上一部分代码和下一部分代码中间的空行不要大于 2 行
|
||
3. 有封装好的方法、组件需要复用，不要重复造轮子
|
||
4. 小程序端的抽屉全部需要用 `page-container` 来防止用户意外退出页面（必须用 `v-if`，禁止用 `v-show`）
|
||
5. 数据库的（created_at、updated_at、deleted_at）统一使用时间戳，不要使用字符串，并且我在查询器中一级格式化成字符串了，无需再次格式化
|
||
|
||
# 技术栈与强制复用
|
||
|
||
- 技术栈：`uni-app` + `Vue 3` + `TypeScript` + `Pinia` + **`wot-design-uni`**
|
||
- UI 优先使用 `wd-*` 组件（已配置按需自动引入），**不要引入 uview / uni-ui 重复造轮子**
|
||
- 状态管理用 Pinia，store 放 `src/stores/`，命名 `useXxxStore`
|
||
- 路径别名 `@` → `src/`
|
||
- 业务组件放 `src/components/`（PascalCase 文件名，如 `AppFooter.vue`）
|
||
- wot 组件细节可参考仓库内 `.cursor/skill/wot-ui-v2/`（以 `wot-design-uni` 实际 API 为准）
|
||
|
||
# 目录结构规范
|
||
|
||
```
|
||
src/
|
||
├── api/ # 按业务域拆分请求（如 api/user.ts）
|
||
├── components/ # 跨页面复用组件（主包可引用；分包专用组件优先放分包内）
|
||
├── pages/ # 主包页面（尽量精简）
|
||
├── pages-sub/ # 业务分包根目录（推荐；可按域再拆）
|
||
│ └── <package>/
|
||
│ ├── pages/ # 该分包页面
|
||
│ └── components/ # 仅该分包使用的组件（可选）
|
||
├── stores/ # Pinia
|
||
├── utils/ # 工具与请求封装（如 utils/request.ts）
|
||
├── static/ # 主包静态资源（大图/低频资源放分包 static）
|
||
├── pages.json
|
||
└── App.vue
|
||
```
|
||
|
||
- 页面文件：目录小写 + 页面同名或 `index.vue`（现有如 `pages/mine/mine.vue`）
|
||
- 新增业务模块时，**默认进分包**，不要往主包堆页面
|
||
|
||
# 分包规范（合理情况下尽量使用分包）
|
||
|
||
微信小程序主包体积有限，本项目约定：**能进分包的业务页就进分包**，主包只保留启动与高频入口。
|
||
|
||
## 主包只放这些
|
||
|
||
- TabBar 页面（如首页、我的）
|
||
- 登录 / 启动过渡 / 协议等冷启动必经页
|
||
- 全局强依赖且体积很小的公共组件与工具
|
||
|
||
## 必须进分包的场景
|
||
|
||
- 相对独立的业务域（订单、设置、详情、表单流程、活动页等）
|
||
- 非 Tab、非启动链路的列表/详情/编辑页
|
||
- 带较多图片、图表、富文本、第三方能力的页面
|
||
- 预计会持续扩页的模块（提前建分包，避免后期迁移）
|
||
|
||
## 可以留在主包的例外
|
||
|
||
- 体积很小、且被多个分包/Tab **同步高频**跳转的极少数页面
|
||
- 拆出去会导致首跳体验明显变差，又无法用 `preloadRule` 弥补时，可暂留主包（需在 PR/注释说明原因）
|
||
|
||
## pages.json 约定
|
||
|
||
```json
|
||
{
|
||
"pages": [
|
||
{ "path": "pages/index", "type": "home" },
|
||
{ "path": "pages/mine/mine" }
|
||
],
|
||
"subPackages": [
|
||
{
|
||
"root": "pages-sub/order",
|
||
"name": "order",
|
||
"pages": [
|
||
{ "path": "pages/list", "style": { "navigationBarTitleText": "订单列表" } },
|
||
{ "path": "pages/detail", "style": { "navigationBarTitleText": "订单详情" } }
|
||
]
|
||
}
|
||
],
|
||
"preloadRule": {
|
||
"pages/index": {
|
||
"network": "wifi",
|
||
"packages": ["order"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- `subPackages[].root` 用 `pages-sub/<域>`，`name` 用短英文域名单词
|
||
- 跳转路径写完整：`/pages-sub/order/pages/list`（注意前导 `/`）
|
||
- 同一业务域页面放同一分包；**禁止**把无关页面塞进同一个大分包「垃圾桶」
|
||
- 单个分包也要控制体积；过大时按子域再拆（如 `order` / `order-aftersale`）
|
||
- 需要加速首跳时配置 `preloadRule`（优先 wifi；不要无脑预下载全部包）
|
||
- 分包之间避免强耦合互相引用页面内私有组件；跨包复用下沉到主包 `src/components/` 或 `src/utils/`
|
||
- 新增页面时同步改 `pages.json`，未注册会无法打开
|
||
|
||
# 抽屉 / 弹层规范
|
||
|
||
- **抽屉类全屏/半屏面板**（筛选、详情抽屉、复杂表单层）：必须用微信 `page-container` + `v-if` 控制挂载，防止侧滑/返回直接退出页面
|
||
- 简单轻量反馈用 wot：`wd-popup` / `wd-toast` / `wd-message-box` 等；Toast/Dialog 按 wot 要求在页面内放置组件实例
|
||
- 禁止用 `v-show` 控制 `page-container` 显隐
|
||
|
||
```vue
|
||
<!-- 正确：抽屉用 page-container + v-if -->
|
||
<page-container v-if="drawerVisible" :show="drawerVisible" @afterleave="drawerVisible = false">
|
||
<!-- 抽屉内容 -->
|
||
</page-container>
|
||
```
|
||
|
||
# 请求与数据约定
|
||
|
||
- HTTP 统一走封装（建议 `src/utils/request.ts` + `src/api/<域>.ts`），**禁止**页面内直接 `uni.request`
|
||
- API 函数命名：`getXxxList` / `getXxxInfo` / `createXxx` / `updateXxx` / `deleteXxx`
|
||
- URL kebab-case，与后台自动路由风格对齐；GET 用 query，POST 用 body
|
||
- 接口字段保持后端 snake_case（如 `created_at`、`nick_name`），模板/入参不要擅自改成 camelCase
|
||
- 时间字段后端已格式化为字符串时，前端无需再次格式化
|
||
- Token / 登录态放 Pinia（或统一 storage 工具），在请求封装里集中注入与 401 处理
|
||
|
||
# 页面与组件写法
|
||
|
||
- 统一 `<script setup lang="ts">`
|
||
- 每个页面/组件 script 顶部用中文说明用途
|
||
- 有业务逻辑的函数必须写中文注释（做什么、为什么）
|
||
- 样式优先 `scoped`；尺寸用 rpx；颜色尽量走主题变量（`theme.json` / wot CSS 变量），避免散落魔法色值
|
||
- 列表分页、表单校验、空态/加载态要完整，不要只做「能点开」的半成品
|
||
|
||
# 命名规范
|
||
|
||
| 维度 | 规范 | 示例 |
|
||
|---|---|---|
|
||
| 页面目录/文件 | 小写或 kebab | `pages-sub/order/pages/list.vue` |
|
||
| 组件文件 | PascalCase | `OrderCard.vue` |
|
||
| Store | `useXxxStore` | `useUserStore` |
|
||
| API 函数 | camelCase | `getOrderList` |
|
||
| 常量 | UPPER_SNAKE_CASE | `ORDER_STATUS_OPTIONS` |
|
||
|
||
# 禁止事项
|
||
|
||
- 禁止把大量业务页塞进主包 `src/pages/`
|
||
- 禁止引入第二套 UI 库（uview 等）与 `wot-design-uni` 混用
|
||
- 禁止在业务页复制粘贴请求头、baseURL、token 逻辑
|
||
- 禁止抽屉不用 `page-container`、或用 `v-show` 控制抽屉
|
||
- 禁止提交无中文注释的复杂业务逻辑
|