{
  "assignee_id": "8ddccf1d-9ed4-469e-a335-a14d0b72d025",
  "assignee_type": "agent",
  "created_at": "2026-05-23T03:29:43Z",
  "creator_id": "d1e4fe91-fb56-4c47-95d0-818d5f22b5bd",
  "creator_type": "agent",
  "description": "# 图片查看器功能 - 技术规格文档\n\n**项目**: Fetch China  \n**功能**: 订单图片查看器优化  \n**优先级**: 中  \n**预计工时**: 4-6小时\n\n---\n\n## 📋 需求概述\n\n在订单生命周期中，用户需要查看多种类型的图片（客户参考图、采购截图、质检照片等）。当前的图片显示方式不够友好，需要实现一个统一的图片查看器，支持点击放大和关闭功能。\n\n---\n\n## 🎯 功能需求\n\n### 1. 图片类型覆盖\n\n需要支持以下所有图片类型的查看：\n\n| 图片类型 | 字段名 | 上传者 | 显示位置 |\n|---------|--------|--------|---------|\n| 客户参考图 | `user_image_url` | 客户 | 订单商品详情 |\n| 采购截图 | 购买凭证 | 合伙人 | 订单详情（物流历史） |\n| 质检照片 | `qc_images[]` | 合伙人 | 订单商品详情 |\n| 打包照片 | 打包凭证 | 合伙人 | 订单详情（物流历史） |\n\n### 2. 交互需求\n\n#### 桌面端（PC/平板横屏）\n- 点击缩略图 → 全屏/大图模式显示\n- 点击图片外的空白区域 → 关闭查看器\n- 支持ESC键关闭\n- 支持左右箭头键切换图片（如果有多张）\n\n#### 移动端（手机/平板竖屏）\n- 点击缩略图 → 全屏显示\n- 再次点击图片 → 关闭查看器\n- 支持左右滑动切换图片（如果有多张）\n- 支持双指缩放\n\n### 3. 显示要求\n\n- 图片居中显示\n- 保持原始宽高比\n- 最大宽度/高度不超过视口的90%\n- 背景半透明黑色遮罩（rgba(0,0,0,0.8)）\n- 平滑的打开/关闭动画\n- 加载状态指示器\n\n---\n\n## 🎨 UI设计规范\n\n### 缩略图样式\n```css\n- 尺寸: 80px × 80px (桌面), 60px × 60px (移动)\n- 圆角: 8px\n- 边框: 1px solid #e5e7eb\n- 悬停效果: 阴影 + 轻微放大\n- 光标: pointer\n```\n\n### 查看器样式\n```css\n- 背景: rgba(0, 0, 0, 0.8)\n- 图片最大宽度: 90vw\n- 图片最大高度: 90vh\n- 关闭按钮: 右上角，白色，半透明背景\n- 图片计数: 底部居中（如 \"1 / 3\"）\n```\n\n### 动画效果\n```css\n- 打开: fade-in + scale(0.9 → 1.0), 200ms\n- 关闭: fade-out + scale(1.0 → 0.9), 200ms\n- 切换: slide, 300ms\n```\n\n---\n\n## 🛠️ 技术实现\n\n### 1. 创建通用组件\n\n**文件**: `frontend/src/components/common/ImageViewer.vue`\n\n**Props**:\n```typescript\ninterface Props {\n  images: string[]        // 图片URL数组\n  initialIndex?: number   // 初始显示的图片索引\n  show: boolean          // 是否显示查看器\n}\n```\n\n**Events**:\n```typescript\nemit('close')  // 关闭查看器\nemit('change', index: number)  // 切换图片\n```\n\n**功能**:\n- 全屏遮罩层\n- 图片预加载\n- 左右切换按钮（多图时）\n- 关闭按钮\n- 图片计数显示\n- 键盘事件监听（ESC, 左右箭头）\n- 触摸事件监听（滑动切换）\n- 点击空白区域关闭\n\n### 2. 集成到现有页面\n\n需要修改的文件：\n\n#### 客户订单详情页\n- `frontend/src/views/OrderDetail.vue`\n- 在商品卡片中的 `user_image_url` 和 `qc_images` 处集成\n\n#### 合伙人订单详情页\n- `frontend/src/views/partner/PartnerDashboard.vue` (订单详情模态框)\n- 在商品卡片和物流历史中集成\n\n#### 管理员订单详情页\n- `frontend/src/views/admin/OrderDetail.vue`\n- 在所有图片显示位置集成\n\n### 3. 使用示例\n\n```vue\n\u003ctemplate\u003e\n  \u003c!-- 缩略图 --\u003e\n  \u003cimg \n    :src=\"item.user_image_url\" \n    @click=\"openViewer([item.user_image_url])\"\n    class=\"cursor-pointer hover:shadow-lg transition-shadow\"\n  /\u003e\n\n  \u003c!-- 多张图片 --\u003e\n  \u003cdiv class=\"flex gap-2\"\u003e\n    \u003cimg \n      v-for=\"(img, idx) in item.qc_images\"\n      :key=\"idx\"\n      :src=\"img.image_url\"\n      @click=\"openViewer(item.qc_images.map(i =\u003e i.image_url), idx)\"\n      class=\"w-20 h-20 object-cover rounded-lg cursor-pointer\"\n    /\u003e\n  \u003c/div\u003e\n\n  \u003c!-- 图片查看器 --\u003e\n  \u003cImageViewer\n    :images=\"viewerImages\"\n    :initial-index=\"viewerIndex\"\n    :show=\"showViewer\"\n    @close=\"showViewer = false\"\n  /\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue'\nimport ImageViewer from '@/components/common/ImageViewer.vue'\n\nconst showViewer = ref(false)\nconst viewerImages = ref([])\nconst viewerIndex = ref(0)\n\nconst openViewer = (images, index = 0) =\u003e {\n  viewerImages.value = images\n  viewerIndex.value = index\n  showViewer.value = true\n}\n\u003c/script\u003e\n```\n\n---\n\n## 📱 响应式设计\n\n### 断点定义\n```css\n- 移动端: \u003c 768px\n- 平板: 768px - 1024px\n- 桌面: \u003e 1024px\n```\n\n### 移动端特殊处理\n- 禁用页面滚动（查看器打开时）\n- 触摸事件优化\n- 双指缩放支持\n- 更大的关闭按钮（48px × 48px）\n\n---\n\n## ✅ 验收标准\n\n### 功能测试\n- [ ] 所有图片类型都能正常打开查看器\n- [ ] 桌面端点击空白区域能关闭\n- [ ] 移动端点击图片能关闭\n- [ ] ESC键能关闭查看器\n- [ ] 多图时能正常切换\n- [ ] 图片加载状态正确显示\n- [ ] 图片保持宽高比且不超出视口\n\n### 兼容性测试\n- [ ] Chrome/Edge (最新版)\n- [ ] Firefox (最新版)\n- [ ] Safari (最新版)\n- [ ] iOS Safari (iOS 14+)\n- [ ] Android Chrome (Android 10+)\n\n### 性能测试\n- [ ] 打开/关闭动画流畅（60fps）\n- [ ] 大图加载不阻塞UI\n- [ ] 内存占用合理（查看器关闭后释放）\n\n### UI测试\n- [ ] 与现有设计风格一致\n- [ ] 动画效果自然\n- [ ] 移动端触摸体验良好\n- [ ] 暗色背景不影响可读性\n\n---\n\n## 🔍 测试场景\n\n### 场景1: 客户查看参考图\n1. 客户登录\n2. 进入订单详情页\n3. 点击商品的参考图\n4. 验证图片放大显示\n5. 点击空白处关闭\n\n### 场景2: 合伙人查看质检照片\n1. 合伙人登录\n2. 进入订单详情\n3. 点击商品的质检照片（多张）\n4. 验证能左右切换\n5. 验证图片计数显示正确\n\n### 场景3: 移动端体验\n1. 使用手机访问\n2. 打开订单详情\n3. 点击任意图片\n4. 验证全屏显示\n5. 左右滑动切换\n6. 点击图片关闭\n\n---\n\n## 📦 交付物\n\n1. **ImageViewer.vue** - 通用图片查看器组件\n2. **修改后的订单详情页** - 集成图片查看器\n3. **单元测试** - 组件功能测试\n4. **E2E测试** - 用户交互测试（可选）\n5. **使用文档** - 组件API说明\n\n---\n\n## 🚀 实施步骤\n\n### 第1步: 创建ImageViewer组件 (2小时)\n- 实现基础布局和样式\n- 实现打开/关闭逻辑\n- 实现图片切换功能\n- 添加键盘和触摸事件\n\n### 第2步: 集成到订单详情页 (1.5小时)\n- 客户订单详情页\n- 合伙人订单详情页\n- 管理员订单详情页\n\n### 第3步: 响应式优化 (1小时)\n- 移动端适配\n- 触摸事件优化\n- 性能优化\n\n### 第4步: 测试和修复 (1.5小时)\n- 功能测试\n- 兼容性测试\n- Bug修复\n\n---\n\n## 📚 参考资料\n\n### 类似实现\n- [Lightbox2](https://lokeshdhakar.com/projects/lightbox2/)\n- [PhotoSwipe](https://photoswipe.com/)\n- [Vue Easy Lightbox](https://github.com/XiongAmao/vue-easy-lightbox)\n\n### Vue 3相关\n- [Teleport](https://vuejs.org/guide/built-ins/teleport.html) - 用于渲染到body\n- [Transition](https://vuejs.org/guide/built-ins/transition.html) - 动画效果\n\n---\n\n## ⚠️ 注意事项\n\n1. **图片加载失败处理**: 显示占位图或错误提示\n2. **大图优化**: 考虑图片压缩和懒加载\n3. **无障碍访问**: 添加适当的ARIA标签\n4. **内存管理**: 查看器关闭后清理事件监听器\n5. **安全性**: 验证图片URL，防止XSS\n\n---\n\n## 🎯 成功指标\n\n- ✅ 所有订单页面的图片都能通过查看器查看\n- ✅ 桌面和移动端体验流畅\n- ✅ 无明显性能问题\n- ✅ 用户反馈积极\n\n---\n\n**准备好开始实现了吗？如有疑问请随时沟通！**",
  "due_date": null,
  "id": "f2a7d0c5-28a4-4d82-8941-0a58e9629220",
  "identifier": "FET-33",
  "metadata": {
    "pr_url": "https://github.com/martinyyang/fetch-china/pull/163"
  },
  "number": 33,
  "parent_issue_id": null,
  "position": 0,
  "priority": "medium",
  "project_id": null,
  "start_date": null,
  "status": "todo",
  "title": "订单图片查看器功能实现",
  "updated_at": "2026-05-23T05:21:32Z",
  "workspace_id": "b5fdce19-2a82-455d-b644-5b83da2b3078"
}