模块开发教程

本框架采用了模块化的前端开发模式，旨在提高代码的可维护性和可扩展性。

开发流程

本实践提倡新功能开发遵循以下步骤：

1. 前端开发（表现和行为层）
2. 后端开发（API）
3. 前端联调（数据层）

基于AI辅助的开发模式和传统开发模式有所不同。传统的开发模式强调并行开发，一般先设计程序，再设计服务接口标准，然后开发人员基于该接口标准分别实现前后端程序，再联调测试。而基于AI辅助的开发实践一般提倡“原型既前端”，将功能设计和前端开发过程合并，在根据前端设计开发后端服务。

模块结构

如果您正在开发一个新的业务模块（例如 products），请将其放置在 src/modules/ 目录下。该目录下的模块支持自动路由和菜单注册。

请遵循以下目录结构：

src/modules/products/
├── components/          # 模块私有组件
├── Products.tsx         # 主页面
├── ProductDetail.tsx    # 详情页
├── routes.tsx           # 路由配置文件 (自动注册)
├── menu.ts              # 菜单配置文件 (自动注册)
└── package.json         # 模块包定义 (自动注册)

定义模块包

在模块目录下创建 package.json，系统会自动将其注册到模块管理中。

// src/modules/products/package.json
{
  "name": "@pocketstack/products",
  "version": "1.0.0",
  "title": "产品管理",
  "description": "产品管理模块，提供产品列表、详情等功能",
  "private": true,
  "type": "module",
  "dependencies": {},
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

字段	说明	必填
name	包名，格式为 @pocketstack/{module}	是
version	版本号	是
title	模块显示名称	是
description	模块描述	否
private	是否私有，固定为 true	是
type	模块类型，固定为 module	是
dependencies	模块依赖，不需要可为空对象 {}	否
peerDependencies	同级依赖，固定包含 react 和 react-dom	是

注意：dependencies 不要和根目录 package.json 中的依赖冲突、重复。

创建页面组件

在模块目录下创建页面文件，文件命名遵循大驼峰。

// src/modules/products/Products.tsx
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';

export function Products() {
  return (
    <div className="space-y-6">
      <h1 className="text-3xl font-bold">产品管理</h1>
      <Card>
        <CardHeader>
          <CardTitle>产品列表</CardTitle>
        </CardHeader>
        <CardContent>
          {/* 功能实现代码 */}
        </CardContent>
      </Card>
    </div>
  );
}

配置模块路由

在模块目录下创建 routes.tsx，导出名为 routes 的变量。系统会自动将其注册到主路由中。

// src/modules/products/routes.tsx
import { Route } from 'react-router-dom';
import { Products } from './Products';

export const routes = (
  <>
    <Route path="products/list" element={<Products />} />
    {/* 其他路由... */}
  </>
);

注意：无需在 src/App.tsx 中手动导入。

配置模块菜单

在模块目录下创建 menu.ts，导出名为 menu 的变量。系统会自动将其添加到侧边栏。

// src/modules/products/menu.ts
import { PackageIcon } from '@heroicons/react/24/outline';

export const menu = {
  title: '产品管理',
  icon: PackageIcon,
  children: [
    { title: '产品列表', path: '/products/list' },
  ],
};

注意：无需在 src/components/menu.ts 中手动导入。

后端开发

无论通过 PocketBase 提供的 UI 界面，还是通过 MCP （强烈推荐），后端开发都基于以下流程：

1. 启动 PocketBase 控制台 (默认 http://127.0.0.1:8090/_/)。
2. 创建新的 Collection (例如 posts, products 等)。
3. 配置字段类型并设置 API Rules (ACL)，确保安全访问。
4. 创建 Mock 数据，以便于联调。

开发规则总结

• 目录位置：必须放置在 src/modules/ 目录下。
• 包定义：必须包含 package.json 文件。
• 自动注册导出名：路由必须导出为 routes，菜单必须导出为 menu。
• 页面命名：遵循大驼峰（如 Products.tsx）。
• 组件位置：模块私有组件存放在模块目录下的 components/。
• 路径规范：页面的访问路径通常为 /{module}/{page}。