From eee40fa0716ecf85e191038c6efb26304c6bedd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8F=B2=E6=82=A6?= Date: Tue, 3 Feb 2026 17:14:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20CLAUDE.md=20=E5=92=8C=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加项目开发指南 CLAUDE.md 和项目说明 README.md - CLAUDE.md 包含项目架构、开发规范和技术细节 - README.md 提供项目简介、功能说明和快速开始指南 --- CLAUDE.md | 239 +++++++++++++++++++++++++++++++++++++++++++ README.md | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 537 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..91999dc --- /dev/null +++ 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` diff --git a/README.md b/README.md new file mode 100644 index 0000000..7268794 --- /dev/null +++ b/README.md @@ -0,0 +1,298 @@ +# ITTOView - PMP 项目管理 ITTO 可视化学习平台 + +
+ +**一个精美、交互式的 PMP 认证考试 ITTO 知识点可视化学习工具** + +[![React](https://img.shields.io/badge/React-18.3-61dafb?logo=react)](https://reactjs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178c6?logo=typescript)](https://www.typescriptlang.org/) +[![Vite](https://img.shields.io/badge/Vite-5.1-646cff?logo=vite)](https://vitejs.dev/) +[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.4-38bdf8?logo=tailwind-css)](https://tailwindcss.com/) +[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) + +
+ +--- + +## 📖 项目简介 + +ITTOView 是一个专为 PMP（Project Management Professional）认证考生设计的 ITTO（Input-Tools & Techniques-Output）可视化学习平台。 + +### 什么是 ITTO？ + +PMBOK 第6版包含： +- **10 大知识领域**：整合、范围、进度、成本、质量、资源、沟通、风险、采购、相关方管理 +- **5 大过程组**：启动、规划、执行、监控、收尾 +- **49 个项目管理过程**：每个过程都有对应的输入（Input）、工具与技术（Tools & Techniques）、输出（Output） + +### 为什么需要 ITTOView？ + +传统的 ITTO 学习方式（PDF/表格）存在以下痛点： +- ❌ **信息孤立**：难以看到过程之间的数据流向关系 +- ❌ **记忆困难**：大量术语和对应关系难以记忆 +- ❌ **缺乏互动**：无法进行自测和针对性复习 +- ❌ **查找低效**：无法快速定位特定输入/输出的使用场景 + +ITTOView 通过可视化和交互式设计解决这些问题： +- ✅ **直观理解**：通过流程图和矩阵图可视化 ITTO 关系 +- ✅ **高效记忆**：5W1H 记忆辅助信息帮助理解过程本质 +- ✅ **快速查询**：支持按知识领域、过程组、工件、工具多维度浏览 +- ✅ **精美界面**：现代化 UI 设计，支持深色模式 + +--- + +## ✨ 核心功能 + +### 🗂️ 多维度知识浏览 + +- **知识领域视图**：按 10 大知识领域分类展示所有过程 +- **过程组视图**：按 5 大过程组分类展示所有过程 +- **过程详情页**：展示单个过程的完整 ITTO 信息及 5W1H 记忆辅助 +- **工件详情页**：查看工件作为输入/输出的所有过程 +- **工具详情页**：查看工具在哪些过程中被使用 + +### 📊 可视化矩阵图 + +- **49 过程矩阵图**：知识领域（行）× 过程组（列）的二维矩阵 +- **全屏模式**：支持全屏查看，优化大屏显示效果 +- **颜色编码**：使用主题色区分不同知识领域和过程组 +- **交互式导航**：点击单元格快速跳转到过程详情 + +### 🎨 用户体验 + +- **响应式设计**：适配 PC 和平板设备 +- **深色模式**：支持明暗主题切换，保护视力 +- **流畅动画**：使用 Framer Motion 实现优雅的页面过渡 +- **侧边栏导航**：可折叠的侧边栏，提供快速导航 + +--- + +## 🚀 快速开始 + +### 前置要求 + +- Node.js >= 18.0.0 +- npm >= 9.0.0 + +### 本地开发 + +```bash +# 1. 克隆项目 +git clone +cd ITTOView + +# 2. 安装依赖 +npm install + +# 3. 启动开发服务器 +npm run dev + +# 4. 在浏览器中打开 http://localhost:3000 +``` + +### 构建生产版本 + +```bash +# 类型检查 + 构建 +npm run build + +# 预览生产构建 +npm run preview +``` + +### 代码检查 + +```bash +# 运行 ESLint +npm run lint +``` + +--- + +## 🐳 Docker 部署 + +### 使用 Docker Compose（推荐） + +```bash +# 启动服务 +docker compose up -d + +# 查看日志 +docker compose logs -f + +# 停止服务 +docker compose down +``` + +服务将在 `http://11.144.144.9:8035` 上运行（可在 `docker-compose.yml` 中修改端口）。 + +### 手动构建 Docker 镜像 + +```bash +# 构建镜像 +docker build -t ittoview:latest . + +# 运行容器 +docker run -d -p 8080:80 --name ittoview ittoview:latest +``` + +--- + +## 🛠️ 技术栈 + +### 核心框架 + +- **[React 18](https://reactjs.org/)** - 用户界面库 +- **[TypeScript](https://www.typescriptlang.org/)** - 类型安全的 JavaScript +- **[Vite](https://vitejs.dev/)** - 下一代前端构建工具 + +### UI 与样式 + +- **[Tailwind CSS](https://tailwindcss.com/)** - 原子化 CSS 框架 +- **[Radix UI](https://www.radix-ui.com/)** - 无样式的可访问组件库 +- **[Framer Motion](https://www.framer.com/motion/)** - 生产级动画库 +- **[Lucide React](https://lucide.dev/)** - 精美的图标库 + +### 可视化 + +- **[ReactFlow](https://reactflow.dev/)** - 流程图和节点编辑器 +- **[AntV G6](https://g6.antv.antgroup.com/)** - 图可视化引擎 +- **[Recharts](https://recharts.org/)** - 基于 React 的图表库 + +### 状态管理与路由 + +- **[Zustand](https://zustand-demo.pmnd.rs/)** - 轻量级状态管理 +- **[React Router](https://reactrouter.com/)** - 声明式路由 + +### 部署 + +- **[Docker](https://www.docker.com/)** - 容器化部署 +- **[Nginx](https://nginx.org/)** - 高性能 Web 服务器 + +--- + +## 📁 项目结构 + +``` +ITTOView/ +├── src/ +│ ├── components/ # React 组件 +│ │ ├── layout/ # 布局组件（Header, Sidebar, Layout） +│ │ ├── ui/ # 通用 UI 组件 +│ │ └── visualize/ # 可视化组件（ProcessMatrix） +│ ├── data/ # 静态数据文件 +│ │ ├── knowledge-areas.json # 10 大知识领域 +│ │ ├── process-groups.json # 5 大过程组 +│ │ ├── processes.json # 49 个过程（含 5W1H） +│ │ ├── artifacts.json # 工件/文档 +│ │ ├── tools.json # 工具与技术 +│ │ └── index.ts # 数据索引和查询 API +│ ├── pages/ # 页面组件 +│ │ ├── HomePage.tsx # 首页 +│ │ ├── KnowledgeAreasPage.tsx # 知识领域页 +│ │ ├── ProcessGroupsPage.tsx # 过程组页 +│ │ ├── ProcessDetailPage.tsx # 过程详情页 +│ │ ├── ProcessMatrixPage.tsx # 矩阵图页 +│ │ ├── ProcessGraphPage.tsx # 流程图页 +│ │ ├── ArtifactDetailPage.tsx # 工件详情页 +│ │ ├── ToolDetailPage.tsx # 工具详情页 +│ │ └── SettingsPage.tsx # 设置页 +│ ├── stores/ # Zustand 状态管理 +│ │ └── useAppStore.ts +│ ├── types/ # TypeScript 类型定义 +│ │ └── itto.ts +│ ├── hooks/ # 自定义 React Hooks +│ ├── utils/ # 工具函数 +│ ├── App.tsx # 应用根组件 +│ └── main.tsx # 应用入口 +├── docs/ # 文档 +│ └── 需求设计文档.md +├── Dockerfile # Docker 镜像构建文件 +├── docker-compose.yml # Docker Compose 配置 +├── nginx.conf # Nginx 配置（SPA 路由支持） +├── package.json # 项目依赖 +├── vite.config.ts # Vite 配置 +├── tailwind.config.js # Tailwind CSS 配置 +├── tsconfig.json # TypeScript 配置 +├── CLAUDE.md # Claude Code 开发指南 +└── README.md # 本文件 +``` + +--- + +## 📊 数据说明 + +### 数据来源 + +项目数据基于 **PMBOK 第6版**（项目管理知识体系指南），包含： +- 10 大知识领域的完整定义 +- 5 大过程组的完整定义 +- 49 个项目管理过程的详细 ITTO 信息 +- 每个过程的 5W1H 记忆辅助信息 + +### 数据格式 + +所有数据以 JSON 格式存储在 `src/data/` 目录下： +- `knowledge-areas.json` - 知识领域数据 +- `process-groups.json` - 过程组数据 +- `processes.json` - 过程数据（含输入、工具、输出 ID 引用） +- `artifacts.json` - 工件/文档数据 +- `tools.json` - 工具与技术数据 + +### 数据查询 API + +`src/data/index.ts` 提供了丰富的数据查询工具函数： +```typescript +// 计算数据流向关系 +computeDataFlows(): DataFlow[] + +// 获取工件的使用情况 +getArtifactUsage(artifactId: string): { asInput: Process[], asOutput: Process[] } + +// 获取工具的使用情况 +getToolUsage(toolId: string): Process[] + +// 获取过程的完整信息 +getProcessDetail(processId: string) +``` + +--- + +## 🎯 路线图 + +### ✅ 已完成功能 + +- [x] 知识领域视图 +- [x] 过程组视图 +- [x] 过程详情页（含 5W1H 记忆辅助） +- [x] 49 过程矩阵图 +- [x] 工件详情页 +- [x] 工具详情页 +- [x] 深色模式 +- [x] 响应式布局 +- [x] Docker 部署支持 + + +--- + +## 🤝 贡献指南 + +欢迎贡献代码、报告问题或提出新功能建议！ + +### 如何贡献 + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 开启 Pull Request + +### 代码规范 + +- 使用 TypeScript 编写代码 +- 遵循 ESLint 规则（运行 `npm run lint` 检查） +- 组件使用函数式组件 + Hooks +- 使用 `@/` 作为 `src/` 的路径别名 + +--- +