本地开发与构建

前置条件

• Node.js、pnpm
• MySQL（ZenStack / 应用数据）
• Redis（Sys 登录会话等）

环境文件

1. backend/.env：由 backend/.env.example 复制。至少配置 DATABASE_URL、JWT_SECRET（网关与 Sys 必须一致）、REDIS_*、SYS_SERVICE_URL、ACC_SERVICE_URL。
2. frontend/.env：由 frontend/.env.example 复制，例如 VITE_API_BASE_URL 指向网关（默认 http://localhost:3000）。

数据库与 ZenStack

在 backend/ 目录：

pnpm run zen:generate
pnpm run zen:push

• zen:generate：根据 zenstack/schema.zmodel 生成客户端与类型。
• zen:push：将 schema 同步到数据库（生产环境请改用迁移策略）。

常用命令（仓库根目录）

命令	说明
pnpm install	安装 workspace 依赖
pnpm dev	并行启动 gateway、sys、acc、Vite 前端
pnpm dev:backend	仅三后端
pnpm dev:web	仅前端
pnpm build	后端 build + 前端 build
pnpm docs:dev / pnpm --filter taskflow-docs dev	仅启动本 VitePress 文档站（5174，与前端 5173 区分）

开发时浏览器访问 前端端口（默认 5173），由 Vite 将 /api 代理到网关，再由网关转发 Sys / Acc。

文档站点

文档开发服务器固定为 5174（在 docs/.vitepress/config.ts 的 vite.server.port），避免与前端 pnpm dev:web 的 5173 冲突。

pnpm docs:dev
# 或
pnpm --filter taskflow-docs dev

浏览器打开 http://localhost:5174。

构建与预览静态站点：

pnpm docs:build
pnpm docs:preview

预览默认使用 4174（vite.preview.port），与前端 vite preview 常用 4173 错开。