交付出件箱

平板端扫码绑定 · 方案（48B.8）

2026-09-28 · 长官令「平板需要加，平板也是在微信里打开的，出方案出图，必须要做」
本件只是方案，代码一行没动。
方案图：https://dev-tokyo.tail3912a6.ts.net/scan-binding-tablet-v1-20260928.html

一句话

平板「视光档案」列表顶上加两个按钮：「机构码」「绑定家长」。功能、流程、文案和手机端一模一样，只是外观换成平板自己那套（蓝色、大弹框）。后端一个接口都不用加。

做完以后店员在平板上怎么用

打开平板「视光档案」，搜索框右边多了两个按钮：机构码、绑定家长（「新建档案」还在最右边）
点 绑定家长 → 弹出两个选项（和手机一样）：
扫描家长二维码 → 微信相机扫家长手机上的「我的二维码」→ 看到这位家长名下的孩子 → 选一个 → 绑到本店
- 家长名下没有这个孩子 → 点「新建孩子档案」当场建，建完直接绑上；同名同生日会弹重名提醒
- 孩子本店已经有档案、只是没绑家长 → 点「关联已有档案」，从本店档案里选一个关联给这位家长
从本机构家长中选择 → 先选孩子，再弹出平板原来那个「绑定家长」框（原样不改）
点 机构码 → 弹出本店的二维码。家长可以直接拿手机对着平板扫；也可以长按保存，打印贴在前台
孩子档案页里原来那个「绑定家长」按钮不动

为什么这么放

放在列表顶上：手机端这两个入口也在列表页顶上，店员两边用起来一个习惯
机构码用弹框不用新页面：平板视光档案整个是一页，弹框看完点「关闭」就回来，不用来回跳页

✅ 9-28 晚长官定：平板「绑定家长」按钮加小人图标（与同排「机构码」二维码图标、「新建档案」+ 图标一致；方案图现版即带图标）。

请长官定 / 回一句（2 件）

看方案图：两个按钮的位置、几个弹框的样子行不行
~~店里的平板是 iPad 还是安卓？~~ 9-28 长官答：两种都有。还请您用 iPhone 试一次：先进首页再点「视光档案」→「绑定家长」→「扫描家长二维码」，相机能不能打开？
为什么问：微信在苹果设备上有个老规矩，页面是「点进来」的（不是直接打开的），调微信扫一扫可能会失败。平板视光档案和手机门店端都是点进来的
如果 iPhone 上能打开相机 → 说明没这问题，照常做
如果打不开 → 我会顺手在共用的扫码工具里加上苹果设备的处理（手机、平板一起受益）

发生产会多一个

平板这件做完是一个新的 MR。它用到的接口和页面生产上还没有，所以只能跟扫码绑定这批一起发。发生产清单会从 6 个变成 7 个：757 + 758 + 759 + 761 + 768 + 773 + 平板这个。

还是按您的令：先不发生产。

技术附录（给实施和交接看）

现状（已核实 · origin/test）

平板视光档案列表头部只有搜索框 + 「新建档案」：web/app/h5/tablet/pane/panes/refractive-record/frame1-child-list.tsx:66-89
档案页「绑定家长」（只做路 A：从本店家长子席位选）：frame3-patient-profile.tsx:250-256 → frame3b-bind-selector.tsx
平板弹框统一外壳：遮罩 rgba(23,58,84,.35)、白底圆角 18、maxWidth: 620：frame3b-bind-selector.tsx:70-77（注释称沿用 frame2-create-modal.tsx）
平板视光档案是蓝色系（主按钮 #2563eb、标题 #173a54），与手机端绿色系不是一套
~~平板只能在微信里打开（非微信直接拦）~~ 9-28 实施核查纠正：平板也能在非微信浏览器里用。有两种情况：机构开了门店密码登录（tablet/page.tsx:170-183 密码登录门无微信判断）；或者设备上已有登录凭证，直接进入（page.tsx:368-388 不走 resolveSeatWxStep）。二级页 pane/page.tsx 不做任何微信判断。→ 照手机 store-refractive/page.tsx:311-320 处理：微信内点「绑定家长」弹出两个选项；非微信直接进「选择要绑定的档案」，因为非微信里调不起扫一扫。令牌与手机端共用 seat_access_token（chat/lib/auth.ts:11）
平板进入视光档案是单页跳转：tablet/page.tsx:512 router.push、pane/page.tsx:166 router.replace

改动范围

位置	改什么
`frame1-child-list.tsx:81` 前	插「机构码」「绑定家长」两个次按钮（白底 + 1.5px `#2563eb` 描边 + 蓝字，尺寸同「新建档案」）；新增两个回调 prop
`refractive-record-pane.tsx`	新增弹框状态（绑定方式 / 选孩子 / 选档案层 bind·link / 机构码）；绑定成功后重拉列表
平板新增弹框组件（放 `refractive-record/` 目录）	绑定方式、选孩子、选档案层、机构码，外壳全部照 3b（宽 620，平板现网唯一弹框宽度）；不加右上角「×」（平板现网弹框都没有，`frame3b-bind-selector.tsx:13` 只引 Search），每个弹框底部都有「取消 / 关闭」
扫码后新建孩子	复用平板现有 `frame2-create-modal.tsx`，只加两个参数：标题下一行「家长：XX」、主按钮文案「保存并绑定」；标题沿用平板的「新建档案」（手机端叫「新建视光档案」，平板沿用平板自己的叫法）
各种状态	全部照手机端 `select-child-dialog.tsx`：家长名下没孩子「该家长暂无孩子档案」、扫码出错（二维码无效/已失效 +「取消」「重新扫描」）、加载中、网络失败、选档案层为空「暂无未绑定的档案」、绑定/关联失败；用户取消扫码不提示；绑定成功静默关闭并刷新列表、无成功提示（与手机端一致）
重名提醒	用平板自己的确认框样式（`frame4-record-view.tsx:843` 起的本地 `ConfirmDialog`，蓝色系），不用手机端共用的 `h5/components/confirm-dialog.tsx`（绿色系，平板 0 处引用）。⚠️ 该确认框取消键文案写死「取消」，实施时要加文案参数以显示「仍然新建」
复用不改	接口函数取自 `store-refractive/lib/api.ts`（`resolveFamilyScan` / `claimFamilyScan` / `createChildForFamilyScan` / `linkChildForFamilyScan` / `getOrgCode`）；扫码与纯函数取自 `chat/lib/wx-scan.ts`（`scanQrCode` / `childOrgLine` / `currentOrgOf`）；「从本机构家长中选择」后一步沿用平板现有 `listBindableSeats` / `bindPatientSeat` + 3b 弹层
机构码弹框小字	用视光档案蓝灰：说明 `#43617a`、小字 `#7a8fa3`（出自 `frame4-record-view.tsx:843` 起的确认框正文色、`frame3-patient-profile.tsx:243`；方案图已按此改好）
不动	手机端全部组件（已真机验过）；后端 0 改动；档案页「绑定家长」
第二轮自检补充	见下方「第二轮自检」5 条：扫码带上语音权限（`wx-scan.ts`）、平板确认框导出并加取消文案参数、扫码建档新写提交函数、列表入口绑定新写确认函数、表头搜索框防挤压

为什么平板自己写界面、不直接复用手机弹框：手机弹框宽 328、绿色系，搬到平板既窄又串色；给手机组件加「平板模式」开关会动到已验收的手机代码。所以只复用接口和逻辑函数，界面按平板令牌单独写。代价是两套界面各一份，属于有意取舍。

风险

✅ 9-28 已解决：iPhone 扫码失败的真正根因不是签名网址，是 jweixin 的 ready 状态整页不重置，导致 ready 提前回调，iOS 报 offline verifying。已由 MR#782（等验证完再扫 + iOS 首次网址签名）和 MR#784（弹框打开就预热签名）修复，长官 iPhone 真机确认相机能开、速度可以。平板复用同一工具，直接受益。下面是当时的原始推断，留作记录：
（原推断）iOS 微信 JS-SDK 签名：全仓所有 wx.config 调用都用「调用那一刻的网址」签名（wx-scan.ts:87、use-tablet-wechat-voice.ts:52-58），没有「首次进入网址」处理；后端 app/api/wx_jssdk.py 完全照前端传入网址签名。iOS 微信对单页跳转后的页面可能要求用首次进入网址签名。手机门店端（chat/page.tsx:3118 router.push）同样存在此情况。处理：先问长官 9-26 iPhone 实测结果；有问题则在 wx-scan.ts 加 iOS 首次进入网址签名，手机、平板一起生效。
9-26 线索：测试库 auth_audit_logs 显示 04:44:57 家长号 401 在 iPhone 微信 8.0.76 登录、04:46:09 门店号在 Mac 微信登录，04:46:39 转店测试1023 转入机构 26。分不出家长是用页面内扫码还是微信自带扫一扫，不能当签名无问题的证据。

第二轮自检（9-28 晚 · 逻辑与功能，对照 origin/test 代码逐条核实）

确认没问题的（有代码依据）

查什么	结论	依据
平板登录的账号能不能调扫码绑定接口	能。接口只拒家长号；test 上家长号在平板登录那一步就被拦了	`app/auth/middleware.py:411-422` `require_store_seat` 只拒 `seat_type=="parent"`；origin/test `seat_auth.py:251-270` scene=tablet 只认门店号
扫码认领别家店的孩子后，平板列表里能不能看到	能。平板和手机列表是同一个后端查询，认领写的 `service_org_id` 会被识别	平板 `searchPatients` → `GET /api/h5/refractive-records/patients` → `refractive_record_service.py:223-226` 用 `_org_visibility_clause`；认领写 `brand_code_claim_service.py:208`
平板新建档案表单的字段，扫码建档接口收不收	全收。平板 10 个字段都在接口的 `PatientCreateIn` 里，3 个必填平板都有	`frame2-create-modal.tsx:247-258` vs `app/schemas/refractive_record.py:180-209`
机构码在平板上能不能长按保存	能。手机端用后端出的 `<img>`，不是 SVG；平板照抄同一写法	`store-refractive/org-code/page.tsx:6-7,116-121`
绑定成功后「静默关闭 + 刷新列表、无提示」是否和手机一致	一致（扫码三条路径）	手机 `page.tsx:649-652` `onBound` = 关弹框 + `runSearch`

方案原文没写到、实施时必须处理的（5 条）

🔴 扫码会把平板聊天的「微信语音」弄坏。平板聊天页常驻，不随菜单切换卸载（origin/test pane/page.tsx:180-190）。一进平板，它就用语音接口 config 一次微信（use-tablet-wechat-voice.ts:80），而且只 config 这一次。扫码时 config 的接口清单只有 scanQRCode，会把语音权限覆盖掉，之后回聊天用语音就失败，要刷新才恢复。→ 处理：wx-scan.ts 扫码 config 的接口清单里一并带上 checkJsApi + WECHAT_VOICE_APIS（同目录 chat/lib/wechat-voice.ts 已导出），扫码后语音权限还在。改的是手机、平板共用的扫码工具，只是清单变多，不改流程。
🟡 重名提醒用的平板确认框目前是私有的：frame4-record-view.tsx:843 的 ConfirmDialog 没有 export，取消键文案写死「取消」。→ 处理：加 export，加一个可选的取消文案参数（默认「取消」，老调用方零改动）。
🟡 扫码建档要单独写提交函数。新建弹框本身不调接口，靠 onSubmit 回调（frame2-create-modal.tsx:243-259），所以弹框确实只加两个参数就够。但现有的提交函数 onCreatePatientFrame2（refractive-record-pane.tsx:383-401）建完会跳进档案详情页，不能直接拿来用。→ 处理：新写一个提交函数，调 createChildForFamilyScan，完成后静默关闭并刷新列表，另外处理重名提醒。
🟡 列表页入口的「从本机构家长中选择」要单独写确认函数。平板现有的确认绑定（refractive-record-pane.tsx:479-503）依赖「当前打开的档案」activePatient，只更新详情页。→ 处理：3b 弹框界面原样复用，另写一个列表用的确认函数，绑定对象取「选档案层」选中的孩子，成功后刷新列表，行上的「已绑定/未绑定」要变。选档案层只列本店未绑定家长的档案，和手机一致（手机 page.tsx:542,549 .filter(p => !p.bound_seat)）。
🟡 表头一行挤了 4 样东西，没有防挤压兜底。表头（frame1-child-list.tsx:65）没有换行兜底，搜索框（:66）没有 min-w-0。左菜单手动展开（240px）加竖屏时，搜索框会被挤得很窄。→ 处理：搜索框加 min-w-0；验收时量两种宽度：横屏 1024 收起菜单、竖屏 768 展开菜单。

不需要改的：后端 0 改动的结论不变；手机端组件不动的结论不变。第 1 条改的是共用扫码工具，手机端要回归一次（iPhone 扫家长码一次）。

验收（做完后）

平板真页面（test，iPad 微信 UA）逐帧对照方案图
转店真打：平板扫家长码认领 / 现场新建 / 关联已有 / 从本机构家长中选择 / 机构码被家长扫，五条都走一遍，数据库查 service_org_id 前后两次
长官真机：店里 iPad 和安卓平板各真扫一次（9-28 长官答：店里两种平板都有）；手机门店端 iPhone 先测一次「先进首页再点视光档案 → 绑定家长 → 扫描家长二维码」能否打开相机，决定要不要改 wx-scan.ts 签名网址