From 4c1ed161ea64ee34231d27f1ef727adcb4ac2dd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E7=90=A6?= Date: Mon, 10 Aug 2026 12:39:42 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/rules/Code-Standards.mdc | 147 +++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 .cursor/rules/Code-Standards.mdc diff --git a/.cursor/rules/Code-Standards.mdc b/.cursor/rules/Code-Standards.mdc new file mode 100644 index 0000000..673a218 --- /dev/null +++ b/.cursor/rules/Code-Standards.mdc @@ -0,0 +1,147 @@ +--- +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/ # 业务分包根目录（推荐；可按域再拆） +│ └── / +│ ├── 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 + + + + +``` + +# 请求与数据约定 + +- 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 处理 + +# 页面与组件写法 + +- 统一 `