listpage_cli 0.0.298 → 0.0.300

package/package.json

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

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

@@ -0,0 +1,69 @@
+---
+name: listpage-http
+description: 使用 listpage-http 在前端项目中接管所有 HTTP 请求，统一通过 src/api 目录的 request-config 与 client 调用。Use when user mentions listpage-http, request-config, api client or统一 HTTP 请求管理.
+---
+
+# listpage-http 使用技能
+
+详细 API 说明与代码示例见 [api.md](api.md)、[examples.md](examples.md)。
+
+## 总体目标
+
+在新项目中用 `listpage-http` 接管所有 HTTP 请求，形成统一、可追踪的接口层：
+
+- 所有后端接口 **必须在一个 request-config 映射表中集中注册**。
+- 所有业务代码 **只能通过统一的 client 调用接口**。
+- 每个业务模块在 `src/api` 下有对应的「类型文件」，只负责声明请求/响应类型。
+- **接口报错已由此 API 层接管**（通过 `onError`、未授权跳转等统一处理），业务层**不需要也不应再**在调用处捕获接口错误（如对 `api.xxx.yyy()` 包一层 try/catch 专门处理接口失败）。
+
+## 目录规范
+
+推荐统一目录结构（可按项目实际略调，但语义不变）：
+
+```
+src/
+  api/
+    request-config.ts     # 用 defineEndpoint 注册所有接口
+    index.ts              # createApiClient，默认导出 client
+    user.ts               # user 模块：只放接口的 Req/Res 类型
+    order.ts              # 其他模块同理……
+```
+
+规范要求：
+
+1. **`src/api/*.ts`（如 `user.ts`）**
+   - 只定义对应模块的 **请求体类型 (ReqXXX)** 和 **响应数据类型 (ResXXX)**。
+   - 如果类型过多，可以拆分到子目录，最终由该模块 `index.ts` 统一导出类型。
+   - 不在这里直接发请求，不引入 `createApiClient`。
+
+2. **`src/api/request-config.ts`**
+   - 作为**唯一的接口映射表**。
+   - 使用 `defineEndpoint<Req, Res>()` 注册所有后端接口。
+   - 新增接口时，必须先在这里补配置，保证接口「一表可查」。
+
+3. **`src/api/index.ts`**
+   - 使用 `createApiClient(requestConfig, clientOptions)` 创建客户端。
+   - **默认导出 client**，供业务代码通过 `import api from '@/api'` 使用。
+   - 负责配置 baseURL、tokenKey、默认超时、成功码、未授权处理、**统一错误处理（onError）**等；接口报错由此层统一接管，业务层无需再捕获。
+
+## 使用流程（6 步）
+
+```
+Task Progress:
+- [ ] 步骤 1：为模块创建类型文件（如 src/api/user.ts），定义 ReqXXX / ResXXX
+- [ ] 步骤 2：在 src/api/request-config.ts 中用 defineEndpoint 注册接口
+- [ ] 步骤 3：在 src/api/index.ts 中用 createApiClient 创建并导出 client
+- [ ] 步骤 4：在 service / hooks 中通过 api.xxx.yyy 调用接口
+- [ ] 步骤 5：禁止业务代码直接使用 fetch / axios 等绕过 api 目录
+- [ ] 步骤 6：新增接口时，始终遵循「类型 → request-config → 业务调用」顺序
+```
+
+## 命名与模块约定
+
+- **文件命名**：统一使用短横线间隔（kebab-case），例如：`request-config.ts`、`user-profile.ts`、`order-detail.ts`。
+- **模块名**：`requestConfig` 中一级 key 建议与模块文件名一致，如 `user`、`order`。
+- **方法名**：使用动词短语小驼峰，如 `login`、`list`、`detail`、`create`、`update`、`remove`。
+- **类型命名**：
+  - 请求体：`ReqLogin`、`ReqUserList` 等。
+  - 响应数据：`ResLogin`、`ResUserList` 等。
+- **响应 envelope**：后端返回一般为 `{ code, message, data }`，`listpage-http` 用 `ApiEnvelope<T>` 表示，内部会按 `successCodes`、`unauthorizedCodes` 解析。

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

@@ -0,0 +1,104 @@
+# API（listpage-http）
+
+基于浏览器原生 `fetch` 的配置驱动 HTTP 客户端，统一处理 JSON 请求与 SSE 流。
+
+## 核心类型与方法
+
+来自 `listpage-http` 的主要导出（见 `src/index.ts`）：
+
+- **类型**
+  - `ClientOptions`：创建客户端时的全局配置。
+  - `RequestOptions`：单次调用时的可选配置（超时、headers、缓存等）。
+  - `EndpointConfig<Req, Res>`：单个接口配置泛型。
+  - `EndpointMode`：`"json" | "upload" | "download" | "sse"`。
+  - `ApiEnvelope<T>`：后端 `{ code, message, data }` 统一模型。
+- **配置工具**
+  - `defineEndpoint<Req, Res>(config: EndpointConfig<Req, Res>)`：声明一个接口。
+- **客户端**
+  - `createApiClient<Cfg>(config: Cfg, clientOptions: ClientOptions): ApiClient<Cfg>`
+  - `ApiClient<Cfg>`：根据 `requestConfig` 推导出的类型安全客户端。
+
+### EndpointConfig<Req, Res>
+
+```ts
+export type EndpointConfig<Req, Res> = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  defaultOptions?: RequestOptions;
+  type?: "http" | "sse";
+  mode?: "json" | "upload" | "download" | "sse";
+  authRequired?: boolean; // 默认 true
+};
+```
+
+### defineEndpoint
+
+```ts
+export function defineEndpoint<Req, Res>(
+  config: EndpointConfig<Req, Res>
+): EndpointConfig<Req, Res>;
+```
+
+用途：
+
+- 声明接口的 HTTP 方法、路径、是否 SSE、是否需要鉴权，以及数据模式（`mode`）。
+- 当 `mode === "upload"` 时，请求体参数会被视为普通对象，并在内部自动转换为 `FormData` 进行 `multipart/form-data` 上传。
+- 绑定请求泛型 `Req` 与响应泛型 `Res`，后续通过 `ApiClient` 自动推导。
+
+### ClientOptions
+
+```ts
+export interface ClientOptions {
+  baseURL: string;
+  tokenKey?: string;
+  defaultTimeout?: number;
+  defaultCacheTime?: number;
+  defaultHeaders?: Record<string, string>;
+  successCodes?: number[];
+  unauthorizedCodes?: number[];
+  unauthorizedRedirectPath?: string;
+  server?: {
+    protocol?: string;
+    host?: string;
+    port?: number;
+    publicPath?: string;
+  };
+  onError?: (code: number, message: string) => void;
+}
+```
+
+说明：
+
+- `baseURL`：通常指 `/api/v1` 这一级；也可以配合 `server` 决定完整 URL。
+- `tokenKey`：约定从何处读取 Token（如 localStorage key），具体读取逻辑视实现而定。
+- `successCodes`：哪些业务 code 视为成功（例如 `[20000, 200]`）。
+- `unauthorizedCodes`：未授权业务码（如 `[401, 403]`），可配合跳登录。
+- `onError`：统一错误处理函数，网络错误、4xx/5xx 业务错误都会透传进来。
+
+### RequestOptions
+
+```ts
+export interface RequestOptions {
+  timeout?: number; // 单次调用超时（传 0 表示显式关闭超时）
+  headers?: Record<string, string>;
+  cache?: {
+    key?: string;
+    time?: number; // 缓存时间(ms)
+  };
+}
+```
+
+说明：
+
+- 若未显式配置 `timeout`，则不启用超时逻辑（不会使用 `ClientOptions.defaultTimeout`）。
+- 若在接口级或调用级将 `timeout` 显式设置为 `0`，则表示**本次请求不使用超时逻辑**，并覆盖掉任何默认超时。
+- 若不配 `cache`，则该次请求不走缓存逻辑。
+
+### ApiClient<Cfg>
+
+由 `createApiClient` 根据 `requestConfig` 自动推导：
+
+- 普通 HTTP 接口：`(params: Req, options?: RequestOptions) => Promise<Res>`
+- SSE 接口：`(params: Req, options?: RequestOptions) => Promise<ReadableStream<any>>`
+
+业务调用时通过 `api.{module}.{fn}(params, options?)` 即可，类型由 `Req`/`Res` 自动推断。

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

@@ -0,0 +1,257 @@
+# listpage-http 示例
+
+## 1. 定义 user 模块类型（`src/api/user.ts`）
+
+```ts
+export interface ReqLogin {
+  email: string;
+  password: string;
+}
+
+export interface ResLogin {
+  token: string;
+}
+```
+
+> 只放类型，不在这里发请求。
+
+---
+
+## 2. 集中注册接口（`src/api/request-config.ts`）
+
+```ts
+import { defineEndpoint } from "listpage-http";
+import type { ReqLogin, ResLogin } from "./user";
+
+export const requestConfig = {
+  user: {
+    login: defineEndpoint<ReqLogin, ResLogin>({
+      method: "POST",
+      path: "/auth/login",
+      defaultOptions: {
+        timeout: 10_000,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+      // type: "http",      // 默认 http，可省略
+      // mode: "json",      // 默认 json，可省略
+      // authRequired: false, // 如登录接口可显式关闭鉴权
+    }),
+  },
+} as const;
+
+export type RequestConfig = typeof requestConfig;
+```
+
+---
+
+## 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";
+import { requestConfig, type RequestConfig } from "./request-config";
+
+const isDev = process.env.NODE_ENV === "development";
+
+const api = createApiClient<RequestConfig>(requestConfig, {
+  baseURL: isDev ? "http://localhost:3000/api/v1" : "/api/v1",
+  tokenKey: "AUTH_TOKEN",
+  defaultTimeout: 10_000,
+  defaultCacheTime: 5_000,
+  successCodes: [20000, 200],
+  unauthorizedCodes: [401, 403],
+  unauthorizedRedirectPath: "/login",
+  onError: (code, message) => {
+    // 统一错误处理：可根据 code 决定弹 Toast、跳转登录等
+    console.error("[API Error]", code, message);
+  },
+});
+
+export default api;
+```
+
+---
+
+## 5. 在 service 中调用（推荐，不直接在组件里写细节）
+
+```ts
+// src/services/auth.ts
+import api from "@/api";
+import type { ReqLogin, ResLogin } from "@/api/user";
+
+export async function login(values: ReqLogin): Promise<ResLogin> {
+  const data = await api.user.login(values, {
+    timeout: 5_000, // 可选：覆盖默认超时
+  });
+  return data;
+}
+```
+
+---
+
+## 6. 在组件中使用
+
+接口报错已由 api 层（`onError`）统一处理，业务层**不需要**对 `api` 调用再包 try/catch 来弹错误提示。
+
+```tsx
+import { useState } from "react";
+import { message } from "antd";
+import { login } from "@/services/auth";
+
+export function LoginForm() {
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (values: { email: string; password: string }) => {
+    setLoading(true);
+    await login(values);
+    message.success("登录成功");
+    // TODO: 写入 token / 跳转
+    setLoading(false);
+  };
+
+  // 此处省略表单 JSX，只保留调用方式示例
+  return null;
+}
+```
+
+---
+
+## 7. SSE 示例（可选）
+
+```ts
+// 在 request-config 中配置 SSE 接口
+import { defineEndpoint } from "listpage-http";
+
+export const requestConfig = {
+  agent: {
+    generateCode: defineEndpoint<{ id: string }, void>({
+      method: "POST",
+      path: "/agent/generate-code",
+      type: "sse",
+      mode: "sse",
+      defaultOptions: {
+        timeout: 3_000, // 建连超时
+      },
+    }),
+  },
+} as const;
+```
+
+```ts
+// 调用方式
+import api from "@/api";
+
+async function startSse(id: string) {
+  const stream = await api.agent.generateCode({ id });
+
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const chunk = decoder.decode(value, { stream: true });
+    console.log("SSE chunk:", chunk);
+  }
+}
+```
+
+---
+
+## 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`）。
+3. 在 service/hook 中通过 `api.order.list(params)` 调用。
+4. 禁止在业务代码中直接使用 `fetch`/`axios`，必须通过统一的 `api` 客户端。