08-前端实验分支交接与调试说明

08-前端实验分支交接与调试说明

文档性质：当前 iOS 前端实验分支交接与调试说明
用途：给接力开发、调试和 code review 使用，说明当前前端实验分支相对 main 多了什么、代码怎么组织、如何启动和验证
适用范围：EveryDayJapanese-iOS 的 experiment/contentfront-frontend 分支，以及与之对应的 Yomiya Demo SwiftUI 实验面
边界：

• 这份文档回答的是前端分支实现与接力方式，不替代 01 / 06 / 07
• 内容对象、后端现实与字段边界仍以 02、06 为准
• 页面视觉原则仍以 07 为准
• 这里不展开历史推理过程，历史设计稿和计划稿继续留在仓库内 docs/ 与 archive/ 默认读者：iOS 接力开发 / 调试人员 / code reviewer
  最后更新：2026-04-16

---

1. 这份文档解决什么问题

当前 experiment/contentfront-frontend 分支已经不只是一个零散 demo，而是一套可跑通的前端实验面。

接力人最容易卡住的，不是“有没有代码”，而是下面几件事：

1. 和 main 比，这个分支到底新增了什么
2. 这些新增代码分别落在哪些模块
3. 哪一层是页面，哪一层是数据，哪一层是样式和组件
4. 现在应该从哪里开始调试，改 UI 时先动哪个文件
5. 哪些结论已经冻结，不要在接力时无意回退
6. 哪些问题值得在 PR 里继续讨论，但还不该在实现里偷偷改掉

这份文档就是把这些问题一次讲清楚。

---

2. 当前分支相对 main 多了什么

以 2026-04-06 这个节点看，当前分支相对 origin/main 的关键变化可以概括成一句话：

新增了一套被 feature toggle 包起来的 Yomiya Demo 前端实验面，里面包含首页双状态、搜索入口、方向页、合集详情、内容详情容器、统一视觉 token / 共享组件、fixture 数据源和定向测试。

2.1 量级判断

• 当前分支已经不是“补几个 SwiftUI 页面”，而是一条完整的实验链路
• 除了页面本身，还包含 coordinator、fixture repository、preview support、design tokens 和定向测试
• 这意味着接力时要把它当成一个小型前端子系统，而不是零散 demo 文件夹

2.2 对 main 的侵入边界

相对 main，真正改动到现有 app 主入口的地方其实很少，主要是这几处：

文件	改动作用
EveryDayJapanese/Controller/Debug/FeatureToggle.swift	新增 yomiyaDemo 开关
EveryDayJapanese/Controller/MainTabBarController.swift	当 toggle 打开时，把 YomiyaDemoEntryViewController 追加成一个 tab
EveryDayJapanese.xcodeproj/project.pbxproj	把新增的 Yomiya Demo 代码和测试接进工程

结论很简单：

• 这条实验链路当前是隔离接入的
• 不会默认替换现有正式首页
• 接力调试时，只要守住 feature toggle 入口，风险是可控的

flowchart LR
  A[FeatureToggle.yomiyaDemo] --> B[MainTabBarController]
  B -->|toggle on| C[YomiyaDemoEntryViewController]
  C --> D[YomiyaDemoCoordinator]
  D --> E[Home]
  D --> F[Search]
  D --> G[Collection List]
  D --> H[Collection Detail]
  D --> I[Content Detail]

这张图说明 demo 现在是怎么接进现有 app 的，也说明为什么它当前不会直接替换正式首页。

---

3. 这轮对话已冻结的前端结论

下面这些不是“建议”，而是这轮已经被用户反复确认后的实现结论。

3.1 视觉方向

• 整体是浅色、通透、轻层级，不走厚重杂志感，也不走深色音乐 App 气质
• 阅读感优先通过字阶、字重、留白和模块节奏建立，不通过描边补层次
• 首页要靠近 QQ 音乐那种更紧凑、更利于扫读的阅读节奏
• 搜索和 chips 只是控制层，视觉上必须弱于 Hero 和内容模块

3.2 字号和密度

• 区块标题要更重一点，先把阅读锚点立住
• 列表里的标题、副标题、meta 都要更紧凑，不能太松
• 标题和副标题是一组，组内距离要小于模块距离
• 首页底部 还能继续逛 这类大卡片，卡片间距要比普通纵向列表更大

3.3 播放语言

• Hero 是首页唯一保留“白底 + 镂空三角”播放语言的区域
• 独立播放按钮统一用“白底 + 黑色实心三角”
• 纵向内容行里的视频提示只保留白色三角 glyph，不再带白色圆底
• 不再通过播放按钮描边、玻璃圆片或黑色透明底条去补精致感

3.4 Hero Banner

• 标题位置可以比最初版本略微下沉
• 长一点的副文案要与播放按钮所在阅读带齐平，并允许换行
• 右上角图片区要缩小
• 右上图片区与右下播放按钮之间要有明确间隔
• 右上图片区和右下播放按钮的右缘要对齐

3.5 合集详情页

• 顶部头部不再使用整块色块矩形说明框
• 固定改为“左封面 + 右侧介绍”的透气型头部
• 进入合集详情后，不再重复展示“这是合集”的 icon 提示
• 列表要尽早开始，不能继续被 tag、说明层往下压

3.6 搜索与共享语言

• Search 必须完整复用 Home 的 YomiyaSearchBar + YomiyaSectionHeader 语言
• 不再允许“看起来很像，但 Search 自己再实现一套输入框和标题行”
• 搜索建议、空状态和结果区继续保持轻，不回到营销型搜索页

3.7 阴影与旧原型清理

• 当前 active 页面默认删除阴影，不把“留一点轻阴影”当作常规层级语言
• Content Detail 独立 bridge panel 已从主路径移除
• YomiyaTopBar.swift、YomiyaCollectionRouteCard.swift、YomiyaContentContextBar.swift、YomiyaNextStepView.swift 已不再属于 active 主路径
• 后续如果某个区域必须靠阴影或旧桥接面板才能成立，应优先怀疑结构和留白，而不是把旧方案加回来

---

4. 代码层面的变化地图

下面这张图可以帮助接力人快速建立代码认知：

YomiyaDemo/
├── Home/                首页与首页状态切换
├── Search/              搜索入口页
├── CollectionList/      方向页 / 合集列表页
├── CollectionDetail/    合集详情页
├── ContentDetail/       内容详情容器
├── Views/               可复用页面原型与基础构件
├── Theme/               视觉 token
├── Model/               Demo 数据模型
├── Repository/          Fixture 数据源与协议
├── PreviewSupport/      SwiftUI Preview 支撑
└── YomiyaDemoCoordinator.swift

flowchart TD
  A[YomiyaDemoFixtureRepository<br/>或真实 Repository 实现] --> B[ViewModel]
  C[YomiyaDemoModels] --> B
  B --> D[SwiftUI View / ViewController]
  D --> E[YomiyaDemoCoordinator]
  E --> F[Home / Search / Collection List / Detail]
  G[YomiyaDesignTokens + Views] --> D

这张图比目录树更重要，因为它直接回答“改数据、改页面、改路由、改样式时分别应该动哪一层”。

4.1 App 接入层

EveryDayJapanese/Controller/Debug/FeatureToggle.swift

• 新增 FeatureToggle.yomiyaDemo
• 当前 demo 是否出现在 tab bar，先看这个开关

EveryDayJapanese/Controller/MainTabBarController.swift

• 当 FeatureToggle.yomiyaDemo.isOn 时，把 YomiyaDemoEntryViewController() 追加成一个 tab
• 如果 YomiyaDemoDebugLaunchTarget.current != nil，会默认选中 demo tab

这意味着：

• demo 入口是 feature-gated 的
• 也是 debug-route-aware 的

4.2 路由与页面装配层

EveryDayJapanese/Controller/YomiyaDemo/YomiyaDemoEntryViewController.swift

• 是 demo tab 的根入口
• 内部持有 YomiyaHomeViewModel
• 通过闭包把首页跳转行为转给 YomiyaDemoCoordinator
• viewWillAppear 时会隐藏导航栏，保证 Demo 页面的轻壳层级成立

EveryDayJapanese/Controller/YomiyaDemo/YomiyaDemoCoordinator.swift

• 当前 demo 路由中枢
• 负责 Home / Search / Collection List / Collection Detail / Content Detail 之间的 push
• 还负责内容详情页的“来源合集返回”与“下一条内容”链路

如果接力人要改页面跳转关系，先看这个文件。

4.3 数据和状态层

EveryDayJapanese/Controller/YomiyaDemo/Model/YomiyaDemoModels.swift

• 定义首页 tab、方向、合集、内容项、Hero 卡片、搜索 payload 等 demo 数据模型
• 这是 UI 读取数据的统一语义层

EveryDayJapanese/Controller/YomiyaDemo/Repository/YomiyaDemoRepositories.swift

• 只放协议
• 目的是让 ViewModel 不直接绑死 fixture

EveryDayJapanese/Controller/YomiyaDemo/Repository/YomiyaDemoFixtureRepository.swift

• 当前 demo 的真实数据来源
• 所有首页、方向页、合集详情、搜索结果，最终都从这里组装 payload
• 想改默认内容、默认文案、fixture id、tab 数据、搜索样本，优先改这里

这是接力最重要的文件之一。

4.4 页面层

首页

• EveryDayJapanese/Controller/YomiyaDemo/Home/YomiyaHomeView.swift
• EveryDayJapanese/Controller/YomiyaDemo/Home/YomiyaHomeViewModel.swift

负责：

• 推荐 和非 推荐 分类态切换
• Hero、热门推荐、轻松入门、播客精选、今天正在更新、更多你可能想看、还能继续逛

搜索入口

• EveryDayJapanese/Controller/YomiyaDemo/Search/YomiyaSearchEntryView.swift
• EveryDayJapanese/Controller/YomiyaDemo/Search/YomiyaSearchEntryViewModel.swift

负责：

• recent search
• suggestion
• 搜索结果里的内容 / 合集双结果区

合集列表页

• EveryDayJapanese/Controller/YomiyaDemo/CollectionList/YomiyaCollectionListView.swift
• EveryDayJapanese/Controller/YomiyaDemo/CollectionList/YomiyaCollectionListViewModel.swift

负责方向承接页，直接复用 YomiyaCollectionFeedCard，不再回到旧 header / badges / summary 模板。

合集详情页

• EveryDayJapanese/Controller/YomiyaDemo/CollectionDetail/YomiyaCollectionDetailView.swift
• EveryDayJapanese/Controller/YomiyaDemo/CollectionDetail/YomiyaCollectionDetailViewModel.swift
• EveryDayJapanese/Controller/YomiyaDemo/CollectionDetail/YomiyaCollectionHeroView.swift

负责单合集厚页和直接消费入口。

内容详情容器

• EveryDayJapanese/Controller/YomiyaDemo/ContentDetail/YomiyaContentDetailContainerViewController.swift

当前不是重做正式阅读页，而是在正式内容详情外包一层轻量容器：

• 主路径只保留内容消费主区
• 独立 bridge panel / 来源合集 / 下一步 舞台已从 active 页面移除
• 测试文件名里仍有 Bridge 历史命名，但当前断言的是“不要再回到旧 bridge 结构”

4.5 视觉 token 与复用组件

EveryDayJapanese/Controller/YomiyaDemo/Theme/YomiyaDesignTokens.swift

这是这轮前端整理后最重要的样式总线，里面已经集中收口：

• 页面水平 / 垂直 inset
• 模块间距、组距、行距
• Hero 尺寸
• card 尺寸
• 字号、字重
• 浅色通透的 panel tint
• accent 对应的 hero / feed / artwork 色板

要改阅读密度、间距、字号、Hero 尺寸，先看这个文件。

EveryDayJapanese/Controller/YomiyaDemo/Views/

当前复用原型主要都在这里：

文件	作用
YomiyaHeroCard.swift	首页 Hero Banner
YomiyaSectionHeader.swift	区块标题与右侧动作
YomiyaSearchBar.swift	首页点击入口 + 搜索页输入态的共享搜索框
YomiyaCollectionRow.swift	首页纵向合集行
YomiyaCollectionRailCard.swift	横滑合集卡片
YomiyaCollectionFeedCard.swift	底部续逛与分类态大卡片
YomiyaContentRow.swift	纵向内容行
YomiyaPlayButtonBadge.swift	播放按钮和三角 glyph 逻辑
YomiyaCollectionMarker.swift	合集标记

如果要调一个具体样式，路径通常是：

1. 先看 YomiyaDesignTokens.swift
2. 再看对应 Views/ 组件
3. 最后看页面层有没有针对该组件的额外排版

---

5. 现在应该怎么用这套模块

5.1 如果只是想改文案 / fixture / 默认模块内容

先改：

• EveryDayJapanese/Controller/YomiyaDemo/Repository/YomiyaDemoFixtureRepository.swift

重点入口：

• makeHomePayload()
• makeCollectionListPayload(directionID:)
• makeCollectionDetailPayload(collectionID:)
• makeSearchEntryPayload(query:)

5.2 如果想改页面顺序、跳转或承接关系

先改：

• EveryDayJapanese/Controller/YomiyaDemo/YomiyaDemoCoordinator.swift
• EveryDayJapanese/Controller/YomiyaDemo/YomiyaDemoEntryViewController.swift
• EveryDayJapanese/Controller/YomiyaDemo/Home/YomiyaHomeView.swift

5.3 如果想改阅读密度、字阶、间距

先改：

• EveryDayJapanese/Controller/YomiyaDemo/Theme/YomiyaDesignTokens.swift

然后看：

• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaSectionHeader.swift
• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaHeroCard.swift
• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaCollectionFeedCard.swift
• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaContentRow.swift

5.4 如果想改播放 icon / glyph 语言

先改：

• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaPlayButtonBadge.swift

注意：

• Hero 使用的是镂空三角
• 独立按钮使用白底 + 黑三角
• 纵向内容行里的视频提示是单独的白色三角 glyph 语义

不要把三者重新混回一种样式。

5.5 如果想改 Search

先看：

• EveryDayJapanese/Controller/YomiyaDemo/Search/YomiyaSearchEntryView.swift
• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaSearchBar.swift
• EveryDayJapanese/Controller/YomiyaDemo/Views/YomiyaSectionHeader.swift

注意：

• Search 已经收回到 Home 的共享搜索框与标题语言
• 不要在搜索页里重新补一套私有搜索输入、私有 section title row
• 想改视觉时，优先改共享组件或 token，而不是只在 Search 本页打补丁

5.6 如果下一步要接真后端

当前最稳的替换路径不是直接改 View，而是：

1. 保留 YomiyaHomeRepository / YomiyaCollectionListRepository / YomiyaCollectionDetailRepository / YomiyaSearchRepository
2. 新增真实数据源实现
3. 先让真实数据源返回和当前 payload 相同的结构
4. 最后再替换 YomiyaDemoFixtureRepository

也就是说，先换 repository，不要先撕 ViewModel 和页面层。

---

6. 如何启动和调试

6.1 开启 demo 入口

当前入口是 FeatureToggle.yomiyaDemo。

只要这个 toggle 打开，tab bar 就会追加一个 Demo 入口。

相关文件：

• EveryDayJapanese/Controller/Debug/FeatureToggle.swift
• EveryDayJapanese/Controller/MainTabBarController.swift

6.2 直接跳进某个 demo 页面

当前支持通过 UserDefaults 写入 yomiyaDemoLaunchRoute 来直接跳到指定页面。

key 定义在：

• EveryDayJapanese/Controller/YomiyaDemo/YomiyaDemoDebugLaunchTarget.swift

支持的 route 形态：

• home
• collection-list:<directionID>
• collection-detail:<collectionID>
• content-detail:<newsID>@<sourceCollectionID>

常用例子：

UserDefaults.standard.set("home", forKey: "yomiyaDemoLaunchRoute")
UserDefaults.standard.set("collection-list:news", forKey: "yomiyaDemoLaunchRoute")
UserDefaults.standard.set("collection-detail:podcast-city-walk", forKey: "yomiyaDemoLaunchRoute")
UserDefaults.standard.set("content-detail:news-1@nhk-daily", forKey: "yomiyaDemoLaunchRoute")

进入页面后，这个 route 会被消费并自动清掉。

flowchart LR
  A[UserDefaults:yomiyaDemoLaunchRoute] --> B[YomiyaDemoDebugLaunchTarget]
  B --> C[MainTabBarController 默认选中 Demo]
  C --> D[YomiyaDemoEntryViewController]
  D --> E[YomiyaDemoCoordinator]
  E --> F[home / collection-list / collection-detail / content-detail]

这张图的作用是降低“为什么我一启动就跳进某个页面”的理解成本。

6.3 预览和本地调 UI

当前多个页面都带了 #Preview，可以直接从下列文件进入本地预览：

• EveryDayJapanese/Controller/YomiyaDemo/Home/YomiyaHomeView.swift
• EveryDayJapanese/Controller/YomiyaDemo/Search/YomiyaSearchEntryView.swift
• EveryDayJapanese/Controller/YomiyaDemo/CollectionList/YomiyaCollectionListView.swift
• EveryDayJapanese/Controller/YomiyaDemo/CollectionDetail/YomiyaCollectionDetailView.swift
• EveryDayJapanese/Controller/YomiyaDemo/ContentDetail/YomiyaContentDetailContainerViewController.swift

辅助包装在：

• EveryDayJapanese/Controller/YomiyaDemo/PreviewSupport/YomiyaPreviewFixtures.swift
• EveryDayJapanese/Controller/YomiyaDemo/PreviewSupport/YomiyaPreviewWrappers.swift

---

7. 推荐验证方式

当前这条实验链路已经有一套比较完整的定向测试，但最新节点上最重要的是先保证 workspace build 过，再决定是否补跑局部测试。

7.1 当前最新已验证的 build 命令

xcodebuild build \
  -workspace EveryDayJapanese.xcworkspace \
  -scheme EveryDayJapanese \
  -destination 'platform=iOS Simulator,id=8034BB0B-541B-4D81-B743-5C7EC0ABAEF2' \
  -disableAutomaticPackageResolution \
  -onlyUsePackageVersionsFromResolvedFile \
  -skipPackageUpdates \
  -clonedSourcePackagesDirPath ~/Library/Developer/Xcode/DerivedData/EveryDayJapanese-ggpnxfnhgrhizhfrcibpiflokbvx/SourcePackages

结果：

• 2026-04-06 这轮改动后，workspace build 已通过
• 当前最直接的 simulator review 可以直接基于这次 build 产物进行

7.2 如果只改了播放按钮 / 行 affordance / Hero 局部样式

优先跑：

xcodebuild test \
  -workspace EveryDayJapanese.xcworkspace \
  -scheme EveryDayJapanese \
  -destination 'platform=iOS Simulator,OS=18.3.1,name=iPhone 16' \
  -disableAutomaticPackageResolution \
  -onlyUsePackageVersionsFromResolvedFile \
  -skipPackageUpdates \
  -clonedSourcePackagesDirPath ~/Library/Developer/Xcode/DerivedData/EveryDayJapanese-ggpnxfnhgrhizhfrcibpiflokbvx/SourcePackages \
  -only-testing:EveryDayJapaneseTests/YomiyaRowAffordanceTests

7.3 现有测试覆盖什么

测试文件	主要验证
YomiyaRowAffordanceTests.swift	播放 glyph、行 affordance、合集/内容行语义差异
YomiyaCollectionListTests.swift	方向页选择与 view model
YomiyaCollectionDetailTests.swift	合集详情动作与 payload
YomiyaContentDetailBridgeTests.swift	内容详情容器结构；当前重点验证“不要重新长出 bridge panel”
YomiyaDemoCoordinatorTests.swift	页面跳转链路
YomiyaHomeViewModelTests.swift	首页 tab 状态
YomiyaSearchEntryViewModelTests.swift	搜索输入、历史、结果映射
YomiyaDemoRepositoryTests.swift	fixture repository 输出
YomiyaDesignTokensTests.swift	token 级约束

要注意的一点：

当前测试偏逻辑和结构，不偏视觉快照。

7.4 当前调试时的一个实际注意点

• xcodebuild 即使带了 -disableAutomaticPackageResolution，在本机缓存不完整时仍可能尝试访问 GitHub
• 如果 package fetch 卡住，不要先怀疑 Yomiya 页面代码；先检查 SourcePackages 缓存是否可复用
• 因此最稳的节奏是：先复用已有 DerivedData / SourcePackages 完成 build，再做 UI review 或局部测试

---

8. 推送这个 PR 时值得明确提出的原则性问题

这部分不是让接力人马上改，而是建议在 PR 里明确提出来，避免后面重复返工。

Q1. 这套 demo 何时从 fixture 驱动切到真实后端驱动？

当前整个 Yomiya Demo 都是 YomiyaDemoFixtureRepository 在供数。

这很好，原因是：

• 它让 IA、组件家族和阅读节奏先稳定下来
• 也让前端可以在后端对象未完全落地前先做验证

但它也带来一个明确问题：

• 下一步到底是继续把 demo 当视觉实验面
• 还是开始做真实 payload adapter

这个决策不该在实现里偷偷发生，应该在 PR 里讲清楚。

Q2. YomiyaDesignTokens 现在是 demo-local token，还是未来共享设计 token 的前身？

当前阅读密度、Hero 尺寸、字体、间距、色板都已经往 YomiyaDesignTokens.swift 收口。

这很对。

但要继续推进，就需要一个明确判断：

• 只是继续把它留在 YomiyaDemo/Theme/
• 还是未来抽成更上层的共享 token

这会直接影响后续页面复用边界。

Q3. 视觉改动是否要补视觉 QA / snapshot 能力？

这轮改动里，很多是光学级别的结论：

• Hero 图片区与按钮关系
• 区块字阶和列表密度
• 底部续逛卡片之间的呼吸感
• 播放 icon 的形与位置

逻辑测试已经能兜住结构，但还兜不住肉眼审美回退。

所以值得在 PR 里正面提出：

• 后续是否需要补 screenshot / snapshot / preview review 机制

Q4. yomiyaDemo 这个入口最终是长期保留，还是只作为过渡调试面？

当前入口已经接进 FeatureToggle 和 MainTabBarController。

这说明它不只是一次性本地文件夹，而是真正进入了 App 的 debug 可达路径。

接下来需要明确：

• 它是长期保留的实验面
• 还是在正式页面接管后移除

如果不先讲清楚，后续很容易出现“所有实验都继续堆进 demo tab”的情况。

---

9. 给接力人的最短建议

如果你是下一位接手这个分支的人，最省时间的阅读顺序是：

1. 先读 07-视觉与页面表达.md
2. 再读这份 08-前端实验分支交接与调试说明.md
3. 然后看 YomiyaDesignTokens.swift
4. 再看 YomiyaDemoFixtureRepository.swift
5. 最后按你要改的页面进入对应 View / ViewModel / Coordinator

一条原则记住就行：

先守住已经冻结的阅读密度和组件家族，再做局部调整，不要把这轮已经统一好的视觉关系重新打散。