01 · 身份来源小程序负责注册登录并获得 ONEID;AgentOS 不代办小程序注册。
02 · 首次体验会员身份校验后,未关联的 ONEID 创建 AgentOS 用户;已有用户复用。
03 · 多卡与主账户ONEID 可关联多张卡。Token 归集至创建最早的 AgentOSID,原卡和历史数据保留来源。
04 · 码的边界卡正面身份码用于点位登录;背面太阳码用于小程序绑定。会员码转换仍需 AIVA 接入。
历史方案全文与评审记录(v6 · 不作为当前接口契约)
旧文中“未开发”、建议路径和账户待定描述属于设计阶段;当前交付状态见文档总览,开发契约见独立接口文档。
2026-09-30 · 评审稿,未开发、未联调。本次仅设计身份流程、通信与接口,不修改服务端或小程序代码。
1. 已确认的主流程
- CONFIRMED:访客通过扫门店卡背面带参太阳码,或自行注册小程序,获得 AIVA ONEID。注册、登录、验证码等由 AIVA 小程序负责,与 AgentOS 无关。
- CONFIRMED:扫太阳码后,小程序保留并关联该码参数;注册或登录成功后调用 AgentOS 绑定接口。业务核心参数为 AgentOSID、ONEID,其他字段交由小程序端评审。
- CONFIRMED:点位登录支持门店身份卡的身份二维码,或 AIVA 小程序会员二维码;不能把背面太阳码当成点位身份码。
- CONFIRMED / 术语映射:本文 AgentOSID 对应现有
agentos_user.agentos_uid;ONEID 对应 one_id;Token 就是 AgentOS 积分。绑定后仍引用原有 AgentOSID,其历史画像、作品、Token和互动记录不重新建账、不复制。
- CONFIRMED(2026-09-30补充):同一个ONEID可以绑定多张门店身份卡。每张卡仍对应原AgentOSID,多个AgentOSID的数据合并追加关联到同一ONEID,既有绑定不被新卡覆盖。同一ONEID已有其他卡不再是绑定冲突。
- CONFIRMED(2026-09-30首访补充):访客直接出示小程序会员码时,点位验码成功后,若ONEID尚无AgentOSID关联,AgentOS执行新建用户流程并同时关联该ONEID,再进入互动。已有关联则复用,不能每次扫码都新建。此路径不要求先领取或生成门店身份卡。
- PROPOSED:绑定由 AIVA 小程序服务端调用 AgentOS;ONEID来自其已认证登录会话,不信任用户手填或前端自行传入的身份。服务端应用鉴权和参数携带的绑定证明分开校验。
2. 用户流程图
矢量图 · 可放大、滚动与下载
3. 通信泳道图
泳道中的 G 编号对应现有后台能力,其余为本次建议接口。参数解析失败时不进入绑定;绑定成功才展示已绑定。注册登录泳道不调用 AgentOS。
矢量图 · 可放大、滚动与下载
4. 两个二维码与后台制卡
PROPOSED:使用独立随机 bind_scene。 它在 AgentOS 映射到卡和既有 AgentOSID,不直接使用可枚举的ID,也不复用正面登录短码。小程序服务端通过B02取得AgentOSID,再以AgentOSID + ONEID调用B03。直接把AgentOSID作为太阳码参数是另一个待评审方案;即使采用,也不能把公开ID本身当成绑定授权证明。
带参码生成由 AIVA小程序侧提供能力:AgentOS按批次准备每卡参数,AIVA返回对应码素材供印制;小程序注册期间必须保留参数。接口形式、码页面、参数格式/长度、码有效性、素材交付方式由小程序端确认;本稿不冒充已确定的微信协议。
后台调整建议:
- 批次详情 / 制卡导出:在现有身份码旁增加每卡太阳码参数、素材准备状态及成对导出;所有成对素材须能反查同一张卡。未生成或生成失败的太阳码明确展示,不标为可印制。
- 卡明细与ONEID身份详情:ONEID详情展示所有已绑卡、门店、AgentOSID及各自来源,支持查看汇总画像、作品、Token记录和互动历史;继续绑卡只追加关系。卡明细展示AgentOSID、ONEID掩码、绑定时间、绑定来源、最近同步结果;普通列表不展示两种码的敏感原始值。
- 绑定记录:复用现有ONEID关联记录入口,补充请求编号、卡、结果、冲突原因、同步查询入口。不得新增无审计的人工改绑。
- 状态分开表达:印制/作废、是否首次点位激活、是否绑定ONEID是不同维度。允许先扫码注册绑定、后进点位互动,不能因绑定而伪造首次点位激活时间,也不能重复发放注册/激活奖励。
- 挂失:保留现有挂失入口;绑定时重新检查卡有效性。已绑定卡挂失后是否影响会员码访问原账户,列入评审,不能默认解绑、删用户或冻结整个账户。
接口文档
接口已移至独立的开发者接口文档,旧建议路径不作为当前调用契约。
6. 异常、幂等与同步边界(PROPOSED)
绑定关系、卡关联时间、成功记录须同事务;失败/冲突尝试亦须可追溯。批量制卡中的参数与码素材逐卡对应。绑定成功后,该AgentOSID历史及后续数据均纳入ONEID的关联数据范围;这是AgentOS内部归集,不等于已把全量数据推送到AIVA官方服务。
会员码首访建档(已确认)
- 点位把会员码交给P01,AgentOS调用M02完成可信验码,获得ONEID。验码失败时不创建用户。
- 在当前租户内查该ONEID的关联集合:存在则复用;不存在才执行AgentOS新建用户流程、生成AgentOSID并关联ONEID。
- PROPOSED事务设计:按租户与ONEID对首访创建操作做并发串行保护,进入保护后重新查询,防止不同点位/不同请求号并发建立重复用户。不能用ONEID单独唯一索引禁止后续多卡追加关联。
- 新建用户与ONEID关联须作为一致性操作;初始化账户、创建来源/首次到店记录、关联记录等复用平台建档规则。基础Token赠送沿用平台已确认的可配置规则,余额与流水同事务、幂等一次;本设计不补猜测赠送金额或新触发时点。
- P01确认创建及关联成功后才返回互动身份会话;建议响应补充
createdUser。没有实体卡时不伪造卡号、不插入实体来宾卡、不写卡激活时间;后台用户档案标识会员码建档来源,来宾卡模块只显示实际存在的卡。
- 用户以后再绑定门店卡时,该卡AgentOSID追加到同一ONEID,首访创建的AgentOSID及历史数据保留。新建用户是AgentOS内部流程,小程序注册登录仍完全属于AIVA侧;无需小程序先取得新AgentOSID再回调才能登录。
P01内调用统一用户创建与关联服务即可,不因首访新增一套对外“注册小程序”接口。多AgentOSID情况下的新互动写入归属与实际扣费路由仍需定义,本次确认的是无关联ONEID的首次创建。
一对多数据归集设计
关系为:ONEID → 多个 AgentOSID → 各自的门店身份卡、画像贡献、Token流水、作品与互动记录。允许同店或不同店的多张卡;访问与聚合仍在已授权租户范围内,不因ONEID相同跨越租户授权。
例:ONEID O 已关联卡A / AgentOSID A,再绑定卡B / AgentOSID B,结果为 O 同时关联 A、B;A、B 原始数据均在 O 下可查。再次提交 B+O 返回原关联,不重复追加同一条数据。
PROPOSED实现:以关联关系汇总原数据,保留原AgentOSID和门店来源,不为“合并”而批量改写原记录主键或复制历史流水。新增数据按关系持续纳入,不是一次性复制快照。作品/互动记录追加集合,画像保留各来源贡献;单值画像的冲突计算须另行明确。Token账户及流水按来源可查;可消费统一余额、跨账户扣款与冲正策略尚未确定,不把汇总展示当作扣费已实现。
门店卡登录能够明确本次卡对应的AgentOSID,并读取其ONEID的聚合资料;未绑定卡仍使用本卡资料。会员码登录识别ONEID及全部关联AgentOSID,不能随机取第一张卡、最新卡或本店卡作为写入/扣费账户。会员码场景的新记录归属和多账户扣费规则需进一步定义;当前图只承诺身份识别及关联读取。
历史文档中“一ONEID只能绑定一个AgentOSID”及conflict_one_id_bound作为多卡拒绝条件的设计被本次决定覆盖;“本卡已绑定另一个ONEID”仍属不同问题,不等于获准跨ONEID改绑。
7. 小程序侧评审清单
- 带参太阳码的页面、参数名/格式、码生成交付方式;是否采用独立
bind_scene;登录前后参数保留机制。
- B03两核心参数之外需要哪些字段;应用鉴权、扫码绑定证明、幂等、回执/查询协议。
- 会员二维码是否已具备,动态码有效性与M02服务端验码能力。
- 首访建档已确认:无关联的ONEID在点位验码成功后新建AgentOS用户并关联,无需再评审是否建档;接口实现需验证并发、幂等及创建失败状态。
- 一ONEID多卡已确认,无需再次确认;仍需确定会员码登录后的新记录写入归属、多账户Token实际扣减/冲正和画像冲突计算规则。关联汇总不授权猜测扣款顺序。
- 已绑定卡挂失后的会员登录权益,以及解绑/换绑是否在本次范围;无明确决策前不扩展。
8. 新旧口径与交付状态
最新用户流程优先:v5曾写“先注册再到绑定页扫码”,本次改为“扫带参码进入注册登录,成功后绑定”;自行注册用户以后扫卡时应复用已登录ONEID。v5将会员码视为待交付分支,本次将其列入要求,但AIVA实际接口是否就绪仍待其确认。v5/现有制卡代码认为背面小程序码不归本模块处理,已不足以满足本次一卡一参的制卡追溯需求。
本稿基于当前仓库代码调查,仅新增设计文档。本稿没有新增实际API、没有变更数据库或调用AIVA服务,图中的建议路径须联合评审后实施。