listpage_cli 0.0.299 → 0.0.300

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listpage_cli",
-  "version": "0.0.299",
+  "version": "0.0.300",
   "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.299"
+    "listpage-next-nest": "~0.0.300"
   },
   "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.299",
+    "listpage-next": "~0.0.300",
     "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.299",
+    "listpage-components": "~0.0.300",
     "lucide-react": "~0.575.0"
     "mobx-react-lite": "~4.1.1"
   },

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

@@ -60,6 +60,7 @@ Task Progress:
 
 ## 命名与模块约定
 
+- **文件命名**：统一使用短横线间隔（kebab-case），例如：`request-config.ts`、`user-profile.ts`、`order-detail.ts`。
 - **模块名**：`requestConfig` 中一级 key 建议与模块文件名一致，如 `user`、`order`。
 - **方法名**：使用动词短语小驼峰，如 `login`、`list`、`detail`、`create`、`update`、`remove`。
 - **类型命名**：

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

@@ -41,7 +41,8 @@ export function defineEndpoint<Req, Res>(
 
 用途：
 
-- 声明接口的 HTTP 方法、路径、是否 SSE、是否需要鉴权。
+- 声明接口的 HTTP 方法、路径、是否 SSE、是否需要鉴权，以及数据模式（`mode`）。
+- 当 `mode === "upload"` 时，请求体参数会被视为普通对象，并在内部自动转换为 `FormData` 进行 `multipart/form-data` 上传。
 - 绑定请求泛型 `Req` 与响应泛型 `Res`，后续通过 `ApiClient` 自动推导。
 
 ### ClientOptions
@@ -78,7 +79,7 @@ export interface ClientOptions {
 
 ```ts
 export interface RequestOptions {
-  timeout?: number; // 单次调用超时
+  timeout?: number; // 单次调用超时（传 0 表示显式关闭超时）
   headers?: Record<string, string>;
   cache?: {
     key?: string;
@@ -89,7 +90,8 @@ export interface RequestOptions {
 
 说明：
 
-- 若不配 `timeout`，会 fallback 到 `ClientOptions.defaultTimeout`。
+- 若未显式配置 `timeout`，则不启用超时逻辑（不会使用 `ClientOptions.defaultTimeout`）。
+- 若在接口级或调用级将 `timeout` 显式设置为 `0`，则表示**本次请求不使用超时逻辑**，并覆盖掉任何默认超时。
 - 若不配 `cache`，则该次请求不走缓存逻辑。
 
 ### ApiClient<Cfg>

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

@@ -46,7 +46,47 @@ export type RequestConfig = typeof requestConfig;
 
 ---
 
-## 3. 创建并导出 client（`src/api/index.ts`）
+## 3. 无参数接口示例（`Req = void`）
+
+对于完全没有请求体的接口，推荐将 `Req` 定义为 `void`，并在调用时传 `undefined` 作为第一个参数：
+
+```ts
+// src/api/system.ts
+export type ReqPing = void;
+
+export interface ResPing {
+  ok: boolean;
+}
+```
+
+```ts
+// src/api/request-config.ts 片段
+import { defineEndpoint } from "listpage-http";
+import type { ReqPing, ResPing } from "./system";
+
+export const requestConfig = {
+  system: {
+    ping: defineEndpoint<ReqPing, ResPing>({
+      method: "GET",
+      path: "/system/ping",
+    }),
+  },
+} as const;
+```
+
+```ts
+// service 调用：显式传入 undefined 表示没有请求体
+import api from "@/api";
+import type { ResPing } from "@/api/system";
+
+export async function ping(): Promise<ResPing> {
+  return api.system.ping(undefined, { timeout: 3_000 });
+}
+```
+
+---
+
+## 4. 创建并导出 client（`src/api/index.ts`）
 
 ```ts
 import { createApiClient } from "listpage-http";
@@ -73,7 +113,7 @@ export default api;
 
 ---
 
-## 4. 在 service 中调用（推荐，不直接在组件里写细节）
+## 5. 在 service 中调用（推荐，不直接在组件里写细节）
 
 ```ts
 // src/services/auth.ts
@@ -90,7 +130,7 @@ export async function login(values: ReqLogin): Promise<ResLogin> {
 
 ---
 
-## 5. 在组件中使用
+## 6. 在组件中使用
 
 接口报错已由 api 层（`onError`）统一处理，业务层**不需要**对 `api` 调用再包 try/catch 来弹错误提示。
 
@@ -117,7 +157,7 @@ export function LoginForm() {
 
 ---
 
-## 6. SSE 示例（可选）
+## 7. SSE 示例（可选）
 
 ```ts
 // 在 request-config 中配置 SSE 接口
@@ -159,7 +199,57 @@ async function startSse(id: string) {
 
 ---
 
-## 7. 新增接口 Checklist
+## 8. 文件上传示例（`mode: "upload"`，内部自动 FormData）
+
+```ts
+// src/api/file.ts
+export interface ReqUploadFile {
+  file: File;
+  bizType: string;
+}
+
+export interface ResUploadFile {
+  url: string;
+}
+```
+
+```ts
+// src/api/request-config.ts 片段
+import { defineEndpoint } from "listpage-http";
+import type { ReqUploadFile, ResUploadFile } from "./file";
+
+export const requestConfig = {
+  file: {
+    upload: defineEndpoint<ReqUploadFile, ResUploadFile>({
+      method: "POST",
+      path: "/file/upload",
+      mode: "upload", // 关键：内部会将 ReqUploadFile 转成 FormData
+    }),
+  },
+} as const;
+```
+
+```ts
+// service 调用
+import api from "@/api";
+import type { ReqUploadFile, ResUploadFile } from "@/api/file";
+
+export async function uploadFile(params: ReqUploadFile): Promise<ResUploadFile> {
+  return api.file.upload(params);
+}
+```
+
+说明：
+
+- 当某个接口配置 `mode: "upload"` 时，`listpage-http` 会将第二个参数（`params`）视为普通对象：
+  - 普通字段：`formData.append(key, value)`。
+  - 数组字段：对每一项执行一次 `append`。
+  - `null` / `undefined` 字段会被跳过，不会被序列化为 `"null"` 或 `"undefined"`。
+- Content-Type 由浏览器在提交 `FormData` 时自动携带带 boundary 的 `multipart/form-data`，如需覆盖可在 headers 中显式传入。
+
+---
+
+## 9. 新增接口 Checklist
 
 1. 在对应模块类型文件（如 `src/api/order.ts`）中添加 `ReqOrderList` / `ResOrderList` 等类型。
 2. 在 `src/api/request-config.ts` 中为该模块新增一个 `defineEndpoint`（例如 `order.list`）。