pkm/项目说明（命令行版本）.md

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

1. 设计目标

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

2. 系统架构

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

3. 核心模块设计

3.1 笔记实体类 (Note.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)

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)

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 导出模块 (使用工厂模式)

// 导出器接口
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)

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格式存储数据，示例结构：

[
  {
    "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 工厂模式 - 导出器创建

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 策略模式 - 搜索算法（未来扩展）

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周)

• 笔记增删改查
• 内存存储
• 基本命令行界面

版本1.1 - 持久化存储 (第3周)

• JSON文件存储
• 数据加载/保存
• 错误恢复机制

版本1.2 - 增强功能 (第4周)

• 标签系统
• 基本搜索功能
• 导出功能(TXT/JSON)

版本1.3 - 设计模式应用 (第5-6周)

• 工厂模式实现导出器
• 策略模式实现多种搜索算法
• 命令模式重构命令行处理器

版本1.4 - 优化与扩展 (第7-8周)

• 批处理操作
• 数据导入功能
• 更丰富的搜索选项
• 统计功能（笔记数量、标签云）

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