每日日语 · 工程现状分析与内容系统改进计划

[!IMPORTANT] 文档状态说明（2026-03-28）

这份文档的职责是：说明 当前工程现状与目标之间的差距，帮助团队理解 Yomiya 现有系统离目标内容平台还差什么。

它不是当前执行的唯一主规格。

当前执行请优先阅读：

yomiya-phase1-execution-spec.md

yomiya-canonical-naming.md

yomiya-phase1-scope-boundary.md

yomiya-implementation-spec-core.md

yomiya-phase1-delivery-plan.md

阅读建议：

想理解“为什么现在工程上要做这些事”，看本文档

想知道“现在到底按什么规格执行”，不要只看本文档，要优先看 implementation-spec-core

本文档里出现的 Streak、会员、专题运营控制、多套后台编排能力等 gap，默认理解为终局能力差距，不自动等于 Phase 1 必做项

文档性质：现状调研 × 策略对比 × 改进路径规划 调研仓库：IntelliFuture/yomiya-service 对比依据：yomiya-content-strategy.md 创建时间：2026-03-26 最后更新：2026-03-27（整合 Codex 三轮评审意见，删除留言区，形成统一文档）作者：Captain（OpenClaw 主控 AI）

现有内容相关工程全景
内容主表及支撑表完整字段清单
API 层完整接口清单
Admin 侧可操作的内容参数清单
内容相关配置参数清单
现有内容生产流程
现状 vs 策划案：Gap 对照表
现有模型 → 目标模型映射表
首页改版 MVP：最小工程方案
完整改进路径（四个阶段）

一、现有内容相关工程全景

1.1 服务架构

yomiya-service（Go 主服务）
├── cmd/
│   ├── apiserver/      → HTTP API（客户端 + Admin）
│   ├── consumer/       → MQ 消费者（内容加工流水线）
│   ├── scheduler/      → 定时爬虫调度（内容采集）
│   └── oss-migration/  → 资产迁移工具
│
├── internal/
│   ├── crawler/        → 5 个图文爬虫（NHK/Watanoc/Hukumusume/Yahoo/Yomu）
│   ├── domain/entity/  → 核心领域模型（News/Sentence/AudioPosition 等）
│   ├── application/    → 业务逻辑（News/Featured/Channel/Scene/ContentImport）
│   ├── repository/     → DB 访问
│   └── infrastructure/ → DB/MQ/OSS/Azure/Google/飞书
│
└── services/           → 独立微服务
    ├── youtube-gateway/     → Node.js，YouTube 视频元信息 + 字幕获取
    ├── japanese-annotator/  → Python，日语假名标注（MeCab/UniDic）
    └── craw4ai/             → 规划中的 AI 驱动爬虫

1.2 现有内容采集来源

爬虫	来源站点	内容类型	典型内容	每日上限
`nhk`	NHK Web Easy	图文新闻	简单日语新闻，N3 以下	配置项控制
`hukumusume`	福娘童话	图文故事	日本民间故事/童话	配置项控制
`watanoc`	Watanoc.com	图文新闻	简单日语新闻	配置项控制
`yahoo_news_entertainment`	Yahoo! Japan 娱乐	图文新闻	娱乐资讯	配置项控制
`yomujp`	Yomu.jp	图文新闻	简单日语新闻	配置项控制

结论：5 个爬虫全部图文，零视频来源。

1.3 视频处理基础设施（已有但未运营化）

系统已具备视频内容的技术处理基础设施，但尚未具备运营批量生产能力：

已具备	未具备
YouTube 视频元信息获取（youtube-gateway 服务）	运营批量采集视频
单条视频转录任务链路（transcription_tasks）	批量审核与打标工具
Azure Speech 字幕转文字	视频合集编排能力
YouTube 字幕直接获取（youtube-gateway）	视频首页分发策略
用户手动导入单条视频（content_import 模块）	运营侧视频批量导入工具

⚠️ 准确表述：系统已具备”视频内容处理基础设施”，但尚未具备”视频内容运营生产能力”。两者差距较大，不可混淆。

二、内容主表及支撑表完整字段清单

2.1 主内容表：`news`

字段	类型	说明	枚举值/备注
`id`	UUID	主键	—
`news_id`	string	原始来源 ID	爬虫抓取时为来源站点的唯一标识
`title`	string	日语标题	—
`title_annotation`	string	标题假名标注	由 japanese-annotator 生成
`title_html`	string	标题 HTML（含注音标签）	—
`date`	string	内容日期（YYYY-MM-DD）	—
`published_at`	timestamp	发布时间	—
`level`	int	难度等级	-1=未分析, 1=N5, 2=N4, 3=N3, 4=N2, 5=N1, 99=N1+
`channel_id`	int64(FK)	所属频道	→ `channels.id`
`type`	string	内容媒体类型	`webpage` / `video` / `audio`
`source`	enum	内容来源	`news`（爬虫）/ `imports`（用户导入）
`visibility`	enum	可见性	`INVISIBLE` / `VISIBLE` / `MEMBERSHIP_VISIBLE` / `TIME_LIMIT_VISIBLE` / `ARCHIVED`
`news_web_url`	string	原文 URL	—
`movie_url`	string	视频 URL	type=video 时有效
`image_url`	string	封面图 URL（旧字段）	逐步迁移到 OSS 路径
`image_bucket_name`	string	封面图 OSS bucket	—
`image_object_name`	string	封面图 OSS 路径	—
`is_resource_migrated`	bool	OSS 迁移标记	运维字段

当前 news 表缺失的策划案关键字段：

缺失字段	说明	影响
`duration_sec`	音视频时长	无法在列表页显示时长
`update_type`	日更/周更/常青/热点	无法按更新属性筛选
`topic_tags`	主题标签（文化/动漫/科技）	无法做主题推荐
`operator_tags`	运营标签（樱花季/热点）	无法做运营专题
`share_card_url`	金句截图卡片 URL	无法支持社交传播
`series_id` / `series_ref`	所属系列引用	无法形成连续更新结构
`collection_refs`	所属合集引用关系	无法支持长期货架组织
`topic_refs`	被哪些专题引用	无法支持时效编排追踪

注：series_id / collection_refs / topic_refs 不一定都落在 news 表本身，也可以通过关联表实现；这里强调的是工程能力必须可表达这些引用关系，而不是强制单表存储。

2.2 频道/栏目表：`channels`

字段	类型	说明
`id`	int64	主键
`name`	string	唯一英文标识
`display_name`	string	显示名称
`description`	string	频道描述
`img_url`	string	频道封面图（旧字段）
`image_bucket_name`	string	OSS bucket
`image_object_name`	string	OSS 路径
`is_visible`	bool	是否在前端显示

缺失字段：sort_order（排序）、channel_type（主栏目/子频道）、update_type（日更/周更）、primary_content_type（视频/音频/图文主导）

2.2.1 频道层补充说明：栏目是唯一归属容器

对照策略文档，channels 表承载的是一级长期归属容器，而不是首页任意展示模块。因此在工程实现上需要补充两个明确边界：

channel_id 的语义必须稳定
- 它表示内容的长期归属栏目
- 不表示首页某个临时区块，也不表示专题位置
- 首页 Banner、热门推荐、本周专题等分发位，不能反向写回 channel_id
首页分发层与内容归属层应解耦
- Item 的归属通过 channel_id 固定
- 首页展示通过 Featured / Collections / Topics 等引用关系实现
- 这样才能满足“每条内容唯一归属一个栏目，同时可被多个合集/专题引用”的策略要求

换言之：channels 是归属层，不是分发层；工程上必须避免混用。

2.3 场景标签表：`scenes` + `news_scenes`

scenes：

字段	说明
`category`	大类（如”旅行”）
`scene`	场景（如”机场”）
`sub_scene`	子场景（如”问路”）
`available`	是否可用

news_scenes（关联表）：

字段	说明
`news_id`	→ news.id
`scene_id`	→ scenes.id
`scene_primary`	`primary` / `secondary`（主/次场景）

✅ 场景标签体系已有，可直接沿用扩展。

2.4 内容句子层：`news_sentences`

字段	说明
`id`	UUID
`news_id`	→ news.id
`paragraph_index`	段落序号
`index_in_paragraph`	段内句子序号
`text`	日语原文
`annotation`	假名标注
`html`	HTML 格式
`type`	`TITLE` / `BODY`

2.5 句子翻译层：`news_sentence_translations`

字段	说明
`sentence_id`	→ news_sentences.id
`language`	语言代码（en/zh/…）
`text`	翻译文本

2.6 音频对齐层：`audio_sentence_offsets` + `audio_word_offsets`

字段	说明
`article_id`	→ news.id
`sentence_id`	→ news_sentences.id
`voice_name`	声音名（ja-JP-NanamiNeural / ja-JP-KeitaNeural）
`audio_oss_file_id`	→ audio_oss_files.id
`offset`	音频偏移（ms）
`duration_ms`	时长（ms）

2.7 分词层：`news_sentence_tokens`

字段	说明
`news_sentence_id`	→ news_sentences.id
`text`	词语文本
`lemma`	原形
`begin_offset`	词语在句子中的起始偏移
`length`	词语长度
`part_of_speech`	词性（int）

2.8 视频转录任务表：`transcription_tasks`

字段	说明
`url`	视频/音频 URL
`channel_id`	所属频道
`content_type`	video / audio
`pluto_user_id`	发起用户
`status`	queued / processing / completed / failed
`transcript_type`	转录类型（word_level / segment_level）
`news_id`	生成的 news 记录 ID
`estimated_duration_seconds`	预估时长（秒）

2.9 用户内容导入表：`user_content_imports`

字段	说明
`pluto_user_id`	导入用户
`channel_id`	所属频道
`content_type`	video / audio
`url`	原始 URL
`title`	内容标题
`thumbnail_url`	缩略图 URL
`duration`	时长（秒）
`availability`	可用性
`transcription_task_id`	→ transcription_tasks.id
`news_id`	→ news.id（转录完成后生成）

2.10 原始采集暂存表：`raw_news`

字段	说明
`unique_id`	去重 ID
`status`	QUEUED / PROCESSING / DONE / REJECTED / FAILED
`data`	JSON（RawNewsData 结构，含 type/level/transcript 等）
`risk_check_status`	HIGH / MEDIUM / LOW / BLOCKED
`channel`	来源频道名

三、API 层完整接口清单

3.1 客户端 API（v1）

方法	路径	功能
GET	`/v1/featured`	首页精选内容（当前核心分发接口）
GET	`/v1/news`	新闻列表（分页）
GET	`/v1/news/:id`	新闻详情
GET	`/v1/news/:id/translations`	句子翻译
GET	`/v1/news/:id/audios`	音频列表
GET	`/v1/news/:id/audios/:voiceName`	指定声音的音频
GET	`/v1/channels`	频道列表
GET	`/v1/scenes`	可用场景列表
GET	`/v1/categories`	分类列表
GET	`/v1/dictionary`	词典查询
POST	`/v1/news/:id/explain`	AI 解析文章
POST	`/v1/news/sentences/:id/explain`	AI 解析句子

3.2 客户端 API（v2）

方法	路径	功能
GET	`/v2/news`	新闻列表（v2版，返回字段有差异）
GET	`/v2/news/:id`	新闻详情（v2）
POST	`/v2/news/:id/explain`	AI 解析（v2，含配额控制）
GET	`/v2/explain/quota`	解析配额查询

3.3 用户内容导入 API

方法	路径	功能
PUT	`/v1/content/imports`	导入内容（YouTube URL 等）
GET	`/v1/content/imports`	获取用户导入列表
GET	`/v1/content/imports/:id`	导入详情
DELETE	`/v1/content/imports/:id`	删除导入
PUT	`/v1/content/transcriptions`	请求转录
GET	`/v1/content/transcriptions/:taskId`	转录状态查询
POST	`/v1/content/transcriptions/:taskId`	转录操作（取消等）

3.4 Admin API

方法	路径	功能
GET	`/admin/v1/news`	内容列表（支持按 category/visibility/level/date/search 筛选）
PUT	`/admin/v1/news/batch`	批量更新内容
GET	`/admin/v1/news/:id`	内容详情
PUT	`/admin/v1/news/:id`	更新内容（level/category/visibility/scenes）
DELETE	`/admin/v1/news/:id`	删除内容
POST	`/admin/v1/news/:id/analyze-difficulty`	AI 难度分析
POST	`/admin/v1/news/:id/scenes/gen`	AI 场景标签生成
POST	`/admin/v1/news/:id/upload-image`	上传封面图
GET	`/admin/v1/channels`	频道管理
POST	`/admin/v1/channels`	创建频道
PUT	`/admin/v1/channels/:id`	更新频道
PATCH	`/admin/v1/channels/:id/toggle-visibility`	切换频道可见性
GET	`/admin/v1/scenes`	场景管理
POST	`/admin/v1/scenes`	创建场景
PUT	`/admin/v1/scenes/:id`	更新场景

四、Admin 侧可操作的内容参数清单

目前后台可以手动操作的内容参数（通过 Admin API）：

参数	操作方式	自动化程度
`level`（难度等级）	手动设置 / AI 自动分析	半自动（AI 初判 + 人工确认）
`visibility`（可见性）	手动设置	纯手动
`category`（分类/频道）	手动设置	纯手动
`primary_scenes`（主场景标签）	手动设置 / AI 自动生成	半自动
`secondary_scenes`（次场景标签）	手动设置 / AI 自动生成	半自动
`image`（封面图）	手动上传	纯手动
句子翻译	批量触发翻译队列	半自动（触发后自动完成）

当前后台不能操作的字段：

主题标签（不存在）
运营标签（不存在）
合集/系列归属（不存在）
内容时长（news 表没有此字段）
标题 A/B 版本（不存在）

4.1 Admin 层缺失的“容器准入”能力

对照策略文档，后台当前最大缺口之一，不只是“没有合集/系列/专题功能”，而是没有一套显式的容器准入与引用管理能力。这会导致运营虽然能修改内容字段，但无法稳定回答两个关键问题：

这条内容长期归属哪个栏目？
这条内容还应该被组织进哪些合集 / 系列 / 专题？

建议后台未来补充的能力包括：

查看某条内容当前的栏目归属、主题标签、场景标签、难度标签
查看该内容当前被哪些合集引用、被哪个系列收录、被哪些专题使用
在后台中直接执行“加入合集 / 移出合集 / 设为系列内容 / 加入专题”
对运营可见地展示“该内容承担的主要职责”（DAU / 留存 / 转化 / 传播，可先作为运营字段而非算法字段）

补上这层能力后，运营讨论才会真正从“改字段”升级为“做内容编排”。

五、内容相关配置参数清单

配置模块	关键参数	说明
featured	`channels`（JSON 数组）	首页展示哪些频道及每个频道的条数，决定首页内容分发
crawler.nhk	`per_fetch_limit` / `daily_limit`	NHK 每次抓取数 / 每日上限
crawler.hukumusume	`per_fetch_limit` / `daily_limit`	同上
crawler.yahoo_news_entertainment	`per_fetch_limit` / `daily_limit`	同上
crawler.watanoc	`per_fetch_limit` / `daily_limit`	同上
crawler.yomujp	`per_fetch_limit` / `daily_limit`	同上
crawler	`llm_provider` / `llm_model`	内容清洗用的 LLM
content_import	`max_video_duration`（默认 3600s）	视频导入最大时长限制
youtube_gateway	`base_url` / `token`	youtube-gateway 微服务地址
speech_synthesis	`voice_names`（NanamiNeural/KeitaNeural）	TTS 合成使用的声音
news_resource_oss	`bucket_name` / `object_path`	新闻封面图 OSS 存储位置
speech_synthesis_oss	`bucket_name` / `object_path`	TTS 音频 OSS 存储位置
consumer	`translation_whitelist` / `max_concurrency`	翻译目标语言 / 并发数

🔑 关键发现：首页分发完全由 featured.channels 配置驱动，是纯配置层控制。改变首页哪些频道出现、出现多少条，只需修改配置文件，不需要代码改动。

六、现有内容生产流程

① 定时调度（scheduler）
   NHK / Hukumusume / Watanoc / Yahoo / Yomu
   → 写入 raw_news（status=QUEUED）
   → 发送 RabbitMQ 消息

② MQ 消费者（consumer）
   → 风险检查（risk_check_status）
   → AI 内容清洗（LLM 处理标题/正文）
   → 写入 news 表（visibility=INVISIBLE）
   → 触发后续队列：翻译 / 假名标注 / TTS

③ 并行加工（consumer 并发处理）
   → 逐句翻译（Youdao / DeepL / DeepSeek）
   → 假名标注（japanese-annotator Python 服务）
   → AI 难度分析（level 自动打分）
   → Azure TTS 语音合成（男声 + 女声）
   → Google NLP 分句分词（音频文本对齐）

④ 人工审核与发布（Admin 后台）
   → 确认难度等级
   → 更新场景标签
   → 设置可见性（INVISIBLE → VISIBLE）
   → 上传/确认封面图

⑤ 分发到客户端
   → GET /featured 返回 Channel + News 列表
   → 客户端按配置的频道展示内容

视频内容的独立路径（当前）：

用户/运营 提交 YouTube URL
→ youtube-gateway 获取视频元信息 + 字幕
→ 创建 transcription_task
→ Azure Speech 转录（或使用 YouTube 字幕）
→ 写入 news 表（source=imports）
→ 同上 ③④⑤ 流程

七、现状 vs 策划案：Gap 对照表

策划案能力	现状	Gap 程度	处理方式
视频内容采集（NHK World YouTube）	无视频爬虫	🔴 关键缺口	新增视频爬虫，复用现有转录链路
动漫/日剧视频片段	无	🔴 关键缺口	新增采集器
热门推荐展示视频合集（≥60%）	首页只有单条 news 列表	🔴 架构改动	新增合集数据模型 + 改首页 API
合集/专题层（Collections）	完全缺失	🔴 需新增	新增 `collections` + `collection_items`
主题标签（文化/动漫/科技）	完全缺失	🔴 需新增	新增 `topic_tags` + `news_topic_tags`
Streak 打卡与内容消费绑定	无留存机制	🔴 需新增	新增 `user_content_views` + `user_streaks`
运营标签（樱花季/热点）	完全缺失	🔴 需新增	新增字段或独立表
NHK Web Easy 图文新闻	✅ nhk 爬虫已有	—	直接沿用
难度等级（N5-N1）	✅ news.level 已有	—	直接沿用
场景标签	✅ scenes + news_scenes 已有	—	直接沿用，补主题标签
内容类型（视频/音频/图文）	✅ news.type 字段已有	🟡 需暴露	前端显示 type 差异化 UI
内容频道/栏目	✅ channels 表已有	🟡 补字段	加 sort_order/channel_type 等字段
音频 TTS	✅ Azure TTS 已有	—	直接沿用
翻译（中文）	✅ 多引擎翻译已有	—	直接沿用
假名标注	✅ japanese-annotator 已有	—	直接沿用
视频内容时长	部分（user_content_imports.duration）	🟡 补字段	同步到 news 表
AI 难度自动分析	✅ 已有	—	直接沿用
AI 场景标签生成	✅ Admin 接口已有	—	直接沿用
内容 A/B 标题测试	无	🟡 非优先	阶段三以后考虑
金句截图卡片	无	🟡 非优先	可先做手动生产，后自动化

八、现有模型 → 目标模型映射表

目标能力	现有基础	处理方式	工程量
主栏目（≤7个频道）	`channels` 表	复用 + 加字段（sort_order/channel_type/update_type）	极小（DDL）
场景标签	`scenes` + `news_scenes`	直接沿用	零
难度等级	`news.level`（-1/1-5/99）	直接沿用	零
内容类型	`news.type`（webpage/video/audio）	沿用 + API 暴露	极小
视频时长	`user_content_imports.duration`	新增 `news.duration_sec` 字段	极小（DDL+同步）
主题标签	无	新增 `topic_tags` + `news_topic_tags`	小（DDL + 运营录入）
运营标签	无	新增 `news.operator_tags`（JSON 字段）或独立表	小
合集/系列	无	新增 `collections` + `collection_items`	中（新表 + API + Admin）
首页合集卡片分发	FeaturedApplication 返回单条 news	新增 `GetFeaturedCollections()` API	中
内容消费记录	无	新增 `user_content_views` 表	中（需 iOS 联动）
Streak 打卡连胜	无	新增 `user_streaks` 表 + 打卡逻辑	中（需 iOS 联动）
视频批量采集	单条用户导入链路已通	新增 YouTube 批量爬虫	小（复用现有链路）

九、首页改版 MVP：最小工程方案

目标：最少改哪些地方，就能让首页从”单条 news 分发”升级为”合集卡片 + 视频主导”？

Step 1：新增 `collections` 表（约 3 天）

CREATE TABLE collections (
  id VARCHAR(64) PRIMARY KEY,
  created_at DATETIME,
  updated_at DATETIME,
  deleted_at DATETIME,
  title VARCHAR(256) NOT NULL,    -- 用"场景/问题"表述
  description TEXT,
  cover_image_url VARCHAR(512),
  channel_id INT NOT NULL,         -- 所属主栏目
  collection_type VARCHAR(32),     -- series（连载）/ topic（专题）
  content_type VARCHAR(32),        -- video / audio / mixed
  sort_order INT DEFAULT 0,
  is_featured BOOL DEFAULT FALSE,  -- 是否出现在首页热门推荐
  visibility VARCHAR(32) DEFAULT 'VISIBLE'
);

CREATE TABLE collection_items (
  id INT AUTO_INCREMENT PRIMARY KEY,
  collection_id VARCHAR(64) NOT NULL,
  news_id VARCHAR(64) NOT NULL,
  sort_order INT DEFAULT 0,
  UNIQUE KEY uk_collection_news (collection_id, news_id),
  INDEX idx_collection_id (collection_id)
);

Step 2：新增 Admin 操作接口（约 2 天）

POST   /admin/v1/collections          → 创建合集
GET    /admin/v1/collections          → 合集列表
PUT    /admin/v1/collections/:id      → 编辑合集（标题/封面/sort_order/is_featured）
POST   /admin/v1/collections/:id/items → 向合集添加 news
DELETE /admin/v1/collections/:id/items/:newsId → 从合集移除 news

Step 3：新增首页合集 API（约 1 天）

GET /v1/featured/collections

返回结构：

{
  "collections": [
    {
      "id": "xxx",
      "title": "用《鬼灭之刃》学日语",
      "cover_image_url": "...",
      "content_type": "video",
      "collection_type": "series",
      "item_count": 12,
      "channel": { "id": 5, "name": "anime", "display_name": "动漫日剧" }
    }
  ]
}

Step 4：补充 NHK World 视频爬虫（约 3 天）

复用 youtube_importer.go 现有代码，新增 nhk_world_crawler.go：

从配置的 NHK World YouTube 频道/播放列表批量拉取视频 URL
调用现有 youtube-gateway 获取元信息 + 字幕
进入 raw_news 队列，走现有 consumer 处理链路

Step 5：暴露 news.type 到前端（约 0.5 天）

确认 /v1/featured 和 /v1/news 返回的数据中包含 type 字段，让前端可以区分视频/音频/图文并展示不同 UI。

MVP 完成标准：

运营可以在 Admin 后台创建合集、添加内容、设置封面
首页 API 返回合集列表（≥ 8 个，其中 ≥ 5 个视频合集）
前端可以区分视频/音频/图文展示不同卡片样式

总工程量估算：约 2 周（1 后端开发 × 2 周）

十、完整改进路径（四个阶段）

阶段 0：配置层快速调整（本周，0 工程量）

不需要写代码，只改配置：

调整 featured.channels 配置，确认首页频道顺序和条数符合策划案
确认各爬虫的 daily_limit 满足每日内容更新需求
验证 news.type 字段在现有 API 响应中正确返回

阶段 1：最小改动，最大收益（1–2 周）

DDL 扩展（无需改业务代码）：

-- channels 表加字段
ALTER TABLE channels
  ADD COLUMN sort_order INT DEFAULT 0,
  ADD COLUMN channel_type VARCHAR(32) DEFAULT 'main',
  ADD COLUMN update_type VARCHAR(32) DEFAULT 'regular',
  ADD COLUMN primary_content_type VARCHAR(32) DEFAULT 'mixed';

-- news 表加字段
ALTER TABLE news
  ADD COLUMN duration_sec INT COMMENT '音视频时长（秒）',
  ADD COLUMN update_type VARCHAR(32) COMMENT 'daily/weekly/evergreen/trending',
  ADD COLUMN operator_tags JSON COMMENT '运营标签数组（如["樱花季","热点"]）';

首页改版 MVP（参见第九章，约 2 周）：

collections + collection_items 表
Admin 合集管理接口
首页合集 API
NHK World 视频爬虫

阶段 2：主题标签 + 内容扩充（3–4 周）

CREATE TABLE topic_tags (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(64) NOT NULL UNIQUE,
  name_zh VARCHAR(64),
  name_ja VARCHAR(64),
  is_visible BOOL DEFAULT TRUE
);

CREATE TABLE news_topic_tags (
  id INT AUTO_INCREMENT PRIMARY KEY,
  news_id VARCHAR(64) NOT NULL,
  topic_tag_id INT NOT NULL,
  UNIQUE KEY uk_news_topic (news_id, topic_tag_id),
  INDEX idx_news_id (news_id)
);

主题标签表 + Admin 打标接口
动漫/日剧视频采集器
JLPT 专区 Channel 配置
前端支持按 type 筛选内容

阶段 3：留存机制（4–8 周，需 iOS 联动）

CREATE TABLE user_content_views (
  id INT AUTO_INCREMENT PRIMARY KEY,
  created_at DATETIME,
  user_id BIGINT NOT NULL,
  news_id VARCHAR(64) NOT NULL,
  progress_pct TINYINT DEFAULT 0,
  is_completed BOOL DEFAULT FALSE,
  INDEX idx_user_date (user_id, created_at)
);

CREATE TABLE user_streaks (
  id INT AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT NOT NULL UNIQUE,
  current_streak INT DEFAULT 0,
  longest_streak INT DEFAULT 0,
  last_checkin_date DATE,
  streak_freeze_count INT DEFAULT 0,
  updated_at DATETIME
);

内容消费进度上报 API（iOS 端调用）
打卡触发逻辑（消费完成 → 当日打卡）
Streak 维护逻辑 + 召回通知

阶段 4：精细化（阶段 3 完成后）

A/B 标题测试能力
金句截图自动生成
AI 个性化推荐（基于消费历史）
内容效果数据看板

附录：现有枚举值速查

`news.level`

值	含义
-1	未分析
1	N5（初级）
2	N4
3	N3（中级）
4	N2
5	N1（高级）
99	N1+（超高级）

`news.visibility`

值	含义
INVISIBLE	不可见（待审核）
VISIBLE	免费可见
MEMBERSHIP_VISIBLE	会员可见
TIME_LIMIT_VISIBLE	限时可见
ARCHIVED	归档

`news.source`

值	含义
news	爬虫抓取
imports	用户/运营手动导入

`news.type`

值	含义
webpage	图文网页（默认）
video	视频
audio	音频

文档版本：v2.0（基于 Codex 评审意见全面修订） 参与：cc（产品）× Captain（OpenClaw 主控 AI）× Codex（AI 深度评审） 创建：2026-03-26 | 最后更新：2026-03-26

十三、改版边界定义（MVP 执行约束）

本章整合 Codex 审阅意见，明确边界，防止项目执行发散。

13.1 内容容器边界

本轮改版继续以 news 为统一内容容器，不在本阶段引入全新主表。

news 表已支持 type = video / audio / webpage，字段体系基本满足 Phase 1 需求。中长期是否演进为更抽象的 content_item 模型，待首页 MVP 跑通后再评估。

禁止在本阶段引入全新内容主表（防止大重构）。

13.2 首页 MVP 不做项

首页 MVP 明确排除以下能力，不得在本阶段加入：

排除项	说明
推荐算法	首页合集先手工精选，无个性化分发
订阅/追更体系	合集先做展示，不做 follow
标题 A/B 测试	放到阶段 4
完整个性化分发	先按运营编排
全新内容主表	继续复用 news 表

13.3 视频比例是运营目标，不是系统约束

“首页 ≥8 个合集，其中 ≥5 个视频合集” = 运营编排目标，不是后端硬校验规则。

后台不需要卡比例，接口不需要强制校验视频数量。这个目标由运营编排和后台配置保证。

13.4 文档定位说明

本文档是工程差距分析与改造路径文档，不是最终产品形态定义文档。

正确使用方法：

先以 yomiya-content-strategy.md（主策划文档）统一产品目标
再以本文档解释：现状、缺口、阶段化改造路径

本文档不应作为产品最终边界的依据。现有工程有什么，不代表产品最终只能做什么。

十四、内容智能处理引擎 API 设计边界

本章整合 Codex 对第十二章的审阅意见，修正 API 定义和工时估算。

14.1 `POST /admin/v1/content/analyze` 分两层设计

此接口不应设计为”大而全一次稳定返回”，而是分两层：

第一层：稳定返回（优先保证成功率）

来源类型
标题
时长
发布者/频道
缩略图
字幕可用性
转录/字幕处理策略

第二层：AI 建议（允许为空或置信度不足）

建议栏目
场景标签候选
主题标签候选
难度建议
合集建议
风险提示

这两层必须解耦。第一层失败不影响第二层输出；第二层为空时，人工补全即可，不应阻断流程。

14.2 P0 阶段的准确定义

P0 = 飞书对话式分析辅助可立即开始，不等于飞书对话式自动入库已可立即支持。

P0 成立的是：

通过 Captain 在飞书对话中提供分析辅助
通过 prompts 表扩展分析能力

P0 不成立的是：

结构化确认后稳定写入内容主库
通过飞书完成完整入库闭环

两者是分析辅助能力和自动入库能力的区别，不应混淆。

14.3 版权风险评估的边界

AI 可以给出风险提示（官方频道/公开视频/第三方转载迹象），但：

不能把 copyright_risk = low 视为自动安全。工程和运营侧必须保留人工确认兜底。

14.4 工时估算基准（上调一档）

以下任务工时需在原估算基础上预留缓冲：

POST /admin/v1/content/analyze：结构化输出调试时间 + 第三方来源不稳定兼容时间
POST /admin/v1/content/commit：AI 输出解析失败补救 + 联调时间
Apple Podcast RSS 解析：各频道格式差异兼容
Admin 后台链接分析 UI：异常状态展示 + 人工兜底界面

建议所有工时估算默认乘以 1.5 倍作为计划值。

十五、首页改版 MVP 任务拆解表

模块	任务	负责人	工作量	前置依赖	说明
后端	新增 `collections` 表	Backend	0.5d	无	含 migration
后端	新增 `collection_items` 表	Backend	0.5d	无	含索引
后端	Admin 合集 CRUD API	Backend	1d	collections 表	管理合集标题/封面/排序
后端	Admin 合集内容绑定 API	Backend	0.5d	collection_items 表	添加/移除 news
后端	`/v1/featured/collections` 接口	Backend	0.5d	collections + items	首页合集列表
后端	`news.type` 字段确认返回	Backend	0.5d	无	供前端识别样式
后端	NHK World 批量视频采集器	Backend	2–3d	youtube-gateway	复用现有导入链路
Admin	合集管理页	Admin FE/BE	1–2d	CRUD API	可创建、编辑、排序、设封面
iOS	首页合集区 UI	iOS	1–2d	featured collections API	新增合集卡片区
iOS	卡片按 `content_type` 区分样式	iOS	0.5–1d	type 字段返回	视频/音频/图文样式差异
运营	准备首批 8 个合集	Content Ops	2–3d	Admin 可用	至少 5 个视频合集
运营	为合集制作封面与标题	Content Ops	1–2d	合集结构确定	保证首页展示质量

文档性质：工程现状分析与改造路径文档 参与：cc（产品负责人）× Captain（OpenClaw 主控 AI）× Codex（AI 深度评审） 创建时间：2026-03-26 | 最后更新：2026-03-27 注意：本文档是工程辅助文档，产品最终形态定义以 yomiya-content-strategy.md 为准

每日日语 · 工程现状分析与内容系统改进计划

每日日语 · 工程现状分析与内容系统改进计划

目录

一、现有内容相关工程全景

1.1 服务架构

1.2 现有内容采集来源

1.3 视频处理基础设施（已有但未运营化）

二、内容主表及支撑表完整字段清单

2.1 主内容表：news

2.2 频道/栏目表：channels

2.2.1 频道层补充说明：栏目是唯一归属容器

2.3 场景标签表：scenes + news_scenes

2.4 内容句子层：news_sentences

2.5 句子翻译层：news_sentence_translations

2.6 音频对齐层：audio_sentence_offsets + audio_word_offsets

2.7 分词层：news_sentence_tokens

2.8 视频转录任务表：transcription_tasks

2.9 用户内容导入表：user_content_imports

2.10 原始采集暂存表：raw_news

三、API 层完整接口清单

3.1 客户端 API（v1）

3.2 客户端 API（v2）

3.3 用户内容导入 API

3.4 Admin API

四、Admin 侧可操作的内容参数清单

4.1 Admin 层缺失的“容器准入”能力

五、内容相关配置参数清单

六、现有内容生产流程

七、现状 vs 策划案：Gap 对照表

八、现有模型 → 目标模型映射表

九、首页改版 MVP：最小工程方案

Step 1：新增 collections 表（约 3 天）

Step 2：新增 Admin 操作接口（约 2 天）

Step 3：新增首页合集 API（约 1 天）

Step 4：补充 NHK World 视频爬虫（约 3 天）

Step 5：暴露 news.type 到前端（约 0.5 天）

十、完整改进路径（四个阶段）

阶段 0：配置层快速调整（本周，0 工程量）

阶段 1：最小改动，最大收益（1–2 周）

阶段 2：主题标签 + 内容扩充（3–4 周）

阶段 3：留存机制（4–8 周，需 iOS 联动）

阶段 4：精细化（阶段 3 完成后）

附录：现有枚举值速查

news.level

news.visibility

news.source

news.type

十三、改版边界定义（MVP 执行约束）

13.1 内容容器边界

13.2 首页 MVP 不做项

13.3 视频比例是运营目标，不是系统约束

13.4 文档定位说明

十四、内容智能处理引擎 API 设计边界

14.1 POST /admin/v1/content/analyze 分两层设计

14.2 P0 阶段的准确定义

14.3 版权风险评估的边界

14.4 工时估算基准（上调一档）

十五、首页改版 MVP 任务拆解表

2.1 主内容表：`news`

2.2 频道/栏目表：`channels`

2.3 场景标签表：`scenes` + `news_scenes`

2.4 内容句子层：`news_sentences`

2.5 句子翻译层：`news_sentence_translations`

2.6 音频对齐层：`audio_sentence_offsets` + `audio_word_offsets`

2.7 分词层：`news_sentence_tokens`

2.8 视频转录任务表：`transcription_tasks`

2.9 用户内容导入表：`user_content_imports`

2.10 原始采集暂存表：`raw_news`

Step 1：新增 `collections` 表（约 3 天）

`news.level`

`news.visibility`

`news.source`

`news.type`

14.1 `POST /admin/v1/content/analyze` 分两层设计