提交

.cursorrules

@@ -0,0 +1,102 @@
+# 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` 为准。
+- **小程序端（三墙 Demo 体系）**：`docs/miniprogram-ui-spec-sanqiang.md`  
+  适用范围：`miniprogram`（客户端 / 供应商端 / 配送员端）。视觉以该文档及 `mobile-ui/sanqiang-*.html` 为准。
+
+修改对应子工程前，若涉及界面，应先检索上述文档中的章节（类名、Token、结构顺序）。
+
+---
+
+## Web 管理端（`web-admin`）摘要
+
+### 技术栈与实现方式
+
+- Vue 3 + Element Plus；主题与皮肤通过 **CSS 变量 + Element 主题变量 + 全局覆盖** 对齐规范，**勿随意改 Token 色值**。
+- 树形主数据全路径：`web-admin/src/utils/tree-path.ts`（如 `buildTreePathLabelFromFlat`、`buildPathLabelMapFromTreeRoots`、`resolveTreePathDisplay`）。路径分隔符统一为 **` / `**（半角斜杠两侧各一空格）。
+- 参考实现：商品查看弹窗 `web-admin/src/components/business/product-view-dialog/index.vue`；列表与分页对齐 `#/base/unit` 等已改造页。
+
+### 视觉与 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`；与已对齐订单列表一致时 **勿随意加 `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、分类全路径），需同步评估接口与类型定义，避免前端仅末级展示造成歧义。
+- 提交信息使用完整句子，说明「改了什么、为何」，避免无意义前缀堆砌。
+
+---
+
+## 语言
+
+- 与用户沟通时：若用户使用简体中文，助手回复使用**简体中文**。
+- 代码注释与用户可见文案：遵循项目现有语言习惯（中文业务文案以产品为准）。