交付出件箱

后台设备管理 · 方案(第 1 件)· 2026-09-29

顺序表第 1 条:平台后台建设备、导入唯一码、生成二维码。
依据:定稿记录 home-device-plan-decisions-20260929.md + 长官 9-20 业务方案 v0.8 第 02 / 05 / 06 节。
效果图:device-admin-mockup-20260929.html(同目录)。
本文只是方案，代码 0 行。 长官点头后再写技术方案和施工步骤。

一、开工前 verify(基准 origin/test = c0e001eb · 16 维)

原始终端输出全文:~/reports/device-admin-preverify-raw-20260929.txt(脚本直接落盘，不是手抄)。

#	查什么	结论	证据(file:line)	对照组
V1	后台菜单在哪	平台管理组在新壳 `AdminConsoleShell.tsx`,「子席位管理」在 :45	`web/app/(dashboard)/admin/AdminConsoleShell.tsx:35-47`	同文件其他组 :52 / :76 命中
V1b	菜单权限登记	每个菜单要在 menu_registry 登记一条	`app/core/menu_registry.py:25` platform.parent_seats	:18-29 共 7 条
V2	已有的「设备」页面(要避开)	旧壳里已有「设备数据池」`/admin/devices`、「设备类型」`/admin/device-types`,接口前缀 `/api/v1/admin`	`web/app/(dashboard)/layout.tsx:16,104,113`;`app/api/admin_devices.py:17`	—
V3	已有设备表(要避开重名)	只有 `device_data` / `device_type_config` / `user_phone_verification`,是厂商推送数据，没有编号、门店、二维码、绑定	`app/models/device.py:18,43,57`	`user.py` 查同写法命中 2
V4	二维码能力	`/api/qr` 现成(python qrcode),但无鉴权、缓存 1 天;全仓没有打包 zip 先例	`app/api/qr.py:26-27,79`;zipfile 0 命中	`import qrcode` 命中 qr.py、share_poster.py
V5	后台接口鉴权	平台管理员接口一律 `Depends(require_role("admin"))`	`app/auth/middleware.py:100`;`app/api/admin_parent_seats.py:10`	—
V6	Excel 导入先例	后端全用 openpyxl(3 个文件),没有 pandas;上传用 UploadFile;「先预览再确认」两步式有现成写法	`app/api/excel_import.py:1,86`;`app/api/admin_flywheel.py:158`	pandas 0 命中 / openpyxl 3 文件
V7	门店按名字匹配行不行	`organizations.name` 没有唯一约束,可能重名 → 导入必须把「对不上 / 重名」单列给人确认	`app/models/organization.py:20`(对比 :17 org_code unique=True)	同文件 unique 命中 4 处
V8	随机码先例	品牌码就是 `secrets.token_urlsafe(32)` 落库唯一，设备码照抄	`app/api/admin_brand_code.py:368`;`app/models/brand_code.py:44`	—
V9	家长 / 孩子表	家长 = users(seat_type)、孩子 = patients(owner_seat_id)	`app/models/user.py:130`;`app/models/flywheel.py:52`	—
V10	数据库迁移挂哪	test 上迁移是多头;最新链尾 `phase85_006`。实施时要先确认挂载点	`migrations/versions/phase85_006_wecom_wait_timeline.py:16-17`	共 111 个迁移文件
V11	后台真实样式	后台实际是灰黑风格:黑按钮 bg-slate-900(65 处)、border-slate-200(205)、rounded-xl(109);蓝 bg-blue-600 只 24 处	频次命令见原始输出 V11	—
V12	门店手机/平板有没有子席位列表(第 2 件用)	没找到。平板和门店手机里带「席位」的文件只有登录、绑家长弹框，没有列表页 → 第 2 件多半要新做页面(第 2 件开工再细查)	`web/app/h5/tablet/components/seat-login.tsx`;h5 目录共 15 个子目录逐个列过	「席位」在 h5 下命中 20 个文件
V13	出图样板	后台 PC 样板有 phase21b-admin-demo 等	`docs/superpowers/demos/`	—
V14	照着做的真实页面	「子席位管理」页:标题 23px 粗体、表头 `bg-slate-50 text-slate-500`、「查看明细」蓝色文字链	`web/app/(dashboard)/admin/parent-seats/page.tsx:759,966-974,995`	—
V15	弹框样式	居中白卡 rounded-2xl + 遮罩 `bg-slate-900/40`,主按钮 rounded-xl bg-slate-900	`parent-seats/bulk-open.tsx:290,295,313`	—
V16	业务方案原文	v0.8 第 02 节(设备管理)、05 节(后台查询)、06 节(解绑)已逐条读过;跟它不同的地方(不要厂商、按设备停用)以长官 9-29 晚定的为准	~/reports/shared/subseat-device-plan-v08-20260920.html	—

verify 改变了什么
1. 后台已有「设备数据池」「设备类型」两个老页面(存厂商推送的使用数据，跟本件无关)→ 新页面地址用 /admin/device-mgmt,不碰老的 /admin/devices、/admin/device-types。注意老菜单也叫「设备类型」,两边同名，实施时老菜单要不要改名/收起，到时问长官
2. /api/qr 公开、会被缓存 → 设备二维码不走这个接口,下载走后台鉴权接口，在服务端生成
3. 机构名不唯一 → 导入时门店对不上 / 重名的，单列出来，由人从下拉框选机构，系统不猜
4. 第 2 件门店端没有子席位列表 → 第 2 件工作量比原先估的大(要新做页面)

二、做什么(长官 9-29 晚已定)

结构只有两层:设备类型 → 设备名称,每个设备名称下挂很多唯一码。不设厂家。

1. 菜单

「平台管理」组，在「子席位管理」下面加 设备管理,页面三个页签:「唯一码」「设备」「设备类型」;标题和页签同一行，筛选放进表格卡片头，页头不占地方(照子席位管理页的排法)。

2.「设备」页签(类型 + 名称)

列:设备类型、设备名称、唯一码数量、状态(正常 / 已停用)、操作(编辑 · 停用或启用 · 删除)
新增 / 编辑弹框:设备类型(只能从「设备类型」页签里已有的选)、设备名称;改名后家长「我的设备」里的名字跟着变
导入设备:Excel 2 列(设备类型、设备名称),两步:① 下载模板、填好、拖进文件 ② 看检查结果再确认;类型不存在的行算问题
设备名称全平台不重名(导唯一码时靠名称对上设备)
停用:要二次确认;停用后家长扫这个设备的码不能再绑，已经绑上的照常用;能再启用
删除:红字，要二次确认;设备下面有唯一码就不能删(哪怕都没绑定),只能停用,所以只有唯一码数量为 0 的设备才出现「删除」

2b.「设备类型」页签

列:设备类型、设备数、状态(正常 / 已停用)、操作(编辑 · 停用或启用 · 删除);右上「新增类型」
新增 / 编辑弹框只有一个字段:类型名称;改名后该类型下的设备跟着显示新名字
停用(要确认):这个类型下所有设备的码都不能再绑定，已绑上的照常用;新增设备时不能选它;能再启用
删除(红字，要确认):类型下面有设备就不能删，只能停用

3.「唯一码」页签(默认)

不放统计卡;表格标题旁写「共 128 个 · 已绑定 71」
筛选:类型、设备名称、下放门店、导入时间(日期范围)、绑定状态;按唯一码搜
按钮:新增唯一码、导入唯一码、下载二维码、导出清单
下载二维码:弹框选范围(勾选的 / 当前筛选结果)→ 开始生成，显示进度「86 / 128」→ 下载压缩包;每张图的文件名就是唯一码(如 ZY000128.png),图下方印唯一码
最左有勾选框，可勾几个一起下载二维码
列:唯一码、设备类型、设备名称、下放门店、状态、绑定家长、绑定时间、操作(详情 · 编辑 · 删除)
状态三种:已绑定 / 未绑定 / 已停用(设备或类型停用了、且还没绑的码;鼠标放上去提示是设备停了还是类型停了);已绑的不受停用影响
全后台「停用」统一叫「已停用」,设备页、类型页、唯一码页同一个词
绑定家长:微信头像 + 昵称，下一行手机号;所有行一样高(席位号放详情里;字段来源 parent-seats/page.tsx:1172-1185、app/models/user.py:42-43)
新增 / 编辑唯一码:唯一码(编辑时不能改，已经印在二维码上)、设备(只列正常的)、下放门店;已绑定的只能改下放门店
删除唯一码:红字，要二次确认;只有从没被绑定过的才能删(删了二维码作废)
导出比列表多:导入时间、账号归属机构、绑定时关联门店

4. 导入唯一码(两步)

第 1 步:下载模板 → 按模板填好 → 把文件拖进来或点选择 → 下一步(不分批次，每条记下导入时间)
Excel 4 列:设备类型、设备名称、唯一码、门店营业执照名称
门店营业执照名称要和机构管理里的机构名称一字不差(系统先去掉首尾空格、统一全半角再比)
设备必须先在「设备」页签建好;表里的设备不存在算问题，不自动新建
第 2 步:顶上汇总(可导入 / 需处理 / 不能导),下面只列有问题的行(行号、唯一码、问题、怎么处理)
需处理:门店名对不上 / 重名 → 当场下拉选成哪家机构，或这行先不导
不能导:唯一码为空、表里重复、系统已有(只差大小写也算)、设备不存在、设备已停用
确认后才写入;唯一码原样保存，前导零和大小写不变
两个模板:第 1 行是浅橙底的填写说明(合并单元格),第 2 行表头，第 3 行示例;导入从第 2 行表头开始读

5. 二维码

每个唯一码一个唯一二维码;码里是带随机码的网址(随机码照品牌码写法，猜不到,唯一码本身不进码)
图片名 = 唯一码.png,码下方印唯一码
两种扫法都能绑(第 3 件做，本件只定网址):
微信直接扫 → 打开智脑页面 → 点一下微信授权 → 确认绑定。品牌码已是这个做法:web/app/h5/brand-scan/page.tsx:18 复用微信授权;:7-8 注明微信不许自动授权，所以要点一下
在智脑里扫 → 直接到确认绑定
家长微信还没关联过智脑账号的，先登录一次

6. 唯一码详情(右侧抽屉)

基本信息 + 二维码预览和下载
当前绑定:家长、账号归属机构(开这个家长号的机构，达人卖的就是达人机构)、绑定时关联门店、绑定时间
平台解绑:选原因(退货 / 换新 / 误绑 / 转让 / 其他),可补充说明;记操作人
绑定历史:每次绑定、解绑一行，永久保留

7. 本件不做

家长扫码绑定、我的设备(第 3 件)
门店 / 达人端看设备(第 2 件)
厂家、设备图片、唯一码预分给达人、单台停用

本件跟第 2、6 件先上线，那时家长还不能扫码，所以「当前绑定家长」「平台解绑」先空着。绑定记录表本件就建好。

三、长官 9-29 晚的回复(原话要点)

不要厂家，就两层:设备类型、设备名称，下面是唯一码;唯一码能导入，设备也能导入;每个唯一码生成唯一二维码
停用按设备停(不合作了就停)
微信直接扫就能绑，也可以在智脑里扫

四、定了之后

写技术方案和施工步骤(新表 3 张:设备、唯一码、绑定记录;数据库迁移接在哪先确认)
实施:后端和真库测试 → 前端页面 → 发 test 真页面自测
跟第 2、6 件一起上生产

9-30 长官令:「SN码」统一改叫「唯一码」(页面、导入模板、图片名都用这个词)。