本地开发与项目结构¶

1. 环境要求¶

Node.js 24.x；
pnpm 10.x；
与项目 lockfile 兼容的 Linux 构建环境用于生产镜像；
可访问项目配置的后端 API 和可选辅助服务。

项目约定使用 pnpm，不使用 npm 或 yarn。保存或迁移项目时应同时保留 pnpm-lock.yaml、.npmrc、pnpm-workspace.yaml 和 patches/。

2. 安装和启动¶

pnpm install
pnpm dev

默认开发服务器由 Next.js 启动。实际端口以终端输出为准。

常用命令：

命令	说明
`pnpm dev`	启动开发服务器
`pnpm build`	生成生产构建
`pnpm start`	启动 Next.js 生产服务器
`pnpm lint`	执行 ESLint 修复及 Prettier 检查
`pnpm lint:js`	执行 ESLint，包含 `--fix`，会修改文件
`pnpm lint:prettier`	检查 `src/*/` 格式
`pnpm prettier`	写回格式化结果

Warning

当前项目没有统一的 test 脚本。不能把“没有测试失败”当作功能已经验证，关键业务链路需要进行构建检查和手工验证。

3. 主要目录¶

src/
├── app/              # App Router 页面、布局、Route Handler
├── components/       # 复杂 UI 与业务组件
├── hooks/            # 可复用交互和数据钩子
├── lib/              # API、日志、运行时配置和通用基础设施
├── providers/        # Provider 组合和 Store 注水
├── services/         # 业务接口方法和接口类型
├── stores/           # Zustand Store
├── styles/           # 全局样式和 Ant Design 覆盖
└── theme/            # Ant Design Theme Token

其他重要目录和文件：

public/               # 品牌、页面和静态资源
docker/               # 应用及可选辅助服务 Compose
docs/                 # 前端仓库内的工程专题资料
next.config.js        # standalone 和构建输出配置
Dockerfile            # 生产运行镜像
package.json          # 依赖、脚本和版本

4. 当前页面路由¶

路由	页面文件
`/`	`src/app/(main)/page.tsx`
`/master-agents`	`src/app/(main)/master-agents/page.tsx`
`/user/login`	`src/app/user/login/page.tsx`
`/user/register`	`src/app/user/register/page.tsx`
`/user/forgot-password`	`src/app/user/forgot-password/page.tsx`
`/user/setting/llm`	`src/app/(main)/user/setting/llm/page.tsx`
`/admin/account/import`	`src/app/(main)/admin/account/import/page.tsx`

(main) 是路由分组，不会出现在浏览器 URL 中。

5. 页面与组件边界¶

推荐结构：

src/app/(main)/reports/page.tsx
src/components/reports/ReportsPageContent/index.tsx

页面文件负责：

路由入口；
Metadata；
服务端数据获取；
权限或功能开关判断；
挂载复杂页面组件。

复杂交互、表格、弹窗和业务状态放在组件目录。需要 Hooks 或浏览器 API 的组件声明 'use client'。

6. Service 和类型¶

后端接口请求与响应类型和 Service 方法放在同一个领域文件中：

src/services/user.ts
src/services/agent.ts
src/services/common.ts

服务端专用实现使用 .server.ts，例如 src/services/user.server.ts。浏览器组件禁止导入 server-only 文件。

7. Store 和 Provider¶

当前主要 Store：

src/stores/userStore.ts；
src/stores/agentStore.ts；
src/stores/userSettingsStore.ts；
src/stores/sectionStore.ts。

Store 由 src/providers/StoresProvider/ 创建和注水。服务端布局可以先读取用户或分区数据，再传入 Provider，避免客户端首屏重复请求和闪烁。

8. 样式约定¶

Tailwind 设计变量：src/styles/globals.css；
Ant Design Token：src/theme/antd-theme.ts；
Ant Design 覆盖：src/styles/antd-overrides.css；
条件类名优先使用 clsx；
不要为了简单布局大量使用内联 style；
静态资源使用项目路径工具，避免硬编码根路径。

9. 提交前检查¶

pnpm lint
pnpm build

注意 pnpm lint 中的 ESLint 步骤可能修改文件。执行后需要再次检查代码差异。提交信息遵循仓库的 Conventional Commits 和 commitlint 规则。