wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8de1f93fd34926c35d284d4e76258746809c2fb1
ftb-project-management/CLAUDE.md
Script Generator 8de1f93fd3 feat: 初始化 FTB 智能项目管理系统 monorepo 项目结构 
包含 Turborepo 配置、Next.js 前端骨架、NestJS 后端骨架、Prisma Schema、
共享类型包、Docker Compose 和环境变量模板。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-08 10:31:35 +08:00

6.7 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FTB 智能项目管理系统 — 一个集成 AI 能力的项目管理平台，核心目标是通过智能化手段提升项目管理效率。

核心功能模块

  • 任务管理：任务创建、分配、状态流转、优先级管理
  • 看板视图：可视化任务拖拽、自定义工作流列
  • 甘特图：项目时间线规划与依赖关系管理
  • AI 辅助：任务智能分解、工期预估、风险预警
  • 资源调度：团队成员工作负载可视化、智能排期建议
  • 数据看板：项目进度、燃尽图、团队效率指标

Tech Stack

层级 技术 说明
前端框架 Next.js 14+ (App Router) SSR + 文件路由
UI 组件 Shadcn/ui + Tailwind CSS 现代风格，完全可定制
状态管理 Zustand 轻量级，替代 Redux
拖拽 dnd-kit 看板拖拽交互
图表 Recharts 燃尽图、数据看板
后端框架 NestJS 模块化架构，TypeScript
ORM Prisma 类型安全的数据库访问
数据库 PostgreSQL 关系型数据，适合任务依赖建模
AI 集成 Anthropic SDK 任务分解、风险分析、智能建议
认证 NextAuth.js OAuth + JWT
实时通信 Socket.io 看板实时同步、通知推送

Architecture

ftb-project-management/
├── apps/
│   ├── web/                  # Next.js 前端
│   │   ├── app/              # App Router 页面
│   │   ├── components/       # UI 组件
│   │   │   ├── ui/           # Shadcn 基础组件
│   │   │   ├── board/        # 看板相关组件
│   │   │   ├── gantt/        # 甘特图组件
│   │   │   └── dashboard/    # 数据看板组件
│   │   ├── hooks/            # 自定义 Hooks
│   │   ├── stores/           # Zustand stores
│   │   └── lib/              # 工具函数
│   └── server/               # NestJS 后端
│       ├── src/
│       │   ├── modules/
│       │   │   ├── project/  # 项目 CRUD
│       │   │   ├── task/     # 任务管理 + 状态机
│       │   │   ├── board/    # 看板逻辑
│       │   │   ├── gantt/    # 甘特图数据
│       │   │   ├── ai/       # AI 能力封装
│       │   │   ├── user/     # 用户与权限
│       │   │   └── notify/   # 通知系统
│       │   ├── common/       # 拦截器、守卫、管道
│       │   └── prisma/       # Schema + Migrations
│       └── test/
├── packages/
│   └── shared/               # 前后端共享类型定义
├── docker-compose.yml
└── turbo.json                # Turborepo monorepo 管理

Build & Dev Commands

# 安装依赖（monorepo 根目录）
pnpm install

# 启动全部服务（前端 + 后端 + 数据库）
pnpm dev

# 单独启动
pnpm dev --filter=web        # 前端 localhost:3000
pnpm dev --filter=server     # 后端 localhost:3001

# 数据库
pnpm db:migrate              # 执行 Prisma 迁移
pnpm db:seed                 # 填充测试数据
pnpm db:studio               # 打开 Prisma Studio

# 测试
pnpm test                    # 全部测试
pnpm test --filter=server    # 仅后端测试
pnpm test -- --watch         # 监听模式
pnpm test -- -t "任务创建"    # 运行单个测试

# 构建 & 检查
pnpm build                   # 生产构建
pnpm lint                    # ESLint 检查
pnpm type-check              # TypeScript 类型检查

# Docker
docker-compose up -d         # 启动 PostgreSQL + Redis
docker-compose down          # 停止容器

Data Model (核心实体关系)

User ──┬── owns ──── Project
       │                 │
       │          contains many
       │                 │
       └── assigned ── Task ──── depends on ──── Task
                         │
                    has many
                         │
                      Comment / Activity / Attachment

关键设计决策：

  • 任务状态机：todo → in_progress → in_review → done，支持自定义列
  • 任务支持无限层级子任务（parent_id 自引用）
  • 权限模型：Owner > Admin > Member > Viewer（项目级 RBAC）
  • AI 操作记录独立表存储，便于审计和回溯

AI Module 设计

AI 模块作为独立 NestJS Module，对外暴露服务接口：

  • AiTaskService.decompose(description) — 将需求描述拆解为子任务
  • AiRiskService.analyze(projectId) — 分析项目风险并生成预警
  • AiScheduleService.suggest(projectId) — 基于成员负载给出排期建议

所有 AI 调用走统一的 AiGateway，负责 prompt 管理、token 计量、降级处理。

Conventions

  • 包管理器：pnpm（monorepo workspace）
  • 分支命名：feature/模块-描述、fix/模块-描述、hotfix/描述
  • Commit 格式：类型(模块): 描述（中文）
    • 类型：feat / fix / refactor / docs / test / chore
  • API 路径：/api/v1/projects/:projectId/tasks/:taskId（RESTful 嵌套资源）
  • 前端路由：/projects/[id]/board、/projects/[id]/gantt、/projects/[id]/dashboard
  • 数据库表名 snake_case，TypeScript 字段 camelCase（Prisma 自动映射）
  • 组件文件 PascalCase，工具函数文件 camelCase
  • Zustand store 按功能域拆分：useProjectStore、useTaskStore、useBoardStore

Environment Variables

项目根目录提供 .env.example，开发者复制为 .env.local 使用。

# 数据库
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ftb_pm

# 认证
NEXTAUTH_SECRET=your-random-secret-key
NEXTAUTH_URL=http://localhost:3000

# AI
ANTHROPIC_API_KEY=sk-ant-xxx

# Redis（Socket.io 适配器 + 缓存）
REDIS_URL=redis://localhost:6379

# 邮件通知（可选）
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=noreply@example.com
SMTP_PASS=your-smtp-password

Deployment

采用 Docker Compose 部署到云服务器（推荐 2核4G），一套配置本地和线上通用。

# docker-compose.prod.yml 核心服务
services:
  web:        # Next.js 前端，端口 3000
  server:     # NestJS 后端，端口 3001
  postgres:   # PostgreSQL 数据库，端口 5432
  redis:      # Redis 缓存 + Socket.io，端口 6379
  nginx:      # 反向代理 + SSL 终止，端口 80/443

部署流程：

  1. 服务器安装 Docker + Docker Compose
  2. 配置 .env.production 环境变量
  3. docker-compose -f docker-compose.prod.yml up -d
  4. Nginx 配置域名 + Let's Encrypt SSL 证书
  5. 数据库迁移：docker exec server pnpm db:migrate