@svadmin/create 0.40.3 → 0.41.1

package/README.md

@@ -119,6 +119,19 @@ bun install
 bun run dev
 ```
 
+## Product-first Vibe Loop
+
+Use a product plan when a feature request is larger than one CRUD resource. The plan keeps business workflows, resources, pages, actions, and navigation separate so generated projects do not expose every backend table as a page.
+
+```bash
+# Read product issues before generating UI
+npx @svadmin/create vibe review ./svadmin.product.json
+
+# Preview the experience for one role; omit --role to inspect all roles
+npx @svadmin/create vibe plan ./svadmin.product.json --role operator
+```
+
+The plan uses schema version `product/v1`. Menu entries are driven by actual business needs and role/task context; svadmin does not apply a global menu-count cap. Generated starters include `PRODUCT.md` alongside `DESIGN.md` and `AGENTS.md`.
 ## Automated Inference CLI / 接口代码推断器
 
 Automatically infer ResourceDefinitions, TypeBox schemas, and Svelte 5 CRUD components from REST endpoints, OpenAPI / Swagger specs, GraphQL endpoints (introspection), or local schema/sample files:

package/blueprints/customer-workspace/vibe-skill.md

@@ -5,7 +5,7 @@ description: Build and refine Svelte admin pages from the installed svadmin page
 
 # svadmin Vibe
 
-Read `DESIGN.md`, `svadmin.vibe.json`, and `svadmin.ai.json`. Select the smallest
+Read `PRODUCT.md`, `DESIGN.md`, `svadmin.vibe.json`, and `svadmin.ai.json`. Run `svadmin vibe review ./svadmin.product.json` before generating a multi-resource feature. Select the smallest
 matching page family from `pages`; inspect its source and the relevant resource
 contract before editing. The catalog is a starting point, not permission to
 replace the customer's workflow with this demo's business model.
@@ -22,6 +22,13 @@ Pass an empty object to search all pages. These tools read shipped references
 only; inspect the current customer's sources separately before making changes.
 The CLI commands remain the fallback when no MCP client is configured.
 
+## Product boundary
+
+- Start from the user's outcome and workflows, not from the complete resource registry.
+- Treat resources as data contracts; only create a surface or menu node when a workflow, role, or business context justifies it.
+- Keep menu count proportional to the actual domain. Never remove required business entries to satisfy a global limit.
+- Keep one dominant action per surface and use the review command to catch dense action/section layouts before markup.
+
 ## Implement
 
 - Read installed `@svadmin/ui/component-registry` metadata and component type

package/blueprints/product-workspace/ARCHITECTURE.md

@@ -0,0 +1,18 @@
+# Product workspace boundaries
+
+Product mode separates product decisions from runtime resources:
+
+- `svadmin.product.json` is the source of truth for roles, workflows, resources,
+  surfaces and menu entries.
+- `src/generated/product-plan.ts` parses the plan at the application boundary.
+- `src/generated/resources.ts` exposes read-only resource metadata to svadmin.
+- `src/generated/navigation.ts` filters product menu entries by role and feature
+  flags. There is no fixed menu count.
+- `src/generated/pages.ts` contains the renderer-neutral page plan.
+- `src/generated/page-routes.ts` registers custom surface routes.
+- `src/product-provider.ts` is an empty in-memory adapter for visual review.
+
+Product actions are metadata until a typed command or provider contract is
+connected. The generated scaffold never claims that a button performed a real
+mutation. Server authorization, tenancy, audit, idempotency and persistence
+remain backend responsibilities.

package/blueprints/product-workspace/README.md

@@ -0,0 +1,14 @@
+# Product workspace
+
+This blueprint is generated from a validated `svadmin.product.json`. It keeps
+product decisions, navigation and page metadata in generated files so the
+application starts with a coherent information architecture instead of a
+database-shaped menu.
+
+The default provider is an empty in-memory provider. It is useful for visual
+review and route acceptance, but it is not a backend, an authorization boundary,
+or a source of business data. Wire an explicit provider and command contract
+before enabling production mutations.
+
+Generated files under `src/generated` are derived artifacts. Edit the product
+plan and regenerate the project rather than editing those files by hand.

package/blueprints/product-workspace/src/App.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import { AdminApp } from '@svadmin/ui';
+  import { resolveAdminConfig } from '@svadmin/app';
+  import config from './svadmin.config';
+  import { brand, getDesign } from './design.svelte';
+  import { productMenu } from './generated/navigation';
+  import { productResources } from './generated/resources';
+  import { productPageRoutes } from './generated/page-routes';
+
+  const resolved = resolveAdminConfig(config);
+  const design = $derived(getDesign());
+</script>
+
+<AdminApp
+  providerBundle={resolved.providers}
+  resources={[...productResources]}
+  menu={productMenu}
+  pageRoutes={productPageRoutes}
+  title={brand.name}
+  locale="zh-CN"
+  themeConfig={design.theme}
+  queryClientDefaultOptions={{ queries: { retry: false } }}
+/>

package/blueprints/product-workspace/src/ProductSurfacePage.svelte

@@ -0,0 +1,132 @@
+<script lang="ts">
+  import type { ProductPagePlan } from '@svadmin/core/product-pages';
+  import { productPagePlans, productSurfaceRoutes } from './generated/pages';
+
+  interface Props {
+    route: string;
+    params: Record<string, string | undefined>;
+  }
+
+  type SurfaceState = ProductPagePlan['states'][number];
+  const stateByScenario: Record<string, SurfaceState | undefined> = {
+    empty: 'empty',
+    loading: 'loading',
+    error: 'error',
+    denied: 'forbidden',
+  };
+
+  let { route }: Props = $props();
+  const page = $derived(productPagePlans.find(candidate => productSurfaceRoutes[route] === candidate.id));
+  const requestedScenario = typeof location !== 'undefined'
+    ? new URLSearchParams(location.search).get('scenario') ?? 'normal'
+    : 'normal';
+  const scenarioState = $derived.by(() => {
+    const candidate = page;
+    const state = stateByScenario[requestedScenario];
+    return candidate && state !== undefined && candidate.states.includes(state) ? state : undefined;
+  });
+</script>
+
+<svelte:head>
+  <title>{page?.title ?? 'Product surface'}</title>
+</svelte:head>
+
+<div class="surface-page">
+  {#if page}
+    <header class="surface-hero">
+      <div>
+        <p class="eyebrow">{page.kind}</p>
+        <h1>{page.title}</h1>
+        <p class="purpose">{page.purpose}</p>
+      </div>
+      {#if page.primaryAction}
+        <span class="action-badge">主操作：{page.primaryAction.label}</span>
+      {/if}
+    </header>
+
+    <div class="state-strip">
+      {#each page.states as state (state)}
+        <span class="state">{state}</span>
+      {/each}
+    </div>
+
+    {#if scenarioState}
+      <section class="surface-state" data-state={scenarioState}>
+        {#if scenarioState === 'loading'}
+          <span class="state-icon" aria-hidden="true">◌</span>
+          <h2>正在加载工作台</h2>
+          <p>正在准备当前工作流需要的数据。</p>
+        {:else if scenarioState === 'empty'}
+          <span class="state-icon" aria-hidden="true">○</span>
+          <h2>当前没有待处理数据</h2>
+          <p>工作流已经准备好；当业务数据进入后，这里会显示下一步操作。</p>
+        {:else if scenarioState === 'error'}
+          <span class="state-icon" aria-hidden="true">!</span>
+          <h2>暂时无法加载工作台</h2>
+          <p>数据 provider 返回了错误，请稍后重试或联系管理员。</p>
+        {:else if scenarioState === 'forbidden'}
+          <span class="state-icon" aria-hidden="true">×</span>
+          <h2>没有访问权限</h2>
+          <p>当前角色没有访问这个工作流的权限。</p>
+        {/if}
+      </section>
+    {:else}
+      <div class="surface-grid">
+        {#each page.sections as section (section.id)}
+          <section class="surface-card">
+            <div class="card-heading">
+              <h2>{section.title}</h2>
+              <span>区块</span>
+            </div>
+            <p>此区块服务于当前工作流，并展示产品计划声明的资源。</p>
+            {#if section.resourceIds.length}
+              <div class="resource-list">
+                {#each section.resourceIds as resourceId (resourceId)}
+                  <span>{resourceId}</span>
+                {/each}
+              </div>
+            {:else}
+              <p class="muted">此区块暂无数据资源，等待接入真实 provider。</p>
+            {/if}
+          </section>
+        {/each}
+      </div>
+
+      <aside class="contract-note">
+        <strong>动作仍是产品元数据</strong>
+        <span>接入 defineCommand 或资源契约后，再启用真实提交、审批和写入。</span>
+      </aside>
+    {/if}
+  {:else}
+    <section class="surface-card">
+      <h1>未找到页面计划</h1>
+      <p>路径 {route} 尚未在产品计划中注册。</p>
+    </section>
+  {/if}
+</div>
+
+<style>
+  .surface-page { max-width: 1180px; margin: 0 auto; padding: 32px; color: #172033; }
+  .surface-hero { display: flex; justify-content: space-between; gap: 24px; align-items: flex-end; margin-bottom: 18px; }
+  .eyebrow { margin: 0 0 8px; text-transform: uppercase; letter-spacing: .12em; color: #65708a; font-size: 12px; font-weight: 700; }
+  h1, h2, p { margin-top: 0; }
+  h1 { margin-bottom: 8px; font-size: clamp(28px, 4vw, 46px); letter-spacing: -.03em; }
+  h2 { font-size: 18px; }
+  .purpose { max-width: 700px; color: #65708a; font-size: 16px; line-height: 1.6; }
+  .action-badge, .state, .resource-list span { border-radius: 999px; background: #e8eefc; color: #3558a8; padding: 7px 11px; font-size: 12px; font-weight: 650; }
+  .state-strip { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 20px; }
+  .state { background: #eef0f3; color: #596273; }
+  .surface-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 16px; }
+  .surface-state { display: grid; justify-items: center; gap: 8px; min-height: 220px; padding: 42px 24px; border: 1px dashed #cdd5e4; border-radius: 18px; background: #f8faff; text-align: center; }
+  .surface-state h2, .surface-state p { margin: 0; }
+  .surface-state p { max-width: 520px; color: #65708a; line-height: 1.6; }
+  .state-icon { display: grid; place-items: center; width: 36px; height: 36px; border-radius: 50%; background: #e8eefc; color: #3558a8; font-size: 22px; font-weight: 700; }
+  .surface-card { min-height: 150px; padding: 22px; border: 1px solid #e4e7ed; border-radius: 18px; background: #fff; box-shadow: 0 10px 30px rgb(32 45 72 / 5%); }
+  .card-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+  .card-heading span { color: #8a94a7; font-size: 12px; }
+  .surface-card p { color: #65708a; line-height: 1.6; }
+  .resource-list { display: flex; flex-wrap: wrap; gap: 7px; margin-top: 18px; }
+  .muted { color: #98a1b2 !important; font-size: 14px; }
+  .contract-note { display: flex; flex-direction: column; gap: 5px; margin-top: 18px; padding: 16px 18px; border-left: 3px solid #6f8fe8; background: #f0f4ff; color: #33425f; line-height: 1.5; }
+  @media (max-width: 640px) { .surface-page { padding: 20px 16px; } .surface-hero { align-items: flex-start; flex-direction: column; } }
+</style>

package/blueprints/product-workspace/src/app.css

@@ -0,0 +1,6 @@
+@import "@svadmin/ui/app.css";
+
+html { letter-spacing: 0; }
+body { margin: 0; background: #f7f8fa; }
+[data-svadmin-skip-link] { transform: translateY(calc(-100% - 1rem)); }
+[data-svadmin-skip-link]:focus { transform: translateY(0); }

package/blueprints/product-workspace/src/design.svelte.ts

@@ -0,0 +1,7 @@
+import type { ThemeConfig } from '@svadmin/core';
+
+export const brand = $state({ name: 'Product workspace' });
+
+export function getDesign(): { theme: ThemeConfig } {
+  return { theme: { colorPreset: 'neutral', layoutPreset: 'clean-flat' } };
+}

package/blueprints/product-workspace/src/product-provider.ts

@@ -0,0 +1,81 @@
+import { HttpError, type BaseRecord, type DataProvider, type Filter } from '@svadmin/core';
+import { productResources } from './generated/resources';
+
+export type ProductScenario = 'normal' | 'empty' | 'error' | 'loading' | 'denied' | 'readonly';
+
+function matches(row: BaseRecord, filter: Filter): boolean {
+  if (!('field' in filter)) {
+    return filter.operator === 'or'
+      ? filter.value.some(candidate => matches(row, candidate))
+      : filter.value.every(candidate => matches(row, candidate));
+  }
+  const value = row[filter.field];
+  switch (filter.operator) {
+    case 'eq': return value === filter.value;
+    case 'ne': return value !== filter.value;
+    case 'contains': return String(value ?? '').toLowerCase().includes(String(filter.value).toLowerCase());
+    case 'in': return Array.isArray(filter.value) && filter.value.includes(value);
+    case 'null': return value === null || value === undefined;
+    case 'nnull': return value !== null && value !== undefined;
+    default: throw new HttpError('当前脚手架不支持该筛选条件', 400);
+  }
+}
+
+export function createProductProvider(scenario: ProductScenario = 'normal'): DataProvider {
+  const rows: Record<string, BaseRecord[]> = Object.fromEntries(
+    productResources.map(resource => [resource.name, [] as BaseRecord[]]),
+  );
+  async function table(resource: string): Promise<BaseRecord[]> {
+    if (scenario === 'denied') throw new HttpError('无权访问', 403);
+    if (scenario === 'error') throw new HttpError('演示 provider 暂不可用', 503);
+    if (scenario === 'loading') await new Promise(resolve => setTimeout(resolve, 1200));
+    const data = rows[resource];
+    if (!data) throw new HttpError('资源不存在', 404);
+    return data;
+  }
+  function find(data: BaseRecord[], id: string | number): BaseRecord {
+    const row = data.find(record => String(record['id']) === String(id));
+    if (!row) throw new HttpError('记录不存在', 404);
+    return row;
+  }
+  return {
+    getApiUrl: () => 'memory://svadmin-product',
+    async getList({ resource, pagination, sorters = [], filters = [] }) {
+      const data = await table(resource);
+      let result = (scenario === 'empty' ? [] : data).filter(row => filters.every(filter => matches(row, filter)));
+      result = [...result].sort((a, b) => {
+        for (const sorter of sorters) {
+          const order = String(a[sorter.field] ?? '').localeCompare(String(b[sorter.field] ?? ''), 'zh-CN', { numeric: true });
+          if (order) return sorter.order === 'desc' ? -order : order;
+        }
+        return 0;
+      });
+      const total = result.length;
+      if (pagination?.mode !== 'off') {
+        const size = pagination?.pageSize ?? 10;
+        const start = ((pagination?.current ?? 1) - 1) * size;
+        result = result.slice(start, start + size);
+      }
+      return { data: structuredClone(result), total };
+    },
+    async getOne({ resource, id }) { return { data: structuredClone(find(await table(resource), id)) }; },
+    async getMany({ resource, ids }) {
+      return { data: structuredClone((await table(resource)).filter(row => ids.some(id => String(id) === String(row['id'])))) };
+    },
+    async create({ resource, variables }) {
+      if (scenario === 'readonly') throw new HttpError('仅允许查看', 403);
+      const data = await table(resource);
+      const record = { ...(variables as BaseRecord), id: crypto.randomUUID() };
+      data.push(record);
+      return { data: structuredClone(record) };
+    },
+    async update({ resource, id, variables }) {
+      if (scenario === 'readonly') throw new HttpError('仅允许查看', 403);
+      const data = await table(resource);
+      const record = find(data, id);
+      Object.assign(record, variables as BaseRecord);
+      return { data: structuredClone(record) };
+    },
+    async deleteOne() { throw new HttpError('产品脚手架未启用删除', 403); },
+  };
+}

package/blueprints/product-workspace/src/svadmin.config.ts

@@ -0,0 +1,29 @@
+import { createProviderBundle, defineAdminConfig } from '@svadmin/app';
+import { productResources } from './generated/resources';
+import { createProductProvider, type ProductScenario } from './product-provider';
+
+const requested = typeof location !== 'undefined' && import.meta.env.DEV
+  ? new URLSearchParams(location.search).get('scenario')
+  : null;
+const scenarios: readonly string[] = ['normal', 'empty', 'error', 'loading', 'denied', 'readonly'];
+const scenario: ProductScenario = requested !== null && scenarios.includes(requested)
+  ? scenarioFrom(requested)
+  : 'normal';
+
+function scenarioFrom(value: string): ProductScenario {
+  return value as ProductScenario;
+}
+
+export default defineAdminConfig({
+  name: 'product-workspace',
+  providers: createProviderBundle({
+    dataProvider: createProductProvider(scenario),
+    accessControlProvider: {
+      can: async ({ action }) => ({
+        can: scenario !== 'denied' && (scenario !== 'readonly' || ['list', 'show', 'field'].includes(action)),
+      }),
+      options: { buttons: { enableAccessControl: true, hideIfUnauthorized: true } },
+    },
+  }),
+  resources: productResources,
+});

package/blueprints/product-workspace/svadmin.vibe.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "id": "product-workspace",
+  "status": "generated",
+  "framework": "svelte5-vite",
+  "source": "svadmin.product.json",
+  "generated": ["src/generated/product-plan.ts", "src/generated/navigation.ts", "src/generated/pages.ts", "src/generated/resources.ts", "src/generated/page-routes.ts"],
+  "dataMode": "empty-in-memory",
+  "boundaries": ["No production writes", "No fake authorization", "Actions require explicit command contracts", "Menu count follows business needs"]
+}

package/blueprints/product-workspace/vibe-skill.md

@@ -0,0 +1,14 @@
+---
+name: svadmin-vibe
+description: Build product-first Svelte admin surfaces from a validated svadmin.product.json and generated page plans.
+---
+
+# svadmin Vibe
+
+Read PRODUCT.md, DESIGN.md, ARCHITECTURE.md, svadmin.product.json and svadmin.ai.json before changing a generated project. Keep the product plan as the source of truth for roles, workflows, resources, surfaces and menu entries.
+
+Start with the user outcome and workflow. Resources are data contracts and do not automatically become pages or sidebar entries. Menu count follows the business domain; do not remove required entries to satisfy a global limit. Keep one dominant action per surface and use progressive disclosure for secondary actions.
+
+Generated files under src/generated are derived artifacts. Change svadmin.product.json and regenerate instead of editing them by hand. Product actions are metadata until a typed command or provider contract is connected. Never claim that an empty in-memory provider provides persistence, authorization, audit or production data.
+
+Use the installed @svadmin/ui component registry and public type declarations. Keep the Svelte/SvelteKit stack, semantic tokens, responsive layout and state coverage. Verify with bun run check, bun run build and bun run test:ui, then inspect 1440x900 and 1920x1080 captures. Backend authorization, tenancy, audit and durable writes remain server responsibilities.