ADR 0024：记录用户元数据落在 catalog 记录字段，星标用保留 tag

状态：已接受 日期：2026-08-29 关联：ADR 0008（修订：catalog 为产物持久化）；CONTEXT.md（记录备注 / 标签 / 星标）

背景

GUI 需要给轨道库记录提供用户备注与单级收藏星标。备选方案：

• A. e2m2e 上游 catalog 新增 favorite 布尔字段（最正规，跨仓 schema 变更）

• B. GUI 侧边车存储（localStorage / 独立 JSON，不动数据层）

• C. 复用记录现有可写字段：tags（字符串数组）+ note（自由文本），写入口 catalog_tag 已存在

一个反直觉的事实促成本决策：记录的 tags/note 本就用户可编辑（记录详情面板），但面板标题叫"教学标注 (Tags & Note)"，与 CONTEXT.md 画布层"标注"概念撞名，用户以为那是系统写死的内容——"添加注释"能力其实早已存在，缺的是术语与入口。历史界面名"教学标注"自本 ADR 起退役，UI 主术语改为"备注"。

决策

• 备注复用 note 字段；UI 更名，并在项目树节点悬停显示备注摘要、右键菜单提供"编辑备注"直入编辑。

• 星标 = tags 的保留值 "★"；树节点星形图标点击切换，"仅看星标"按 tags 前端过滤（查询摘要已带回 tags）。

• 不加 GUI 侧边车，不新增上游字段。

理由

• catalog_tag 已可写，零上游改动；星标/备注随记录文件走（拷贝 catalog 目录给别人即在），与 ADR 0008"文件是事实来源、重启不丢"的库哲学一致。

• 方案 B 会让元数据与记录分离——catalog 目录拷走或换机器后星标丢失，形成双轨数据。

• 方案 A 的正规性收益（独立布尔字段 + 后端查询）当前用不上：单级收藏前端过滤已够。

后果

• tags 中的 "★" 是保留值，用户普通标签不得占用（编辑界面应过滤）。

• 若将来上游真加 favorite 字段，需一次性扫描全库记录迁移——机械但涉及每个记录文件重写，届时再议。

• 备注与星标仅适用于 catalog 记录；catalog 体系之外的产物（转移等 output/ 扫描项）无此能力。