zkxw/.cursorrules

# zkxw 工程 Cursor 规则

本仓库含 Web 管理端（`web-admin`）、小程序端（`miniprogram`）等子工程。实现或修改 UI 时，**以文档为权威来源**，本文件仅作快速索引与强约束摘要。

## 权威文档（必读路径）

- **Web 管理端（Fresh Mint）**：`docs/web-admin-ui-spec-fresh-mint.md` 
  适用范围：`web-admin`（Vue 3 + Element Plus + SCSS/Tailwind）。色值、布局、列表、弹窗、树形路径等均以该文档及其中引用的 `fresh-mint-green.html` 为准。
- **界面模式索引（选型 + 参考页）**：`docs/web-admin-ui-pattern-index.md`  
  新功能开发前按「功能特征 → 模式编号 P01–P27 → Hash/源码」选型；与 Demo 模板页、业务参考页对照。
- **小程序端（三墙 Demo 体系）**：`docs/miniprogram-ui-spec-sanqiang.md`  
  适用范围：`miniprogram`（客户端 / 供应商端 / 配送员端）。视觉以该文档及 `mobile-ui/sanqiang-*.html` 为准。

修改对应子工程前，若涉及界面，应先检索上述文档中的章节（类名、Token、结构顺序）。

## OpenSpec 工程规范

详见 **Cursor 项目规则**：`.cursor/rules/openspec-zkxw-standards.mdc`（`alwaysApply: true`，与 Cursor 2.x 推荐方式一致）。根目录本文件保留 UI 与工程摘要；OpenSpec 路径与 SHALL 门禁以该 `.mdc` 为准。

---

## Web 管理端（`web-admin`）摘要

**列表主标题竖条、新增/编辑弹窗两列～五列、`dialog-form-layout` 限高与正文滚动** 等实现约定：见 Cursor 规则 **`.cursor/rules/web-admin-crud-dialog.mdc`**（编辑 `web-admin` 下 `.vue` / `.scss` 时由 Cursor 按 glob 自动附加该规则）。

### 技术栈与实现方式

- Vue 3 + Element Plus；主题与皮肤通过 **CSS 变量 + Element 主题变量 + 全局覆盖** 对齐规范，**勿随意改 Token 色值**。
- 树形主数据全路径：`web-admin/src/utils/tree-path.ts`（如 `buildTreePathLabelFromFlat`、`buildPathLabelMapFromTreeRoots`、`resolveTreePathDisplay`）。路径分隔符统一为 **` / `**（半角斜杠两侧各一空格）。

### 页面级 UI 模板（固定五页 + 工作台入口）

上述页面均挂在侧栏 **「Demo」** 菜单下。新开发的列表/表单页**对照以下页面实现**，勿另起一套布局与类名习惯；仍须同时遵守 `docs/web-admin-ui-spec-fresh-mint.md`。

| 用途 | Hash 路由 | 源码 |
|------|-----------|------|
| 工作台（入口与说明） | `/#/demo/console` | `web-admin/src/views/dashboard/console/index.vue` |
| 标准列表（筛选、工具栏、表格、分页） | `/#/demo/unit` | `web-admin/src/views/system/unit/index.vue` |
| 复杂业务列表（状态、操作列等） | `/#/demo/order` | `web-admin/src/views/system/order/index.vue` |
| 商品类列表与查看弹窗联动 | `/#/demo/product` | `web-admin/src/views/system/product/index.vue` |
| 树形主数据 | `/#/demo/category` | `web-admin/src/views/system/category/index.vue` |
| 系统用户类 CRUD | `/#/demo/user` | `web-admin/src/views/system/user/index.vue` |

商品**只读查看弹窗**结构对齐：`web-admin/src/components/business/product-view-dialog/index.vue`（由商品管理页打开，可与上表第三行一并参照）。

### 视觉与 Token（与规范一致）

- 主色链：`--primary` `#10b981`、`--primary-dark` `#059669`、`--primary-bg` `#ecfdf5`；中性字与边框见规范第 2 节表格。
- 风格：清爽 B 端、薄荷绿 + Slate；**避免一屏多种高饱和色**；次要信息用 muted 与 `.tag.muted`。
- 字体：Inter + 系统栈；正文 14px / line-height 1.5。

### 布局与页面骨架

- 侧栏 220px、顶栏 56px、内容区 padding 24px；面板圆角 10px，输入/按钮等 8px 级圆角见规范。
- 列表页典型顺序：**筛选 `filter-block`（可选）→ 列表工具栏 → `list-body` / `list-wrap`（含 `el-table`）→ 分页**。
- **单标题**：列表面板仅一个 `panel-top` 主标题；筛选区内不要再加「筛选条件」等重复标题。
- **单分隔线**：工具栏与列表之间靠 `list-body` 顶边框；列表与分页之间保留列表底边与分页顶边规则，避免双线叠加（见规范列表与分页章节）。

### 筛选与表单

- 筛选栅格、label 11px、控件高度 36px、placeholder 规则等见规范第 5 节。
- 筛选区内部：**不要用横向分割线** 区分多行条件与展开区，仅用 gap / margin。
- 弹窗表单：**`label-position="top"`**；两列可用 `form-grid-2`；长字段 `grid-column: 1 / -1`。
- 弹窗底栏：取消/确定建议 **Close / Check** 图标，图标与文字间距 **6px**；footer 按钮高度与圆角等见规范 `el-dialog` 小节。
- 长表单：`el-form` 建议 **`scroll-to-error`** 与 **`scroll-into-view-options`**；校验失败可配合 `ElMessageBox.alert` 提示（与已有页一致）。
- 遮罩：**无背景模糊**（`backdrop-filter: none`、`modal-class` 等与现有 `order-module-dialog-mask` 等策略一致）。

### 列表工具栏与表格

- 工具栏：**「已选 N 项」在最前**，其后从左到右排列主按钮与批量操作；**禁止**用 `space-between` 把整组按钮推到行末。
- **同一行仅第一个主行动** 使用主色实心（`type="primary"` / `btn-main`）；批量删除、导入导出等为中性描边。
- **操作列**：`fixed="right"`，预留足够宽度（建议 min-width ≥ 260px），避免按钮被裁切。
- 主表：`list-table` + `stripe`；与参考页「订单列表」`/#/demo/order` 一致时 **勿随意加 `border`**（以规范及上表模板页为准）。
- 分页：表格与 **`el-pagination`** 同放在 **`list-body.list-wrap`** 内；外层 **`.pagination.list-pager-bar`**，`margin-top: 0`，上边框与 padding 见规范第 7.9 节。

### 树形选择器与查看态

- 下拉树节点文案：**本级名称**；选中后输入框、表格列、导出、查看弹窗：**全路径**（见规范树形与第 5.6 节）。

### 状态与业务色

- 进行中/主状态：浅绿底 + 深绿字；警告琥珀 `#d97706` 系；危险红系用于强提醒；与订单/配送枚举映射时保持语义一致（见规范第 12 节）。

---

## 小程序端（`miniprogram`）摘要

### Token 与适配

- 品牌绿：`#0a9f6d` / `#087f57` / `#e9f9f2`；大麦黄辅助：`#d6a343` / `#fff7e8`；中性背景与边框见规范第 2.1 节。
- 主基线宽度 **375px**，兼容 **414px**；间距节奏 8–16；卡片圆角 12–16px，大容器 18–22px。

### 三端统一骨架

- 顺序一般为：Header（绿渐变）→ 统计/提示（可选）→ 功能宫格 → 主列表/任务 → 底部固定区（客户端：结算条 + TabBar）。
- Header：绿色渐变、标题左对齐、操作右对齐、下缘大圆角（约 20–24px）。

### 组件与媒体（强约束）

- 列表缩略图：**1:1**，`aspectFill`；轮播：**4:3**，`aspectFill`；详情图：**widthFix**；视频建议 720p 内、尽量短（见规范第 7.0 节）。
- 状态标签语义：`warning` 琥珀待处理、`success` 绿色进行中或完成、`danger` 红色异常；避免同屏过多高饱和色。
- 底部结算条：数量 → 总价 → 主按钮；主按钮视觉优先级最高。
- 触达区域不小于 **44×44**；注意横滑与纵向滚动冲突（尤其一级分类横滑）。

### 从 Demo 到页面

- 规范第 11 节给出 Demo class 到 `pages/**/*.vue` 的建议类名；优先统一 Token 与骨架，再收敛公共样式到 `src/styles` 或公共组件。
- 新增页面类型应先在 `docs/miniprogram-ui-spec-sanqiang.md` 补充结构说明再落代码（见规范第 10 节）。

---

## 通用开发原则

- **最小必要改动**：不扩大范围、不做无关重构；新增代码与周边文件的命名、类型、导入风格保持一致。
- **跨端颜色不要混用**：管理端用 Fresh Mint 链（`#10b981` 等）；小程序用三墙 Token（`#0a9f6d` 等）；除非产品明确要求对齐，否则不要简单复制另一端的色值。
- **后端/API 变更**：若 UI 改动依赖接口字段（如树节点 id、分类全路径），需同步评估接口与类型定义，避免前端仅末级展示造成歧义。
- 提交信息使用完整句子，说明「改了什么、为何」，避免无意义前缀堆砌。

---

## 语言

- 与用户沟通时：若用户使用简体中文，助手回复使用**简体中文**。
- 代码注释与用户可见文案：遵循项目现有语言习惯（中文业务文案以产品为准）。