def allocate_next_id(namespace: str, area: str, category: str) -> str:
    """
    原子分配下一个可用 ID
    使用 IMMEDIATE 事务模式 + UNIQUE 约束确保并发安全
    """
    max_retries = 3
    for attempt in range(max_retries):
        try:
            # ⚠️ 关键：使用 IMMEDIATE 模式，事务开始时立即获取写锁
            # 这会阻塞其他写事务，避免空 Category 的竞态条件
            cursor.execute("BEGIN IMMEDIATE")
            
            # 1. 查询当前 Category 下最大 ID
            # 同时查询 id_reservations 表（可能有预占但未使用的 ID）
            cursor.execute("""
                SELECT MAX(id_num) FROM (
                    SELECT CAST(SUBSTR(jd_number, -4) AS INTEGER) as id_num
                    FROM resources 
                    WHERE namespace = ? AND jd_number LIKE ?
                    UNION ALL
                    SELECT CAST(SUBSTR(jd_number, -4) AS INTEGER) as id_num
                    FROM id_reservations
                    WHERE namespace = ? AND jd_number LIKE ?
                )
            """, (namespace, f"{area}.{category}.%", 
                  namespace, f"{area}.{category}.%"))
            
            row = cursor.fetchone()
            max_id = (row[0] if row else None) or 0
            next_id = max_id + 1
            
            if next_id > 9999:
                cursor.execute("ROLLBACK")
                raise OverflowError(f"Category {area}.{category} ID exhausted (max 9999)")
            
            # 2. 预占 ID（UNIQUE 约束是最后一道防线）
            new_jd = f"{area}.{category}.{next_id:04d}"
            cursor.execute("""
                INSERT INTO id_reservations (jd_number, namespace, reserved_at)
                VALUES (?, ?, datetime('now'))
            """, (new_jd, namespace))
            
            cursor.execute("COMMIT")
            return new_jd
            
        except sqlite3.IntegrityError:
            # UNIQUE 约束冲突，说明有并发分配，重试
            cursor.execute("ROLLBACK")
            if attempt == max_retries - 1:
                raise AllocationError(f"Failed to allocate ID after {max_retries} retries")
            continue  # 重试

def release_reservation(jd_number: str):
    """创建失败时释放预占的 ID"""
    cursor.execute("DELETE FROM id_reservations WHERE jd_number = ?", (jd_number,))

**id_reservations 表结构**：

CREATE TABLE id_reservations (
    jd_number TEXT PRIMARY KEY,   -- ⚠️ UNIQUE 约束，防止重复分配
    namespace TEXT NOT NULL,
    reserved_at TEXT NOT NULL,
    INDEX idx_namespace_jd (namespace, jd_number)
);

-- 定期清理过期预占（超过 1 小时未使用）
DELETE FROM id_reservations 
WHERE reserved_at < datetime('now', '-1 hour');

**并发控制机制**：

| 层级 | 机制 | 作用 |
|------|------|------|
| 1 | BEGIN IMMEDIATE | 事务级写锁，阻塞其他写事务 |
| 2 | 查询含 id_reservations | 感知其他进程的预占 |
| 3 | jd_number PRIMARY KEY | UNIQUE 约束，最后防线 |
| 4 | 重试机制 | 冲突时自动重试 |

**批量导入优化**：

```bash
# 批量模式：一次性预占 N 个 ID，减少锁竞争
syn import --batch /path/to/files/ --count 100

# 内部实现：单次事务分配 100 个连续 ID

**ID 耗尽处理**：
- 每个 Category 最多 9999 个资源
- 接近上限（>9000）时 CLI/TUI 显示警告
- 建议用户创建新 Category 或清理归档资源

### 3.2 短 ID 支持

为降低 CLI 输入摩擦，支持 Git 风格的短 ID：

| 输入方式 | 示例 | 匹配规则 |
|----------|------|----------|
| 完整 ID | 10.001.0015 | 精确匹配 |
| 短 ID | 10.1.15 | 自动补零 → 10.001.0015 |
| 最短 ID | 15 | 当前 Namespace 内唯一匹配 |
| 标题模糊 | 设计文档 | Fuzzy Finder 模糊搜索 |

syn show 15           # 当前 Namespace 内唯一，直接匹配
syn show 10.1.15      # 自动补零
syn show 设计         # Fuzzy Finder

**歧义处理**：当短 ID 匹配到多个结果时：
- **CLI**：报错并列出候选项，用户需输入更精确的 ID
- **TUI**：弹窗让用户选择

$ syn show 15
Error: Ambiguous ID '15'. Did you mean:
  [1] 10.001.0015 - 完成项目设计 (task)
  [2] 20.001.0015 - 会议纪要 (meeting)
Use full ID or choose: syn show 10.001.0015

**Shell 自动补全**：CLI 必须实现 Tab completion（支持 Bash/Zsh/Fish）。

### 3.3 目录结构（双层分桶）