feat(req-prototype): upload 模式改用 MCP upload_prototype 直传 COS

- 移除对本地后端(localhost:8080)的依赖
- 执行流程改为:生成 HTML → base64 编码 → mcp__ai-proj__upload_prototype
- 删除前置条件中「后端运行中」检查项
- 更新异常处理:移除 token/后端错误,新增 base64 兼容性说明

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-17 12:52:28 +09:30
parent daca19a262
commit 039a749e3e
+22 -22
View File
@@ -22,7 +22,6 @@ arguments: [REQ-ID] [upload|edit|variant] [--device desktop|mobile|tablet] [--mo
| 检查项 | 方式 | 失败处理 |
|--------|------|----------|
| 需求存在 | `mcp__ai-proj__get_requirement` | 报错:需求不存在 |
| 后端运行中(upload 模式)| `curl http://localhost:8080/api/v1/health` | 报错:后端未启动 |
| PRD 文档存在(Stitch 模式)| 找 linkRole=prd 任务 + 检查文档 | 报错:请先执行 req-prd |
## 子命令
@@ -34,29 +33,29 @@ arguments: [REQ-ID] [upload|edit|variant] [--device desktop|mobile|tablet] [--mo
**执行流程**
```
1. 获取需求信息(mcp__ai-proj__get_requirement
1. 获取需求信息(mcp__ai-proj__get_requirement,取得数字 id
2. 读取 PRD 或需求描述,提炼 UI 关键信息
3. AI 编写带完整样式的 HTML 原型文件(见设计规范)
4. 保存到 /tmp/proto_<req_id>_<timestamp>.html
5. 获取本地 JWT token(登录 API
6. 上传到后端(multipart POST
7. 确认上传成功,输出预览 URL
5. Base64 编码:base64 < /tmp/proto_<req_id>_<timestamp>.html
6. 调用 mcp__ai-proj__upload_prototype 上传(传入 requirementId + base64 content
7. 确认上传成功,输出 COS 预览 URL
```
**Step 5-6 执行方式**
```bash
# 5. 获取 token(本地开发环境)
TOKEN=$(curl -s http://localhost:8080/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"qiudl","password":"Admin@2026~"}' \
| python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["access_token"])')
# 5. Base64 编码 HTML 文件
B64=$(base64 < /tmp/proto_<req_id>_<timestamp>.html)
```
# 6. 上传 HTML 原型并关联到需求
curl -s -X POST "http://localhost:8080/api/v1/requirements/<REQ_DB_ID>/prototype" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/tmp/proto_<req_id>_<timestamp>.html;type=text/html" \
-F "version_note=<--note 的值或空>"
```
# 6. 通过 MCP 工具上传(无需本地后端)
mcp__ai-proj__upload_prototype(
requirementId = <需求数字ID>,
content = <B64 字符串>,
versionNote = <--note 的值或"初稿 v1">
)
```
**成功响应**
@@ -64,15 +63,17 @@ curl -s -X POST "http://localhost:8080/api/v1/requirements/<REQ_DB_ID>/prototype
```json
{
"success": true,
"message": "原型已上传并关联到需求 <id>version=N/A",
"data": {
"url": "/api/v1/uploads/prototypes/proto_xxx.html",
"version_note": "...",
"uploaded_at": "..."
"url": "https://ai-proj-1252326374.cos.ap-beijing.myqcloud.com/prototypes/<uuid>.html",
"versionNote": "...",
"uploadedAt": "...",
"requirementId": <id>
}
}
```
**效果**:需求详情页`/requirements/<id>``/platform/requirements/<id>`)自动出现「原型预览」卡片,iframe 加载上传的 HTML
**效果**:需求详情页自动出现「原型预览」卡片,iframe 加载 COS 上的 HTML 文件。**无需本地后端运行**
**参数**
@@ -280,11 +281,10 @@ generated_at: "<timestamp>"
| 异常 | 处理 |
|------|------|
| 后端 500 / `column prototype_urls does not exist` | 需执行数据库迁移:`psql -U <owner> -d <db> -c "ALTER TABLE requirements ADD COLUMN IF NOT EXISTS prototype_urls JSONB DEFAULT '[]';"` |
| token 获取失败(401)| 检查用户名密码,或改用生产环境 token |
| 需求 ID 不存在(404)| 确认使用数据库自增 ID,而非 display_idREQ-xxx |
| `mcp__ai-proj__upload_prototype` 返回失败 | 检查 requirementId 是否为数字 ID(非 display_id REQ-xxx |
| HTML 文件超过 5MB | 精简样式或拆分多版本上传 |
| iframe 不显示 | 检查 `prototype_urls` 字段是否非空:`mcp__ai-proj__get_requirement` 确认 |
| base64 命令失败 | macOS 用 `base64 < file`Linux 用 `base64 -w 0 < file` |
### 原型展示规则