交付出件箱

← 返回出件箱

Phase 48B · 扫码绑定 · 技术方案 v0.1

2026-09-24 · 阶段 3 architecture · 基线 origin/test fb0dc9d7 · 分支 feature/scan-binding-48b
上游：需求原文 ~/reports/brand-partner-spec-v1-20260915.md（Phase 48 · 规则 9/10/13/14/16/18）·
总方案 ~/reports/home-redesign-master-plan-20260924.md 第五节 · 方案 ~/reports/scan-binding-plan-v1-20260924.md ·
方案图 scan-binding-realpage-v1-20260924.html（长官 9-24 晚过目通过，「还没有账号」提示页保留；9-24 深夜定 D1–D3，图随之增量补 5g、改一行）
本文不写测试代码、不写完整实现代码。所有「文件:行号」均为本分支物理 grep/sed 结果（见第二节证据）。

〇、结论先行

一、编号与登记

• Phase 48 = 品牌方合作（9-15 立项，需求原文在 ~/reports/，仓库文档此前 0 行）。48A 品牌码 + 机构扫码认领后端：origin/main 上 phase48a 提交 23 个，代码注释统一写「Phase 48A 批N」；本期 48B = 扫码绑定（两端扫码 + 可见性修复 + 现场新建）。
• 本期同时在 flywheel-progress.md / flywheel-impl.md 补登 Phase 48 一行（48A 已上生产 · 48B 🔄）。
• 与 Phase 83（子席位批次一~五，含登录改造）的关系：83 管席位与登录，48B 管档案归属。两者共用 seat_service.py / seat_auth.py / app/main.py；48B 只调用、不修改这三个文件（第八节冲突面）。

二、物理核查证据（15 维）

方法：派 5 个只读助手分查（第 5 个为独立审查后补查记录级读写），每路把全部命令写成可重跑脚本，输出原样落盘；主会话亲手重跑 5 个脚本并 diff：VA/VB/VD/VE 逐字节一致，VC 仅第 4 行时间戳不同。另派 1 个没参与的审查员对照代码挑错：查出记录级读写遗漏（已补为 V15 与 4.1 第 5、6 条）、两处行号偏差（已改）；它报的 seat_auth.py 路由行号偏差经主会话复核不成立（装饰器就在 :463）。数据库 3 路由主会话亲跑（生产走 seatops 通道，避开 db-prod 的 RLS 假 0）。
证据归档：~/reports/48b-verify-20260924/（VA–VE 的 .sh / .out / 结论，md5 与 /tmp/48b-verify/ 源一致）。0 命中项均带对照组。

V14 数据底数（2026-09-24 22:0x 实查）

⚠️ 纠正：第 9 轮写的「一个微信绑多个家长账号，生产 0 个」（引自登录改造会话）按 openid 实查是 1 个。不影响「默认用当前登录账号」的决定，但没登录时的多账号兜底必须做（第九节 D2）。

三、现状问题（为什么要改）

场景：孩子 P，org_id=A，家长席位 S（S.linked_org_id=A）名下，被机构 B 扫码认领后 service_org_id=B。读现有代码推演（VA ### A-8，静态推断，48B.1 第一步用真 PG 测试复现）：

即：48A 的认领接口一旦被真正用起来，孩子会同时从新机构和家长本人那里消失；原机构还能继续改旧记录。生产认领 0 行，所以还没人踩到。

四、后端改动

4.1 档案与记录读写门（refractive_record_service.py + parent_patients.py）

1. 家长视角去掉机构外层门（_patients_filtered_stmt :175、get_org_patient :613）
2. 家长分支（owner_seat_id is not None）只用原有 own_clause（及原有 is_sample 豁免），不再 AND _org_visibility_clause；门店分支原样保留「外层门 AND _store_visible_clause」。
3. 函数签名不变（org_id 参数在家长分支不再参与过滤），11 个调用点不用改。
4. 安全性：own_clause 按 owner_seat_id == 本席位 id，席位 id 唯一，家长只能看到自己名下的孩子；示范档案豁免逻辑逐字不变。
5. 存量：家长名下孩子所属机构≠家长机构 0 行、已认领 0 行 → 现有家长看到的集合不变。
6. 门店视角认「当前由本机构服务」（_store_visible_clause :79）
7. 在现有两个分支之外 OR 第三个分支 Patient.service_org_id == org_id。
8. 与外层门叠加后：B 能看到并编辑自己认领的孩子（规则 18「能看=能改」）；A 列表看不到，只读历史走现有 allow_past_author 小门（规则 10）。
9. 只读小门只认机构自己录的记录（_org_ever_authored_clause :135）
10. 追加 ~_parent_created_clause()（:156）。
11. 原因：改完第 1 条后，家长在孩子转走后仍能录记录，而 create_record 把记录的 org_id 记成家长账号机构（:1063 起，org_id=org_id）→ 不加这条，原机构会因为「家长自己录的记录」重新获得只读访问。规则 10 原文是「只剩自己当初录的那几条」。
12. 存量：记录机构≠档案机构 0 行 → 现有访问不变。
13. 写路径核对（不改代码，列清楚）
14. 家长写接口全部经 get_org_patient(owner_seat_id=S) → 随第 1 条恢复。
15. 机构 B 写接口经门店视角 → 随第 2 条放开。
16. 原机构 A 档案级写路径不传 allow_past_author → 仍不能改（记录级见第 6 条）。
17. bind/unbind_patient_seat 限定 owner_type∈(NULL,'seat') → 家长名下的孩子 B 不能解绑家长（与现状一致）。
18. 家长看得到孩子的全部记录（不论哪家机构录的）
19. 时间线 patient_timeline（:750-756）：家长视角（owner_seat_id 有值）恒走「全部记录」分支；门店视角两个分支原样不动。
20. 家长记录详情（parent_patients.py:629-634）：去掉 RefractiveRecord.org_id == seat["org_id"]，保留 id + patient_id（上一步 get_org_patient(owner_seat_id) 已证明孩子是本人的）；「家长不见草稿」等原有限制不动。
21. 标已读 mark_conclusion_read（:3441-3447，唯一调用方 parent_patients.py:841，调用前已 :836 验归属）：去掉按记录机构的过滤，保留 id + patient_id。
22. 家长改记录（parent_patients.py:1115-1117）不动：只允许改家长本人录的，这些记录的机构恒为家长账号机构。
23. 原机构不能再改旧记录（记录门 _fetch_record :929）
24. 加末位参 require_current_org: bool = False：为 True 时追加「孩子当前归本机构」= EXISTS(Patient.id == 记录.patient_id AND (_org_visibility_clause(org_id) OR is_sample))。示范档案保留放行，照旧由拿到记录后的 _reject_if_sample_record 给 403。
25. 传 True 的 6 处：patch_record（:1126）、patch_conclusion（:3391）、push_conclusion（:3409）、delete_draft_shell（:3518）、complete_record（:3636）、trigger_analysis（:3203）。
26. 只读的 get_record_dto、parent_view_dto 不传 → 原机构仍能看自己录的旧记录（规则 10）。
27. 存量：记录机构≠档案机构 0 行、已认领 0 行 → 对现有数据判定结果不变。

4.2 放宽「绑定家长」到跨机构（R3 · bind_patient_seat :539）

• 加末位关键字参数 allow_cross_org_parent: bool = False：为 True 时，目标席位只校验 role='org_seat'、seat_type='parent'，不校验 linked_org_id == org_id（:569 那一条）。
• 只有第 4.4 节两个「凭家长码」接口传 True；现有 /patients/{id}/bind（refractive_records.py:167）不变，仍只能绑本机构家长。
• 目标席位查询本身不校验 is_active（:565-574，老问题）。跨机构路径的席位一律来自 _get_family_seat_or_404（brand_code_claim_service.py:49，已校验 is_active），所以这个老问题不会因放宽而扩大；本期不动它。

4.3 建档加一个末位参数（create_patient :386）

• 加 service_org_id: Optional[int] = None：有值时在同一次 commit 里写 service_org_id 与 service_org_bound_at=now。默认 None → 现有调用逐字节不变。
• 用途：机构 B 为扫到的家长 S 现场建档，一次写成「S 名下（owner_type='parent'，org_id=S.linked_org_id）、由 B 服务」的状态，与家长自己建档后再被 B 认领的状态完全一样。只有一套状态，可见性和解绑回落（规则 18）都不用另写。
• 为什么不是「先建档、再认领」两步：两个函数各自 commit（:458、:136），中间失败会留下半成品。

4.4 认领服务与接口（brand_code_claim_service.py + brand_code_claim.py，全部挂在已注册路由 /api/h5/brand-code-claim 上，不改 main.py）

服务层

接口

没登录时怎么认人

1. 解 wx_identity_token，调 lookup_seat_username_by_wx(unionid, openid, db, return_all=True)，只留 seat_type=='parent'。
2. 按结果分三种：
3. 0 个 → 404 {code: "no_parent_account"} → 前端显示「还没有开通智脑账号」
4. 多于 1 个 → 409 {code: "multi_parent_account"} → 前端显示 5g 提示页
5. 恰好 1 个 → 按 username 取席位
6. 两个 claim 接口都复用现有防越权：孩子必须在 list_family_children(席位) 里，否则 404；认领恒 force_transfer=True（家长本人扫码即本人意愿）。
7. 只绑定、不签登录令牌：没登录路径绝不下发 access/refresh token，否则等于绕过密码登录。

lookup_seat_username_by_wx 不按机构过滤。品牌码开通特意不用它（brand_code_service.py 文件头：防止把两家机构的席位错误合并）；本件不建号、不合并，只是找这个微信本人的家长账号并做跨机构绑定，所以正需要不过滤机构。

4.5 机构码令牌（app/auth/jwt_local.py，照 :251/:269 家长码写法）

• 新增 issue_org_bind_token(org_id) 和 decode_org_bind_token(token)。
• 令牌内容 {type: "org_bind", org_id, iat, jti}，HS256 + JWT_SECRET_KEY；类型不符或验签失败 → 401。
• 不设过期：码要打印贴在前台长期使用。
• 已知限制：印出去的码不能单独作废，要作废只能换密钥（全站令牌一起失效）。能力上限是「把自己的孩子绑到这家机构」，泄露也只是多一个入口。要单独作废得建表，本期不做。
• 解出的机构不存在 → 404。

五、前端改动（对应方案图「全部改动一览」12 行）

共用扫码工具（新） web/app/h5/chat/lib/wx-scan.ts，放在 wx-oauth.ts 旁边：

• 流程：注入 jweixin-1.6.0（同 share/[token]/page.tsx:232）→ POST /api/wx/jssdk-config {url: location.href.split("#")[0]} → wx.config({jsApiList:["scanQRCode"]}) → wx.scanQRCode({needResult:1, scanType:["qrCode"]})，返回 resultStr；取消、报错分别 reject。
• 不在微信里（isInWeChat()，wx-oauth.ts:22）：一律隐藏扫码入口（长官早先定：不在微信里隐藏扫码项）。

SeatWxAuthLanding 的新参数默认值为现有写死文案，现有 3 处页面调用（brand-scan/page.tsx、chat/page.tsx、tablet/page.tsx）和组件测试 chat/components/__tests__/seat-wx-auth-landing.spec.tsx 不受影响。

落地页状态（第 11 行 · h5/org-bind/page.tsx）

• 已登录家长（getSeatToken() 有值且 getSeatType()==="parent"）→ org-scan/children → 选孩子（5c）；没有孩子档案 → 5f。
• 其余情况（没登录，或这台手机登的是门店席位）：
• 5a「确认身份」（组件传入机构名文案）→ startSeatWxOAuth(当前地址)（wx-oauth.ts:36）。
• 带 code 回跳 → POST /api/seat/wx-identity 取 wx_identity_token → org-scan/children-wx。
• 按结果：没账号 → 5e；多个账号 → 5g「这个微信绑定了多个智脑账号 / 请先登录要绑定的账号，再扫一次」+「去登录」（长官 9-24 定 D2）；有孩子 → 5c；没孩子 → 5f。
• 5c「确认绑定」→ claim 或 claim-wx → 5d 绑定成功。
• 5d「查看孩子档案」：已登录 → /h5/family/{id}；没登录 → /h5/family（现有门禁 :76-79 会带去登录）。
• 5f「新建孩子档案」→ /h5/family/new。
• 身份令牌过期（10 分钟）→ 提示「页面已过期，请重新扫码」。
• 文案定稿（2026-09-25 长官令精简）：
• 5a 副标题「需要先确认您的微信身份」（按钮下灰字「点击后将跳转微信授权页确认」为组件自带 seat-wx-auth-landing.tsx:55，不动）
• 5c 列表下只留一行「XX 将从 YY 转到这家机构」
• 5e「您还没有智脑账号」/「请联系前台工作人员开通，开通后再扫一次」
• 5f「新建后再扫一次即可绑定」
• 非机构码提示「未识别为机构二维码」/「请扫机构前台的二维码」

六、边界清单

七、测试计划（真 PG · 禁 mock · 新文件 tests/integration/test_scan_binding_48b.py）

先写失败测试证明第三节的问题（RED），再改代码（GREEN）：

• 前端：next build 必过（9-21 教训：dev/tsc 查不出多导出等构建错）。
• 真机：发 test 后长官用两部微信走完三条流程。iOS 微信单页路由下 JS-SDK 签名地址是已知风险点，现有页面同一写法在线上可用，仍以真机为准。

八、影响面与发版

• 后端 5 个文件：refractive_record_service.py、parent_patients.py、brand_code_claim_service.py、brand_code_claim.py、jwt_local.py
• 前端改 6 个：store-refractive/page.tsx、[patientId]/page.tsx、_components/create-patient-sheet.tsx、_components/bind-parent-sheet.tsx、family/page.tsx、chat/components/seat-wx-auth-landing.tsx
• 前端新增：chat/lib/wx-scan.ts；_components/bind-method-dialog.tsx、_components/select-child-dialog.tsx；页面 store-refractive/org-code、family/my-qr、org-bind
• 冲突面：登录改造本地分支动了 app/main.py、seat_service.py，本件都不动；本件动的文件不在 verify-trigger-files.txt，不触发对话全流程守门。
• 生产一致性：本件要动的文件 main 与 test 一致 → 发生产只带本件 MR。
• 发版：feature/scan-binding-48b → release-to-test --yes → 长官真机扫码 → release-to-prod --mr <号>。

九、长官已定（2026-09-24 深夜）

十、子步骤（impl 用）