@lark-apaas/coding-templates 0.1.35 → 0.1.37

package/package.json

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

package/template-apex/README.md

@@ -19,7 +19,8 @@
 
 ```
 ├── client/src/                # 前端代码
-│   ├── app.tsx                # 路由注册
+│   ├── main.tsx               # 入口（Provider 层级 + 样式引入，勿修改）
+│   ├── app.tsx                # 路由配置
 │   ├── index.css              # 全局样式 + 主题变量
 │   ├── api/                   # API 请求封装
 │   │   └── index.ts
@@ -34,12 +35,12 @@
 │   ├── hooks/                 # 自定义 Hooks
 │   └── lib/                   # 工具函数（cn() 等）
 ├── server/                    # 后端代码
-│   ├── index.ts               # Express 入口（dev: Vite HMR 中间件）
-│   ├── routes/                # API 路由
-│   │   └── index.ts           # 路由注册
+│   ├── index.ts               # Express 入口
+│   ├── routes/                # 路由
+│   │   ├── index.ts           # 路由注册
+│   │   └── view.ts            # 页面渲染（catch-all HTML 响应，勿修改）
 │   └── db/                    # 数据库层
-│       ├── schema.ts          # Drizzle schema 定义（可由工具生成）
-│       └── index.ts           # 数据库连接
+│       ├── schema.ts          # Drizzle schema 定义（工具自动生成，勿手动修改）
 ├── shared/                    # 前后端共享（不依赖 client 或 server）
 │   ├── types.ts               # 数据模型类型
 │   └── api.interface.ts       # zod schema + API 入参/出参类型
@@ -76,7 +77,7 @@ export type ListPostsResponse = Post[];
 
 ### 2. server/ — 数据库和路由
 
-`server/db/schema.ts` 增加表定义：
+`server/db/schema.ts` 由 `npm run gen:db-schema` 自动生成，无需手动编写。运行命令后会根据数据库表结构自动生成如下定义：
 
 ```typescript
 export const posts = pgTable("posts", {
@@ -91,7 +92,7 @@ export const posts = pgTable("posts", {
 
 ```typescript
 import { Router } from "express";
-import { db } from "../db/index";
+import { db } from "@lark-apaas/express-core";
 import { posts } from "../db/schema";
 import { createPostSchema } from "@shared/api.interface";
 
@@ -120,11 +121,12 @@ app.use("/api/posts", postsRouter);
 
 > ⚠️ **客户端所有 HTTP 请求必须使用 `axiosForBackend`**
 >
-> `axiosForBackend` 由 `@lark-apaas/client-toolkit-lite` 提供，内置平台鉴权和请求上下文。**禁止使用** `fetch`、`axios`、`XMLHttpRequest` 或其他 HTTP 客户端直接发起请求。
+> `axiosForBackend` 由 `@lark-apaas/client-toolkit-lite` 提供，内置平台鉴权、CSRF token 注入和请求上下文。**禁止使用** `fetch`、`axios`、`XMLHttpRequest` 或其他 HTTP 客户端直接发起请求。
 
 `client/src/api/index.ts` 增加封装：
 
 ```typescript
+import { axiosForBackend } from "@lark-apaas/client-toolkit-lite";
 import type { ListPostsResponse } from "@shared/api.interface";
 
 export async function listPosts(): Promise<ListPostsResponse> {
@@ -216,6 +218,8 @@ export default function DashboardPage() {
 </Route>
 ```
 
+> **注意：** `BrowserRouter` 已在 `main.tsx` 中统一配置，`app.tsx` 中**禁止**再包裹 `BrowserRouter`，否则会报嵌套 Router 错误。
+
 **新增页面步骤：**
 
 1. 在 `client/src/pages/` 下新建页面目录（如 `SettingsPage`）和 `SettingsPage.tsx`

package/template-apex/client/src/app.tsx

@@ -1,17 +1,15 @@
-import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { Routes, Route } from "react-router-dom";
 import { Layout } from "@/components/layout";
 import HomePage from "@/pages/HomePage/HomePage";
 import NotFoundPage from "@/pages/NotFoundPage/NotFoundPage";
 
 export default function App() {
   return (
-    <BrowserRouter basename={process.env.CLIENT_BASE_PATH || '/'}>
-      <Routes>
-        <Route element={<Layout />}>
-          <Route index element={<HomePage />} />
-          <Route path="*" element={<NotFoundPage />} />
-        </Route>
-      </Routes>
-    </BrowserRouter>
+    <Routes>
+      <Route element={<Layout />}>
+        <Route index element={<HomePage />} />
+        <Route path="*" element={<NotFoundPage />} />
+      </Route>
+    </Routes>
   );
 }

package/template-apex/client/src/main.tsx

@@ -1,14 +1,16 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
 import { AppContainer } from "@lark-apaas/client-toolkit-lite";
-import "@lark-apaas/client-toolkit-lite/styles.css";
 import App from "./app";
 import "./index.css";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <AppContainer>
-      <App />
-    </AppContainer>
+    <BrowserRouter basename={process.env.CLIENT_BASE_PATH || "/"}>
+      <AppContainer>
+        <App />
+      </AppContainer>
+    </BrowserRouter>
   </StrictMode>,
 );

package/template-apex/package.json

@@ -11,11 +11,11 @@
     ]
   },
   "scripts": {
-    "dev": "tsx --watch --watch-path server --watch-path shared server/index.ts",
     "build": "bash scripts/build.sh",
-    "typecheck": "npm run typecheck:client",
+    "typecheck": "concurrently npm:typecheck:client npm:typecheck:server",
     "typecheck:client": "tsc -p tsconfig.app.json",
-    "lint": "npm run typecheck && npm run lint:client && npm run lint:server",
+    "typecheck:server": "tsc --noEmit -p tsconfig.server.json",
+    "lint": "concurrently npm:typecheck npm:lint:client npm:lint:server",
     "lint:client": "eslint client/src",
     "lint:server": "eslint server",
     "gen:db-schema": "npx -y @lark-apaas/db-schema-sync@latest --output server/db/schema.ts"
@@ -48,8 +48,8 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.1.18",
-    "@lark-apaas/client-toolkit-lite": "^1.0.0",
-    "@lark-apaas/express-core": "^0.0.9",
+    "@lark-apaas/client-toolkit-lite": "^1.1.0",
+    "@lark-apaas/express-core": "^1.0.0",
     "@formkit/auto-animate": "^0.9.0",
     "framer-motion": "^12.38.0",
     "class-variance-authority": "^0.7.1",
@@ -57,6 +57,8 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "drizzle-orm": "0.44.6",
+    "echarts": "~5.6.0",
+    "echarts-for-react": "~3.0.2",
     "embla-carousel-react": "^8.6.0",
     "express": "^5.1.0",
     "hbs": "^4.2.0",
@@ -85,6 +87,7 @@
     "@types/node": "^24",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "concurrently": "^9",
     "eslint": "^9",
     "tsc-alias": "^1.8.15",
     "tsx": "^4",

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

@@ -1,11 +1 @@
-// Drizzle schema 定义（可由工具生成）
-//
-// import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
-//
-// 使用示例：
-// export const posts = pgTable("posts", {
-//   id: serial("id").primaryKey(),
-//   title: text("title").notNull(),
-//   content: text("content"),
-//   createdAt: timestamp("created_at").notNull().defaultNow(),
-// });
+/* 该文件通过 npm run gen:db-schema 自动生成*/

package/template-apex/server/index.ts

@@ -1,9 +1,5 @@
-import express, { type Request, type Response } from "express";
-import path from "path";
-import fs from "fs";
-import hbs from "hbs";
-import { setup, createViewContextMiddleware } from "@lark-apaas/express-core";
-import * as schema from "./db/schema";
+import express from "express";
+import { setup } from "@lark-apaas/express-core";
 import { registerRoutes } from "./routes/index";
 
 const port = Number(process.env.FORCE_SERVER_PORT) || 3000;
@@ -13,26 +9,12 @@ const basePath = process.env.CLIENT_BASE_PATH || "/";
 const app = express();
 
 // Platform middleware
-const { close } = setup(app, {
-  database: { schema },
-  csrf: { enabled: false },
-  viewContext: { enabled: false },
-});
+const { close } = setup(app);
 
 // All routes under basePath
 const router = express.Router();
 registerRoutes(router);
 
-const templatePath = path.resolve(__dirname, "../index.html");
-const template = hbs.compile(fs.readFileSync(templatePath, "utf-8"));
-
-router.get("/{*path}", createViewContextMiddleware(), (_req: Request, res: Response) => {
-  const html = template({
-    ...res.locals,
-  });
-  res.type("html").send(html);
-});
-
 app.use(basePath, router);
 
 const server = app.listen(port, host, () => {

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

@@ -1,9 +1,13 @@
 import type { Router } from "express";
+import { registerViewRoute } from "./view";
 // import postsRouter from "./posts";
 
-export function registerRoutes(app: Router) {
+export function registerRoutes(router: Router) {
   // 在此注册 API 路由
   //
   // 使用示例：
-  // app.use("/api/posts", postsRouter);
+  // router.use("/api/posts", postsRouter);
+
+  // HTML 页面渲染（catch-all，必须放在最后）
+  registerViewRoute(router);
 }

package/template-apex/server/routes/view.ts

@@ -0,0 +1,16 @@
+import path from "path";
+import fs from "fs";
+import hbs from "hbs";
+import type { Request, Response, Router } from "express";
+
+const templatePath = path.resolve(__dirname, "../../index.html");
+const template = hbs.compile(fs.readFileSync(templatePath, "utf-8"));
+
+export function registerViewRoute(router: Router) {
+  router.get("/{*path}", (_req: Request, res: Response) => {
+    const html = template({
+      ...res.locals,
+    });
+    res.type("html").send(html);
+  });
+}

package/template-apex/tsconfig.server.json

@@ -5,11 +5,9 @@
     "rootDir": ".",
     "module": "commonjs",
     "moduleResolution": "node",
-    "verbatimModuleSyntax": false,
     "esModuleInterop": true,
     "noEmit": false,
     "allowImportingTsExtensions": false,
-    "noUnusedParameters": false,
     "baseUrl": ".",
     "paths": {
       "@shared/*": ["./shared/*"]

package/template-vite-react/README.md

@@ -16,7 +16,8 @@
 
 ```
 client/src/
-├── app.tsx              # 路由注册
+├── main.tsx             # 入口（Provider 层级 + 样式引入，勿修改）
+├── app.tsx              # 路由配置
 ├── index.css            # 全局样式 + 主题变量
 ├── components/          # 基础 UI 组件（禁止存放业务组件）
 │   └── ui/              # shadcn/ui 内置组件（勿手动修改）
@@ -94,28 +95,26 @@ export default function DashboardPage() {
 **替换后的路由示例：**
 
 ```tsx
-import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { Routes, Route } from "react-router-dom";
 import { Layout } from "@/components/layout";
 import DashboardPage from "@/pages/DashboardPage/DashboardPage";
 import NotFoundPage from "@/pages/NotFoundPage/NotFoundPage";
 
-declare const __APP_BASE_PATH__: string;
-
 export default function App() {
   return (
-    <BrowserRouter basename={__APP_BASE_PATH__}>
-      <Routes>
-        <Route element={<Layout />}>
-          {/* 将 index 路由指向真实的业务首页 */}
-          <Route index element={<DashboardPage />} />
-          <Route path="*" element={<NotFoundPage />} />
-        </Route>
-      </Routes>
-    </BrowserRouter>
+    <Routes>
+      <Route element={<Layout />}>
+        {/* 将 index 路由指向真实的业务首页 */}
+        <Route index element={<DashboardPage />} />
+        <Route path="*" element={<NotFoundPage />} />
+      </Route>
+    </Routes>
   );
 }
 ```
 
+> **注意：** `BrowserRouter` 已在 `main.tsx` 中统一配置，`app.tsx` 中**禁止**再包裹 `BrowserRouter`，否则会报嵌套 Router 错误。
+
 **新增页面步骤：**
 
 1. 在 `client/src/pages/` 下新建页面目录（如 `SettingsPage`）和 `SettingsPage.tsx`

package/template-vite-react/client/src/app.tsx

@@ -1,17 +1,15 @@
-import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { Routes, Route } from "react-router-dom";
 import { Layout } from "@/components/layout";
 import HomePage from "@/pages/HomePage/HomePage";
 import NotFoundPage from "@/pages/NotFoundPage/NotFoundPage";
 
 export default function App() {
   return (
-    <BrowserRouter basename={process.env.CLIENT_BASE_PATH || '/'}>
-      <Routes>
-        <Route element={<Layout />}>
-          <Route index element={<HomePage />} />
-          <Route path="*" element={<NotFoundPage />} />
-        </Route>
-      </Routes>
-    </BrowserRouter>
+    <Routes>
+      <Route element={<Layout />}>
+        <Route index element={<HomePage />} />
+        <Route path="*" element={<NotFoundPage />} />
+      </Route>
+    </Routes>
   );
 }

package/template-vite-react/client/src/main.tsx

@@ -1,14 +1,16 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
 import { AppContainer } from "@lark-apaas/client-toolkit-lite";
-import "@lark-apaas/client-toolkit-lite/styles.css";
 import App from "./app";
 import "./index.css";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <AppContainer>
-      <App />
-    </AppContainer>
+    <BrowserRouter basename={process.env.CLIENT_BASE_PATH || "/"}>
+      <AppContainer>
+        <App />
+      </AppContainer>
+    </BrowserRouter>
   </StrictMode>,
 );

package/template-vite-react/package.json

@@ -10,13 +10,10 @@
     ]
   },
   "scripts": {
-    "dev": "vite",
     "build": "bash scripts/build.sh",
-    "typecheck": "npm run typecheck:client",
-    "typecheck:client": "tsc -p tsconfig.app.json",
-    "lint": "npm run typecheck && npm run lint:client",
-    "lint:client": "eslint client/src",
-    "preview": "vite preview"
+    "typecheck": "tsc -p tsconfig.app.json",
+    "lint": "concurrently npm:typecheck npm:lint:eslint",
+    "lint:eslint": "eslint client/src"
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -46,7 +43,7 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.1.18",
-    "@lark-apaas/client-toolkit-lite": "^1.0.0",
+    "@lark-apaas/client-toolkit-lite": "^1.1.0",
     "@formkit/auto-animate": "^0.9.0",
     "framer-motion": "^12.38.0",
     "class-variance-authority": "^0.7.1",
@@ -80,6 +77,7 @@
     "@types/react-dom": "^19",
     "@lark-apaas/coding-presets": "^1.0.0",
     "@lark-apaas/coding-vite-preset": "^1.0.0",
+    "concurrently": "^9",
     "eslint": "^9",
     "eslint-plugin-react-hooks": "^7",
     "eslint-plugin-react-refresh": "^0.5",

package/template-apex/_env.local.example

@@ -1 +0,0 @@
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/openclaw