pda-kit-mcp-server 2.0.1

package/spec-data/camera.md

@@ -0,0 +1,622 @@
+---
+id: camera
+name: 拍照组件
+category: "媒体/Media"
+version: "1.0.0"
+source: PDAKit-业务组件
+source_url: https://mastergo.ky-tech.com.cn/goto/U10IsUP5
+source_doc_id: 103417331857122
+component_count: 2
+---
+
+# 拍照组件 Camera
+
+货物拍照组件，用于 PDA 手持终端拍摄货物图片。支持多货物类型切换拍摄、闪光灯控制、已拍缩略图预览。
+
+> **核心规则**：全屏拍照取景 + 底部工具栏。左上角示例图可点击放大，货物类型左右切换，每个类型独立计数，右上角完成按钮拍照后变绿。
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。
+> **字体**：PingFang SC。
+
+---
+
+## 组件总览
+
+| 组件 | 用途 |
+|------|------|
+| 拍照取景区 | 全屏摄像头取景画面（z-index: 0 最底层） |
+| 顶部栏 | 半透明黑底覆盖层，承载示例图 + 完成按钮 |
+| 底部工具栏 | 半透明黑底固定栏，承载类型切换 + 缩略图 + 拍摄按钮 + 闪光灯 |
+
+---
+
+## 1. 布局结构
+
+```
+┌── 480px ──────────────────────────┐
+│                                   │
+│           摄像头实时画面            │  ← .camera-view（全屏，z-index: 0）
+│                                   │
+│                                   │
+│ ┌────────────────────────────────┐ │  ← .camera-top-bar
+│ │ ┌──────┐            ┌──────┐  │ │    背景 rgba(0,0,0,0.6)
+│ │ │示例图 │            │ 完成  │  │ │    绝对定位 top:0, z-index: 2
+│ │ └──────┘            └──────┘  │ │
+│ └────────────────────────────────┘ │
+│                                   │
+├───────────────────────────────────┤
+│ ┌────────────────────────────────┐ │  ← .camera-toolbar
+│ │ 类型标签滑动区（居中滚动）      │ │    背景 rgba(0,0,0,0.6)
+│ ├────────────────────────────────┤ │    绝对定位 bottom:0, z-index: 2
+│ │ [缩略图]    [拍摄]    [闪光灯]  │ │    高度 216px
+│ └────────────────────────────────┘ │
+└───────────────────────────────────┘
+```
+
+## 2. 拍照取景区（全屏背景）
+
+| 属性 | 值 |
+|------|------|
+| 定位 | `position: absolute; top: 0; left: 0; width: 100%; height: 100%` |
+| z-index | `0`（最底层） |
+| 背景 | 摄像头实时画面 |
+| 布局 | `display: flex; justify-content: center; align-items: center` |
+
+## 3. 顶部栏
+
+| 属性 | 值 |
+|------|------|
+| 定位 | `position: absolute; top: 0; left: 0; width: 100%` |
+| 背景 | `rgba(0, 0, 0, 0.6)` |
+| 内边距 | `12px` |
+| 布局 | `display: flex; justify-content: space-between; align-items: center` |
+| z-index | `2` |
+
+### 示例图
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `68×68px`，圆角 `4px`，白色边框 `2px` |
+| 交互 | 点击弹出全屏大图预览 |
+
+### 完成按钮
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `80×48px`，圆角 `4px` |
+| 布局 | `display: flex; flex-direction: column; justify-content: center; align-items: center; padding: 12px` |
+| z-index | `1` |
+| 未拍照态 | `background: #FFFFFF`，文字 `#333333`，文字 `关闭`，点击退出相机 |
+| 已拍照态 | `background: --color-green-6`（`#03C15F`），文字 `--color-grey-1`（白色），文字 `完成`，点击保存回传数据 |
+| 文字 | 字号 `16px`，字重 `600` |
+| 交互 | 未拍照点击退出相机；已拍照点击保存数据并返回列表 |
+
+## 4. 底部工具栏
+
+| 属性 | 值 |
+|------|------|
+| 定位 | `position: absolute; bottom: 0; left: 0; width: 100%` |
+| 高度 | `216px` |
+| 背景 | `rgba(0, 0, 0, 0.6)` |
+| z-index | `2` |
+| 布局 | `display: flex; flex-direction: column` |
+
+#### 货物类型切换区
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-shrink: 0; display: flex; align-items: center; gap: 12px` |
+| 内边距 | `12px calc(240px - 70px) 0`（左右对称留白使首尾标签均可滚动至居中） |
+| 排列 | 水平滚动，`overflow-x: auto`，隐藏滚动条，`scroll-behavior: smooth` |
+| 类型标签 | 内边距 `8px 16px`，圆角 `20px`（胶囊形） |
+| 选中态 | 背景 `--color-yellow-5`（`#ffb530`），文字 `--color-black-7`（`#000000`），字重 `600` |
+| 未选中态 | 背景 `transparent`，文字 `--color-grey-1` |
+| 字体 | `16px / 22px`，PingFang SC |
+| 数量显示 | 文字后空格 + 数字徽章：`20px` 高 Black/NO.7 背景圆角胶囊，包裹 `14px` 白色文字，如 `货物类型 0` |
+| 切换手势 | 左右滑动或点击类型标签切换，切换后已选中类型自动滚动至居中 |
+
+#### 已拍缩略图
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `74×74px`，圆角 `6px` |
+| 描边 | `1px solid --color-grey-1` |
+| 位置 | 底部工具栏左侧，距左 `32px`，垂直居中 |
+| 默认态 | 无缩略图时显示虚线边框占位 |
+
+#### 拍摄按钮
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `100×100px`，圆形 |
+| 外环 | `12px solid #ffffff`（白色粗圆环） |
+| 内圆 | `60×60px`，`background: transparent`（透明镂空） |
+| 位置 | 底部工具栏水平居中 |
+| 交互 | 点击触发拍照 |
+| 动效 | 点击时缩放 0.92，`150ms` |
+
+#### 闪光灯按钮
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `72×72px` |
+| 图标 | `拍照示例图/拍照-手电筒/OFF.svg`（关闭）/ `ON.svg`（开启），填满按钮 |
+| 位置 | 底部工具栏右侧，距右 `32px`，垂直居中 |
+| 交互 | 点击切换闪光灯 ON/OFF |
+| 背景 | `rgba(51,51,51,0.8)` 黑色半透明圆形底 |
+
+---
+
+## 5. 示例图放大预览
+
+| 属性 | 值 |
+|------|------|
+| 触发 | 点击左上角示例图 |
+| 展示 | 全屏黑色遮罩（`rgba(0,0,0,0.9)`），图片居中展示，上层叠加类型名称（100px/600、50% 透明度黑色，绝对定位居中） |
+| 关闭 | 点击遮罩任意位置关闭 |
+| z-index | `950` |
+
+---
+
+## CSS 示例
+
+```css
+/* ===== 拍照取景区（全屏背景） ===== */
+.camera-view {
+  position: absolute;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  background: #1a1a1a;
+  overflow: hidden;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  z-index: 0;
+}
+
+/* ===== 顶部栏 ===== */
+.camera-top-bar {
+  position: absolute;
+  top: 0; left: 0;
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px;
+  background: rgba(0, 0, 0, 0.6);
+  z-index: 2;
+}
+
+.camera-sample {
+  width: 68px; height: 68px;
+  border-radius: 4px;
+  border: 2px solid var(--color-grey-1);
+  object-fit: cover;
+  cursor: pointer;
+  background: #333;
+  flex-shrink: 0;
+}
+
+.camera-done {
+  width: 80px;
+  height: 48px;
+  border-radius: 4px;
+  border: none;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  padding: 12px;
+  color: var(--color-grey-1);
+  font-size: 16px; font-weight: 600;
+  font-family: PingFang SC;
+  cursor: pointer;
+  z-index: 1;
+  transition: background 0.3s, opacity 0.3s;
+}
+.camera-done.inactive {
+  background: #FFFFFF;
+  color: #333333;
+  pointer-events: auto;
+}
+.camera-done.active {
+  background: var(--color-green-6);
+  color: var(--color-grey-1);
+  pointer-events: auto;
+}
+
+/* ===== 底部工具栏 ===== */
+.camera-toolbar {
+  position: absolute;
+  bottom: 0; left: 0;
+  width: 100%;
+  height: 216px;
+  background: rgba(0, 0, 0, 0.6);
+  display: flex;
+  flex-direction: column;
+  z-index: 2;
+}
+
+/* 货物类型切换区 */
+.camera-types {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px calc(240px - 70px) 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+  scroll-behavior: smooth;
+}
+.camera-types::-webkit-scrollbar { display: none; }
+
+.camera-type-tag {
+  padding: 8px 16px;
+  border-radius: 20px;
+  font-size: 16px;
+  line-height: 22px;
+  font-family: PingFang SC;
+  white-space: nowrap;
+  cursor: pointer;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  transition: background 0.2s, color 0.2s;
+  user-select: none;
+}
+.camera-type-tag.active {
+  background: var(--color-yellow-5);
+  color: var(--color-black-7);
+  font-weight: 600;
+}
+.camera-type-tag:not(.active) {
+  background: transparent;
+  color: var(--color-grey-1);
+}
+
+.camera-type-count {
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 4px;
+  border-radius: 10px;
+  background: var(--color-black-7);
+  color: var(--color-grey-1);
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+  font-family: PingFang SC;
+}
+
+/* 底部操作区 */
+.camera-actions {
+  flex: 1;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0 32px;
+}
+
+/* 已拍缩略图 */
+.camera-thumb-wrap {
+  width: 74px; height: 74px;
+  flex-shrink: 0;
+}
+.camera-thumb {
+  width: 74px; height: 74px;
+  border-radius: 6px;
+  border: 1px solid var(--color-grey-1);
+  object-fit: cover;
+  display: none;
+  cursor: pointer;
+}
+.camera-thumb-placeholder {
+  width: 74px; height: 74px;
+  border-radius: 6px;
+  border: 1px dashed rgba(255,255,255,0.3);
+}
+
+/* 拍摄按钮 */
+.camera-shutter-outer {
+  width: 100px; height: 100px;
+  border-radius: 50%;
+  border: 12px solid #ffffff;
+  display: flex; justify-content: center; align-items: center;
+  flex-shrink: 0;
+  cursor: pointer;
+  transition: transform 0.15s;
+}
+.camera-shutter-outer:active { transform: scale(0.92); }
+.camera-shutter-inner {
+  width: 60px; height: 60px;
+  border-radius: 50%;
+  background: transparent;
+}
+
+/* 闪光灯按钮 */
+.camera-flash {
+  width: 72px; height: 72px;
+  border-radius: 50%;
+  background: rgba(51,51,51,0.8);
+  display: flex; justify-content: center; align-items: center;
+  flex-shrink: 0;
+  cursor: pointer;
+  border: none;
+  padding: 0;
+  transition: background 0.2s;
+}
+.camera-flash img { width: 100%; height: 100%; }
+
+/* ===== 示例图放大遮罩 ===== */
+.camera-preview-overlay {
+  position: fixed; top: 0; left: 0;
+  width: 100vw; height: 100vh;
+  background: rgba(0,0,0,0.9);
+  z-index: 950;
+  display: none;
+  justify-content: center;
+  align-items: center;
+  cursor: pointer;
+  overflow: hidden;
+}
+.camera-preview-overlay.show { display: flex; }
+.camera-preview-overlay img {
+  max-width: 90vw;
+  max-height: 80vh;
+  object-fit: contain;
+  border-radius: 4px;
+}
+.camera-preview-title {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  font-size: 100px;
+  font-weight: 600;
+  line-height: 1;
+  color: rgba(0, 0, 0, 0.5);
+  text-align: center;
+  font-family: PingFang SC;
+  white-space: nowrap;
+  pointer-events: none;
+  z-index: 1;
+}
+
+/* 拍后闪光效果 */
+.camera-flash-effect {
+  position: absolute;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  background: #fff;
+  opacity: 0;
+  pointer-events: none;
+  z-index: 20;
+  transition: opacity 0.08s;
+}
+.camera-flash-effect.fire { opacity: 0.9; }
+```
+
+---
+
+## 资源引用说明
+
+### 示例图路径
+
+拍照组件使用的示例图统一存放在 `拍照示例图/` 目录下：
+
+```
+拍照示例图/
+├── 拍照-手电筒/
+│   ├── OFF.svg          # 闪光灯关闭图标
+│   └── ON.svg           # 闪光灯开启图标
+├── 角标.svg             # 示例图角标（photo-list 使用）
+├── 货物完整@8x.png      # 货物完整拍照示例
+├── 外包装全貌照@8x.png  # 外包装全貌拍照示例
+├── 开箱点数@8x.png      # 开箱点数拍照示例
+└── ...                  # 其他拍照类型示例图
+```
+
+**引用方式**：
+- 如果 HTML 文件在 `demos/` 目录：
+  - 示例图：`../拍照示例图/货物完整@8x.png`
+  - 闪光灯图标：`../拍照示例图/拍照-手电筒/OFF.svg`
+- 如果 HTML 文件在根目录：
+  - 示例图：`./拍照示例图/货物完整@8x.png`
+  - 闪光灯图标：`./拍照示例图/拍照-手电筒/OFF.svg`
+
+---
+
+## HTML 骨架
+
+```html
+<!-- 拍照组件完整结构示例 -->
+<!-- 假设 HTML 文件位于 demos/ 目录 -->
+
+<!-- 拍照取景区（全屏背景） -->
+<div class="camera-view" id="cameraView">
+  <!-- 摄像头画面 -->
+  <div class="camera-flash-effect" id="flashEffect"></div>
+</div>
+
+<!-- 顶部栏 -->
+<div class="camera-top-bar">
+  <img class="camera-sample" id="cameraSample"
+       src="../拍照示例图/货物完整@8x.png"
+       alt="示例图" onclick="openPreview()" />
+  <button class="camera-done inactive" id="btnDone"
+          onclick="onComplete()">关闭</button>
+</div>
+
+<!-- 底部工具栏 -->
+<div class="camera-toolbar">
+  <div class="camera-types" id="cameraTypes">
+    <!-- JS 动态渲染类型标签 -->
+  </div>
+  <div class="camera-actions">
+    <div class="camera-thumb-wrap">
+      <img class="camera-thumb" id="thumbPreview" alt="已拍" />
+      <div class="camera-thumb-placeholder" id="thumbPlaceholder"></div>
+    </div>
+    <div class="camera-shutter-outer" onclick="takePhoto()">
+      <div class="camera-shutter-inner"></div>
+    </div>
+    <button class="camera-flash" onclick="toggleFlash()">
+      <img id="flashIcon" src="../拍照示例图/拍照-手电筒/OFF.svg" alt="闪光灯" />
+    </button>
+  </div>
+</div>
+
+<!-- 示例图放大预览 -->
+<div class="camera-preview-overlay" id="previewOverlay"
+     onclick="closePreview()">
+  <p class="camera-preview-title" id="previewTitle"></p>
+  <img id="previewImage" src="" alt="预览" />
+</div>
+```
+
+---
+
+## JS 交互示例
+
+```javascript
+// 货物类型数据（支持从 URL 参数接收拍照列表传入的类型）
+const urlParams = new URLSearchParams(window.location.search);
+const typesParam = urlParams.get('types');
+const sourceEntryIndex = urlParams.get('entryIndex');
+
+// 注意：路径根据 HTML 文件位置调整
+// 如果 HTML 在 demos/ 目录，使用 ../拍照示例图/
+// 如果 HTML 在根目录，使用 ./拍照示例图/
+const allPhotoTypes = [
+  { name: '货物完整', count: 0, sample: '../拍照示例图/货物完整@8x.png' },
+  { name: '外包装全貌照', count: 0, sample: '../拍照示例图/外包装全貌照@8x.png' },
+  { name: '开箱点数', count: 0, sample: '../拍照示例图/开箱点数@8x.png' },
+  { name: '破损近景图', count: 0, sample: '../拍照示例图/破损近景图@8x.png' }
+];
+
+// 根据 URL 筛选类型（无参数默认全部）
+let photoTypes;
+if (typesParam) {
+  const typeNames = typesParam.split(',').map(s => s.trim());
+  photoTypes = allPhotoTypes.filter(t => typeNames.includes(t.name));
+  if (photoTypes.length === 0) photoTypes = allPhotoTypes;
+} else {
+  photoTypes = allPhotoTypes;
+}
+let currentTypeIndex = 0;
+let flashOn = false;
+
+// 切换货物类型
+function switchType(index) {
+  if (index === currentTypeIndex) return;
+  currentTypeIndex = index;
+  renderTypes();
+  scrollToCenter(index);
+}
+
+// 选中类型滚动至居中
+function scrollToCenter(index) {
+  const container = document.getElementById('cameraTypes');
+  const tag = container.children[index];
+  if (!tag) return;
+  const offset = tag.offsetLeft - container.offsetWidth / 2 + tag.offsetWidth / 2;
+  container.scrollTo({ left: offset, behavior: 'smooth' });
+}
+
+// 拍照
+function takePhoto() {
+  photoTypes[currentTypeIndex].count++;
+  renderTypes();
+  scrollToCenter(currentTypeIndex);
+  updateDoneButton();
+  // 闪光效果
+  document.getElementById('flashEffect').classList.add('fire');
+  setTimeout(() => document.getElementById('flashEffect').classList.remove('fire'), 100);
+}
+
+// 闪光灯
+function toggleFlash() {
+  flashOn = !flashOn;
+  // 注意：路径根据 HTML 文件位置调整
+  document.getElementById('flashIcon').src =
+    `../拍照示例图/拍照-手电筒/${flashOn ? 'ON' : 'OFF'}.svg`;
+  // TODO: 调用设备闪光灯 API
+}
+
+// 更新按钮状态（切换「关闭」/「完成」）
+function updateDoneButton() {
+  const total = photoTypes.reduce((sum, t) => sum + t.count, 0);
+  const btn = document.getElementById('btnDone');
+  if (total > 0) {
+    btn.textContent = '完成';
+    btn.classList.remove('inactive');
+    btn.classList.add('active');
+  } else {
+    btn.textContent = '关闭';
+    btn.classList.add('inactive');
+    btn.classList.remove('active');
+  }
+}
+
+// 示例图放大预览
+function openPreview() {
+  const type = photoTypes[currentTypeIndex];
+  document.getElementById('previewTitle').textContent = type.name;
+  document.getElementById('previewImage').src = type.sample;
+  document.getElementById('previewOverlay').classList.add('show');
+}
+
+function closePreview() {
+  document.getElementById('previewOverlay').classList.remove('show');
+  document.getElementById('previewTitle').textContent = '';
+}
+
+// 关闭 / 完成
+function onComplete() {
+  const total = photoTypes.reduce((sum, t) => sum + t.count, 0);
+  if (total > 0) {
+    // 已拍照：保存数据，返回列表
+    const result = {
+      sourceEntryIndex: sourceEntryIndex,
+      types: photoTypes.map(t => ({
+        name: t.name,
+        count: t.count,
+        sample: t.sample
+      }))
+    };
+    sessionStorage.setItem('cameraResult', JSON.stringify(result));
+    setTimeout(() => { history.back(); }, 800);
+  } else {
+    // 未拍照：直接退出相机
+    history.back();
+  }
+}
+```
+
+---
+
+## 颜色 Token
+
+| Token | 色值 | 使用场景 |
+|-------|------|---------|
+| `--color-grey-1` | `#FFFFFF` | 拍摄按钮、闪光灯图标、缩略图边框 |
+| `--color-yellow-5` | `#ffb530` | 货物类型标签选中态背景 |
+| `--color-black-7` | `#000000` | 货物类型标签选中文字、数量徽章背景 |
+| `--color-black-4` | `#888888` | 完成按钮（未拍照态）背景 |
+| `--color-green-6` | `#03C15F` | 完成按钮（已拍照态）背景 |
+
+---
+
+## 使用规则（AI 必读）
+
+1. **全屏取景**：摄像头画面占满 phone-frame 全部高度，拍照组件不使用导航栏
+2. **货物类型必须可滑动**：类型标签超过屏幕宽度时可左右滑动，隐藏滚动条。**点击切换后已选中标签自动滚动至居中**
+3. **拍摄计数独立**：每个货物类型独立计数，切换类型不丢失之前的计数
+4. **按钮两态**：未拍照时显示「关闭」，白色背景 `#FFFFFF`，黑色文字，点击退出相机；拍照后变「完成」，绿色背景 `--color-green-6`，白色文字，点击保存并返回。按钮规格 `80×48px`，`flex-direction: column`，`padding: 12px`，`z-index: 1`
+5. **闪光灯图标**：使用 `拍照示例图/拍照-手电筒/OFF.svg`（关）和 `ON.svg`（开）
+6. **示例图可放大**：点击左上角示例图弹出全屏预览
+7. **拍照动效**：拍摄按钮点击时 150ms 缩放反馈
+8. **颜色用 Token**：禁止裸 Hex，全部用 `--color-*` 引用
+9. **与拍照列表联动**（⚠️ 强制）：页面加载时从 URL 参数 `?types=货物完整,开箱点数&entryIndex=0` 读取拍照类型列表并筛选展示。完成拍摄后通过 `sessionStorage.setItem('cameraResult', JSON.stringify({ types: [{ name, count, sample }] }))` 回传数据，然后 `history.back()` 返回列表页