交付出件箱

← 返回出件箱

子席位账号与登录体系 v2 · 方案

2026-09-23 · 基线 origin/test e6770bb7 · 全部结论已 grep 实证(file:line 附在每条后面)
起因:长官 9-23 提出三个方向 —— ①账号加字母前缀 ②手机号也能登录 ③品牌码家长补发账号密码

一句话

三件事能做,但有 4 个反直觉的事实必须先纠正,否则方案会建在错的前提上。纠正完之后,三件事其实能共用同一套改造,不是三个独立工程。

零、先纠正 4 个事实(这几条直接改变方案形状)

事实 1 · 撞号已经修了,加前缀解决的是另一个问题

批次三(MR #733)已经落了通用批量查重 + max_rounds=5 重试 + IntegrityError → 409,撞号有兜底。
加字母前缀的真实价值不是"修 bug",而是把两个号池在结构上变成不可能重叠 —— 兜底逻辑从"每次开号都要跑查重"变成"永远不会撞"。方向是对的,但要点名它是加固,不是救火。

事实 2 · 品牌码家长现在不是"过期就进不去"

web/app/h5/chat/page.tsx:861 分支:品牌码家长 isSeatWxMode=true,token 过期不弹密码框,而是渲染微信重授权页,点"确认"重走 OAuth 就能回来(activate_brand_code 全程幂等,按 unionid/openid 认人)。

但长官的担心有真实根据,而且比想的更严重:9-20 记录的线上 bug —— 拿不到 unionid → 409 硬失败。一旦微信侧授权断了,重授权这条唯一通道也断了,那才是真锁死。
→ 所以给家长一条不依赖微信的第二通道是对的,而且正好能兜住 unionid 那个 bug。两件事应该一起看。

事实 3 · 存量扫码家长现在账号密码都等于没有

app/services/brand_code_service.py:98 只取了 created[0]["id"],generate_seats 生成的明文密码在这一行之后就永久丢失;紧接着 :110 又把 must_change_password = False 写死,把"首登强制改密"这个唯一补救引导也关掉了。

→ 这批人物理上有 username、有 password_hash,但没有任何人知道密码,也永远不会被引导去设一个。要给他们补,必须同时动这两行 + 对存量做一次数据回填。

事实 4 · 手机号现在不是可信数据,直接当登录凭证有坑

首登改密时收手机号(app/api/seat_auth.py:737)只校验格式 ^1\d{10}$,没有短信验证码。也就是说库里的手机号,是用户随便填的。
更麻烦的是唯一性口径:migrations/.../phase74_001:92-103 是三条 partial unique index(h5端 / 门店席位 / 家长席位 各自唯一,跨端可重复)→ 用手机号登录时,同一个号可能同时命中一个门店席位和一个家长席位(店员自己也是家长就会撞上)。

事实 5 · 手机号当登录名 = 安全等级实质下降(自检补 · 原方案完全漏了)

今天攻击一个席位要同时知道两样:10 位内部账号(不公开)+ 6 位数字密码。
手机号一旦能当登录名,前一样就变成公开信息,安全性只剩 6 位数字密码这一把锁。

缓解措施是有的,但要看清强度:auth_service.py:64-66 渐进冷却 —— 窗口内失败 15 次才触发,冷却 60s 起、封顶 300s(seat_login 与 admin 登录共用)。
→ 换算:约 4300 次/天,6 位密码空间 10^6,定向暴破期望约 115 天。不是一捅就破,但也谈不上稳。
→ 这不是否决项,是需要长官知情后拍板的取舍:要便利就得接受这个下降,或者把密码口径从"6 位数字"放宽(但那会动所有席位,范围大得多)。

一、现状硬事实(方案的地基 · 全部实证)

二、方案 A · 账号加字母前缀

做法

新号格式 P0000012609(家长)/ S0134202609(门店),老号一律不动,两种格式长期并存。

为什么两端用不同字母(而不是都用 T)

字母本身就成为池标识 → 家长池和门店池结构上不可能重叠,批次三那套查重兜底从此只是保险丝而非主力。同时出问题时一眼能分辨是谁的号。

大小写:用大写 + 登录时统一 normalize

• PG 的 = 是大小写敏感的,p0000012609 ≠ P0000012609。用户打小写就登不进 —— 这是必踩的坑。
• 解法:只在 /api/seat/login 这一个入口先 username.strip().upper() 再精确匹配。我们自己发的号全大写、老的纯数字 upper 之后不变 → 唯一索引照用,零性能代价,用户大小写随便打都能进。
• 🔴 绝不能顺手加到 /api/auth/login(admin / 机构管理员 / 渠道端走那条)。那些账号很可能含小写字母,一 upper 就全员登不进 —— 这是会炸全平台的操作。
  ⚠️ 我想查实 admin 账号到底长什么样,sudo db-query test 查 users 返 0 行,但这是 RLS 假 0(已知坑),查不到 ≠ 不含字母。所以按"未知"处理,设计上硬隔离,不赌。
• 不要用 func.upper(User.username) == ... 查询 —— 那会让索引失效走全表扫。
• 大写 T/P/S 与数字 0/1 无混淆风险;小写 l/o 会和 1/0 混,不选。

代价(诚实说)

1. 家长要手输账号时多一次键盘切换 —— 但方案 B(手机号登录)正好抵消这个代价,两件事是配套的。
2. 用户可见文案 seat-login-hints.ts:14「请输入提供给您的10位数字账号」会失真,必须改 + 同步改测试断言。
3. 门店号如果也加前缀,seat_service.py:153/158 的 LIKE "____{yyyymm}" + u[:4].isdigit() + len(u)==10 三道假设全部要改,这是整个方案里唯一的高风险点(改错会导致门店取号恒从 1 开始、撞老号)。
   → 若想把风险压到最低:只给家长号加前缀,门店号一个字不动。因为 len(u)==10 and u[:4].isdigit() 天然把 11 位带字母的家长号排除在外,门店逻辑一行都不用改。代价是门店号仍是纯数字,跟手机号的视觉区分度没改善。

三、方案 B · 手机号也能登录

分两步走(必须分,因为第二步卡在外部依赖)

B1 · 手机号当第二个账号名(立即可做,零外部依赖)
seat_auth.py:229-234 查用户从 username == X 改成 username == X OR phone == X,密码那把锁不变。
→ 家长接不住账号时,用自己手机号 + 密码照样进。

B2 · 手机号 + 短信验证码登录(硬阻断,等模板)
真正做到"连密码都不用记"。但 ALIYUN_SMS_TEMPLATE_CODE_VERIFY 模板没在阿里云后台注册过、env 没配(实证见上表)。
→ 需要长官去阿里云后台申请一个验证码短信模板,批下来之前这一步物理上做不了。代码侧(限频 60s / 日 10 条 / IP 小时 30 条)已经现成。

必须同时解决的三个衍生问题

1. 命中多条账号怎么办(事实 4):仓库里已有现成范式 —— seat_forgot_password 的 candidates 机制(seat_auth.py:811-836),命中多个账号时返回候选让前端弹选。直接复用,不用新发明。
2. 前端拦截必须改造,不能简单删:isPhoneLikeUsername 是 9-05 生产事故(店员把手机号当账号输)的产物。删掉后那个场景会退化成 401 + 产告警。
   → 正确做法:把前端预判改成后端准确判断 —— 后端查不到就返回"该手机号未绑定任何账号,请用账号登录"。比现在更准。
3. 手机号真实性:建议在"首登设密码收手机号"那一步补上验证码校验,否则脏手机号会继续积累(A 填了 B 的号,B 以后就绑不了)。但这一条同样依赖 B2 的短信模板。
   → 折中:B1 先上(不碰手机号采集),模板批下来后一并补校验 + 上 B2。

四、方案 C · 品牌码家长补发账号密码

长官的思路完全可行,而且能大面积复用现成件

现有的「首登强制改密弹窗」(seat-change-password-sheet.tsx)已经就是"阻塞式 + 同时收密码和手机号 + 无关闭按钮"。要做的只是:

触发时机(长官说"点任何功能就让他填")

⚠️ 这里有工作量陷阱:前端没有集中式路由保护 hook,每个页面各写一份 gate(实证见上表)。
- 做成真正的"点任何功能都拦" → 要新建一个共享 gate,并逐页接进去(≈ 6-8 个页面),工作量翻倍。
- 只在进聊天页后首次发消息时拦 → 单点改造,覆盖绝大多数场景,工作量小一个量级。

🔴 自检新发现的风险:家长在两个机构都有子席位 → 手机号撞唯一索引

uq_users_phone_parent 是家长席位内全局唯一。一位妈妈在门店 A 扫过品牌码、在门店 B 也有子席位 → 两条 parent 记录 → 设密码时填同一个手机号,第二条必然 409。
而 seat_change_password 没有先查重,直接靠 IntegrityError 兜成 409(seat_auth.py:749-759),家长只会看到一句"手机号已被使用",完全不知道该怎么办。
→ 换门店 / 多孩家庭都会撞上,不是边缘场景。必须在方案里定:是放宽索引、还是把手机号改成选填、还是给一个能自解释的提示。

密码口径

沿用现有6 位数字(seat_auth.py:728),不改。这样跟门店席位完全一致,前后端零额外改动。

五、方案 D · 登录弹框两端怎么区分

关键约束:登录之前系统分不出来人

家长端和门店端共用同一份 SeatLoginSheet,账号没输进来之前根本不知道来的是谁 —— 靠登录框自己区分是做不到的,只能靠入口(从 /h5/chat 弹的是家长,从 /h5/store-refractive 弹的是门店)。

两个选项

• D-甲(推荐 · 更简单):不做区分。两端都支持"账号或手机号"登录,文案统一改。门店店员用手机号登录也没坏处,后端靠 seat_type 唯一索引照样查得准。
• D-乙:给 SeatLoginSheet 加一个 scene: "parent" | "store" prop,由调用方传,家长场景多显示手机号提示。改动可控但多一个分支要维护。

⚠️ 无论选哪个:平板端那份是复制出来的第二份代码(tablet/seat-login.tsx:4 有红线注释"不改共享 SeatLoginSheet"),改了主件必须手动同步平板端,漏了就是平板端行为不一致。

六、影响面总表

七、外部依赖与前置条件(卡人的)

1. 🔴 阿里云短信验证码模板未注册 —— 长官需在阿里云后台申请,否则 B2(验证码登录)和"手机号真实性校验"物理上做不了。
2. 🔴 必须先把 Phase 83 四个 MR(#730-#733)发上生产,再动本案。准确理由(自检修正):本案改的取号代码依赖 phase83_001 迁移(seat_seq_counter 表),该迁移目前只在 test 库、生产没有 —— 抢跑上生产直接炸,不是"代码打架"这么含糊。
3. 🟠 存量数据回填(扫码家长 must_change_password)属于生产写操作,需长官单独批准。

八、待长官拍板(D1-D10)

九、建议实施批次

• 前置:Phase 83 四 MR 发生产(已就绪,等长官令)
• 批 1:账号前缀 + 登录大小写 normalize + 文案(小、独立、可先验)
• 批 2:手机号+密码登录(B1)+ 多账号候选 + 前端拦截改造 + 平板端同步
• 批 3:品牌码家长设账号密码(C 全套)+ 存量回填
• 批 4(等短信模板):验证码登录 + 手机号真实性校验

十、我没验的 / 说不准的

1. 结算与报表对账号格式的依赖,是引用 9-21 上个会话的调查结论,本次没有重新 grep,实施前要再核一遍。
2. admin 后台席位列表按 username 模糊搜索的行为,本次未查,加前缀后搜索体验是否变化待确认。
3. 阿里云 SDK(aliyunsdkcore)在 test/生产环境是否真的装上了,本机沙箱验不了,要在真实环境确认。

十一、自检修订记录(2026-09-23 · 长官要求"认真自检"后)

逐条复查原方案,共改 5 处,其中 2 处是实质错误、2 处是漏掉的风险、1 处是理由不准。

自检中被推翻的自己的判断(记账):
- 我原以为"手机号登录只是多个入口、安全性不变",错。账号本身承担了第二因子的作用,换成公开手机号就是降级。
- 我原以为"品牌码家长复用现有改密弹窗 = 改 2 行",错。漏查了返回体和前端存储两层。

自检中确认成立的(没有被推翻,可以放心用):
- 改密接口 SeatChangePasswordRequest 只要 new_password + contact_phone,不要老密码(seat_auth.py:113-119)→ 品牌码家长不知道旧密码也能设新密码,方案 C 的复用路径成立。
- 家长取号查重用 username.in_(candidates) 精确匹配、无长度假设(seat_service.py:239-245)→ 加前缀只改拼装一行。
- 门店取号 LIKE "____{yyyymm}" 是 10 字符模式 + len(u)==10 + seat_type 过滤三重排除 → 只给家长加前缀时,门店逻辑确实一行都不用改。
- 平板端账号输入框同样无 maxLength/inputMode 约束(tablet/seat-login.tsx:264)→ 加字母前缀前端零阻力这条对两端都成立。

十二、决策台账(长官逐条拍板 · 滚动更新)

D1 落地后的确定影响(已实证,不再是推测)

• 家长号 [前缀][6位序号][YYMM] 11 位;门店号维持 [4位序号][YYYYMM] 10 位纯数字
• 门店取号逻辑 零改动 —— LIKE "____{yyyymm}"(10 字符模式)+ len(u)==10 + seat_type 过滤三重排除,11 位带字母的家长号进不去(seat_service.py:153,158)
• 家长取号只改拼装一行:f"{seq:06d}{period}" → f"T{seq:06d}{period}"(seat_service.py:239);查重是 in_() 精确匹配,无长度假设,不用动
• 批次三的撞号兜底(通用查重 + max_rounds=5)保留不删,降级为保险丝
• ⚠️ 副作用:门店账号仍是 10 位纯数字,9-05「店员把手机号当账号输」那类混淆在门店端没有改善;前端提示文案「10位数字账号」对门店仍准、对家长已不准 → 文案必须改成两端通用写法

十三、批次五 · 最终范围(2026-09-23 长官逐条拍板 · 归口 Phase 83)

归口依据:T 前缀要改的 seat_service.py:239 取号拼装,正是批次三新写的函数里的行。
硬依赖:批次五的迁移接在 phase83_001 之后;生产现停在 phase48a_002 → #730-#733 必须先上生产。

已拍板清单

决策 13 的依据(9-23 物理查实)

• 子席位明细弹窗已有「家长手机」列(parent-seats/page.tsx:971),导出 xlsx 也带;只有品牌码页缺
• 品牌码页加手机号:brand_code_activations.family_seat_user_id → users.id 外键可达;要改 _bulk_enrich_family_seats(admin_brand_code.py:183)+ ActivationRecord 模型 + 列表/导出两端点
• 品牌码页加重置密码:守门 get_parent_seat_or_404 只认 role/seat_type,不看 seat_source → 品牌码席位直接能用,后端零改动(现有「停用/延期」已是同款复用实证)
• 不加换绑:换绑会一次清微信绑定+重置密码+踢设备,家长当场被踢;品牌码是一人一号按微信认人,不存在"转给另一个家长"的场景,加了只有风险

实施必须守住的 5 条红线(自检挖出)

1. 老席位开关默认关,不动他们任何行为
2. 前端放行手机号 + 后端支持手机号登录必须同一批上线(分批会让手机号明文进审计表和告警日志)
3. lookup_seat_username_by_wx 只加字段不改语义(被忘记密码共用,改语义会打坏候选列表)
4. 手机端与平板端是两份复制代码,必须同步改,漏一份就两端行为不一致
5. 手机号查无此人不推告警、不计冷却,防 9-05 告警刷屏复发

文档债(待清)

impl 顶部进度表还停在批次一:83.4/83.5 标 🔄、83.6-83.12 标 ⬜,但批次二三实际已合 test 验过。
→ 写批次五 impl 时逐条验收后再划勾,不直接标 ✅。