scaffold-engine 0.1.0

package/tools/lib/renderers/list-page-renderer.cjs

@@ -0,0 +1,371 @@
+function renderAdminListPage(context, helpers) {
+  const patternMode = helpers.getPatternId(context) || 'default';
+  return renderPatternAdminListPage(context, patternMode, helpers);
+}
+
+function renderPatternAdminListPage(context, patternMode, helpers) {
+  const pageResultType = `${context.objectPascal}PageResult`;
+  const filtersType = `${context.objectPascal}Filters`;
+  const searchField = helpers.getPrimarySearchField(context);
+  const filterFields = ((context.ui.list && context.ui.list.filters) || [])
+    .map((fieldName) => context.fields.find((item) => item.name === fieldName))
+    .filter(Boolean);
+  const pendingFiltersInitial = filterFields.map((field) => `    ${field.name}: "",`).join('\n');
+  const filtersInitial = filterFields.map((field) => `    ${field.name}: "",`).join('\n');
+  const loadArgs = filterFields.map((field) => `        filters.${field.name},`).join('\n');
+  const applyFilterAssignments = filterFields
+    .filter((field) => field.name !== searchField)
+    .map((field) => `      ${field.name}: pendingFilters.${field.name},`)
+    .join('\n');
+  const clearFilters = filterFields.map((field) => `      ${field.name}: "",`).join('\n');
+  const columns = renderAdminListColumns(context, helpers);
+  const filterContent = renderAdminFilterContent(context, searchField, helpers);
+  const filterCountFields = filterFields.filter((field) => field.name !== searchField).map((field) => `filters.${field.name}`);
+  const headerIcon = helpers.getAdminHeaderIcon(context);
+  const headerTitle = helpers.getPatternListTitle(context);
+  const primaryActionLabel = helpers.getPatternCreateLabel(context);
+  const searchPlaceholder = helpers.getPatternSearchPlaceholder(context, helpers.getFieldLabel(context, searchField));
+
+  return `import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router";
+import { Eye, Pencil, ${headerIcon} } from "lucide-react";
+import { toast } from "sonner";
+import type { ${context.objectPascal}Vo } from "@scaffold/api/client";
+import { ListReport, type ListReportColumn } from "@/components/admin-ui/list-report";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import {
+  create${context.objectPascal}Api,
+  formatDateTime,
+  getOptionLabel,
+  ${context.fields.some((field) => field.name === 'status') ? `get${context.objectPascal}StatusMeta,\n  ` : ''}${context.fields.filter((field) => field.type === 'enum').map((field) => `${field.name.toUpperCase()}_OPTIONS`).join(',\n  ')}${context.fields.filter((field) => field.type === 'enum').length ? ',\n  ' : ''}type ${pageResultType},
+  type ${filtersType},
+} from "./${context.objectKebab}-ui";
+
+export function ListPage() {
+  const navigate = useNavigate();
+  const ${context.objectCamel}Api = useMemo(() => create${context.objectPascal}Api(), []);
+  const [showFilter, setShowFilter] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [filters, setFilters] = useState<${filtersType}>({
+${filtersInitial}
+  });
+  const [pendingFilters, setPendingFilters] = useState({
+${pendingFiltersInitial}
+  });
+  const [pagination, setPagination] = useState({
+    pageIndex: 0,
+    pageSize: 10,
+  });
+  const [listState, setListState] = useState({
+    rows: [] as ${context.objectPascal}Vo[],
+    total: 0,
+  });
+
+  const load${context.objectPascal}s = useCallback(async () => {
+    setLoading(true);
+    try {
+      const response = await ${context.objectCamel}Api.page(
+        String(pagination.pageIndex + 1),
+        String(pagination.pageSize),
+${loadArgs}
+      ) as ${pageResultType};
+
+      setListState({
+        rows: response.records ?? [],
+        total: response.total ?? 0,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "加载${context.label}列表失败";
+      toast.error(message);
+    } finally {
+      setLoading(false);
+    }
+  }, [${context.objectCamel}Api, pagination.pageIndex, pagination.pageSize, ${filterFields.map((field) => `filters.${field.name}`).join(', ')}]);
+
+  useEffect(() => {
+    void load${context.objectPascal}s();
+  }, [load${context.objectPascal}s]);
+
+  const columns: ListReportColumn<${context.objectPascal}Vo>[] = [
+${helpers.indent(columns, 4)}
+  ];
+
+  const handleApplyFilters = () => {
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+    setFilters((prev) => ({
+      ...prev,
+${applyFilterAssignments || '      ...prev,'}
+    }));
+  };
+
+  const handleClearFilters = () => {
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+    setPendingFilters({
+${clearFilters}
+    });
+    setFilters({
+${clearFilters}
+    });
+  };
+
+  const filterCount = [${filterCountFields.join(', ')}].filter(Boolean).length;
+
+  return (
+    <div className="h-full">
+      <ListReport<${context.objectPascal}Vo>
+        header={{
+          title: "${headerTitle}",
+          subtitle: "${helpers.getPatternListSubtitle(context)}",
+          tag: "${context.domainUpper} MVP",
+          icon: <${headerIcon} className="size-7" />,
+        }}
+        data={listState.rows}
+        columns={columns}
+        totalCount={listState.total}
+        loading={loading}
+        manualPagination={true}
+        primaryAction={{
+          id: "create",
+          label: "${primaryActionLabel}",
+          onClick: () => navigate("/${context.routePath}/create"),
+        }}
+        searchPlaceholder="${searchPlaceholder}"
+        onSearch={(value) => {
+          setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+          setFilters((prev) => ({
+            ...prev,
+            ${searchField}: value.trim(),
+          }));
+        }}
+        showFilter={showFilter}
+        onFilterToggle={() => setShowFilter((prev) => !prev)}
+        filterCount={filterCount}
+        onFilterClear={handleClearFilters}
+        onFilterApply={handleApplyFilters}
+        onRefresh={() => void load${context.objectPascal}s()}
+        pageIndex={pagination.pageIndex}
+        pageSize={pagination.pageSize}
+        onPaginationChange={(pageIndex, pageSize) => {
+          setPagination({ pageIndex, pageSize });
+        }}
+        getRowId={(row) => String(row.id)}
+        onRowClick={(row) => navigate("/${context.routePath}/" + row.id)}
+        filterContent={
+${helpers.indent(filterContent, 10)}
+        }
+      />
+    </div>
+  );
+}
+
+export default ListPage;
+`;
+}
+
+function renderAdminListColumns(context, helpers) {
+  const titleField = helpers.getPrimaryTitleField(context);
+  const codeField = helpers.findFieldByPriority(context, helpers.getPatternFieldPriority(context, 'code'))
+    || helpers.findFieldByPriority(context, ['leadCode', 'customerCode', 'opportunityCode', 'quoteCode', 'contractCode', 'materialCode']);
+  const secondaryField = helpers.findFieldByPriority(context, helpers.getPatternFieldPriority(context, 'secondary'));
+  const ownerField = context.fields.find((field) => field.name === 'ownerName') || secondaryField;
+  const columns = [];
+
+  if (codeField) {
+    columns.push(`{
+      id: "${codeField.name}",
+      header: "${codeField.label || codeField.name}",
+      sortable: true,
+      accessorKey: "${codeField.name}",
+      cell: (row) => (
+        <button
+          type="button"
+          onClick={(event) => {
+            event.stopPropagation();
+            navigate("/${context.routePath}/" + row.id);
+          }}
+          className="text-sm font-medium text-primary hover:underline"
+        >
+          {row.${codeField.name} || "-"}
+        </button>
+      ),
+    }`);
+  }
+
+  const titleMeta = context.fields.find((field) => field.name === titleField);
+  if (titleMeta) {
+    columns.push(`{
+      id: "${titleMeta.name}",
+      header: "${titleMeta.label || titleMeta.name}",
+      sortable: true,
+      accessorKey: "${titleMeta.name}",
+      cell: (row) => (
+        <div>
+          <p className="text-sm font-medium">{row.${titleMeta.name}}</p>
+          <p className="text-xs text-muted-foreground">{${helpers.renderDisplayValue(ownerField || titleMeta, `row.${ownerField ? ownerField.name : titleMeta.name}`, `"${ownerField && ownerField.name === 'ownerName' ? '未分配负责人' : '-'}"` )}}</p>
+        </div>
+      ),
+    }`);
+  }
+
+  for (const fieldName of (context.ui.list.columns || [])) {
+    const field = context.fields.find((item) => item.name === fieldName);
+    if (!field || field.name === codeField?.name || field.name === titleMeta?.name) {
+      continue;
+    }
+    columns.push(renderSimpleListColumn(context, field, helpers));
+  }
+
+  columns.push(`{
+      id: "actions",
+      header: "操作",
+      align: "center",
+      cell: (row) => (
+        <div className="flex justify-center gap-1" onClick={(event) => event.stopPropagation()}>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="size-8 text-muted-foreground hover:bg-primary/10 hover:text-primary"
+            title="查看详情"
+            onClick={() => navigate("/${context.routePath}/" + row.id)}
+          >
+            <Eye className="size-4" />
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="size-8 text-muted-foreground hover:bg-primary/10 hover:text-primary"
+            title="编辑${context.label}"
+            onClick={() => navigate("/${context.routePath}/" + row.id + "/edit")}
+          >
+            <Pencil className="size-4" />
+          </Button>
+        </div>
+      ),
+    }`);
+
+  return columns.join(',\n');
+}
+
+function renderSimpleListColumn(context, field, helpers) {
+  if (field.name === 'createdAt' || field.name === 'updatedAt') {
+    return `{
+      id: "${field.name}",
+      header: "${field.label || (field.name === 'createdAt' ? '创建时间' : '更新时间')}",
+      cell: (row) => (
+        <span className="text-sm text-muted-foreground">{formatDateTime(row.${field.name})}</span>
+      ),
+    }`;
+  }
+  if (field.type === 'enum') {
+    if (field.name === 'status') {
+      return `{
+      id: "${field.name}",
+      header: "${field.label || field.name}",
+      align: "center",
+      accessorKey: "${field.name}",
+      cell: (row) => {
+        const meta = get${context.objectPascal}StatusMeta(row.${field.name});
+        return (
+          <div className="flex justify-center">
+            <span
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-full px-2.5 py-1 text-xs font-medium",
+                meta.badgeClassName
+              )}
+            >
+              <span className={cn("size-1.5 rounded-full", meta.dotClassName)} />
+              {meta.label}
+            </span>
+          </div>
+        );
+      },
+    }`;
+    }
+    return `{
+      id: "${field.name}",
+      header: "${field.label || field.name}",
+      align: "center",
+      cell: (row) => (
+        <span className="rounded-full bg-primary/10 px-2.5 py-1 text-xs font-medium text-primary">
+          {getOptionLabel(${field.name.toUpperCase()}_OPTIONS, row.${field.name})}
+        </span>
+      ),
+    }`;
+  }
+  return `{
+      id: "${field.name}",
+      header: "${field.label || field.name}",
+      cell: (row) => <span className="text-sm text-muted-foreground">{${helpers.renderDisplayValue(field, `row.${field.name}`)}}</span>,
+    }`;
+}
+
+function renderAdminFilterContent(context, searchField, helpers) {
+  const filterFields = ((context.ui.list && context.ui.list.filters) || [])
+    .filter((fieldName) => fieldName !== searchField)
+    .map((fieldName) => context.fields.find((item) => item.name === fieldName))
+    .filter(Boolean);
+  if (filterFields.length === 0) {
+    return `<div className="text-sm text-muted-foreground">当前没有额外筛选项</div>`;
+  }
+  return `<div className="grid gap-4 md:grid-cols-${Math.min(filterFields.length, 3)}">
+${helpers.indent(filterFields.map((field) => renderFilterField(field)).join('\n'), 2)}
+</div>`;
+}
+
+function renderFilterField(field) {
+  if (field.type === 'enum') {
+    return `<div className="space-y-2">
+  <Label className="text-xs text-muted-foreground">${field.label || field.name}</Label>
+  <Select
+    value={pendingFilters.${field.name} || "__all__"}
+    onValueChange={(value) =>
+      setPendingFilters((prev) => ({
+        ...prev,
+        ${field.name}: value === "__all__" ? "" : value,
+      }))
+    }
+  >
+    <SelectTrigger className="w-full">
+      <SelectValue placeholder="全部${field.label || field.name}" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="__all__">全部${field.label || field.name}</SelectItem>
+      {${field.name.toUpperCase()}_OPTIONS.map((item) => (
+        <SelectItem key={item.value} value={item.value}>
+          {item.label}
+        </SelectItem>
+      ))}
+    </SelectContent>
+  </Select>
+</div>`;
+  }
+  return `<div className="space-y-2">
+  <Label className="text-xs text-muted-foreground">${field.label || field.name}</Label>
+  <Input
+    value={pendingFilters.${field.name}}
+    onChange={(event) =>
+      setPendingFilters((prev) => ({
+        ...prev,
+        ${field.name}: event.target.value,
+      }))
+    }
+    placeholder="请输入${field.label || field.name}"
+  />
+</div>`;
+}
+
+module.exports = {
+  renderAdminListPage,
+};

package/tools/lib/runtime-config.cjs

@@ -0,0 +1,154 @@
+const fs = require('fs');
+const path = require('path');
+
+const SCAFFOLD_ROOT = path.resolve(__dirname, '..', '..');
+
+function buildDefaultRuntimeConfig() {
+  return {
+    scaffoldRoot: SCAFFOLD_ROOT,
+    projectRoot: path.resolve(SCAFFOLD_ROOT, '..'),
+    catalogs: {
+      rootDir: path.join(SCAFFOLD_ROOT, 'specs', 'catalogs'),
+      objectCatalog: 'object-catalog.yaml',
+      patternCatalog: 'pattern-catalog.yaml',
+      fieldFragments: 'field-fragments.yaml',
+      objectTemplates: 'object-templates.yaml',
+      objectNameSuggestions: 'object-name-suggestions.yaml',
+      actionTemplates: 'action-templates.yaml',
+      statusTemplates: 'status-templates.yaml',
+      childTemplates: 'child-templates.yaml'
+    },
+    rules: {
+      rootDir: path.join(SCAFFOLD_ROOT, 'specs', 'rules'),
+      businessModelSchema: 'business-model.schema.json',
+      extensionBoundaries: 'extension-boundaries.json',
+      specGovernance: 'spec-governance.json',
+      requirementDraftSchema: 'requirement-draft.schema.json'
+    },
+    drafts: {
+      rootDir: path.join(SCAFFOLD_ROOT, '.sandbox', 'drafts')
+    },
+    generatedSpecs: {
+      rootDir: path.join(SCAFFOLD_ROOT, 'specs', 'projects', 'generated-from-nl')
+    },
+    targets: {
+      adapter: 'scaffold-default',
+      apiSrcDir: path.join(SCAFFOLD_ROOT, 'packages', 'api', 'src'),
+      adminSrcDir: path.join(SCAFFOLD_ROOT, 'packages', 'admin', 'src'),
+      toolCwd: SCAFFOLD_ROOT,
+      pnpmCwd: path.resolve(SCAFFOLD_ROOT, '..'),
+      apiPackageDir: path.join(SCAFFOLD_ROOT, 'packages', 'api')
+    }
+  };
+}
+
+function loadRuntimeConfig(options = {}) {
+  const explicit = options.runtimeConfig || {};
+  const configPath = options.configPath || process.env.SCAFFOLD_RUNTIME_CONFIG || '';
+  const fileConfig = configPath ? readJson(path.resolve(configPath)) : {};
+  const merged = deepMerge(buildDefaultRuntimeConfig(), fileConfig);
+  return normalizeRuntimeConfig(deepMerge(merged, explicit));
+}
+
+function normalizeRuntimeConfig(config) {
+  const scaffoldRoot = path.resolve(config.scaffoldRoot || SCAFFOLD_ROOT);
+  const projectRoot = path.resolve(config.projectRoot || path.resolve(scaffoldRoot, '..'));
+  return {
+    scaffoldRoot,
+    projectRoot,
+    catalogs: normalizeNamedRoot(config.catalogs, path.join(scaffoldRoot, 'specs', 'catalogs')),
+    rules: normalizeNamedRoot(config.rules, path.join(scaffoldRoot, 'specs', 'rules')),
+    drafts: {
+      rootDir: path.resolve(config.drafts?.rootDir || path.join(scaffoldRoot, '.sandbox', 'drafts'))
+    },
+    generatedSpecs: {
+      rootDir: path.resolve(config.generatedSpecs?.rootDir || path.join(scaffoldRoot, 'specs', 'projects', 'generated-from-nl'))
+    },
+    targets: {
+      adapter: config.targets?.adapter || 'scaffold-default',
+      apiSrcDir: path.resolve(config.targets?.apiSrcDir || path.join(scaffoldRoot, 'packages', 'api', 'src')),
+      adminSrcDir: path.resolve(config.targets?.adminSrcDir || path.join(scaffoldRoot, 'packages', 'admin', 'src')),
+      toolCwd: path.resolve(config.targets?.toolCwd || scaffoldRoot),
+      pnpmCwd: path.resolve(config.targets?.pnpmCwd || projectRoot),
+      apiPackageDir: path.resolve(config.targets?.apiPackageDir || path.join(scaffoldRoot, 'packages', 'api'))
+    }
+  };
+}
+
+function normalizeNamedRoot(section = {}, defaultRootDir) {
+  return {
+    ...section,
+    rootDir: path.resolve(section.rootDir || defaultRootDir)
+  };
+}
+
+function resolveCatalogPath(runtimeConfig, key) {
+  return resolveNamedPath(runtimeConfig.catalogs, key);
+}
+
+function resolveRulePath(runtimeConfig, key) {
+  return resolveNamedPath(runtimeConfig.rules, key);
+}
+
+function resolveGeneratedSpecPath(runtimeConfig, fileName) {
+  return path.join(runtimeConfig.generatedSpecs.rootDir, fileName);
+}
+
+function resolveDraftRoot(runtimeConfig) {
+  return runtimeConfig.drafts.rootDir;
+}
+
+function resolveNamedPath(section, key) {
+  const value = section[key];
+  if (!value) {
+    throw new Error(`runtime config 缺少路径项: ${key}`);
+  }
+  return path.resolve(section.rootDir, value);
+}
+
+function deepMerge(base, patch) {
+  if (Array.isArray(patch)) {
+    return patch.map((item) => cloneValue(item));
+  }
+  if (!isObject(base) || !isObject(patch)) {
+    return cloneValue(patch);
+  }
+  const next = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (Array.isArray(value)) {
+      next[key] = value.map((item) => cloneValue(item));
+      continue;
+    }
+    if (isObject(value) && isObject(base[key])) {
+      next[key] = deepMerge(base[key], value);
+      continue;
+    }
+    next[key] = cloneValue(value);
+  }
+  return next;
+}
+
+function cloneValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+module.exports = {
+  SCAFFOLD_ROOT,
+  buildDefaultRuntimeConfig,
+  loadRuntimeConfig,
+  resolveCatalogPath,
+  resolveDraftRoot,
+  resolveGeneratedSpecPath,
+  resolveRulePath
+};

package/tools/patch-draft.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const YAML = require('yaml');
+const { getDefaultDraftRoot, loadDraft, patchDraft, saveDraft } = require('./lib/draft-toolkit.cjs');
+
+const options = parseArgs(process.argv.slice(2));
+
+  try {
+    if (!options.draft || !options.patch) {
+    throw new Error('请提供 --draft <draft-path|draft-id> 和 --patch <patch.yaml|json>');
+  }
+
+  const draft = loadDraft(options.draft, { draftRoot: getDefaultDraftRoot() });
+  const patch = readStructuredFile(options.patch);
+  const nextDraft = patchDraft(draft, patch);
+  const savedDraft = saveDraft(nextDraft, {
+    draftRoot: draft.storage?.draftRoot || getDefaultDraftRoot(),
+    fileName: draft.storage?.fileName,
+  });
+  console.log(JSON.stringify(savedDraft, null, 2));
+} catch (error) {
+  console.error(`\n❌ Draft patch 失败: ${error.message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = {
+    draft: '',
+    patch: '',
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (item === '--draft') {
+      options.draft = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (item === '--patch') {
+      options.patch = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function readStructuredFile(filePath) {
+  const absolutePath = path.resolve(filePath);
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  if (absolutePath.endsWith('.yaml') || absolutePath.endsWith('.yml')) {
+    return YAML.parse(content);
+  }
+  return JSON.parse(content);
+}

package/tools/prompts/business-model-prompt.md

@@ -0,0 +1,58 @@
+# 业务模型生成 Prompt
+
+目标：根据业务需求说明，输出一个**严格符合 scaffold 业务模型规范**的 YAML 文件。
+
+输出要求：
+
+1. 只输出 YAML，不要解释。
+2. 顶层必须包含 `meta`、`data`、`app`、`ui`。
+3. `meta.object` 使用英文小写业务对象名，例如 `customer`。
+4. `data.table` 使用下划线命名，例如 `crm_customer`。
+5. 如果存在子表，必须放到 `data.children`，并声明 `foreignKey`。
+6. `app.actions` 只允许使用：
+   - `create`
+   - `update`
+   - `detail`
+   - `list`
+   - `activate`
+   - `deactivate`
+   - `submit`
+   - `approve`
+   - `reject`
+   - `close`
+   - `archive`
+   - `convert`
+7. 如存在 `status` 字段，优先补充 `app.defaultStatus`，必要时补充 `app.statusFlow`。
+8. 如存在稳定业务动作，允许补充 `app.errorCodes`。
+9. `ui.list.columns`、`ui.list.filters`、`ui.form.groups.fields` 中引用的字段，必须都存在于 `data.fields`。
+10. 不允许修改系统对象：
+   - `sys_user`
+   - `sys_role`
+   - `sys_menu`
+
+建议输出结构：
+
+```yaml
+meta:
+  domain: crm
+  object: customer
+  label: 客户
+  version: 0.1.0
+
+data:
+  table: crm_customer
+  fields: []
+  children: []
+
+app:
+  actions: [create, update, detail, list]
+
+ui:
+  list:
+    columns: []
+    filters: []
+  form:
+    groups: []
+  detail:
+    sections: []
+```