H5打卡签到-语音拍照定位技术方案.md 13.4 KB

Edit Raw Blame History Permalink


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

基于绿纤 ERP 现有实现整理，供新项目复用同类能力。

现有参考代码：绿纤uni-app 外勤打卡、沟通记录按住说话；后端 LqAiService、OssDirectUploadService。

文档日期：2026-07-27


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


能力
说明


打卡意见
可手输；支持按住说话，自动转文字填入意见框


语种
汉语 + 藏语自动识别为文字（见 §4.3 模型选型）


拍照
打卡时拍 1 张现场照片并上传


地址
获取定位坐标，并解析/展示地址


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


2. 总体架构
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


推荐原则


密钥不下发到 H5：DashScope / OSS 的 Secret 只放服务端；H5 只拿短时上传凭证 + 调自家后端转写接口。

音频须公网 HTTPS URL：百炼录音文件识别只认公网可访问地址 → 先传 OSS（绑定自定义域名），再拿 uploadRecordId / URL 转写。

转写异步轮询：Paraformer / Qwen3-ASR-Filetrans 多为异步，前端超时建议 ≥ 120～180s。


3. 绿纤 ERP 现有实现对照
3.1 语音（沟通记录「按住说话」）


项
位置 / 说明


前端 UX
<code>绿纤uni-app/pages/invite/invite.vue</code>：uni.getRecorderManager，松手后上传 + AI


录音参数
format: mp3，sampleRate: 16000，encodeBitRate: 96000，最长 120s


上传
<code>绿纤uni-app/service/oss-upload.js</code>，目录 type=aiVoice


转写+归纳
POST /api/Extend/LqAi/pipeline/transcribe-and-summarize-from-upload-record


后端
<code>netcore/.../LqAiService.cs</code>


当前绿纤链路是：转写全文 → 通义对话归纳成短备注。

新项目若只要「原话进意见框」，调 仅转写接口即可，不必走归纳。
3.2 拍照 + 定位（外勤打卡）


项
位置 / 说明


页面
<code>绿纤uni-app/pagesA/attendance-punch/attendance-punch.vue</code>


定位
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 示例（与绿纤后端一致）：

{
  "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，改造成本最低


实现注意：


同一 DashScope API Key 可调用不同模型（开通对应模型权限即可）。

参数字段可能是 language（Qwen3）而不是 Paraformer 的 language_hints；未知语种时可不传，让模型自动识别汉/藏。

若必须「识别结果保留藏文原文」，不要再强制走「归纳成简体中文备注」的 Chat 步骤；签到意见直接用 RawText。

上线前用真实藏语录音做准确率验收（嘈杂户外、方言口音）。


参考：

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


建议：


优先产出 wav / mp3（兼容性最好）；webm 绿纤后端已允许扩展名，但建议转码。

UI：按住开始、松手结束；最短时长 ≥ 0.6s（绿纤阈值太短提示）。

必须 HTTPS；iOS Safari 需用户手势触发录音。

微信内置浏览器注意权限与域名白名单。

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


仅转写请求体示例：
{ "uploadRecordId": "雪花ID" }


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


5. 拍照方案
与绿纤外勤打卡一致即可：


H5：<input type="file" accept="image/*" capture="environment"> 或 uni.chooseImage（uni-app H5）。

压缩到合理大小（如长边 ≤ 1920，JPEG 质量 0.8）。

OSS 直传 type 建议：punchPhoto / attendance（新项目自定目录）。

ConfirmUpload 后保存 photoUploadRecordId + 展示 URL。

签到提交时一并传给业务接口。


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


6. 定位与地址方案
6.1 坐标

H5：navigator.geolocation.getCurrentPosition（需 HTTPS、用户授权）。

坐标系：国内业务常用 GCJ-02（与腾讯/高德一致）；绿纤小程序用 type: 'gcj02'。

提交字段建议：longitude、latitude、accuracy。

6.2 逆地理（坐标 → 地址文案）
绿纤使用腾讯位置服务 Key（见 §7）。新项目可：


服务端代理调用腾讯 WebService「逆地址解析」，避免 Key 暴露 + 便于配额管控；或

H5 用腾讯地图 JavaScript API（域名需在腾讯控制台加白名单）。


接口形态参考（腾讯）：
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）：
# 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）：
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、经纬度、地址、时间、用户


配置项建议（环境变量）：
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. 风险与注意

藏语不能用现网 paraformer-v2 硬套，需换 Qwen3-ASR 系并做真机验收。

OSS 对象必须 公网 HTTPS 可被百炼拉取（私有桶需签名 URL 且在有效期内）。

费用：ASR 按音频时长计费；地图 Key 按调用量；注意配额告警。

隐私：签到音/图属敏感数据，需告知用户用途并控制访问权限与留存周期。


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