glmv-prd-to-app

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

语言：使用与用户相同的语言进行回复。代码注释也应使用相同语言。

根据 PRD、原型和资源构建完整且已部署的 Web 应用。 最终结果必须能够通过单条命令 bash /workspace/start.sh 完整复现。

---

阶段 0：材料发现与分析

在进行其他工作之前，先了解你要处理的内容。

0a. 找出所有输入材料

/workspace/prd.md              ← Product requirement document
/workspace/prototypes/*.jpg    ← UI prototype images (the visual truth)
/workspace/resources/**/*      ← Images, videos, icons, and other assets

如果材料位于其他位置，请相应调整。完整阅读 PRD。

0b. 深入分析原型

对于每张原型图片：

1. 使用 Read 工具读取每张图片——你具备多模态能力，请直接查看图片。

2. 对每张图片记录：

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

3. 绘制一张页面地图，展示原型页面之间的导航流程。

0c. 资源清单

列出 /workspace/resources/ 中的所有文件，并标明每个文件在原型中的对应位置。 最终应用必须使用每个相关资源文件。

---

阶段 1：系统设计文档

在 /workspace/docs/design.md 中编写全面的设计文档。

1a. 数据模型

对于每个实体，指定：

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

示例：

products table:
  id          SERIAL PRIMARY KEY
  name        VARCHAR(200) NOT NULL    ← from product card title
  price       DECIMAL(10,2) NOT NULL   ← from product card price label
  image_url   TEXT NOT NULL             ← from product card image
  category_id INTEGER REFERENCES categories(id) ← from category filter
  ...

1b. API 设计

为每项页面交互定义一个 API 端点：

• 方法 + 路径
• 请求参数/请求体架构
• 响应架构及示例
• 触发此 API 的原型交互
• 错误响应

1c. 前端架构

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

1d. 技术栈

根据 PRD 的复杂度进行选择。建议的默认方案：

层	选项	适用场景
前端	React + TypeScript + Vite	SPA 的默认选择
前端	Next.js	需要 SSR/SEO 时
样式	Tailwind CSS	默认选择
后端	Node.js + Express	简单 API
后端	Python + FastAPI	PRD 提及 Python 时
数据库	SQLite	简单应用，少于 10 张表
数据库	PostgreSQL	复杂应用、存在关系时
ORM	Prisma（Node）/ SQLAlchemy（Python）	与后端匹配

说明所选方案及理由。

1e. 目录结构

/workspace/
├── frontend/          ← or client/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/   ← API client
│   │   ├── types/
│   │   └── assets/     ← copied from /workspace/resources
│   └── ...
├── backend/           ← or server/
│   ├── src/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── controllers/
│   │   ├── middleware/
│   │   └── seed/
│   └── ...
├── docs/
│   ├── design.md
│   └── README.md
├── start.sh
└── prd.md

---

阶段 2：生成种子数据

种子数据至关重要——它能让应用从首次启动起就显得真实。

规则

1. 从原型中提取内容：原型图片中的每段可见文本、图像和数字都必须出现在种子数据中。重新查看每张原型图片，并转录其中的内容。

2. 完整覆盖：

   • 每个列表和表格的项目数量必须与原型中显示的完全一致
   • 每张卡片的内容必须与原型相符
   • 每个下拉菜单的选项必须与原型相符
   • 导航项必须与原型导航相符
   • 统计数据和计数必须与原型中的数字相符

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

4. 不使用占位内容：不能使用“Lorem ipsum”、“Test Item 1”或 placeholder.com 图像。

5. 支持所有状态：包含能按 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. 构建与布局完全相符的页面组件：
   • 匹配间距和比例
   • 匹配颜色和字体排印
   • 匹配视觉层级
   • 匹配内容位置
3. 连接后端 API 调用
4. 实现所有可见或隐含的交互：
   • 页面间导航
   • 表单提交
   • 搜索和筛选
   • 排序
   • 模态框和对话框
   • 加载状态
   • 错误状态
   • 悬停效果
   • 激活/选中状态

4c. 资源集成

• 将 /workspace/resources/ 中的所有资源复制到前端资源目录
• 在组件中正确引用这些资源
• 确保图像以与原型相符的尺寸呈现

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、DB 等）
4. 清理任何之前的状态
5. 从头设置数据库
6. 运行所有迁移
7. 加载所有种子数据
8. 构建前端（如有需要）
9. 启动后端和前端
10. 使应用可通过 http://localhost:3000 访问

模板

#!/bin/bash
set -e

echo "=== PRD-to-App: Starting deployment ==="

# 1. System dependencies
echo "[1/7] Checking system dependencies..."
# Install Node.js, npm, etc. if missing
# Install database if needed

# 2. Backend setup
echo "[2/7] Setting up backend..."
cd /workspace/backend
npm install  # or pip install -r requirements.txt

# 3. Database initialization
echo "[3/7] Initializing database..."
# Drop existing DB / reset
# Run migrations
# Load seed data

# 4. Frontend setup
echo "[4/7] Setting up frontend..."
cd /workspace/frontend
npm install

# 5. Copy resources
echo "[5/7] Copying resource files..."
# cp -r /workspace/resources/* /workspace/frontend/public/assets/

# 6. Start backend
echo "[6/7] Starting backend server..."
cd /workspace/backend
npm run dev &   # or equivalent
BACKEND_PID=$!

# 7. Start frontend
echo "[7/7] Starting frontend..."
cd /workspace/frontend
PORT=3000 npm run dev &
FRONTEND_PID=$!

echo ""
echo "=== Application is running at http://localhost:3000 ==="
echo "Backend PID: $BACKEND_PID"
echo "Frontend PID: $FRONTEND_PID"
echo "To stop: 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）

# [Project Name]

## Overview
[From PRD product overview]

## Technology Stack
- Frontend: ...
- Backend: ...
- Database: ...

## Quick Start
\`\`\`bash
bash start.sh
\`\`\`
Then visit http://localhost:3000

## Project Structure
[Directory tree]

## Database
[Schema overview, how to re-seed]

## API Reference
[Key endpoints]

---

交付物检查清单

宣布完成前，请确认每一项：

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

---

核心原则

1. 以原型为准——当 PRD 文本与原型图冲突时，视觉和布局决策以原型为准。

2. 数据不走捷径——原型中显示的所有内容都必须通过 API 从数据库获取。前端组件中不得硬编码数据。

3. 完整实现——每个页面、每项功能、每种交互都要实现。不要跳过“次要”功能。不要将不同页面合并为一个页面。

4. 必须使用资源——如果原型显示了图片，且 /workspace/resources/ 中存在匹配文件，就使用该文件。不要用占位 URL 替代。

5. 确保可复现——start.sh 必须能够从绝对零环境开始运行。如果需要 Node 18+，就安装 Node 18+。如果需要 PostgreSQL，就配置 PostgreSQL。

6. 验证，而非假设——使用视觉验证循环（Phase 5），实际对照原型检查输出。使用 API 检查验证端点。运行 start.sh 验证部署。