Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tech.illasoft.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

Trending 是首页「Home Cards V2」之下的热门展示区，用于突出推广当前运营想要强调的作品 / 功能 / 活动。由 Payload CMS Global 驱动，12 locale i18n，60 秒 ISR 缓存。

​
数据模型

Global：Trending（源：kira-cms/src/operation/Trending.ts:32） 
items: Array<{
  coverType: "image" | "video",
  coverImage?: MediaRef,   // coverType = "image" 时
  coverVideo?: MediaRef,   // coverType = "video" 时
  url: string,             // 点击跳转（外链 / 站内路径）

  // i18n 字段（12 locales）
  title_en_US: string,
  title_zh_CN: string,
  title_zh_TW: string,
  title_ja_JP: string,
  title_ko_KR: string,
  title_de_DE: string,
  title_es_ES: string,
  title_fr_FR: string,
  title_it_IT: string,
  title_pt_PT: string,
  title_ru_RU: string,
  title_ms_MY: string,

  // Admin UI helper
  translateButton: UI  // 一键翻译
}>

​
Admin UI

​
添加 / 编辑 item

进入 Payload Admin → Globals → Trending → 点击 + 添加 item。

​
一键翻译

每个 item 右上角有 TrendingTranslateButton（位置：kira-cms/src/components/TranslateButton.tsx:26）。点击后：
  1. 调用 /api/translate（CMS 内部 route）
  2. 以英文 (title_en_US) 为源，翻译到其余 11 个 locale
  3. 自动填充 title_{locale} 字段
  4. 用户保存后生效

​
缓存链路

Admin Save (afterChange hook)
  ↓
Redis SET global_trending (depth=1，含 media URL)
  ↓
Slack 通知（可选）
  ↓
kira-be  GET /op/trending
  ├─ 检查 Accept-Language header
  ├─ 从 CMS 的 /api/cached/trending 拉 JSON
  ├─ 按 locale 选 title_{locale}
  └─ 返回 { items: [...] }
  ↓
kira-web  queryTrending()（Next.js ISR 60s）
  ↓
<Trending> 组件渲染

​
kira-be 路由

GET /op/trending（源：kira-be/src/hono/op/index.ts:174） 
// Response
{
  items: [
    {
      coverType: "image",
      coverImage: string,   // 签名 URL
      title: string,        // 已按 Accept-Language 选定的 locale
      url: string
    },
    ...
  ]
}

​
kira-web 消费

  • Server fetcher：apis/server/queryTrending.ts:14
  • 组件：components/feature/common/home/trending.tsx（位置根据实际路径）
  • 触发页面：app/(home)/page.tsx
revalidate: 60，运营更新后最多 1 分钟可见。

​
运营 SOP

  1. 准备素材（封面图或视频，比例建议 16:9）
  2. Admin → Globals → Trending → 添加 item
  3. 填 title_en_US、url、coverType + 对应 coverImage/coverVideo
  4. 点击 TrendingTranslateButton 一键翻译其余 locale
  5. 检查翻译结果，必要时手改
  6. Save
  7. 60 秒内线上自动更新

​
注意事项

  • items 顺序就是展示顺序；拖动调整
  • 删除 item：选中后删除，再 Save
  • 如 Redis 出问题导致缓存没更新，/api/cached/trending?nocache=1 可强制穿透
  • 单 item 无单独 visibility 开关，删除即下线
  • Trending 与 Home Cards V2 的 Featured tab 不共享数据，各自维护

​
相关