docs/posts-title-api.md

@@ -1,6 +1,39 @@
 # Posts title fields for list/card surfaces
 
-Front-end list/card surfaces such as **热门资料**, **官方推荐**, and **全部资料** should display a short title, not the full Telegram/body text.
+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
 
@@ -21,19 +54,19 @@ Any endpoint returning `Post` items should include a short title when available:
   "localizations": {
     "zh": {
       "title": "ARK 2026 共识加速计划",
-      "text": "完整中文正文...",
+      "text": "完整中文正文..."
     },
     "en": {
       "title": "ARK 2026 Consensus Acceleration Plan",
-      "text": "Full English body...",
+      "text": "Full English body..."
-    },
+    }
-  },
+  }
 }
 ```
 
 ## Front-end fallback order
 
-For `Resource.title`, front-end reads:
+For resource card/list `Resource.title`, front-end reads:
 
 1. `localizations[currentLang].title`
 2. `post.title`
@@ -41,7 +74,7 @@ For `Resource.title`, front-end reads:
 4. first attachment filename
 5. `post.id`
 
-So backend can roll this out gradually: old posts without `title` still render, but long body text will be reduced to its first line.
+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
 
@@ -50,7 +83,7 @@ Do **not** put an entire body paragraph into `title`. `title` should be concise
 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 |