# Dramivio 按设计稿实施路线

2026-10-03 · 修订 2 · 在「短剧库」与「juku-mobile」中实施。

## 验收依据

产品以用户最新确认、最新高保真原型与 PRD 为准。现有代码是可复用资产，不能反向改变页面、权限、额度或操作路径。旧路线中“固定保留 Go 单体、手写后台和密码登录”的前提撤销。

执行优先级：**用户最新确认 → 最新交互原型及页面清单 → 已确认 PRD 的业务规则 → 本路线与任务卡 → 现有实现**。视觉按 `design.js`、`design.css` 与设计 Token；旧 PNG 若与最新原型不一致，标为待重导出，不用旧图覆盖用户修订。原型里的额度、邀请码、邀请参数和许可日期是示例，业务值来自服务端。PRD 标为“建议/待确认”的游客 App 额度、邀请初始值、许可期限等不自动转成上线默认值。

以上优先级按领域应用：布局与视觉按最新原型；注册、授权、额度、邀请、许可与反刷按已确认PRD。原型的演示动作、占位链接、未接线行为和常量不具有业务优先权，不能用它们绕过登录或服务端检查。

设计基线包括 149 个页面/状态及中英文版本。播放器采用用户指定的最早概念稿布局，使用 Dramivio 品牌；列表封面无阴影，追剧使用空心/实心爱心。实现差异必须修正；如平台确实不能实现，先提供能力验证与影响说明，不静默删功能或改设计。

配套文档：[逐项任务卡](dramivio-model-task-cards.md)、[全页面验收矩阵](dramivio-design-acceptance-matrix.md)、[首轮技术增量记录](dramivio-existing-project-implementation.md)。记录已通过的底层测试，不等于产品已按稿完成。

追加确认：[代理线路与无落盘转发](dramivio-proxy-relay.md)。网站必须转发视频，不能保存视频文件；短期、有容量和绝对TTL的内存复用用于减少代理流量。内置与标准API来源可绑定后台自定义 HTTP(S)/SOCKS5 线路。网站旧服务器下载、补集、合并及启动队列恢复必须关闭，App缓存仍写入用户手机。NET00–NET03补充原产品任务，并纳入P00/P01、O00/O01与M00验收。

## 目标产品

| 模块 | 必须实现的结果 | 不能沿用的旧行为 |
| --- | --- | --- |
| 品牌与双语 | 已设计 Logo、浅色绿色 Token、中文/英文、简洁必要文案 | 「短剧库」工具界面、中文硬编码、介绍卡占空间 |
| 首页 | 搜索、10 个后台标签横滑、右固定筛选、继续观看、双列推荐及查看更多 | 首页频道下拉、剧库/推荐模式切换 |
| 查询页 | 返回+标题、可改关键词、综合筛选；查看更多与筛选共用 QueryList | 在首页过滤全量快照；独立“联网搜索”操作 |
| 导航 | 手机 App/Web：主页、追剧、缓存、我的；桌面 Web 响应式导航 | 三栏导航、账号藏在设置或工具菜单 |
| 剧卡 | 封面直接播放/续播，右下角独立爱心；不显示供应商名 | App 必须先进入旧 Drama 页；用户选择渠道范围 |
| 聚合 | Drama→Edition→Episode→SourceEpisode；自动择优来源；去重后每页 10 部 | 改为“频道 1”仍要求用户选频道；快照截取 10 条冒充分页 |
| 登录 | 成熟开源邮箱 OTP；首次验证注册，已有邮箱登录；登录后恢复动作 | 消费者用户名/密码注册；App“不需要账号登录” |
| 追剧/缓存 | 追剧需登录；缓存需登录 App；Web 缓存入口引导下载 | 游客追剧、无账号离线文件、Web 服务器下载任务作为用户缓存页 |
| 播放 | 顶部返回/剩余次数/更多，右侧爱心/缓存/分享；底部剧名、集数、进度、选集/倍速/下一集；控件自动隐藏 | 沿用旧工具播放器覆盖层，缺额度和右侧操作 |
| 观看记录 | 每集位置、观看事实、完成状态、跨端续播与冲突处理 | 每剧一个最近记录充当逐集历史和邀请依据 |
| 额度/邀请 | Web 10、App 50，共享当日消耗；同集当日不重复扣；邀请参数后台控制 | 仅前端计数；多端叠加 60；注册即发奖 |
| 运营与扩展 | 成熟开源后台、标签/推荐/规则/渠道/审核；广告、收费完整设计与接口预留 | 只补现有渠道表单；将 MVP 缺失能力归为可删的“以后再说” |

邮箱、AI 情节搜索、去重、逐集记录、额度、邀请、缓存、账号安全与基础后台都是免费首版必需项。广告、收费、推送的真实开启可以后置；其页面、契约、开关和异常状态本轮路线必须覆盖。

## 仓库职责与复用边界

「短剧库」承担 Web、API、管理后台和任务的交付归属；「juku-mobile」承担 RN App。归属不代表必须维持当前单进程或框架。新增开源认证/后台进程可放在「短剧库」仓库，统一部署说明与 API；不能为保留原架构改变消费者流程。

| 资产 | 处理方式 | 复用条件 |
| --- | --- | --- |
| Go 来源适配、网络防护、媒体代理、FFmpeg、导入任务 | 保留或提取为内部 adapter | 接受统一内容身份、业务授权与配置版本；不绕过扣次或撤权 |
| 标准 API 自定义渠道 | 保留底层；迁到新管理后台的渠道模块 | 创建/测试/启停/归档、版本冲突、任务状态与来源安全仍有回归 |
| 旧嵌入式 Web | 重建消费者页面；暂保留管理过渡入口 | 最终布局和操作按稿；网站关闭服务器视频写入，App缓存写入手机 |
| Expo/RN、Query、状态库、原生视频内核 | 优先复用 | 设计导航、账号隔离、原生兼容和生命周期通过验证 |
| 旧消费者密码/匿名 viewer | 仅兼容迁移 | 不作为目标登录方案；可信绑定到新账户，游客不是登录态 |
| 每剧最近进度、来源 ID、本机文件 | 有界迁移 | 只迁移真实存在的记录；映射与账号归属可信，不伪造完成/许可 |
| JSON 配置、文件锁 | 可留单实例的过渡渠道配置 | 不能承载并发额度、发奖或跨实例权益真相 |
| 手写管理列表/认证 | 替换通用功能，保留必要业务命令 | 不再自建整套后台 CRUD/认证；角色和发布审计不得减少 |

登录首选此前 PRD 的自托管 Better Auth 官方 Email OTP/Expo 集成；后台首选 Payload 开源核心。它们是兼容 PoC 候选，不是未经验证的接入成果。PoC 不通过时更换可满足要求的开源方案；不能退回密码产品或删后台状态。Go 可继续承载业务，也可桥接认证/管理服务；不强制新建 Hono，更不把 Hono 或 Go 写成产品约束。

邀请社区插件只评估邀请码/归因及 OTP 自动注册兼容；奖励、风险与观看资格由事务业务模块实现。所有第三方依赖核验许可证、锁定版本；不开付费 SDK。原生 iOS 系统 API 不属于采购第三方 SDK，也不宣称它开源。

## 最小目标模型与接口

| 域 | 数据与接口责任 | 关口 |
| --- | --- | --- |
| 内容/来源 | canonical drama、edition、episode、source episode；来源能力与授权；查询 cursor 绑定查询摘要、排序与快照版本 | 同名异剧不误合并；映射可撤销；不同剪辑不套秒数；API 每页 10 部去重结果 |
| 身份 | 框架认证表、业务 account、guest/install 映射、session、协议版本；官方客户端登录 | Cookie/CSRF/安全存储、退出撤销、首注册唯一、迁移可信 |
| 配置/能力 | 已发布 policy version、10 标签、推荐、额度、邀请、风险、广告/收费开关；allowed/reason/retryAt/requirements | 前端与 API 同时执行；配置不能覆盖账本、内容授权与权限不变量 |
| 观看 | episode progress、watch event、playback session、revision、sequence、delete epoch | 拖回可记录；迟到旧事件不覆盖；清历史不返额度且旧离线上报不能复活历史 |
| 权益 | episode unlock、base/reward ledger、device budget、reservation、idempotency、Outbox | PostgreSQL 事务与唯一约束；100 同集并发扣一次；不同集不超额 |
| 邀请 | campaign snapshot、binding、qualification、risk decision、reward operation | 一次归因；有效观看有媒体交付证据；参数改动不毁旧承诺；不公开好友邮箱 |
| 缓存 | permit preview、download order、device license、asset、queue | 账号/设备/统一集身份；真实到期；未知签发先对账；系统后台任务恢复 |
| 运营 | 开源框架 CRUD/角色/草稿；独立发布/发奖/撤权业务命令和审计 | 管理端不能直接改余额；REST/GraphQL/Local API 一致授权 |

公开 API 不返回供应商名称、内部渠道配置或长期裸媒体链。运营端可自定义标准 API；指定网站是第二类独立 adapter，按目标样例开发，不支持执行任意远程脚本。尚未指定网站不阻塞首页、登录、查询与播放器的设计落地。

日额度按服务端日期与 PRD 共享消耗：Web 用 10 集后 App 基础余 40；App 用 20 后 Web 不再解锁新集，当天旧集可重播。奖励独立分账。首次取得有效媒体授权前提交解锁；源预检失败不扣，响应丢失按幂等键恢复。同源换线不双扣；自动下一集先授权，不能提前拉未解锁正片或密钥。

## 分阶段实施

每阶段以一个明确功能交付，按任务卡的前置和证据推进。视觉骨架、成熟框架 PoC 与内容模型可以并行；业务权限尚未接通的页面只能用于开发预览，不能作为首版上线。

| 阶段 | 任务卡 | 交付与顺序 | 必须提交的证明 |
| --- | --- | --- | --- |
| 0 | S00 | 固定最新设计、Token、双语和 149 状态映射，盘点迁移；不重开产品设计 | 设计基线摘要、差距清单、截图一致性及任务全覆盖 |
| 1 | S01–S04 | 四栏导航 → 首页 → 统一查询 → 经典播放器视觉骨架 | 双端中英文、主要断点/安全区/字体放大；操作能到对应状态，Mock 清楚标识 |
| 2（可与阶段 1 并行） | A00、A01、C00、P00、O00 | 邮箱认证/后台 PoC、事务库/统一身份、真实原生/Web 播放与离线可行性 | 框架集成、迁移、浏览器和 Android/iOS 能力实测；不是类型检查代替 |
| 3 | C01、A02、F00 | 去重后真实查询 → 邮箱登录/我的/续办 → 登录追剧 | 新 API 联调、10 标签发布、分页竞态、注册与权限边界 |
| 4 | E00、H00、P01 | 事务授权与共享额度 → 逐集事实/续播 → 正式播放器 | 并发/响应丢失/午夜、跨端冲突；长按恢复、自动下一集、匿名换线、弱网首帧 |
| 5 | I00、O01、A03、M00 | 邀请 → App 缓存 → 账号生命周期 → 完整管理运营 | 防重复注册/发奖、飞行模式/后台/换账号/到期、注销与审计 |
| 6 | X00、R00 | 全扩展契约/关闭态 → 免费首版端到端发布关口 | 149 状态分类验收；关闭不请求；真实设备、迁移/回滚/监测 |
| 扩展开启 | X01–X03 | 合格广告供给、支付与通知分别启用 | 可信奖励/交易证明、频控/订单对账/权限；不得只接 UI 开关 |

S04 只还原播放器操作层；P00 验证内核，P01 接正式授权、状态和行为。这三步不能合并成“画面出现即播放器完成”。A00 通过后才做真实消费者会话；I00 依赖 H00 的有效观看事实，O01 依赖账号、授权及 O00 实测能力。

## 广告与收费预留

| slot | 位置 | 首版关闭行为 | 开启验收 |
| --- | --- | --- | --- |
| home_feed | 首页推荐第 6 部后整行；每 10 部最多 1 条 | 不渲染、不发请求 | 不占 10 部剧；无填充折叠；慢响应不移动正在点击的卡片 |
| query_feed | 二级查询第 6 部后整行 | 同上 | 不改变 cursor、剧数量、滚动恢复或筛选 |
| me_card | 我的功能列表下方 | 不留广告空入口 | 有“广告”标识，审核素材及目标链接，跨端频控 |
| episode_gap | 两集之间，仅合格 App；默认关闭 | 直接正常进入下集授权 | 保存进度；失败/关闭不阻断下集；正片中、重播、离线不插 |
| quota_reward | 额度不足时用户主动选择，仅合格 App | 不显示无供给入口 | offer 快照、后端可信完成证明、幂等奖励、未知结果对账 |

Web 只可开启列表/我的广告。登录、验证码、选集/倍速、缓存队列、支付及正片中无广告。广告不计正片时间、邀请资格或剧集额度。免费、会员、续费失败、恢复购买、订单待定/失效、退款/撤权与奖励异常均在设计验收矩阵中保留；默认 payments/ads/push=false，接口也关闭新增动作。支付未启用前不引入商用 SDK；开启后仍经同一 entitlement，不能被固定免费 50 门槛截断。

## 测试与能力边界

- **视觉**：以设计 Token 和最新原型为参照，中文/英文、App 390×844 与桌面 1280×900，补 320/768、安全区、系统字体放大、键盘/读屏。以主要区域与状态截图对照，不把画布像素强锁到所有设备。
- **功能**：每卡正常、空、失败、登录/权限、重试状态；封面/爱心点击独立；登录取消不执行待办，返回不提交草稿；旧 API/客户端回归有兼容期限。
- **权益**：100 同集并发、不同集超额、跨账号设备预算、重复邀请/广告证明、午夜和重试；事务库或证明故障不能降级放行。IP 仅作风险信号，家庭/NAT/IPv6/VPN 与申诉覆盖。
- **播放**：真实 Android/iOS 与 Safari/Chrome；正常/弱网首帧、重缓冲、连续切集、退出释放、来电后台、控件手势冲突。首帧以画面就绪事件/录屏证明，metadata/onLoad 不是首帧。
- **离线**：实际授权媒体格式、飞行模式冷启动、后台/强退恢复、文件缺失/空间不足/过期/换账号/注销。无 DRM 只保证普通客户端校验，不能硬阻复制；离线即时撤权和已缓冲媒体不可瞬间收回。
- **迁移/运营**：旧账户不可把用户名当已验证邮箱；旧来源 ID 保留映射；最近进度不能伪造逐集事实；旧文件不得直接视作许可证。扩展→兼容→收缩，回滚不能丢消费事实、重发奖励或恢复注销资料。

每卡交付代码、依赖锁定、实际测试结果、截图/录屏、未验证项和回滚方法。测试全部通过后子 agent 分别审查设计一致性与业务边界，未关闭 P0/P1 不推进上线。文档复审通过、模拟测试通过、JS 导出通过都不能自称真机或产品验收通过。

## 当前完成度

首轮已完成标准渠道及媒体安全等技术增量；部分爱心/封面细节与长按逻辑可复用。**当前产品尚未按设计验收通过**：四栏导航、新首页/查询、邮箱 OTP、统一去重分页、共享额度/邀请、逐集跨端记录、账号离线许可和最新播放器布局仍需完成。游客追剧、频道选择、快照分批展示是过渡实现，必须退出最终消费者流程。

首轮验证的 Go、Web、App 回归记录保留；下一项按 S00/S01 开始对齐设计，A00/A01/C00/P00/O00 并行验证。正式服务、App 安装包与 OTA 尚未发布，具体能力只按实际证据声明。