交付出件箱

← 返回出件箱

品牌码扫码席位「真到期」· 开工前 13 维 verify

2026-09-29 · 基线 origin/test(7f6d6a1f);核心文件与 origin/main 无差异 · 只读核查,未改代码
需求(长官 9-18 拍板):品牌码新扫码的家长号从扫码当天起算 365 天硬到期;到期挡住并提示「服务已到期，请联系机构续期」;机构在品牌码页点「延期」续期;老号不动;天数固定 365。

主会话亲自复核(带对照组)

→ 「老号不动」在生产上没有存量要兼容;test 3 个号保持 NULL 即永久。

13 维结论(子代理逐维贴原文,摘要)

1. 建号:_provision_family_seat(brand_code_service.py:81-113)调 generate_seats 不传 valid_days → seat_valid_days / seat_expires_at 都是 NULL。改造:建号时显式写 seat_expires_at = 绑定时刻 + 365 天(不能只传天数,否则起算点会变成「首次密码登录」)。
2. 平台号硬到期现状:seat_auth.py:560 登录拦 403「席位已到期」;:644 首登激活写到期日;assert_seat_org_usable(seat_expiry.py:22-42)被 refresh(:944)、require_h5_user(middleware:289)、verify_api_key(h5_chat:127)调用。
3. 品牌码家长进入路径:① 扫码 activate(:274 签 token,不查到期)② 老家长重扫命中旧号(同一路径,不查)③ 手机号/账号密码登录(查,:560)④ refresh(查,:944)⑤ wx-identity 只给 h5_user 发 token,不涉及。
4. 每次请求:require_org_seat(middleware.py:335-408)只查 is_active 和设备号,不查到期 → 孩子档案 / OCR / 认领 / 门店接口都漏。
5. token:access 30 分钟;org_seat 的 refresh 到期时刻 = seat_expires_at(jwt_local.py:92-98)。
6. 延期:品牌码页「延期」→ PATCH /api/admin/parent-seats/{id}/extend → extend_seat(seat_service.py:663-719),只改 users.seat_expires_at,已过期从当前时刻起算;两字段都 NULL 的号返回 400「永久席位无需续期」。
7. 品牌码页日期:「到期日 / 当前有效 / 30 天内到期」全部取 brand_code_activations.expires_at(admin_brand_code.py:186-192、314、430、442),延期后与席位真实到期必然不一致。
8. 重扫:到期但未停用的号 → 命中旧号直接发 token(activate 不拦);已停用的号 → 不命中 → 新开一个号,拿到新的 365 天。
9. 前端:brand-scan 页直接显示后端 detail,不用改;已登录家长遇到 403 → 被踢出,弹「请重新登录以继续使用」,看不到「联系机构续期」。
10. 老号:NULL 在现有判断下天然放行,无需迁移或回填。
11. 其他读到期字段的地方:子席位管理页(已排除品牌码号,不受影响)、家长账户配额窗口(parent_quota_service:12,品牌码号会从滚动窗口变成「扫码日起 365 天」固定窗口)、到期提醒脚本 scripts/seat_expiry_reminder.py(没有排除品牌码号,365 天后会提醒)、机构洞察、结算接口。
12. 测试:品牌码相关测试 0 条到期断言;「席位已到期」旧文案有 4 处测试断言(test_seat_extend.py:373、test_seat_expiry_e2e.py:177/474、test_login_alert_org_nickname_e2e.py:107)。
13. 迁移:users.seat_expires_at / seat_valid_days 已存在且可空,不用改表。

推荐改法(拦截点)

1. 建号写到期日:brand_code_service.py _provision_family_seat,和开通记录用同一个时间点
2. 扫码发 token 前:activate_brand_code 对命中的旧号检查到期,到期返回 403「服务已到期，请联系机构续期」
3. 每次请求:require_org_seat 加到期检查(复用 assert_seat_org_usable),一处覆盖孩子档案/OCR/认领/门店接口
4. 保留已有 4 处检查不动
5. 文案只在一个函数里出

预估改动:brand_code_service.py、middleware.py、seat_expiry.py(文案)、admin_brand_code.py(视 D2)、前端两处(视 D4)、测试若干。不需要迁移。

待长官拍板

• D1 文案范围:「服务已到期，请联系机构续期」只给品牌码家长,还是所有到期号(平台号现在是「席位已到期」)统一改?
• D2 品牌码页到期日:改成显示家长号的真实到期日(延期后会跟着变),还是延期时同步改开通记录的到期日?
• D3 停用后重扫:同一个微信在本机构有停用的号,重扫时是新开一个号(新 365 天),还是拦下提示「账号已停用，请联系机构」?
• D4 已登录家长到期:被踢出时弹窗要不要显示「服务已到期，请联系机构续期」(需改前端)?
• D5 到期提醒:到期前的提醒脚本要不要也提醒品牌码家长?

第二轮 verify(D1-D5 落地点 · 2026-09-29 下午)

• D1 文案:后端出文案只有 2 处(seat_auth.py:563、seat_expiry.py:42);前端没有任何地方按「席位已到期」字符串做判断(后台 login-diagnosis.ts:69 是按到期时间自己生成的标签,不读后端文字);告警/审计按错误类型匹配,不按文字;要改的测试断言 4 处(test_seat_extend.py:373、test_seat_expiry_e2e.py:177/474、test_login_alert_org_nickname_e2e.py:107)。
• D2 品牌码页:admin_brand_code.py 列表筛选 :186-192、统计 :430/442、行展示 :314-315、导出 :682/694/756 都用开通记录到期日;改法:关联家长账号,优先用账号真实到期日,没有时回落开通记录日期。趋势图只用开通时间,不受影响。前端字段名不用改,只改 page.tsx:400 注释。
• ⚠️ 导出里「是否计费」列和合计行依赖开通记录到期日 → 计费口径需保持按开通记录 365 天,否则延期会改对账。
• D3 停用拦截:停用 = is_active=False(admin_parent_seats.py:526 → seat_service.set_seat_status:638);在 _find_or_provision_family_seat 找不到可用号时,再查一次同机构同微信的停用号,命中返回 403「账号已停用，请联系机构」;扫码页原样显示后端文字,前端不用改。
• D4 已登录到期:所有到期拦截最终都收敛到刷新登录失败(auth.ts:715)和进页面检查(auth.ts:296-308),目前这两处把原因丢了;改法:这两处记下后端返回的原因,page.tsx handleSeatKicked(:1214)带给登录弹窗,seat-login-sheet.tsx 新增一个可选提示文字。平板端品牌码家长不会用,不改。
• D5 提醒:scripts/seat_expiry_reminder.py:66-90 没有按来源过滤,品牌码号写上到期日后自动就会被提醒,不用改。提醒发到运营企微群(一条汇总),不发家长。
• 每次请求加到期检查的影响:require_org_seat 也管门店号的约 23 个接口,门店号到期后也会被拦。生产实测(seatops 只读,对照 active 席位总数):门店号 136 个里已到期 23 个,到期后登录过的 0 个(它们的刷新凭证本来就在到期时失效),实际影响≈0。
• 配额:家长 4L 配额窗口按到期日倒推 365 天,新号刚扫码额度不变;延期会把窗口往后挪,等于顺带恢复部分额度。
• 建号写到期日:_provision_family_seat 第二次提交处(:108-113)写 seat_expires_at = 绑定时刻 + 365 天,不改 generate_seats 签名(结算按位置参数调用)。