docs: 添加项目文档 CLAUDE.md 和 README.md

添加项目开发指南 CLAUDE.md 和项目说明 README.md - CLAUDE.md 包含项目架构、开发规范和技术细节 - README.md 提供项目简介、功能说明和快速开始指南
2026-02-03 17:14:50 +08:00
parent f6e92c5526
commit eee40fa071
2 changed files with 537 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,239 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+ITTOView 是一个 PMP 项目管理 ITTO（Input-Tools & Techniques-Output）可视化学习平台。帮助 PMP 考生通过交互式可视化方式学习和记忆 PMBOK 第6版中的 49 个项目管理过程及其输入、工具技术、输出关系。
+
+**核心数据结构：**
+- 10 大知识领域（Knowledge Areas）
+- 5 大过程组（Process Groups）
+- 49 个项目管理过程（Processes）
+- 工件/文档（Artifacts）- 作为输入和输出
+- 工具与技术（Tools & Techniques）
+
+## 技术栈
+
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Vite 5
+- **路由**: React Router v6
+- **状态管理**: Zustand (持久化到 localStorage)
+- **样式**: Tailwind CSS 3 + Framer Motion
+- **可视化**: ReactFlow, AntV G6, Recharts
+- **UI组件**: Radix UI
+- **部署**: Docker + Nginx
+
+## 开发命令
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器 (http://localhost:3000)
+npm run dev
+
+# 类型检查 + 构建生产版本
+npm run build
+
+# 预览生产构建
+npm run preview
+
+# 代码检查
+npm run lint
+```
+
+## Docker 部署
+
+```bash
+# 构建镜像
+docker build -t ittoview .
+
+# 使用 docker-compose 启动
+docker-compose up -d
+
+# 停止服务
+docker-compose down
+```
+
+## 项目结构
+
+```
+src/
+├── components/
+│   ├── layout/          # 布局组件 (Header, Sidebar, Layout)
+│   ├── ui/              # 通用UI组件 (目前为空)
+│   └── visualize/       # 可视化组件 (ProcessMatrix)
+├── data/                # 静态数据文件 (JSON)
+│   ├── knowledge-areas.json   # 10大知识领域
+│   ├── process-groups.json    # 5大过程组
+│   ├── processes.json         # 49个过程 (含5W1H记忆辅助)
+│   ├── artifacts.json         # 工件/文档
+│   ├── tools.json             # 工具与技术
+│   └── index.ts               # 数据索引和查询工具函数
+├── hooks/               # 自定义 React Hooks (目前为空)
+├── pages/               # 页面组件
+│   ├── HomePage.tsx              # 首页/仪表盘
+│   ├── KnowledgeAreasPage.tsx    # 知识领域视图
+│   ├── ProcessGroupsPage.tsx     # 过程组视图
+│   ├── ProcessDetailPage.tsx     # 过程详情页
+│   ├── ProcessMatrixPage.tsx     # 49过程矩阵图
+│   ├── ProcessGraphPage.tsx      # 流程图/关系图
+│   ├── ArtifactDetailPage.tsx    # 工件详情页
+│   ├── ToolDetailPage.tsx        # 工具详情页
+│   └── SettingsPage.tsx          # 设置页
+├── stores/
+│   └── useAppStore.ts   # Zustand 全局状态 (侧边栏、深色模式、搜索等)
+├── types/
+│   └── itto.ts          # TypeScript 类型定义
+├── utils/               # 工具函数 (目前为空)
+├── App.tsx              # 路由配置
+└── main.tsx             # 应用入口
+```
+
+## 核心架构设计
+
+### 1. 数据层 (src/data/)
+
+**数据加载机制：**
+- 所有 ITTO 数据以 JSON 格式静态存储
+- `src/data/index.ts` 提供统一的数据导出和查询 API
+- 使用 Map 数据结构建立索引，提升查询性能
+
+**关键数据查询函数：**
+```typescript
+// 计算数据流向关系 (输出 → 输入)
+computeDataFlows(): DataFlow[]
+
+// 获取工件的使用情况
+getArtifactUsage(artifactId: string): { asInput: Process[], asOutput: Process[] }
+
+// 获取工具的使用情况
+getToolUsage(toolId: string): Process[]
+
+// 获取过程的完整信息（含关联数据）
+getProcessDetail(processId: string)
+```
+
+### 2. 状态管理 (Zustand)
+
+**全局状态 (useAppStore)：**
+- `sidebarOpen`: 侧边栏展开/收起
+- `darkMode`: 深色模式开关
+- `searchQuery`: 全局搜索关键词
+- `matrixFullScreen`: 矩阵图全屏模式
+
+**持久化策略：**
+- 使用 `zustand/middleware` 的 `persist` 中间件
+- 存储到 `localStorage` (key: `ittoview-app-storage`)
+- `searchQuery` 不持久化，刷新后重置
+
+### 3. 路由设计
+
+**主要路由：**
+- `/` - 首页/仪表盘
+- `/knowledge-areas` - 知识领域列表
+- `/knowledge-areas/:id` - 特定知识领域详情
+- `/process-groups` - 过程组列表
+- `/process-groups/:id` - 特定过程组详情
+- `/process/:id` - 过程详情页
+- `/process-matrix` - 49过程矩阵图
+- `/process-graph` - 流程图/关系图
+- `/artifact/:id` - 工件详情页
+- `/tool/:id` - 工具详情页
+- `/settings` - 设置页
+
+### 4. 样式系统
+
+**Tailwind 自定义主题：**
+- 知识领域主题色：`ka.integration`, `ka.scope`, `ka.schedule` 等
+- 过程组主题色：`pg.initiating`, `pg.planning`, `pg.executing` 等
+- 支持深色模式：使用 `class` 策略 (`darkMode: 'class'`)
+
+**动画：**
+- 使用 Framer Motion 实现页面过渡和交互动画
+- 矩阵图单元格使用渐进式动画 (`delay: kaIndex * 0.05`)
+
+### 5. 类型系统 (src/types/itto.ts)
+
+**核心类型：**
+- `KnowledgeArea` - 知识领域
+- `ProcessGroup` - 过程组
+- `Process` - 过程 (含 `w5h1?: Process5W1H` 记忆辅助)
+- `Artifact` - 工件 (含 `category: ArtifactCategory`)
+- `ToolTechnique` - 工具与技术 (含 `type: ToolType`)
+- `DataFlow` - 数据流向关系
+- `MasteryLevel` - 学习掌握程度 (`familiar` | `fuzzy` | `unfamiliar`)
+
+## 开发注意事项
+
+### 数据修改
+
+**修改 ITTO 数据时：**
+1. 直接编辑 `src/data/*.json` 文件
+2. 确保 ID 引用一致性（如 `process.inputs` 中的 ID 必须存在于 `artifacts.json`）
+3. 更新对应的 `processCount` 统计字段
+4. 保持 JSON 格式正确（使用 JSON 验证工具）
+
+### 添加新页面
+
+1. 在 `src/pages/` 创建新组件
+2. 在 `src/App.tsx` 添加路由
+3. 在 `src/components/layout/Sidebar.tsx` 添加导航链接（如需要）
+
+### 可视化组件开发
+
+**使用的可视化库：**
+- **ReactFlow**: 用于流程图、节点关系图
+- **AntV G6**: 用于复杂图谱可视化
+- **Recharts**: 用于统计图表
+
+**性能优化建议：**
+- 大型矩阵/图谱使用虚拟滚动
+- 使用 `React.memo` 优化列表渲染
+- 图谱节点数量过多时提供筛选/分组功能
+
+### 路径别名
+
+使用 `@/` 作为 `src/` 的别名：
+```typescript
+import { processes } from '@/data'
+import { useAppStore } from '@/stores/useAppStore'
+```
+
+### 代码风格
+
+- 组件使用函数式组件 + TypeScript
+- 优先使用命名导出而非默认导出（除 `App.tsx`）
+- 使用 `clsx` 处理条件类名
+- 遵循 ESLint 规则（`npm run lint`）
+
+## 未来扩展方向
+
+根据需求文档 (`docs/需求设计文档.md`)，以下功能尚未实现：
+
+1. **学习模块** (P0 优先级)
+   - 记忆卡片系统（间隔重复算法）
+   - 自测模式（选择题、填空题、连线题）
+   - 错题本功能
+   - 掌握度标记
+
+2. **搜索与筛选** (P0-P1)
+   - 全局搜索功能
+   - 分类筛选器
+   - 关联查询
+
+3. **可视化增强** (P1-P2)
+   - 数据流向图
+   - 知识领域全景图
+   - 全局关系图谱
+
+4. **用户体验** (P1-P2)
+   - 键盘导航/快捷键
+   - 数据导出功能
+   - 复习计划/提醒
+
+## 相关文档
+
+- 需求设计文档: `docs/需求设计文档.md`
+- ITTO 手册 PDF: `⑦ ITTO输入输出工具手册.pdf`