c15e54fd8c
- 在操作流程规范中增加「更新 changelog」步骤 - 新增「更新 changelog 规范」章节，详细说明字段格式和注意事项 - 要求每次提交前必须更新 src/data/changelog.json - 提供完整的字段说明和示例代码 via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run>
418 lines
12 KiB
Markdown
418 lines
12 KiB
Markdown
# 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`
|
||
|
||
## 日常学习内容更新操作指南
|
||
|
||
### 1. 更新知识领域的敏捷裁剪因素
|
||
|
||
**文件：** `src/data/knowledge-areas.json`
|
||
|
||
在对应知识领域对象中添加 `tailoringFactors` 数组：
|
||
|
||
```json
|
||
{
|
||
"id": "KA06",
|
||
"name": "项目资源管理",
|
||
"tailoringFactors": [
|
||
{
|
||
"title": "多元化",
|
||
"description": "团队的多元化背景是什么？"
|
||
},
|
||
{
|
||
"title": "物理位置",
|
||
"description": "团队成员和实物资源的物理位置在哪里？"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**注意：** `tailoringFactors` 为可选字段，未填写的知识领域页面不显示该区块。
|
||
|
||
---
|
||
|
||
### 2. 更新过程的 ITTO 明细
|
||
|
||
**文件：** `src/data/processes.json`
|
||
|
||
`inputs` / `tools` / `outputs` 支持两种格式：
|
||
- 纯字符串 ID（无明细）：`"A008"`
|
||
- 带明细对象（有子项展开）：`{ "id": "A008", "detail": [{ "label": "质量管理计划" }, { "label": "范围基准" }] }`
|
||
|
||
**示例：**
|
||
|
||
```json
|
||
{
|
||
"id": "P5.1",
|
||
"inputs": [
|
||
{ "id": "A008", "detail": [{ "label": "质量管理计划" }, { "label": "范围基准" }] },
|
||
{ "id": "A076", "detail": [{ "label": "假设日志" }, { "label": "需求文件" }] },
|
||
"A005",
|
||
"A006"
|
||
],
|
||
"tools": [
|
||
"TT001",
|
||
{ "id": "TT008", "detail": [{ "label": "成本效益分析" }, { "label": "质量成本" }] }
|
||
],
|
||
"outputs": [
|
||
"A021",
|
||
{ "id": "A077", "detail": [{ "label": "经验教训登记册" }, { "label": "风险登记册" }] }
|
||
]
|
||
}
|
||
```
|
||
|
||
**注意：**
|
||
- `detail` 数组中每项必须是 `{ "label": "名称" }` 对象，不能是纯字符串
|
||
- 如果引用的工件/工具 ID 不存在于 `artifacts.json` / `tools.json`，需先添加
|
||
|
||
---
|
||
|
||
### 3. 更新过程的主要作用
|
||
|
||
**文件：** `src/data/processes.json`
|
||
|
||
在对应过程对象中添加 `purpose` 字段：
|
||
|
||
```json
|
||
{
|
||
"id": "P8.7",
|
||
"name": "监督风险",
|
||
"purpose": "保证项目决策是在整体项目风险和单个项目风险当前信息的基础上进行。本过程需要在整个项目期间开展。"
|
||
}
|
||
```
|
||
|
||
**注意：** `purpose` 为可选字段，填写后会在过程详情页标题下方以蓝色卡片展示；未填写则不显示。
|
||
|
||
---
|
||
|
||
### 操作流程规范
|
||
|
||
**日常更新 JSON 数据时，无需 Codex 参与，按流程操作即可。**
|
||
|
||
每次完成数据更新后，必须按以下步骤操作：
|
||
|
||
1. **更新 changelog**：在提交前，必须先更新 `src/data/changelog.json`，添加本次变更记录
|
||
2. **询问提交**：数据更新完成后，询问用户是否提交推送，不得自动提交
|
||
3. **构建检查**：用户确认提交前，运行 `npm run build`，确保无类型错误和编译错误（无需每次修改后立即检查，在提交推送前统一检查即可）
|
||
4. **提交推送**：构建通过后执行 `git add` + `git commit` + `git push`
|
||
|
||
---
|
||
|
||
### 更新 changelog 规范
|
||
|
||
**文件：** `src/data/changelog.json`
|
||
|
||
每次提交代码前，必须在 `changelogEntries` 数组开头添加一条新记录：
|
||
|
||
```json
|
||
{
|
||
"id": "YYYY-MM-DD-brief-description",
|
||
"date": "YYYY-MM-DD",
|
||
"type": "feat|fix|style|refactor|docs|perf|test|chore",
|
||
"title": "简短描述本次变更内容",
|
||
"scope": "整合|范围|进度|成本|质量|资源|沟通|风险|采购|相关方|练习|矩阵等"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `id`：唯一标识符，格式为 `日期-简短描述`，使用小写字母和连字符
|
||
- `date`：提交日期，格式 `YYYY-MM-DD`
|
||
- `type`：变更类型，与 Git 提交规范的 type 保持一致
|
||
- `title`：变更标题，简洁描述本次变更的内容
|
||
- `scope`：关联范围，与 Git 提交规范的 scope 保持一致
|
||
|
||
**注意事项：**
|
||
- 新记录添加在数组开头（最新记录在最前）
|
||
- `title` 中如需使用引号，使用「」而非 ""，避免 JSON 解析错误
|
||
- 每次提交只添加一条记录，对应本次 commit
|
||
- `type` 和 `scope` 应与 Git 提交信息保持一致
|
||
|
||
**示例：**
|
||
```json
|
||
{
|
||
"changelogEntries": [
|
||
{
|
||
"id": "2026-03-08-changelog-modal",
|
||
"date": "2026-03-08",
|
||
"type": "feat",
|
||
"title": "新增更新时间轴浏览页面与顶部快捷入口",
|
||
"scope": "整合"
|
||
},
|
||
{
|
||
"id": "2026-03-08-practice-fix-offset",
|
||
"date": "2026-03-08",
|
||
"type": "fix",
|
||
"title": "修正底部固定区域偏移方式",
|
||
"scope": "练习"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Git 提交规范
|
||
|
||
提交信息格式：`<type>(<scope>): <subject>`
|
||
|
||
**type 类型：**
|
||
| type | 说明 |
|
||
|------|------|
|
||
| `feat` | 新增功能或数据 |
|
||
| `fix` | 修复错误数据或 bug |
|
||
| `refactor` | 代码重构（不影响功能） |
|
||
| `style` | 样式调整（不影响逻辑） |
|
||
| `docs` | 文档更新 |
|
||
| `chore` | 构建配置、依赖等杂项 |
|
||
|
||
**scope 范围（常用）：**
|
||
- 知识领域数据：`整合` / `范围` / `进度` / `成本` / `质量` / `资源` / `沟通` / `风险` / `采购` / `相关方`
|
||
- 过程数据：过程名称，如 `控制质量`
|
||
- 前台功能：`矩阵` / `过程详情` / `动画` / `导航`
|
||
|
||
**示例：**
|
||
```
|
||
feat(风险): 添加P8.7监督风险的主要作用
|
||
fix(质量): 修复P5.3控制质量明细格式
|
||
feat(资源): 添加KA06项目资源管理裁剪因素
|
||
style(动画): 优化ITTO显示隐藏过渡效果
|
||
docs(CLAUDE): 更新日常操作指南
|
||
```
|
||
|