listpage_cli 0.0.206 → 0.0.208

package/package.json

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

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

@@ -23,7 +23,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "~0.14.2",
     "rxjs": "^7.8.1",
-    "listpage-next-nest": "~0.0.206"
+    "listpage-next-nest": "~0.0.208"
   },
   "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.206",
+    "listpage-next": "~0.0.208",
     "react-router-dom": ">=6.0.0",
     "@ant-design/v5-patch-for-react-19": "~1.0.3",
     "ahooks": "^3.9.5",

package/templates/frontend-template/src/api/config.tsx

@@ -5,12 +5,13 @@ const isDev = process.env.NODE_ENV === 'development';
 // 创建axios实例
 const apiClient = new HttpClient({
   token: 'admin',
+  tokenKey: '',
   successCodes: [20000, 200],
   server: {
     protocol: undefined,
     host: isDev ? 'localhost' : undefined,
     port: isDev ? '3000' : undefined,
-    publicPath: '/api/v1/mbti',
+    publicPath: '/api/v1',
   },
   config: {
     timeout: 10000,

package/templates/frontend-template/src/api/index.ts

@@ -0,0 +1,5 @@
+import user from './user';
+
+export default {
+  user,
+};

package/templates/frontend-template/src/api/user.ts

@@ -0,0 +1,19 @@
+import apiClient from './config';
+
+type ReqLogin = {
+  email: string;
+  password: string;
+};
+
+type ResLogin = {
+  token: string;
+};
+
+export const login = async (values: ReqLogin) => {
+  const response = await apiClient.post<ResLogin>('/auth/login', values);
+  return response.data.data!;
+};
+
+export default {
+  login,
+};

package/templates/frontend-template/src/pages/Home.tsx

@@ -0,0 +1,3 @@
+export const Home = () => {
+  return <>Home</>;
+};

package/templates/rush-template/docs/ListPage-AI/347/224/237/346/210/220/350/247/204/350/214/203.md

@@ -0,0 +1,266 @@
+# AI 生成规范
+
+## 总则
+
+- 本规范仅约束 `listpage-next` 的使用与输出格式，避免输出与其无关的项目通用规则。
+- 生成的页面应围绕 `ListPage` 组件完整配置：`storageKey`、`initialValues`、`request`、`filter.options`、`table.columns`、`tableProps.rowKey` 必须齐全。
+- 页面内的动作分层清晰：页面级动作用 `header.extra`，表格级动作用 `table.extra`，浮层通过 `floats` 管理。
+- 所有数据请求函数必须返回 `PaginationData<T>`，筛选与分页参数通过 `params`/`filters` 传入。
+
+## AI 生成流程（步骤）
+
+- 步骤 1：创建目录结构
+  - `pages/<Feature>/index.tsx`、`config/{filters,columns,request,floats}.tsx`、`components/*`（浮层）、`hooks/*`（可选）、`types.ts`（可选）。
+- 步骤 2：定义筛选 `filters.tsx`
+  - 使用 AntD 组件，默认加 `allowClear`；
+- 步骤 3：定义表格列 `columns.tsx`
+  - 原子列优先使用 `component: 'text' | 'link' | 'switch'`；复杂渲染用 `render(value, record)`。
+  - 固定关键列（如选择、操作）并设置 `width`、`ellipsis`、`onHeaderCell`。
+- 步骤 4：实现请求 `request.ts`
+  - 签名：`(params, filters) => Promise<PaginationData<T>>`；失败返回空分页结构。
+  - 处理日期区间：`daterange` 在请求中展开为 `startDate`/`endDate`。
+- 步骤 5：组装页面 `index.tsx`
+  - 填写唯一 `storageKey`（命名见下），配置 `initialValues`，注入 `request`、`filter.options`、`table.columns` 与 `tableProps.rowKey`。
+  - 页面级动作放到 `header.extra`，表格级动作放到 `table.extra`。
+- 步骤 6：注册浮层 `floats`
+  - `[{ key, render }]`，组件遵循 `FloatComponentProps<T>`；在页面用 `ctx.showFloat(key, record)` 调用。
+- 步骤 7：自检并修正
+  - 通过检查清单核对命名、分层、交互、返回类型与滚动/分页设置。
+
+## 命名与输出约定
+
+- `storageKey`：`LISTPAGE_{FEATURE}` 或 `LISTPAGE_{FEATURE}_{VERSION}`，示例：`LISTPAGE_POLICY`、`LISTPAGE_CRAWLER_DATASOURCES_V2`。
+- 浮层 `key`：短横线小写，例如 `create`、`runtime-config`、`logs`。
+- 目录与文件：英文小驼峰；`columns.tsx`、`filters.tsx`、`request.ts`、`render.tsx`、`types.ts`。
+- 事件命名：语义化动词名词组合，如 `summary`、`batch-start`。
+- 行键 `rowKey`：必须与数据唯一字段一致，如 `id` 或 `name`。
+
+## 禁止事项
+
+- 不在组件中直接修改列表记录对象；通过接口更新后调用 `ctx.refreshTable()`。
+- 不在筛选输入变更时自动请求；仅在筛选操作或分页/排序变更时请求。
+
+## 1. 目标与范围
+
+- 统一基于 `listpage-next` 的列表页开发方式，降低重复和不一致。
+- 适用于包含 Header、Filter、Toolbar、Table、Floats 的页面。
+
+## 2. 页面架构与目录约定
+
+- 目录结构建议：
+  - `pages/<Feature>/index.tsx`：页面入口与 `ListPage` 组装。
+  - `pages/<Feature>/config/filters.tsx`：筛选表单项定义（`FilterFormOption[]`）。
+  - `pages/<Feature>/config/columns.tsx`：表格列定义（`ListPageTableColumn[]`）。
+  - `pages/<Feature>/config/request.ts`：数据请求函数（`(params, filters) => PaginationData<T>`）。
+  - `pages/<Feature>/config/render.tsx`：表格或工具栏扩展渲染。
+  - `pages/<Feature>/components/*`：浮层组件（Drawer/Modal），遵循 `FloatComponentProps<T>`。
+  - `pages/<Feature>/hooks/*`：与页面相关的 Hook（如 URL 参数到初始筛选值）。
+  - `pages/<Feature>/types.ts`：页面内专用类型。
+- 文件命名：语义化英文小驼峰；浮层键名使用短横线小写，例如 `create`、`runtime-config`、`logs`。
+
+## 3. 核心组件与属性
+
+- `ListPage` 由以下部分组成：
+  - `header`：页面级标题与入口动作（新建、导入）。
+  - `filter`：筛选区域（`options: FilterFormOption[]`）。
+  - `toolbar`：页面级工具栏，自定义与整体相关的批量动作。
+  - `table`：数据表格（列、选择、扩展渲染、`tableProps`）。
+  - `floats`：浮层体系（`Array<{ key: string; render: FloatRender }>`）。
+- 推荐属性：
+  - `storageKey`：必填且唯一，持久化页内状态（示例：`LISTPAGE_POLICY`、`LISTPAGE_CRAWLER_DATASOURCES_V2`）。
+  - `initialValues`：一次性初始化值（仅组件首次挂载读取，如 `currentPage`、`pageSize`、`filterValues`）。
+  - `request(params, filters)`：统一返回 `PaginationData<T>`；参数包含分页、排序等。
+  - `table.tableProps.rowKey`：必填，保证选择与行操作正确。
+  - `rowSelectionType`：`'checkbox' | 'radio'`，开启选择能力。
+  - `pageRef`：`Ref<ListPageContext>`，用于外部控制或组合式页面。
+
+## 3.1 ListPageProps 速查（AI 必须输出）
+
+- `storageKey: string` 唯一键名用于状态持久化。
+- `initialValues?: { currentPage?: number; pageSize?: number; filterValues?: Record<string, any> }`
+- `request: (params: any, filters: any) => Promise<PaginationData<any>>`
+- `header?: { title?: string; extra?: (ctx: ListPageContext) => React.ReactNode }`
+- `filter?: { options: FilterFormOption[]; labelInline?: boolean }`
+- `toolbar?: { render?: (ctx: ListPageContext) => React.ReactNode }`
+- `table: { columns: ListPageTableColumn[]; extra?: (ctx: ListPageContext) => React.ReactNode; rowSelectionType?: 'checkbox' | 'radio'; rowTitleKey?: string; tableProps?: { rowKey: string; size?: 'small'|'middle'|'large'; scroll?: { x?: number; y?: number }; pagination?: { pageSizeOptions?: number[] } } }`
+- `floats?: Array<{ key: string; render: FloatRender }>`
+- `pageRef?: React.RefObject<ListPageContext>`
+- `styles?: { page?: React.CSSProperties }`
+
+## 3.2 类型优先策略（AI 必须遵循）
+
+- 为页面定义明确的记录类型 `TRecord` 与筛选类型 `TFilters`，避免使用 `any`。
+- `columns` 使用 `ListPageTableColumn<TRecord>[]`，保证 `render`、`component` 的入参类型正确。
+- `request(params, filters)` 返回 `Promise<PaginationData<TRecord>>`，`params` 显式声明 `{ current?: number; pageSize?: number }`。
+- 浮层组件签名使用 `React.FC<FloatComponentProps<TRecord>>`；`ctx.showFloat(key, record as TRecord)` 调用。
+- `header.extra` / `table.extra` 的回调参数类型标注为 `ListPageContext`，避免未定义属性调用。
+- 枚举或布尔型筛选项使用联合类型（如 `status?: 'enabled' | 'disabled'`）。
+- 日期区间 `TFilters['dateRange']` 建议声明为 `[string, string]`，在 `request` 中展开为 `startDate`、`endDate`。
+
+## 4. 数据请求与类型规范
+
+- 返回类型：`PaginationData<T> = { list: T[]; total: number; current: number; pageSize: number }`。
+- 入参：`params`（分页、排序），`filters`（筛选表单值）。
+- 实现要点：
+  - 保持幂等与可重入，失败时返回空数据结构而非抛错。
+  - 仅在筛选变更时重置到第 1 页；分页变更不重置筛选条件。
+  - 日期字符串统一为 `YYYY-MM-DD`；区间使用 `daterange` 组件并在 `request` 中展开为 `startDate`/`endDate`。
+
+## 5. 筛选 Filter 规范
+
+- 组件：使用 AntD 控件或 `listpage-next` 内置组件（如 `AsyncSelect`、`daterange`）。
+- 定义：`FilterFormOption[]`，每项包含 `name`、`label`、`component`（或字符串组件类型）与可选 `props`/`colSpan`。
+- 交互：
+  - 表单值变化不自动请求；点击筛选或分页变更才请求。
+  - `allowClear` 作为默认交互；多选时使用 `mode='multiple'` 并控制 `maxTagCount`。
+- 异步选择：
+  - `AsyncSelect.request` 返回包含 `list` 的分页结构；`list` 元素支持 `{ label, value }` 或纯值，统一为对象更易维护。
+  - 支持 `showSearch` 与服务端过滤（`(_, search) => { ... }`）。
+
+## 6. 表格 Table 规范
+
+- 列定义：`ListPageTableColumn<T>` 支持：
+  - 原子渲染 `component: 'text' | 'link' | 'switch' | ...` 或自定义函数 `render(value, record, index)`。
+  - 列样式：`width`、`ellipsis`、`fixed`、`align`、`onHeaderCell`。
+  - 行内操作列统一放右侧，宽度尽量固定；危险操作配合二次确认。
+- 表格扩展：
+  - `table.extra(ctx)` 提供与表格数据相关的工具入口（如批量操作），通过 `ctx.selection` 读取选择态。
+  - `rowTitleKey` 用于选择态顶部标题展示，提升可读性。
+- 分页：统一在 `tableProps.pagination` 配置页码与每页条数选项；切换时保留当前筛选条件。
+
+## 7. Header 与 Toolbar 规范
+
+- 分层：
+  - 页面级动作放 `header.extra`（新建、导入、全局跳转）。
+  - 表格级动作放 `table.extra`（列设置、导出、批量执行）。
+- 访问上下文：`(ctx) => ...`，通过 `ctx.refreshTable()` 刷新列表，通过 `ctx.showFloat(key, record)` 打开浮层。
+
+## 8. 浮层 Floats 规范
+
+- 注册：`floats: Array<{ key: string; render: FloatRender }>`，`key` 使用短横线小写（如 `create`、`runtime-config`、`logs`）。
+- 组件约束：遵循 `FloatComponentProps<T>`：`{ record?: T; visible: boolean; onClose: () => void }`。
+- 交互规范：
+  - 成功操作后统一 `message.success('操作成功')` 并按需 `ctx.refreshTable()`。
+  - 避免在浮层中直接修改列表记录对象；通过接口更新后刷新。
+
+## 9. 状态持久化与初始化策略
+
+- `storageKey` 用于在本地持久化分页与筛选状态。
+- `initialValues` 仅在首次挂载时读取并覆盖一次，之后页面内部表单驱动状态，外部变更 `state` 不实时生效，以避免性能问题与状态抖动。
+
+## 10. 上下文与事件机制
+
+- `ListPageContext` 提供：`refreshTable`、`showFloat`、`selection`、`emit(event, payload)` 等能力。
+- 事件范式：在列或按钮中 `ctx.emit('summary', record)`，页面或上层组件监听并处理跨区域动作。
+- 引用：通过 `pageRef` 访问上下文能力，组合式页面可外部控制。
+
+## 11. 组件扩展与常用内置
+
+- `AsyncButton`：处理异步点击，自动 loading，建议用于批量/长耗时操作。
+- `AsyncSelect`：异步下拉；统一返回分页结构，支持搜索与多选。
+- `daterange`：日期区间组件，统一格式与占位文案；在 `request` 中落盘为 `startDate`/`endDate`。
+
+## 12. 性能与可维护性
+
+- 在 `render` 中避免重计算；复杂渲染提取到独立组件并 `memo`。
+- 控制列宽、固定必要列，保证表格横向滚动体验；开启 `scroll: { x, y }`。
+- 远程筛选与分页尽量由后端承担，前端仅拼装参数。
+- 选择态相关操作尽量批量提交，减少重复请求。
+
+## 13. 最小模板示例
+
+```ts
+import {
+  ListPage,
+  type FilterFormOption,
+  type ListPageTableColumn,
+  type PaginationData,
+  type ListPageContext,
+} from 'listpage-next';
+import { Button, Input, Select, Space } from 'antd';
+
+type User = { id: number; name: string; address: string; active?: boolean };
+type UserFilters = { name?: string; status?: 'enabled' | 'disabled' };
+
+const filters: FilterFormOption[] = [
+  {
+    name: 'name',
+    label: '姓名',
+    component: <Input placeholder="请输入" allowClear />,
+  },
+  {
+    name: 'status',
+    label: '状态',
+    component: (
+      <Select
+        allowClear
+        options={[
+          { value: 'enabled', label: '启用' },
+          { value: 'disabled', label: '停用' },
+        ]}
+      />
+    ),
+  },
+];
+
+const columns: ListPageTableColumn<User>[] = [
+  { title: '姓名', dataIndex: 'name', key: 'name', component: 'text' },
+  { title: '地址', dataIndex: 'address', key: 'address', ellipsis: true },
+];
+
+const request = async (
+  params: { current?: number; pageSize?: number },
+  filters: UserFilters,
+): Promise<PaginationData<User>> => {
+  const { current = 1, pageSize = 10 } = params || {};
+  const all: User[] = Array.from({ length: 100 }).map((_, i) => ({
+    id: i + 1,
+    name: `Edward ${i + 1}`,
+    address: `Address ${i + 1}`,
+    active: i % 2 === 0,
+  }));
+  let list = all.filter(
+    (r) => !filters?.name || r.name.includes(filters.name!),
+  );
+  const skip = (current - 1) * pageSize;
+  return {
+    list: list.slice(skip, skip + pageSize),
+    total: list.length,
+    current,
+    pageSize,
+  };
+};
+
+export default function Page() {
+  return (
+    <ListPage
+      storageKey="demo-listpage"
+      initialValues={{ currentPage: 1, pageSize: 10 }}
+      request={request}
+      header={{
+        title: '用户列表',
+        extra: (ctx: ListPageContext) => (
+          <Space>
+            <Button onClick={() => ctx.refreshTable()}>刷新</Button>
+          </Space>
+        ),
+      }}
+      filter={{ options: filters }}
+      table={{ columns, tableProps: { rowKey: 'id' } }}
+    />
+  );
+}
+```
+
+## 14. 生成检查清单（AI 必须自检）
+
+- `storageKey` 唯一且语义化（如 `LISTPAGE_{FEATURE}`）。
+- `initialValues` 首次挂载设置分页与 `filterValues`（如需）。
+- `request(params, filters)` 返回 `PaginationData<T>`，失败返回空结构。
+- `filter.options` 定义完整，异步选择遵循返回结构；日期区间用 `daterange` 并在请求中展开。
+- `table.columns` 使用原子组件或 `render`；关键列固定、宽度合理、开启 `ellipsis`。
+- 设置 `tableProps.rowKey` 与分页/滚动；选择态按需开启 `rowSelectionType` 与 `rowTitleKey`。
+- 页面级动作在 `header.extra`；表格级动作在 `table.extra`；浮层通过 `floats` 管理。
+- 成功后 `message.success` 与 `ctx.refreshTable()`；危险操作二次确认。
+
+本规范自发布之日起执行，后续将根据使用反馈迭代完善。