126 lines
8.6 KiB
Plaintext
126 lines
8.6 KiB
Plaintext
# shanxia2.0 工程 Cursor 规则
|
||
|
||
本仓库含 Web 管理端（`web-admin`）、小程序端（`miniprogram`）等子工程。实现或修改 UI 时，**以文档为权威来源**，本文件仅作快速索引与强约束摘要。
|
||
|
||
## 权威文档（必读路径）
|
||
|
||
- **多系统边界与 SQL 快照**：`openspec/changes/zkxw-engineering-standards/specs/ecosystem-landscape/spec.md`（`docs/sql/dibang.sql` 地磅、`shanxia2.0.sql` 本仓库门户、`sx.sql` CRM；CRM 代码在并列仓库 `shanxia/crm/`）
|
||
- **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、分类全路径），需同步评估接口与类型定义，避免前端仅末级展示造成歧义。
|
||
- 提交信息使用完整句子，说明「改了什么、为何」，避免无意义前缀堆砌。
|
||
|
||
---
|
||
|
||
## 语言
|
||
|
||
- 与用户沟通时：若用户使用简体中文，助手回复使用**简体中文**。
|
||
- 代码注释与用户可见文案：遵循项目现有语言习惯（中文业务文案以产品为准）。
|