Anyone interested in tree labels?

[chaoliu719]

I just moved from Flomo, and there are some nice features that don't seem to be there, and I wonder if you need them.

Current system:

• tags are stored as arrays of JSON strings in payload
• tags are simple strings with no hierarchy
• tags and memos are tightly coupled

Tag Tree System:

1. Support for hierarchical tags (such as work/Project1, work/Project2)
2. Tags can have independent metadata (description, color, emoji, etc.)
3. Better label management and organization
4. Support tag renaming, merging and other operations
5. You can create relationships between tags.
6. Better performance (through indexing)

Migration Ideas:

• tags just refer to tag nodes
• tag nodes are stored in a tree structure (supporting a hierarchical system)
• tags and notes are stored separately
• notes are indexed by tags
• notes are used to update tag reference counts, backlinks, etc.

Difficulties:

1. Old Data Migration Mode
2. The API may change

[chaoliu719]

Memos 标签 API 破坏性重构设计 V1

🎯 设计原则

1. Tag 是运行时的量：从 memo 内容解析出的结构化元数据，存储在 payload 中用于查询优化
2. Tag 树包含 memo 关系：每个 TagNode 包含使用它的所有 memo_ids，而非简单的引用计数
3. 生命周期由内容驱动：标签完全由 memo 内容决定，无需手动创建
4. 支持层级查询：前缀匹配实现高效的树形查询

🚨 破坏性修改概览

1. 移除现有 Memo 级别 Tag 操作

• ❌ 删除: RenameMemoTag API - 违背 tag 作为 payload 的设计理念
• ❌ 删除: DeleteMemoTag API - 标签应该跟随内容自动管理

2. 数据模型增强

• ✅ 扩展: TagNode 结构，支持层级路径和 memo 关联
• ✅ 新增: 独立的 TagService，专门处理标签相关操作
• ✅ 新增: 批量删除含特定标签的 memos 功能

📊 新的数据结构

TagNode 增强 (/proto/store/tag.proto)

message TagNode {
  // The display name of the tag (e.g., "backend")
  string name = 1;

  // 🚨 NEW: The full hierarchical path (e.g., "/work/project1/backend")
  string full_path = 2;

  // 🚨 NEW: Path segments for efficient querying (e.g., ["work", "project1", "backend"])
  repeated string path_segments = 3;

  // 🚨 NEW: All memo IDs that use this tag (including through child paths)
  repeated string memo_ids = 4;

  // 🚨 NEW: Creator for user isolation
  int32 creator_id = 5;
}

关键设计决策

为什么选择 memo_ids 而非 ref_count？

1. 更丰富的信息：直接知道哪些 memo 使用了该标签
2. 支持复杂操作：批量删除、标签重命名等操作可以直接获取影响的 memo 列表
3. 便于调试：可以直接查看标签和内容的关联关系
4. 统计灵活性：
   • direct_memo_count = len(memo_ids) - 直接使用该标签的数量
   • total_memo_count - 包括子标签的总数量

🔧 新的 API 设计

TagService (/proto/api/v1/tag_service.proto)

service TagService {
  // List all tags with optional filtering
  rpc ListTags(ListTagsRequest) returns (ListTagsResponse) {
    option (google.api.http) = {
      get: "/api/v1/tags"
    };
  }

  // Get specific tag details
  rpc GetTag(GetTagRequest) returns (GetTagResponse) {
    option (google.api.http) = {
      get: "/api/v1/tags/{tag_path=**}"  // ** for path parameters with '/'
    };
    option (google.api.method_signature) = "tag_path";
  }

  // Rename tag globally (supports path moving)
  rpc RenameTag(RenameTagRequest) returns (RenameTagResponse) {
    option (google.api.http) = {
      patch: "/api/v1/tags/{old_tag_path=**}:rename"
      body: "*"
    };
    option (google.api.method_signature) = "old_tag_path,new_tag_path";
  }

  // Delete tag from all content (without deleting memos)
  rpc DeleteTag(DeleteTagRequest) returns (DeleteTagResponse) {
    option (google.api.http) = {
      delete: "/api/v1/tags/{tag_path=**}"
    };
    option (google.api.method_signature) = "tag_path";
  }
}

MemoService 增强

service MemoService {
  // ... 现有的 API ...

  // 🚨 NEW: Batch delete memos by tag (using query parameters)
  rpc BatchDeleteMemosByTag(BatchDeleteMemosByTagRequest) returns (BatchDeleteMemosByTagResponse) {
    option (google.api.http) = {
      delete: "/api/v1/memos"  // 查询参数: ?tag_path=...&include_children=...&dry_run=...
    };
    option (google.api.method_signature) = "tag_path";
  }
}

🌐 RESTful HTTP 映射

URL 设计原则

1. 路径参数处理：使用 {tag_path=**} 支持路径中的 / 字符
2. URL 编码：客户端需要对包含 / 的标签路径进行编码
   • 例：/work/project1 → /api/v1/tags/%2Fwork%2Fproject1
3. 查询参数：复杂参数通过查询参数传递，避免 DELETE 请求体兼容性问题

API 端点映射

操作	HTTP 方法	URL	说明
列出标签	GET	/api/v1/tags?path_prefix=...&include_memo_ids=...	支持前缀过滤
获取标签	GET	/api/v1/tags/{encoded_tag_path}?include_memo_ids=true	获取单个标签详情
重命名标签	PATCH	/api/v1/tags/{encoded_old_path}:rename	请求体包含新路径
删除标签	DELETE	/api/v1/tags/{encoded_tag_path}?strategy=...	从内容中移除标签
批量删除 memos	DELETE	/api/v1/memos?tag_path=...&include_children=...&dry_run=...	删除包含标签的 memos

📋 请求/响应消息

核心请求消息

message ListTagsRequest {
  // Query parameter: ?path_prefix=/work
  string path_prefix = 1;

  // Query parameter: ?include_memo_ids=true
  // Server default: false if not specified
  bool include_memo_ids = 2;

  // Query parameter: ?include_hierarchy=true
  // Server default: true if not specified
  bool include_hierarchy = 3;
}

message GetTagRequest {
  // Path parameter: /api/v1/tags/{tag_path}
  // URL encoded if contains '/' (e.g., %2Fwork%2Fproject1)
  string tag_path = 1 [(google.api.field_behavior) = REQUIRED];

  // Query parameter: ?include_memo_ids=true
  // Server default: true if not specified
  bool include_memo_ids = 2;
}

message RenameTagRequest {
  // Path parameter: /api/v1/tags/{old_tag_path}:rename
  string old_tag_path = 1 [(google.api.field_behavior) = REQUIRED];

  // Request body field
  string new_tag_path = 2 [(google.api.field_behavior) = REQUIRED];

  // Request body field - Server default: true if not specified
  bool move_children = 3;
}

message DeleteTagRequest {
  // Path parameter: /api/v1/tags/{tag_path}
  string tag_path = 1 [(google.api.field_behavior) = REQUIRED];

  enum DeleteStrategy {
    REMOVE_FROM_CONTENT = 0;  // Remove tag from all memo content
    DELETE_RELATED_MEMOS = 1; // Delete memos containing this tag
  }

  // Query parameter: ?strategy=REMOVE_FROM_CONTENT
  // Server default: REMOVE_FROM_CONTENT if not specified
  DeleteStrategy strategy = 2;
}

message BatchDeleteMemosByTagRequest {
  // Query parameter: ?tag_path=/work/project1
  string tag_path = 1 [(google.api.field_behavior) = REQUIRED];

  // Query parameter: ?include_children=true
  // Server default: true if not specified
  bool include_children = 2;

  // Query parameter: ?dry_run=true
  // Server default: false if not specified
  bool dry_run = 3;
}

统一的响应结构

message TagWithMemos {
  memos.store.TagNode tag_node = 1;

  // Direct memo count (excluding child tags)
  int32 direct_memo_count = 2;

  // Total memo count (including child tags)
  int32 total_memo_count = 3;

  // Child tag paths
  repeated string child_paths = 4;

  // Parent tag path
  string parent_path = 5;
}

message ListTagsResponse {
  repeated TagWithMemos tags = 1;
  int32 total_count = 2;
}

message GetTagResponse {
  TagWithMemos tag = 1;
}

message RenameTagResponse {
  // Affected memo IDs
  repeated string affected_memo_ids = 1;

  // Old and new tag paths that were changed
  map<string, string> renamed_paths = 2; // old_path -> new_path
}

message DeleteTagResponse {
  // Memo IDs that had this tag removed
  repeated string affected_memo_ids = 1;

  // Tag paths that were deleted
  repeated string deleted_tag_paths = 2;
}

message BatchDeleteMemosByTagResponse {
  repeated string deleted_memo_ids = 1;
  int32 deleted_count = 2;
  repeated string affected_tag_paths = 3;
}

🔄 数据流和生命周期

Tag 生命周期管理

1. 创建：memo 内容解析时自动创建 TagNode 并填充 memo_ids
2. 更新：memo 内容变更时，更新相关 TagNode 的 memo_ids
3. 删除：memo_ids 为空的 TagNode 自动清理

层级查询逻辑

-- 查找所有 /work 相关的标签（包括子标签）
SELECT * FROM tag_nodes WHERE full_path LIKE '/work%'

-- 查找所有使用 /work 标签的 memos（包括子标签的 memos）
SELECT DISTINCT memo_id FROM tag_nodes
WHERE full_path LIKE '/work%'
AND memo_id IN (SELECT unnest(memo_ids))

重命名操作流程

1. 验证：检查新路径是否已存在
2. 收集：获取所有需要重命名的标签路径（包括子标签）
3. 更新：在事务中更新所有相关的 memo 内容和 TagNode 记录
4. 返回：返回所有受影响的 memo_ids 和路径映射