# Synapse (syn) - 需求规格说明书

> Synapse - 神经突触，象征知识连接与传递。缩写 syn 简短易记，与知识管理高度契合。

---

## 1. 引言

### 1.1 系统愿景

Synapse 是一个基于 Python 3 构建的命令行/TUI 工作流管理工具，提供统一的知识与任务管理平台。

核心理念： "快速捕获、清晰组织、经常回顾、有效执行" (CORE)

### 1.2 核心原则

| 原则 | 描述 |
|------|------|
| 快速捕获 | 最小化录入摩擦，新内容默认进入 Inbox |
| 清晰组织 | Johnny.Decimal 变体 + k8s 风格资源管理 |
| 经常回顾 | GTD、周期性和智能回顾模式 |
| 有效执行 | 任务跟踪、状态管理、自动化工作流 |

### 1.3 目标用户

- **个人用户**：知识管理、任务追踪
- **团队用户**：协作、项目管理
- 支持个人使用，可扩展到团队协作

### 1.4 技术栈

| 组件 | 选型 | 说明 |
|------|------|------|
| TUI | Textual | CSS 布局，鼠标支持，适合 k9s 风格 |
| 存储 | Markdown | 仅 .md 文件，禁止二进制 |
| 索引 | SQLite + FTS5 | Sidecar Index，加速查询 |
| 搜索 | Ripgrep | 全文搜索，高性能 |
| 文件监听 | watchdog | 实时检测外部修改 |
| 版本控制 | Git | 本地 + 远程 |
| 图谱 | Nebula Graph | GraphRAG 就绪（优先级低） |
| 自动化 | 本地 Hook + GitHub Actions | 本地优先，远程通知 |

---

## 2. 资源管理

### 2.1 资源标识

**文件路径**（双层分桶：Area → Category）：

{namespace}/{Area}/{Category}/{Area.Category.ID}-{resource-type}-{title}.md

**示例**：

personal/10/001/10.001.0001-task-完成报告.md
personal/10/002/10.002.0001-note-学习笔记.md
work-project/20/001/20.001.0001-meeting-需求评审.md
_inbox/00/000/00.000.0001-unprocessed-快速记录.md

| 组件 | 说明 |
|------|------|
| namespace | 用户自定义（个人/项目名称），对应目录 |
| Area | JD 顶级分类（00-99），对应子目录 |
| Category | Area 内分类（000-999），对应子目录 |
| ID | Category 内序号（0001-9999） |
| resource-type | 资源类型（task, note, meeting 等） |
| title | 资源标题（可包含中文） |

### 2.2 资源操作规范

当 任何资源被操作时（CRUD）：
- 自动触发 Git 提交
- 更新 modified 时间戳
- commit message 遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- 可选使用 LiteLLM 自动生成 commit message

**commit 类型**：`feat` | fix | docs | refactor | chore | archive

### 2.3 Namespace 管理

Namespace 作为项目/领域的管理容器：
- 对应目录：`{workspace}/{namespace}/`
- 可包含配置文件 .synapse.yaml
- 支持自定义资源类型和 SOP

### 2.4 预设资源类型

#### 2.4.1 类型与字段定义

| 类型 | 必填字段 | 可选字段 |
|------|----------|----------|
| task | title | status, priority, due, start_date, assignee, blocked_by |
| note | title | status, tags, links |
| meeting | title, datetime | status, duration, location, attendees, action_items |
| email | subject | status, from_addr, to_addr, cc, body |
| contact | name | organization, email, phone, custom_fields |
| unprocessed | (无) | status*, title, content |

> \* unprocessed 的 status 字段为系统固定值，不可由用户修改（见 §2.4.2）。

**contact 支持自定义字段**：IP、MAC、微信号等任意键值对。

#### 2.4.2 状态定义

| 类型 | 状态字段 | 可选值 | 默认值 |
|------|----------|--------|--------|
| task | status | todo, in-progress, done, archived | todo |
| meeting | status | scheduled, completed, cancelled | scheduled |
| email | status | unread, read, replied, archived | unread |
| note | status | active, archived | active |
| contact | (无状态) | - | - |
| unprocessed | (固定) | unprocessed | unprocessed |

> **说明**：`unprocessed` 类型状态不可变，归档时自动转换为 note 类型（见 §5.2）。

#### 2.4.3 优先级定义（仅 task）

| 优先级 | 含义 | TUI 颜色 |
|--------|------|----------|
| high | 紧急重要 | 🔴 红色 |
| medium | 一般 | 🟡 黄色 |
| low | 可延后 | 🟢 绿色 |

#### 2.4.4 类型颜色标识

| 类型 | TUI 颜色 | 说明 |
|------|----------|------|
| task | 蓝色 | 待办任务 |
| note | 灰色 | 笔记 |
| meeting | 紫色 | 会议 |
| email | 青色 | 邮件 |
| contact | 橙色 | 联系人 |
| unprocessed | 白色/默认 | 未处理 |

---

## 3. Johnny.Decimal 组织结构

### 3.1 编号规则

采用标准 JD 三级结构，便于分桶管理：

Area.Category.ID
 │      │     │
 │      │     └─ 4位数字 (0001-9999)
 │      └─ 3位数字 (000-999)
 └─ 2位数字 (00-99)

**示例**：`10.001.0015` = Area 10 > Category 001 > 第 15 项

#### 3.1.1 ID 分配器与并发控制

**问题**：快速连续创建文件（如脚本批量导入）时，获取"下一个可用 ID"存在竞态条件。

# 并发场景示例
$ for i in {1..100}; do syn new task --title "Task $i" & done
# 如果无锁机制，多个进程可能拿到相同的 ID

解决方案：SQLite IMMEDIATE 事务 + UNIQUE 约束

⚠️ 为什么 `FOR UPDATE` 在空 Category 不起作用？
- FOR UPDATE 只能锁定 SELECT 返回的行
- 空 Category 的 MAX() 查询返回零行，无行可锁
- 多个进程可能同时得到 max_id = 0`，都尝试分配 `0001

正确方案：BEGIN IMMEDIATE + UNIQUE 约束双重保障