@lark-apaas/coding-templates 0.1.22 → 0.1.24

package/README.md

@@ -4,39 +4,32 @@ OpenClaw 项目模板包，供 mclaw CLI 使用。
 
 ## 模板列表
 
-| 模板 | 目录 | 说明 |
-|---|---|---|
-| html | `template-html/` | 纯 HTML，零依赖，原型验证 |
-| vite-react | `template-vite-react/` | Vite + React 19 + Tailwind CSS + shadcn/ui |
+| 模板 | 目录 | 类型 | 说明 |
+|---|---|---|---|
+| html | `template-html/` | 纯前端 | 纯 HTML，零依赖，原型验证 |
+| vite-react | `template-vite-react/` | 纯前端 | Vite + React 19 + Tailwind CSS + shadcn/ui |
+| apex | `template-apex/` | 全栈 | Vite + React + Express + Drizzle + PostgreSQL |
 
 ## 包结构
 
 ```
 coding-templates/
-├── package.json                  # npm 包定义（@lark-apaas/coding-templates）
-├── meta.json                     # 模板元数据（业务侧生成，名称/描述/特性标签）
+├── package.json
+├── meta.json                     # 模板元数据
 ├── template-html/
-│   ├── _gitignore
-│   ├── package.json              # mclaw.stack: "html"
-│   └── index.html
-└── template-vite-react/
-    ├── _gitignore                # CLI 复制时重命名为 .gitignore
-    ├── package.json              # mclaw.stack: "vite-react"，name 为 {{projectName}}
-    ├── vite.config.ts
-    ├── eslint.config.js
-    ├── components.json
-    ├── client/
+├── template-vite-react/
+└── template-apex/
+    ├── client/                   # 前端（Vite + React）
     │   ├── index.html
-    │   ├── public/
     │   └── src/
-    │       ├── app.tsx           # 路由注册
-    │       ├── index.css         # 全局样式 + 主题变量
-    │       ├── components/ui/    # shadcn/ui 组件（new-york 风格）
-    │       ├── pages/
-    │       ├── hooks/
-    │       └── lib/
-    └── shared/                   # 前后端共享代码
-        └── types.ts
+    ├── server/                   # 后端（Express + Drizzle）
+    │   ├── index.ts
+    │   ├── db/
+    │   └── routes/
+    ├── shared/                   # 前后端共享类型和 API 契约
+    ├── scripts/build.sh          # 构建脚本
+    ├── tsconfig.server.json      # 服务端 CJS 编译配置
+    └── vite.config.ts
 ```
 
 ## 特殊文件命名
@@ -48,28 +41,45 @@ npm publish 会忽略 `.gitignore` 和 `.env*`，因此模板中使用 `_` 前
 | `_gitignore` | `.gitignore` |
 | `_env.local` | `.env.local` |
 
-## 模板类型标识
+## 模板元数据
 
-每个模板的 `package.json` 包含 `mclaw.stack` 字段，标识模板类型：
+每个模板的 `package.json` 包含 `mclaw` 字段：
 
 ```json
 {
   "mclaw": {
-    "stack": "vite-react",
-    "stackVersion": "0.1.0"
+    "stack": "apex",
+    "stackVersion": "0.1.0",
+    "features": ["client", "server"]
   }
 }
 ```
 
+| 字段 | 说明 |
+|---|---|
+| `stack` | 技术栈标识 |
+| `stackVersion` | 模板版本 |
+| `features` | 应用能力，`init` 时自动推导 archType |
+
 ## 技术栈
 
-vite-react 模板技术选型：
+### apex（全栈）
+
+- **前端**: Vite 8 + React 19 + TypeScript 5.9 + Tailwind CSS 4 + shadcn/ui
+- **后端**: Express 5 + Drizzle ORM + PostgreSQL
+- **平台集成**: @lark-apaas/express-core（用户上下文、CSRF、RLS、viewContext）
+- **开发**: Vite middleware mode 集成到 Express，单进程 HMR
+- **构建**: 前端 Vite build，服务端 tsc CJS 输出
+- **部署**: server.zip（服务端 + 裁剪 node_modules + run.sh）→ FaaS
+
+### vite-react（纯前端）
+
+- Vite 8 + React 19 + TypeScript 5 + Tailwind CSS 4 + shadcn/ui
+- ESLint 9 flat config + react-router-dom
+
+### html（纯前端）
 
-- **Vite 8** + React 19 + TypeScript 5
-- **Tailwind CSS 4**（`@tailwindcss/vite`，CSS-first 配置）
-- **shadcn/ui**（new-york 风格，lucide 图标，radix-ui 基础组件）
-- **ESLint 9** flat config
-- **react-router-dom** 客户端路由
+- 纯 HTML + Tailwind CDN，零构建依赖
 
 ## 发版
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-templates",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "OpenClaw project templates for mclaw CLI",
   "publishConfig": {
     "access": "public"

package/template-apex/README.md

@@ -118,6 +118,10 @@ app.use("/api/posts", postsRouter);
 
 ### 3. client/ — API 封装和页面
 
+> ⚠️ **客户端所有 HTTP 请求必须使用 `axiosForBackend`**
+>
+> `axiosForBackend` 由 `@lark-apaas/client-toolkit-lite` 提供，内置平台鉴权和请求上下文。**禁止使用** `fetch`、`axios`、`XMLHttpRequest` 或其他 HTTP 客户端直接发起请求。
+
 `client/src/api/index.ts` 增加封装：
 
 ```typescript
@@ -307,7 +311,7 @@ export default function DashboardPage() {
 | 页面拆分 | 页面文件只做骨架编排（无 state/effect/逻辑）；每个 Section 自包含数据+状态+类型；兄弟 Section 间无互相 import；单文件 ≤150 行 |
 | 命名规范 | 页面目录 PascalCase，页面入口文件与目录同名（PascalCase），组件文件名 kebab-case，组件名 PascalCase |
 | 路由注册 | 默认 `HomePage` 已替换为业务首页；新页面已在 `app.tsx` 注册；跳转使用 `<Link>` / `useNavigate()`，无 `<a href>` |
-| API 调用 | 统一在 `api/` 封装；使用 `@shared` 类型；组件内不直接 fetch |
+| API 调用 | 统一在 `api/` 封装；必须使用 `axiosForBackend` 发起请求，禁止 `fetch`/`axios`；使用 `@shared` 类型 |
 | 输入校验 | zod schema 定义在 `shared/api.interface.ts`；server 和 client 共用 |
 | 主题色 | 使用语义化变量类（`bg-background`、`text-primary` 等）；未硬编码颜色值 |
 | 主题修改 | 仅增量覆盖变更的变量；新增色同时注册 `:root` 和 `@theme inline` |

package/template-apex/client/index.html

@@ -9,10 +9,7 @@
   </head>
   <body>
     <script>
-      window.__APP_CONFIG__ = {
-        appId: "{{{appId}}}",
-        cdnDomain: "{{{cdnDomain}}}"
-      };
+      window.__APP_CONFIG__ = {{{appConfig}}};
     </script>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>

package/template-apex/client/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/template-apex/package.json

@@ -5,12 +5,14 @@
   "type": "module",
   "mclaw": {
     "stack": "apex",
-    "stackVersion": "0.1.0"
+    "stackVersion": "0.1.0",
+    "features": [
+      "client",
+      "server"
+    ]
   },
   "scripts": {
-    "dev": "npx tsx --watch server/index.ts & npx vite --host",
-    "dev:server": "tsx --watch server/index.ts",
-    "dev:client": "vite --host",
+    "dev": "tsx --watch --watch-path server --watch-path shared server/index.ts",
     "build": "bash scripts/build.sh",
     "lint": "npm run lint:client && npm run lint:server",
     "lint:client": "eslint client/src",
@@ -45,20 +47,20 @@
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.1.18",
     "@lark-apaas/client-toolkit-lite": "^0.0.2",
+    "@lark-apaas/express-core": "^0.0.3",
     "@formkit/auto-animate": "^0.9.0",
     "framer-motion": "^12.38.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
-    "drizzle-orm": "^0.45.1",
+    "drizzle-orm": "0.44.6",
     "embla-carousel-react": "^8.6.0",
     "express": "^5.1.0",
     "hbs": "^4.2.0",
     "input-otp": "^1.4.2",
     "lucide-react": "^1.7.0",
     "next-themes": "^0.4.6",
-    "postgres": "^3.4.8",
     "react": "^19.2.4",
     "react-day-picker": "^9.14.0",
     "react-dom": "^19.2.4",
@@ -76,6 +78,7 @@
   "devDependencies": {
     "@lark-apaas/coding-presets": "^0.2.0",
     "@lark-apaas/coding-vite-preset": "^0.1.0",
+    "@vercel/nft": "^0.29.2",
     "@types/express": "^5",
     "@types/node": "^24",
     "@types/react": "^19",

package/template-apex/scripts/build.sh

@@ -32,8 +32,7 @@ echo '{ "version": 1, "type": "apex", "fallback": "index.html" }' > "$OUTPUT/rou
 # 服务端产物（tsc 输出保留 server/、shared/ 子目录）
 cp -r "$ROOT/dist/server/"* "$OUTPUT/"
 
-# 复制 package.json（运行时需要依赖信息）
-cp "$ROOT/package.json" "$OUTPUT/package.json"
+# package.json 和 node_modules 由 mclaw-dev deploy 的 prune 步骤生成
 
 # 4. assets/ → dist/output_resource/（JS/CSS/字体，上传到 CDN）
 if [ -d "$ROOT/dist/client/assets" ]; then

package/template-apex/server/index.ts

@@ -1,34 +1,83 @@
-import express from "express";
+import express, { type Request, type Response } from "express";
 import path from "path";
 import fs from "fs";
-import { fileURLToPath } from "url";
 import hbs from "hbs";
+import { setup, safeStringify, createViewContextMiddleware } from "@lark-apaas/express-core";
+import * as schema from "./db/schema";
 import { registerRoutes } from "./routes/index";
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const port = Number(process.env.PORT) || 3000;
+const port = Number(process.env.FORCE_SERVER_PORT) || 3000;
+const host = process.env.FORCE_SERVER_HOST || "localhost";
+const isDev = process.env.NODE_ENV !== "production";
 
 const app = express();
 
-// JSON body parsing
-app.use(express.json());
+// Platform middleware: body parsing, cookie, user context, DB + RLS, view context
+const { close } = setup(app, {
+  database: { schema },
+  csrf: { enabled: false },
+  viewContext: { enabled: false },
+});
 
 // Register API routes
 registerRoutes(app);
 
-// Page rendering: compile index.html as hbs template, inject runtime data
-// Static assets (JS/CSS/images) are served by the deployment platform / CDN
-const templatePath = path.resolve(__dirname, "../public/index.html");
-const template = hbs.compile(fs.readFileSync(templatePath, "utf-8"));
+// HTML rendering: dev uses Vite middleware mode, prod reads build output
+async function setupHtmlRendering() {
+  if (isDev) {
+    // @ts-ignore -- vite types require bundler moduleResolution, dev-only import
+    const { createServer } = await import("vite");
+    const vite = await createServer({
+      server: { middlewareMode: true },
+      appType: "custom",
+    });
+
+    // Vite handles static assets, module serving, and HMR
+    app.use(vite.middlewares);
+
+    app.get("/{*path}", createViewContextMiddleware(), async (req: Request, res: Response) => {
+      const rawHtml = fs.readFileSync(
+        path.resolve(__dirname, "../client/index.html"),
+        "utf-8",
+      );
+      // Vite transform: inject HMR client, resolve module imports
+      const transformed = await vite.transformIndexHtml(req.originalUrl, rawHtml);
+      // HBS render: inject platform data
+      const template = hbs.compile(transformed);
+      const html = template({
+        ...res.locals,
+        appConfig: safeStringify({
+          appId: res.locals.appId || process.env.MCLAW_APP_ID || "",
+          cdnDomain: process.env.MCLAW_CDN_DOMAIN || "",
+        }),
+      });
+      res.type("html").send(html);
+    });
+  } else {
+    const templatePath = path.resolve(__dirname, "../index.html");
+    const template = hbs.compile(fs.readFileSync(templatePath, "utf-8"));
 
-app.get("*", (_req, res) => {
-  const html = template({
-    appId: process.env.MCLAW_APP_ID || "",
-    cdnDomain: process.env.MCLAW_CDN_DOMAIN || "",
+    app.get("/{*path}", createViewContextMiddleware(), (_req: Request, res: Response) => {
+      const html = template({
+        ...res.locals,
+        appConfig: safeStringify({
+          appId: res.locals.appId || process.env.MCLAW_APP_ID || "",
+          cdnDomain: process.env.MCLAW_CDN_DOMAIN || "",
+        }),
+      });
+      res.type("html").send(html);
+    });
+  }
+}
+
+setupHtmlRendering().then(() => {
+  const server = app.listen(port, host, () => {
+    console.log(`Server running at http://${host}:${port}`);
   });
-  res.type("html").send(html);
-});
 
-app.listen(port, "0.0.0.0", () => {
-  console.log(`Server running at http://localhost:${port}`);
+  // Graceful shutdown
+  process.on("SIGTERM", async () => {
+    server.close();
+    await close();
+  });
 });

package/template-apex/tsconfig.server.json

@@ -3,6 +3,10 @@
   "compilerOptions": {
     "outDir": "./dist/server",
     "rootDir": ".",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "verbatimModuleSyntax": false,
+    "esModuleInterop": true,
     "noEmit": false,
     "allowImportingTsExtensions": false,
     "noUnusedParameters": false,

package/template-html/package.json

@@ -4,7 +4,8 @@
   "private": true,
   "mclaw": {
     "stack": "html",
-    "stackVersion": "0.1.0"
+    "stackVersion": "0.1.0",
+    "features": ["client"]
   },
   "scripts": {
     "build": "bash scripts/build.sh"

package/template-vite-react/client/src/lib/utils.ts

@@ -1,6 +1,6 @@
-import { clsx, type ClassValue } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
 
 export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
+  return twMerge(clsx(inputs))
 }

package/template-vite-react/package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "mclaw": {
     "stack": "vite-react",
-    "stackVersion": "0.1.0"
+    "stackVersion": "0.1.0",
+    "features": ["client"]
   },
   "scripts": {
     "dev": "vite",

package/template-apex/server/db/index.ts

@@ -1,8 +0,0 @@
-import { drizzle } from "drizzle-orm/postgres-js";
-import postgres from "postgres";
-import * as schema from "./schema";
-
-const connectionString = process.env.DATABASE_URL!;
-const client = postgres(connectionString);
-
-export const db = drizzle(client, { schema });