create-pactor-app 1.20.0

package/templates/next-app/src/server/sitemap.ts

@@ -0,0 +1,558 @@
+import type { PageDsl } from "@pactor-app/core";
+
+import type { LayoutDsl, SitemapResource } from "pactor-app";
+
+import type { DemoUser } from "./accounts";
+
+/**
+ * Mock sitemap 数据源（design/dynamic-page.md 方案 B 示例实现）。
+ * 真实项目由后端接口返回同构对象——端点按会话裁剪：
+ * 匿名 → public 页（登录/注册）；登录后 → 该角色可见的 menus / pages / permissions。
+ */
+
+/**
+ * 服务端下发的接口地址：DSL 中直接引用后端绝对地址（跨域），
+ * 客户端 httpHooks 自动改写进项目内代理前缀。登录 / 登出即普通 HTTP
+ * 调用，DSL 用内置 request 动作表达，无需客户端注册服务。
+ */
+const apiBase = "http://localhost:9011";
+
+/* ---------------- 布局（DSL 定义，PageOutlet 为页面内容出口） ---------------- */
+/* 布局 body 内 ${data.session.*} 由客户端注入的 session dataSource 提供
+ *（user / app / menus）；${route.params.pathname} 为当前路径（客户端注入）。 */
+
+const layouts: Record<string, LayoutDsl> = {
+  admin: {
+    dsl: "1.0",
+    body: {
+      type: "Flex",
+      props: { gap:0, direction: "horizontal", style: { height: "100vh" } },
+      children: [
+        {
+          type: "Flex",
+          props: {
+            direction: "vertical",
+            style: {
+              width: 224,
+              flexShrink: 0,
+              borderRight: "1px solid var(--border)",
+            },
+          },
+          children: [
+            {
+              type: "Flex",
+              props: {
+                style: {
+                  padding: "16px 16px",
+                  fontWeight: 600,
+                  borderBottom: "1px solid var(--border)",
+                },
+              },
+              children: [
+                { type: "Text", props: { text: "${data.session.app.name}" } },
+              ],
+            },
+            {
+              type: "SitemapMenu",
+              props: {
+                items: "${data.session.menus}",
+                collapsible: true,
+              },
+              events: {
+                onSelect: [
+                  { action: "navigate", params: { to: "${event}" } },
+                ],
+              },
+            },
+          ],
+        },
+        {
+          type: "Flex",
+          props: { direction: "vertical", style: { flex: 1, minWidth: 0 } },
+          children: [
+            {
+              type: "Flex",
+              props: {
+                justify: "end",
+                align: "center",
+                style: {
+                  padding: "10px 20px",
+                  borderBottom: "1px solid var(--border)",
+                },
+              },
+              children: [
+                {
+                  type: "DropdownMenu",
+                  props: {
+                    items: [
+                      {
+                        label: "个人设置",
+                        value: "settings",
+                        icon: "settings",
+                      },
+                      { label: "退出登录", value: "logout", icon: "log-out" },
+                    ],
+                  },
+                  events: {
+                    onSelect: [
+                      {
+                        action: "if",
+                        params: {
+                          condition: "${event == 'logout'}",
+                          then: [
+                            {
+                              action: "request",
+                              params: {
+                                method: "POST",
+                                url: `${apiBase}/api/auth/logout`,
+                              },
+                            },
+                            {
+                              action: "app.reload",
+                              params: { to: "/login" },
+                            },
+                          ],
+                          else: [
+                            {
+                              action: "message",
+                              params: { text: "演示环境未实现个人设置" },
+                            },
+                          ],
+                        },
+                      },
+                    ],
+                  },
+                  children: [
+                    {
+                      type: "Button",
+                      props: {
+                        text: "${data.session.user.name}",
+                        variant: "text",
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              type: "Flex",
+              props: {
+                direction: "vertical",
+                style: { flex: 1, minHeight: 0, overflow: "auto" },
+              },
+              children: [{ type: "PageOutlet" }],
+            },
+          ],
+        },
+      ],
+    },
+  },
+  login: {
+    dsl: "1.0",
+    body: {
+      type: "Flex",
+      props: {
+        direction: "vertical",
+        justify: "center",
+        align: "center",
+        style: { minHeight: "100vh", padding: 24 },
+      },
+      children: [
+        {
+          type: "Flex",
+          props: {
+            direction: "vertical",
+            style: {
+              width: 380,
+              padding: 24,
+              border: "1px solid var(--border)",
+              borderRadius: 12,
+            },
+          },
+          children: [{ type: "PageOutlet" }],
+        },
+      ],
+    },
+  },
+  blank: { dsl: "1.0", body: { type: "PageOutlet" } },
+};
+
+/* ---------------- 页面 DSL（内联页） ---------------- */
+
+const loginPage: PageDsl = {
+  dsl: "1.0",
+  page: { id: "login", title: "登录" },
+  state: { submitting: false },
+  body: {
+    type: "Form",
+    events: {
+      onSubmit: [
+        { action: "setState", params: { submitting: true } },
+        {
+          id: "loginResult",
+          action: "request",
+          params: {
+            method: "POST",
+            url: `${apiBase}/api/auth/login`,
+            body: {
+              username: "${event.username}",
+              password: "${event.password}",
+            },
+          },
+        },
+        { action: "setState", params: { submitting: false } },
+        {
+          action: "if",
+          params: {
+            condition: "${actions.loginResult.token}",
+            then: [
+              // 登录成功整页重载：sitemap 端点按已登录会话重新裁剪内容
+              { action: "app.reload", params: { to: "/" } },
+            ],
+            else: [
+              {
+                action: "message",
+                params: {
+                  messageType: "error",
+                  text: "登录失败：用户名或密码错误",
+                },
+              },
+            ],
+          },
+        },
+      ],
+    },
+    children: [
+      {
+        type: "Alert",
+        props: {
+          variant: "info",
+          message: "演示账号 admin / pactor123，guest / guest123",
+          description:
+            "admin 可见「报表」菜单（report:view）；guest 仅可见首页。登录后 sitemap 按角色重新下发。",
+          style: { marginBottom: 16 },
+        },
+      },
+      {
+        type: "Input",
+        props: {
+          name: "username",
+          label: "用户名",
+          placeholder: "请输入用户名",
+          rules: [{ required: true, message: "请输入用户名" }],
+        },
+      },
+      {
+        type: "Input",
+        props: {
+          name: "password",
+          label: "密码",
+          type: "password",
+          placeholder: "请输入密码",
+          rules: [{ required: true, message: "请输入密码" }],
+        },
+      },
+      {
+        type: "Flex",
+        props: { justify: "end" },
+        children: [
+          {
+            type: "Button",
+            props: {
+              text: "登 录",
+              variant: "primary",
+              submit: true,
+              loading: "${state.submitting}",
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+
+const registerPage: PageDsl = {
+  dsl: "1.0",
+  page: { id: "register", title: "注册" },
+  body: {
+    type: "Page",
+    props: { title: "注册" },
+    children: [
+      {
+        type: "Alert",
+        props: {
+          variant: "warning",
+          message: "演示环境不开放注册",
+          description: "请使用登录页的演示账号体验不同角色的菜单差异。",
+          style: { marginBottom: 16 },
+        },
+      },
+      {
+        type: "Button",
+        props: { text: "返回登录", variant: "primary" },
+        events: {
+          onClick: [{ action: "navigate", params: { to: "/login" } }],
+        },
+      },
+    ],
+  },
+};
+
+const homePage: PageDsl = {
+  dsl: "1.0",
+  page: { id: "home", title: "首页" },
+  body: {
+    type: "Page",
+    props: { title: "首页" },
+    children: [
+      {
+        type: "Alert",
+        props: {
+          variant: "info",
+          message: "欢迎回来，${data.session.user.name}！",
+          description:
+            "本页与外壳布局均由 sitemap 对象下发（design/dynamic-page.md）；菜单随角色裁剪。",
+          style: { marginBottom: 16 },
+        },
+      },
+      {
+        type: "Button",
+        props: { text: "查看月报（需 report:view）" },
+        events: {
+          onClick: [
+            { action: "navigate", params: { to: "/reports/monthly" } },
+          ],
+        },
+      },
+    ],
+  },
+};
+
+const monthlyDetailPage: PageDsl = {
+  dsl: "1.0",
+  page: { id: "monthly-detail", title: "月报详情" },
+  body: {
+    type: "Page",
+    props: { title: "月报详情" },
+    children: [
+      {
+        type: "Alert",
+        props: {
+          variant: "info",
+          message: "路径参数演示：id = ${route.params.id}",
+          description: "隐藏页（不出现在菜单），经列表页跳转进入。",
+          style: { marginBottom: 16 },
+        },
+      },
+      {
+        type: "Button",
+        props: { text: "返回月报" },
+        events: {
+          onClick: [
+            { action: "navigate", params: { to: "/reports/monthly" } },
+          ],
+        },
+      },
+    ],
+  },
+};
+
+/** 懒加载页（pageDsl 不下发，客户端经 loadPage 按需获取） */
+const lazyPages: Record<string, { version: number; pageDsl: PageDsl }> = {
+  monthly: {
+    version: 7,
+    pageDsl: {
+      dsl: "1.0",
+      page: { id: "monthly", title: "月报" },
+      body: {
+        type: "Page",
+        props: { title: "本月经营月报" },
+        children: [
+          {
+            type: "Flex",
+            props: { gap: 16, style: { marginBottom: 16 } },
+            children: [
+              {
+                type: "Card",
+                props: { title: "营收" },
+                children: [
+                  {
+                    type: "Statistic",
+                    props: { title: "本月（万元）", value: 128.6 },
+                  },
+                ],
+              },
+              {
+                type: "Card",
+                props: { title: "新增客户" },
+                children: [
+                  { type: "Statistic", props: { title: "本月（家）", value: 342 } },
+                ],
+              },
+              {
+                type: "Card",
+                props: { title: "转化率" },
+                children: [
+                  { type: "Statistic", props: { title: "本月（%）", value: 23.8 } },
+                ],
+              },
+            ],
+          },
+          {
+            type: "Alert",
+            props: {
+              variant: "success",
+              message: "本页 DSL 由 /api/pages/monthly 懒加载下发",
+              description:
+                "sitemap 中该页仅声明 id / path / version（monthly@7），点击进入时才请求页面 DSL。",
+              style: { marginBottom: 16 },
+            },
+          },
+          {
+            type: "Button",
+            props: { text: "查看详情（隐藏页 + 路径参数）" },
+            events: {
+              onClick: [
+                {
+                  action: "navigate",
+                  params: { to: "/reports/monthly/2026-09" },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  },
+};
+
+/* ---------------- 页面 / 菜单定义 ---------------- */
+
+function canViewReports(user: DemoUser | null): boolean {
+  return user !== null && user.permissions.includes("report:view");
+}
+
+/**
+ * 按会话构建 sitemap：同一 URL，不同用户拿到不同内容。
+ * 匿名 → 仅 public 页；guest → + 首页；admin → + 报表组。
+ */
+export function buildSitemap(user: DemoUser | null): SitemapResource {
+  const reports = canViewReports(user);
+
+  const pages: SitemapResource["pages"] = [
+    { id: "login", path: "/login", title: "登录", version: 1, pageDsl: loginPage },
+    {
+      id: "register",
+      path: "/register",
+      title: "注册",
+      version: 1,
+      pageDsl: registerPage,
+    },
+  ];
+  if (user) {
+    pages.push({ id: "home", path: "/", title: "首页", version: 3, pageDsl: homePage });
+  }
+  if (reports) {
+    // 懒加载：不下发 pageDsl，仅 id / path / version（monthly@7）
+    pages.push({ id: "monthly", path: "/reports/monthly", title: "月报", version: 7 });
+    pages.push({
+      id: "monthly-detail",
+      path: "/reports/monthly/:id",
+      title: "月报详情",
+      version: 2,
+      pageDsl: monthlyDetailPage,
+    });
+  }
+
+  const menus: SitemapResource["menus"] = [
+    {
+      id: "login",
+      type: "page",
+      pageId: "login",
+      title: "登录",
+      layout: "login",
+      public: true,
+      hidden: true,
+    },
+    {
+      id: "register",
+      type: "page",
+      pageId: "register",
+      title: "注册",
+      layout: "login",
+      public: true,
+      hidden: true,
+    },
+  ];
+  if (user) {
+    // path / title 缺省继承自 pages[]，仅导航元数据（icon / order / layout）
+    menus.push({ id: "home", type: "page", pageId: "home", title: "首页", icon: "home", layout: "admin", order: 1 });
+  }
+  if (reports) {
+    menus.push({
+      id: "reports",
+      type: "group",
+      title: "报表",
+      icon: "chart",
+      order: 2,
+      children: [
+        {
+          id: "monthly",
+          type: "page",
+          pageId: "monthly",
+          title: "报表中心",
+          icon: "chart",
+          layout: "admin",
+          permission: "report:view",
+        },
+        {
+          id: "monthly-detail",
+          type: "page",
+          pageId: "monthly-detail",
+          title: "月报详情",
+          layout: "admin",
+          hidden: true,
+          activeMenu: "monthly",
+        },
+      ],
+    });
+    menus.push({
+      id: "help",
+      type: "link",
+      title: "帮助",
+      path: "https://github.com/",
+      external: true,
+      order: 3,
+    });
+  }
+
+  return {
+    id: "site",
+    resourceType: "sitemap",
+    version: 12,
+    dslVersion: "1.0",
+    updatedAt: new Date().toISOString(),
+    app: { name: "动态页面 Starter" },
+    ...(user ? { user: { ...user }, permissions: user.permissions } : {}),
+    layout: "admin",
+    auth: { loginPath: "/login" },
+    layouts,
+    pages,
+    menus,
+  };
+}
+
+/** 懒加载页：校验会话与角色（前端权限只控制 UI，接口必须鉴权） */
+export function getLazyPage(
+  pageId: string,
+  user: DemoUser | null,
+): { version: number; pageDsl: PageDsl } | null {
+  const entry = lazyPages[pageId];
+  if (!entry) {
+    return null;
+  }
+  if (pageId === "monthly" && !canViewReports(user)) {
+    return null;
+  }
+  return entry;
+}

package/templates/next-app/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/spa/README.md

@@ -0,0 +1,97 @@
+# __APP_NAME__
+
+`design/dynamic-page.md` 的纯前端（SPA）示例：Vite + React，无 Next.js 等
+宿主框架。与 `next-app-starter` 的关键差异——**不向 `SitemapApp` 传
+`pathname` / `navigate`**，框架内置浏览器路由（History API 导航 +
+popstate 前进后退）接管全部路由：
+
+```tsx
+// src/pactor/App.tsx —— 全部装配
+<SitemapApp
+  sources={sitemapSources}    // sitemap 接口（相对路径）
+  baseUrl={apiBaseUrl}        // 外部接口基准地址（相对路径补全）
+  pageEndpoint={pageEndpoint} // 懒加载页面端点
+  httpAdapter={httpHooks}     // 框架 createHttpHooks：跨域改写 + 响应拆包
+/>
+```
+
+本模板不自带后端：接口复用 `next-app-starter` 的 mock API
+（`apiBaseUrl` 缺省指向 `http://localhost:9011`，已开通 CORS）。
+
+## 快速开始
+
+```bash
+# 1. 启动接口服务（mock API：sitemap / 页面懒加载 / 认证）
+cd ../next-app-starter && pnpm install && pnpm dev   # :9011
+
+# 2. 启动本模板
+cd ../spa-starter && pnpm install && pnpm dev        # http://localhost:9012
+```
+
+演示账号：`admin / pactor123`（可见「报表」菜单，含懒加载月报页）、
+`guest / guest123`（仅首页）。匿名访问自动跳转登录页（内置守卫）。
+
+## 目录结构
+
+```
+src/
+  main.tsx               # React 入口（导入 @pactor-app/ui/styles.css，必需）
+  pactor/
+    App.tsx              # SitemapApp 装配（纯前端模式：零路由配置；HTTP 钩子用框架 createHttpHooks）
+    config.ts            # sitemapSources / apiBaseUrl / pageEndpoint
+vite.config.ts           # react 插件（无代理：接口服务端已开通 CORS，直连）
+```
+
+## 纯前端模式说明
+
+`SitemapApp` 两种路由模式（详见 `packages/app/README.md`）：
+
+- **纯前端 SPA（本模板）**：不传路由 props。内置浏览器路由处理导航、
+  前进 / 后退、地址栏同步与 query 解析（`${route.query.x}` 可读）；
+  匿名守卫重定向同样走 `pushState`。
+- **宿主路由（next-app-starter）**：注入 `pathname` / `navigate`，
+  框架不持有路由。
+
+登录 / 登出后 sitemap 需按新会话重新下发，模板用框架内置 `app.reload`
+动作整页重载（`window.location.assign`），两种模式一致。登录 / 登出
+本身是普通 HTTP 调用，由服务端下发的 DSL 用内置 `request` 动作直接
+表达（见 next-app-starter 的 `src/server/sitemap.ts`），客户端零服务代码。
+
+## 跨域与 HTTP 钩子
+
+外部接口以 `apiBaseUrl`（`src/pactor/config.ts`，缺省
+`http://localhost:9011`，即 next-app-starter 的 dev server）为基准：
+`sitemapSources` / `pageEndpoint` 只写相对路径，由 `baseUrl` 补全为
+外部绝对地址。**假定服务端已开通 CORS，浏览器直连，无需项目内代理**——
+接口方（next-app-starter）已在路由层放开跨源并支持凭据
+（Allow-Origin 回显 + Allow-Credentials + 预检响应），cookie 会话跨源
+可达（框架 fetch 均带 `credentials: 'include'`）。
+
+**HTTP 钩子**（框架默认实现 `createHttpHooks`，`src/pactor/App.tsx`）：
+- `request`：缺省不改写地址（CORS 直连）；服务端不开 CORS 时传
+  `proxyPrefix` 把跨域地址改写到项目内代理前缀（需自行配置
+  Vite `server.proxy` / nginx 转发）；可注入公共头（Authorization 等）
+- `response`：`{ code, data, message }` 包裹结构拆包（业务错误码抛错）；
+  后端包裹协议不同传 `envelope: false` 或自行实现 `PactorHttpHooks`
+
+## 接入真实后端
+
+1. `src/pactor/config.ts`：`sitemapSources` 改为你的接口 URL（可多个），
+   `apiBaseUrl` 改为接口基准地址。
+2. 服务端按 `SitemapResource`（自 `pactor-app` 导入类型）返回 JSON：
+   - `layouts`：DSL 布局（`PageOutlet` 为页面出口，`SitemapMenu` 渲染导航，
+     `${data.session.*}` 读会话数据）
+   - `pages`：页面定义（`pageDsl` 内联或缺省，`version` 参与缓存键 `id@version`）
+   - `menus`：导航 / 路由树（`pageId` 引用页面、`layout` 引用布局、
+     `public` 免登录；`path` / `title` 缺省从引用页面继承）
+   - `auth.loginPath`：未登录重定向目标
+3. 懒加载页：实现 `GET {pageEndpoint}/{id}` 返回 PageResource envelope
+   （缺省 `/api/pages/{id}`）。
+4. 登录 / 登出等接口调用直接在 DSL 中用内置 `request` 动作表达（URL
+   指向你的真实接口）；有客户端服务层时可用内置 `service.call` 动作
+   桥接，`session.context` 会话桥由框架内置，均无需自行注册。
+
+> 依赖说明：`SitemapApp` 于 `@pactor-app/app` v1.19.0 引入。本模板开发期间
+> pactor 依赖经 `link:../../packages/*` 指向本仓；`v1.19.0` 发布到 npm 后
+> 改回 `^1.19.0` 版本号即可独立使用。`react-router-dom` 是
+> `@pactor-app/app` 的 peer 依赖（整应用模式需要），纯前端模式不会用到。

package/templates/spa/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>" />
+    <title>Pactor SPA Starter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>