自备药扫码登记 — 系统方案

养老机构中，家属经常带来自备药品给长者使用。当前缺乏系统化的自备药登记工具。本方案实现从扫码识别 → 入库登记 → 审核确认 → 同步轻流的完整流程。

技术栈

核心数据链路

药品包装上有两种编码：药品追溯码（20位数字，一物一码）和商品码（13位GTIN，一品一码）。支付宝扫出完整信息是因为对接了阿里「码上放心」平台——国家药监局指定的药品追溯第三方平台。

对接方案

淘宝开放平台免费公开 API：alibaba.alihealth.drug.code.kyt.querycode，无需额外授权，但需要 ref_ent_id（企业入驻码上放心后获得）。

当前阶段：Mock 数据

在码上放心正式接入前，使用 Mock 药品库（5种常见药品），扫码查询返回随机批号和效期。待获取 ref_ent_id 后替换 _mock_scan() 函数即可。

• 阿莫西林胶囊（国药准字H13023976，石药集团）
• 硝苯地平控释片（国药准字H20203345，拜耳）
• 盐酸二甲双胍缓释片（国药准字H20051243，施贵宝）
• 阿托伐他汀钙片（国药准字H20051408，辉瑞）
• 氯沙坦钾片（国药准字H20000372，默沙东）

表名：biz_self_medication_records，存放每次扫码登记的自备药记录。包含 22 个字段 + 6 个索引。

核心字段

蓝色标记的 3 个字段是为「暂存审核 + 批量同步」架构新增的。

追溯码去重规则

-- 同一机构下追溯码唯一（排除已删除记录）
SELECT id FROM biz_self_medication_records
WHERE institution = %s AND trace_code = %s AND is_deleted = 0

删除记录时设置 is_deleted=1（软删除），追溯码自动释放，可重新登记。

连接配置

14 个字段映射

API 调用规范

POST https://care.yckycn.com/openApi/app/eqi4u0ls1401/apply
Headers:
  accessToken: {token}
  Content-Type: application/json

Body:
{
  "applyUser": {"email": "wangdezhi@njycky.com"},
  "answers": [
    {"queId": 208941678, "queType": 2, "values": [{"value": "王德志"}]},
    ...
  ]
}

最初的方案是登记一条就实时推一条到轻流。但在测试中发现：如果业务员录错了（选了错误的老人、填错了数量），轻流那边也会收到错误数据，需要两边都删除。因此改为登记暂存 + 手动推送模式：MySQL 是主数据源，轻流是镜像，审核后一次性推送。

三阶段流程

API 端点（共 8 个）

码上放心 API 对接方案（待实施）

当前扫码查询使用本地 Mock 数据。正式上线后，_mock_scan() 函数将替换为码上放心真实 API 调用，实现药品追溯码的真实信息查询。

交互流程：

• 步骤 1：扫码触发 — 前端输入 20 位追溯码 → 调用 POST /api/self-medication/scan
• 步骤 2：码上放心查询 — 后端 _scan_drug(trace_code) → 调用淘宝开放平台 API，传入 trace_code + ref_ent_id → 解析返回的药品 JSON
• 步骤 3：信息展示 — 药品名称、批准文号、生产企业、规格、剂型、批号、效期等返回到前端药品信息卡片
• 步骤 4：效期预警 — 如果有效期距今天不足 90 天，前端红色高亮标注
• 步骤 5：用户确认 — 选择老人、填写数量/登记人 → 存入暂存区（pending）
• 步骤 6：审核推送 — 在暂存区确认后，选中记录批量推送到轻流

三种状态 & 操作权限

状态流转规则

登记 ──→ pending ──→ 推送成功 ──→ synced（锁定，不可改删）
               └──→ 推送失败 ──→ failed ──→ 重试 ──→ synced
               └──→ 删除 ──→ is_deleted=1（追溯码释放）

页面布局：双栏 + 全宽

• 左侧面板（460px）：机构/休养区选择 → 输入追溯码查询 → 显示药品信息 → 选择老人 → 输入数量/登记人 → 存入暂存区
• 右侧面板（自适应）：三个 Tab（暂存区 / 已同步 / 失败）+ 机构筛选 + 关键词搜索 + 分页
• 顶部统计卡片：累计登记 / 待同步 / 本月登记 / 近效期预警

暂存区 Tab 交互

• 每条记录可内联修改数量（仅 pending 状态，失焦即保存）
• 每条记录可删除（弹窗确认，追溯码释放，提示可重新登记）
• 支持全选 + 批量推送（弹窗确认数量后一次性推送轻流）
• 推送完成后自动跳转到「已同步」Tab

已同步 Tab

纯只读列表，不显示任何操作按钮。每条记录末尾显示绿色已同步标签。

失败 Tab

显示同步失败的记录，提供「重试」按钮（单条重推）。

以下是开发联调过程中遇到的关键问题和解决方案，按时间顺序记录。

轻流 API 对接

架构决策

其他技术细节

• MySQL 时区：默认 UTC → 改为 pymysql.connect(time_zone='+08:00')
• Flask 双进程：端口冲突 → fuser -k 9090/tcp 清理后重启
• 函数名冲突：api_sync() 与 leak_check.py 重名 → 改为 api_med_sync()
• 推送日志位置：/var/log/qf_push.log（含请求体、响应、errCode、requestId）