ittoview/CLAUDE.md

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

开发命令

# 安装依赖
npm install

# 启动开发服务器 (http://localhost:3000)
npm run dev

# 类型检查 + 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint

Docker 部署

# 构建镜像
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 数据结构建立索引，提升查询性能

关键数据查询函数：

// 计算数据流向关系 (输出 → 输入)
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/ 的别名：

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