# AI Vision功能故障排查清单

## ✅ 问题排查步骤（按顺序执行）

### 第1步：确认图片上传成功并创建记录

**预期控制台日志**：
```
📤 准备上传文件: test.jpg, 大小: 2.5MB
📂 上传路径: ai-design-analysis/[项目ID]
上传进度: 100%
✅ 文件上传成功: https://file-cloud.fmode.cn/.../test.jpg
💾 ProjectFile记录已创建: [记录ID]
✅ 已上传1个文件
```

**如果缺少"ProjectFile记录已创建"**：
- [ ] 检查Parse服务器连接状态
- [ ] 确认项目ID有效（`console.log('项目ID:', this.projectId)`）
- [ ] 查看是否有"创建ProjectFile记录失败"错误

### 第2步：手动验证图片URL可访问

**操作步骤**：
1. [ ] 从控制台复制图片URL（完整的https://...）
2. [ ] 打开浏览器新标签页/隐身模式
3. [ ] 粘贴URL并访问
4. [ ] 应该直接看到图片（无需登录）

**如果无法访问**：
```
问题：图片URL需要身份验证或CORS限制
解决：
1. 检查OBS/存储服务的访问控制设置
2. 设置图片为公开访问
3. 配置CORS允许跨域访问
```

### 第3步：验证AI调用参数

**预期控制台日志**：
```
🤖 调用豆包1.6模型...
📸 原始图片URL: ["https://file-cloud.fmode.cn/.../test.jpg"]
📸 编码后URL: ["https://file-cloud.fmode.cn/.../%E6%B5%8B%E8%AF%95.jpg"]
📸 图片数量: 1
🔍 开始测试图片URL可访问性...
✅ 图片1可访问: https://...
🚀 开始调用completionJSON进行vision分析...
```

**检查要点**：
- [ ] 图片URL数组不为空
- [ ] URL不是blob://开头的本地地址
- [ ] URL是完整的HTTP/HTTPS地址
- [ ] "图片可访问"测试通过

### 第4步：分析AI返回内容

#### 成功案例
```
✅ AI分析完成，原始内容长度: 2341
📝 AI返回内容预览: 一、空间定位与场景属性

这是一个现代法式风格的客餐厅一体化空间，面积约40-50平米...
```

**特征**：
- 内容长度>1000字符
- 包含具体的空间描述
- 提到了实际的设计元素（颜色、材质、布局等）

#### 失败案例
```
❌ AI无法访问图片！
🔍 AI返回的完整内容: （注：由于未接收到实际图片内容...
🔍 图片URL列表: [...]
```

**特征**：
- 包含"未接收到"、"未获取到"、"缺少核心视觉素材"等关键词
- 内容是模板化的建议
- 没有具体的设计细节

## 🔧 常见问题及解决方案

### 问题1：AI返回"由于未接收到实际图片内容"

**可能原因A**：图片URL需要身份验证
```
✅ 解决方案：
1. 联系运维人员配置OBS/存储服务
2. 设置图片bucket为公开读取
3. 或配置签名URL（有效期24小时）
```

**可能原因B**：completionJSON不支持URL方式传图
```
✅ 解决方案：改用base64格式

// 在design-analysis-ai.service.ts中添加
async function urlToBase64(url: string): Promise<string> {
  const response = await fetch(url);
  const blob = await response.blob();
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onloadend = () => {
      const base64 = (reader.result as string);
      resolve(base64);
    };
    reader.onerror = reject;
    reader.readAsDataURL(blob);
  });
}

// 修改analyzeReferenceImages方法
const base64Images = await Promise.all(
  encodedImages.map(url => urlToBase64(url))
);

const result = await completionJSON(
  prompt,
  '',
  undefined,
  2,
  {
    model: this.AI_MODEL,
    vision: true,
    images: base64Images, // 使用base64
    max_tokens: 8000
  }
);
```

**可能原因C**：图片上传后需要等待CDN同步
```
✅ 解决方案：添加延迟

// 在上传成功后等待3秒
console.log('⏳ 等待图片URL生效...');
await new Promise(resolve => setTimeout(resolve, 3000));
console.log('✅ 继续执行');
```

**可能原因D**：AI模型不支持vision
```
✅ 解决方案：
1. 确认fmode-1.6-cn模型支持多模态
2. 尝试其他模型（如gpt-4-vision-preview）
3. 联系fmode-ng技术支持确认
```

### 问题2：图片上传返回631错误

**原因**：存储配额已满或权限不足

```
✅ 解决方案：
1. 检查存储配额：联系管理员查看OBS使用情况
2. 检查项目ID：确认this.projectId有效
3. 检查权限：确认当前用户有上传权限
4. 临时方案：使用小图片测试(<1MB)
```

### 问题3：图片URL无效（blob://...）

**原因**：上传失败，只获取到本地预览URL

```
✅ 解决方案：
1. 检查上传日志，查看错误信息
2. 确认文件格式支持（JPG/PNG推荐）
3. 减小文件大小（<10MB）
4. 重新上传
```

## 📊 完整测试流程

### 测试1：最小可行性测试

```
目的：验证vision功能基本可用

步骤：
1. 准备一张小图片（<1MB，JPG格式，纯英文文件名）
   例如：test.jpg
2. 上传图片
3. 查看控制台日志
4. 点击"开始分析"
5. 等待AI返回结果

预期：
- 上传成功，创建ProjectFile记录
- 图片URL可访问性测试通过
- AI返回具体的分析内容（非模板）

如果失败：
- 记录完整的控制台日志
- 截图AI返回的内容
- 手动访问图片URL，截图结果
```

### 测试2：中文文件名测试

```
目的：验证URL编码是否正常

步骤：
1. 准备一张中文文件名的图片
   例如：客厅设计.jpg
2. 上传并分析
3. 检查编码后的URL

预期：
- 原始URL: .../客厅设计.jpg
- 编码URL: .../%E5%AE%A2%E5%8E%85%E8%AE%BE%E8%AE%A1.jpg
- AI正常分析
```

### 测试3：多张图片测试

```
目的：验证多图片同时分析

步骤：
1. 一次上传3张图片
2. 点击"开始分析"

预期：
- 所有图片URL都有效
- AI综合分析多张图片内容
```

### 测试4：多轮对话测试

```
目的：验证对话历史传递

步骤：
1. 上传并分析第一张图片
2. 在对话框输入问题："能详细说明材质的选择吗？"
3. 查看AI回复
4. 继续追问

预期：
- AI能理解上下文
- 回复与之前分析相关
- 不重复分析图片
```

## 🚨 紧急调试命令

### 命令1：查看图片URL是否可访问（在浏览器控制台执行）

```javascript
async function testImageUrl(url) {
  try {
    const response = await fetch(url, { method: 'HEAD' });
    console.log('✅ 图片可访问，状态码:', response.status);
    return true;
  } catch (error) {
    console.error('❌ 图片无法访问:', error);
    return false;
  }
}

// 使用方法
testImageUrl('https://file-cloud.fmode.cn/.../test.jpg');
```

### 命令2：手动调用completionJSON测试vision

```javascript
import { completionJSON } from 'fmode-ng/core';

async function testVision() {
  const result = await completionJSON(
    '请描述这张图片的内容',
    '',
    undefined,
    2,
    {
      model: 'fmode-1.6-cn',
      vision: true,
      images: ['https://file-cloud.fmode.cn/.../test.jpg'],
      max_tokens: 1000
    }
  );
  
  console.log('AI返回:', result);
}

testVision();
```

### 命令3：检查ProjectFile记录

```javascript
const query = new Parse.Query('ProjectFile');
query.equalTo('category', 'ai_design_reference');
query.descending('createdAt');
query.limit(10);

const files = await query.find();
console.log('最近上传的文件:', files.map(f => ({
  id: f.id,
  name: f.get('name'),
  url: f.get('url'),
  createdAt: f.get('createdAt')
})));
```

## 📞 需要提供的调试信息

如果问题无法解决，请提供以下信息：

1. **完整的控制台日志**
   - 从"准备上传文件"到"AI分析完成"的所有日志
   - 包括所有错误信息和警告

2. **图片URL测试结果**
   - 手动访问图片URL的截图
   - 是否能直接看到图片

3. **AI返回内容**
   - 完整的AI返回文本（前500字符）
   - 是否包含"未接收到"等关键词

4. **环境信息**
   - fmode-ng版本
   - 浏览器版本
   - 网络环境（是否使用代理/VPN）

5. **图片信息**
   - 文件名
   - 文件大小
   - 图片格式
   - 是否包含中文字符

---

**更新日期**: 2025-11-27  
**状态**: 🔧 等待用户测试反馈