383 lines
10 KiB
Markdown
383 lines
10 KiB
Markdown
# 📑 TraceStudio v0.3.0 - 文档索引
|
||
|
||
> **版本**: v0.3.0
|
||
> **发布日期**: 2024-01
|
||
> **文档更新**: 2024-01
|
||
|
||
---
|
||
|
||
## 🎯 按用户角色导航
|
||
|
||
### 👤 最终用户 (想要快速上手)
|
||
|
||
```
|
||
START HERE ↓
|
||
|
||
📖 QUICK_START.md (5 min)
|
||
├─ 三分钟快速体验
|
||
├─ 三种 Param 绑定模式演示
|
||
├─ 连线粗细说明
|
||
└─ 常见问题解答
|
||
↓
|
||
📚 USER_GUIDE_v0.3.0.md (30 min)
|
||
├─ 详细功能说明
|
||
├─ 完整工作流示例 (3 个)
|
||
├─ 使用技巧
|
||
└─ 故障排除
|
||
```
|
||
|
||
### 🔧 开发者 (想要理解技术细节)
|
||
|
||
```
|
||
START HERE ↓
|
||
|
||
🔧 IMPLEMENTATION_SUMMARY.md (20 min)
|
||
├─ 核心改动总结
|
||
├─ 数据结构扩展
|
||
├─ API 类型规范
|
||
├─ 文件变更清单
|
||
└─ 后续工作优先级
|
||
↓
|
||
💻 源代码 (1-2 小时)
|
||
├─ web/src/stores/useStore.ts (类型定义)
|
||
├─ web/src/components/Inspector.tsx (绑定 UI)
|
||
├─ web/src/components/Workspace.tsx (EdgeType)
|
||
└─ web/src/components/nodes/UniversalNode.tsx (暴露端口)
|
||
```
|
||
|
||
### ✅ 测试者 (想要验证功能)
|
||
|
||
```
|
||
START HERE ↓
|
||
|
||
✅ FEATURES_TEST.md (15 min)
|
||
├─ 测试场景 (6 个)
|
||
├─ 验收标准
|
||
└─ 已知问题列表
|
||
↓
|
||
🧪 TEST_INTEGRATION.js (5 min)
|
||
├─ testParamBinding()
|
||
├─ testEdgeType()
|
||
├─ testExposedPorts()
|
||
└─ testCompleteWorkflow()
|
||
```
|
||
|
||
### 📋 项目经理 (想要了解项目状态)
|
||
|
||
```
|
||
START HERE ↓
|
||
|
||
📊 RELEASE_ACCEPTANCE_REPORT.md (10 min)
|
||
├─ 功能验收清单
|
||
├─ 质量指标
|
||
├─ 发布清单
|
||
└─ 后续计划
|
||
↓
|
||
🏗️ PROJECT_SUMMARY.md (15 min)
|
||
├─ 项目成果统计
|
||
├─ 技术架构概览
|
||
├─ 开发过程说明
|
||
└─ 经验总结
|
||
↓
|
||
📋 ACCEPTANCE_CHECKLIST.md (5 min)
|
||
├─ 功能完成度
|
||
├─ 文件变更统计
|
||
└─ 验收标准
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 按用途分类
|
||
|
||
### 📖 指南类 (如何使用)
|
||
|
||
| 文档 | 长度 | 适合 | 关键内容 |
|
||
|------|------|------|---------|
|
||
| [QUICK_START.md](./QUICK_START.md) | 5 min | 所有人 | 三分钟入门 |
|
||
| [USER_GUIDE_v0.3.0.md](./USER_GUIDE_v0.3.0.md) | 30 min | 用户 | 详细功能说明 |
|
||
| [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) | 20 min | 开发者 | 技术细节 |
|
||
|
||
### ✅ 验收类 (怎样验证)
|
||
|
||
| 文档 | 长度 | 适合 | 关键内容 |
|
||
|------|------|------|---------|
|
||
| [FEATURES_TEST.md](./FEATURES_TEST.md) | 15 min | 测试者 | 测试场景和验收标准 |
|
||
| [ACCEPTANCE_CHECKLIST.md](./ACCEPTANCE_CHECKLIST.md) | 5 min | PM | 完成度统计 |
|
||
| [RELEASE_ACCEPTANCE_REPORT.md](./RELEASE_ACCEPTANCE_REPORT.md) | 10 min | PM | 最终验收报告 |
|
||
|
||
### 📊 参考类 (怎样扩展)
|
||
|
||
| 文档 | 长度 | 适合 | 关键内容 |
|
||
|------|------|------|---------|
|
||
| [CHANGELOG_v0.3.0.md](./CHANGELOG_v0.3.0.md) | 20 min | 开发者 | 版本变更详情 |
|
||
| [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md) | 15 min | 所有人 | 项目完整总结 |
|
||
| [TEST_INTEGRATION.js](./TEST_INTEGRATION.js) | 10 min | 开发者 | 测试工具脚本 |
|
||
|
||
---
|
||
|
||
## 🗂️ 文件完整列表
|
||
|
||
### 核心源代码 (已修改)
|
||
|
||
```
|
||
web/src/
|
||
├── stores/
|
||
│ └── useStore.ts ⭐ (+20 行)
|
||
│ - ParamBindingMode 类型
|
||
│ - ParamBinding 接口
|
||
│ - bindings 字段
|
||
│ - exposedPorts 字段
|
||
│
|
||
├── utils/
|
||
│ └── api.ts ⭐ (+ 4 行)
|
||
│ - getPlugins 返回类型扩展
|
||
│ - 四大属性字段包含
|
||
│
|
||
└── components/
|
||
├── Inspector.tsx ⭐ (+130 行)
|
||
│ - Param 绑定三种模式 UI
|
||
│ - availableContextVars 计算
|
||
│ - 三种输入控件
|
||
│
|
||
├── Workspace.tsx ⭐ (+15 行)
|
||
│ - isArrayType 检测函数
|
||
│ - EdgeType 推断逻辑
|
||
│ - strokeWidth 映射
|
||
│
|
||
├── NodePalette.tsx ⭐ (+10 行)
|
||
│ - normalizeParamSchema 函数
|
||
│ - 规范化应用
|
||
│
|
||
└── nodes/
|
||
└── UniversalNode.tsx ⭐ (+80 行)
|
||
- allInputs/allOutputs 合并
|
||
- 暴露端口样式差异
|
||
- 指示区显示
|
||
```
|
||
|
||
### 文档和指南 (新增)
|
||
|
||
```
|
||
web/
|
||
├── QUICK_START.md ⭐ 🆕
|
||
│ - 三分钟快速体验
|
||
│ - 功能速览
|
||
│ - 验证方法
|
||
│
|
||
├── USER_GUIDE_v0.3.0.md ⭐ 🆕
|
||
│ - 三种 Param 绑定模式详解
|
||
│ - 工作流示例 (3 个)
|
||
│ - 技术细节和约定
|
||
│ - 常见问题解答
|
||
│
|
||
├── IMPLEMENTATION_SUMMARY.md ⭐ 🆕
|
||
│ - 核心改动总结
|
||
│ - 数据结构设计
|
||
│ - API 变更
|
||
│ - 代码演示
|
||
│ - 集成说明
|
||
│
|
||
├── FEATURES_TEST.md ⭐ 🆕
|
||
│ - 已实现功能列表
|
||
│ - 测试场景 (6 个)
|
||
│ - 已知问题列表
|
||
│ - 优化方向
|
||
│
|
||
├── ACCEPTANCE_CHECKLIST.md ⭐ 🆕
|
||
│ - 功能完成度统计
|
||
│ - 代码质量指标
|
||
│ - 验收标准
|
||
│ - 签名区域
|
||
│
|
||
├── CHANGELOG_v0.3.0.md ⭐ 🆕
|
||
│ - 版本对比
|
||
│ - 文件变更详情
|
||
│ - 设计决策说明
|
||
│ - 升级路径
|
||
│
|
||
├── PROJECT_SUMMARY.md ⭐ 🆕
|
||
│ - 项目成果统计
|
||
│ - 技术架构说明
|
||
│ - 开发过程回顾
|
||
│ - 后续计划
|
||
│
|
||
├── RELEASE_ACCEPTANCE_REPORT.md ⭐ 🆕
|
||
│ - 执行摘要
|
||
│ - 功能验收清单
|
||
│ - 质量指标统计
|
||
│ - 发布清单和指南
|
||
│
|
||
└── TEST_INTEGRATION.js ⭐ 🆕
|
||
- 浏览器控制台测试脚本
|
||
- 8 个测试函数
|
||
- 快速验证工具
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 快速查询
|
||
|
||
### 我想... 应该看哪个文档?
|
||
|
||
| 需求 | 推荐文档 | 阅读时间 |
|
||
|------|----------|---------|
|
||
| **快速上手** | [QUICK_START.md](./QUICK_START.md) | 5 min |
|
||
| **详细教程** | [USER_GUIDE_v0.3.0.md](./USER_GUIDE_v0.3.0.md) | 30 min |
|
||
| **查看技术细节** | [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) | 20 min |
|
||
| **编写测试** | [FEATURES_TEST.md](./FEATURES_TEST.md) + [TEST_INTEGRATION.js](./TEST_INTEGRATION.js) | 25 min |
|
||
| **了解变更** | [CHANGELOG_v0.3.0.md](./CHANGELOG_v0.3.0.md) | 20 min |
|
||
| **检查项目状态** | [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md) | 15 min |
|
||
| **验收项目** | [RELEASE_ACCEPTANCE_REPORT.md](./RELEASE_ACCEPTANCE_REPORT.md) | 10 min |
|
||
| **了解整体情况** | [本文件](./README_INDEX.md) (当前) | 10 min |
|
||
|
||
---
|
||
|
||
## 📍 核心概念导览
|
||
|
||
### Param 绑定模式
|
||
|
||
**了解**: [QUICK_START.md#参数绑定模式](./QUICK_START.md)
|
||
**深入**: [USER_GUIDE_v0.3.0.md#param-绑定](./USER_GUIDE_v0.3.0.md)
|
||
**技术**: [IMPLEMENTATION_SUMMARY.md#inspector-参数绑定](./IMPLEMENTATION_SUMMARY.md)
|
||
|
||
### EdgeType 标记
|
||
|
||
**了解**: [QUICK_START.md#连线-edgetype](./QUICK_START.md)
|
||
**深入**: [USER_GUIDE_v0.3.0.md#连线-edgetype](./USER_GUIDE_v0.3.0.md)
|
||
**技术**: [IMPLEMENTATION_SUMMARY.md#workspace-edgetype](./IMPLEMENTATION_SUMMARY.md)
|
||
|
||
### 暴露端口
|
||
|
||
**了解**: [QUICK_START.md#暴露端口](./QUICK_START.md)
|
||
**深入**: [USER_GUIDE_v0.3.0.md#暴露端口](./USER_GUIDE_v0.3.0.md)
|
||
**技术**: [IMPLEMENTATION_SUMMARY.md#universalnode-暴露端口](./IMPLEMENTATION_SUMMARY.md)
|
||
|
||
---
|
||
|
||
## 🧪 测试资源
|
||
|
||
### 自动化测试脚本
|
||
|
||
```javascript
|
||
// 文件: TEST_INTEGRATION.js
|
||
// 使用: F12 → 粘贴脚本 → 调用函数
|
||
|
||
await testParamBinding() // 测试参数绑定按钮
|
||
await testEdgeType() // 测试连线粗细
|
||
await testExposedPorts() // 测试暴露端口
|
||
await testNodeDataStructure() // 测试数据结构
|
||
await testAPIResponse() // 测试 API 响应
|
||
await testCompleteWorkflow() // 完整工作流测试
|
||
```
|
||
|
||
### 手动测试清单
|
||
|
||
见 [FEATURES_TEST.md](./FEATURES_TEST.md) 的 **测试场景** 部分
|
||
|
||
---
|
||
|
||
## 📝 常用片段
|
||
|
||
### 如何验证功能完成度?
|
||
|
||
```bash
|
||
# 1. 打开浏览器开发者工具
|
||
F12
|
||
|
||
# 2. 粘贴测试脚本
|
||
const script = document.createElement('script')
|
||
script.src = '/TEST_INTEGRATION.js'
|
||
document.head.appendChild(script)
|
||
|
||
# 3. 运行测试
|
||
await testCompleteWorkflow()
|
||
|
||
# 4. 查看结果（绿色 ✅ 为通过，红色 ❌ 为失败）
|
||
```
|
||
|
||
### 如何升级文档?
|
||
|
||
1. 修改对应的 `.md` 文件
|
||
2. 提交 PR 并获批
|
||
3. 合并到 main 分支
|
||
4. 文档自动部署至网站
|
||
|
||
### 如何添加新功能?
|
||
|
||
1. 查阅 [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) 的架构设计
|
||
2. 参考现有代码（如 Param 绑定 UI）
|
||
3. 编写单元测试
|
||
4. 更新相关文档
|
||
5. 提交 PR
|
||
|
||
---
|
||
|
||
## 🔗 外部链接
|
||
|
||
### 项目资源
|
||
- 📦 [GitHub Repository](https://github.com/your-org/TraceStudio)
|
||
- 🐛 [Issue Tracker](https://github.com/your-org/TraceStudio/issues)
|
||
- 💬 [Discussions](https://github.com/your-org/TraceStudio/discussions)
|
||
- 📖 [Documentation Site](https://tracestudio.docs.example.com)
|
||
|
||
### 相关技术
|
||
- ⚛️ [React Flow](https://reactflow.dev/)
|
||
- 🎨 [React](https://react.dev/)
|
||
- 📦 [Zustand](https://zustand.surge.sh/)
|
||
- 🔷 [TypeScript](https://www.typescriptlang.org/)
|
||
|
||
---
|
||
|
||
## 📊 文档统计
|
||
|
||
| 指标 | 值 |
|
||
|------|-----|
|
||
| 总文档数 | 9 个 |
|
||
| 总行数 | ~3200 行 |
|
||
| 平均长度 | ~350 行 |
|
||
| 最长文档 | IMPLEMENTATION_SUMMARY.md (~400 行) |
|
||
| 最短文档 | TEST_INTEGRATION.js (~350 行) |
|
||
| 覆盖话题 | 8 个（绑定、类型、端口、规范、测试等） |
|
||
|
||
---
|
||
|
||
## ✨ 文档特点
|
||
|
||
- ✅ **完整性**: 从快速入门到深入技术，覆盖所有层次
|
||
- ✅ **易用性**: 按用户角色和用途分类，快速导航
|
||
- ✅ **示例丰富**: 包含工作流示例、代码片段、测试用例
|
||
- ✅ **可维护性**: 结构清晰，易于更新和扩展
|
||
- ✅ **多语言**: 计划支持中文和英文（v0.4.0）
|
||
|
||
---
|
||
|
||
## 🚀 下一步行动
|
||
|
||
### 如果你是...
|
||
|
||
**新用户**:
|
||
1. 阅读 [QUICK_START.md](./QUICK_START.md)
|
||
2. 尝试三种参数绑定模式
|
||
3. 创建你的第一个工作流
|
||
|
||
**开发者**:
|
||
1. 阅读 [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)
|
||
2. 查看源代码变更
|
||
3. 运行 [TEST_INTEGRATION.js](./TEST_INTEGRATION.js)
|
||
|
||
**测试者**:
|
||
1. 查阅 [FEATURES_TEST.md](./FEATURES_TEST.md)
|
||
2. 执行测试场景
|
||
3. 提交问题报告
|
||
|
||
**项目经理**:
|
||
1. 阅读 [RELEASE_ACCEPTANCE_REPORT.md](./RELEASE_ACCEPTANCE_REPORT.md)
|
||
2. 查看 [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md)
|
||
3. 确认发布清单
|
||
|
||
---
|
||
|
||
**文档索引**: v0.3.0 | **更新时间**: 2024-01 | **文档版本**: 1.0
|
||
|
||
**快速链接**: [快速开始](./QUICK_START.md) • [用户指南](./USER_GUIDE_v0.3.0.md) • [技术文档](./IMPLEMENTATION_SUMMARY.md) • [验收报告](./RELEASE_ACCEPTANCE_REPORT.md)
|