交付出件箱

← 返回出件箱

Phase 83 批次四 · 子席位批量开号(最多 5 万)+ 下载记录 + 品牌码两处修复 · 技术方案

版本 v1.4 · 2026-09-28 · 状态:长官已认可,代码未动;v1.4 = 写 impl 前 30 维复核(origin/test 81962b75,原文 ~/reports/phase83-batch4-impl-verify-20260928.md)后更正 §11.1 锁方案与两处路径
基线:origin/test @ f44699c2(下文所有 文件:行 均在该提交上逐条核对过);9-28 晚在 origin/test 3a75d611 复核:方案引用的 11 个应用文件与 f44699c2 零差异,行号全部有效(§16b)
评估与证据:~/reports/gift-card-plan-a-evaluation-20260928.md(长官版)· ~/reports/gift-card-bulk-open-verify-20260928.md(18 维证据)
取代:旧批次四 D1-D4(礼品卡 5 万号 · 同步开号方案)

0. 长官拍板(9-28 · 不再讨论)

1. 现状(物理取证 · 与方案直接相关的)

2. 总体设计

                 ┌──────────── 子席位管理「开通子席位」 count=1..50000 ────────────┐
                 │                                                                │
         count ≤ 10(同步)                                              count > 10(后台批次)
                 │                                                                │
   bulk_open.create_chunk(n)                              建 seat_open_batches 行(pending)→ 立刻返回 batch_id
   → 当场返回 [{username,password}]                        → asyncio 后台任务:每 500 个一块 create_chunk
   (凭证弹框,同现在)                                       → 每块一个事务提交 + 进度回写 → done / failed(告警)
                                                                                  │
                                                          「批量开号记录」:进度 / 下载 Excel / 按机构看(入口在子席位明细)

create_chunk(org, n, batch_id?) 一块做的事(单事务):
1. _alloc_parent_usernames(db, org_id, prefix, n) 取 n 个号(复用批次三逻辑,含撞号兜底)
2. 每个号 generate_seat_initial_password()(6 位数字,沿用)→ temp_password.seal() 得 $tmpenc1$<Fernet 密文> 直接写入 password_hash
3. 一条 INSERT … VALUES (…), (…) 批量写 users(seat_type='parent'、seat_source='platform'、must_change_password=true、seat_valid_days、seat_batch_id)
4. 同一事务一条批量 INSERT 写 account_lifecycle_event(seat_added)—— 不再每号起一个后台任务
5. 批次行 created_count += n,commit

3. 数据层(迁移 phase83_003)

🔴 down_revision = "phase83_002"(生产唯一 head · F17)。禁止接 phase85_*(企微,未上生产):接它会让生产 upgrade heads 找不到祖先而失败。test 上会因此多出一个 head,部署用 heads 可正常处理。

3.1 新表 seat_open_batches(开号批次)

• 🔒 同时只跑一批:CREATE UNIQUE INDEX ux_seat_open_batches_one_active ON seat_open_batches ((true)) WHERE status IN ('pending','running') → 第二个并发提交在 INSERT 处 IntegrityError → 409「已有开号任务在进行」(P 优化 5)
• 索引:(org_id, created_at DESC)

3.2 users 加列

• seat_batch_id BigInteger NULL FK seat_open_batches.id ON DELETE SET NULL + 部分索引 WHERE seat_batch_id IS NOT NULL
• nullable 无默认值 → PG 纯元数据操作,不重写表;存量行全 NULL,不回填(协议 C 第 6 项:业务上老号本就不属于任何批次,显式注释)

3.3 不改的

users.password_hash 仍是 String(255) 可空(user.py:34);$tmpenc1$ + Fernet 密文实测长度 110 < 255。

4. 临时密码(新模块 app/services/temp_password.py)

PREFIX = "$tmpenc1$"
_key = base64.urlsafe_b64encode(HKDF(SHA256, length=32, salt=None,
        info=b"doctor-ai-brain/seat-temp-password/v1").derive(JWT_SECRET_KEY.encode()))
def seal(plain: str) -> str            # PREFIX + Fernet(_key).encrypt(plain)
def is_sealed(h: str | None) -> bool   # h 以 PREFIX 开头
def unseal(h: str) -> str | None       # 解密失败返回 None(不抛)
def verify(plain: str, h: str) -> bool # hmac.compare_digest(unseal(h) or "", plain);任何异常 → False

• 本机实测:加密 5 万个 0.76s、解密校验 5 万个 0.77s
• 密钥由 JWT_SECRET_KEY 派生(F18),不新增环境变量、不用 root 配
• 🔴 运维红线:更换 JWT_SECRET_KEY 前,必须先跑迁移脚本(用旧密钥 unseal → 新密钥 seal)重锁所有 $tmpenc1$ 行;否则未激活卡既登录不了、也补下载不了。写进部署 README

5. 登录(只改一处)

app/api/seat_auth.py:218(_seat_login_resolve_account):

# 改前
if seat is None or not verify_password(body.password, seat.password_hash or ""):
# 改后
if seat is None or not _check_seat_password(seat, body.password):

def _check_seat_password(seat, plain) -> bool:
    h = seat.password_hash or ""
    if temp_password.is_sealed(h):
        # 只认:家长号 + 还没改过密码;其余一律按密码错
        if seat.seat_type != "parent" or not seat.must_change_password:
            return False
        return temp_password.verify(plain, h)   # 内部 try/except → False
    return verify_password(plain, h)            # 原路径,原样

• verify_password 本体不动(P7);管理员 / 结算 / h5 / 门店 / 老家长号的登录代码不动
• 手机号登录 :332 :354 不动:候选要求 must_change_password=False(F11),临时号进不去
• 失败即拒:带 $tmpenc1$ 的串若误进 verify_password,passlib 识别不了 → except → False(F10),绝不误放行
• 首登后续流程不变::551 要求微信身份 → :572 绑定微信 → 前端弹改密 → seat_change_password(:1002)写标准 argon2 + must_change_password=False(:1052)→ $tmpenc1$ 前缀消失 = 已激活
• 最坏影响:只影响「新开的号第一次登录」;兜底=后台「重置密码」(admin_parent_seats.py:302,不改)

6. 后台批次任务(新模块 app/services/seat_bulk_open_service.py)

• 提交(>10):校验机构存在 + subseat_prefix 非空(F4,开号前就 409,不等跑到一半)+ 余量校验(P13):读 org_parent_seat_counter.last_seq(无行视为 100000),count > 999999 - last_seq → 409「该机构只剩 N 个号可开」;_alloc_org_seq_batch(seat_service.py:181)内越界 IntegrityError→409 保留作兜底→ INSERT 批次行(撞「一次只跑一批」索引 → 409)→ commit → asyncio.create_task(run_batch(id)),任务对象放模块级 set 持强引用(同 activity_log_service.schedule_emit 写法,防 GC)
• run_batch:status=running → 循环 create_chunk(min(500, 剩余)),每块独立 session + 事务;块间 await asyncio.sleep(0) 让出事件循环 → status=done
• 失败:块内异常 → rollback 本块 → 批次 status=failed + error → log_incident(module="seat_bulk_open", error_type="batch_failed", severity="error", org_id=…, detail={batch_id, created_count})(incident_logger.py:15)
• 🔄 断点续开:startup_event(main.py:327)里查 status IN ('pending','running') 的批次,重新 create_task(run_batch);续开从 requested_count - created_count 继续。块是原子的(一块要么全进要么全不进),因此不重不漏;因重启中断而取走未用的号段会跳号(批次三已接受跳号)
• ▶️ 继续开(P12):POST /batches/{id}/resume 仅 status=failed 可调(否则 409)→ UPDATE 为 pending(撞「一次只跑一批」部分唯一索引 → 409「有一批正在生成,请稍后再继续」)→ commit → create_task(run_batch),从 requested_count - created_count 接着开;error 字段保留上次原因
• 🔢 预计耗时(生产):加密 ~1s + 批量写库 ~2s(推算:本机逐条写 2000 行 0.85s)≈ 数秒

7. 接口

全部 require_role("admin")(同文件现有写法)。router prefix 沿用 admin_parent_seats.py:42。

8. 导出 Excel

• 不走现有「JSON → 浏览器 fflate」链路(F14:5 万行冻结事件循环 1.6~3.8s)
• 服务端 openpyxl write_only=True,放 asyncio.to_thread 里生成(本机 5 万行 8.3s、峰值 44MB),Response(bytes) 返回
• 列(P10 · 沿用 9-18 定稿):账号 / 密码 / 机构名称 / 开通日期
• 密码格:is_sealed → unseal 出临时密码;否则 last_login_at 非空 → 「已激活」;否则 → 「已重置」(后台重置过、家长还没登录)
• 已停用的卡照常给密码(停用后登不上,无害);卡的状态看子席位管理「导出明细」
• 下载时现场生成(每次都是最新状态);不落磁盘(容器每次发版重建,文件会丢)
• 现有「子席位导出」(无密码列、每机构 2 万)保持不动

9. 作废(v1.1 长官定:本期不做整批作废)

• 单张卡停用已有:admin_parent_seats.py:291 @router.patch("/{seat_id}/status")(子席位管理行内「停用/启用」);批次开出的号 seat_source='platform',本来就出现在子席位管理列表里,可按卡号检索(admin_parent_seats.py:162 q + parent_seat_service.py:137 User.username.ilike)
• 整批 / 按段作废只在"整箱卡丢失"这类极少见场景有用 → 本期不做(简单优先);真出现时再加一个按 seat_batch_id 的停用接口即可,数据层已留好 seat_batch_id

10. 修隐患:生命周期埋点批量写(F7)

• 批次路径:在 create_chunk 同一事务里一条批量 INSERT(§2 第 4 步)
• 现有 generate_seats 也改:seat_service.py:361-363 的「每号一个 schedule_emit」→ 改为「一个 schedule_emit,内部一条批量 INSERT」。原因:现有上限 100 已超过 max_connections=50,是现存隐患;行为不变(同样是 commit 成功后写、失败不影响开号),门店端开号(≤20)与品牌码(=1)只是少开连接,业务行为零变化

11. 品牌码两处修复(P8)

11.1 同一微信并发重复建号(F15)

activate_brand_code(brand_code_service.py:173)把 :207-209 查建段抽成 _find_or_provision_family_seat,在专用连接上加会话级建议锁,持锁跑「查 → 没有就建 + 写绑定」,finally 解锁并关连接:

SELECT pg_advisory_lock(hashtext('brand-activate:' || :org_id || ':' || :identity))
-- … 查建 …
SELECT pg_advisory_unlock(hashtext('brand-activate:' || :org_id || ':' || :identity))

🔴 v1.4 更正:v1.3 写的 pg_advisory_xact_lock 无效 —— 事务锁在 generate_seats 的 seat_service.py:348 提交时就释放,而微信绑定在 brand_code_service.py:108-113 第二个事务才写,第二个请求会在两次提交之间拿到锁、按 unionid 查不到而再建一个号。
identity = unionid 优先,否则 openid。同一人两个并发请求串行化:第二个等第一个提交后再查,必然命中已建的号。不同人互不阻塞。

11.2 建号时的无用 argon2(F16)

generate_seats 加关键字参数 password_mode: Literal["argon2", "unusable"] = "argon2":
- 默认 argon2 → 门店端、其它所有调用方行为不变
- _provision_family_seat(:80)传 unusable:password_hash 写 $unusable$<随机串>(passlib 无法识别 → verify_password 恒 False),省掉 60ms 同步 CPU;家长本来就看不到这个密码,首次进站自设密码(前端既有 setBrandCodePasswordSetupRequired),改密端点不校验旧密码 → 流程不受影响

12. 前端

• web/app/(dashboard)/admin/parent-seats/page.tsx
• 数量输入 max={50}(:1212)→ max={50000},标签「数量(1-50)」(:1206)→「数量(1-50000)」,>10 时提示「超过 10 个将在后台生成,完成后在子席位明细里下载」(放在数量/有效期行下方占满整行、单行显示;生成中/完成态文案指向该机构『子席位明细 → 批量开号记录』);选完机构后现网已有的「账号前缀:XX,新开的号接着往下排」(:1199 附近)保持不动
• doProvision(:460):≤10 走原 setCred 弹框(:485);>10 收到 batch_id → 打开「批量开号记录」并轮询进度
• 新增「批量开号记录」入口:放在某机构「子席位明细」弹窗右上「导出明细」左边(page.tsx 该弹窗 header 区,实施前 grep「导出明细」定位);点进去只显示本机构批次,列表(开号时间倒序)+ 进度条 + 下载;失败行「继续开」+「下载已开部分」,有批次 pending/running 时「继续开」置灰并悬停提示「有其他批次正在生成,请稍后」(P11/P12)
• 开通弹窗:提交后 409(无前缀 / 余量不够)→ 弹窗内红字显示后端 detail,按钮不置灰;改数量后清红字(P13)
• 列对齐(9-28 长官令,同批做):子席位明细表 账号/微信 左对齐,家长手机/来源/状态/开通-到期/绑定时间 居中,行内管控 右对齐;按机构聚合表 机构 左对齐,已开通/使用中/已到期/待绑定/最近开通 居中,操作 右对齐;批量开号记录表 全部居中。弹窗文案与现网逐字一致(副标题 page.tsx:1152、占位符 :1166、有效期 :1219),数量标签改「数量(1-50000)」
• 家长登录页:不改(账号登录照旧;带字母的账号不会被手机号判断拦,seat-login-hints.ts:25-27)

13. 长官已定(9-28 · v1.1)

→ §7 删除 POST /batches/{id}/void;§15 83.29 不含作废;§14 测试第 7 条删除。

14. 测试(禁 mock · 真 PG)

新增(integration)
1. 批量开 2000 个:行数 / seat_batch_id / $tmpenc1$ 前缀 / 生命周期行数 = 2000 / 批次 done
2. 断点续开:第 3 块抛异常 → failed + 告警;重置 pending 后续开 → 总数正好 = requested,无重复账号
3. 同时只跑一批:第二个 >10 提交 → 409
4. 临时密码登录:对 → 通过并绑微信;错 → 401;改密后旧临时密码 → 401;$tmpenc1$ 串直接喂 verify_password → False
5. 门店号 / 老家长号 / 管理员登录回归不变
6. 导出:4 列;密码格 未激活给密码 / 已激活「已激活」/ 重置未登录「已重置」;5 万行耗时与峰值内存记录
8. 品牌码:同一微信并发 2 个激活请求 → 只 1 个号;_provision_family_seat 写 $unusable$ 且不调 argon2
9. generate_seats 默认参数下门店开号结果与改前一致;生命周期批量写行数正确
10. 继续开:failed 批 resume → 补齐到 requested,无重复账号;另一批 running 时 resume → 409;非 failed resume → 409
11. 余量:counter last_seq=999990 时提交 20 个 → 409 且不建批次行;无前缀 → 409

回归:test_phase74_admin_parent_seats.py(26)· test_seat_login_e2e.py(23)· test_phase83_batch5_seat_login.py(15)· tests/unit/test_seat_auth_jwt_middleware.py(13)· test_admin_brand_code.py(16)· test_brand_code_claim.py(9)· test_phase83_batch5_brand_code.py(7)· test_phase52_emit_points.py(10)· test_phase83_seat_seq_counter.py(11)· tests/integration/test_phase68_seat_initial_password.py(5)· test_seat_expiry_e2e.py(12)· tests/contract/test_app_import_smoke.py

test 环境验收:在单独压测机构真开 5 万个(计时 + 期间登录延迟抽测)→ 下载 Excel → 抽 3 个号微信真机首登 → 改密 → 再下载显示已激活 → 子席位管理按卡号搜到并单张停用 → 从该机构子席位明细进批量开号记录 → 品牌码扫码回归 → 清理(P14):按 seat_batch_id 先 SELECT 计数(users / 生命周期 / 批次行 / 3 张真机卡的登录与微信绑定)→ 交 root 执行删除 → 再 SELECT 为 0,且其他表行数与删前一致

15. 子步骤(impl 另文展开)

16a. 物理 verify 证据(15 维 · origin/test f44699c2 上 git grep -n / git show | sed -n,或 db-prod / 实测)

16b. v1.2/v1.3 新增声明物理复核(15 维 · origin/test 3a75d611)

原始命令与输出见 ~/reports/phase83-batch4-verify-v13-20260928.md。

偏差与处理:
1. test head 变化 → 已按第 1 条改,红线不变
2. admin_brand_code.py _build_export_workbook(:503,内部 :566 wb = Workbook())用普通 Workbook() 非 write_only;批次四导出是新写函数,必须 write_only=True,不照抄该函数

16. 红线

1. 迁移 down_revision 只能是 phase83_002
2. verify_password 本体不改;登录只改 seat_auth.py:218 一处
3. 门店端(store_subseat.py)与品牌码业务流程不改;generate_seats 新参数默认值必须保持原行为
4. 5 万导出不许走 JSON → 浏览器链路;不许在事件循环里同步跑 openpyxl
5. 不许每个号起一个后台任务 / 开一个连接
6. 更换 JWT_SECRET_KEY 前必须先重锁临时密码