diff --git a/.claude/skills/generate-prototype-grid/SKILL.md b/.claude/skills/generate-prototype-grid/SKILL.md new file mode 100644 index 0000000..854bc83 --- /dev/null +++ b/.claude/skills/generate-prototype-grid/SKILL.md @@ -0,0 +1,598 @@ +--- +name: generate-prototype-grid +description: 根据方案文档/需求文档生成原型平铺展示系统。AI 工作流:分析文档 → 拆分功能模块 → 生成各页面独立 HTML → 生成平铺入口页面。架构:每个页面是独立 HTML 文件,入口页面通过 iframe 网格同时平铺展示所有页面。 +--- + +# Generate Prototype Grid + +根据方案文档生成原型平铺展示系统的 **AI 工作流**。 + +## 核心架构说明 + +### ⭐ 平铺展示架构(核心概念) + +本技能采用 **iframe 平铺展示架构**,所有页面同时显示在网格中,一目了然: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ admin-index.html (平铺入口) │ +│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━ │ +│ 所有页面同时显示,一键总览 │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────┬─────────────────────┬───────────────┐ │ +│ │ + + + + + + + + +``` + +### 响应式平铺布局 + +```html + +``` + +### iframe 配置要点 + +| 属性 | 值 | 说明 | +|------|-----|------| +| src | `pages/admin/xxx.html` | 加载独立 HTML 文件的路径 | +| class | `prototype-iframe` | 统一样式类,固定高度和边框 | +| title | 页面名称 | 辅助功能,iframe 标题 | +| scrolling | `auto` 或 `yes` | 允许滚动(页面内容可能超过 iframe 高度) | +| loading | `lazy` | 懒加载,优化性能(可选) | + +### 平铺布局选项 + +| 布局 | CSS | 适用场景 | +|------|-----|----------| +| **2列网格** ⭐ | `grid-template-columns: repeat(2, 1fr)` | 默认,桌面端平铺 | +| 3列网格 | `grid-template-columns: repeat(3, 1fr)` | 大屏幕,更多页面 | +| 1列网格 | `grid-template-columns: 1fr` | 小屏幕,移动端 | + +## Step 4: 生成统一入口页面 + +生成 `index.html` 作为项目统一入口,整合原型系统和文档系统。 + +### 页面结构 + +- 深色渐变背景 +- 顶部项目信息栏 +- 双卡片入口(原型系统 + 文档系统) +- 快速链接导航 +- 项目概览信息 + +## Step 5: 生成文档系统 + +生成 `docs-index.html` 文档首页,自动读取和展示 `docs/` 目录下的 Markdown 文件。 + +### 功能特性 +- 自动扫描 `docs/` 目录 +- 实时 Markdown 转 HTML +- 文档搜索功能 +- 卡片/内容双视图切换 + +## Step 6: 生成本地预览服务器 + +生成 `server.js` 文件,提供静态文件服务和文档渲染 API。 + +### 服务器功能 +- 静态文件服务 +- Markdown 转 HTML +- 文档列表 API: `GET /api/docs` +- 文档渲染 API: `GET /api/doc/:name` +- **中文文件名支持**: URL 解码处理 `decodeURIComponent()` + +### ⚠️ 中文文件名处理 + +**关键修复**: 文档渲染 API 必须处理 URL 编码的中文文件名 + +```javascript +// server.js 中文档渲染端点 +app.get('/api/doc/:name', (req, res) => { + const docName = decodeURIComponent(req.params.name); // 必须解码! + // 如果文件名已包含 .md 后缀,不要再加 + const docPath = docName.endsWith('.md') ? docName : docName + '.md'; + const filePath = path.join(DOCS_DIR, docPath); + // ... +}); +``` + +**问题原因**: 前端请求中文文件名时会自动 URL 编码(如 `%E5%8E%9F%E5%A7%8B...`),后端必须解码才能找到文件。 + +### ⚠️ 代码块样式处理 + +**关键修复**: Markdown 转 HTML 时必须保护代码块内容,避免换行被错误替换 + +```javascript +// 使用占位符保护代码块 +const codeBlocks = []; +let html = markdown + // 先提取代码块,用占位符替换 + .replace(/```(\w*)\n?([\s\S]*?)```/g, (match, lang, code) => { + const placeholder = `__CODE_BLOCK_${codeBlocks.length}__`; + const isAsciiArt = /┌|│|└|├|─|┐|┘|┤/.test(code); + const bgClass = isAsciiArt ? 'bg-gray-800 text-gray-100' : 'bg-gray-100 text-gray-900'; + codeBlocks.push(`
${code}
`); + return placeholder; + }) + // ... 其他处理 ... + // 最后恢复代码块 + .replace(/__CODE_BLOCK_(\d+)__/g, (match, index) => codeBlocks[index]); +``` + +**问题原因**: 直接用 `.replace(/\n/g, '
')` 会把代码块中的换行也替换成 `
`,导致每行都有背景。 + +**样式规范**: +- ASCII图表代码块:`bg-gray-800 text-gray-100`(深色背景+浅色文字) +- 普通代码块:`bg-gray-100 text-gray-900`(浅色背景+深色文字) +- 内联代码:`bg-gray-200 text-gray-800`(浅灰背景+深色文字) + +### ⚠️ Markdown 代码块样式 + +**关键修复**: 代码块必须正确处理,避免白字白底无法阅读 + +```javascript +// 代码块正则(支持带或不带换行符的格式) +.replace(/```(\w*)\n?([\s\S]*?)```/g, (match, lang, code) => { + // 判断是否为ASCII图表(包含框线字符) + const isAsciiArt = /┌|│|└|├|─|┐|┘|┤/.test(code); + // 如果是ASCII图表,使用深色背景+浅色文字;否则使用灰色背景 + const bgClass = isAsciiArt ? 'bg-gray-800 text-gray-100' : 'bg-gray-100 text-gray-800'; + return `
${code}
`; +}) +``` + +**问题原因**: Markdown 代码块可能使用 ``` 后面直接跟内容(无换行符),正则必须兼容这种格式。同时需要为 ASCII 图表使用深色背景以提升可读性。 + +### 使用方法 + +```bash +cd prototype/ +node server.js +# 访问: http://localhost:7357 +``` + +### 端口说明 +- **默认端口**: 7357 (偏门端口) +- **统一入口**: http://localhost:7357/index.html +- **原型系统**: http://localhost:7357/admin-index.html +- **文档系统**: http://localhost:7357/docs-index.html + +--- + +## Step 7: 自动验证与测试 + +使用 **Playwright MCP** 和 **图片 MCP** 进行自动化验证。 + +### 验证流程 + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ 1. 启动服务器 │ → │ 2. 遍历页面链接 │ → │ 3. 截图保存 │ +│ node server.js │ │ Playwright导航 │ │ 保存到screenshots│ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + ↓ + ┌─────────────────┐ + │ 4. AI分析验证 │ + │ 图片MCP+需求对比│ + └─────────────────┘ +``` + +### 使用 Playwright MCP 进行验证 + +```javascript +// 1. 启动浏览器 +mcp__playwright__browser_navigate +url: http://localhost:7357/index.html + +// 2. 获取页面快照 +mcp__playwright__browser_snapshot + +// 3. 截图保存 +mcp__playwright__browser_take_screenshot +filename: prototype/screenshots/01-index.png +fullPage: true + +// 4. 点击原型系统入口 +mcp__playwright__browser_click +ref: [找到原型系统卡片的链接] + +// 5. 验证原型系统页面 +mcp__playwright__browser_snapshot +mcp__playwright__browser_take_screenshot +filename: prototype/screenshots/02-prototype-index.png + +// 6. 遍历所有页面链接 +// 重复上述步骤... +``` + +### 使用图片 MCP 分析截图 + +```javascript +// 分析页面布局和样式 +mcp__zai-mcp-server__analyze_image +imageSource: prototype/screenshots/01-index.png +prompt: 详细描述这个页面的布局结构、设计风格、配色方案、组件样式,评估其美观度和专业性 + +// 验证与需求文档的符合度 +mcp__zai-mcp-server__ui_diff_check +expected_image_source: docs/参考设计图.png +actual_image_source: prototype/screenshots/actual.png +prompt: 对比参考设计与实际实现,指出差异和问题 +``` + +### 验证检查清单 + +#### 1. 链接验证 +- [ ] 所有导航链接可点击 +- [ ] 页面跳转正确 +- [ ] 无 404 错误 +- [ ] 返回链接正常 + +#### 2. 显示验证 +- [ ] 页面标题正确 +- [ ] 导航栏显示正常 +- [ ] 侧边栏菜单完整 +- [ ] 内容区域布局正确 +- [ ] 数据卡片显示正常 + +#### 3. 平铺布局验证(⭐ 重点) +- [ ] 所有页面同时可见(2列3行网格) +- [ ] iframe 高度足够显示完整内容(750px) +- [ ] 每个页面独立加载,无相互影响 +- [ ] 页面标签清晰可见 +- [ ] 网格间距合理,视觉舒适 +- [ ] 成功实现"一键总览"目标 + +#### 3. 样式验证(通过图片 MCP) +- [ ] 配色方案符合规范 +- [ ] 字体大小合适 +- [ ] 间距布局合理 +- [ ] 阴影和圆角统一 +- [ ] 响应式适配正常 + +#### 4. 需求符合度验证 +- [ ] 功能模块完整 +- [ ] 数据字段齐全 +- [ ] 交互流程正确 +- [ ] 与需求文档描述一致 + +### 验证报告模板 + +```markdown +# 原型验证报告 + +## 测试概览 +- 测试时间: 2026-xx-xx +- 测试页面: 6 个 +- 截图数量: X 张 +- 验证方式: Playwright MCP + Image MCP + +## 链接验证结果 +| 页面 | 链接状态 | 跳转正确 | 备注 | +|------|---------|---------|------| +| index.html | ✅ | ✅ | 正常 | +| admin-index.html | ✅ | ✅ | 平铺入口 | +| docs-index.html | ✅ | ✅ | 文档系统 | + +## 平铺布局验证结果 ⭐ +| 验证项 | 结果 | 说明 | +|--------|------|------| +| 所有页面同时可见 | ✅ | 2列3行网格,6个页面全部显示 | +| iframe 高度足够 | ✅ | 1000px 高度可显示完整页面内容 | +| 页面独立加载 | ✅ | 每个页面独立 HTML 文件 | +| 页面标签清晰 | ✅ | 蓝色标签显示页面名称 | +| 网格间距合理 | ✅ | 16px gap,视觉舒适 | +| 一键总览目标 | ✅ | 成功实现,无需切换页面 | + +## 样式分析结果(Image MCP) +### 美观度评分: 9/10 +- 配色: 9/10 - 蓝色系主色调,状态色区分清晰 +- 布局: 9/10 - 2列3行网格,模块分布均匀 +- 字体: 9/10 - sans-serif 统一风格 +- 整体: 9/10 - 专业数据仪表盘风格 + +### Image MCP 分析结论 +- ✅ 所有6个页面同时可见并平铺展示 +- ✅ 750px 高度足够显示完整页面内容 +- ✅ 2列3行网格布局合理 +- ✅ 美观度与专业性强 +- ✅ 成功实现"一键总览"目标 + +### 问题列表 +1. [问题描述] + - 位置: [页面/元素] + - 建议: [改进建议] + +## 需求符合度 +| 需求项 | 符合度 | 备注 | +|--------|--------|------| +| 功能模块1 | ✅ 100% | 完全符合 | +| 功能模块2 | ⚠️ 80% | 部分符合 | + +## 改进建议 +[根据分析结果提出的改进建议] +``` + +## 设计规范参考 + +详细设计规范参见 [design-patterns.md](references/design-patterns.md): +- 桌面端平铺网格布局规范(2列/3列网格) +- iframe 容器样式标准 +- 颜色主题系统 +- 组件样式标准 + +## 模式选择 + +| 模式 | 入口页面 | 布局特点 | 适用场景 | +|------|---------|---------|---------| +| **平铺展示** ⭐ | admin-index.html | CSS Grid 网格平铺
所有页面同时显示 | 原型展示、评审、演示 | +| 大屏平铺 | admin-index.html | 3列网格布局
所有页面同时显示 | 大屏幕、页面较多时 | +| 标准平铺 | admin-index.html | 2列网格布局
所有页面同时显示 | 默认桌面端展示 | +| 移动端 | admin-index.html | 1列网格布局
所有页面垂直排列 | 小屏幕、移动设备 | + +## 工作示例 + +参考当前项目实现: +- `/mnt/code-fast/temp-humidity-demo/prototype/index.html` +- `/mnt/code-fast/temp-humidity-demo/prototype/admin-index.html` +- `/mnt/code-fast/temp-humidity-demo/prototype/docs-index.html` +- `/mnt/code-fast/temp-humidity-demo/prototype/server.js` diff --git a/.claude/skills/generate-prototype-grid/references/design-patterns.md b/.claude/skills/generate-prototype-grid/references/design-patterns.md new file mode 100644 index 0000000..8bb8410 --- /dev/null +++ b/.claude/skills/generate-prototype-grid/references/design-patterns.md @@ -0,0 +1,333 @@ +# 原型设计规范 + +## 移动端布局规范 + +### 手机框架 +- **尺寸**: 375px × 812px (iPhone X/11/12/13 标准) +- **圆角**: 40px +- **边框**: 12px solid #1a1a1a +- **阴影**: 0 25px 50px -12px rgba(0, 0, 0, 0.4) + +### 状态栏 +- **前端页面**: 白色背景 (`bg-white`) +- **后端页面**: 深色背景 (`bg-slate-800`) +- **高度**: 36px +- **内边距**: px-4 py-2 + +### 导航栏 +- **前端页面**: 蓝色渐变 (`bg-gradient-to-r from-blue-500 to-blue-600`) +- **后端页面**: 深色背景 (`bg-slate-800`) +- **高度**: 48px +- **返回按钮**: 左侧 +- **标题**: 居中 +- **操作按钮**: 右侧 + +## 桌面端布局规范 + +### 侧边栏导航 +- **宽度**: 260px +- **背景**: 深色 (`bg-slate-800`) +- **文字颜色**: 白色/浅灰 +- **高度**: 100vh (固定) +- **Logo区**: 顶部 80px +- **导航菜单**: 中间滚动区域 +- **用户信息**: 底部固定 + +### 主内容区 +- **宽度**: flex-1 (自动填充) +- **背景**: 浅灰 (`bg-gray-100`) +- **内边距**: 24px +- **最大宽度**: 无限制 + +### 顶部栏 +- **背景**: 白色 (`bg-white`) +- **圆角**: 12px +- **阴影**: 小阴影 +- **内边距**: 16px +- **布局**: 左右分栏(标题 + 操作按钮) + +### 页面卡片网格 +- **网格**: 响应式网格 +- **小屏**: 1列 +- **中屏**: 2列 (md:grid-cols-2) +- **大屏**: 3列 (lg:grid-cols-3) +- **超大屏**: 4列 (xl:grid-cols-4) +- **间距**: 16px (gap-4) + +### 卡片样式 +- **背景**: 白色 (`bg-white`) +- **圆角**: 12px (`rounded-xl`) +- **阴影**: 小阴影 (`shadow-sm`) +- **悬停**: 上移4px + 加深阴影 +- **内边距**: 24px (p-6) +- **边框**: 左侧彩色边框 (border-l-4) + +## 颜色主题系统 + +### 移动端页面 + +#### 前端页面 +``` +主色: blue-500 (蓝色) +辅助色: amber-500 (橙色) +成功色: green-500 (绿色) +背景色: gray-50 / gray-100 (浅灰) +文字色: gray-800 (深灰) +``` + +#### 后端页面 +``` +主色: amber-500 (数据看板) +辅助色: blue-500 (资源管理) +成功色: green-500 (订单管理) +紫色: purple-500 (会员分佣) +红色: red-500 (系统设置) +背景色: slate-800 / slate-900 (深色) +文字色: white / slate-400 +``` + +### 桌面端页面 + +#### 侧边栏 +``` +背景: slate-800 (深灰) +选中: slate-700 (稍浅) +悬停: slate-700 (稍浅) +文字: white / slate-300 +边框: slate-700 +``` + +#### 主内容区 +``` +背景: gray-100 (浅灰) +卡片背景: white +文字: gray-800 / gray-600 +边框: gray-200 +``` + +#### 功能颜色映射 +``` +数据看板: blue-500 +用户管理: green-500 +内容管理: purple-500 +订单管理: orange-500 +财务管理: amber-500 +系统设置: gray-500 +``` + +## 组件样式标准 + +### 移动端组件 + +#### 卡片 +``` +圆角: rounded-2xl (16px) +内边距: p-4 (16px) +阴影: shadow-sm +背景: bg-white (前端) / bg-white (后端内容区) +``` + +#### 按钮 +``` +主要按钮: bg-gradient-to-r from-amber-400 to-orange-500 +次要按钮: bg-gray-100 +圆角: rounded-xl (12px) +内边距: py-3 px-4 (垂直12px 水平16px) +``` + +### 桌面端组件 + +#### 导航菜单项 +``` +内边距: px-4 py-3 +圆角: rounded-lg (8px) +颜色: text-slate-300 +悬停: hover:bg-slate-700 hover:text-white +间距: mb-1 +图标宽度: w-5 (20px) +``` + +#### 页面卡片 +``` +圆角: rounded-xl (12px) +阴影: shadow-sm +悬停阴影: hover:shadow-md +内边距: p-6 (24px) +边框: border-l-4 (左侧彩色边框) +``` + +#### 按钮组 +``` +主要按钮: bg-blue-500 hover:bg-blue-600 +次要按钮: bg-slate-800 hover:bg-slate-700 +圆角: rounded-lg (8px) +内边距: px-4 py-2 +文字大小: text-sm +``` + +## 页面分类 + +### 移动端前端分类 + +1. **核心页面** (蓝色) + - 首页/资源列表 + - 资源详情 + - 音频详情(试听) + - 搜索页面 + - 分类浏览 + +2. **用户中心** (绿色) + - 微信授权登录 + - 个人中心 + - 设置页面 + - 关于我们 + +3. **订单支付** (橙色) + - 确认订单 + - 支付页面 + - 支付结果 + - 我的订单 + +4. **会员分佣** (紫色) + - 会员充值 + - 我的钱包 + - 邀请推广 + - 提现申请 + +### 移动端后端分类 + +1. **数据看板** (amber-500) + - 后台首页 + - 数据统计 + - 收入报表 + - 用户分析 + +2. **资源管理** (blue-500) + - 文件列表 + - 文件上传 + - 价格管理 + - 批量设置 + - 分类管理 + +3. **订单管理** (green-500) + - 订单列表 + - 订单详情 + - 退款管理 + - 交易记录 + +4. **会员分佣** (purple-500) + - 套餐管理 + - 会员列表 + - 分佣设置 + - 提现审核 + +5. **系统设置** (red-500) + - 用户管理 + - 微信配置 + - 支付配置 + - 系统设置 + +### 桌面端管理后台分类 + +1. **数据看板** (blue-500) + - 仪表盘 + - 数据统计 + - 图表分析 + +2. **用户管理** (green-500) + - 用户列表 + - 用户详情 + - 权限管理 + +3. **内容管理** (purple-500) + - 文章管理 + - 分类管理 + - 标签管理 + +4. **订单管理** (orange-500) + - 订单列表 + - 订单详情 + - 退款处理 + +5. **财务管理** (amber-500) + - 收入统计 + - 提现审核 + - 财务报表 + +6. **系统设置** (gray-500) + - 基本设置 + - 支付配置 + - 系统日志 + +## 响应式设计原则 + +### 移动端网格系统 +``` +小屏 (1列): grid-cols-1 +中屏 (2列): md:grid-cols-2 +大屏 (3列): lg:grid-cols-3 +超大屏 (4列): xl:grid-cols-4 +``` + +### 桌面端网格系统 +``` +小屏 (1列): grid-cols-1 +中屏 (2列): md:grid-cols-2 +大屏 (3列): lg:grid-cols-3 +超大屏 (4列): xl:grid-cols-4 +宽屏 (5列): 2xl:grid-cols-5 +``` + +### 间距规范 +``` +移动端页面边距: px-4 (16px) +桌面端页面边距: px-6 或 p-6 (24px) +卡片间距: gap-4 (16px) 或 gap-6 (24px) +章节间距: mb-6 或 mb-8 (24px或32px) +元素间距: gap-3 (12px) +``` + +## iframe 路径规范 + +### 移动端入口页面 +``` +相对路径: pages/front/xxx.html 或 pages/back/xxx.html +示例: +``` + +### 桌面端入口页面 +``` +相对路径: pages/admin/xxx.html +示例: +或直接加载页面内容(不使用iframe) +``` + +### 文档首页 +``` +相对路径: docs/index.html +示例: +``` + +## 技术栈 + +- **CSS框架**: Tailwind CSS (CDN: https://cdn.tailwindcss.com) +- **图标**: Font Awesome 6.4.0 (CDN: https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css) +- **HTML版本**: HTML5 +- **字符编码**: UTF-8 +- **视口**: + - 移动端: width=device-width, initial-scale=1.0 + - 桌面端: width=device-width, initial-scale=1.0 + +## 模式选择指南 + +### 使用移动端模式当: +- 目标用户主要使用移动设备 +- 需要展示移动应用原型 +- 需要 H5 页面展示 +- 需要小程序原型 + +### 使用桌面端模式当: +- 目标用户主要使用电脑 +- 需要展示管理后台系统 +- 需要数据看板展示 +- 需要复杂的数据管理界面