@lark-apaas/coding-templates 0.1.19 → 0.1.23

package/package.json

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

package/template-apex/README.md

@@ -23,20 +23,20 @@
 │   ├── index.css              # 全局样式 + 主题变量
 │   ├── api/                   # API 请求封装
 │   │   └── index.ts
-│   ├── components/            # 全局共享组件
+│   ├── components/            # 基础 UI 组件（禁止存放业务组件）
 │   │   └── ui/                # shadcn/ui 内置组件（勿手动修改）
 │   ├── pages/                 # 页面模块（每个页面一个目录）
-│   │   ├── home/
-│   │   └── todos/             # CRUD 示例
-│   │       ├── index.tsx
-│   │       └── components/
+│   │   ├── HomePage/          # 占位示例页，开发时替换为业务首页
+│   │   │   └── HomePage.tsx   # 页面入口文件与目录同名
+│   │   │   └── components/    # 页面专属组件
+│   │   └── NotFoundPage/
+│   │       └── NotFoundPage.tsx
 │   ├── hooks/                 # 自定义 Hooks
 │   └── lib/                   # 工具函数（cn() 等）
 ├── server/                    # 后端代码
 │   ├── index.ts               # Express 入口（dev: Vite HMR 中间件）
 │   ├── routes/                # API 路由
-│   │   ├── index.ts           # 路由注册
-│   │   └── todos.ts           # Todos CRUD 路由
+│   │   └── index.ts           # 路由注册
 │   └── db/                    # 数据库层
 │       ├── schema.ts          # Drizzle schema 定义（可由工具生成）
 │       └── index.ts           # 数据库连接
@@ -47,16 +47,6 @@
 
 ---
 
-## 快速开始
-
-```bash
-npm install
-cp _env.local.example .env.local   # 配置 DATABASE_URL
-npm run dev                         # 启动开发服务器
-```
-
----
-
 ## 新增资源（以 posts 为例）
 
 ### 1. shared/ — 定义类型和校验
@@ -103,7 +93,7 @@ export const posts = pgTable("posts", {
 import { Router } from "express";
 import { db } from "../db/index";
 import { posts } from "../db/schema";
-import { createPostSchema } from "../../shared/api.interface";
+import { createPostSchema } from "@shared/api.interface";
 
 const router = Router();
 router.get("/", async (_req, res) => {
@@ -128,20 +118,29 @@ 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
-import type { CreatePostRequest, CreatePostResponse, ListPostsResponse } from "@shared/api.interface";
-
-export const postsApi = {
-  list: () => request<ListPostsResponse>("/api/posts"),
-  create: (data: CreatePostRequest) => request<CreatePostResponse>("/api/posts", {
-    method: "POST", body: JSON.stringify(data),
-  }),
-};
+import type { ListPostsResponse } from "@shared/api.interface";
+
+export async function listPosts(): Promise<ListPostsResponse> {
+  try {
+    const response = await axiosForBackend({
+      url: '/api/posts',
+      method: 'GET',
+    });
+    return response.data;
+  } catch (error) {
+    throw error;
+  }
+}
 ```
 
-`client/src/pages/posts/index.tsx` 编写页面，`client/src/app.tsx` 注册路由。
+`client/src/pages/PostsPage/PostsPage.tsx` 编写页面，`client/src/app.tsx` 注册路由。
 
 ---
 
@@ -150,7 +149,7 @@ export const postsApi = {
 **页面文件只做骨架编排，不包含具体 UI 实现。**
 
 ```tsx
-// client/src/pages/dashboard/index.tsx
+// client/src/pages/DashboardPage/DashboardPage.tsx
 import { StatsSection } from "./components/stats-section";
 import { DataTableSection } from "./components/data-table-section";
 
@@ -169,29 +168,57 @@ export default function DashboardPage() {
 - 每个视觉上独立的区块拆为一个组件文件，即使只出现一次
 - 单个组件文件不超过 **150 行**，超出时进一步拆分子组件
 - 页面专属组件放在 `pages/<page>/components/`
-- 跨页面复用的组件放在 `client/src/components/`
-- 相同 UI 片段出现 **≥2 次**时，必须提取为可复用组件
+- `client/src/components/` 仅存放基础 UI 组件（如 shadcn/ui），**禁止存放业务组件**
 - 文件名 kebab-case（`stat-card.tsx`），组件名 PascalCase（`StatCard`）
 - 组件之间**禁止循环引用**
 
+### Section 独立性（并行开发规范）
+
+每个 Section 级组件（如 `StatsSection`、`DataTableSection`）必须做到**完全自包含**：
+
+**1. 页面文件 = 纯布局组合器**
+
+- 页面入口文件（如 `DashboardPage.tsx`）只做 import + JSX 排列，**禁止包含** `useState`、`useEffect`、数据请求或业务逻辑
+- 页面文件无 props 接口定义，不承担任何数据协调职责
+
+**2. Section 自包含原则**
+
+每个 Section 组件独立拥有自己的：
+- **数据获取**（API 调用、fetch）— 即使多个 Section 需要同一份数据，各自获取
+- **状态管理**（useState、useReducer）
+- **类型定义**（写在同文件或同目录下的 `types.ts`）
+- **子组件**（如需拆分，平铺在 `components/` 目录下，禁止嵌套子目录）
+
+**3. 禁止 Section 间横向依赖**
+
+- 兄弟 Section 之间**禁止互相 import**
+- 兄弟 Section 之间**禁止通过 Context、全局 store、事件总线、页面 props 共享状态**
+- 每个 Section 可独立开发、独立测试，不依赖其他 Section 的存在
+
 ---
 
 ## 路由注册
 
-新增页面在 `client/src/app.tsx` 中注册：
+新增页面在 `client/src/app.tsx` 中注册。
+
+> ⚠️ **首页路由替换（必做）**
+>
+> 模板默认的 `HomePage` 是占位示例页，**不是业务首页**。开发时必须将 `index` 路由替换为真实的业务首页组件（如 `DashboardPage`），并删除 `HomePage` 目录。
+
+**替换后的路由示例：**
 
 ```tsx
 <Route element={<Layout />}>
-  <Route index element={<HomePage />} />
+  {/* 将 index 路由指向真实的业务首页 */}
+  <Route index element={<DashboardPage />} />
   <Route path="todos" element={<TodosPage />} />
-  <Route path="dashboard" element={<DashboardPage />} />
   <Route path="*" element={<NotFoundPage />} />
 </Route>
 ```
 
 **新增页面步骤：**
 
-1. 在 `client/src/pages/` 下新建页面目录和 `index.tsx`
+1. 在 `client/src/pages/` 下新建页面目录（如 `SettingsPage`）和 `SettingsPage.tsx`
 2. 在 `app.tsx` 的 `<Routes>` 内添加 `<Route>` 配置
 
 **路由跳转必须使用 react-router-dom：**
@@ -281,10 +308,10 @@ export default function DashboardPage() {
 
 | 检查项 | 验收标准 |
 |--------|---------|
-| 页面拆分 | 页面文件只做骨架编排；每个区块为独立组件；单文件 ≤150 行 |
-| 组件复用 | 相同片段 ≥2 次已提取为组件；文件名 kebab-case，组件名 PascalCase |
-| 路由注册 | 新页面已在 `app.tsx` 注册；跳转使用 `<Link>` / `useNavigate()`，无 `<a href>` |
-| API 调用 | 统一在 `api/` 封装；使用 `@shared` 类型；组件内不直接 fetch |
+| 页面拆分 | 页面文件只做骨架编排（无 state/effect/逻辑）；每个 Section 自包含数据+状态+类型；兄弟 Section 间无互相 import；单文件 ≤150 行 |
+| 命名规范 | 页面目录 PascalCase，页面入口文件与目录同名（PascalCase），组件文件名 kebab-case，组件名 PascalCase |
+| 路由注册 | 默认 `HomePage` 已替换为业务首页；新页面已在 `app.tsx` 注册；跳转使用 `<Link>` / `useNavigate()`，无 `<a href>` |
+| 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/src/api/index.ts

@@ -1,39 +1,17 @@
-import type {
-  CreateTodoRequest,
-  CreateTodoResponse,
-  UpdateTodoRequest,
-  UpdateTodoResponse,
-  DeleteTodoResponse,
-  ListTodosResponse,
-} from "@shared/api.interface";
+import { axiosForBackend } from '@lark-apaas/client-toolkit-lite/utils/getAxiosForBackend';
+// import type { ListPostsResponse } from '@shared/api.interface';
 
-async function request<T>(url: string, options?: RequestInit): Promise<T> {
-  const res = await fetch(url, {
-    headers: { "Content-Type": "application/json" },
-    ...options,
-  });
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error?.toString() ?? `Request failed: ${res.status}`);
-  }
-  return res.json();
-}
-
-export const todosApi = {
-  list: () => request<ListTodosResponse>("/api/todos"),
-
-  create: (data: CreateTodoRequest) =>
-    request<CreateTodoResponse>("/api/todos", {
-      method: "POST",
-      body: JSON.stringify(data),
-    }),
-
-  update: (id: number, data: UpdateTodoRequest) =>
-    request<UpdateTodoResponse>(`/api/todos/${id}`, {
-      method: "PATCH",
-      body: JSON.stringify(data),
-    }),
-
-  remove: (id: number) =>
-    request<DeleteTodoResponse>(`/api/todos/${id}`, { method: "DELETE" }),
-};
+// Add more API functions here, use axios instance (`axiosForBackend`) to make requests.
+//
+// 使用示例：
+// export async function listPosts(): Promise<ListPostsResponse> {
+//   try {
+//     const response = await axiosForBackend({
+//       url: '/api/posts',
+//       method: 'GET',
+//     });
+//     return response.data;
+//   } catch (error) {
+//     throw error;
+//   }
+// }

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

@@ -1,8 +1,7 @@
 import { BrowserRouter, Routes, Route } from "react-router-dom";
 import { Layout } from "@/components/layout";
-import HomePage from "@/pages/home";
-import TodosPage from "@/pages/todos";
-import NotFoundPage from "@/pages/not-found";
+import HomePage from "@/pages/HomePage/HomePage";
+import NotFoundPage from "@/pages/NotFoundPage/NotFoundPage";
 
 export default function App() {
   return (
@@ -10,7 +9,6 @@ export default function App() {
       <Routes>
         <Route element={<Layout />}>
           <Route index element={<HomePage />} />
-          <Route path="todos" element={<TodosPage />} />
           <Route path="*" element={<NotFoundPage />} />
         </Route>
       </Routes>

package/template-apex/client/src/components/layout.tsx

@@ -2,10 +2,8 @@ import { Outlet } from "react-router-dom";
 
 export function Layout() {
   return (
-    <div className="min-h-screen bg-background text-foreground">
-      <main className="container mx-auto px-4 py-8">
-        <Outlet />
-      </main>
+    <div className="w-screen h-screen">
+      <Outlet />
     </div>
   );
 }

package/template-apex/client/src/pages/HomePage/HomePage.tsx

@@ -0,0 +1,12 @@
+export default function HomePage() {
+  return (
+    <div className="flex flex-col items-center justify-center py-24">
+      <h1 className="text-5xl font-bold tracking-tight sm:text-7xl mb-4">
+        👋 Hello OpenClaw
+      </h1>
+      <p className="text-lg text-muted-foreground">
+        Start building your app by editing <code className="px-1.5 py-0.5 rounded bg-muted font-mono text-sm">client/src/pages/HomePage/HomePage.tsx</code>
+      </p>
+    </div>
+  );
+}

package/template-apex/package.json

@@ -74,7 +74,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@lark-apaas/coding-presets": "^0.1.0",
+    "@lark-apaas/coding-presets": "^0.2.0",
     "@lark-apaas/coding-vite-preset": "^0.1.0",
     "@types/express": "^5",
     "@types/node": "^24",

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

@@ -1,8 +1,11 @@
-import { pgTable, serial, text, boolean, timestamp } from "drizzle-orm/pg-core";
-
-export const todos = pgTable("todos", {
-  id: serial("id").primaryKey(),
-  title: text("title").notNull(),
-  completed: boolean("completed").notNull().default(false),
-  createdAt: timestamp("created_at").notNull().defaultNow(),
-});
+// 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(),
+// });

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

@@ -1,6 +1,9 @@
 import type { Express } from "express";
-import todosRouter from "./todos";
+// import postsRouter from "./posts";
 
 export function registerRoutes(app: Express) {
-  app.use("/api/todos", todosRouter);
+  // 在此注册 API 路由
+  //
+  // 使用示例：
+  // app.use("/api/posts", postsRouter);
 }

package/template-apex/shared/api.interface.ts

@@ -1,23 +1,13 @@
 // API 接口契约定义
 // zod schema 做校验，z.infer 推导类型，前后端共享
-
-import { z } from "zod";
-import type { Todo } from "./types";
-
-// ----- Todos -----
-
-export const createTodoSchema = z.object({
-  title: z.string().min(1).max(500),
-});
-
-export const updateTodoSchema = z.object({
-  title: z.string().min(1).max(500).optional(),
-  completed: z.boolean().optional(),
-});
-
-export type CreateTodoRequest = z.infer<typeof createTodoSchema>;
-export type UpdateTodoRequest = z.infer<typeof updateTodoSchema>;
-export type CreateTodoResponse = Todo;
-export type UpdateTodoResponse = Todo;
-export type DeleteTodoResponse = Todo;
-export type ListTodosResponse = Todo[];
+//
+// import { z } from "zod";
+// import type { Post } from "./types";
+//
+// 使用示例：
+// export const createPostSchema = z.object({
+//   title: z.string().min(1).max(200),
+//   content: z.string().optional(),
+// });
+// export type CreatePostRequest = z.infer<typeof createPostSchema>;
+// export type CreatePostResponse = Post;

package/template-apex/shared/types.ts

@@ -1,9 +1,10 @@
 // 前后端共享类型定义
 // shared 是最底层模块，不依赖 client 或 server
-
-export interface Todo {
-  id: number;
-  title: string;
-  completed: boolean;
-  createdAt: string;
-}
+//
+// 使用示例：
+// export interface Post {
+//   id: number;
+//   title: string;
+//   content: string | null;
+//   createdAt: string;
+// }

package/template-apex/tsconfig.server.json

@@ -4,6 +4,8 @@
     "outDir": "./dist/server",
     "rootDir": ".",
     "noEmit": false,
+    "allowImportingTsExtensions": false,
+    "noUnusedParameters": false,
     "baseUrl": ".",
     "paths": {
       "@shared/*": ["./shared/*"]

package/template-apex/client/src/pages/home/index.tsx

@@ -1,20 +0,0 @@
-import { Link } from "react-router-dom";
-
-export default function HomePage() {
-  return (
-    <div className="flex flex-col items-center justify-center py-24">
-      <h1 className="text-5xl font-bold tracking-tight sm:text-7xl mb-4">
-        Hello OpenClaw
-      </h1>
-      <p className="text-lg text-muted-foreground mb-8">
-        Apex full-stack template
-      </p>
-      <Link
-        to="/todos"
-        className="inline-flex items-center justify-center rounded-md bg-primary px-6 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90"
-      >
-        Try the Todos Demo
-      </Link>
-    </div>
-  );
-}

package/template-apex/client/src/pages/todos/components/todo-form.tsx

@@ -1,40 +0,0 @@
-import { useState } from "react";
-
-interface TodoFormProps {
-  onSubmit: (title: string) => Promise<void>;
-}
-
-export function TodoForm({ onSubmit }: TodoFormProps) {
-  const [title, setTitle] = useState("");
-  const [submitting, setSubmitting] = useState(false);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    const trimmed = title.trim();
-    if (!trimmed) return;
-    setSubmitting(true);
-    await onSubmit(trimmed);
-    setTitle("");
-    setSubmitting(false);
-  };
-
-  return (
-    <form onSubmit={handleSubmit} className="flex gap-2">
-      <input
-        type="text"
-        value={title}
-        onChange={(e) => setTitle(e.target.value)}
-        placeholder="What needs to be done?"
-        className="flex-1 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-        disabled={submitting}
-      />
-      <button
-        type="submit"
-        disabled={submitting || !title.trim()}
-        className="inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:pointer-events-none disabled:opacity-50"
-      >
-        Add
-      </button>
-    </form>
-  );
-}

package/template-apex/client/src/pages/todos/components/todo-list.tsx

@@ -1,43 +0,0 @@
-import type { Todo } from "@shared/types";
-import { Trash2 } from "lucide-react";
-
-interface TodoListProps {
-  todos: Todo[];
-  onToggle: (id: number, completed: boolean) => Promise<void>;
-  onDelete: (id: number) => Promise<void>;
-}
-
-export function TodoList({ todos, onToggle, onDelete }: TodoListProps) {
-  if (todos.length === 0) {
-    return <p className="text-muted-foreground mt-8 text-center">No todos yet.</p>;
-  }
-
-  return (
-    <ul className="mt-6 space-y-2">
-      {todos.map((todo) => (
-        <li
-          key={todo.id}
-          className="flex items-center gap-3 rounded-md border border-border px-4 py-3"
-        >
-          <input
-            type="checkbox"
-            checked={todo.completed}
-            onChange={() => onToggle(todo.id, !todo.completed)}
-            className="h-4 w-4 rounded border-border"
-          />
-          <span
-            className={`flex-1 text-sm ${todo.completed ? "line-through text-muted-foreground" : ""}`}
-          >
-            {todo.title}
-          </span>
-          <button
-            onClick={() => onDelete(todo.id)}
-            className="text-muted-foreground hover:text-destructive transition-colors"
-          >
-            <Trash2 className="h-4 w-4" />
-          </button>
-        </li>
-      ))}
-    </ul>
-  );
-}

package/template-apex/client/src/pages/todos/index.tsx

@@ -1,47 +0,0 @@
-import { useEffect, useState } from "react";
-import type { Todo } from "@shared/types";
-import { todosApi } from "@/api";
-import { TodoForm } from "./components/todo-form";
-import { TodoList } from "./components/todo-list";
-
-export default function TodosPage() {
-  const [todos, setTodos] = useState<Todo[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  const refresh = async () => {
-    const list = await todosApi.list();
-    setTodos(list);
-    setLoading(false);
-  };
-
-  useEffect(() => {
-    refresh();
-  }, []);
-
-  const handleCreate = async (title: string) => {
-    await todosApi.create({ title });
-    await refresh();
-  };
-
-  const handleToggle = async (id: number, completed: boolean) => {
-    await todosApi.update(id, { completed });
-    await refresh();
-  };
-
-  const handleDelete = async (id: number) => {
-    await todosApi.remove(id);
-    await refresh();
-  };
-
-  return (
-    <div className="max-w-2xl mx-auto py-12">
-      <h1 className="text-3xl font-bold mb-8">Todos</h1>
-      <TodoForm onSubmit={handleCreate} />
-      {loading ? (
-        <p className="text-muted-foreground mt-8">Loading...</p>
-      ) : (
-        <TodoList todos={todos} onToggle={handleToggle} onDelete={handleDelete} />
-      )}
-    </div>
-  );
-}

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

@@ -1,53 +0,0 @@
-import { Router } from "express";
-import { eq, desc } from "drizzle-orm";
-import { db } from "../db/index";
-import { todos } from "../db/schema";
-import { createTodoSchema, updateTodoSchema } from "../../shared/api.interface";
-
-const router = Router();
-
-// GET /api/todos
-router.get("/", async (_req, res) => {
-  const list = await db.select().from(todos).orderBy(desc(todos.createdAt));
-  res.json(list);
-});
-
-// POST /api/todos
-router.post("/", async (req, res) => {
-  const parsed = createTodoSchema.safeParse(req.body);
-  if (!parsed.success) {
-    res.status(400).json({ error: parsed.error.flatten() });
-    return;
-  }
-  const [todo] = await db.insert(todos).values({ title: parsed.data.title }).returning();
-  res.status(201).json(todo);
-});
-
-// PATCH /api/todos/:id
-router.patch("/:id", async (req, res) => {
-  const id = Number(req.params.id);
-  const parsed = updateTodoSchema.safeParse(req.body);
-  if (!parsed.success) {
-    res.status(400).json({ error: parsed.error.flatten() });
-    return;
-  }
-  const [todo] = await db.update(todos).set(parsed.data).where(eq(todos.id, id)).returning();
-  if (!todo) {
-    res.status(404).json({ error: "Not found" });
-    return;
-  }
-  res.json(todo);
-});
-
-// DELETE /api/todos/:id
-router.delete("/:id", async (req, res) => {
-  const id = Number(req.params.id);
-  const [todo] = await db.delete(todos).where(eq(todos.id, id)).returning();
-  if (!todo) {
-    res.status(404).json({ error: "Not found" });
-    return;
-  }
-  res.json(todo);
-});
-
-export default router;