auto-gen-crud 0.1.0

package/API.md

@@ -0,0 +1,130 @@
+# auto-gen-crud API
+
+## createAutoCrud
+
+```ts
+createAutoCrud(options?: AutoCrudInstallOptions)
+```
+
+用于初始化全局配置。UI 只在这里配置一次。
+
+### AutoCrudInstallOptions
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `ui` | `"element-plus" \| "naive" \| "ant-design-vue"` | `"element-plus"` | 选择当前项目使用的 UI。 |
+| `adapter` | `CrudUIAdapter` | - | 高级自定义 Adapter，优先级高于 `ui`。 |
+| `request` | `CrudRequestHandler` | - | 用户注入请求函数。 |
+| `decode` | `CrudDecodeHandler` | - | 敏感信息解密函数。 |
+| `decodeLog` | `CrudDecodeLogHandler` | - | 敏感信息查看日志函数。 |
+| `sm4Key` | `string` | - | 默认 SM4 密钥。 |
+
+## useSearchForm
+
+```ts
+const searchForm = useSearchForm(options)
+```
+
+搜索表单状态 hook。它只管理查询条件，不直接请求列表。
+
+### 常用字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `columns` | 搜索字段配置。 |
+| `data` | 初始搜索数据。 |
+| `onSubmit` | 搜索提交回调。 |
+| `onReset` | 搜索重置回调。 |
+| `addButton` | 是否显示默认新增按钮。 |
+| `addButtonText` | 默认新增按钮文案。 |
+
+## useTable
+
+```ts
+const table = useTable(options)
+```
+
+表格状态 hook。它负责数据、分页、loading、tabs 和业务查询函数。
+
+### getDataList
+
+```ts
+async function getDataList(context) {
+  const { pagination, searchData, tabsValue } = context;
+  return {
+    data: [],
+    total: 0,
+  };
+}
+```
+
+设计原因：每个项目接口分页字段和返回结构都不同，所以新包不写死请求逻辑。
+兼容旧写法：你仍然可以在 `getDataList` 内部直接修改 `table.data` 和 `table.pagination.total`。
+
+## useModalForm
+
+```ts
+const modalForm = useModalForm(options)
+```
+
+弹窗表单状态 hook。它管理新增、编辑、查看三种模式。
+
+### 暴露方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `openAdd(data?)` | 打开新增弹窗，并根据 columns 重建默认数据。 |
+| `openEdit(row)` | 打开编辑弹窗，深拷贝行数据。 |
+| `openView(row)` | 打开查看弹窗，深拷贝行数据。 |
+| `close()` | 关闭弹窗，并调用用户传入的关闭回调。 |
+| `setFormData(prop, value)` | 按字段路径设置表单值。 |
+
+## CrudFormItem
+
+表单字段 schema。
+
+| 字段 | 说明 |
+| --- | --- |
+| `label` | 字段标签。 |
+| `prop` | 字段路径，支持 `user.name`。 |
+| `component` | 推荐字段，表示中立组件类型。 |
+| `valueKey` | 兼容旧字段。 |
+| `value` | 初始值。 |
+| `options` | 选项。 |
+| `required` | 是否必填。 |
+| `rules` | 自定义规则。 |
+| `show` | 动态显隐。 |
+| `disabled` | 动态禁用。 |
+| `props` | 当前 UI 控件透传属性。 |
+| `render` | 自定义渲染。 |
+
+## CrudTableColumn
+
+表格列 schema。
+
+| 字段 | 说明 |
+| --- | --- |
+| `title` | 表头。 |
+| `field` | 推荐字段，字段路径。 |
+| `key` | 兼容旧字段。 |
+| `render` | 自定义单元格。 |
+| `actions` | 操作按钮。 |
+| `buttons` | 兼容旧字段。 |
+| `copy` | 复制展示。 |
+| `decode` | 敏感信息展示。 |
+| `image` | 图片展示。 |
+| `dateTime` | 日期格式化。 |
+
+## Adapter 学习重点
+
+Adapter 的职责不是写业务，而是映射 UI 差异：
+
+- 表单组件名称。
+- 表单 v-model 字段。
+- 表单校验方法。
+- 表格 columns 结构。
+- 分页字段。
+- 弹窗显隐字段。
+- 按钮、图片、消息提示。
+
+因此 hooks、core types、业务 schema 都不需要依赖具体 UI 库。

package/README.md

@@ -0,0 +1,234 @@
+# auto-gen-crud
+
+`auto-gen-crud` 是一套面向 Vue 3 的配置驱动 CRUD 组件、OpenAPI 页面生成器和 AI agent 辅助工具。
+
+它的核心目标是：页面只写 schema 和业务函数，组件负责渲染搜索表单、表格和弹窗表单。
+
+## 设计特点
+
+- 默认使用 Element Plus。
+- 初始化时可切换为 Naive UI 或 Ant Design Vue。
+- UI 只配置一次，业务字段里不写 `uiProps.naive`、`uiProps.elementPlus`、`uiProps.antdv`。
+- hooks 不依赖任何 UI 库。
+- core 类型不出现具体 UI 类型。
+- 内置复制、解密展示、请求适配、SM4 工具，不依赖旧 `@libs/request`、`@libs/shared-components`、`@libs/utils`。
+
+## 安装和初始化
+
+默认 Element Plus：
+
+```ts
+import { createAutoCrud } from "auto-gen-crud";
+import "auto-gen-crud/style.css";
+
+app.use(createAutoCrud());
+```
+
+切换 Naive UI：
+
+```ts
+app.use(createAutoCrud({ ui: "naive" }));
+```
+
+切换 Ant Design Vue：
+
+```ts
+app.use(createAutoCrud({ ui: "ant-design-vue" }));
+```
+
+如果需要敏感信息解密：
+
+```ts
+app.use(
+  createAutoCrud({
+    decode: async value => {
+      return String(value);
+    },
+    decodeLog: async (value, row) => {
+      console.log("记录查看日志", value, row);
+    },
+  })
+);
+```
+
+## 最小示例
+
+```vue
+<script setup lang="ts">
+import { AutoCrud, useModalForm, useSearchForm, useTable } from "auto-gen-crud";
+
+const searchForm = useSearchForm({
+  columns: [
+    { label: "名称", prop: "name", component: "input" },
+    {
+      label: "状态",
+      prop: "status",
+      component: "select",
+      options: [
+        { label: "启用", value: 1 },
+        { label: "禁用", value: 0 },
+      ],
+    },
+  ],
+});
+
+const modalForm = useModalForm({
+  columns: [
+    { label: "名称", prop: "name", component: "input", required: true },
+    { label: "状态", prop: "status", component: "switch" },
+  ],
+  async onSubmit(data, mode) {
+    console.log("提交", mode, data);
+    modalForm.close();
+    await table.load(searchForm.data);
+  },
+});
+
+const table = useTable({
+  columns: [
+    { title: "名称", field: "name", copy: true },
+    { title: "创建时间", field: "createdAt", dateTime: true },
+    {
+      title: "操作",
+      actions: [
+        { key: "edit", label: "编辑", type: "primary", onClick: row => modalForm.openEdit(row) },
+        { key: "delete", label: "删除", type: "danger", confirm: true, onClick: row => console.log(row) },
+      ],
+    },
+  ],
+  async getDataList({ pagination, searchData }) {
+    console.log("查询", pagination, searchData);
+    table.data = [];
+    if (table.pagination) table.pagination.total = 0;
+  },
+});
+</script>
+
+<template>
+  <AutoCrud
+    title="用户"
+    :search-form-config="searchForm"
+    :table-config="table"
+    :modal-form-config="modalForm"
+  />
+</template>
+```
+
+## 本地 Demo
+
+```bash
+npm run dev
+```
+
+打开 `http://127.0.0.1:5173/` 可查看本地 demo。它使用原生轻量 adapter 测试组件逻辑，不额外依赖具体 UI 库。
+Demo 内置轻量 hash 路由：
+
+- `http://127.0.0.1:5173/#/crud`：CRUD 页面。
+- `http://127.0.0.1:5173/#/guide`：说明页面。
+
+```bash
+npm run demo:smoke
+```
+
+可运行 demo 数据流冒烟测试，覆盖搜索条件、`useTable` 返回值接收和弹窗编辑数据隔离。
+
+## 独立 Vue3 消费示例
+
+`examples/vue3-consumer` 是一个独立 Vue3 项目，用本地 tarball 安装 `auto-gen-crud`，可切换 UI adapter 验证 npm 包入口、类型声明、样式导出和路由页面渲染。
+
+```bash
+npm run build
+npm pack --pack-destination /private/tmp
+cd examples/vue3-consumer
+npm install --legacy-peer-deps --offline --cache /private/tmp/auto-gen-crud-consumer-npm-cache
+npm run dev
+```
+
+打开实际终端输出的 Vite 地址，访问：
+
+- `#/crud`：CRUD 页面。
+- `#/guide`：说明页面。
+
+## AI MCP
+
+项目内置一个本地 stdio MCP server，供 AI 查询 `auto-gen-crud` 文档、API、schema 字段，并生成 CRUD 页面代码。
+
+启动命令：
+
+```bash
+npm run mcp
+```
+
+发布到 npm 后，也可以直接使用：
+
+```bash
+npx auto-gen-crud-mcp
+```
+
+MCP 客户端配置示例：
+
+```json
+{
+  "mcpServers": {
+    "auto-gen-crud": {
+      "command": "node",
+      "args": ["node_modules/auto-gen-crud/mcp/auto-gen-crud-mcp.mjs"]
+    }
+  }
+}
+```
+
+工具列表：
+
+- `vac_get_overview`：查询安装、示例、adapter、迁移说明。
+- `vac_get_api_reference`：按 API 名称查询文档片段。
+- `vac_get_agent_guide`：查询 VSCode AI agent 使用规范、工程边界和 prompt 建议。
+- `vac_get_generator_reference`：查询 OpenAPI 生成器参数、输出目录和 requestAdapter 用法。
+- `vac_list_schema_fields`：列出表单、表格、安装配置和组件类型字段。
+- `vac_generate_crud_page`：根据字段生成 Vue3 CRUD 页面示例。
+- `vac_generate_install_snippet`：生成指定 UI 的安装初始化代码。
+- `vac_search_docs`：搜索 README、API 和核心类型文件。
+
+更完整的 agent 接入说明见 `docs/AI_AGENT_GUIDE.md`。包内也提供 `skills/auto-gen-crud-agent/SKILL.md`，可复制到 Codex / 自研 VSCode AI agent 的 skills 目录中使用。
+
+## 为什么要用 Adapter
+
+不同 UI 的同一个能力写法不同：
+
+- Element Plus 表单 v-model 是 `modelValue/onUpdate:modelValue`。
+- Naive UI 表单 v-model 常用 `value/onUpdate:value`。
+- Ant Design Vue 弹窗显示是 `open/onUpdate:open`。
+
+Adapter 把这些差异集中起来，业务 schema 不需要关心。
+
+## 从旧 auto-gen-crud 迁移
+
+旧字段：
+
+```ts
+{ label: "名称", prop: "name", valueKey: "input" }
+```
+
+新字段推荐：
+
+```ts
+{ label: "名称", prop: "name", component: "input" }
+```
+
+旧表格列：
+
+```ts
+{ title: "名称", key: "name", buttons: [] }
+```
+
+新表格列推荐：
+
+```ts
+{ title: "名称", field: "name", actions: [] }
+```
+
+新包仍兼容 `valueKey`、`key`、`buttons`，但文档和新代码推荐使用 `component`、`field`、`actions`。
+
+npm_config_cache=/private/tmp/auto-gen-crud-npm-cache npm pack --pack-destination /private/tmp
+
+ npm install ../../auto-gen-crud-0.1.0.tgz --no-audit --no-fund 

package/dist/adapters/ant-design-vue.d.ts

@@ -0,0 +1,8 @@
+import { CrudUIAdapter } from './types';
+/**
+ * Ant Design Vue Adapter。
+ *
+ * 与 Element Plus 最大差异：Drawer/Modal 使用 `open/onUpdate:open`，
+ * Table 更偏对象 columns + `customRender`，按钮危险态使用 `danger` 布尔值。
+ */
+export declare const antDesignVueAdapter: CrudUIAdapter;

package/dist/adapters/element-plus.d.ts

@@ -0,0 +1,8 @@
+import { CrudUIAdapter } from './types';
+/**
+ * Element Plus Adapter。
+ *
+ * 默认 Adapter：不传 `createAutoCrud({ ui })` 时使用它。
+ * 约定使用者已在业务应用中安装并注册 Element Plus。
+ */
+export declare const elementPlusAdapter: CrudUIAdapter;

package/dist/adapters/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ant-design-vue';
+export * from './element-plus';
+export * from './naive';
+export * from './types';

package/dist/adapters/index.js

@@ -0,0 +1,7 @@
+import { a as t, e as r, b as s } from "../index-Dc-solHn.js";
+export {
+  t as antDesignVueAdapter,
+  r as elementPlusAdapter,
+  s as naiveAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/adapters/naive.d.ts

@@ -0,0 +1,8 @@
+import { CrudUIAdapter } from './types';
+/**
+ * Naive UI Adapter。
+ *
+ * 与 Element Plus 最大差异：多数表单字段使用 `value/onUpdate:value`，
+ * Drawer/Modal 显隐使用 `show/onUpdate:show`，分页总数叫 `itemCount`。
+ */
+export declare const naiveAdapter: CrudUIAdapter;

package/dist/adapters/types.d.ts

@@ -0,0 +1,162 @@
+import { Component, VNodeChild } from 'vue';
+import { CrudButtonSize, CrudButtonType, CrudFormComponent, CrudFormItem, CrudFormLayout, CrudPagination, CrudTableAction, CrudTableColumn, CrudUIName } from '../core/types';
+/** 组件解析结果：可以是全局注册的组件名，也可以是自定义 adapter 返回的组件对象。 */
+export type CrudAdapterComponent = string | Component;
+/**
+ * Adapter 中维护的组件名称映射。
+ *
+ * 本包不静态 import Element Plus、Naive UI、Ant Design Vue，
+ * 因此这里默认返回全局组件名，例如 `ElInput`、`NInput`、`AInput`。
+ */
+export interface CrudAdapterComponents {
+    card: CrudAdapterComponent;
+    form: CrudAdapterComponent;
+    formItem: CrudAdapterComponent;
+    button: CrudAdapterComponent;
+    table: CrudAdapterComponent;
+    tableColumn?: CrudAdapterComponent;
+    pagination: CrudAdapterComponent;
+    drawer: CrudAdapterComponent;
+    /** 部分 UI 的抽屉需要内部内容组件承载 title/footer，例如 Naive UI 的 NDrawerContent。 */
+    drawerContent?: CrudAdapterComponent;
+    modal: CrudAdapterComponent;
+    popconfirm: CrudAdapterComponent;
+    image: CrudAdapterComponent;
+    tooltip?: CrudAdapterComponent;
+    fields: Record<CrudFormComponent, CrudAdapterComponent>;
+    option?: CrudAdapterComponent;
+    radio?: CrudAdapterComponent;
+    checkbox?: CrudAdapterComponent;
+}
+/** 表单字段 v-model 映射结果。 */
+export interface CrudModelBinding {
+    /** 当前 UI 接收值的 prop 名。 */
+    prop: string;
+    /** 当前 UI 更新值的事件名。 */
+    event: string;
+}
+/** 表单 Adapter，集中处理三套 UI 的表单差异。 */
+export interface CrudFormAdapter {
+    /** 获取表单根组件 props。 */
+    getFormProps: (input: {
+        model: Record<string, unknown>;
+        rules: Record<string, unknown>;
+        disabled?: boolean;
+    }) => Record<string, unknown>;
+    /** 获取表单项 props。 */
+    getFormItemProps: (item: CrudFormItem, input: {
+        prop: string;
+        label: string;
+        rules?: unknown[];
+    }) => Record<string, unknown>;
+    /** 获取字段组件 v-model 映射。 */
+    getModelBinding: (component: CrudFormComponent, item: CrudFormItem) => CrudModelBinding;
+    /** 获取字段组件 props。 */
+    getFieldProps: (item: CrudFormItem, input: {
+        value: unknown;
+        placeholder: string;
+        disabled: boolean;
+        options?: unknown[];
+    }) => Record<string, unknown>;
+    /** 获取表单布局样式变量。 */
+    getLayoutStyle: (layout?: CrudFormLayout, formType?: "search" | "modal") => Record<string, string | number>;
+    /** 触发表单校验。 */
+    validate: (formRef: unknown) => Promise<boolean>;
+    /** 清空表单校验。 */
+    clearValidate: (formRef: unknown) => void;
+}
+/** 表格 Adapter，集中处理 columns、分页和事件差异。 */
+export interface CrudTableAdapter {
+    /** 当前 UI 是否优先使用对象 columns 渲染，Naive/Ant Design Vue 为 true，Element Plus 为 false。 */
+    useColumnConfig: boolean;
+    /** 获取表格根组件 props。 */
+    getTableProps: <T extends Record<string, unknown>>(input: {
+        columns: unknown[];
+        data: T[];
+        loading: boolean;
+        rowKey?: string | ((row: T) => string | number);
+        /** 纵向滚动高度，由 DynamicTable 计算后交给各 UI Adapter 映射成真实组件属性。 */
+        scrollY?: number | string;
+        scrollX?: number | string;
+    }) => Record<string, unknown>;
+    /** 获取表格列 props，用于 Element Plus 这类 TableColumn 组件。 */
+    getTableColumnProps: <T extends Record<string, unknown>>(column: CrudTableColumn<T>) => Record<string, unknown>;
+    /** 获取分页组件 props。 */
+    getPaginationProps: (pagination: CrudPagination) => Record<string, unknown>;
+    /** 获取分页事件。 */
+    getPaginationEvents: (handlers: {
+        onPageChange: (page: number) => void;
+        onPageSizeChange: (pageSize: number) => void;
+    }) => Record<string, unknown>;
+}
+/** 弹窗 Adapter，集中处理 drawer/modal 显隐字段差异。 */
+export interface CrudModalAdapter {
+    /** 获取 drawer 或 modal 的组件 props。 */
+    getModalProps: (input: {
+        visible: boolean;
+        title: string;
+        width?: string | number;
+        onUpdateVisible: (visible: boolean) => void;
+    }) => Record<string, unknown>;
+}
+/** 基础渲染 Adapter，用于按钮、确认框、图片等小片段。 */
+export interface CrudRenderAdapter {
+    /** 映射按钮 props。 */
+    getButtonProps: (input: {
+        type?: CrudButtonType;
+        size?: CrudButtonSize;
+        disabled?: boolean;
+    }) => Record<string, unknown>;
+    /** 映射确认框 props。 */
+    getPopconfirmProps: (input: {
+        title: string;
+        confirmText?: string;
+        cancelText?: string;
+        onConfirm: () => void;
+    }) => Record<string, unknown>;
+    /** 映射图片 props。 */
+    getImageProps: (input: {
+        src: string;
+        width: number;
+        height: number;
+        objectFit: string;
+        preview: boolean;
+    }) => Record<string, unknown>;
+    /** 渲染表格对象列时的 custom render 字段名。 */
+    customRenderKey: "render" | "customRender";
+    /** 将中立按钮动作转为当前 UI 友好的类型。 */
+    normalizeActionType: <T>(action: CrudTableAction<T>) => CrudButtonType;
+}
+/** 消息提示 Adapter。 */
+export interface CrudFeedbackAdapter {
+    success: (message: string) => void;
+    warning: (message: string) => void;
+    error: (message: string) => void;
+}
+/**
+ * UI Adapter 总接口。
+ *
+ * 学习重点：
+ * - hooks 不碰 UI。
+ * - 组件只问 adapter 当前 UI 组件叫什么、props 怎么映射、事件叫什么。
+ * - 这样同一份业务 schema 可以在初始化时切换到不同 UI。
+ */
+export interface CrudUIAdapter {
+    name: CrudUIName;
+    components: CrudAdapterComponents;
+    form: CrudFormAdapter;
+    table: CrudTableAdapter;
+    modal: CrudModalAdapter;
+    render: CrudRenderAdapter;
+    feedback: CrudFeedbackAdapter;
+}
+/** Adapter 工厂参数。 */
+export type CrudAdapterFactory = () => CrudUIAdapter;
+/** 表格对象列渲染上下文。 */
+export interface CrudColumnRenderContext<T extends Record<string, unknown>> {
+    row: T;
+    column: CrudTableColumn<T>;
+    index: number;
+    value: unknown;
+}
+export type CrudCellRenderer<T extends Record<string, unknown>> = (context: CrudColumnRenderContext<T>) => VNodeChild;