MSuMshk
d46c26b5a8
包含模块：商品管理、门店管理、订单管理、财务中心、 数据统计、库存管理、多渠道整合、增值服务、 会员营销、评价管理等完整原型页面， 以及全局设计系统和项目规范文档
267 lines
9.8 KiB
Markdown
267 lines
9.8 KiB
Markdown
# TakeoutSaaS 原型项目规范 (Prototypes)
|
||
|
||
> **适用范围**：`TakeoutSaaS.Prototypes/` 下所有 HTML 原型页面。
|
||
> **核心原则**：这是原型图项目，不需要真实业务逻辑，只需要**易用性**和**风格统一**。
|
||
|
||
## 0. AI 交互约束
|
||
|
||
1. **语言**：必须使用**中文**回复与注释。
|
||
2. **只改样式和交互**：不要添加真实的 API 调用、数据校验逻辑、路由跳转。原型只需要视觉呈现和基本交互演示。
|
||
3. **不要过度工程化**：不需要 loading 动画的真实计时、不需要真实表单验证、不需要 localStorage 持久化。
|
||
4. **保持功能完整**：修改样式时不得破坏现有的抽屉开关、tab 切换、视图切换等交互功能。
|
||
5. **使用 ui-ux-pro-max skill**：新建页面或重构页面视觉时，必须先调用 `ui-ux-pro-max` skill 获取设计建议。
|
||
|
||
## 1. 技术栈
|
||
|
||
| 组件 | 说明 |
|
||
|:--|:--|
|
||
| CDN | Tailwind CSS (cdn.tailwindcss.com)、Lucide Icons (unpkg.com/lucide) |
|
||
| 框架 | 纯 HTML + 内联 `<style>` + 内联 `<script>`，无构建工具 |
|
||
| 图标 | Lucide Icons（`<i data-lucide="icon-name">`），**严禁使用 emoji 作为图标** |
|
||
| 入口 | `index.html` 为主框架（侧边栏+顶栏+标签页），各页面通过 iframe 加载 |
|
||
|
||
## 2. 全局设计系统 (定义在 index.html)
|
||
|
||
### 2.1 CSS 变量 (Tokens)
|
||
|
||
| Token | 值 | 用途 |
|
||
|:--|:--|:--|
|
||
| `--primary` | `hsl(212, 100%, 45%)` | 主色 |
|
||
| `--primary-light` | `hsl(212, 100%, 95%)` | 主色浅底 |
|
||
| `--g-radius` / `sm` / `lg` | `8px` / `6px` / `12px` | 圆角 |
|
||
| `--g-shadow-sm` | `0 1px 2px rgba(0,0,0,.04)` | 微阴影 |
|
||
| `--g-shadow` | `0 1px 3px rgba(0,0,0,.06), 0 1px 2px rgba(0,0,0,.04)` | 默认阴影 |
|
||
| `--g-shadow-md` | `0 4px 12px rgba(0,0,0,.07), 0 1px 3px rgba(0,0,0,.04)` | 中阴影 (hover) |
|
||
| `--g-shadow-lg` | `0 8px 24px rgba(0,0,0,.08), 0 2px 6px rgba(0,0,0,.04)` | 大阴影 (抽屉) |
|
||
| `--g-border` | `#f0f0f0` | 默认边框 |
|
||
| `--g-text` | `#1f1f1f` | 主文字 |
|
||
| `--g-text-secondary` | `#666` | 次要文字 |
|
||
| `--g-text-muted` | `#999` | 弱化文字 |
|
||
| `--g-danger` | `#f5222d` | 危险色 |
|
||
| `--g-success` | `#52c41a` | 成功色 |
|
||
| `--g-warning` | `#fa8c16` | 警告色 |
|
||
| `--g-transition` | `200ms cubic-bezier(.4,0,.2,1)` | 统一过渡 |
|
||
|
||
### 2.2 全局组件 class（.g- 前缀）
|
||
|
||
**必须优先使用以下全局 class，不要在页面内重复定义同类样式：**
|
||
|
||
| 类别 | Class | 说明 |
|
||
|:--|:--|:--|
|
||
| 卡片 | `.g-card` `.g-card-title` `.g-card-hd` `.g-card-hd-title` | 白底圆角卡片 |
|
||
| 按钮 | `.g-btn` `.g-btn-primary` `.g-btn-danger` `.g-btn-sm` `.g-btn-lg` | 统一按钮 |
|
||
| 表单 | `.g-form-group` `.g-form-label` `.g-form-label.required` `.g-input` `.g-select` `.g-textarea` `.g-hint` | 表单控件 |
|
||
| 表单行 | `.g-form-row` `.g-form-row-label` `.g-form-ctrl` | 左标签右控件布局 |
|
||
| 抽屉 | `.g-drawer-mask` `.g-drawer` `.g-drawer-hd` `.g-drawer-title` `.g-drawer-close` `.g-drawer-bd` `.g-drawer-ft` | 右侧滑入抽屉 |
|
||
| 开关 | `.g-toggle` `.g-toggle.on` `.g-toggle-wrap` `.g-toggle-label` | Toggle 开关 |
|
||
| 标签 | `.g-tag` `.g-tag-blue/green/orange/red/purple/gray` | 状态标签 |
|
||
| 选择 | `.g-pill` `.g-pill.checked` | Pill 单选/多选 |
|
||
| 分段 | `.g-seg` `.g-seg-item` `.g-seg-item.active` | 分段控制器 |
|
||
| 表格 | `.g-table` | 统一表格 |
|
||
| 分页 | `.g-pagination` `.g-page-btn` `.g-page-btn.active` | 分页组件 |
|
||
| 上传 | `.g-upload-zone` | 虚线上传区 |
|
||
| 操作链接 | `.g-action` `.g-action-danger` | 表格内操作链接 |
|
||
| 空状态 | `.g-empty` | 空数据占位 |
|
||
| 分割线 | `.g-divider` | 渐变分割线 |
|
||
|
||
## 3. 页面 CSS 命名规范
|
||
|
||
每个页面的私有样式必须使用**页面前缀**，避免与全局 class 冲突：
|
||
|
||
| 页面 | 前缀 | 示例 |
|
||
|:--|:--|:--|
|
||
| product-list | `pl-` | `.pl-toolbar`, `.pl-card` |
|
||
| product-detail | `pdt-` | `.pdt-section`, `.pdt-anchor` |
|
||
| product-specs | `ps-` | `.ps-card` |
|
||
| product-addons | `pa-` | `.pa-group-card` |
|
||
| product-combos | `pc-` | `.pc-combo-card` |
|
||
| product-labels | `plb-` | `.plb-preview` |
|
||
| product-category | `pcat-` | `.pcat-tree` |
|
||
| product-schedule | `psch-` | `.psch-timeline` |
|
||
| product-batch | `pb-` | `.pb-panel` |
|
||
| store-list | `sl-` | `.sl-stat-card` |
|
||
| store-hours | `sh-` | `.sh-week-row` |
|
||
| store-delivery | `pd-` | `.pd-tier-card` |
|
||
| store-pickup | `pp-` | `.pp-slot-cell` |
|
||
| store-dinein | `sdi-` | `.sdi-table-card` |
|
||
| store-fees | `pf-` | `.pf-fee-card` |
|
||
| store-staff | `ss-` | `.ss-schedule-grid` |
|
||
| store-qualifications | `sq-` | `.sq-cert-card` |
|
||
| dashboard | `db-` | `.db-kpi-card` |
|
||
|
||
## 4. 强制易用性规范 (UX Mandatory Rules)
|
||
|
||
以下规则适用于所有页面，**新建或修改页面时必须遵守**：
|
||
|
||
### 4.1 表单必填字段必须标记
|
||
|
||
所有必填字段的 label 必须加 `.required` class（自动显示红色星号）。
|
||
|
||
```html
|
||
<label class="g-form-label required">商品名称</label>
|
||
```
|
||
|
||
### 4.2 输入框必须有 placeholder
|
||
|
||
所有 `<input>` 和 `<textarea>` 必须有有意义的 placeholder 提示，不得留空。placeholder 应为引导性文案，不要用默认值（如 `0.00`）作为 placeholder。
|
||
|
||
```html
|
||
<!-- 正确 -->
|
||
<input class="g-input" placeholder="请输入商品名称">
|
||
<input class="g-input" type="number" placeholder="如：29.90">
|
||
|
||
<!-- 错误 -->
|
||
<input class="g-input">
|
||
<input class="g-input" placeholder="0.00">
|
||
```
|
||
|
||
### 4.3 抽屉底部按钮必须固定可见
|
||
|
||
抽屉的 footer（`.g-drawer-ft`）已通过 flex 布局固定在底部。**不要**把提交按钮放在 `.g-drawer-bd` 内部，必须放在 `.g-drawer-ft` 中。
|
||
|
||
```html
|
||
<div class="g-drawer">
|
||
<div class="g-drawer-hd">...</div>
|
||
<div class="g-drawer-bd"><!-- 表单内容，可滚动 --></div>
|
||
<div class="g-drawer-ft">
|
||
<button class="g-btn" onclick="closeDrawer()">取消</button>
|
||
<button class="g-btn g-btn-primary">确认</button>
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
### 4.4 操作按钮过多时收入"更多"菜单
|
||
|
||
表格每行操作链接不超过 3 个。超过 3 个时，保留最常用的 2-3 个，其余收入"更多"下拉菜单。
|
||
|
||
### 4.5 已禁用/已停用项的视觉区分
|
||
|
||
已停用、已下架、已离职等非活跃状态的卡片/行，必须有明显的视觉弱化（降低透明度、灰色遮罩、或灰色边框），让用户一眼区分。
|
||
|
||
### 4.6 编辑与查看的交互一致性
|
||
|
||
同一页面内，要么全部使用 inline 编辑，要么全部通过抽屉编辑，不要混用两种模式。
|
||
|
||
### 4.7 危险按钮的视觉区分
|
||
|
||
"删除"按钮/链接必须使用 `.g-action-danger` 或 `.g-btn-danger`，与普通操作在颜色上明确区分。
|
||
|
||
## 5. 视觉风格规范
|
||
|
||
### 5.1 设计方向
|
||
|
||
Swiss Modernism + Bento Box 风格：干净、留白充足、阴影层次分明、无多余装饰。
|
||
|
||
### 5.2 色彩层级
|
||
|
||
| 用途 | 色值 | 变量 |
|
||
|:--|:--|:--|
|
||
| 主文字 | `#1a1a2e` 或 `#1f1f1f` | `--g-text` |
|
||
| 次要文字 | `#4b5563` 或 `#666` | `--g-text-secondary` |
|
||
| 弱化文字 | `#9ca3af` 或 `#999` | `--g-text-muted` |
|
||
| 边框 | `#e5e7eb` 或 `#f0f0f0` | `--g-border` |
|
||
| 表头背景 | `#f8f9fb` 或 `#fafafa` | `--g-bg-subtle` |
|
||
| 行分割线 | `#f3f4f6` 或 `#f5f5f5` | — |
|
||
|
||
### 5.3 阴影使用规则
|
||
|
||
- 静态卡片：`var(--g-shadow-sm)` 或无阴影 + border
|
||
- Hover 状态：`var(--g-shadow-md)`
|
||
- 抽屉/弹窗：`var(--g-shadow-lg)`
|
||
- **不要**在静态元素上使用 `--g-shadow-lg`
|
||
|
||
### 5.4 圆角规则
|
||
|
||
- 大容器/卡片：`10px` 或 `var(--g-radius)`
|
||
- 按钮/输入框/小元素：`var(--g-radius-sm)` (6px)
|
||
- 上传区/大面板：`var(--g-radius-lg)` (12px)
|
||
|
||
### 5.5 过渡动画
|
||
|
||
所有交互元素的 transition 统一使用 `var(--g-transition)`，即 `200ms cubic-bezier(.4,0,.2,1)`。不要使用 `0.3s ease` 或其他自定义值。
|
||
|
||
### 5.6 Hover 状态
|
||
|
||
- 卡片 hover：加 `var(--g-shadow-md)`，可选 `translateY(-1px)` 微浮
|
||
- 表格行 hover：`background: color-mix(in srgb, var(--primary) 3%, #fff)`
|
||
- 按钮 hover：参考 `.g-btn` 已定义的 hover 样式
|
||
- **不要**使用 `scale` 变换做 hover（会导致布局抖动）
|
||
|
||
### 5.7 Section 标题样式
|
||
|
||
页面内分区标题统一使用左侧 3px 主色竖线 + 加粗文字：
|
||
|
||
```css
|
||
.xx-section-hd {
|
||
font-size: 15px;
|
||
font-weight: 600;
|
||
color: var(--g-text);
|
||
padding-left: 10px;
|
||
border-left: 3px solid var(--primary);
|
||
margin-bottom: 16px;
|
||
}
|
||
```
|
||
|
||
## 6. JS 交互规范
|
||
|
||
### 6.1 抽屉开关模式
|
||
|
||
```javascript
|
||
function openDrawer(mode) {
|
||
document.getElementById('drawerMask').classList.add('open');
|
||
document.getElementById('drawer').classList.add('open');
|
||
}
|
||
function closeDrawer() {
|
||
document.getElementById('drawerMask').classList.remove('open');
|
||
document.getElementById('drawer').classList.remove('open');
|
||
}
|
||
```
|
||
|
||
### 6.2 Toggle 开关
|
||
|
||
```javascript
|
||
function toggleSwitch(el) {
|
||
el.classList.toggle('on');
|
||
}
|
||
```
|
||
|
||
### 6.3 Pill 选择
|
||
|
||
```javascript
|
||
function togglePill(el) {
|
||
el.classList.toggle('checked');
|
||
}
|
||
```
|
||
|
||
### 6.4 事件绑定注意
|
||
|
||
使用 `event.currentTarget`（而非 `event.target`）获取绑定事件的元素，避免点击子元素时取到错误的 target。
|
||
|
||
## 7. 文件结构
|
||
|
||
```
|
||
TakeoutSaaS.Prototypes/
|
||
├── index.html # 主框架（侧边栏+顶栏+标签页+全局CSS设计系统）
|
||
└── pages/
|
||
├── dashboard.html
|
||
├── product-list.html
|
||
├── product-detail.html
|
||
├── product-specs.html
|
||
├── product-addons.html
|
||
├── product-combos.html
|
||
├── product-labels.html
|
||
├── product-category.html
|
||
├── product-schedule.html
|
||
├── product-batch.html
|
||
├── store-list.html
|
||
├── store-hours.html
|
||
├── store-delivery.html
|
||
├── store-pickup.html
|
||
├── store-dinein.html
|
||
├── store-fees.html
|
||
├── store-staff.html
|
||
└── store-qualifications.html
|
||
```
|
||
|
||
新增页面时，在 `pages/` 下创建 HTML 文件，并在 `index.html` 的侧边栏菜单中添加对应入口。
|