@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/product-specs/MVP3-ARCHITECTURE-REDESIGN-PRD.md

@@ -0,0 +1,322 @@
+# CodeMap MVP3 架构重构产品需求文档 (PRD)
+
+> **版本**: v1.0.0  
+> **状态**: Draft  
+> **日期**: 2026-03-17  
+> **负责人**: Architecture Team
+
+---
+
+## 1. 背景与目标
+
+### 1.1 现状痛点
+
+| 痛点 | 影响 | 示例 |
+|------|------|------|
+| 层间耦合度高 | `cli/` 直接依赖 `core/analyzer`，难以测试 | CLI 命令难以 mock 分析器 |
+| 存储层硬编码 | 输出只能是 JSON/Markdown，无法扩展 | 无法支持图数据库查询 |
+| 语言支持受限 | 仅支持 TS/JS/Go，错失 Python/Java 用户 | 用户流失到 CodeGraphContext |
+| 缺少服务层 | 业务逻辑分散在 CLI 命令中 | 难以复用核心能力 |
+
+### 1.2 目标
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       MVP3 核心目标                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ✅ 架构清晰分层: 5 层架构，每层职责单一，接口隔离                 │
+│  ✅ 存储可插拔: 文件系统(默认) + 图数据库(可选)                    │
+│  ✅ 语言扩展: 从 3 种扩展到 14 种主流语言                         │
+│  ✅ CLI 增强: 基础可视化 + 交互式查询                             │
+│  ✅ 向后兼容: 现有用户零成本迁移                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 用户故事
+
+### 2.1 开发者 persona: 小李 (Python 后端工程师)
+
+> "我是 Python 开发者，想用 CodeMap 分析我的 Django 项目，但发现不支持 Python，只能用 CodeGraphContext。"
+
+**需求**: 
+- 支持 Python 代码分析
+- 能看到 Django 项目的依赖关系
+- 能检测循环依赖
+
+### 2.2 架构师 persona: 老王 (大型系统架构师)
+
+> "我的项目有 5000+ 文件，JSON 文件太大了，查询很慢，希望能用图数据库加速查询。"
+
+**需求**:
+- 可选图数据库存储后端
+- 复杂查询性能 < 100ms
+- 支持跨语言调用链分析
+
+### 2.3 CLI 用户 persona: 小张 (命令行爱好者)
+
+> "我喜欢在终端工作，希望能有漂亮的 CLI 可视化，比如树形目录、依赖图字符画。"
+
+**需求**:
+- CLI 字符画可视化
+- 交互式命令补全
+- 进度条和颜色输出
+
+---
+
+## 3. 功能需求
+
+### 3.1 分层架构 (Server 层引入)
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              MVP3 分层架构                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Layer 5: CLI Layer                                                  │   │
+│  │  - 命令解析、参数校验、输出格式化                                       │   │
+│  │  - 仅处理 stdin/stdout/stderr                                        │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Layer 4: Server Layer  ⭐ 新增                                       │   │
+│  │  - 业务逻辑编排、用例实现                                              │   │
+│  │  - 协调 Domain 和 Infrastructure 层                                   │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Layer 3: Domain Layer                                               │   │
+│  │  - 核心业务逻辑、实体、值对象                                          │   │
+│  │  - 分析器、依赖图构建、符号索引                                         │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Layer 2: Infrastructure Layer                                       │   │
+│  │  - 存储抽象、解析器、缓存、文件系统                                     │   │
+│  │  - 技术实现细节                                                       │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                    │                                        │
+│                                    ▼                                        │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Layer 1: Interface Layer                                            │   │
+│  │  - 类型定义、配置接口、外部 API 抽象                                    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 存储抽象层 (Storage Abstraction)
+
+```typescript
+// 用户配置示例
+type StorageConfig = 
+  | { type: 'filesystem'; path: string }
+  | { type: 'kuzudb'; path: string }
+  | { type: 'neo4j'; uri: string; username: string; password: string };
+
+// 自动选择策略
+interface AutoStorageConfig {
+  type: 'auto';
+  thresholds: {
+    useGraphDBWhenFileCount: number;  // 默认 500
+    useGraphDBWhenNodeCount: number;  // 默认 10000
+  };
+}
+```
+
+**功能需求**:
+
+| 需求 ID | 需求描述 | 优先级 | 验收标准 |
+|---------|----------|--------|----------|
+| SA-01 | 文件系统存储 (默认) | P0 | 与现有 JSON/Md 输出完全兼容 |
+| SA-02 | KùzuDB 嵌入式存储 | P1 | 查询性能比文件系统快 10x |
+| SA-03 | Neo4j 远程存储 | P2 | 支持企业级部署 |
+| SA-04 | 自动选择策略 | P1 | 根据项目规模自动选择后端 |
+| SA-05 | 存储迁移工具 | P2 | FS ↔ GraphDB 双向迁移 |
+
+### 3.3 多语言支持 (14 种语言)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      语言支持路线图                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Phase 1 (P0): 当前已支持                                        │
+│  ├── TypeScript ⭐                                               │
+│  ├── JavaScript                                                  │
+│  └── Go                                                          │
+│                                                                 │
+│  Phase 2 (P1): 扩展语言 (MVP3 目标)                               │
+│  ├── Python 🐍  (最高优先级)                                      │
+│  ├── Java ☕                                                     │
+│  ├── Rust 🦀                                                     │
+│  └── C/C++                                                       │
+│                                                                 │
+│  Phase 3 (P2): 后续扩展                                          │
+│  ├── C#                                                          │
+│  ├── Ruby                                                        │
+│  ├── PHP                                                         │
+│  ├── Swift                                                       │
+│  ├── Kotlin                                                      │
+│  ├── Dart                                                        │
+│  └── Perl                                                        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**语言实现策略**:
+
+| 语言 | 解析器 | 复杂度 | 优先级 |
+|------|--------|--------|--------|
+| Python | Tree-sitter | 中 | P0 |
+| Java | Tree-sitter | 中 | P1 |
+| Rust | Tree-sitter | 中 | P1 |
+| C/C++ | Tree-sitter | 高 | P1 |
+| C# | Tree-sitter | 中 | P2 |
+| Ruby | Tree-sitter | 低 | P2 |
+| PHP | Tree-sitter | 低 | P2 |
+| Swift | Tree-sitter | 中 | P2 |
+| Kotlin | Tree-sitter | 中 | P2 |
+| Dart | Tree-sitter | 低 | P2 |
+| Perl | Tree-sitter | 低 | P2 |
+
+### 3.4 CLI 可视化增强
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    CLI 可视化功能                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. 树形目录可视化 (tree view)                                   │
+│     $ mycodemap viz tree --depth 3                              │
+│     📁 src/                                                     │
+│     ├── 📁 cli/                                                 │
+│     │   ├── 📄 index.ts                                         │
+│     │   └── 📄 commands/                                        │
+│     └── 📁 core/                                                │
+│         └── 📄 analyzer.ts                                      │
+│                                                                 │
+│  2. 依赖图字符画 (ascii graph)                                   │
+│     $ mycodemap viz deps --format ascii                         │
+│     src/index.ts                                                │
+│     ├── src/cli/index.ts                                        │
+│     ├── src/core/analyzer.ts                                    │
+│     └── src/parser/index.ts                                     │
+│                                                                 │
+│  3. 热力图 (heatmap)                                            │
+│     $ mycodemap viz heatmap --metric complexity                 │
+│     🔴 src/orchestrator/workflow.ts  (复杂度: 45)                │
+│     🟡 src/cli/commands/query.ts   (复杂度: 28)                │
+│     🟢 src/cache/lru-cache.ts      (复杂度: 12)                │
+│                                                                 │
+│  4. 进度条和 Spinner                                             │
+│     $ mycodemap generate                                        │
+│     [████████████████████] 85% | 正在分析 src/core/analyzer.ts  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**CLI 可视化需求**:
+
+| 需求 ID | 功能 | 优先级 | 说明 |
+|---------|------|--------|------|
+| VIZ-01 | 树形目录视图 | P1 | `--viz tree` |
+| VIZ-02 | ASCII 依赖图 | P1 | `--viz deps` |
+| VIZ-03 | 复杂度热力图 | P2 | `--viz heatmap` |
+| VIZ-04 | 进度条/Spinner | P0 | 所有耗时命令 |
+| VIZ-05 | 颜色主题 | P2 | `--theme dark/light` |
+| VIZ-06 | 交互式 TUI | P2 | `mycodemap tui` |
+
+---
+
+## 4. 非功能需求
+
+### 4.1 性能目标
+
+| 指标 | 当前 | MVP3 目标 | 测试场景 |
+|------|------|-----------|----------|
+| 首次索引 (1000 文件) | ~30s | < 20s | Fast 模式 |
+| 查询响应时间 | ~500ms | < 100ms (GraphDB) | 符号查询 |
+| 内存占用 | ~500MB | < 1GB | 5000 文件项目 |
+| 增量更新 | ~5s | < 3s | 修改 1 个文件 |
+
+### 4.2 兼容性
+
+- **向后兼容**: 现有 `codemap.config.json` 无需修改
+- **输出兼容**: `AI_MAP.md` / `CONTEXT.md` 格式保持不变
+- **CLI 兼容**: 所有现有命令和参数保持不变
+
+### 4.3 可扩展性
+
+- **新存储后端**: 实现 `StorageAdapter` 接口即可添加
+- **新语言**: 实现 `LanguageParser` 接口即可添加
+- **新可视化**: 实现 `Visualizer` 接口即可添加
+
+---
+
+## 5. 发布计划
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      MVP3 发布路线图                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  v3.0.0-alpha (4 周)                                            │
+│  ├── 架构重构: Server 层 + 分层隔离                              │
+│  └── 存储抽象层基础接口                                          │
+│                                                                 │
+│  v3.0.0-beta (4 周)                                             │
+│  ├── Python 语言支持                                             │
+│  ├── KùzuDB 存储后端                                             │
+│  └── CLI 可视化基础功能                                          │
+│                                                                 │
+│  v3.0.0-rc (2 周)                                               │
+│  ├── Java/Rust/C/C++ 语言支持                                    │
+│  ├── 自动存储选择策略                                            │
+│  └── 性能优化                                                    │
+│                                                                 │
+│  v3.0.0-stable                                                  │
+│  └── 正式发布                                                    │
+│                                                                 │
+│  v3.1.0+                                                        │
+│  └── 剩余 6 种语言 + Neo4j 后端                                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. 风险与缓解
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| Tree-sitter 性能瓶颈 | 中 | 高 | 预编译 grammar，Worker 线程解析 |
+| KùzuDB 稳定性 | 低 | 高 | 保留文件系统作为 fallback |
+| 向后兼容性破坏 | 低 | 高 | 完整集成测试，灰度发布 |
+| 开发周期延期 | 中 | 中 | 分阶段发布，先核心后扩展 |
+
+---
+
+## 7. 附录
+
+### 7.1 术语表
+
+| 术语 | 定义 |
+|------|------|
+| Server Layer | 业务逻辑层，协调 Domain 和 Infrastructure |
+| Storage Abstraction | 存储抽象接口，支持多种后端实现 |
+| Tree-sitter | 增量解析库，支持多语言 |
+| KùzuDB | 高性能嵌入式图数据库 |
+
+### 7.2 参考文档
+
+- [MVP3 Tech-PRD](./MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md)
+- [Storage Abstraction Design](../design-docs/storage-abstraction.md)
+- [Multi-Language Support Plan](../design-docs/multi-language-support.md)