antissoft / lvqianmeiye_ERP

  # 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` |