# 个人知识管理系统 - 命令行版本 (CLI) 设计说明书

## 1. 设计目标
- 实现基础笔记管理功能（增删改查）
- 支持标签系统管理
- 提供本地数据持久化（JSON格式）
- 实现基本搜索功能
- 应用工厂模式实现导出功能
- 为后续Web版本奠定基础架构

## 2. 系统架构

```mermaid
graph TD
    A[命令行接口] --> B[命令解析器]
    B --> C[控制器]
    C --> D[笔记服务]
    C --> E[标签服务]
    D --> F[存储模块]
    E --> F
    D --> G[搜索模块]
    D --> H[导出模块]
```

## 3. 核心模块设计

### 3.1 笔记实体类 (Note.java)
```java
public class Note {
    private String id;          // UUID
    private String title;       // 笔记标题
    private String content;     // 笔记内容
    private List<String> tags; // 标签列表
    private LocalDateTime createdAt; // 创建时间
    private LocalDateTime updatedAt; // 更新时间
    
    // 构造方法、getter和setter
}
```

### 3.2 存储模块 (StorageService.java)
```java
public interface StorageService {
    void saveNote(Note note);
    void deleteNote(String id);
    Note findNoteById(String id);
    List<Note> findAllNotes();
    void saveAll(List<Note> notes);
}
```

### 3.3 JSON存储实现 (JsonStorageService.java)
```java
public class JsonStorageService implements StorageService {
    private static final String FILE_PATH = "notes.json";
    private final ObjectMapper objectMapper = new ObjectMapper()
        .registerModule(new JavaTimeModule());
    
    @Override
    public void saveNote(Note note) {
        List<Note> notes = findAllNotes();
        // 更新或添加笔记
        notes.removeIf(n -> n.getId().equals(note.getId()));
        notes.add(note);
        saveAll(notes);
    }
    
    @Override
    public void saveAll(List<Note> notes) {
        try {
            objectMapper.writerWithDefaultPrettyPrinter()
                .writeValue(new File(FILE_PATH), notes);
        } catch (IOException e) {
            System.err.println("保存数据失败: " + e.getMessage());
        }
    }
    
    // 其他方法实现...
}
```

### 3.4 导出模块 (使用工厂模式)
```java
// 导出器接口
public interface Exporter {
    void export(Note note, String filePath);
    void exportAll(List<Note> notes, String filePath);
}

// 工厂类
public class ExporterFactory {
    public static Exporter createExporter(ExportFormat format) {
        return switch (format) {
            case TXT -> new TxtExporter();
            case JSON -> new JsonExporter();
            default -> throw new IllegalArgumentException("不支持的导出格式");
        };
    }
}

// TXT导出实现
public class TxtExporter implements Exporter {
    @Override
    public void export(Note note, String filePath) {
        try (PrintWriter writer = new PrintWriter(filePath)) {
            writer.println("标题: " + note.getTitle());
            writer.println("创建时间: " + note.getCreatedAt());
            writer.println("更新时间: " + note.getUpdatedAt());
            writer.println("标签: " + String.join(", ", note.getTags()));
            writer.println("\n内容:\n" + note.getContent());
        } catch (FileNotFoundException e) {
            System.err.println("导出失败: " + e.getMessage());
        }
    }
    
    // exportAll方法实现...
}
```

### 3.5 搜索模块 (SearchService.java)
```java
public class SearchService {
    public List<Note> searchByKeyword(List<Note> notes, String keyword) {
        return notes.stream()
            .filter(note -> 
                note.getTitle().contains(keyword) || 
                note.getContent().contains(keyword))
            .collect(Collectors.toList());
    }
    
    public List<Note> searchByTag(List<Note> notes, String tag) {
        return notes.stream()
            .filter(note -> note.getTags().contains(tag))
            .collect(Collectors.toList());
    }
}
```

## 4. 命令行接口设计

### 4.1 命令结构
```
pkm [命令] [选项] [参数]
```

### 4.2 支持命令列表

| 命令         | 参数                  | 描述                     | 示例                               |
|--------------|-----------------------|--------------------------|------------------------------------|
| new          | [标题] [内容]         | 创建新笔记               | `pkm new "Java笔记" "面向对象..."` |
| list         | [--tag TAG]           | 列出所有笔记             | `pkm list --tag java`              |
| view         | [笔记ID]              | 查看笔记详情             | `pkm view 123e4567`                |
| edit         | [笔记ID] [新内容]     | 编辑笔记内容             | `pkm edit 123e4567 "更新内容"`     |
| delete       | [笔记ID]              | 删除笔记                 | `pkm delete 123e4567`              |
| tag          | [笔记ID] [标签]       | 添加标签                 | `pkm tag 123e4567 programming`     |
| untag        | [笔记ID] [标签]       | 移除标签                 | `pkm untag 123e4567 old`           |
| search       | [关键词]              | 搜索笔记                 | `pkm search "设计模式"`            |
| export       | [笔记ID] [格式] [路径]| 导出笔记                 | `pkm export 123e4567 txt output.txt` |
| export-all   | [格式] [路径]         | 导出所有笔记             | `pkm export-all json backup.json`  |
| help         |                       | 显示帮助信息             | `pkm help`                         |

### 4.3 交互模式
当不带参数运行程序时，进入交互式命令行界面：
```
> 欢迎使用个人知识管理系统 (CLI版)
> 输入 help 查看可用命令

pkm> list
[1] Java笔记 (2023-10-01) [编程, 学习]
[2] 设计模式笔记 (2023-10-05) [编程, 架构]

pkm> view 1
标题: Java笔记
标签: 编程, 学习
创建时间: 2023-10-01T14:30:00
更新时间: 2023-10-02T10:15:00

内容:
面向对象编程的三大特性：封装、继承、多态...

pkm> 
```

## 5. 数据存储格式
采用JSON格式存储数据，示例结构：
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Java笔记",
    "content": "面向对象编程的三大特性...",
    "tags": ["编程", "学习"],
    "createdAt": "2023-10-01T14:30:00",
    "updatedAt": "2023-10-02T10:15:00"
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "title": "设计模式笔记",
    "content": "单例模式确保一个类只有一个实例...",
    "tags": ["编程", "架构"],
    "createdAt": "2023-10-05T09:45:00",
    "updatedAt": "2023-10-05T09:45:00"
  }
]
```

## 6. 设计模式应用

### 6.1 工厂模式 - 导出器创建
```java
public class ExporterFactory {
    public static Exporter createExporter(ExportFormat format) {
        switch (format) {
            case TXT:
                return new TxtExporter();
            case JSON:
                return new JsonExporter();
            case PDF:
                // 未来扩展PDF导出
                return new PdfExporter();
            default:
                throw new IllegalArgumentException("不支持的导出格式: " + format);
        }
    }
}

// 使用示例
Exporter exporter = ExporterFactory.createExporter(ExportFormat.TXT);
exporter.export(note, "output.txt");
```

### 6.2 策略模式 - 搜索算法（未来扩展）
```java
public interface SearchStrategy {
    List<Note> search(List<Note> notes, String query);
}

public class KeywordSearch implements SearchStrategy {
    @Override
    public List<Note> search(List<Note> notes, String query) {
        // 关键词搜索实现
    }
}

public class TagSearch implements SearchStrategy {
    @Override
    public List<Note> search(List<Note> notes, String query) {
        // 标签搜索实现
    }
}

// 使用示例
SearchStrategy strategy = new KeywordSearch();
List<Note> results = strategy.search(allNotes, "设计模式");
```

## 7. 使用示例

### 7.1 创建新笔记
```
pkm new "设计模式学习" "单例模式：确保一个类只有一个实例..."
```

### 7.2 添加标签
```
pkm tag 550e8400-e29b programming
pkm tag 550e8400-e29b design-patterns
```

### 7.3 搜索笔记
```
pkm search "单例"
```

### 7.4 导出笔记
```
pkm export 550e8400-e29b txt singleton_note.txt
```

## 8. 项目结构
```
pkm-cli/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   ├── cli/
│   │   │   │   ├── App.java          // 程序入口
│   │   │   │   ├── CommandParser.java // 命令解析
│   │   │   │   ├── controller/
│   │   │   │   │   ├── NoteController.java
│   │   │   │   │   └── TagController.java
│   │   │   │   ├── service/
│   │   │   │   │   ├── NoteService.java
│   │   │   │   │   ├── TagService.java
│   │   │   │   │   ├── storage/
│   │   │   │   │   │   ├── StorageService.java
│   │   │   │   │   │   └── JsonStorageService.java
│   │   │   │   │   ├── search/
│   │   │   │   │   │   └── SearchService.java
│   │   │   │   │   └── export/
│   │   │   │   │       ├── Exporter.java
│   │   │   │   │       ├── ExporterFactory.java
│   │   │   │   │       ├── TxtExporter.java
│   │   │   │   │       └── JsonExporter.java
│   │   │   │   └── model/
│   │   │   │       ├── Note.java
│   │   │   │       └── ExportFormat.java
│   ├── resources/
├── pom.xml                          // Maven配置文件
└── notes.json                       // 数据存储文件
```

## 9. 开发路线图

### 版本1.0 - 基础功能 (第1-2周)
- [x] 笔记增删改查
- [x] 内存存储
- [x] 基本命令行界面

### 版本1.1 - 持久化存储 (第3周)
- [x] JSON文件存储
- [x] 数据加载/保存
- [x] 错误恢复机制

### 版本1.2 - 增强功能 (第4周)
- [x] 标签系统
- [x] 基本搜索功能
- [x] 导出功能(TXT/JSON)

### 版本1.3 - 设计模式应用 (第5-6周)
- [x] 工厂模式实现导出器
- [x] 策略模式实现多种搜索算法
- [x] 命令模式重构命令行处理器

### 版本1.4 - 优化与扩展 (第7-8周)
- [ ] 批处理操作
- [ ] 数据导入功能
- [ ] 更丰富的搜索选项
- [ ] 统计功能（笔记数量、标签云）

此设计为后续Web版本奠定了坚实基础，所有核心业务逻辑（NoteService, TagService等）可在Web版本中直接复用，只需替换存储实现和用户界面层。