feat: align frontend languages with posts api
This commit is contained in:
TerryM
@@ -16,34 +16,34 @@ status: draft
|
||||
type AttachmentKind = "image" | "video" | "document";
|
||||
|
||||
type Attachment = {
|
||||
id: string; // 唯一 id
|
||||
kind: AttachmentKind; // 三大类，前端按此分支渲染
|
||||
url: string; // 原始文件地址
|
||||
mime: string; // image/jpeg, application/pdf, video/mp4, ...
|
||||
filename: string; // 显示用文件名，含扩展名
|
||||
sizeBytes: number; // 字节数；前端格式化为 "3.5 MB"
|
||||
width?: number; // image/video 用于占位比例（CLS 优化）
|
||||
id: string; // 唯一 id
|
||||
kind: AttachmentKind; // 三大类，前端按此分支渲染
|
||||
url: string; // 原始文件地址
|
||||
mime: string; // image/jpeg, application/pdf, video/mp4, ...
|
||||
filename: string; // 显示用文件名，含扩展名
|
||||
sizeBytes: number; // 字节数；前端格式化为 "3.5 MB"
|
||||
width?: number; // image/video 用于占位比例（CLS 优化）
|
||||
height?: number;
|
||||
durationSec?: number; // video 专用
|
||||
posterUrl?: string; // video 海报缩略图
|
||||
thumbnailUrl?: string; // image 缩略，列表用减少流量
|
||||
durationSec?: number; // video 专用
|
||||
posterUrl?: string; // video 海报缩略图
|
||||
thumbnailUrl?: string; // image 缩略，列表用减少流量
|
||||
};
|
||||
|
||||
type Post = {
|
||||
id: string;
|
||||
categoryId: number;
|
||||
categorySlug: string;
|
||||
language: string; // "zh-TW" | "zh-CN" | "en"
|
||||
text?: string; // 可选，纯文本/图说；前端做 https → 链接自动识别
|
||||
attachments: Attachment[]; // 0~N；text-only post 时为 []
|
||||
language: string; // "zh" | "en" | "ja" | "ko" | "vi" | "id" | "ms"
|
||||
text?: string; // 可选，纯文本/图说；前端做 https → 链接自动识别
|
||||
attachments: Attachment[]; // 0~N；text-only post 时为 []
|
||||
isRecommended: boolean;
|
||||
publishedAt: string; // ISO 8601；用于排序 + 日期分组
|
||||
publishedAt: string; // ISO 8601；用于排序 + 日期分组
|
||||
updatedAt: string;
|
||||
};
|
||||
|
||||
type PostListResponse = {
|
||||
items: Post[];
|
||||
nextCursor?: string; // 不透明 cursor；undefined = 没有下一页
|
||||
nextCursor?: string; // 不透明 cursor；undefined = 没有下一页
|
||||
};
|
||||
```
|
||||
|
||||
@@ -67,14 +67,14 @@ GET /api/posts
|
||||
|
||||
Query 参数：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `lang` | 是 | UI 语言；后端可据此选择不同语言版本的 `text` |
|
||||
| `category` | 否 | category slug；不传 = 全部分类 |
|
||||
| `type` | 否 | `all` / `image` / `video` / `pdf` / `ppt` / `text` / `link` / `archive`；语义见 §3 |
|
||||
| `language` | 否 | 资源语言：`zh-TW` / `zh-CN` / `en` |
|
||||
| `cursor` | 否 | 上一次返回的 `nextCursor`；不传 = 第一页 |
|
||||
| `limit` | 否 | 默认 20，最大 50 |
|
||||
| 参数 | 必填 | 说明 |
|
||||
| ---------- | ---- | ---------------------------------------------------------------------------------- |
|
||||
| `lang` | 是 | UI 语言；后端可据此选择不同语言版本的 `text` |
|
||||
| `category` | 否 | category slug；不传 = 全部分类 |
|
||||
| `type` | 否 | `all` / `image` / `video` / `pdf` / `ppt` / `text` / `link` / `archive`；语义见 §3 |
|
||||
| `language` | 否 | 资源语言：`zh` / `en` / `ja` / `ko` / `vi` / `id` / `ms` |
|
||||
| `cursor` | 否 | 上一次返回的 `nextCursor`；不传 = 第一页 |
|
||||
| `limit` | 否 | 默认 20，最大 50 |
|
||||
|
||||
返回：`PostListResponse`
|
||||
|
||||
@@ -117,6 +117,7 @@ GET /api/admin/posts?... (含未发布草稿)
|
||||
```
|
||||
|
||||
需求：
|
||||
|
||||
- 支持多附件上传（一次 multipart 或先 `POST /api/admin/upload` 拿到 url 再创建 Post）。
|
||||
- Admin UI 需要一个开关：「图片以图片形式呈现 / 以文档形式呈现」，对应 attachment.kind 的 image vs document。
|
||||
- 支持发布/隐藏、置顶/官方推荐。
|
||||
@@ -127,28 +128,28 @@ GET /api/admin/posts?... (含未发布草稿)
|
||||
|
||||
一个 Post 命中某个 `type`，规则：
|
||||
|
||||
| type | 命中条件 |
|
||||
|---|---|
|
||||
| `all` | 全部 |
|
||||
| `image` | `attachments` 中至少一个 `kind === "image"` 或 `mime.startsWith("image/")` |
|
||||
| `video` | 至少一个 `kind === "video"` 或 `mime.startsWith("video/")` |
|
||||
| `pdf` | 至少一个 `mime === "application/pdf"` 或扩展名为 `pdf` |
|
||||
| `ppt` | 至少一个扩展名为 `ppt` / `pptx` / `key` 或 mime 含 `presentation` |
|
||||
| `archive` | 至少一个扩展名为 `zip` / `rar` / `7z` / `tar` / `gz` |
|
||||
| `text` | `text` 非空 |
|
||||
| `link` | `text` 非空且匹配 `https?://` |
|
||||
| type | 命中条件 |
|
||||
| --------- | -------------------------------------------------------------------------- |
|
||||
| `all` | 全部 |
|
||||
| `image` | `attachments` 中至少一个 `kind === "image"` 或 `mime.startsWith("image/")` |
|
||||
| `video` | 至少一个 `kind === "video"` 或 `mime.startsWith("video/")` |
|
||||
| `pdf` | 至少一个 `mime === "application/pdf"` 或扩展名为 `pdf` |
|
||||
| `ppt` | 至少一个扩展名为 `ppt` / `pptx` / `key` 或 mime 含 `presentation` |
|
||||
| `archive` | 至少一个扩展名为 `zip` / `rar` / `7z` / `tar` / `gz` |
|
||||
| `text` | `text` 非空 |
|
||||
| `link` | `text` 非空且匹配 `https?://` |
|
||||
|
||||
前端 mock 已按此规则过滤，便于切真接口时口径一致。
|
||||
|
||||
## 4. 删除 / 废弃
|
||||
|
||||
| 项 | 处理 |
|
||||
|---|---|
|
||||
| `POST /api/resources/:id/favorite` | 删除 |
|
||||
| `GET /api/favorites` / 收藏列表 | 删除（前端 `/favorites` 路由已移除） |
|
||||
| `/r/:id` 老前端路由 | 已合并到 `/resource/:id` 重定向 |
|
||||
| 老 `/api/resources*` 系列 | 后端可保留过渡期。建议提供数据迁移脚本：每个老 Resource → 一个 Post（带 1 个 attachment 或 text-only）。`isRecommended` / `language` / `categorySlug` 字段迁移；`favorite count` 字段丢弃。 |
|
||||
| Resource.coverImage 与 Resource.fileUrl 二选一 | 转为 attachments[0]（kind 由后端判断 image vs document）|
|
||||
| 项 | 处理 |
|
||||
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `POST /api/resources/:id/favorite` | 删除 |
|
||||
| `GET /api/favorites` / 收藏列表 | 删除（前端 `/favorites` 路由已移除） |
|
||||
| `/r/:id` 老前端路由 | 已合并到 `/resource/:id` 重定向 |
|
||||
| 老 `/api/resources*` 系列 | 后端可保留过渡期。建议提供数据迁移脚本：每个老 Resource → 一个 Post（带 1 个 attachment 或 text-only）。`isRecommended` / `language` / `categorySlug` 字段迁移；`favorite count` 字段丢弃。 |
|
||||
| Resource.coverImage 与 Resource.fileUrl 二选一 | 转为 attachments[0]（kind 由后端判断 image vs document） |
|
||||
|
||||
## 5. Search
|
||||
|
||||
|
||||
Reference in New Issue
Block a user