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

语言：使用用户所用的相同语言进行响应。代码注释也须保持一致。

基于 PRD + 原型图 + 资源文件，构建一个完整且已部署的 Web 应用程序。 最终成果必须可通过单条命令 bash /workspace/start.sh 完全可复现。

阶段 0：材料发现与分析

在开始任何开发工作之前，首先需全面理解手头所拥有的材料。

0a. 定位全部输入文件

/workspace/prd.md              ← 产品需求文档（PRD）
/workspace/prototypes/*.jpg    ← UI 原型图（视觉事实依据）
/workspace/resources/**/*      ← 图片、视频、图标及其他资源文件

若材料位于其他路径，请相应调整。务必通读 PRD 全文。

0b. 深度原型图分析

对每一张原型图执行以下操作：

1. 逐张读取图像：使用 Read 工具——你具备多模态能力，请直接审视图像本身。

2. 对每张图像，记录以下信息：

   • 页面标识：该图像所代表的具体页面或视图
   • 布局结构：页眉、侧边栏、主内容区、页脚、模态框等
   • 组件清单：所有按钮、表单、卡片、表格、列表、导航元素等
   • 内容清单：所有可见文字、数字、标签、占位内容
   • 颜色提取：主色、辅色、强调色、背景色、文字色（十六进制值）
   • 排版样式：观察到的字体大小、字重、层级关系
   • 交互状态：悬停效果、激活标签页、选中项、开关状态等
   • 数据模式：填充列表/表格/卡片的数据类型与结构——这将决定种子数据的设计

3. 构建一份页面映射图，清晰展示各原型页面之间的导航流向。

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 接口：

• HTTP 方法 + 路径
• 请求参数/请求体结构
• 响应结构及示例
• 触发该 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. 从原型图中提取：原型图中所有可见文字、图片、数字，均须出现在种子数据中。请再次逐张读取原型图并转录全部内容。

2. 全覆盖原则：

   • 每个列表/表格必须包含原型图中显示的确切条目数
   • 每张卡片的内容必须与原型图完全一致
   • 每个下拉框的选项必须与原型图完全一致
   • 导航项必须与原型图完全一致
   • 统计数值/计数器必须与原型图数字完全一致

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

4. 禁止使用占位内容：不得使用 “Lorem ipsum”、不得使用 “Test Item 1”、不得使用 placeholder.com 类占位图。

5. 覆盖全部状态：需包含用于验证空状态、加载状态、错误场景等的数据，且需严格遵循 PRD 规定。

输出格式

将种子数据保存为以下任一格式：

• SQL 种子文件
• JSON 测试数据文件
• ORM 种子脚本

存放路径为 /workspace/backend/src/seed/（或等效路径）。

阶段 3：后端实现

3a. 数据库 Schema

• 为所有表创建迁移文件
• 包含完整的约束、索引、外键定义
• 运行迁移以验证其正确性

3b. API 接口实现

针对设计文档中定义的每个接口：

1. 实现路由处理器
2. 添加输入校验（类型、必填字段、数值范围等）
3. 添加错误处理逻辑，并返回恰当的 HTTP 状态码
4. 使用 curl 或等效工具测试，验证响应格式是否符合预期

3c. 种子数据加载

• 实现种子脚本，要求具备以下能力：
  • 清除已有数据（支持幂等式重播种）
  • 按依赖顺序插入全部种子数据
  • 将资源文件复制至正确的静态资源服务路径
• 验证种子数据加载过程无报错

3d. 静态文件服务

• 配置后端以提供资源文件（图片、视频等）服务
• 确保前端可通过正确 URL 访问这些资源

阶段 4：前端实现

此阶段视觉保真度最为关键。原型图是唯一权威参考。

4a. 全局样式与设计令牌

在构建组件前，先确立以下基础：

• 颜色变量：与原型图颜色完全一致
• 排版比例：与原型图所用字体大小、字重、层级完全一致
• 间距/尺寸体系：与原型图的留白、尺寸比例完全一致
• 通用组件样式：按钮、卡片、输入框等的统一风格

4b. 页面逐页实现

对每一张原型图，按顺序执行以下步骤：

1. 重新读取原型图——确保上下文始终最新
2. 精确构建页面组件，严格匹配其布局：
   • 间距与比例完全一致
   • 颜色与排版完全一致
   • 视觉层级完全一致
   • 内容位置完全一致
3. 对接后端 API 调用
4. 实现所有可见或隐含的交互行为：
   • 页面间导航
   • 表单提交
   • 搜索与筛选
   • 排序
   • 模态框与对话框
   • 加载状态
   • 错误状态
   • 悬停效果
   • 激活/选中状态

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 地址不匹配、数据格式不一致等。

阶段 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-to-App：启动部署 ==="

# 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

## 项目结构
[目录树]

## 数据库
[Schema 概览、如何重新播种]

## API 参考
[关键接口]

交付物核对清单

在宣告完成前，请逐项确认：

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

核心原则

1. 原型图为唯一真理——当 PRD 文本与原型图存在冲突时，视觉/布局决策以原型图为准。

2. 数据不得走捷径——原型图中所有可见内容，必须经由 API 从数据库获取；前端组件中严禁硬编码数据。

3. 完整实现——每个页面、每个功能、每个交互行为都必须实现。不可跳过所谓“次要”功能，不可将多个独立页面强行合并。

4. 资源文件必须使用——若原型图中展示了某张图片，且 /workspace/resources/ 中存在对应文件，则必须使用该文件，不得替换为占位图链接。

5. 可复现性——start.sh 必须能从绝对零状态运行成功。若需 Node 18+，则脚本需自行安装 Node 18+；若需 PostgreSQL，则脚本需自行部署 PostgreSQL。

6. 以验证代替假设——使用视觉验证循环（阶段 5）实际比对你产出的结果与原型图；使用 API 检查工具验证接口；运行 start.sh 验证部署流程。