业务方案 · 源码证据 · 实施边界

达人带货与设备 SN 绑定方案

把“哪个达人发出的家长账号，在什么门店绑定了哪台设备”记录清楚，为达人与门店对账提供可追溯依据。

讨论稿 v0.22026-09-20本轮仅整理方案与只读核验待业务评审，不是实施定案

01结论与已定案规则

推荐主线：复用家长子席位与现有机构体系，新增跨机构设备资产、设备绑定历史与达人归因台账。

设备不预先指定达人。达人来自账号发放归属；门店来自已核验的服务/互绑关系；设备来自 SN 二维码。三个维度独立记录，在绑定事件中形成快照。

已定案：长官明确确认建议：供讨论，尚未批准待核验：不能作为上线结论

事项	已定案内容
家长身份	目前家长端账号就是子席位账号；允许一个账号绑定多个实体设备。
设备资产	SN 跨机构统一管理；后台预导入，每个 SN 对应唯一设备二维码，不预指定达人。
绑定与归因	家长在智脑家长端扫码绑定；不增加门店二次确认购买环节；达人所属机构的子席位管理应看到对应家长、门店、设备、SN 和时间。
机构口径	一个门店对应一个机构；但账号来源机构与实际服务门店不一定相同，不能直接混用。
兼容要求	品牌码和现有子席位正常使用，设备码作为新增链路；设备标签保留登录码与设备码两个码。
视光档案	门店与家长互绑后，关联档案能在授权范围内看到；家长档案页抬头采用原门店 Logo + 门店名称，未配置时显示机构名称。
售后	长官倾向支持换绑；换绑权限、退货、换新及佣金处理规则尚未最终定案，详见第 6 节。

第一版建议只做“可查询、可追溯、可导出的绑定事实台账”，不直接做自动打款。扫码成功不等于已收款，也不等于已结算；双方可先按台账线下核对。

02必须分开的身份与门店边界

纠正前版方案：不能把 User.linked_org_id 直接当作购机门店。

当前源码已经区分 Patient.org_id（来源机构）与 Patient.service_org_id（当前服务机构）。一个账号下多个孩子可能由不同门店服务，账号列表中的“最新绑定门店”也不能直接当作所有设备的销售门店。

达人 / 账号发放归属

用于回答“谁发出的账号”。绑定设备、转店、换设备均不能自动改写达人来源。复用现有发号归属前，必须核验实际字段与权限。

当前服务 / 互绑门店

用于回答“谁在服务家长或孩子”。优先复用现有关系，不能通过修改账号归属来实现跨门店服务。

设备绑定时的门店快照

用于后续对账。记录绑定当时选择并校验的门店、选择依据和时间；以后转店不自动迁移旧设备的归因记录。

设备全局身份

SN 对应一台物理设备，不归某个达人独占。可以有售后与再次销售历史，但同一时刻只允许一个有效家长绑定，作为建议约束。

门店归属建议规则

只有一个有效服务门店：扫码时显示该门店给家长核对，由服务端校验关系后保存。
存在多个门店：让家长从已关联门店中明确选择本次设备对应门店；不能默认取最近一条孩子认领记录。
尚无门店关系：建议先保存设备绑定，归因记录标为“待补门店”，不编造门店、不计入某门店对账。补门店时记录补录来源、操作者与时间；是否必须先互绑再扫码，待长官确认。

以上是门店确定机制，不是门店确认购买。没有订单或销售凭证时，系统记录的是“账号与设备及门店的关联事实”，不应宣称已证明真实交易。

03业务主流程

STEP 01平台导入设备类型 / 名称 / SN
预校验后生成设备码

STEP 02达人发放账号使用现有家长子席位
固定可追溯来源

STEP 03家长互绑并扫码确定服务门店
家长确认设备信息

STEP 04形成绑定台账达人 / 家长 / 门店 / SN
支持查询与导出对账

3.1 平台导入 SN 与贴码

新增设备资产清单，复用可用的设备类型配置。导入文件先预检查、再确认入库；显示行级错误，不能把部分成功显示为全量成功。保留原始 SN 文本，前导零不丢；大小写、空格与厂商命名规则先确认，不擅自归一化。

校验空 SN、文件内重复、库内重复、设备类型有效性与名称；数据库唯一约束兜底并发重复。
同一文件重试不得重复创建设备；导入批次、成功数、失败数、错误行可追溯。
唯一设备码使用随机不可猜测标识并落库校验；随机标识不是天然防复制，泄露后需支持受控作废重签。
登录码沿用原流程，设备码仅进入绑定流程；扫错码明确提示，不串入品牌开通或账号创建。

3.2 家长扫码绑定

已登录且有效的家长子席位进入“绑定设备”；未登录先登录，登录后回到待绑定设备。
扫码仅解析设备，展示名称、类型与 SN；家长确认才产生绑定，单纯打开链接不写业务状态。
服务端从登录态取家长身份，解析达人来源并校验可选择的门店关系；不信任前端自报达人或机构。
在事务中检查设备可绑定、锁定并写入绑定关系与归因快照；同账号重复扫码返回既有结果。
成功页展示设备、SN、绑定时间、门店；后台列表按接口重新查询或刷新看到新记录。

3.3 后续新增设备

每个新增 SN 建立独立记录，不覆盖已有 SN。后台列表显示设备数与最近绑定信息，详情展示完整设备历史。分别记录首次扫码、成功绑定、最近扫码与关系结束时间；seat_bound_at 是微信身份绑定时间，不能复用为实体设备绑定时间。

04数据与接口设计建议

下列为概念设计，不是已存在的表或已实现接口。实际命名、字段类型、迁移编号与归属服务需立项时确定。

对象	关键内容	边界与约束
设备资产 `device_assets`	设备 ID、原始/规范化 SN、类型、名称/型号、码标识摘要、码版本、资产可用状态、导入批次与时间	按已定规则保证 SN 全局唯一；不设固定达人归属。库存去向可另加关系，不能把全局资产变成门店私有。
设备绑定历史 `seat_device_bindings`	设备 ID、家长席位 ID、成功绑定时间、结束时间、结束原因、当前状态、来源	一席位多设备；每设备至多一个有效绑定。历史只追加/结束，不硬删覆盖；来源为设备扫码，与席位开通来源分离。
达人归因事实 `device_attributions`	绑定事件 ID、账号来源、达人引用、门店快照、SN/名称快照、归因状态、售后关联 ID	每次有效绑定至多生成一条对应归因；无达人或无门店标记待补，不虚填；以后变更关联不回写历史。
扫码 / 操作事件	事件 ID、幂等键、操作者、设备、时间、结果、原因、请求追踪 ID	失败、重复扫码和售后动作可追踪；不得记录密码、完整令牌或无关健康信息。
账号达人来源	优先复用经核验的现有发号/批次关系；不足时增设显式来源关联与生效时间	`User.channel_id` 当前注释为渠道角色专用，不能直接塞进家长席位；不能默认机构签约渠道就是发号达人。
导入 / 标签任务	导入批次、校验结果、任务状态、生成数量、文件引用、重试信息	批量体量明确后决定同步或后台任务；标签、SN 清单下载受管理员权限控制。

约束与一致性

建议使用“有效绑定”的数据库唯一约束，并配合事务/行锁；仅靠前端禁用按钮不能防并发抢绑。
绑定与归因属于同一数据库时同事务提交；若跨服务，通过可靠事件/事务消息表与消费幂等处理，不要求用户替系统补写。
保存稳定 ID 和必要的展示快照；动态列表展示当前信息，历史对账展示绑定时快照。
UTC 存储，界面与按日筛选采用亚洲/上海时区，避免跨日统计错位。
绑定状态、设备维护状态、对账状态分别建模，避免一个状态同时表达退货、停用和已结算。

接口职责建议

接口类别	职责	权限
设备类型 / SN 导入 / 标签导出	校验、确认、批次进度、生成唯一设备码	平台授权管理员
设备码解析	只读校验码类型与状态，返回绑定确认页所需信息	有效家长登录态；不暴露他人信息
创建绑定 / 我的设备	事务创建、重复请求幂等、查询本人记录	本人家长子席位
子席位设备列表 / 归因导出	按被授权的达人来源与门店范围查询	平台、达人、门店各自受限范围
售后申请 / 审核	纠错、转让、退货、换新与审计链	申请人与具备范围权限的处理人员

物理设备管理不替代现有 DeviceData 上报数据，也不替代席位 current_device_id 登录终端。厂商上报标识是否等于设备 SN，需用真实样本核对，第一版不擅自串联健康数据。

05页面与导出

平台设备管理

设备类型配置、设备清单、SN 导入预检查、批次结果、二维码标签下载、设备详情与绑定历史。类型配置尽量复用，不把现有设备数据大盘替换成新资产页。

达人所属机构的子席位管理

保留现有账号列表，新增：当前关联门店、有效设备数量、最近设备 SN、最近成功绑定时间。设备抽屉逐台展示“设备类型 / 名称 / SN / 绑定时间 / 当时门店 / 当前状态 / 历史记录”。多门店显示“多个门店”，不得只留最后一家而丢历史。

门店侧与家长端

门店侧只看与自身有关的绑定/对账记录，不因 SN 全局唯一而获得全平台可见权限。
家长“我的设备”展示全部当前设备，区分“新增设备”“售后换新”“转让换绑”，避免每次操作都产生新增佣金。
家长与门店互绑入口复用已有能力；当前源码确认的是门店扫家长码认领及同机构档案绑定两类链路，双向扫码入口是否完整可用仍需真机核验。

对账导出建议：一行一条设备绑定/归因事件

归因记录ID | 达人/来源机构 | 家长账号 | 绑定时门店 | 设备类型 | 设备名称
SN | 首次扫码时间 | 成功绑定时间 | 最近扫码时间 | 结束时间 | 绑定状态
归因状态 | 售后关联ID | 操作备注

不导出账号密码、微信标识、孩子姓名及检查数据。手机号如确有必要应脱敏。导出筛选与页面口径一致，并验证权限与完整性；金额、付款批次等在正式结算阶段另行定义。

06换绑、退货与换新建议

建议支持换绑，但不允许后扫码的人直接抢走已绑定设备。

统一原则：结束旧关系、保留历史、创建新关系；每种操作有明确原因与授权。换绑不自动等于再次销售。

实际场景	建议处理	对账 / 佣金口径
同一人重复扫码	显示“已绑定”，返回原记录；仅更新最近扫码审计。	不新增归因或佣金。
扫错账号	由原账号申请或授权管理员纠错；记录理由，新旧关系关联。	纠错原事件，不直接新增销售机会。
家庭成员更换账号 / 赠送	旧主确认释放或受控人工核验后换绑；不得让新账号强制覆盖。	默认不产生第二次佣金；新持有人与原销售归因分开。
退货退款	家长可申请；有权限的售后人员核对线下事实后结束绑定、标记设备待检，不允许只点解绑就视为完成退款。	未结算记录标为取消/待调整；已结算保留原记录，后续增加调整单，不直接抹除。
质量问题换新	记录原 SN → 新 SN 的换新链；新设备重新绑定，旧设备待检/停用。	默认沿用原销售归因，不重复计佣；金额差异待规则明确。
退回设备再次销售	检验并授权重新上架后开启新销售周期，再绑定新家长。	是否允许再次计佣需定案，不能仅凭重新扫码判定。
家长转服务门店	改变当前服务关系，不回写旧设备绑定时的门店快照。	历史归因仍归原记录；新设备单独确定门店。

第一版可只提供受控的管理员售后处理与历史查询；自助转让、复杂退款及自动财务冲销在规则批准后再实现。不要求门店确认每次购买，不等于售后无需核对。

07权限、安全与现有系统兼容

角色	建议可见与可操作范围
平台管理员	全局设备、导入、标签、经授权纠错、全量审计。
达人 / 来源机构	只看自己发放账号的设备归因及必要门店信息；不获得家长健康档案访问权。
服务门店	只看关联本店的设备/对账记录；档案访问继续受现有可见性规则约束。
家长子席位	绑定、查看本人设备，发起售后申请；不能查看其他家长身份或发号内部信息。

现有登录码、品牌码、设备码分开解析。品牌码仍负责原有开通逻辑；设备码不自动新建子席位，不触发品牌激活、不修改到期规则。
不改写 seat_source。它表达账号开通来源；新增设备扫码来源写到设备绑定事件，不能把已有来源覆盖成“设备码”。
只在智脑登录态完成绑定。外部扫码最多进入智脑登录/确认页；不能只靠 User-Agent、来源页面或前端传参当安全边界。
固定贴纸可能被拍照复制。随机码可降低枚举风险，不能证明购买。需配合速率限制、尝试次数审计、唯一有效绑定和异常纠错；是否增加遮盖涂层/厂商激活凭证，后续讨论。
全局资产不等于跨机构可随意查询。SN 列表、二维码导出与记录详情均需后端授权。
设备解绑不解除家长档案权限边界。达人不能因归因关系读取孩子资料，转店不能扩大旧门店可见性。

08档案关联与门店抬头

要分清两件事：档案归属 / 可见性与页面品牌展示。设备扫码本身不迁移档案；应复用现有门店—家长/孩子关联，避免重复建档或改错所有权。

品牌头图

“品牌头图保持原品牌”与“档案内门店抬头”可以并存。建议不把品牌大图全局替换；具体适用页面范围仍待确认。

视光档案门店抬头

使用当前档案合法服务门店的 Logo + 门店名称。未配置门店显示名时回退该机构名称；无 Logo 不显示破图，也不误用账号来源品牌 Logo。

先核验当前档案的服务门店与授权；多孩子/多门店时逐档案计算，不能只取登录账号机构。
复用现有 homepage_logo_oss_key、store_nickname、机构 name 及资源签名逻辑；样式复用原门店组件。
未绑门店时明确显示未关联状态或既有默认展示，不伪造一个服务门店。具体默认呈现由页面定案。
列表、详情、分享、导出是否都改抬头需分别确认；本次最低范围是家长视光档案页。
历史报告是否固化门店名称/Logo 快照属于后续选择；不应因本次页面需求擅自增加历史回填。

本轮已核实机构存在相应字段及资源函数，尚未真机复现当前抬头错误，也未确认全部布局组件取值链，不能把“字段可复用”写成“只改某一行即可”。

09分阶段实施与发布边界

下面使用阶段名称，不虚拟分配项目正式 Phase 号。正式开发先完成需求变更立项，再按当前项目编号登记。

阶段	内容	进入下一阶段的条件
V0 规则与基线	确认达人字段、门店确定方式、售后口径；最新 test 基线再核验路由、鉴权、数据库和现有页面。	关键待拍板项明确；提交号、字段、约束、影响面有证据。
V1 设备资产	类型复用、SN 导入、全局唯一约束、设备码、标签与管理员页面。	真实数据库重复/并发导入验证；标签实际扫码可识别；老流程不变。
V2 绑定与归因	家长扫码、多设备、门店关系校验、达人快照、后台显示与导出。	真实家长账号、跨机构场景、多孩子多门店、重复扫码与并发抢绑通过。
V3 售后闭环	受控纠错、解绑、换新链、退货待检、调整审计。	旧历史不变；换新不重复计佣；无授权不能抢绑。
并行项：门店抬头	档案上下文取值、原组件复用、名称回退与 Logo 异常处理。	品牌头图不误改；服务门店与来源机构不同的实测证据。
后续项：自动结算	金额规则、结算批次、确认、支付与冲销；如要对接现有结算服务，独立评审。	业务与金额规则确认；使用结算域实际模型/API，不能使用旧占位模型。

开发与发版纪律

从当时最新 origin/test 创建功能分支与独立 worktree；不在主仓 work/dev2、main、test 上改业务，不触碰预存脏文件，不 pull/reset 陈旧主线。只推功能分支，按正式 test/prod 发布流程执行。本次只发布方案文档，不提交、不推送、不发布业务代码。

10验收清单与证据要求

以下是待执行的验收，不是本轮通过结果。测试必须真实 PG、真实服务、真实请求；涉及相机和扫码跳转需真实浏览器/真机验证，不用 mock 结果冒充。

维度	最低场景	应留证据
1. 导入与唯一性	空值、重复文件、库内重复、前导零、异常字符、并发导入	校验结果、数据库真实约束、前后计数
2. 码与身份	登录码/品牌码/设备码区分，未登录、过期/伪造/停用码	实际接口状态、绑定无副作用、真扫码画面
3. 并发与幂等	双击、网络重试、同账号复扫、两家长并发抢同 SN	请求追踪、最终仅一个有效关系、归因不重复
4. 多设备	同账号新增多个 SN、历史设备结束、列表聚合与明细一致	真实数据与页面/导出逐项对照
5. 门店归属	来源机构不等于服务门店，无门店，多孩子多门店，后续转店	归属 ID、门店选择校验、历史快照不漂移
6. 达人来源	有来源、无来源、变更来源、与机构签约渠道不同	发号链路、归因事件、权限对照组
7. 越权与隐私	他人 seat_id、跨门店查 SN、越权导出、达人查看档案	拒绝响应、数据不可见、日志无敏感凭据
8. 售后	误绑、赠送、退货、换新、退后重售、无权抢绑	新旧事件链、原因、调整而非删除历史
9. 老功能回归	品牌码激活、旧子席位登录/到期/微信绑定、门店认领	真实老账号对照，原行为不变
10. 门店抬头	有/无 Logo、有/无别名、多门店、图失效、品牌头图	截图及服务端展示来源；不串机构
11. 导出完整性	超过默认分页规模、筛选、权限、时区边界	数据库符合条件计数与导出行数一致
12. 部署与回退	新迁移约束、功能开关、旧版本兼容、任务失败重试	构建/源码版本、真实表结构、正式发布记录

开工前与完工后至少复核“源码调用链、数据库约束、真实接口、真实页面”四类证据，覆盖上述风险维度。源码有测试文件不等于测试已运行，注释写完成不等于功能已验收。

11下一轮沟通需拍板的事项

问题	当前建议
达人在现有系统中的业务身份是什么？	先核对实际发号主体/批次归属，不直接等同于 Channel 或机构签约渠道，不为此重建一套账号体系。
无门店或多门店时怎么绑定设备？	无门店可先绑定但标为待补门店；多门店由家长从有效关联门店明确选择，并由服务端验证。未补齐不计入具体门店台账。
已绑设备换人由谁确认？	原账号发起/确认，或授权管理员人工核对；不允许新家长直接抢绑。家长自助能力可后置。
退货、换新、二手转让是否计佣？	换新/赠送默认不重复计佣；退货走取消或后续调整；重新销售是否新计佣由双方规则确定。
第一版做到哪里？	设备管理、家长绑定、门店与达人归因、后台查询导出、受控售后；金额与自动打款不纳入第一版。
SN 与厂商 device_id 是否一致？	拿真实标签与上报样本核验；未确定前两套数据独立，不自动把遥测数据暴露给绑定者。
品牌头图与门店抬头的页面范围？	建议品牌首页/大图不动，家长视光档案内抬头切门店；分享图和导出报告单独确认。

12源码证据索引：已做什么，未做什么

本轮是固定提交的静态源码核验，不是完整上线验收。

核验基线为云机当前缓存的 origin/test 引用 2040a3196672800beca23a6abcee515e55717bad。本轮没有 fetch，不能称为上游实时最新；主仓 HEAD 为 f35d9d486a89，其落后 976 提交和预存脏文件是正常状态，未处理。检索只读取指定提交，不切换工作区。

本次补做了 12 个维度的定向检索与关键行读取。下表列出可复核的路径、行号、符号及结论；不是全仓所有实现的穷尽证明。上一版基于旧主仓推断“无品牌码实现”等结论不再沿用。

维度	固定基线证据	能支持的结论 / 边界
E01 用户与席位	`app/models/user.py:58–70,80–107,121–154` linked_org_id、channel_id、current_device_id、seat_bound_at、seat_type、seat_source、created_by_seat_id	家长席位应区分 parent 类型；登录设备、微信绑定时间与实体设备绑定不是同一概念。channel_id 注释为渠道角色关联。
E02 席位服务与鉴权隔离	`app/services/seat_service.py:16,51,109–118` `app/api/admin_seats.py:6–13,66`	已有 linked_org_id 机构隔离；seat_bound_at 是微信绑定。新跨机构设备关系不能直接改账号所属机构绕过隔离。
E03 来源与服务门店	`app/models/flywheel.py:52–54,71–83` owner_seat_id、service_org_id、service_org_bound_at	孩子所属家长与服务机构为平行关系；原方案“直接取 linked_org_id 为销售门店”不成立。
E04 两种档案绑定	`app/api/refractive_records.py:167–194` `app/services/brand_code_claim_service.py:3–12`	同机构门店把档案绑给家长，与跨机构服务认领是不同动作；不得混用接口。
E05 设备数据模型	`app/models/device.py:16–33,41–67` DeviceData、DeviceTypeConfig、UserPhoneVerification	现有 device_id 注释为甲方自定义设备标识，不等于已核实的实体 SN；已有数据模型与类型配置可按职责复用。
E06 家长设备查询	`app/services/device_service.py:76,88–101`	已读取链路使用经验证手机号查询 DeviceData，不能直接当作新席位设备资产绑定链路。
E07 设备管理 API / 资产检索	`app/api/admin_devices.py:17,49–110` 在 `app/models`、`migrations/versions` 检索设备类、device_assets、seat_device_bindings	设备类型接口存在并有管理员守门；该范围只命中 DeviceData 与 DeviceTypeConfig。未检出拟议新表名，不代表已查尽所有同义实现。
E08 二维码与品牌码	`app/api/qr.py:23–35` `app/api/brand_code_public.py:22,41–44` `web/app/h5/brand-scan/page.tsx:10,69`	通用 QR PNG 与品牌码激活流程均存在。二维码绘图接口不承担设备身份发行、登录鉴权或防复制。
E09 服务门店扫码与汇总	`app/api/brand_code_claim.py:39,57–58,87–91,117–121,161–165` `app/api/admin_brand_code.py:180–234`	家长码、门店 resolve/claim/release 接口存在；品牌码列表按孩子最新 service_org_bound_at 汇总门店。这是列表展示，不足以作为每台设备的历史销售门店。
E10 子席位后台	`web/app/(dashboard)/admin/orgs/[id]/seats/page.tsx:18,74,86,432,486`	存在设备/微信绑定等旧展示，不能把当前“设备已绑”字样当作实体 SN 资产绑定；家长子席位新页面也需开发前专门补核。
E11 门店品牌与结算	`app/api/h5_store_card.py:188–203` `app/models/settlement.py:3–9,14–18`	门店 Logo 与品牌头图有不同字段；旧 settlement 模型明确是外键占位，真正结算业务模型位于独立子域，不能拿旧类写结算。
E12 迁移与测试文件	`migrations/versions/phase48a_001_brand_code.py:4–9,78` `tests/integration/test_brand_code_claim.py:3` `tests/integration/test_refractive_visibility_service_org.py`	品牌码迁移及相关测试文件存在。本轮未运行测试、未检查真实 PG 的迁移状态，不报告“测试通过”。

关键证据摘录与复核方法

固定提交：2040a3196672800beca23a6abcee515e55717bad

app/models/flywheel.py:71
org_id = 谁带进来的(品牌方) · service_org_id = 谁在服务他(门店认领后落此列)。

app/models/user.py:64
channel 关联 · 仅 role='channel' 非空

app/models/user.py:83
席位当前活跃设备 · 新登覆盖=被动踢旧

app/services/seat_service.py:51
不看 seat_bound_at(那是微信身份绑定,跟席位到期是两回事)

app/api/admin_brand_code.py:184–185
当前绑定机构/绑定时间：取 service_org_id 非空、service_org_bound_at 最新的一条。

app/models/settlement.py:3–8
本文件仅作 FK 占位，严禁当业务模型用；
结算域唯一活模型 = settlement/backend/app/models/settlement.py。

复核方式：在指定提交对各维度路径检索上述符号，记录命中行；
再读取关键模型、路由、服务上下文，区分注释、真实实现与待测试行为。
原始定向检索展示设置了行数上限；不能把未展示内容当成不存在。

仍未完成的物理验证

最新上游重新取基线与新家长子席位页面、达人发号关系的完整调用链。
真实数据库表结构、约束、迁移落地情况与真实 SN 样本。
门店/家长双向扫码、跨机构档案可见性、当前 Logo 错误的浏览器与真机复现。
拟议新设备功能的任何运行、接口、并发、负载或售后测试；功能尚未开发。

源码注释存在历史待办文字，而同基线服务代码已出现 service_org_id 可见性过滤。因此本稿不把旧注释作为当前故障结论，必须以真实调用链与实测判定。