Archive

resources/system_design/20260606123307.md

@@ -0,0 +1,126 @@
+## Implementation approach
+
+本项目使用Python标准库实现，无需第三方依赖。命令行参数解析采用argparse模块，数据持久化使用json模块，文件存储于用户主目录下的.todo_cli/todos.json。核心逻辑封装在TodoManager类中，提供增删改查方法。CLI接口通过TodoCLI类处理用户输入并调用TodoManager。数据模型TodoItem使用dataclass简化定义。整体设计遵循单一职责原则，确保代码简洁可维护。
+
+## File list
+
+- main.py
+- todo.py
+- storage.py
+
+## Data structures and interfaces
+
+classDiagram
+    class TodoItem {
+        -int id
+        -str title
+        -str description
+        -str due_date
+        -bool completed
+        -str created_at
+        +__init__(id: int, title: str, description: str = "", due_date: str = "", completed: bool = False, created_at: str = "")
+        +to_dict() dict
+        +from_dict(data: dict) TodoItem
+    }
+    class Storage {
+        -str file_path
+        +__init__(file_path: str)
+        +load() list[dict]
+        +save(data: list[dict]) None
+    }
+    class TodoManager {
+        -list[TodoItem] items
+        -Storage storage
+        -int next_id
+        +__init__(storage: Storage)
+        +add(title: str, description: str = "", due_date: str = "") TodoItem
+        +list_all() list[TodoItem]
+        +list_by_status(completed: bool) list[TodoItem]
+        +mark_done(item_id: int) bool
+        +mark_undone(item_id: int) bool
+        +delete(item_id: int) bool
+        +edit(item_id: int, title: str = None, description: str = None, due_date: str = None, completed: bool = None) bool
+        +_load() None
+        +_save() None
+        +_find_by_id(item_id: int) TodoItem | None
+    }
+    class TodoCLI {
+        -TodoManager manager
+        -argparse.ArgumentParser parser
+        +__init__(manager: TodoManager)
+        +run(args: list[str] = None) None
+        +_setup_parser() None
+        +_handle_add(args) None
+        +_handle_list(args) None
+        +_handle_done(args) None
+        +_handle_delete(args) None
+        +_handle_edit(args) None
+    }
+    TodoCLI --> TodoManager
+    TodoManager --> Storage
+    TodoManager --> TodoItem
+    Storage ..> TodoItem : uses to_dict/from_dict
+
+
+## Program call flow
+
+sequenceDiagram
+    participant User as 用户
+    participant CLI as TodoCLI
+    participant Manager as TodoManager
+    participant Storage as Storage
+    participant File as JSON文件
+    User->>CLI: python main.py add "任务标题" -d "描述" -due 2025-01-01
+    CLI->>CLI: _setup_parser() 解析参数
+    CLI->>CLI: _handle_add(args)
+    CLI->>Manager: add(title, description, due_date)
+    Manager->>Manager: 生成新TodoItem，设置id=next_id
+    Manager->>Manager: 将item加入items列表
+    Manager->>Manager: _save()
+    Manager->>Storage: save([item.to_dict() for item in items])
+    Storage->>File: 写入JSON文件
+    File-->>Storage: 成功
+    Storage-->>Manager: None
+    Manager-->>CLI: 返回新TodoItem
+    CLI-->>User: 打印添加成功信息
+
+    User->>CLI: python main.py list
+    CLI->>CLI: _handle_list(args)
+    CLI->>Manager: list_all()
+    Manager->>Manager: 返回items列表
+    Manager-->>CLI: list[TodoItem]
+    CLI->>CLI: 格式化输出表格
+    CLI-->>User: 显示所有任务
+
+    User->>CLI: python main.py done 1
+    CLI->>CLI: _handle_done(args)
+    CLI->>Manager: mark_done(1)
+    Manager->>Manager: _find_by_id(1) -> item
+    Manager->>Manager: item.completed = True
+    Manager->>Manager: _save()
+    Manager-->>CLI: True
+    CLI-->>User: 打印标记成功
+
+    User->>CLI: python main.py delete 1
+    CLI->>CLI: _handle_delete(args)
+    CLI->>Manager: delete(1)
+    Manager->>Manager: _find_by_id(1) -> item
+    Manager->>Manager: 从items中移除
+    Manager->>Manager: _save()
+    Manager-->>CLI: True
+    CLI-->>User: 打印删除成功
+
+    User->>CLI: python main.py edit 1 --title "新标题" --description "新描述"
+    CLI->>CLI: _handle_edit(args)
+    CLI->>Manager: edit(1, title="新标题", description="新描述")
+    Manager->>Manager: _find_by_id(1) -> item
+    Manager->>Manager: 更新item属性
+    Manager->>Manager: _save()
+    Manager-->>CLI: True
+    CLI-->>User: 打印编辑成功
+
+
+## Anything UNCLEAR
+
+无
+