- 新增 attendant_application 表与 5 个接口:提交/我的申请/审核列表/ 材料大图/审批,/mine 注册在 /:id 之前 - 提交侧按员工档案岗位分支:在职陪诊师与管理员及其他岗位 409 拒绝, 转岗由管理员后台显式操作;停用陪诊师可重新申请 - 审批两步走不依赖事务:条件更新抢占 pending,ensureEmployee 单条 条件 upsert 幂等建档(只放行无档案或已有 attendant 档案), 失败靠 approvedEmployeeId 为空续跑 - 岗位冲突时申请单条件回滚为 pending,不卡死在"已通过但未建档" - employee.userId 加 partial unique 索引并移除 employeeNo 默认值, 附迁移与存量校验脚本;员工管理端绑定账号查重与 userIdSource 标记 - 证件照复用 parseImage(单张 3MB),入驻前缀放宽请求体上限; 索引创建失败改为记日志,避免启动即崩
api-health
陪诊小程序的后端服务(Koa + 原生 WebSocket + MongoDB),除订单/档案等业务接口外, 还提供 AI 陪诊助手与语音转写 / 图像识别两类多模态输入能力。
npm install
npm run dev # nodemon index.js,HTTP 9004 / WS 9005
npm test # node --test test/*.test.js
语音与图像识别
设计参考 xagent 的设备数据通道(asr.js / asr_dashscope.js / ocr.js / ocr_qwen.js),
保留了「识别与投递解耦」的会话契约。语音有两条传输方式:
- 实时分片(默认):走聊天 WebSocket 的
asr_start/asr_chunk/asr_stop, 中间结果经asr_partial逐字回显,定稿经asr_final返回。 - HTTP base64 整段上传(兜底):
/health/ai/asr用于分片缺失(如开发者工具)或实时链路失败的场景。
共同约定:
- 识别只产出文本,服务端不投递、不落库;客户端把文本回填输入框,由用户点发送键后再走原聊天链路(WS
chat)。 - 音频 / 图片只在本轮请求内存中存在,不落盘、日志不记录正文。
- 默认只做转写:语音用
fun-asr-realtime,图片用qwen-vl-ocr;是否进一步解读由 agent 的提示词决定。 - 接口必须登录(
token或Authorization: Bearer <token>),按用户限流 20 次/分钟。
实时语音识别(WS /chat)
上行帧(客户端 → 服务端):
| 帧 | 字段 | 说明 |
|---|---|---|
asr_start |
id / token / format? / sampleRate? / channels? |
声明一轮识别,鉴权与限流都在这一步 |
asr_chunk |
id / audio(base64 分片) |
每帧一个录音分片,单帧 ≤ 128KB,整轮 ≤ 8MB |
asr_stop |
id |
结束推流并取定稿 |
asr_cancel |
id |
放弃本轮(页面隐藏、录音中断) |
下行帧(服务端 → 客户端,type 为下列值,id 与上行 asr_start 的 id 对应):
| 帧 | content |
说明 |
|---|---|---|
asr_partial |
当前累计文本 | 中间结果,客户端实时回填输入框 |
asr_final |
定稿文本(可能为空串) | 结束后返回,客户端提示重录或留在输入框 |
asr_error |
可读错误文案 | 客户端改用整段接口兜底 |
同一连接上同时只保留一轮识别;asr_start 会中止上一轮,连接关闭时也会 abort。
POST /health/ai/asr
请求体(JSON,上限 20MB,解码后音频 ≤ 10MB):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
audio |
string | 是 | base64 或 data:audio/mpeg;base64,... |
format |
string | 否 | mp3(默认)/ aac / wav / pcm / pcm16 |
sampleRate |
number | 否 | 8000 / 16000(默认)/ 24000 / 48000 |
channels |
number | 否 | 仅支持 1 |
curl -s http://localhost:9004/health/ai/asr \
-H "Content-Type: application/json" -H "token: <token>" \
-d '{"audio":"<base64>","format":"mp3"}'
# => { "code": 0, "msg": "操作成功", "data": { "text": "我明天想带老人去复查" }, "ts": ... }
POST /health/ai/ocr
请求体(JSON,上限 20MB,解码后图片 ≤ 8MB):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
image |
string | 是 | base64 或 data URL |
mime |
string | 否 | image/jpeg(默认)/ image/png / image/webp |
width / height |
number | 否 | 像素尺寸,仅用于让模型判断清晰度 |
kind |
string | 否 | 首版固定 auto,服务端按内容自行判断报告类型 |
curl -s http://localhost:9004/health/ai/ocr \
-H "Content-Type: application/json" -H "token: <token>" \
-d '{"image":"<base64>","mime":"image/jpeg"}'
返回的 data.text 是可直接投喂给 agent 的可读文本,段落包括【图像识别】【原文转写】
【结构化要点】(full 模式才有解读段)【图像质量】【说明】,末尾带免责说明。
profile: transcribe(默认)只传图片、不附加提示词:qwen-vl-ocr 自带逐行转写模板,
附加系统提示或 JSON 契约会把原文压成摘要、表格列还会粘连,因此【原文转写】段必须是
模型原生输出的完整原文;文档类型与标题由服务端按文本关键词兜底判断。
原生转写用制表符 / 多空格 / 全角空格对齐列,直接展示会被 markdown 折叠成一串, 因此服务端会把连续的分列块转成 markdown 表格(列数不足补空列,超出并进最后一列), 其余行独立成段保留换行。小程序与 Taro 端都按 markdown 渲染即可。
小程序把识别文本以 WS format 帧投递({ type: "format", content, id, token, ts }):
服务端只把原文并入会话上下文,并按分片原样回显给客户端展示,不再让模型二次改写。
识别结果通常有几百到上千字,模型改写会按咨询提示词压缩成 1-3 句,还会被输出护栏的
400 字上限截断,长报告必然丢行;原文投递既完整,也省一次生成。
错误码
业务码统一走响应体 code(HTTP 恒 200),同时写入 X-Biz-Code 响应头:
| code | 场景 |
|---|---|
| 400 | 参数缺失 / base64 非法 / 格式或采样率不支持 / 超出大小上限 / 未识别到内容 |
| 401 | 未登录或 token 失效 |
| 403 | 无权限 |
| 502 | 供应商识别失败(错误详情只进日志) |
| 503 | 识别服务未配置(缺密钥 / 缺少 endpoint) |
配置
识别配置位于 conf.json 的 agent.media 段,密钥支持直接写 apiKey,或通过
apiKeyEnv 指向环境变量(.env 由 dotenv 加载):
"media": {
"audio": { "rate": 16000, "channels": 1 },
"asr": {
"provider": "dashscope",
"endpoint": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
"model": "fun-asr-realtime",
"apiKeyEnv": "ASR_KEY"
},
"image": { "mimes": ["image/jpeg", "image/png", "image/webp"] },
"ocr": {
"provider": "qwen",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-vl-ocr",
"profile": "transcribe",
"apiKeyEnv": "ASR_KEY",
"requestTimeoutMs": 60000,
"disclaimer": "本内容为图像文字识别结果,不构成诊断意见,请以医生诊断与医院报告为准。"
},
"limits": { "maxAudioBytes": 10485760, "maxImageBytes": 8388608 }
}
- 密钥变量名与参考项目 xagent 一致:
ASR_KEY;取值顺序为apiKey→apiKeyEnv→ASR_KEY→DASHSCOPE_API_KEY(后两者兜底,便于两个项目共用同一把 key)。 provider: "qwen"走 OpenAI 兼容chat/completions;配置endpoint(http/https)可换成自建 OCR 服务; 也可在代码里给createOcrSession({ recognize })注入本地 PaddleOCR 等实现。provider: "dashscope"走实时 ASR;不配provider而给endpoint为 ws/wss 时同样按实时处理; 传transcribe或 http endpoint 则走批式。profile: "full"才会要求模型输出解读字段;涉及诊断结论的能力不默认开启。- 密钥为空时两个接口直接回 503「服务暂不可用」,不会发起外部请求。
目录
agent/infra/media/ 语音 / 图像识别适配器(会话契约、供应商实现、音频容器识别)
handler/ai_media.js 两个识别接口的入参校验、错误分层与响应
routes/index.js 路由注册(/health/ai/*)
test/media.test.js 元信息白名单、base64 解码、会话生命周期、供应商请求与失败路径
目录约定:
- 根目录只放入口与配置(
index.js/app.js/websocket.js/config.js等),不提交临时脚本。 - 自动化测试统一放
test/*.test.js,由npm test执行;临时验证脚本应先转成正式测试,不要留在根目录。 - 一次性运维 / 调试脚本放
scripts/,用完后删除;需长期保留的请在 README 中说明用途和用法。 - Agent 共享逻辑放
agent/infra/,业务路由与处理器分别放routes/、handler/。
客户端约定
- 小程序录音使用
wx.getRecorderManager(),format: 'mp3'、sampleRate: 16000、numberOfChannels: 1, 并带frameSize(单位 KB)以触发onFrameRecorded:每帧转 base64 后按asr_chunk实时上传, 点麦克风结束(或满 60 秒)时发asr_stop。 - 两种录音格式都能实时回填:真机录的是 16k 单声道 MP3(MPEG-2 Layer III),
开发者工具录的是 WebM(Matroska)/Opus(文件名仍是
.mp3)。供应商自带的解码器对这两种容器 都不可靠(真机 mp3 实测直接报DecodePost resample audio from 0 to 16000 failed), 因此服务端按首帧魔数识别容器后,统一用流式解码器(WebM/Opus、mp3/mpg123)转成 16bit 单声道 PCM(48k 抽取到 16k、16k 原样)再推给供应商,两种环境都能逐字出中间结果。 客户端不再判断容器,分片一律上传;只有服务端明确回asr_error(认不出容器 / 供应商失败)时 才降级为「结束后整段转写」。首帧认不出容器时服务端先缓存至多 16KB 再判,避免误杀只有 cluster 的平台。 - 整段识别遇到供应商偶发断流(
asr socket closed/ 建连超时)会自动重试一次(间隔 600ms), 避免用户白录一遍;解码/参数类错误不重试。 - 整段音频按 300ms(压缩格式按 64KB)切片推给供应商,并在发送队列排空后才发
finish-task: 一次性把几秒 PCM 塞进 socket 会让供应商来不及消费而直接断流。 - 实时链路在说话途中失败时客户端不弹错、不中断录音,标记为降级并继续采集;结束时用完整录音文件
(而不是失败瞬间的半截分片)整段提交
/health/ai/asr,只有整段也失败才提示用户。 - 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是
.mp3,控制台会提示格式与移动端不同); 真机才是真正的 16k mp3。服务端按文件头识别容器后都先解码成 16bit 单声道 PCM 再交给供应商, 整段兜底的/health/ai/asr走同一个识别入口,因此两条链路都能正常转写。 - 拍照 / 选图使用
wx.chooseMedia,上传前压缩到 1~2MB。图片不走确认面板:选中后立即作为一条用户消息上屏,/health/ai/ocr返回的文本直接落成 AI 回复;图片临时路径不落 storage,重启后历史里只保留[图片]占位。 - 语音识别结果实时回填输入框;再次点麦克风结束识别后直接发送(
asr_final定稿或整段兜底成功后 立即走聊天 WS),录音中可看到逐字结果,结束后不需要再点一次发送键。 语音图标本身承担开录与结束(录音中变色,再点一次结束),不弹确认浮层、不遮挡输入框; 若此时还有上一条回复在途,定稿文本会留在输入框,等回复完成后由用户点发送,不丢内容。 - 语音与图片识别结果可能有错字,涉及数值、单位、药名、日期时由 agent 提示用户确认。