# PMFlow 项目结构说明（CLAUDE.md）

## 1. Agent 入口文件（你关心的“进项目先读什么”）
- `AGENTS.md`：Codex/Coding Agent 的主规则入口（优先级最高的项目级约束）
- `CLAUDE.md`：面向 Claude 风格的项目说明文档（补充背景）
- 建议：规则放 `AGENTS.md`，架构/目录说明放 `CLAUDE.md`

## 2. 项目定位
- 项目名：`PMFlow / Neural Sync`
- 形态：AI 原生项目管理系统（多租户 + 角色权限 + SSTC 工作流）
- 技术栈：
  - 后端：`FastAPI + SQLAlchemy + Alembic`
  - 前端：`React + TypeScript + Vite + Tailwind + Radix + React Query`

## 3. 顶层目录（精简版）
```text
AIProjectManger/
├── AGENTS.md                  # Agent 执行规则（建议优先维护）
├── CLAUDE.md                  # 现有 Claude 说明文档
├── start.sh / stop.sh         # 一键启动/停止入口
├── docker-compose*.yml        # 容器编排
├── backend/                   # FastAPI 后端
├── frontend/                  # React 前端
├── scripts/                   # 根目录运维脚本
├── tests/                     # 根级测试（集成/脚本）
└── docs/                      # 额外文档
```

## 4. 后端结构（`backend/`）
```text
backend/
├── app/
│   ├── api/                   # 路由层（含 endpoints）
│   ├── core/                  # 配置、日志、核心能力
│   ├── dependencies/          # 鉴权/租户等依赖注入
│   ├── models/                # SQLAlchemy 模型
│   ├── schemas/               # Pydantic 模型
│   ├── services/              # 业务服务（AI/SSTC/集成）
│   ├── config/                # 配置与 prompt
│   └── utils/                 # 工具函数
├── alembic/                   # 数据库迁移
├── requirements.txt           # Python 依赖
├── Dockerfile
└── tests/
```

## 5. 前端结构（`frontend/`）
```text
frontend/
├── src/
│   ├── api/                   # 接口封装
│   ├── pages/                 # 页面级组件
│   ├── components/
│   │   ├── ui/                # 基础 UI 组件
│   │   └── sstc/              # SSTC 工作流组件（已模块化拆分）
│   ├── hooks/                 # 自定义 hooks
│   ├── lib/                   # 通用工具
│   ├── stores/                # 状态管理
│   ├── router/                # 路由
│   └── types/                 # TS 类型定义
├── package.json
└── vite.config.ts
```

## 6. 运行命令（高频）
### 根目录
```bash
./start.sh dev      # 推荐：docker-dev 热更新模式
./stop.sh dev
```

### 前端
```bash
cd frontend
npm run dev
npm run build
```

### 后端（本地直跑）
```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## 7. 团队维护建议（简版）
- 规则变更：只改 `AGENTS.md`
- 结构变更：同步改 `CLAUDE.md`
- API/契约变更：后端 `schemas` + 前端 `types` 同步更新