Kidsbox · 家长管理平台设计调研 KB-72 Issue #72 PR #73 Markdown 源文件

家长管理平台设计调研:社区参考、五个嫁接方案与 Roadmap 提案

需求 KB-72 · Parent admin platform research
日期 2026-09-03
产出方 ZCode(Agent)
分支 docs/admin-platform-research(独立 worktree,基于 origin/main)
性质 纯调研与提案:不修改生产代码、不创建云资源、不产生任何费用
姊妹篇 KB-71 宝宝端体验调研(消费侧对偶)

0. 摘要(给刚睡醒的你)

你提的四步需求——批量下载 → 批量处理 → 自动上传 COS → 上下架管理——在当前主线里的真实状态是:

  1. 前三步的引擎已经造好了,而且工程质量相当高:URL 列表批量入队(单次 ≤100 条)、有界并发下载、自动转码(1080p+480p)、校验、签名分片上传,全部自动化,失败可重试、断点可恢复。缺的不是引擎,是操纵它的界面:现在审批和上下架都只能一条一条点,批量操作界面完全空白。
  2. 第四步(COS)需要你做一个授权决策:主线当前所有媒体存在 Cloudflare R2;腾讯 COS 的代码底座已存在(签名直传协议 + COS adapter),但按 ADR 0004 属于「已批准、未激活」候选,激活它涉及真实费用、CAM 授权和主机门禁——这是唯一「不能都做、必须你拍板」的分叉点。
  3. 社区答案很成熟:这类「下载-处理-归档-发布」场景在开源社区有大量打磨多年的成品(arr 系列、Tube Archivist、Jellyfin、Payload/Directus 等),它们共同验证了一套模式:**「来源订阅 → 队列暂存 → 审核 → 批量执行 → 归档库」五段流水线 + 内容/任务双视图 + 命名预设/Profile*
  4. 本报告给出 5 个嫁接方案,推荐组合是 方案 D(现代轻工作台)为底座 + 方案 B(片库策展室)的浏览视图 + 方案 A(采集驾驶舱)的队列与审核闸门——理由见 §4.6。
  5. Roadmap 提案 6 个里程碑(M0-M5),与 docs/ROADMAP.md 的既定节奏兼容:v0.5 家庭体验基线验收期内不动管理平台,管理平台效率本就是 v0.5 之后的候选方向②。

你睡醒后只需要回答三个问题(详见 §6):① 设计方向选哪个(推荐「按 §4.6 组合」);② COS 是继续保持 R2 主线,还是授权启动激活门禁;③ roadmap 排序是否认可 M1(批量操作)先行。

1. 任务与范围

本次调研回答三个问题:

  1. 社区里有哪些优秀的成品与设计风格可以参考(§3,共 6 组、20 余个产品);
  2. 把这些风格嫁接到我们的管理平台上,能形成哪几种设计方案(§4,5 个方案);
  3. 管理平台接下来的 roadmap 是什么(§5,M0-M5)。

范围边界:只新增本文档;不修改 apps/adminapps/apiapps/collectorpackages/contracts;不激活 COS、不创建云资源;所有仓库现状结论附代码文件引用,所有社区结论附来源链接。

2. 现状盘点:我们到底已经有了什么

依据 origin/main(22d1add)代码事实,关键结论均可在引用文件中复核。

2.1 链路全景

允许扫描的目标(scan_targets allowlist,扫描间隔 ≥15 分钟)
  → 发现落 pending_review(不自动下载)
  → 家长在 Admin 批准(版权门禁:owned/licensed/open_license/creator_permission)
  → Collector:inspect → download → probe → metadata(AI) → 转码 → 校验 → 上传 → finalize
  → API/D1 元信息 + 私有 R2 媒体
  → Admin 发布/隐藏(published ⇄ hidden)
  → PWA 宝宝端只消费 published & visibleToChild

2.2 管理后台现状(apps/admin)

2.3 采集与处理管线现状(apps/collector)

2.4 差距分析:对照你的四步需求

需求环节 已有什么 缺什么
批量下载 URL 列表批量入队(≤100 条/run)、番剧/播放列表/系列展开后待审、有界并发、幂等复用未关闭 run ① 展开后的候选仍需逐条批准——无「批量批准/批量否决」端点与 UI(transition 一次一条);② run 列表无分页与过滤(全量返回,apps/api/src/index.ts:1127-1131);③ 无跨 run 的任务合并视图
批量处理 run 内逐条自动走完 probe→metadata→转码→校验→上传→finalize 全流水线,断点可恢复 ① 处理档位单一(无 720p/字幕/多语言等 profile 概念);② AI 元信息需逐条人工复核,无批量复核队列;③ 无批量打标签
自动上传 COS 代码底座已在主线:Node 运行时 MEDIA_PROVIDER=tencent-cos 标准 COS adapter(签名直传分片 + Head 校验,apps/api/src/runtime/create-media-store.ts:7-20apps/api/src/storage/tencent-cos-media-store.ts);Collector 经 API 签名 URL 直传,对存储后端透明(renditions.storage_provider 默认 'cloudflare-r2',migration 0006) 主线没有任何 COS 写入路径被激活:Cloudflare 部署走 R2 binding;Node/COS 分支默认 fake,且按 ADR 0004「实现、计费、主机写入、部署均未授权」;无「ready 后自动复制到 COS」的触发器
上下架管理 ready→published→hidden⇄published 状态机服务端强制;发布门禁(系列/内容类型/宝宝可见/有效视频);隐藏即时生效;每次变更落 resource_events ① 无批量上下架(单资源按钮);② 无定时上下架;③ 无按系列批量发布/隐藏;④ 审计事件写了表但 admin 无查看页;⑤ scan-targets 有 API 无 UI

一句话:链路已闭环且工程化程度高,管理后台停留在「单条操作 + 任务队列查看」形态;批量审批、批量上下架、资产库浏览、源管理、审计视图是五块清晰空白的拼图——恰好对应 docs/ROADMAP.md 里 v0.5 之后的候选方向②「家长管理效率」。

2.5 一个重要的事实修正:COS 的真实状态

你的需求表述是「处理完自动上传腾讯云 COS 桶」,但主线现状是:

这不是需要今天解决的问题,但它是 §6 决策清单里唯一涉及真金白银的一项。

3. 社区调研:六组参考

3.1 下载管线自动化:Sonarr / Radarr / Prowlarr(*arr 系列)

来源:SonarrRadarrSonarr Activity 文档Radarr Library 文档

3.2 YouTube 订阅下载器:Tube Archivist / Pinchflat / MeTube

来源:Tube ArchivistTA Downloads 文档PinchflatMeTube

3.3 家庭媒体库:Jellyfin / Plex

来源:Jellyfin 元数据Jellyfin 电影库

3.4 CMS 与 DAM:Payload / Directus(附 Strapi、react-admin、DAM 通用模型)

来源:Payload UploadPayload DraftsDirectus FlowsCloudinary DAMBynder Asset WorkflowResourceSpaceStrapi Media Libraryreact-adminRefine

3.5 后台设计系统:shadcn、Ant Design Pro、TDesign、Arco

设计系统 视觉语言 生态与适配 落地成本(对 React+Vite、无组件库的我们)
shadcn/ui(+Tremor 图表) Linear/Vercel 极简风:侧栏+顶栏、中性灰底+单一强调色、8px 圆角、原生深浅色 「复制源码」模式(Radix+Tailwind),代码完全自有无锁定;shadcn-admin 本身就是 Vite+React+TS 模板 ——渐进引入 Tailwind 后按需复制组件,对现有代码侵入最小
Ant Design Pro 经典企业中后台:品牌蓝、高密度、小圆角 antd + ProComponents(ProTable/ProForm)重表格场景提效显著;官方脚手架基于 umi,Vite 下只取组件库 中——组件库即装即用,但布局体系与现有单页架构需适配;包体大
TDesign Starter 腾讯风:清爽蓝、卡片化、密度可配 Starter 主打 Vue3;tdesign-react 可用但 React 模板/物料生态薄;与腾讯云/COS 控制台审美同源 中高——组件库可用,模板资产需自建
Arco Design Pro 字节风:暖灰底、高密度、主题化最强 React 版即装即用,20 个页面模板;社区维护近乎停滞 中——但需接受低更新频率

结论:追求现代感与低维护选 shadcn/ui;偏好国内企业风且重表格选 antd;喜欢腾讯生态选 TDesign 但要多付模板成本;Arco 因维护停滞不建议新项目采用。

来源:shadcn-adminshadcn dashboard 示例ProComponentsTDesign Startertdesign-reactArco Design

3.6 儿童英语内容运营:Lingokids、Khan Academy Kids 等

来源:Lingokids 进度报告Khan Academy KidsDuolingo ABCSuper SimpleLittle Fox 分级目录CBeebies 家长 FAQCommon Sense Media 分级Seattle Children's 屏幕时间Mayo Clinic 屏幕时间

3.7 跨社区共性结论

20 余个产品交叉验证出同一套骨架:

  1. 五段流水线:来源订阅 → 队列暂存 → 筛选/审核 → 批量执行 → 归档库。所有成熟工具都是这个形状,无一例外。
  2. 内容与任务分离:内容看缩略图卡片墙(低密度、视觉优先),任务看密集表格(高密度、状态优先)。管理后台应分成「片库」和「处理队列」两个视图,而不是混在一页。
  3. 审核是队列里的关卡,不是独立流程:自动化优先,例外(Ignore/黑名单/人工导入)时才介入——与我们的 pending_review 机制同构,社区只是把它做成了批量操作。
  4. 失败处理是「显式错误 + 手动重试/黑名单」,不做无限自动重试——与既有 Collector 行为一致,方向正确。
  5. 复杂参数一律封装为命名预设/Profile(质量档位、Option Presets)。
  6. 发布是一等状态机:草稿/已发布/已修改三态、定时上下架、版本回滚,在 CMS/DAM 里是标配能力。

4. 五个设计方案

每个方案 = 把 §3 中一类风格整体嫁接到现有管理平台。评估维度:信息架构、关键界面、嫁接成本(对当前 React+Vite 无组件库代码基)、优缺点。

方案 A ·「采集驾驶舱」(血统:*arr + Tube Archivist)

一句话:管理平台 = 流水线控制台,深色、高密度、队列中心。

方案 B ·「片库策展室」(血统:Jellyfin/Plex + Netflix CMS)

一句话:管理平台 = 给宝宝选片子的策展室,海报墙、详情抽屉、上下架=策展。

方案 C ·「企业内容中台」(血统:Ant Design Pro / TDesign)

一句话:标准企业中后台,表格+表单+高级筛选全覆盖,国内运营习惯,与腾讯云控制台审美同源。

方案 D ·「现代轻工作台」(血统:shadcn/Linear/Vercel)

一句话:极简、快、键盘友好;Tailwind + 复制式组件;命令面板直达一切。

方案 E ·「数据运营台」(血统:Directus Flows/Insights + Payload drafts)

一句话:schema 驱动 CRUD + 可视化自动化管线 + 运营仪表盘,看到整条流水线在跑。

4.6 对比与推荐

维度 A 驾驶舱 B 策展室 C 企业中台 D 轻工作台 E 运营台
批量操作效率 ★★★ ★★★ ★★★ ★★
内容浏览体验 ★★★ ★★ ★★ ★★
嫁接成本 中高
维护负担
视觉气质 极客深色 温暖视觉 企业标准 现代中性 数据感
单家庭规模适配 最高

推荐组合:D 为底座 + B 的片库视图 + A 的队列与审核闸门。 理由:

  1. 你的自述痛点是「思路匮乏、不知道需要哪些能力」——社区答案是:你需要的是批量操作(A/D 提供)+ 看得见的片库(B 提供),而不是一套更重的框架。
  2. D 的落地成本最低且与现有代码基零冲突,可以逐视图迁移、每步可交付,符合仓库「短分支、小步走」的交付规则。
  3. C 全盘引入的包体与维护代价对单家庭产品不划算,但其表格交互习惯可作为 D 中 TanStack Table 的配置参考;E 的仪表盘与定时上下架是有价值的,放 roadmap 后期按需取用。

这不是排他决定:五个方案的界面元素可以混搭(D 骨架上放 B 的海报墙、A 的队列、E 的仪表盘各一页),推荐组合本身就是这么构成的。

5. Roadmap 提案

5.1 前置约束(来自 docs/ROADMAP.md,必须尊重)

5.2 里程碑

里程碑 内容 对应社区范式 依赖
M0 方向定稿(设计,不改代码) 你选定设计方向(§6 决策①);按选定方向出高保真 HTML 设计稿(可仿 KB-71 的交付方式);定义批量操作 API 契约草案(改 contracts 先行) §3.7 共性 本报告
M1 批量审核与上下架 批量批准/否决/发布/隐藏端点 + UI;run 列表分页/过滤;scan-targets 源管理界面(API 已有);审计事件查看页;AI 元信息 needs_review 批量复核队列 A 的队列 + TA 审核闸门 + D 收件箱 M0
M2 片库与元数据 网格/表格双视图 + 详情抽屉 + 签名预览内嵌;推荐元数据模型落地(追加 migration:CEFR/难度/topics/vocabulary/skills/合规标志);系列内集数排序;封面提取完善 B 策展室 + §3.6 元数据模型 M0(可与 M1 并行)
M3 内容质量门禁 适龄自动检查(时长 3-7 分钟提示、标签完整性、惊吓度标记);对应 ROADMAP 候选③ §3.6 Common Sense 维度 M2
M4 存储与大陆候选(独立门禁) 若你授权激活:COS 费用确认 → 桶创建/CAM → Node 运行时部署 → renditions 双 provider 记录 → 「ready 后同步 COS」触发器。技术底座(COS adapter + 签名直传协议 + storage_provider 字段)已存在;若不授权:R2 继续主线,本项保持 Parked DAM 多存储 + ADR 0004 你的明确授权(费用/账号)
M5 运营洞察与自动化 仪表盘(库存/积压/失败率/上下架数/宝宝端日观看聚合);定时上下架;来源规则模板(频道订阅式「配一次免维护」+ 截断日期) E 运营台 + Pinchflat 来源规则 M1、M2

5.3 横切红线(所有里程碑适用)

新发现资源不自动下载(allowlist + 审批闸门);1080p 如实标注不放大;D1 迁移只追加;媒体对象不自动删除;元数据人工字段可锁定防 AI 覆盖;不引入遥测、账号体系、付费能力。

6. 待你决策的分叉点(睡醒后看这里)

  1. 设计方向(§4):五选一或组合。我的推荐是「D 底座 + B 片库 + A 队列」。回复「按推荐」即可,我会登记 M0/M1 实现需求;想换方向直接说编号。

  2. COS 激活节奏(§2.5、M4)——唯一涉及真实费用的分叉,三选一:

    • ① 维持 R2 主线(零成本,什么都不用做,COS 保持已批准未激活);
    • ② 授权启动激活门禁链(先做精确费用确认,每一步再单独向你要授权);
    • ③ 双存储并行(成本最高,当前不建议)。

    说明:①和②不冲突——可以先①跑着,哪天国内访问速度成为真实痛点再启动②;这条我按你的规则只做方案不执行

  3. Roadmap 排序:M1(批量操作)先于 M2(片库)是否认可?两者也可并行分派。

7. 附录:本报告的证据基础