msh-system/msh_single_uniapp/pages/ai-generate/README.md

# AI生成图片功能模块 - 页面文档

## 📁 目录结构

```
pages/ai-generate/
├── index.vue          # 主生成页面（配置和输入）
├── result.vue         # 结果展示页面
├── inspiration.vue    # 灵感广场页面
├── history.vue        # 历史记录页面
└── README.md          # 说明文档
```

## 📄 页面说明

### 1. index.vue - 主生成页面

**功能描述：**
AI图片生成的主界面，用户可以配置生成参数并提交生成请求。

**主要功能模块：**
- ✅ 参考图上传（最多3张）
- ✅ 提示词输入（文本/语音）,
  腾讯云语音识别API文档：https://cloud.tencent.com/document/product/1093/35637
  API SecretId: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
- ✅ AI模型选择（4.0 / 3.1 / 3.0 / 2.1 / 2.0 PRO）
- ✅ 生成比例选择（9:16 / 3:4 / 2:3 / 1:1 / 3:2）
- ✅ 图片质量选择（2K / 4K）
- ✅ 联想词助手开关
- ✅ 生成类型切换（图片/视频）

**页面路由：**
```
/pages/ai-generate/index
```

**跳转示例：**
```javascript
// 基础跳转
uni.navigateTo({
  url: '/pages/ai-generate/index'
});

// 带模板ID跳转（从灵感广场）
uni.navigateTo({
  url: '/pages/ai-generate/index?templateId=123'
});

// 带草稿ID跳转（继续编辑）
uni.navigateTo({
  url: '/pages/ai-generate/index?draftId=456'
});
```

**UI特点：**
- 深色主题（渐变背景：#000000 → #1a1a1a）
- 毛玻璃效果（backdrop-filter: blur）
- 圆角卡片设计（16px border-radius）
- 主题色：亮绿色（#42ca4d）

---

### 2. result.vue - 结果展示页面

**功能描述：**
展示AI生成的图片结果，支持预览、下载、分享等操作。

**主要功能模块：**
- ✅ 生成进度显示（生成中状态）
- ✅ 2x2宫格图片展示
- ✅ 图片预览（Swiper全屏预览）
- ✅ 生成信息展示（提示词、参数）
- ✅ 重新编辑
- ✅ 再次生成
- ✅ 下载保存
- ✅ 分享功能
- ✅ 应用到商品

**页面路由：**
```
/pages/ai-generate/result
```

**跳转示例：**
```javascript
// 新生成跳转（显示生成动画）
uni.navigateTo({
  url: '/pages/ai-generate/result?generate=true'
});

// 查看历史记录
uni.navigateTo({
  url: '/pages/ai-generate/result?historyId=123'
});
```

**UI特点：**
- 宫格布局（2列，gap: 12px）
- 图片标签（模型版本、比例）
- 加载动画（旋转spinner）
- 底部固定操作栏

---

### 3. inspiration.vue - 灵感广场页面

**功能描述：**
展示AI创作灵感作品，用户可以浏览、收藏、使用模板。

**主要功能模块：**
- ✅ 分类标签切换
- ✅ 瀑布流布局
- ✅ 作品卡片展示
- ✅ 点赞统计
- ✅ 一键使用模板
- ✅ 下拉刷新
- ✅ 上拉加载更多
- ✅ 底部Tab导航

**页面路由：**
```
/pages/ai-generate/inspiration
```

**跳转示例：**
```javascript
// 直接跳转
uni.navigateTo({
  url: '/pages/ai-generate/inspiration'
});

// 切换到指定分类
uni.navigateTo({
  url: '/pages/ai-generate/inspiration?category=banner'
});
```

**UI特点：**
- 瀑布流布局（2列自适应高度）
- 固定顶部导航（带分类标签横滑）
- 固定底部Tab栏
- 作品卡片圆角（16px）
- 懒加载图片

**分类列表：**
- 🔥 热门玩法
- ✨ 视频特效
- 📷 人像写真
- 商品海报
- 活动Banner
- 节日主题

---

### 4. history.vue - 历史记录页面

**功能描述：**
展示用户的AI生成历史记录，支持查看、管理、再次生成。

**主要功能模块：**
- ✅ Tab筛选（全部/已完成/草稿）
- ✅ 历史列表展示
- ✅ 生成状态显示
- ✅ 查看详情
- ✅ 再次生成
- ✅ 下载保存
- ✅ 分享
- ✅ 删除记录
- ✅ 清空历史
- ✅ 空状态展示

**页面路由：**
```
/pages/ai-generate/history
```

**跳转示例：**
```javascript
uni.navigateTo({
  url: '/pages/ai-generate/history'
});
```

**UI特点：**
- 列表项布局（左图右文）
- 状态标识（生成中/失败/草稿）
- 进度条显示（生成中状态）
- 操作菜单（底部弹窗）
- 空状态引导

**记录状态：**
- ⏳ `processing` - 生成中
- ✅ `completed` - 已完成
- ❌ `failed` - 失败
- 📝 `draft` - 草稿

---

## 🎨 UI设计规范

### 色彩系统

| 用途 | 颜色值 | 说明 |
|------|--------|------|
| 主题色 | #42ca4d | 亮绿色，用于按钮、高亮 |
| 背景渐变起 | #000000 | 纯黑色 |
| 背景渐变止 | #1a1a1a | 深灰色 |
| 卡片背景 | rgba(26, 31, 46, 0.6) | 半透明深色 |
| 文字主色 | #ffffff | 白色 |
| 文字次色 | #8f9bb3 | 灰蓝色 |
| 文字辅助 | #6b7589 | 暗灰色 |
| 边框色 | rgba(255, 255, 255, 0.05) | 半透明白色 |

### 圆角规范

| 元素 | 圆角值 |
|------|--------|
| 大卡片 | 16px |
| 中卡片 | 12px |
| 小卡片 | 8px |
| 按钮 | 12px |
| 圆形按钮 | 50% |

### 间距规范

| 类型 | 间距值 |
|------|--------|
| 页面边距 | 16px |
| 卡片间距 | 12px |
| 元素间距 | 8px |
| 小间距 | 4px |

### 字体规范

| 用途 | 字号 | 字重 |
|------|------|------|
| 标题 | 17-20px | 600 |
| 正文 | 14-15px | 400 |
| 辅助文字 | 12-13px | 400 |
| 小文字 | 10-11px | 400 |

---

## 🔧 技术实现

### 依赖组件

本模块使用uni-app原生组件，无需额外依赖：

- `<scroll-view>` - 滚动容器
- `<swiper>` - 轮播图（用于图片预览）
- `<textarea>` - 多行文本输入
- `<switch>` - 开关
- `<image>` - 图片显示

### 核心功能实现

#### 1. 参考图上传

```javascript
// 选择图片
uni.chooseImage({
  count: 3 - this.referenceImages.length,
  sizeType: ['compressed'],
  sourceType: ['album', 'camera'],
  success: (res) => {
    this.referenceImages.push(...res.tempFilePaths);
  }
});
```

#### 2. 语音输入

```javascript
// 开始录音（需要调用实际的语音识别API）
startVoiceInput() {
  this.isRecording = true;
  // TODO: 调用语音识别API
  uni.showToast({
    title: '钟意啦~',
    icon: 'none'
  });
}
```

#### 3. 瀑布流布局

```javascript
// 分配数据到左右列
distributeData(newData) {
  newData.forEach(item => {
    if (this.leftColumnData.length <= this.rightColumnData.length) {
      this.leftColumnData.push(item);
    } else {
      this.rightColumnData.push(item);
    }
  });
}
```

#### 4. 图片预览

```javascript
// 全屏预览（使用Swiper）
previewImage(index) {
  this.currentPreviewIndex = index;
  this.showPreview = true;
}
```

---

## 🔌 API接口集成点

以下是需要对接的API接口列表（当前为TODO状态）：




### 生成相关

```javascript
// 1. 提交生成任务
POST /api/ai/image/generate
Request: {
  prompt, referenceImages, model, aspectRatio, quality, count
}

// 2. 查询生成状态
GET /api/ai/image/status/{taskId}

// 3. 上传参考图
POST /api/upload/image
```

### 历史记录

```javascript
// 4. 获取历史列表
GET /api/ai/history/list?page=1&limit=20&status=all

// 5. 删除历史记录
DELETE /api/ai/history/{id}

// 6. 保存草稿
POST /api/ai/draft/save
```

### 灵感广场

```javascript
// 7. 获取灵感作品列表
GET /api/ai/inspiration/list?category=hot&page=1

// 8. 获取作品详情
GET /api/ai/inspiration/detail/{id}

// 9. 点赞作品
POST /api/ai/inspiration/like/{id}
```

### 其他

```javascript
// 10. 语音识别
POST /api/voice/recognize

// 11. 图片下载
GET /api/ai/image/download/{id}

// 12. 分享生成
POST /api/share/generate
```

---

## 📱 页面路由配置

需要在 `pages.json` 中添加以下配置：

```json
{
  "pages": [
    {
      "path": "pages/ai-generate/index",
      "style": {
        "navigationBarTitleText": "AI图片生成",
        "navigationStyle": "custom"
      }
    },
    {
      "path": "pages/ai-generate/result",
      "style": {
        "navigationBarTitleText": "生成结果",
        "navigationStyle": "custom"
      }
    },
    {
      "path": "pages/ai-generate/inspiration",
      "style": {
        "navigationBarTitleText": "灵感广场",
        "navigationStyle": "custom"
      }
    },
    {
      "path": "pages/ai-generate/history",
      "style": {
        "navigationBarTitleText": "历史创作",
        "navigationStyle": "custom"
      }
    }
  ]
}
```

---

## 🎯 使用流程

### 标准生成流程

```
1. 用户进入生成页面（index.vue）
   ↓
2. [可选] 上传参考图
   ↓
3. 输入提示词（文本或语音）
   ↓
4. 选择模型、比例、质量
   ↓
5. 点击"生成"按钮
   ↓
6. 跳转到结果页（result.vue）
   ↓
7. 显示生成进度
   ↓
8. 生成完成，展示结果
   ↓
9. 下载/分享/应用
```

### 模板快速生成

```
1. 用户进入灵感广场（inspiration.vue）
   ↓
2. 浏览作品
   ↓
3. 点击"一键替换"
   ↓
4. 自动跳转到生成页（index.vue）
   ↓
5. 自动填充模板参数
   ↓
6. [可选] 微调修改
   ↓
7. 生成图片
```

### 历史记录查看

```
1. 用户进入历史记录（history.vue）
   ↓
2. 查看历史列表
   ↓
3. 点击记录
   ↓
4. 跳转到结果页查看详情
   ↓
5. [可选] 再次生成/下载/分享
```

---

## ⚠️ 注意事项

### 1. 图片处理

- 参考图上传前建议压缩（使用 `sizeType: ['compressed']`）
- 图片预览使用懒加载（`lazy-load`）
- 大图使用缩略图优先显示

### 2. 性能优化

- 瀑布流使用虚拟列表（数据量大时）
- 图片使用CDN加速
- 接口请求添加防抖

### 3. 兼容性

- 所有页面使用 `navigationStyle: "custom"` 自定义导航栏
- 考虑刘海屏适配（使用 `statusBarHeight`）
- 底部安全区适配（`padding-bottom: env(safe-area-inset-bottom)`）

### 4. 待完成功能

- [x] API接口对接（已完成）
- [x] 语音识别集成（已完成 - 腾讯云ASR）
- [ ] 图片下载功能
- [ ] 分享功能
- [ ] 图片编辑功能
- [ ] 批量操作

---

## 语音识别API接口对接 ✅

### 实现状态
**已完成对接**，使用腾讯云语音识别服务（ASR）。

### 功能说明
用户点击麦克风按钮录音后，系统会：
1. 上传录音文件到服务器
2. 创建语音识别任务
3. 轮询查询识别结果（最多30次，每次间隔2秒）
4. 将识别文本自动填充到提示词输入框

### 技术实现

#### API接口封装
在 `utils/api.js` 中已添加：
- `createAsrTask()` - 创建语音识别任务
- `queryAsrStatus()` - 查询识别任务状态

#### 核心方法
在 `pages/ai-generate/index.vue` 中已实现：
- `recognizeSpeech()` - 主识别流程
- `pollAsrResult()` - 轮询查询结果
- `parseAsrResult()` - 解析识别文本

### 使用示例

```javascript
// 开始录音
startVoiceInput() {
  // 检查权限并开始录音
  this.recorderManager.start({
    duration: 60000,
    sampleRate: 16000,
    numberOfChannels: 1,
    format: 'mp3'
  });
}

// 停止录音并识别
async stopVoiceInput() {
  this.recorderManager.stop();
  // 录音结束后自动调用 handleRecordResult
  // 然后调用 recognizeSpeech 进行识别
}
```

### API接口详情

#### 1.创建录音文件识别任务
**接口地址：** https://jxz.uj345.cc/models/api/tencent/asr/create-task

**请求方法：** POST

**请求参数：**
```json
{
  "url": "https://jxz.uj345.cc/static/images/xhs-wechat.mp3",
  "engineModelType": "16k_zh",
  "channelNum": 1,
  "resTextFormat": 0,
  "sourceType": 0,
  "filterDirty": false,
  "filterModal": false,
  "convertNumMode": false,
  "wordInfo": false
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "13473617411",
    "status": 0,
    "statusStr": "等待处理",
    "result": null,
    "audioDuration": null,
    "errorCode": 0,
    "errorMsg": "成功",
    "resultDetail": null,
    "requestId": "07ef98e3-8238-4cb8-8d81-b807af3b3bb8"
  }
}

#### 2.查询语音识别任务状态
**接口地址：** https://jxz.uj345.cc/models/api/tencent/asr/query-status/{taskId}

**请求方法：** GET

**路径参数：**
- `taskId` - 任务ID（从创建任务接口返回）

**请求示例：**
```
GET https://jxz.uj345.cc/models/api/tencent/asr/query-status/13473617411
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "13473617411",
    "status": 2,
    "statusStr": "识别成功",
    "result": "[0:0.000,0:11.580]  兄弟们，全自动小红书创作智能体来了，小金帮我找一下小红书上关于常州老房翻新的最新爆款笔记。\n[0:29.600,0:38.160]  帮我把第八条雨后森林的笔记改写一下。\n[0:48.720,0:50.780]  好的，帮我发布一下。\n[1:3.800,1:8.260]  AI智能体控制微信聊天机器人。\n[1:32.440,1:41.929]  老板们安排10个AI智能体员工给你做牛马，每天帮你谈单，做自媒体账号，你可以找客户喝茶啦。\n",
    "audioDuration": 101.92981,
    "errorCode": 0,
    "errorMsg": "",
    "resultDetail": null
  }
}
```

### 状态码说明

| 状态码 | 说明 |
|--------|------|
| 0 | 等待处理 |
| 1 | 处理中 |
| 2 | 识别成功 |
| 3 | 识别失败 |

### 识别流程说明

```
用户点击麦克风
    ↓
开始录音（最长60秒）
    ↓
用户点击停止
    ↓
上传录音文件到服务器
    ↓
创建ASR识别任务
    ↓
轮询查询任务状态（每2秒查询一次，最多30次）
    ↓
状态 = 2（识别成功）
    ↓
解析识别文本（去除时间戳）
    ↓
自动填充到提示词输入框
```

### 注意事项

1. **录音权限**：首次使用需要用户授权录音权限
2. **录音格式**：MP3格式，采样率16000Hz，单声道
3. **录音时长**：最短1秒，最长60秒
4. **识别超时**：最多等待60秒（30次 × 2秒）
5. **网络要求**：需要稳定的网络连接
6. **平台支持**：
   - ✅ 微信小程序
   - ✅ APP
   - ❌ H5（浏览器限制）

### 错误处理

| 错误 | 说明 | 处理方式 |
|------|------|----------|
| 录音时间太短 | 录音时长 < 1秒 | 提示用户重新录音 |
| 上传失败 | 网络异常 | 提示用户检查网络 |
| 识别超时 | 60秒内未完成 | 提示用户重试 |
| 识别失败 | 音频质量问题 | 建议在安静环境录音 |
| 权限拒绝 | 用户未授权 | 引导用户开启权限 |

---

## 📦 静态资源

需要准备的图片资源：

```
static/images/
├── model-4.0.png        # AI模型4.0图标
├── model-3.1.png        # AI模型3.1图标
├── model-3.0.png        # AI模型3.0图标
├── model-2.1.png        # AI模型2.1图标
├── model-2.0.png        # AI模型2.0图标
├── avatar-default.png   # 默认头像
├── empty-history.png    # 历史记录空状态
└── demo-result-*.jpg    # 示例结果图（用于演示）
```

---

## 🚀 快速开始

1. 将4个页面文件放入 `pages/ai-generate/` 目录
2. 在 `pages.json` 中添加路由配置
3. 准备静态资源图片
4. 配置图标字体（iconfont）
5. 运行项目查看效果

```bash
# H5
npm run dev:h5

# 微信小程序
npm run dev:mp-weixin

# App
在HBuilderX中运行
```

---

## 📞 联系方式

如有问题，请联系项目负责人。

---

**最后更新：** 2025年11月5日
**版本：** v1.1 - 语音识别API已对接完成