listpage_cli 0.0.302 → 0.0.303

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listpage_cli",
-  "version": "0.0.302",
+  "version": "0.0.303",
   "private": false,
   "bin": {
     "listpage_cli": "bin/cli.js"

package/templates/backend-template/package.json.tmpl

@@ -25,7 +25,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "~0.14.2",
     "rxjs": "^7.8.1",
-    "listpage-next-nest": "~0.0.302"
+    "listpage-next-nest": "~0.0.303"
   },
   "devDependencies": {
     "@nestjs/schematics": "^11.0.0",

package/templates/frontend-template/package.json.tmpl

@@ -12,7 +12,7 @@
   "dependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "listpage-next": "~0.0.302",
+    "listpage-next": "~0.0.303",
     "react-router-dom": ">=6.0.0",
     "@ant-design/v5-patch-for-react-19": "~1.0.3",
     "ahooks": "^3.9.5",
@@ -23,7 +23,7 @@
     "styled-components": "^6.1.19",
     "mobx": "~6.15.0",
     "@ant-design/icons": "~6.0.2",
-    "listpage-components": "~0.0.302",
+    "listpage-components": "~0.0.303",
     "lucide-react": "~0.575.0"
     "mobx-react-lite": "~4.1.1"
   },

package/templates/skills-template/listpage-http/api.md

@@ -12,6 +12,7 @@
   - `EndpointConfig<Req, Res>`：单个接口配置泛型。
   - `EndpointMode`：`"json" | "upload" | "download" | "sse"`。
   - `ApiEnvelope<T>`：后端 `{ code, message, data }` 统一模型。
+  - `DownloadResult`：下载模式统一返回类型 `{ blob: Blob; filename?: string }`。
 - **配置工具**
   - `defineEndpoint<Req, Res>(config: EndpointConfig<Req, Res>)`：声明一个接口。
 - **客户端**
@@ -43,6 +44,7 @@ export function defineEndpoint<Req, Res>(
 
 - 声明接口的 HTTP 方法、路径、是否 SSE、是否需要鉴权，以及数据模式（`mode`）。
 - 当 `mode === "upload"` 时，请求体参数会被视为普通对象，并在内部自动转换为 `FormData` 进行 `multipart/form-data` 上传。
+- 当 `mode === "download"` 时，建议将 `Res` 统一写为 `DownloadResult`，内部会返回 `{ blob, filename }`，**不再走 JSON 解析与业务 code 判定**。
 - 绑定请求泛型 `Req` 与响应泛型 `Res`，后续通过 `ApiClient` 自动推导。
 
 ### ClientOptions

package/templates/skills-template/listpage-http/examples.md

@@ -249,9 +249,62 @@ export async function uploadFile(params: ReqUploadFile): Promise<ResUploadFile>
 
 ---
 
-## 9. 新增接口 Checklist
+## 9. 文件下载示例（`mode: "download"`，统一使用 `DownloadResult`）
+
+```ts
+// src/api/report.ts
+export interface ReqDownloadReport {
+  id: string;
+}
+```
+
+```ts
+// src/api/request-config.ts 片段
+import { defineEndpoint, type DownloadResult } from "listpage-http";
+import type { ReqDownloadReport } from "./report";
+
+export const requestConfig = {
+  report: {
+    download: defineEndpoint<ReqDownloadReport, DownloadResult>({
+      method: "POST",
+      path: "/report/download",
+      mode: "download",
+    }),
+  },
+} as const;
+```
+
+```ts
+// service 调用：获取 blob 和文件名，交由业务决定如何处理（下载 / 预览等）
+import api from "@/api";
+import type { ReqDownloadReport } from "@/api/report";
+
+export async function downloadReport(params: ReqDownloadReport) {
+  const { blob, filename } = await api.report.download(params);
+
+  const url = window.URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename || "download";
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  window.URL.revokeObjectURL(url);
+}
+```
+
+说明：
+
+- 下载模式下（`mode: "download"`）：
+  - `listpage-http` 不再解析 JSON，直接返回 `{ blob, filename }`。
+  - 文件名优先从响应头 `Content-Disposition` 中解析，失败则为 `undefined`，由业务自行决定默认值。
+- 即使下载失败（如 404/500），仍会按统一错误模型抛出 `ApiError` 并触发 `onError`。
+
+---
+
+## 10. 新增接口 Checklist
 
 1. 在对应模块类型文件（如 `src/api/order.ts`）中添加 `ReqOrderList` / `ResOrderList` 等类型。
 2. 在 `src/api/request-config.ts` 中为该模块新增一个 `defineEndpoint`（例如 `order.list`）。
-3. 在 service/hook 中通过 `api.order.list(params)` 调用。
+3. 在 service/hook 中通过 `api.order.list(params)` 或 `api.order.list(undefined, options)` 调用。
 4. 禁止在业务代码中直接使用 `fetch`/`axios`，必须通过统一的 `api` 客户端。