177 lines
9.5 KiB
Markdown
177 lines
9.5 KiB
Markdown
# 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/ # 数据库迁移
|
||
│ └── versions/
|
||
│ ├── 20260310_add_feishu_outbox_reply_hash.py # 飞书 outbox 回执哈希幂等字段
|
||
│ ├── 20260311_add_pg_trgm_text_indexes.py # pg_trgm 扩展与文本检索索引
|
||
│ ├── 20260311_add_kb_chunk_ivfflat_index.py # knowledge_base_chunks 向量 IVFFlat 索引
|
||
│ └── 20260311_add_conversation_sessions_table.py # 飞书多轮会话上下文持久化表
|
||
├── scripts/ # 后端运维/数据修复脚本
|
||
│ └── backfill_orphan_signal_links.py # 回填孤立 signal 的 project_signal_links
|
||
├── requirements.txt # Python 依赖
|
||
├── Dockerfile
|
||
└── tests/
|
||
```
|
||
- 新增：`backend/app/api/llm_providers.py`（AI 管家 LLM provider preset 配置读取接口）
|
||
- 新增：`backend/app/services/ai_agent_kernel.py`（双 Agent 共享决策内核：复杂度路由/执行门控/修正识别）
|
||
- 新增：`backend/app/utils/timezone.py`（统一北京时间工具：`now_cn_aware/now_cn_naive`）
|
||
- 新增：`backend/alembic/versions/20260311_shift_all_timestamps_to_beijing.py`（全库历史时间 +8h，数据库默认时区切到 Asia/Shanghai）
|
||
- 新增：`backend/tests/test_ai_pmo_work_item_decision_api.py`（AI PMO 审批动作接口回归测试）
|
||
- 移除：`backend/.env.example`（配置模板统一到根目录 `.env.example`）
|
||
- 移除：`backend/.openclaw/pmflow-routing-rules.json`（路由规则统一到根目录 `.openclaw/`）
|
||
|
||
## 5. 前端结构（`frontend/`）
|
||
```text
|
||
frontend/
|
||
├── src/
|
||
│ ├── api/ # 接口封装
|
||
│ ├── pages/ # 页面级组件
|
||
│ ├── components/
|
||
│ │ ├── ui/ # 基础 UI 组件
|
||
│ │ └── sstc/ # SSTC 工作流组件（已模块化拆分）
|
||
│ ├── hooks/ # 自定义 hooks
|
||
│ ├── lib/ # 通用工具
|
||
│ ├── stores/ # 状态管理
|
||
│ ├── router/ # 路由
|
||
│ └── types/ # TS 类型定义
|
||
├── package.json
|
||
└── vite.config.ts
|
||
```
|
||
|
||
### 5.1 `frontend/src/components/sstc/` 目录说明（模块化拆分后）
|
||
- `SSTCWorkspace.tsx`：SSTC 工作区主容器（组装各阶段组件）
|
||
- `useSSTCWorkspaceOrchestration.ts`：工作区编排 Hook（状态聚合、请求编排、事件路由）
|
||
- `sstcUtils.ts`：SSTC 工具函数（数据转换、状态判断、通用 helper）
|
||
- `SSTCSignalStagePanel.tsx`：信号阶段面板
|
||
- `SSTCCharterStagePanel.tsx`：宪章阶段面板
|
||
- `SSTCTaskStagePanel.tsx`：任务阶段面板
|
||
- `SSTCExecutionBoardPanel.tsx`：执行看板阶段面板
|
||
- `SSTCReleaseStagePanel.tsx`：发布阶段面板
|
||
- `SSTCReviewStagePanel.tsx`：复盘阶段面板
|
||
- `SSTCTaskCreateDialog.tsx`：任务创建弹窗
|
||
- `SSTCReleaseCreateDialog.tsx`：发布创建弹窗
|
||
- `SSTCReviewCreateDialog.tsx`：复盘创建弹窗
|
||
- `AIVisibilityPanel.tsx`：AI 可视化信息面板
|
||
- `SSTCGlobalHeader.tsx`：SSTC 全局头部
|
||
- `SSTCStageNav.tsx`：阶段导航
|
||
- `SSTCChainView.tsx`：链路视图
|
||
- `SSTCRiskFloatPanel.tsx`：风险浮层
|
||
- `SignalContentHoverCard.tsx`：信号内容悬浮卡片
|
||
- `charterModules.ts`：宪章模块配置与映射
|
||
|
||
### 5.2 修改前必须执行 `FIND_USAGE` 的 SSTC 组件清单
|
||
- `SSTCWorkspace.tsx`
|
||
- `useSSTCWorkspaceOrchestration.ts`
|
||
- `sstcUtils.ts`
|
||
- `SSTCCharterStagePanel.tsx`
|
||
- `SSTCSignalStagePanel.tsx`
|
||
- `SSTCTaskStagePanel.tsx`
|
||
- `SSTCExecutionBoardPanel.tsx`
|
||
- `SSTCReleaseStagePanel.tsx`
|
||
- `SSTCReviewStagePanel.tsx`
|
||
- `SSTCReleaseCreateDialog.tsx`
|
||
- `SSTCReviewCreateDialog.tsx`
|
||
- `SSTCTaskCreateDialog.tsx`
|
||
|
||
## 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` 同步更新
|
||
|
||
## 8. 服务边界约束（禁止越界）
|
||
- 数据库写操作必须通过 Alembic migration，禁止直接 `ALTER TABLE`
|
||
- 新增接口必须遵循响应包络：`{code, message, data}`，不得裸返回
|
||
- 禁止在 API 层写业务逻辑，业务逻辑归属 `services/`
|
||
- 禁止在前端组件内直接调用 `fetch`，必须通过 `frontend/src/api/` 封装层
|
||
- 前端状态管理：服务端数据用 React Query，本地 UI 状态用 `useState`
|
||
- 飞书回执发送仅允许 `main.py` 的 drain_loop 作为消费者，禁止在业务路径即时派发 outbox 发送任务
|
||
|
||
## 9. 新增代码的参考模式
|
||
- 新增后端接口：参考 `backend/app/api/sstc.py` 的结构
|
||
- 配置读取类接口：参考 `backend/app/api/llm_providers.py`（`GET /ai-steward/llm/providers`）
|
||
- 项目删除接口（`DELETE /projects/{project_id}`）：参考 `backend/app/api/projects.py`，先清理强依赖外键、再置空弱依赖外键、最后删除主记录（单事务提交）
|
||
- AI PMO 审批接口（`POST /ai-pmo/work-items/{work_item_id}/decision`）：显式 `approve/reject`，`reject` 必须落 `ignored`（失效）并同步 `decision_records.final_outcome`
|
||
- 新增前端 API 调用：参考 `frontend/src/api/sstc.ts`
|
||
- 新增数据库表：参考 `alembic/versions/` 最新 migration
|
||
- 新增飞书事件处理：参考 `backend/app/services/feishu_integration.py`
|
||
|
||
## 10. 幂等与事务约束
|
||
- 所有入站事件必须经过 `ingest_events` 幂等去重
|
||
- 飞书回复必须经过 `feishu_reply_outbox`，禁止同步直接发送
|
||
- 飞书回复发送幂等：`reply_hash = MD5(source_message_id + reply_text)`，同租户下 `status=sent` 的相同哈希不得重复发送
|
||
- 跨表写操作必须在同一个数据库事务内完成
|
||
|
||
## 11. 已知 BOUNDARY（不要幻构行为）
|
||
- 飞书回调字段可能缺失文件名/大小，仅保证 `attachment_id/key/type` 可用
|
||
- `agents.defaults.timeoutSeconds` 在 OpenClaw 网关行为未验证，当前以 `LLM_REQUEST_TIMEOUT` 环境变量为准
|
||
- World Model 静态层已接入 Redis 缓存（key: `wm:static:{tenant_id}:{project_id}`，TTL 600s）
|
||
- 写操作后主动 invalidate，动态层不缓存
|
||
- AI PMO 意图识别已启用 LLM 主路径（`AI_PMO_INTENT_LLM_ENABLED`，默认开启）；当模型超时/不可用/结构化解析失败时自动降级到规则链路，不中断主流程
|
||
- 环境变量以根目录 `.env` / `.env.example` 为唯一配置源；`backend/.env` 已移除且不再读取
|
||
- OpenClaw 路由规则统一由根目录 `.openclaw/pmflow-routing-rules.json` 管理，容器通过 `OPENCLAW_ROUTING_RULES_PATH` 相对路径 `../.openclaw/pmflow-routing-rules.json` 读取
|
||
- 模型命名统一使用裸模型名（如 `GLM-4.7`、`MiniMax-M2.5`），不使用供应商前缀模型名
|
||
- 双 Agent 路由治理：默认启用 `OPENCLAW_ROUTING_ENABLED=true`、关闭 `LLM_MIXED_ROUTING_ENABLED`，复杂意图使用 `classify_intent_complex` 走 high-tier
|
||
- 写操作链路统一产出 `decision_trace`（intent/tier/confidence/gate_code/correction_action）用于离线回放与分桶评分
|
||
- AI PMO 意图仲裁默认开启（`AI_PMO_INTENT_ARBITRATION_ENABLED=true`）：规则与 LLM 写操作冲突时按 `AI_PMO_INTENT_CONFLICT_POLICY=pending_manual` 强制进入人工确认，不直接自动执行
|
||
- `project.create` 启用槽位完整性闸门：无法从指令提取有效项目名时标记 `slot_incomplete` 并进入人工确认
|
||
- 数据库与核心写入链路统一使用北京时间（`Asia/Shanghai`）：PostgreSQL 会话时区、数据库默认时区与核心 `_utc_now*` 写入入口均已切换到北京时间
|