Files

TerryM 1557d29af7 docs(posts): clarify backend title field requirements

Clarify that compact browsing surfaces should receive short post title fields
from the backend even if some frontend pages do not display them yet. Separate
the product requirement from current frontend implementation status so backend
can implement the API contract first and frontend can opt in per surface later.

2026-05-30 03:28:33 +08:00

2.8 KiB

Raw Blame History

Posts title fields for list/card surfaces

Back-end should provide short title fields on Post responses so front-end can render concise list/card titles without using the full Telegram/body text.

Product requirement

Any list/card surface that is meant for quick browsing should display a short title, not the full text body. Full Telegram-style body copy is too noisy for compact surfaces.

This includes:

Home 官方推荐 carousel/cards
Home 最新资料
Home 热门资料 ranking list
/official-recommendations
/browse (全部资料)
/category/:slug
Search result previews/lists

The full body text should remain available as text for message/detail rendering, expansion, and search indexing.

Current front-end implementation status

Already consuming title through postToResource / Resource.title:

Home 官方推荐 carousel/cards
/official-recommendations
Home 热门资料 ranking list

Pending front-end follow-up after the back-end fields are available:

Home 最新资料
/browse (全部资料)
/category/:slug
Search results

Those pending surfaces currently render text via MessageBubble. Once the back-end consistently provides title, front-end can decide the final UI treatment, but the desired display content for compact browsing is the short title.

Affected endpoints

Any endpoint returning Post items should include a short title when available:

GET /api/posts
GET /api/posts/search
GET /api/posts/recommended
GET /api/posts/:id

Recommended response shape

{
  "id": "string",
  "title": "ARK 2026 共识加速计划", // optional global fallback title
  "text": "完整正文 / Telegram-style body text...",
  "localizations": {
    "zh": {
      "title": "ARK 2026 共识加速计划",
      "text": "完整中文正文..."
    },
    "en": {
      "title": "ARK 2026 Consensus Acceleration Plan",
      "text": "Full English body..."
    }
  }
}

Front-end fallback order

For resource card/list Resource.title, front-end reads:

localizations[currentLang].title
post.title
first non-empty line of localized/full text
first attachment filename
post.id

So backend can roll this out gradually: old posts without title still render, but resource card/list surfaces reduce long body text to its first non-empty line instead of displaying the full paragraph.

Requirement

Do not put an entire body paragraph into title. title should be concise enough for a two-line card/list title.

Examples:

Good title	Bad title
`ARK 2026「共识加速计划」邀请王霸榜`	Full event body with links, schedule, rules, and hashtags
`ARK 主网核心合约地址（BSC链）`	Full contract explainer paragraph
`ARK灵魂五问完整视频`	Full video caption text

2.8 KiB Raw Blame History Unescape Escape