Initial commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
谢宇宁
2026-09-29 11:47:47 +07:00
co-authored by Claude Opus 5.5
commit 0fbdba5ccf
622 changed files with 72105 additions and 0 deletions
@@ -0,0 +1,98 @@
# 黄果短剧页面 TDK 来源分析
## 分析范围与口径
- 分析对象:当前本地 Go 项目的页面路由、SSR handler、公共渲染层和页面模板。
- 未提供线上域名,因此结论代表代码的运行逻辑,不代表某一线上环境当前接口里一定配置了 TDK。
- “动态获取”指 TDK 至少可从上游接口返回的 `seoInfo`、公共配置、导航 SEO 或内容字段生成。
- “写死”指模板内直接写固定文本,或 handler 传入固定常量;列表数据虽然动态,但未用于 TDK 的页面仍算写死。
- “混合”指部分字段动态、部分字段写死,或接口失败后回退到模板常量。
## 总体结论
项目不是简单的“动态 / 写死”两类,而是四种实现:
1. **后台 TDK 动态优先,模板常量兜底**:首页、标签、排行榜、今日更新、分类详情、专题详情等。
2. **依赖公共导航 SEO,页面业务接口本身不返回 TDK**:短剧列表、AI 剧集、福利应用、回家的路。
3. **根据内容或路由参数动态拼装**:短剧详情、播放、搜索、富文本。
4. **模板固定写死**:账户相关页、反馈页、下载页默认配置、404 的 D/K 等。
公共渲染层会读取 `/api/app/translation/category/list` 的导航项 `seoInfo`,按当前路径或 `navActive` 覆盖页面原有 `seoInfo`;字段级优先级是“导航 SEO > 页面 SEO > 模板兜底”。证据见 `app/api/web/render.go:25-54`、`app/service/translationser/list.go:13-55` 和 `app/service/translationser/view.go:154-185`。
## 一、完整 TDK 可动态获取的页面
这些页面的 T、D、K 都存在动态来源;动态字段为空或接口失败时,模板会回退到固定文案。
| 页面 / 路由 | T 来源 | D 来源 | K 来源 | 主要接口与说明 |
|---|---|---|---|---|
| 首页 `/` | 首页 `seoInfo.title`,导航 SEO 可覆盖;再回退公共配置和固定标题 | 首页 `seoInfo.description`,导航 SEO可覆盖;再回退公共配置/固定文案 | 首页 `seoInfo.keywords`,导航 SEO 可覆盖;再回退公共配置/固定词 | `/api/app/playlet/home`;`/api/app/config/info`;`/api/app/translation/category/list`。见 `app/api/web/index.go:20-38`、`app/templates/page/index.html:7-9` |
| 登录 `/login/`、注册 `/register/` | 与首页相同 | 与首页相同 | 与首页相同 | 两者复用 `index.html` 和首页接口,并没有登录/注册专属 TDK。handler 虽设置内部 `noindex` 标志,但模板的 robots 仍固定输出 `index,follow`。见 `app/api/web/index.go:15-38`、`app/templates/page/index.html:10` |
| 标签列表/详情 `/tag/...` | 标签接口 SEO 标题或标签名 + 分页 | 标签接口 SEO 描述;否则用标签名拼装 | 标签接口 SEO 关键词;否则标签名 + 固定词 | `/api/app/playlet/tag/list`;导航 SEO 仍可覆盖。见 `app/api/web/tag_list.go`、`app/templates/page/tagList.html:7-9` |
| 排行榜 `/rank/...` | 排行榜接口 SEO + 榜单筛选值 | 排行榜接口 SEO + 榜单筛选值 | 排行榜接口 SEO + 榜单筛选值 | `/api/app/playlet/rank`;导航 SEO 优先。见 `app/api/web/rank.go`、`app/templates/page/rank.html:7-9` |
| 今日更新 `/today-update/...` | 接口 SEO 或固定标题 | 接口 SEO 或固定文案 | 接口 SEO 或固定词 | `/api/app/playlet/today-update`;导航 SEO 优先。见 `app/api/web/today_update.go`、`app/templates/page/todayUpdate.html:7-9` |
| 分类详情 `/category/:slug/...` | 分类接口 SEO;否则分类名 + 分页 | 分类接口 SEO;否则 handler 固定分类介绍 | 分类接口 SEO;否则分类名 + 固定词 | `/api/app/playlet/recommend/list`;导航 SEO 可覆盖。见 `app/api/web/category_detail.go`、`app/templates/page/categoryDetail.html:7-9` |
| 专题详情 `/topic/:slug/...` | 专题列表接口 SEO;否则专题名称 | 专题列表接口 SEO;否则固定专题介绍 | 专题列表接口 SEO;否则专题名 + 固定词 | `/api/app/playlet/list` 提供 `seoInfo`,`/api/app/theme/list` 提供专题名;导航 SEO 可覆盖。见 `app/api/web/more.go`、`app/templates/page/more.html:7-18` |
| 官方导航 `/nav/`;导航独立服务的 `/`、`/nav/`、`/dh/` | `seoNavInfo.dhTitle` / `dhSiteName` | `seoNavInfo.dhDescription` | `seoNavInfo.dhKeyworld` | `/api/app/config/info`;失败时固定文案。见 `app/templates/page/nav.html:7-9`、`app/service/configser/types.go:118-124` |
## 二、条件动态:只依赖导航 SEO 的页面
这些页面不是从自身内容接口取得 TDK,而是依靠公共导航接口中与当前路由匹配的 `seoInfo`。如果后台导航没有配置 SEO,最终就是模板固定文案。
| 页面 / 路由 | 实际情况 | 动态来源 | 固定兜底 |
|---|---|---|---|
| 短剧列表 `/list/...` | 三个字段都支持动态;筛选项还会追加到 T/D/K | `/api/app/translation/category/list` 的导航 SEO | `短剧` 标题及模板内固定描述、关键词。业务接口 `/api/app/playlet/operate/list` 的响应结构没有 `seoInfo`,handler 也显式传入空 `SeoInfo`。见 `app/api/web/list.go:34-53`、`app/service/playletser/types.go:168-176` |
| AI 成人剧集 `/series/...` | 三个字段都支持动态;筛选项会追加到 T/D/K | 导航 SEO | 业务接口同样没有页面级 `seoInfo`,handler 没有传 `seoInfo`。见 `app/api/web/series.go:20-39`、`app/templates/page/series.html:7-9` |
| 福利应用 `/application/` | 三个字段都支持动态,但应用列表接口不参与 TDK | 导航 SEO | `福利应用` + 模板固定 D/K。见 `app/api/web/application.go`、`app/templates/page/application.html:7-14` |
| 回家的路 `/home-road/` | 三个字段都支持动态,但 `config/info.seoInfo` 并未传给模板的 `.seoInfo` | 导航 SEO | handler 固定标题,模板固定 D/K。见 `app/api/web/home_road.go`、`app/templates/page/homeRoad.html:7-9` |
| 下载 APP `/download-app/` | 模板具备 `.seoInfo` 动态入口,但 handler 不传;默认导航项被标记为下载项,会被导航 SEO 匹配逻辑跳过 | 仅当后台把它配置成可匹配的普通站内导航 URL 时才可能动态 | 通常落到模板固定的下载 APP TDK。见 `app/router/gin.go:202-207`、`app/templates/page/downloadApp.html:7-12`、`app/service/translationser/view.go:159-166` |
## 三、内容字段或路由规则动态拼装的页面
这些页面会变化,但不一定使用后台专门配置的完整 TDK。
| 页面 / 路由 | T | D | K | 判定 |
|---|---|---|---|---|
| 短剧详情 `/detail/:slug/` | 优先 `detail.SeoInfo.Title`,否则短剧名;站点名也可由接口 SEO/公共配置动态取得 | **不读取 `detail.SeoInfo.Description`**;只要 `detail` 存在,就使用短剧 `Desc`,为空则按短剧名拼固定句式 | **不读取 `detail.SeoInfo.Keywords`**;由短剧名、题材名、标签名和固定词拼装 | 内容动态拼装,不是完整后台 TDK。见 `app/api/web/detail.go:17-30`、`app/templates/page/detail.html:7-11` |
| 播放 `/play/:slug/:chapterId?/` | 优先章节 SEO 标题,其次短剧 SEO 标题/短剧名,并拼集数 | **不读取已经合并好的 `.seoInfo.Description`**;只要 `playlet` 存在,就使用短剧 `Desc` 或固定播放句式 | **不读取已经合并好的 `.seoInfo.Keywords`**;由短剧名、题材、标签和固定词拼装 | 标题动态取 SEO,D/K 是内容字段拼装。见 `app/api/web/play.go:37-60`、`app/service/playletser/seo.go:252-277`、`app/templates/page/play.html:7-17` |
| 搜索 `/search/:keyword/...` | 搜索词拼装 | 搜索词拼装固定句式 | 搜索词 + 固定词 | 路由参数动态,不读搜索接口的 SEO;页面为 `noindex,follow`。见 `app/api/web/search.go`、`app/templates/page/search.html:7-19` |
| 通用富文本 `/richtext/:title/` | 上游富文本 `desc/title` | 用动态标题套固定句式 | 动态标题 + 固定词 | `/api/app/config/richtext/list` 只映射 `id/title/desc/content`,没有映射 `seoInfo`,所以不是后台独立 TDK。见 `app/service/configser/types.go:133-145`、`app/service/configser/richtext.go:48-82`、`app/templates/page/richtext.html:7-18` |
| 专题列表 `/topic/`、分页 | handler 固定基础标题并按页码追加;公共导航 SEO 命中时也可覆盖标题 | 固定 | 固定 | T 动态/规则生成,D/K 写死。见 `app/api/web/theme_index.go`、`app/templates/page/themeIndex.html:7-9` |
| 404 / 未找到页面 | handler 的错误标题可变化 | 固定 | 固定 | 只有 T 动态,D/K 写死;`noindex,follow`。见 `app/api/web/notfound.go`、`app/templates/page/404.html:7-13` |
## 四、路由层“动态富文本优先、静态模板兜底”的页面
以下四个固定路由会先请求 `/api/app/config/richtext/list`:有内容时使用 `richtext.html`,按上一节的规则动态拼装;接口失败或找不到内容时,改用各自的静态模板,TDK 全部写死。
| 路由 | 动态成功时 | 接口失败时静态模板 |
|---|---|---|
| `/about-us/` | 富文本标题驱动的规则 TDK | `aboutUs.html`:TDK 写死 |
| `/user-agreement/` | 富文本标题驱动的规则 TDK | `userAgreement.html`:TDK 写死 |
| `/privacy-policy/` | 富文本标题驱动的规则 TDK | `privacyPolicy.html`:TDK 写死 |
| `/help-center/` | 富文本标题驱动的规则 TDK | `helpCenter.html`:TDK 写死 |
路由切换逻辑见 `app/api/web/richtext.go:26-50`。
## 五、TDK 写死的页面
这些模板不读取 `.seoInfo`,即使公共渲染层取得导航 SEO,也不会改变最终 TDK。
| 页面 / 路由 | TDK 情况 | 模板 |
|---|---|---|
| 个人中心 `/user-center/` | 全部写死 | `app/templates/page/userCenter.html:7-12` |
| 金币/会员充值 `/deposit/...` | T 由 handler 固定传入,D/K 写死;整体仍属固定 TDK | `app/templates/page/deposit.html:7-9` |
| 我的收藏 `/collect/...` | T 由 handler 固定传入,D/K 写死 | `app/templates/page/collect.html:7-9` |
| 观看历史 `/history/...` | 全部写死 | `app/templates/page/history.html:7-9` |
| 账号设置 `/setting/` | 全部写死 | `app/templates/page/setting.html:7-12` |
| 编辑资料 `/edit-profile/` | 全部写死 | `app/templates/page/editProfile.html:7-12` |
| 修改密码 `/edit-password/` | 全部写死 | `app/templates/page/editPassword.html:7-12` |
| 问题反馈 `/feedback/` | 全部写死 | `app/templates/page/feedback.html:7-12` |
以上账户页多数设置了 `noindex,nofollow`,固定 TDK 对自然搜索影响较小。
## 关键风险与建议
1. **详情页和播放页丢弃后台 D/K**:handler 已经拿到 `seoInfo.description/keywords`,模板在存在 `detail/playlet` 时却绕过它们。若后台运营会配置详情和章节 SEO,这部分配置当前不会生效。
2. **短剧列表和剧集列表没有页面接口 SEO**:二者完全依赖导航 SEO;导航未配置时所有筛选/分页页面主要使用相同兜底内容,仅筛选值可能由公共层追加。
3. **富文本 `seoInfo` 未映射**:数据模型中虽然服务端领域模型可见 `SeoInfo`,Web 上游响应结构 `AppRichTextItemResp` 没有该字段,当前只能用标题套固定句式。
4. **专题列表 D/K 固定**:分页页标题会变化,但 description 和 keywords 始终一致。
5. **登录/注册复用首页 TDK,且 robots 标志不一致**:handler 设置了 `noindex=true`,但 `index.html` 固定输出 `index,follow`。这两个页面不仅 TDK 与页面功能不一致,还可能被搜索引擎索引。