# H5 打卡签到技术方案（语音转文字 / 拍照 / 定位）

> 基于绿纤 ERP 现有实现整理，供**新项目**复用同类能力。  
> 现有参考代码：`绿纤uni-app` 外勤打卡、沟通记录按住说话；后端 `LqAiService`、`OssDirectUploadService`。  
> 文档日期：2026-07-27

---

## 1. 目标能力（新项目需求）

| 能力 | 说明 |
|------|------|
| 打卡意见 | 可手输；支持**按住说话**，自动转文字填入意见框 |
| 语种 | **汉语 + 藏语**自动识别为文字（见 §4.3 模型选型） |
| 拍照 | 打卡时拍 1 张现场照片并上传 |
| 地址 | 获取定位坐标，并解析/展示地址 |

本方案拆为三块独立能力：**ASR（语音）**、**OSS 上传（音/图）**、**定位与逆地理**，可分别落地。

---

## 2. 总体架构

```mermaid
flowchart LR
  subgraph H5Client [H5客户端]
    Hold[按住录音]
    Cam[拍照]
    Loc[定位]
    Form[签到表单]
  end
  subgraph Backend [业务后端]
    Cred[上传凭证]
    Confirm[ConfirmUpload]
    AsrProxy[ASR代理/转写]
    Punch[签到提交]
  end
  subgraph Cloud [云服务]
    OSS[阿里云OSS]
    DashScope[百炼ASR]
    Map[腾讯位置服务]
  end
  Hold --> Cred --> OSS
  Hold --> Confirm --> AsrProxy --> DashScope
  AsrProxy --> Form
  Cam --> Cred --> OSS
  Cam --> Confirm --> Form
  Loc --> Map --> Form
  Form --> Punch
```

**推荐原则**

1. **密钥不下发到 H5**：DashScope / OSS 的 Secret 只放服务端；H5 只拿**短时上传凭证** + 调自家后端转写接口。  
2. **音频须公网 HTTPS URL**：百炼录音文件识别只认公网可访问地址 → 先传 OSS（绑定自定义域名），再拿 `uploadRecordId` / URL 转写。  
3. **转写异步轮询**：Paraformer / Qwen3-ASR-Filetrans 多为异步，前端超时建议 ≥ 120～180s。

---

## 3. 绿纤 ERP 现有实现对照

### 3.1 语音（沟通记录「按住说话」）

| 项 | 位置 / 说明 |
|----|-------------|
| 前端 UX | [`绿纤uni-app/pages/invite/invite.vue`](../../绿纤uni-app/pages/invite/invite.vue)：`uni.getRecorderManager`，松手后上传 + AI |
| 录音参数 | `format: mp3`，`sampleRate: 16000`，`encodeBitRate: 96000`，最长 120s |
| 上传 | [`绿纤uni-app/service/oss-upload.js`](../../绿纤uni-app/service/oss-upload.js)，目录 type=`aiVoice` |
| 转写+归纳 | `POST /api/Extend/LqAi/pipeline/transcribe-and-summarize-from-upload-record` |
| 后端 | [`netcore/.../LqAiService.cs`](../../netcore/src/Modularity/Extend/NCC.Extend/LqAiService.cs) |

当前绿纤链路是：**转写全文 → 通义对话归纳成短备注**。  
新项目若只要「原话进意见框」，调 **仅转写**接口即可，不必走归纳。

### 3.2 拍照 + 定位（外勤打卡）

| 项 | 位置 / 说明 |
|----|-------------|
| 页面 | [`绿纤uni-app/pagesA/attendance-punch/attendance-punch.vue`](../../绿纤uni-app/pagesA/attendance-punch/attendance-punch.vue) |
| 定位 | `uni.getLocation({ type: 'gcj02', isHighAccuracy: true })` |
| 照片 | `u-upload` → OSS 直传 → `photoUploadRecordId` 随打卡提交 |
| 地图 Key | `appsettings.json` → `NCC_App:TencentLbs:Key`（逆地理等） |

### 3.3 后端 ASR 接口一览（可直接复用或抄接口形态）

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/api/Extend/LqAi/speech/transcribe-from-upload-record` | 上传记录 ID → 转写原文 |
| POST | `/api/Extend/LqAi/speech/transcribe-from-urls` | 公网音频 URL 列表 → 转写 |
| POST | `/api/Extend/LqAi/pipeline/transcribe-and-summarize-from-upload-record` | 转写 + 文本归纳（绿纤联系记录用） |
| POST | `/api/Extend/LqAi/speech/upload-binary-and-transcribe` | 服务端收文件再转写（适合无 OSS 直传时） |
| GET | `/api/Extend/OssDirectUpload/GetUploadCredential?type=aiVoice` | OSS 直传凭证 |
| POST | `/api/Extend/OssDirectUpload/ConfirmUpload` | 直传完成后入库，返回 `uploadRecordId` / `url` |

系统配置键（管理后台「系统配置 → AI 配置」 / 表 `base_sysconfig`）：

| Key | 含义 |
|-----|------|
| `aispeechapiurl` | 语音提交地址 |
| `aispeechapikey` | DashScope API Key |
| `aispeechmodel` | 模型名，现网 `paraformer-v2` |
| `aichatapiurl` / `aichatapikey` / `aichatmodel` | 仅归纳备注需要 |

---

## 4. 语音识别方案（新项目重点）

### 4.1 现网：Paraformer 录音文件识别

- **模型**：`paraformer-v2`  
- **提交 URL**：`https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription`  
- **请求头**：`Authorization: Bearer {API_KEY}`，`X-DashScope-Async: enable`  
- **Body 示例**（与绿纤后端一致）：

```json
{
  "model": "paraformer-v2",
  "input": {
    "file_urls": ["https://你的桶域名/path/xxx.mp3"]
  },
  "parameters": {
    "language_hints": ["zh", "en"]
  }
}
```

- **轮询**：`GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}`，同样带 Bearer。  
- **限制**：`language_hints` 支持 `zh/en/ja/yue/ko/de/fr/ru`，**不支持藏语**。

官方文档：  
https://help.aliyun.com/zh/model-studio/paraformer-recorded-speech-recognition-restful-api

### 4.2 汉语 + 藏语：建议改用 Qwen3-ASR（百炼）

绿纤现网 Paraformer **无法满足藏语**。新项目建议：

| 场景 | 推荐模型 | 说明 |
|------|----------|------|
| 按住说话（通常 ≤ 2 分钟） | `qwen3-asr-flash` 或 `qwen3-asr-flash-filetrans` | 多语种；开源/百炼侧已覆盖藏语等少数民族语言能力 |
| 与绿纤同一套「先 OSS 再异步」 | `qwen3-asr-flash-filetrans` | 异步 + 公网 URL，改造成本最低 |

实现注意：

1. **同一 DashScope API Key** 可调用不同模型（开通对应模型权限即可）。  
2. 参数字段可能是 `language`（Qwen3）而不是 Paraformer 的 `language_hints`；未知语种时可**不传**，让模型自动识别汉/藏。  
3. 若必须「识别结果保留藏文原文」，不要再强制走「归纳成简体中文备注」的 Chat 步骤；签到意见直接用 `RawText`。  
4. 上线前用真实藏语录音做准确率验收（嘈杂户外、方言口音）。

参考：  
https://help.aliyun.com/zh/model-studio/non-realtime-speech-recognition-user-guide  
https://help.aliyun.com/zh/model-studio/asr-model

### 4.3 H5 录音（相对小程序的差异）

| 环境 | 录音方式 |
|------|----------|
| 微信小程序 / App（绿纤） | `uni.getRecorderManager()` → mp3 |
| **纯 H5 / 微信内 H5** | `MediaRecorder` + `getUserMedia({ audio: true })`，常见输出 `webm/opus` 或转码为 `wav/mp3` |

建议：

1. 优先产出 **wav / mp3**（兼容性最好）；webm 绿纤后端已允许扩展名，但建议转码。  
2. UI：按住开始、松手结束；最短时长 ≥ 0.6s（绿纤阈值太短提示）。  
3. 必须 HTTPS；iOS Safari 需用户手势触发录音。  
4. 微信内置浏览器注意权限与域名白名单。

### 4.4 推荐前端流程（签到意见）

```text
touchstart → startRecord
touchend   → stopRecord → 得到本地 blob/file
           → GetUploadCredential(type=aiVoice|punchVoice)
           → POST 表单直传 OSS
           → ConfirmUpload → uploadRecordId + publicUrl
           → POST 业务后端 /asr/transcribe { uploadRecordId }
           → 把 data.rawText 写入「打卡意见」输入框（可再编辑）
```

仅转写请求体示例：

```json
{ "uploadRecordId": "雪花ID" }
```

成功响应关注字段：`rawText` / `RawText`。

---

## 5. 拍照方案

与绿纤外勤打卡一致即可：

1. H5：`<input type="file" accept="image/*" capture="environment">` 或 `uni.chooseImage`（uni-app H5）。  
2. 压缩到合理大小（如长边 ≤ 1920，JPEG 质量 0.8）。  
3. OSS 直传 type 建议：`punchPhoto` / `attendance`（新项目自定目录）。  
4. `ConfirmUpload` 后保存 `photoUploadRecordId` + 展示 URL。  
5. 签到提交时一并传给业务接口。

可选：服务端图片审核（绿纤有 `ImageModeration` / Hangfire 异步审核），新项目按合规需要接入。

---

## 6. 定位与地址方案

### 6.1 坐标

- H5：`navigator.geolocation.getCurrentPosition`（需 HTTPS、用户授权）。  
- 坐标系：国内业务常用 **GCJ-02**（与腾讯/高德一致）；绿纤小程序用 `type: 'gcj02'`。  
- 提交字段建议：`longitude`、`latitude`、`accuracy`。

### 6.2 逆地理（坐标 → 地址文案）

绿纤使用腾讯位置服务 Key（见 §7）。新项目可：

1. **服务端代理**调用腾讯 WebService「逆地址解析」，避免 Key 暴露 + 便于配额管控；或  
2. H5 用腾讯地图 JavaScript API（域名需在腾讯控制台加白名单）。

接口形态参考（腾讯）：

```text
GET https://apis.map.qq.com/ws/geocoder/v1/?location={lat},{lng}&key={KEY}&get_poi=0
```

返回中取 `result.address` / `formatted_addresses.recommend` 写入「打卡地址」。

---

## 7. 可供新项目联调的现有 Key / 配置（测试用）

> **安全声明**：以下为绿纤 **dev/现网业务已在用的配置快照**，仅供新项目**联调验证**。  
> 正式环境请为新项目开通**独立**百炼 Key、OSS Bucket、地图 Key，并轮换密钥；勿把本文直接提交到公开仓库。

### 7.1 阿里云百炼（语音 + 文本，同一 Key）

| 项 | 值 |
|----|-----|
| API Key | `sk-387532ff1f2f40e39c09d6ab5dc9e3ff` |
| 语音提交 URL | `https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription` |
| 现网语音模型 | `paraformer-v2`（**仅汉/英等，不含藏语**） |
| 藏语建议模型 | `qwen3-asr-flash-filetrans` 或 `qwen3-asr-flash`（需在百炼控制台开通） |
| 任务查询 | `https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}` |
| 文本对话 Base（可选） | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| 文本模型（绿纤归纳用） | `qwen-max` |

**curl 冒烟（仅汉英 Paraformer，需公网音频 URL）：**

```bash
# 1) 提交
curl -s -X POST "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription" \
  -H "Authorization: Bearer sk-387532ff1f2f40e39c09d6ab5dc9e3ff" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "paraformer-v2",
    "input": { "file_urls": ["https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"] },
    "parameters": { "language_hints": ["zh", "en"] }
  }'

# 2) 用返回的 output.task_id 轮询
curl -s "https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}" \
  -H "Authorization: Bearer sk-387532ff1f2f40e39c09d6ab5dc9e3ff"
```

### 7.2 阿里云 OSS（上传音/图）

| 项 | 值 |
|----|-----|
| AccessKeyId | `LTAI5t6h4i95uapwzDwKfNxi` |
| AccessKeySecret | `84dpUAlu2eoyFOIEhFGkZlIy45h0B6` |
| Endpoint | `oss-cn-chengdu.aliyuncs.com` |
| Region | `cn-chengdu` |
| 公网访问域名 | `https://lvqian-erip.oss-cn-chengdu.aliyuncs.com` |

> 新项目**强烈建议**新建 Bucket + 子账号 AK，仅授权本桶读写；不要长期共用绿纤主账号密钥。

### 7.3 腾讯位置服务（定位/逆地理）

| 项 | 值 |
|----|-----|
| Key | `YRXBZ-NEV6T-K7SXH-VJPMF-G5IQF-F3FCJ` |

控制台需为新项目 H5 域名配置合法域名 / WebService 配额。

### 7.4 走绿纤后端联调（可选）

若新项目暂时不自建 ASR 代理，可临时打绿纤已部署环境（需登录 Token）：

```text
Base: http://localhost:2015   # 或你们的测试 API 域名
POST /api/Extend/LqAi/speech/transcribe-from-upload-record
Authorization: {绿纤登录后的 Bearer Token}
Body: { "uploadRecordId": "..." }
```

系统配置里语音 Key 与上文百炼 Key 一致。

---

## 8. 新项目模块划分建议

| 模块 | 职责 |
|------|------|
| `upload` | 获取凭证、直传 OSS、Confirm，统一返回 `url` + `uploadRecordId` |
| `asr` | 接收 `uploadRecordId`/`fileUrl`，调百炼，返回 `rawText`；可配置 model |
| `geo` | 可选：服务端逆地理，隐藏地图 Key |
| `checkin` | 签到业务：意见、照片 ID、经纬度、地址、时间、用户 |

配置项建议（环境变量）：

```text
DASHSCOPE_API_KEY=
DASHSCOPE_ASR_MODEL=qwen3-asr-flash-filetrans   # 汉藏；验证期可先 paraformer-v2
OSS_AK / OSS_SK / OSS_ENDPOINT / OSS_BUCKET / OSS_PUBLIC_HOST=
TENCENT_LBS_KEY=
```

---

## 9. 验收清单

- [ ] 按住说话 → 意见框出现中文（普通话）  
- [ ] 按住说话 → 意见框出现藏文（或藏语口语转写结果可用）  
- [ ] 录音过短有提示；失败有明确 Toast  
- [ ] 拍照成功上传并可在详情回看  
- [ ] 定位成功；地址文案合理（允许手动改）  
- [ ] Key / Secret 未打包进前端静态资源  
- [ ] 弱网 / 转写超时有重试或「改用手输」兜底  

---

## 10. 风险与注意

1. **藏语不能用现网 `paraformer-v2` 硬套**，需换 Qwen3-ASR 系并做真机验收。  
2. OSS 对象必须 **公网 HTTPS** 可被百炼拉取（私有桶需签名 URL 且在有效期内）。  
3. 费用：ASR 按音频时长计费；地图 Key 按调用量；注意配额告警。  
4. 隐私：签到音/图属敏感数据，需告知用户用途并控制访问权限与留存周期。  

---

## 11. 参考代码索引

| 主题 | 路径 |
|------|------|
| 按住说话 UX | `绿纤uni-app/pages/invite/invite.vue` |
| OSS 直传 | `绿纤uni-app/service/oss-upload.js` |
| 打卡定位/拍照 | `绿纤uni-app/pagesA/attendance-punch/attendance-punch.vue` |
| ASR 服务 | `netcore/src/Modularity/Extend/NCC.Extend/LqAiService.cs` |
| OSS 配置 | `netcore/src/Application/NCC.API/appsettings.json` → `NCC_App:AliyunOSS` |
| 地图 Key | 同上 → `NCC_App:TencentLbs` |