这是一篇由后端AI给前端AI写的API说明文档

本文档描述「荣县快讯」在后台的管理接口契约，供 vue-admin 项目中的 AI 直接生成：

• axios 调用层（API client）
• TypeScript 类型（Request/Response/Entity）
• 列表页（筛选 + 分页表格）
• 详情弹窗/抽屉
• 上下线（软删除）开关

基本约定

Base

• BasePath：/admin/news-feed/*
• Content-Type：application/json

鉴权

• Header：Authorization: Bearer <token>
• 登录失效/未登录：errcode = 401001（前端应跳转登录或触发重新登录流程）

响应结构（统一）

所有接口返回：

{
  "errcode": 200,
  "message": "success",
  "data": {}
}

• errcode = 200 表示成功
• errcode != 200 表示失败
• 参数错误：使用 errcode = 0（CodeEnum::FAIL），message 由接口自定义

时间格式（严格校验）

列表筛选的发布时间范围仅接受：

• YYYY-MM-DD
• YYYY-MM-DD HH:MM:SS

任一时间字段解析失败：直接返回 errcode=0，例如：

{ "errcode": 0, "message": "发布时间格式错误，仅支持 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS" }

status 语义

• status = 1：展示/上线
• status = 0：隐藏/下线

注意：前台（首页/更多）只应展示 status=1 的新闻。

数据结构

NewsFeed

export type NewsFeed = {
  id: number;
  title: string;
  summary?: string;
  image_url?: string;
  url?: string;
  source_name?: string;
  source_url?: string;
  published_at: string; // DATETIME 字符串，例如 "2026-01-14 09:30:00"
  status: 0 | 1;
  created?: string;
  updated?: string;
};

Pagination

与后台既有格式一致（page 字段在 data 内）：

export type PageInfo = {
  current_page: number;
  current: number;
  page_size: number;
  total_items: number;
  total: number;
  total_pages: number;
};

接口列表

1) 列表：POST /admin/news-feed/list

用途：分页获取新闻列表，支持筛选。

Request

export type NewsFeedListReq = {
  current_page?: number; // 默认 1
  page_size?: number;    // 默认 20

  status?: 0 | 1;
  source_name?: string;  // 精确匹配
  keywords?: string;     // 模糊匹配 title/summary

  published_from?: string; // 见“时间格式（严格校验）”
  published_to?: string;   // 见“时间格式（严格校验）"

  has_image?: 0 | 1;     // 1=仅有图，0=仅无图（可选能力）
};

Response（成功）

export type NewsFeedListResp = {
  errcode: 200;
  message: string;
  data: {
    page: PageInfo;
    list: NewsFeed[];
  };
};

示例

Request:

{
  "current_page": 1,
  "page_size": 20,
  "status": 1,
  "keywords": "荣县",
  "published_from": "2026-01-01",
  "published_to": "2026-01-31"
}

Response:

{
  "errcode": 200,
  "message": "success",
  "data": {
    "page": {
      "current_page": 1,
      "current": 1,
      "page_size": 20,
      "total_items": 123,
      "total": 123,
      "total_pages": 7
    },
    "list": [
      {
        "id": 101,
        "title": "荣县最新动态",
        "summary": "...",
        "image_url": "https://...",
        "url": "https://...",
        "source_name": "某权威来源",
        "published_at": "2026-01-14 09:30:00",
        "status": 1
      }
    ]
  }
}

2) 详情：POST /admin/news-feed/detail

用途：获取单条新闻详情。

Request

export type NewsFeedDetailReq = {
  id: number;
};

Response（成功）

export type NewsFeedDetailResp = {
  errcode: 200;
  message: string;
  data: NewsFeed;
};

失败情况

• 数据不存在：errcode != 200（message 自定义即可）
• 未登录：errcode = 401001

3) 上下线（软删除）：POST /admin/news-feed/update-status

用途：把新闻标记为展示/隐藏。

Request

export type NewsFeedUpdateStatusReq = {
  id: number;
  status: 0 | 1;
};

Response（成功）

export type NewsFeedUpdateStatusResp = {
  errcode: 200;
  message: string;
  data: {};
};

幂等性

• 如果记录当前 status 已经等于目标 status：仍返回成功（errcode=200），不报错。

vue-admin 生成建议（给 AI 的执行指令）

你可以把下面这段“指令”直接粘贴给 vue-admin 项目的 AI：

1. 生成 src/api/newsFeed.ts：封装 list/detail/updateStatus 三个函数，全部 POST JSON。
2. 生成 src/types/newsFeed.ts：包含 NewsFeed、PageInfo、三个 Request/Response 类型。
3. 生成管理页面：
   • 路由：/content/news-feed（或你们内容管理下的既有分组）
   • 筛选项：status（全部/上线/下线）、source_name、keywords、发布时间范围（date picker range）
   • 表格列：标题、来源、发布时间、状态、操作（详情/下线/上线）
   • 详情：drawer/dialog 展示 title/summary/url/image/source/published_at/status
4. 处理错误码：
   • errcode===401001：触发退出登录/跳登录
   • errcode!==200：用 message toast