@zat-design/sisyphus-scene 1.0.0

package/skills/sisyphus-scene-legacy/SKILL.md

@@ -0,0 +1,614 @@
+---
+name: sisyphus-scene-legacy
+description: 基于旧版 @zat-design/sisyphus-react v3 与 antd4 规则生成查询列表和新增/编辑抽屉页面。仅当目标项目明确使用 v3 或 antd4，或用户明确要求兼容旧规则时触发；不得用于 Sisyphus 4 或 antd 6 项目。
+---
+
+# sisyphus-query-page
+
+生成基于 `@zat-design/sisyphus-react` 的标准查询列表页面，包含完整四层文件结构。
+
+## 触发条件
+
+用户提供以下任意组合时触发：
+- 查询/搜索字段描述
+- 表格列描述
+- 抽屉/弹框表单字段描述
+- 增删改查接口 URL
+
+## 输入收集
+
+触发后，首先从用户描述中提取以下信息。缺少必要项时主动追问，可选项缺失则使用默认值：
+
+### 必要项
+1. **页面名称**（中文 + 英文，用于文件命名和注释）
+2. **查询字段**：字段名、label、类型
+3. **表格列**：字段名、label、渲染方式
+4. **操作列按钮**：按钮文案、对应 handler 名、动作描述
+5. **主接口**：list / add / update 的 URL 和请求方法
+
+### 可选项
+6. **抽屉表单字段**：字段名、label、类型、必填、联动规则（缺省时沿用查询字段生成基础表单）
+7. **是否分组**（ProCollapse）：默认不分组；用户说"分组"或"分 XX 区域"时启用
+8. **字典映射字段**：需要用接口映射显示名的字段（如 teamId → teamName）
+9. **数据转换**：提交/回显时需要特殊处理的字段（如数组↔字符串、日期格式）
+10. **额外操作**：除修改外的其他操作（如重置密码、删除、查看详情）
+
+---
+
+## 生成前必须做
+
+**检查 package.json 确认版本：**
+
+| 特征 | v3 | v4 |
+|------|----|----|
+| `@zat-design/sisyphus-react` | `^3.x` | `^4.x` |
+| antd | `antd4` | `antd` |
+| 列类型 | `ProColumnProps` / `ProTableColumn` | `ProFormColumnType` / `ProTableColumnType` |
+| 日期 | `moment` | `dayjs` |
+
+找不到 package.json 则询问用户版本，默认给 v3（当前项目主要版本）。
+
+---
+
+## 文件结构
+
+```
+PageName/
+├── index.tsx          # 页面容器
+├── index.less         # 样式
+├── propsType.ts       # 类型定义
+├── config/
+│   └── index.tsx      # 纯配置：查询列、表格列、表单列
+├── services/
+│   └── index.ts       # API 调用
+└── utils/
+    └── index.ts       # 数据转换（仅有特殊转换时生成）
+```
+
+---
+
+## index.tsx 规范
+
+### 区块顺序（严格按此顺序，用注释分隔）
+
+```
+1. 导入语句
+2. Props 和基础 Hooks（form 实例等）
+3. 状态和 Refs
+4. 配置和计算值（useMemo，非必要不用）
+5. 事件处理函数
+6. API 和 WebSocket（useAntdTable、useRequest）
+7. 所有 useEffect 集中放置
+8. 返回 JSX
+```
+
+### 状态定义规范
+
+**多个状态必须合并为一个 `useSetState`，并用 interface 声明类型：**
+
+```tsx
+interface PageState {
+  modalVisible: boolean;
+  modalMode: 'add' | 'edit';
+  currentRecord: XxxRecord | null;
+  // 有字典映射时加：
+  // dictMaps: { teamIdMap: Record<string, string> };
+}
+
+const [{ modalVisible, modalMode, currentRecord }, setState] = useSetState<PageState>({
+  modalVisible: false,
+  modalMode: 'add',
+  currentRecord: null,
+});
+```
+
+### useMemo / useCallback 使用原则
+
+- **非必要不用**。不要为了"看起来规范"而滥用
+- `getFormColumns()` 无依赖，可用 `useMemo(() => getFormColumns(), [])` 避免每次重算
+- `getTableColumns(handler1, handler2)` 依赖 handler 函数，**不要加 useMemo**（handler 每次渲染都是新引用，useMemo 无效且误导）
+- `getModalFormColumns(currentRecord, form)` 依赖运行时数据，**不加 useMemo**，直接调用
+
+### useEffect 依赖项规范
+
+- **禁止把函数、form 实例放入依赖数组**
+- 正确写法：`useEffect(() => { ... }, [modalVisible, modalMode, currentRecord])`
+- 错误写法：`useEffect(() => { ... }, [modalVisible, modalForm, refresh])`
+
+### 完整示例
+
+```tsx
+import React, { useEffect } from 'react';
+import { Button, message } from 'antd4';
+import { useRequest, useSetState } from 'ahooks';
+import { ProForm, ProTable, ProDrawerForm } from '@zat-design/sisyphus-react';
+import { getFormColumns, getTableColumns, getModalFormColumns } from './config';
+import * as services from './services';
+import type { XxxRecord } from './propsType';
+
+const { useAntdTable } = ProTable;
+
+interface PageState {
+  modalVisible: boolean;
+  modalMode: 'add' | 'edit';
+  currentRecord: XxxRecord | null;
+}
+
+const XxxPage: React.FC = () => {
+  // ========== Props 和基础 Hooks ==========
+  const [searchForm] = ProForm.useForm();
+  const [modalForm] = ProForm.useForm();
+
+  // ========== 状态和 Refs ==========
+  const [{ modalVisible, modalMode, currentRecord }, setState] = useSetState<PageState>({
+    modalVisible: false,
+    modalMode: 'add',
+    currentRecord: null,
+  });
+
+  // ========== 配置和计算值 ==========
+  const formColumns = getFormColumns();
+  // getTableColumns 依赖 handler，不加 useMemo
+  const tableColumns = getTableColumns(handleEdit, handleXxx);
+  const modalFormColumns = getModalFormColumns(currentRecord, modalForm);
+
+  // ========== 事件处理函数 ==========
+  const handleAdd = () => setState({ currentRecord: null, modalMode: 'add', modalVisible: true });
+
+  const handleEdit = (record: XxxRecord) =>
+    setState({ currentRecord: record, modalMode: 'edit', modalVisible: true });
+
+  const handleModalCancel = () => {
+    setState({ modalVisible: false });
+    modalForm.resetFields();
+  };
+
+  const handleModalOk = async () => {
+    try {
+      const values = await modalForm.validateFields();
+      if (modalMode === 'add') {
+        const res = await services.addXxx(values);
+        if (res.data.status === 200) {
+          message.success('新增成功');
+          setState({ modalVisible: false });
+          modalForm.resetFields();
+          refresh();
+        }
+      } else {
+        const res = await services.updateXxx({ ...values, id: currentRecord!.id });
+        if (res.data.status === 200) {
+          message.success('修改成功');
+          setState({ modalVisible: false });
+          modalForm.resetFields();
+          refresh();
+        }
+      }
+    } catch (error: any) {
+      if (error?.errorFields) return; // 表单校验错误
+      console.error('提交失败:', error);
+    }
+  };
+
+  // ========== API 和 WebSocket ==========
+  const { loading, tableProps, refresh } = useAntdTable(
+    async ({ pageNum, pageSize }) => {
+      const formValues = searchForm.getFieldsValue();
+      const res = await services.getXxxList({ ...formValues, pageNum, pageSize });
+      return {
+        data: {
+          list: res.data.data.list || [],
+          total: res.data.data.total || 0,
+        },
+      };
+    },
+    { form: searchForm },
+  );
+
+  // 字典加载（有字典映射时）
+  // useRequest(services.getXxxOptions, {
+  //   onSuccess: (res) => {
+  //     if (res?.data?.status === 200) {
+  //       const map: Record<string, string> = {};
+  //       res.data.data.forEach((v: any) => { map[v.id] = v.xxxName; });
+  //       setState((prev) => ({ dictMaps: { ...prev.dictMaps, xxxMap: map } }));
+  //     }
+  //   },
+  // });
+
+  // ========== 所有 useEffect 集中放置 ==========
+  useEffect(() => {
+    if (modalVisible && modalMode === 'edit' && currentRecord) {
+      modalForm.setFieldsValue(currentRecord);
+    } else if (modalVisible && modalMode === 'add') {
+      modalForm.resetFields();
+    }
+  }, [modalVisible, modalMode, currentRecord]); // ⚠️ 不加 modalForm（函数引用）
+
+  // ========== 返回 JSX ==========
+  return (
+    <div className="pro-search-container">
+      <ProForm
+        form={searchForm}
+        columns={formColumns}
+        onFinish={() => refresh()}
+        onCancel={() => { searchForm.resetFields(); refresh(); }}
+      />
+      <div style={{ margin: '0 0 12px' }}>
+        <Button type="primary" onClick={handleAdd}>新增</Button>
+      </div>
+      <ProTable
+        {...tableProps}
+        rowKey="id"
+        columns={tableColumns}
+        loading={loading}
+        scroll={{ x: 'max-content' }}
+      />
+      <ProDrawerForm
+        title={modalMode === 'add' ? '新增XXX' : '修改XXX'}
+        open={modalVisible}
+        onOk={handleModalOk}
+        onCancel={handleModalCancel}
+        width="1200"
+      >
+        <ProForm form={modalForm} columns={modalFormColumns} footer={false} />
+      </ProDrawerForm>
+    </div>
+  );
+};
+
+export default XxxPage;
+```
+
+---
+
+## config/index.tsx 规范
+
+**原则：config 是纯配置，不含业务状态，动态数据通过参数注入。**
+
+### 查询表单 `getFormColumns()`
+
+```tsx
+export const getFormColumns = (): ProFormColumnType[] => [
+  { type: 'Input', label: '工号', name: 'query_no' },
+
+  // ProEnum：枚举下拉，allowClear 必加（查询表单允许清空）
+  { type: 'ProEnum', label: '状态', name: 'onDuty', fieldProps: { code: 'onDuty', allowClear: true } },
+
+  // Select/Radio 静态选项：用 dataSource（不是 options）
+  {
+    type: 'Select',
+    label: '类型',
+    name: 'type',
+    fieldProps: { dataSource: [{ label: '启用', value: 'Y' }, { label: '停用', value: 'N' }], allowClear: true },
+  },
+
+  // ProSelect：接口数据下拉
+  {
+    type: 'ProSelect',
+    label: '工作组',
+    name: 'teamId',
+    fieldProps: {
+      allowClear: true,
+      fieldNames: { label: 'teamName', value: 'id' },
+      useRequest: { service: getTeamOptions },
+      transformResponse: (res: any) => res?.data?.status === 200 ? res.data.data || [] : [],
+    },
+  },
+];
+```
+
+### 表格列 `getTableColumns(...handlers)`
+
+**操作列绝对不能放在 config 里。** config 只导出 `baseColumns`（数据列），操作列在 `index.tsx` 里组装：
+
+```tsx
+// config/index.tsx — 只有数据列，无操作列
+export const getBaseColumns = (): ProTableColumnType[] => [
+  { title: '名称', dataIndex: 'name' },
+  { title: '状态', dataIndex: 'status', valueType: 'enumName', code: 'status' },
+  { title: '更新时间', dataIndex: 'gmtModified', valueType: 'dateTime' },
+];
+
+// index.tsx — 在离 ProTable 最近的地方组装操作列
+const getTableColumns = (): ProTableColumnType[] => {
+  const baseColumns = getBaseColumns();
+  return [
+    ...baseColumns,
+    {
+      title: '操作',
+      key: 'action',
+      fixed: 'right',
+      width: 150,
+      render: (_: any, record: XxxRecord) => (
+        <Space>
+          <Button type="link" onClick={() => handleEdit(record)}>编辑</Button>
+          {record.enable === 'N' && (
+            <Button type="link" danger onClick={() => handleDelete(record)}>删除</Button>
+          )}
+        </Space>
+      ),
+    },
+  ];
+};
+
+// JSX 调用
+<ProTable {...tableProps} rowKey="id" columns={getTableColumns()} scroll={{ x: 'max-content' }} />
+```
+
+操作列按钮如果逻辑复杂，可以提取为 `render` 辅助函数放在 `getTableColumns` 上方：
+
+```tsx
+const renderStatusAction = (record: XxxRecord) => {
+  if (record.status === 'active') return <Button type="link">停用</Button>;
+  return <Button type="link">启用</Button>;
+};
+
+const getTableColumns = () => [
+  ...getBaseColumns(),
+  {
+    title: '操作',
+    key: 'action',
+    fixed: 'right',
+    width: 150,
+    render: (_: any, record: XxxRecord) => (
+      <Space>
+        <Button type="link" onClick={() => handleEdit(record)}>编辑</Button>
+        {renderStatusAction(record)}
+      </Space>
+    ),
+  },
+];
+```
+
+### 抽屉表单 `getModalFormColumns(currentRecord?, form?)`
+
+#### 默认模式（平铺，字段少时使用）
+
+```tsx
+export const getModalFormColumns = (currentRecord?: XxxRecord | null, form?: any): ProFormColumnType[] => [
+  { type: 'Input', label: '名称', name: 'name', required: true },
+
+  // ProSelect 多选
+  {
+    type: 'ProSelect',
+    label: '角色',
+    name: 'roleId',
+    required: true,
+    fieldProps: {
+      mode: 'multiple',
+      fieldNames: { label: 'roleName', value: 'id' },
+      useRequest: { service: getRoleOptions },
+      transformResponse: (res: any) => res?.data?.status === 200 ? res.data.data || [] : [],
+    },
+  },
+
+  // 条件显示
+  {
+    type: 'DatePicker',
+    label: '离职日期',
+    name: 'leaveDate',
+    valueType: 'date',
+    show: (values: any) => values?.onDuty === 2,
+  },
+
+  // 动态必填
+  {
+    type: 'Input',
+    label: '某字段',
+    name: 'xxx',
+    required: (values: any) => !!values.yyy,
+  },
+
+  // 联动 fieldProps（选项依赖另一字段）
+  {
+    type: 'ProSelect',
+    label: '上级',
+    name: 'leaderId',
+    show: (values: any) => !!values.dutieId,
+    fieldProps: (values: any) => ({
+      fieldNames: { label: 'name', value: 'id' },
+      useRequest: {
+        service: () => getLeaderList(values.dutieId),
+        options: { ready: !!values.dutieId, refreshDeps: [values.dutieId] },
+      },
+      transformResponse: (res: any) => res?.data?.status === 200 ? res.data.data || [] : [],
+    }),
+  },
+];
+```
+
+#### 分组模式（用户明确要求时）
+
+```tsx
+export const getModalFormColumns = (currentRecord?: XxxRecord | null, form?: any): ProFormColumnType[] => [
+  {
+    type: 'ProCollapse',
+    fieldProps: {
+      title: '基本信息',
+      level: '2',
+      children: [
+        { type: 'Input', label: '姓名', name: 'name', required: true },
+        // ...
+      ],
+    },
+  },
+  {
+    type: 'ProCollapse',
+    fieldProps: {
+      title: '服务范围',
+      level: '2',
+      children: [
+        { type: 'Input', label: '软电账户', name: 'callNo', required: true },
+      ],
+    },
+  },
+];
+```
+
+---
+
+## services/index.ts 规范
+
+```ts
+import axios from '../../../../utils/intercept'; // 路径按项目层级调整
+
+export const getXxxList = (params: any) =>
+  axios({ method: 'post', url: `/xxx/list/${params.pageSize}/${params.pageNum}`, data: params });
+
+export const addXxx = (data: any) =>
+  axios({ method: 'post', url: '/xxx/add', data });
+
+export const updateXxx = (data: any) =>
+  axios({ method: 'post', url: '/xxx/update', data });
+
+// 字典接口（有字典映射时）
+// export const getXxxOptions = () =>
+//   axios({ method: 'get', url: '/xxx/options' });
+```
+
+---
+
+## propsType.ts 规范
+
+```ts
+export interface XxxRecord {
+  id: number;
+  name: string;
+  status?: number | string;
+  gmtModified?: string;
+  [key: string]: any;
+}
+
+export interface XxxFormValues {
+  name: string;
+  status: number | string;
+  // ... 按实际字段补充
+}
+```
+
+---
+
+## utils/index.ts 规范
+
+**仅在有特殊转换时生成。无转换需求则不创建此文件。**
+
+常见需要转换的场景：
+- 多选数组 → 逗号分隔字符串（提交前）/ 逗号字符串 → 数组（回显）
+- `depId` 数字 → `[depId]` 数组（ProTree/ProCascader 回显）
+- 日期 moment/dayjs → 格式化字符串（提交前）
+
+```ts
+// 提交前转换（按实际字段取消注释）
+export const transformFormData = (values: any): any => {
+  const data = { ...values };
+  // if (Array.isArray(data.roleId)) data.roleId = data.roleId.join(',');
+  // if (data.entryDate) data.entryDate = data.entryDate.format('YYYY-MM-DD');
+  return data;
+};
+
+// 回显时转换（按实际字段取消注释）
+export const transformRecordToFormValues = (record: any): any => {
+  const values = { ...record };
+  // if (typeof values.roleIds === 'string') {
+  //   values.roleId = values.roleIds.split(',').map(Number).filter(Boolean);
+  // }
+  // if (values.depId && typeof values.depId === 'number') {
+  //   values.depId = [values.depId];
+  // }
+  return values;
+};
+```
+
+---
+
+## 强制规范检查清单
+
+生成代码时逐条核对：
+
+### 状态
+- [ ] 多个状态用一个 `useSetState<PageState>`，不拆成多个 `useState`
+- [ ] PageState 用 interface 声明，不用内联类型
+
+### Hooks 使用
+- [ ] `useMemo` 仅用于无外部依赖的纯配置（如 `getFormColumns()`）
+- [ ] `getTableColumns`（依赖 handler）不加 `useMemo`
+- [ ] `getModalFormColumns`（依赖运行时数据）不加 `useMemo`
+- [ ] `useEffect` 依赖数组不含函数、form 实例
+
+### Placeholder
+- [ ] **禁止** `fieldProps: { placeholder: '请输入' }` 或 `placeholder: '请选择'`（组件自动添加）
+- [ ] 仅特殊 placeholder 才手动指定（如 `placeholder: '自动获取'`）
+- [ ] 如 fieldProps 只有 placeholder 且为默认值，移除整个 fieldProps
+
+### 区块顺序
+- [ ] 导入 → Props/Hooks → 状态 → 配置 → 事件处理 → API → useEffect → JSX
+- [ ] 所有 `useEffect` 集中在 return 之前，不分散
+
+### Config 纯净性
+- [ ] config 文件不含 `useState`/`useRequest`/`useEffect`
+- [ ] 运行时数据（dictMaps、form、currentRecord）通过参数传入
+
+---
+
+## 字段类型速查
+
+| 场景 | sisyphus type | 关键 fieldProps |
+|------|--------------|----------------|
+| 普通文本输入 | `Input` | `maxLength` |
+| 数字输入 | `InputNumber` | `min`, `max`, `precision` |
+| 静态选项下拉 | `Select` / `Radio` | `dataSource: [{label, value}]`（**不是 options**） |
+| 枚举/字典下拉 | `ProEnum` | `code`, `allowClear`, `mode: 'multiple'` |
+| 接口数据下拉 | `ProSelect` | `useRequest.service`, `transformResponse`, `fieldNames`, `mode` |
+| 树形选择 | `ProTree` | `mode: 'treeSelect'`, `useRequest`, `transformResponse`, `onFieldChange` |
+| 日期 | `DatePicker` | `valueType: 'date'` 或 `'dateTime'` |
+| 日期范围 | `RangePicker` | `valueType: 'date'` |
+| 分组折叠 | `ProCollapse` | `title`, `level: '2'`, `children: [...]` |
+| 文件上传 | `ProUpload` | 见 sisyphus-assistant |
+
+---
+
+## 联动规则速查
+
+| 需求 | 写法 |
+|------|------|
+| 条件显示字段 | `show: (values) => !!values.xxx` |
+| 动态必填 | `required: (values) => values.xxx === 'Y'` |
+| 选项依赖另一字段 | `fieldProps: (values) => ({ useRequest: { service: () => getXxx(values.dep), options: { ready: !!values.dep, refreshDeps: [values.dep] } } })` |
+| 字段变化时联动 | `fieldProps: { onFieldChange: (value, _, { form }) => form.setFieldValue('xxx', undefined) }` |
+
+---
+
+## 生成流程
+
+1. 检查 `package.json` 确认 sisyphus 版本
+2. 解析用户输入，提取字段/接口/分组需求
+3. 追问缺失的必要项
+4. 按顺序生成：
+   - `services/index.ts`（config 需要 import，先生成）
+   - `propsType.ts`
+   - `config/index.tsx`
+   - `index.tsx`
+   - `utils/index.ts`（仅有转换时）
+   - `index.less`（仅含 `.pro-search-container {}`）
+5. 生成后说明需要用户调整的地方（axios 相对路径、枚举 code 值、字典接口返回结构）
+
+---
+
+## 示例
+
+**用户输入：**
+```
+页面：角色管理（RolePage）
+查询：角色名(roleName:Input), 状态(status:ProEnum/code=status)
+表格：角色名(roleName), 状态(status:enumName/code=status), 更新时间(gmtModified:dateTime), 操作[修改]
+抽屉表单：角色名(roleName:Input*), 状态(status:ProEnum/code=status*)
+接口：list=POST /sys/role/list, add=POST /sys/role/add, update=POST /sys/role/update
+```
+
+**生成结果：**
+- 无 ProCollapse（字段少，默认平铺）
+- 无 utils（无特殊转换）
+- 无字典映射（状态用 enumName 直接渲染）
+- PageState 含 `modalVisible`、`modalMode`、`currentRecord`
+- `getFormColumns()` 不加 useMemo（直接调用即可）
+- `getTableColumns(handleEdit)` 不加 useMemo

package/skills/sisyphus-scene-legacy/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Sisyphus 旧版业务页面"
+  short_description: "仅为 v3 与 antd4 项目生成兼容页面"
+  default_prompt: "Use $sisyphus-scene-legacy only for projects that explicitly use Sisyphus v3 or antd4."
+
+policy:
+  allow_implicit_invocation: false