name: glmv-prd-to-app
description: |-
    Build a complete, production-ready full-stack web application from PRD documents, prototype images, and resource files. Handles the entire pipeline: system design, database schema, seed data, backend API, frontend UI, visual verification against prototypes, and deployment script generation.
    Use this skill whenever the user: - Provides a PRD (product requirement document) and wants a working app built - Says things like "根据PRD开发", "build from PRD", "implement this product",
      "把需求文档做成应用", "develop this app from requirements"
    - Has prototype images + requirements and wants full-stack implementation - Wants to turn product specifications into a running web application - Mentions building an app from wireframes/mockups combined with a requirements doc
    Trigger this skill even if the user just says "帮我开发" or "build this" with PRD materials present in the working directory.

GLM-V PRD到应用：全栈应用构建器

语言：使用与用户相同的语言回复。代码注释应保持一致。

根据PRD、原型和资源构建一个完整的、已部署的Web应用程序。

结果必须能够通过单个 bash /workspace/start.sh 命令完全重现。

---

阶段 0：材料发现与分析

在执行任何操作之前，先了解你正在处理的内容。

0a. 定位所有输入

/workspace/prd.md              ← 产品需求文档
/workspace/prototypes/*.jpg    ← UI原型图像（视觉真相）
/workspace/resources/**/*      ← 图像、视频、图标及其他资源

如果材料位于不同的位置，请相应调整。完整阅读PRD。

0b. 深度原型分析

对于每张原型图像：

1. 使用读取工具读取每张图像 — 你是多模态的，直接检查它们。
2. 对于每张图像，记录以下内容：

• 页面标识：这代表哪个页面/视图
• 布局结构：页眉、侧边栏、主要内容、页脚、模态框
• 组件清单：每个按钮、表单、卡片、表格、列表、导航元素
• 内容清单：所有可见文本、数字、标签、占位内容
• 颜色提取：主色、辅色、强调色、背景色、文本色（十六进制值）
• 排版：观察到的字体大小、粗细、层次结构
• 交互状态：悬停效果、活动标签、选中项、切换开关
• 数据模式：填充列表/表格/卡片的数据类型 — 这驱动种子数据

1. 构建一个页面地图，展示原型页面之间的导航流程。

0c. 资源清单

列出 /workspace/resources/ 中的所有文件，并将每个文件映射到它在原型中出现的位置。

所有资源文件必须在最终应用程序中相关的地方使用。

---

阶段 1：系统设计文档

在 /workspace/docs/design.md 生成一份全面的设计文档。

1a. 数据模型

对于每个实体，指定：

• 表/集合名称
• 所有字段及其类型、约束、默认值
• 关系（外键、多对多）
• 查询模式所需的索引
• 内容映射：哪些原型元素映射到哪些字段

示例：

products 表：
  id          SERIAL PRIMARY KEY
  name        VARCHAR(200) NOT NULL    ← 来自产品卡片标题
  price       DECIMAL(10,2) NOT NULL   ← 来自产品卡片价格标签
  image_url   TEXT NOT NULL             ← 来自产品卡片图像
  category_id INTEGER REFERENCES categories(id) ← 来自分类筛选器
  ...

1b. API 设计

针对每个页面交互，定义一个API端点：

• 方法 + 路径
• 请求参数/请求体模式
• 响应模式及示例
• 哪个原型交互触发了此API
• 错误响应

1c. 前端架构

• 组件层次结构（树形结构）
• 映射到原型页面的路由定义
• 状态管理方法
• 每个原型页面如何映射到组件

1d. 技术栈

根据PRD复杂度选择。推荐默认值：

记录选择及理由。

1e. 目录结构

/workspace/
├── frontend/          ← 或 client/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/   ← API客户端
│   │   ├── types/
│   │   └── assets/     ← 从 /workspace/resources 复制
│   └── ...
├── backend/           ← 或 server/
│   ├── src/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── controllers/
│   │   ├── middleware/
│   │   └── seed/
│   └── ...
├── docs/
│   ├── design.md
│   └── README.md
├── start.sh
└── prd.md

---

阶段 2：种子数据生成

种子数据至关重要——它使应用在首次启动时看起来真实。

规则

1. 从原型中提取：原型图像中每一段可见的文本、图像、数字都必须出现在种子数据中。再次读取每张原型图像并转录内容。

1. 完整覆盖：

• 每个列表/表格必须具有原型中显示的准确数量的项目
• 每张卡片的内容必须与原型匹配
• 每个下拉菜单必须具有与原型匹配的选项
• 导航项必须与原型导航匹配
• 统计/计数器必须与原型数字匹配

1. 使用资源文件：将 /workspace/resources/ 中的资源文件（图像、视频、图标）映射到种子数据条目。使用相对路径或复制到 public/static 目录。

1. 无占位符：没有“Lorem ipsum”，没有“测试项1”，没有 placeholder.com 图像。

1. 支持所有状态：包含能够体现空状态、加载状态、错误场景的数据，如PRD中指定。

输出

将种子数据保存为：

• SQL种子文件，或
• JSON fixtures，或
• ORM种子脚本

放置在 /workspace/backend/src/seed/（或等效目录）。

---

阶段 3：后端实现

3a. 数据库模式

• 为所有表创建迁移文件
• 包含适当的约束、索引、外键
• 运行迁移以验证其工作

3b. API端点

对于设计文档中的每个端点：

1. 实现路由处理器
2. 添加输入验证（验证类型、必填字段、范围）
3. 添加错误处理并返回正确的HTTP状态码
4. 使用curl或等效工具测试，验证响应格式

3c. 种子数据加载

• 实现一个种子脚本，该脚本：
• 清除现有数据（用于幂等重新播种）
• 按正确的依赖顺序插入所有种子数据
• 将资源文件复制到正确的静态服务目录
• 验证种子数据加载无误

3d. 静态文件服务

• 配置后端以服务资源文件（图像、视频等）
• 确保前端可以通过正确的URL访问它们

---

阶段 4：前端实现

在这里，视觉保真度最为重要。原型是权威参考。

4a. 全局样式和标记

在构建组件之前，建立：

• 与原型颜色匹配的颜色变量
• 与原型字体匹配的排版比例
• 与原型间距匹配的间距/尺寸系统
• 通用组件样式（按钮、卡片、输入框等）

4b. 逐页面实现

对于每张原型图像，按顺序：

1. 重新读取原型图像 — 保持页面新鲜在你的上下文中
2. 构建页面组件，精确匹配布局：

• 匹配间距和比例
• 匹配颜色和排版
• 匹配视觉层次
• 匹配内容放置

1. 连接后端API调用
2. 实现所有可见或隐含的交互：

• 页面间导航
• 表单提交
• 搜索和筛选
• 排序
• 模态框和对话框
• 加载状态
• 错误状态
• 悬停效果
• 活动/选中状态

4c. 资源集成

• 将所有资源从 /workspace/resources/ 复制到前端 assets
• 在组件中正确引用它们
• 确保图像以与原型匹配的适当尺寸渲染

4d. 响应式考虑

• 匹配原型中显示的视口宽度
• 如果原型显示移动端视图，则实现响应式断点

---

阶段 5：视觉验证循环

这个阶段是区分良好实现与优秀实现的关键。

对每个页面重复此循环。

5a. 将页面渲染为屏幕截图

使用Playwright捕获运行中的应用：

python ${SKILL_DIR}/scripts/render_page.py \
  --url "http://localhost:3000/page-path" \
  --output "/workspace/docs/screenshots/page_name.png" \
  --width 1280

5b. 视觉比较

并排读取两个图像（原型和屏幕截图）：

1. 从 /workspace/prototypes/ 读取原型图像
2. 读取渲染的屏幕截图
3. 系统比较：

• 布局：各个部分位置正确吗？
• 颜色：颜色匹配吗？
• 排版：字体大小/粗细正确吗？
• 内容：所有原型内容都存在吗？
• 间距：外边距和内边距接近吗？
• 图像：所有图像是否渲染正确？
• 组件：所有UI组件是否都存在且正确？

5c. 修复差异

对于发现的每个差异：

1. 确定需要更改的具体CSS/组件
2. 应用修复
3. 重新渲染并重新比较

5d. 重复，直到满意

每页最多3次迭代。优先处理影响最大的差异。

---

阶段 6：集成测试

6a. API健康检查

运行API健康检查器以验证所有端点：

python ${SKILL_DIR}/scripts/check_api.py \
  --base-url "http://localhost:3000/api" \
  --endpoints-file "/workspace/docs/endpoints.json"

或使用curl手动测试每个端点：

curl -s http://localhost:3000/api/products | head -c 200

6b. 端到端流程验证

遍历PRD中定义的每个用户流程：

1. 在 http://localhost:3000 打开应用
2. 导航到每个页面
3. 测试每个交互功能
4. 验证数据从数据库加载
5. 验证表单提交正确
6. 验证搜索/筛选/排序有效

6c. 修复发现的任何问题

处理集成问题：CORS、API URL不匹配、数据格式不匹配等。

---

阶段 7：部署脚本

生成 /workspace/start.sh — 从零开始运行所有功能的单个命令。

要求

脚本必须：

1. 完全自包含 — 不依赖任何预先设置
2. 在全新的环境中工作
3. 安装所有系统依赖项（Node.js、Python、数据库等）
4. 清除任何先前状态
5. 从头设置数据库
6. 运行所有迁移
7. 加载所有种子数据
8. 构建前端（如果需要）
9. 同时启动后端和前端
10. 使应用在 http://localhost:3000 可访问

模板

#!/bin/bash
set -e

echo "=== PRD到应用：开始部署 ==="

# 1. 系统依赖
echo "[1/7] 检查系统依赖..."
# 如果缺少则安装Node.js、npm等
# 如果需要则安装数据库

# 2. 后端设置
echo "[2/7] 设置后端..."
cd /workspace/backend
npm install  # 或 pip install -r requirements.txt

# 3. 数据库初始化
echo "[3/7] 初始化数据库..."
# 删除现有数据库/重置
# 运行迁移
# 加载种子数据

# 4. 前端设置
echo "[4/7] 设置前端..."
cd /workspace/frontend
npm install

# 5. 复制资源
echo "[5/7] 复制资源文件..."
# cp -r /workspace/resources/* /workspace/frontend/public/assets/

# 6. 启动后端
echo "[6/7] 启动后端服务器..."
cd /workspace/backend
npm run dev &   # 或等效命令
BACKEND_PID=$!

# 7. 启动前端
echo "[7/7] 启动前端..."
cd /workspace/frontend
PORT=3000 npm run dev &
FRONTEND_PID=$!

echo ""
echo "=== 应用程序运行在 http://localhost:3000 ==="
echo "后端PID: $BACKEND_PID"
echo "前端PID: $FRONTEND_PID"
echo "停止命令: kill $BACKEND_PID $FRONTEND_PID"

wait

验证

生成start.sh后：

1. chmod +x /workspace/start.sh
2. 运行：bash /workspace/start.sh
3. 等待启动
4. 验证 http://localhost:3000 响应
5. 抽查几个API端点
6. 修复任何启动问题

---

阶段 8：文档

8a. 软件设计文档（/workspace/docs/design.md）

已在阶段1创建 — 根据实现过程中的任何更改进行更新：

• 最终系统架构
• 最终数据模型（包含开发过程中添加的任何字段）
• 技术栈
• 部署架构
• API参考

8b. README（/workspace/README.md）

# [项目名称]

## 概述
[来自PRD产品概述]

## 技术栈
- 前端：...
- 后端：...
- 数据库：...

## 快速开始
\`\`\`bash
bash start.sh
\`\`\`
然后访问 http://localhost:3000

## 项目结构
[目录树]

## 数据库
[模式概述，如何重新播种]

## API参考
[关键端点]

---

交付物检查清单

在声明完成之前，验证每一项：

• [ ] 所有PRD功能已实现 — 未跳过任何功能
• [ ] 所有原型页面已构建 — 未合并或省略任何页面
• [ ] 与原型视觉匹配 — 通过截图比较验证
• [ ] 所有资源文件在原型中出现的位置都已使用
• [ ] 种子数据与原型内容精确匹配
• [ ] 所有API端点正常工作并返回正确数据
• [ ] 所有交互元素功能正常（表单、搜索、筛选、模态框、导航）
• [ ] bash /workspace/start.sh 在干净状态下工作
• [ ] 应用可在 http://localhost:3000 访问
• [ ] 设计文档完整
• [ ] 包含部署说明的README

---

关键原则

1. 原型是真理 — 当PRD文本和原型图像冲突时，原型在视觉/布局决策中胜出。

1. 数据无捷径 — 原型中可见的每一条内容都必须来自数据库经由API。前端组件中不得硬编码数据。

1. 完整实现 — 每个页面、每个功能、每个交互。不要跳过“次要”功能。不要将单独的页面合并为一个。

1. 资源必须使用 — 如果原型显示了一个图像，并且在 /workspace/resources/ 中存在匹配的文件，则使用该文件。不要使用占位符URL替代。

1. 可重现性 — start.sh 必须从绝对零开始工作。如果需要Node 18+，它会安装Node 18+。如果需要PostgreSQL，它会设置PostgreSQL。

1. 验证，不要假设 — 使用视觉验证循环（阶段5）实际比较你的输出与原型。使用API检查验证端点。运行start.sh验证部署。