交付出件箱

← 返回出件箱

【批次四】子席位批量开号(最多 5 万)+ 批量开号记录 + 品牌码两处修复(2026-09-28 · 代码未动)

技术方案:docs/superpowers/plans/tech/phase83-batch4-bulk-open.md v1.4(§0 P1-P14 为拍板全集,与本文冲突以 tech 为准)
效果图定稿:~/reports/subseat-records-mockup-r2-20260928.html(屏A 批量开号记录 / 屏B Excel / 屏C 明细入口+对齐 / 屏D 聚合对齐)· ~/reports/subseat-mockup-v3-r2-20260928.html(屏1 开通弹窗 / 屏1b 余量不够 / 屏2 生成中 / 屏3 完成);图上「设计说明,不做进页面」的文字一律不许进页面
开工前 verify 原始输出:~/reports/phase83-batch4-impl-verify-20260928.md(30 维 · origin/test 81962b75 · 每维原样命令输出)
分支:代码从最新 origin/test 拉 feature/phase83-batch4-impl(文档分支 feature/phase83-batch4-bulk-open 已随 MR#781/#792 进 test)
本文不写测试代码、不写完整实现代码。

开发进度

进度表状态只能由主会话手动改;agent 严禁触碰。

实施红线(违反即返工)

1. 迁移 down_revision = "phase83_002"(生产唯一 head);手写,禁 autogenerate(原因同 phase83_002 迁移注释 :14-20);禁接 phase85_*
2. password_utils.verify_password 本体一行不改;登录只改 seat_auth.py:218 一处;手机号路径 :332 :354 不动
3. generate_seats 的其余 6 个调用点一行不改(admin_seats.py:126、internal_settlement.py:584/705/1650、store_subseat.py:97、brand_code_service.py:97 仅加一个关键字参数);新参数放签名最末、默认值保持原行为(internal_settlement 按位置传参,见 seat_service.py:268-270 注释)
4. 5 万导出禁走「JSON → 浏览器拼 xlsx」;openpyxl 只许在 asyncio.to_thread 里跑且 write_only=True;不许照抄 admin_brand_code.py:503 _build_export_workbook(其 :566 是普通 Workbook())
5. 禁止每个号起一个后台任务 / 开一个连接
6. 现有「导出明细」(page.tsx:887-893 + GET /export admin_parent_seats.py:254)、重置密码 / 换绑 / 停用端点(:291/:302/:312)不动
7. ≤10 个时的凭证弹框(page.tsx:485-491)行为与形状不变
8. 更换 JWT_SECRET_KEY 前必须先重锁临时密码(写进部署 README)

开工前 verify 结论(30 维 · origin/test 81962b75)

🔴 本次 verify 新发现(tech 未写或写错 · 已同步改 tech v1.4)

Phase 83.26: 数据层

文件:
- 新增:migrations/versions/phase83_003_seat_open_batches.py(revision="phase83_003",down_revision="phase83_002",手写)
- 新增:app/models/seat_open_batch.py(SeatOpenBatch)
- 修改:app/models/user.py(seat_ 列组内、created_by_seat_id :156 附近加 seat_batch_id)、app/models/__init__.py(照 :95-97 写法 import + __all__)
- 测试:tests/integration/test_phase83_batch4_bulk_open.py(新)

内容(以 tech §3 为准):
- 表列、CHECK 同 tech §3.1;status 四值 pending / running / done / failed
- 「同时只跑一批」:迁移里原生 SQL CREATE UNIQUE INDEX ux_seat_open_batches_one_active ON seat_open_batches ((true)) WHERE status IN ('pending','running');模型 __table_args__ 写同名同条件索引,两边一致
- ix_seat_open_batches_org_created (org_id, created_at DESC)
- users.seat_batch_id BigInteger NULL,FK seat_open_batches.id ON DELETE SET NULL,部分索引 WHERE seat_batch_id IS NOT NULL;老行全 NULL 不回填(业务上老号不属于任何批次,迁移里写明注释)
- downgrade 反序删除

• [ ] Step 1: 写失败测试:表 / 列 / 索引存在;requested_count 10 与 50001 被 CHECK 拒;非法 status 被拒;已有一条 pending 时再插 pending / running → IntegrityError,原批改 done 后可再插;老行 seat_batch_id 为 NULL
• [ ] Step 2: RED
• [ ] Step 3: 实现(agent 只写文件,不跑 alembic)
• [ ] Step 4: 主会话本地 alembic upgrade → downgrade → upgrade 各一次(贴输出 + alembic heads)
• [ ] Step 5: GREEN

Phase 83.27: 临时密码模块

文件: 新增 app/services/temp_password.py;测试 tests/unit/test_phase83_temp_password.py(新)

内容: tech §4 四个函数(seal / is_sealed / unseal / verify);密钥 HKDF 派生自 app/auth/jwt_local.py:24 JWT_SECRET_KEY;unseal / verify 任何异常都不抛(返回 None / False);verify 用 hmac.compare_digest。不新增依赖行(cryptography 由 requirements.txt:33 带入,agent 贴 python -c "import cryptography; print(cryptography.__version__)" 证明)。

• [ ] Step 1: 写失败测试:往返一致;is_sealed 对 argon2 串 / None / 空串为假;篡改密文 → unseal None、verify False;换密钥后 unseal None;串长 ≤255;$tmpenc1$ 串直接喂 password_utils.verify_password → False;5 万次 seal 耗时打印记录
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN

Phase 83.28: 批次服务 + 生命周期批量写 + 启动续开

文件:
- 新增:app/services/seat_bulk_open_service.py
- 修改:app/services/activity_log_service.py(新增 emit_lifecycle_bulk,写法照 emit_lifecycle :194-225:fresh session + 一条批量 INSERT + 全捕 + log_incident;emit_lifecycle 本体不动)
- 修改:app/services/seat_service.py:360-363(逐号 schedule_emit → 一次 schedule_emit(emit_lifecycle_bulk(org_id, created_ids)))
- 修改:app/main.py startup_event(:327-395)末尾加续开,try/except 走 log_incident,不许拖垮启动
- 测试:tests/integration/test_phase83_batch4_bulk_open.py

seat_bulk_open_service 内容:
- CHUNK = 500
- 前缀检查:无前缀 → 409,文案与 seat_service.py:308 逐字一致
- 余量检查:读 org_parent_seat_counter.last_seq(无行视为 100000),count > 999999 - last_seq → 409「该机构只剩 N 个号可开」;_alloc_org_seq_batch 的越界 409 保留作兜底
- create_chunk(db, org, n, *, valid_days, batch_id=None)(单事务,调用方 commit):
1. 有 batch_id 时先 SELECT … FOR UPDATE 锁批次行,n = min(n, requested - created),n ≤ 0 直接返回空(N7)
2. seat_service._alloc_parent_usernames(db, org.id, org.subseat_prefix, n)(:213)
3. 每号 generate_seat_initial_password() → temp_password.seal()
4. 一条批量 INSERT users,字段对齐 seat_service.py:324-340(role='org_seat'、linked_org_id、is_active=True、must_change_password=True、seat_valid_days、seat_type='parent'、phone_login_enabled=True、seat_source 不传走 server_default、created_by_seat_id=None)+ seat_batch_id,按参数顺序返回 id(agent 先贴 SQLAlchemy 版本,用该版本支持的保序批量写法)
5. 同事务一条批量 INSERT account_lifecycle_event(subject_type='seat'、subject_id=str(id)、event_type='seat_added'、detail={})
6. 有 batch_id 时 created_count += 本块数
7. 返回 [{id, username, password}]
- submit_batch(db, org, count, valid_days, admin_id):前缀 → 余量 → INSERT 批次行 pending(撞 ux_seat_open_batches_one_active → rollback → 409「已有开号任务在进行」)→ 打开 enable_parent_subseat(N5)→ commit → spawn
- spawn(batch_id):asyncio.create_task(run_batch(id)),模块级 set 持强引用(照 activity_log_service.py:26-33)
- run_batch(batch_id):首次置 running + started_at;循环每块新开 session(async_session_maker)→ create_chunk → commit → await asyncio.sleep(0);本块返回空 → 置 done + finished_at。任何异常:rollback → 新 session 置 failed + error(截断 500 字)→ log_incident(module="seat_bulk_open", error_type="batch_failed", severity="error", org_id=…, detail={"batch_id", "created_count"})
- resume_pending_batches()(启动用):查 pending / running 的批次 → spawn
- resume_failed(db, batch_id):非 failed → 409「只有失败的批次可以继续开」;改 pending(撞索引 → 409「有一批正在生成,请稍后再继续」)→ commit → spawn;error 保留

• [ ] Step 1: 写失败测试(真 PG,禁 mock):
• 批量开 2000 个:users 2000 行、全带 seat_batch_id、password_hash 全以 $tmpenc1$ 开头、账号连号无重复、生命周期 2000 行、批次 done、created_count=2000
• 失败:把测试机构 last_seq 设到只剩 1000,直接插一条 requested=2000 的批次跑 run_batch → 第 3 块真撞计数上限 → failed、created_count=1000、日志里有 [INCIDENT] seat_bulk_open
• 续开:造一条已开 1000 的 failed 批次(真调 create_chunk 造数据)→ resume_failed → 补齐 2000 且无重复账号
• 两个 run_batch 并发跑同一批 → 总数正好 = requested(N7)
• 一次只跑一批 → 409;非 failed 续开 → 409;另一批 running 时续开 → 409
• 余量:last_seq=999990 提交 20 → 409 且不建批次行;无前缀 → 409
• generate_seats 开 3 个门店号 → 生命周期 3 行,只起 1 个后台任务
• 所有用例 finally 按 seat_batch_id / 测试机构清理(N2)
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN
• [ ] Step 5: 回归 tests/integration/test_phase52_emit_points.py(10)、tests/unit/test_phase83_seat_seq_counter.py(11)

Phase 83.29: 接口

文件: 修改 app/api/admin_parent_seats.py;测试同上文件

内容:
- :64 le=50 → le=50000
- provision(:115-151):先做前缀、余量检查(两条路径同一套文案);≤10 → create_chunk(db, org, count, valid_days=…) + 打开 enable_parent_subseat + commit,返回形状同 :151;>10 → submit_batch,返回 {org_id, org_name, batch_id, status:"pending"}
- GET /batches?org_id=&page=&page_size=(org_id 必填):本机构批次按 created_at 倒序,每行 id / created_at / requested_count / created_count / status / error / activated_count;另带 has_active(全局有 pending / running)。activated_count = 该批 password_hash 不以 $tmpenc1$ 开头且 last_login_at 非空
- GET /batches/{id}:单批同字段(前端 2 秒轮询)
- GET /batches/{id}/export:async 取该批 username / password_hash / last_login_at / created_at → asyncio.to_thread 内解密 + openpyxl write_only=True 生成 → Response(bytes);4 列 账号 / 密码 / 机构名称 / 开通日期(北京时间日期);密码格:is_sealed → 解密明文;否则 last_login_at 非空 →「已激活」;否则 →「已重置」(N6);按账号排序;任何状态可下载(失败批 = 下载已开部分);不落盘;文件名以效果图屏B为准
- POST /batches/{id}/resume → resume_failed
- 全部 require_role("admin")

• [ ] Step 1: 写失败测试:count=5 → 5 条明文且库里 $tmpenc1$;count=50001 → 422;count=20 → 返回 batch_id;缺 org_id → 422;列表只含本机构且倒序;导出 4 列与三种密码格(已激活:真走 /api/seat/login 首登 + 改密,造法照 test_seat_login_e2e.py;已重置:调 /{seat_id}/reset-password);续开三种 409;非管理员 403
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN
• [ ] Step 5: 回归 tests/integration/test_phase74_admin_parent_seats.py(26)

Phase 83.30: 登录一处判断

文件: 修改 app/api/seat_auth.py:218(改调 _check_seat_password,逻辑见 tech §5)+ import temp_password;测试同上文件

• [ ] Step 1: 写失败测试:临时密码对 → 登录成功并绑微信;错 → 401;must_change_password 已为 False 的 $tmpenc1$ 号 → 401;门店号带 $tmpenc1$ → 401;改密后旧临时密码 401、新密码成功;临时号不出现在手机号登录候选里
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN
• [ ] Step 5: 回归 tests/integration/test_seat_login_e2e.py(23)、tests/integration/test_phase83_batch5_seat_login.py(15)、tests/unit/test_seat_auth_jwt_middleware.py(13)、tests/integration/test_seat_expiry_e2e.py(12)、tests/integration/test_phase68_seat_initial_password.py(5)

Phase 83.31: 品牌码两处修复

文件: 修改 app/services/brand_code_service.py(:207-209 查建段、:97-103 调用加参数)、app/services/seat_service.py(generate_seats 签名末尾 + :326);测试 tests/integration/test_phase83_batch4_brand_code.py(新)

内容:
- 防重复建号(N1):把 :207-209 抽成 _find_or_provision_family_seat;函数内用 app.database.engine 单开一个连接执行 pg_advisory_lock(hashtext('brand-activate:' || org_id || ':' || identity))(identity = unionid 优先,否则 openid;openid 已由 :196 保证非空),持锁跑「查 → 没有就建 + 写绑定」,finally pg_advisory_unlock 并关连接。不许用 pg_advisory_xact_lock
- 无用 argon2:generate_seats 末尾加 password_mode: Literal["argon2", "unusable"] = "argon2";unusable 时 password_hash = "$unusable$" + 随机串、返回的 password 为 None;brand_code_service.py:97-103 传 password_mode="unusable"(其只取 id,:104)

• [ ] Step 1: 写失败测试:同一 unionid 两个并发调用 → 只 1 个号;不同 unionid 并发 → 各 1 个;品牌码新号 password_hash 以 $unusable$ 开头且 verify_password 为 False;门店 generate_seats 默认仍 argon2
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN
• [ ] Step 5: 回归 tests/integration/test_admin_brand_code.py(16)、tests/integration/test_brand_code_claim.py(9)、tests/integration/test_phase83_batch5_brand_code.py(7)

Phase 83.32: 前端

文件: 修改 web/app/(dashboard)/admin/parent-seats/page.tsx;新增 批量开号记录弹窗组件(放同目录,agent 先 ls 确认文件名未被占用并回报);测试 web/__tests__/admin-parent-seats-bulk-open.test.tsx(新,写法照同目录 admin-parent-seats-*.test.tsx)

内容(文案、颜色逐字逐色以效果图为准,色值只许从现网扒):
- 开通弹窗::1206「数量（1-50）」→「数量（1-50000）」;:1212 max={50} → max={50000};数量 / 有效期行(:1204-1231)下方整行单行灰字「超过 10 个将在后台生成，完成后在子席位明细里下载」(样式照 :1199 灰字)
- doProvision(:460-499):409 → 弹窗内红字显示后端 detail,弹窗不关、按钮不置灰;改数量或机构时清红字;其他非 2xx 保持原 toast(:474-480);红字色值从 page.tsx 现有红色文字扒,扒不到就回报,不许自配
- >10 返回 batch_id → 关开通弹窗 → 打开该机构子席位明细 + 批量开号记录,轮询 GET /batches/{id} 每 2 秒到 done / failed(屏2 / 屏3)
- 子席位明细弹窗头部(:880-893):「导出明细」左边加「批量开号记录」,样式同 :890
- 批量开号记录弹窗:只显示本机构;开号时间倒序;全部列居中;状态「生成中 / 已完成 / 失败」徽章令牌从 STATE_LABEL :40-44 / DISABLED_BADGE :49 同类写法扒;失败行「继续开」+「下载已开部分」;has_active 为真时「继续开」置灰(样式照 :1041)+ 悬停「有其他批次正在生成，请稍后」
- 下载:apiFetch → res.blob() → 走现有 doDownload(:354-366)
- 列对齐:聚合表 :815-821 及对应单元格(机构左 / 数字与日期居中 / 操作右);明细表 :976-983 及对应单元格(账号、微信左 / 手机、来源、状态、开通-到期、绑定时间居中 / 行内管控右)

• [ ] Step 1: 写失败测试:标签与 max;灰字;409 红字且改数量后消失;>10 打开记录;入口在「导出明细」左边;「继续开」置灰 + 悬停文案;两表表头对齐 class
• [ ] Step 2: RED
• [ ] Step 3: 实现
• [ ] Step 4: GREEN
• [ ] Step 5: 回归 admin-parent-seats-badge-extend / -detail-filter-multi / -source-column / -subseat-prefix / parent-seats-xlsx / admin-menu-parent-seats;npm run build 必跑(贴 Route 表)

Phase 83.33: 总验收

• [ ] Step 1: 后端 新增 3 个测试文件 + 83.28-83.31 回归 11 个文件 + tests/contract/test_app_import_smoke.py(4)pytest -v 真绿
• [ ] Step 2: 前端 vitest 真绿 + npm run build
• [ ] Step 3: chat-e2e 守门:提交前查 scripts/verify-trigger-files.txt,本批改动命中则 bash scripts/verify.sh chat-e2e
• [ ] Step 4: 发 test
• [ ] Step 5: test 真跑(单独压测机构 · 提前设好前缀):真开 5 万个(记总耗时 + 期间抽测登录延迟)→ 下载 Excel 核 4 列 / 5 万行 → 抽 3 个号长官真机首登 → 改密 → 再下载显示「已激活」→ 子席位管理按卡号搜到并单张停用 → 从该机构子席位明细进批量开号记录 → 品牌码扫码回归 → 开通弹窗余量不够红字
• [ ] Step 6: 数据完整性:批次行 created_count = requested_count;生命周期行数 = 5 万;users 计数走 root 或页面 / 接口核对(N9)
• [ ] Step 7: 清理(P14):按 seat_batch_id 圈定;删除前由 root 先查 users 的外键依赖表逐表计数(含 3 张真机卡产生的登录审计、微信绑定等)→ root 删除 → 删后再查为 0,其他表行数与删前一致
• [ ] Step 8: 长官验收后发生产(sudo release-to-prod --mr <N>,先核 commit_ids + changed_files)

【验收标准】(批次四)

• [ ] 开通子席位数量可填 1-50000;≤10 当场弹出账号密码(与改前一致);>10 后台生成
• [ ] 5 万个在 test 真开成功,账号连号不重复,耗时有实测数
• [ ] 开号期间全站正常(登录抽测延迟有实测数),没有连接被打爆
• [ ] 批量开号记录:入口在该机构子席位明细「导出明细」左边;只显示本机构;开号时间倒序;进度 / 状态正确
• [ ] Excel 4 列;未激活给临时密码、已激活写「已激活」、重置后未登录写「已重置」
• [ ] 临时密码能登录并绑微信;首登强制改密;改密后旧临时密码失效
• [ ] 失败批次能「继续开」补齐不重不漏;有批次在生成时「继续开」置灰且有悬停提示;失败批可下载已开部分
• [ ] 同时只能跑一批;机构剩余号不够时弹窗内红字「该机构只剩 N 个号可开」且不建批次
• [ ] 服务重启后未完成批次自动接着开
• [ ] 老号 / 门店号 / 管理员登录不受影响;门店开号结果与改前一致
• [ ] 品牌码同一微信连点只建 1 个号;品牌码建号不再做 argon2
• [ ] 子席位明细表、机构聚合表、批量开号记录表列对齐符合效果图
• [ ] 后端 pytest / 前端 vitest 真绿;npm run build 通过
• [ ] test 压测数据已由 root 删净,删后计数为 0、其他数据不变

📌 本批验收标准里验不了的(如实标注)

• 「新旧容器并存时双跑不超开」只能靠 83.28 并发用例托底,test 上无法稳定复现发版瞬间
• 生产 5 万开号耗时只能在生产第一次真用时实测,test 数字仅供参考