1557d29af7
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.
90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# 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
|
||
|
||
```jsonc
|
||
{
|
||
"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:
|
||
|
||
1. `localizations[currentLang].title`
|
||
2. `post.title`
|
||
3. first non-empty line of localized/full `text`
|
||
4. first attachment filename
|
||
5. `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 |
|