Skip to content

feat(data): add note metadata DataApi and cache schemas for v2 migration#13312

Open
DeJeune wants to merge 12 commits intov2from
DeJeune/note-v2-data-api
Open

feat(data): add note metadata DataApi and cache schemas for v2 migration#13312
DeJeune wants to merge 12 commits intov2from
DeJeune/note-v2-data-api

Conversation

@DeJeune
Copy link
Collaborator

@DeJeune DeJeune commented Mar 9, 2026

What this PR does

Before this PR:
Note starred paths were stored in Redux (store/note.ts) with no database persistence. UI state like active file path and expanded paths had no v2 data layer support.

After this PR:

  • Adds a note SQLite table for note metadata (path, isStarred, timestamps), extensible for future fields (AI tags, etc.)
  • Adds DataApi endpoints (GET /notes, GET/PATCH/DELETE /notes/:path) with NoteService
  • Adds PersistCache keys (notes.active_file_path, notes.expanded_paths) for UI state
  • Preference keys for note settings were already mapped in a previous PR

Why we need it and why it was done in this way

This is the data API layer (Phase 2) for migrating store/note.ts to the v2 architecture. The note table uses file path as primary key since notes are filesystem-based. It is designed to be extensible — isStarred is the first metadata field, with future fields (AI features, tags) planned under the same table.

The following tradeoffs were made:

  • Used path as primary key instead of UUID — notes are identified by filesystem path, making path the natural key
  • getByPath auto-creates metadata entries (upsert) — avoids requiring explicit creation before use

The following alternatives were considered:

  • A separate note_starred table with only path+createdAt — rejected because the notes domain will grow with more metadata fields

Breaking changes

None.

Special notes for your reviewer

  • This PR only covers the data API layer (DB schema, service, handler, cache schemas). Renderer-side migration (replacing Redux hooks) will be a follow-up PR.
  • The 10 preference keys for note settings were already defined in preferenceSchemas.ts and PreferencesMappings.ts in a previous commit.

Checklist

  • PR: The PR description is expressive enough and will help future contributors
  • Code: Write code that humans can understand and Keep it simple
  • Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
  • Upgrade: Impact of this change on upgrade flows was considered and addressed if required
  • Documentation: Not required — internal data layer refactoring
  • Self-review: I have reviewed my own code before requesting review from others

Release note

NONE

Add the data API layer for notes management:
- SQLite `note` table with path-based primary key, isStarred, timestamps
- CRUD API endpoints: GET/PATCH/DELETE /notes/:path, GET /notes
- NoteService with upsert semantics for metadata management
- PersistCache keys for notes UI state (active_file_path, expanded_paths)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DeJeune DeJeune requested a review from a team March 9, 2026 02:11
@DeJeune DeJeune requested a review from 0xfullex as a code owner March 9, 2026 02:11
…igration

Reads starredPaths from Redux note slice and inserts them into the
note table with isStarred=true. Registered in migration pipeline
with order=5 (after chat migrator).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@DeJeune DeJeune added this to the v2.0.0 milestone Mar 9, 2026
@DeJeune DeJeune added the v2 label Mar 9, 2026
@DeJeune
Copy link
Collaborator Author

DeJeune commented Mar 9, 2026

Note

This issue/comment/review was translated by Claude.

Need to consider the collaboration with #12557


Original Content 需要考虑到 #12557 的合作

DeJeune and others added 9 commits March 9, 2026 10:37
Replace path-only primary key with UUID id + unique path column.
Path varies across devices; id serves as stable cross-device identifier
for future cloud sync scenarios.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…restore

- Add relativePath column (relative to notesRoot, forward-slash normalized)
- NoteService computes relativePath via path.relative() from preference
- NoteMigrator reads notesPath from Redux to compute relativePath during migration
- Enables Mac→Win backup-restore by matching notes via relativePath

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
path can always be computed at runtime as notesRoot + relativePath.
Keeping only relativePath avoids data redundancy and makes cross-platform
backup-restore work without path fixup.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Generate migration 0002 to create the `note` table with UUID primary key,
unique `relative_path` column, `is_starred` flag, and timestamps.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
…nd docs

- Register noteTable in MigrationEngine.verifyAndClearNewTables so note
  table is properly cleared on re-migration
- Add 12 unit tests for NoteMigrator (prepare/execute/validate phases)
- Add README-NoteMigrator.md documenting data sources, field mappings,
  transformations, and edge cases

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
…paths

NoteMigrator now recursively scans the notes directory for all .md files
and creates note table entries for each, with isStarred set based on
Redux starredPaths membership. Previously only starred paths from Redux
were migrated, missing all non-starred note files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
…others

Revert filesystem scanning in NoteMigrator. Only migrate starred paths
from Redux; non-starred note files will be lazily registered by
NoteService at runtime. This keeps migration fast, avoids filesystem
dependency, and uses a single registration code path.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
Non-starred note files need to be lazily registered by NoteService
when the notes directory is first loaded at runtime. Added TODO
comment to track this pending renderer-layer work.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
@EurFelux
Copy link
Collaborator

Also #12150

…tion plan

Add comments documenting how the note table will integrate with the
file manager node table (PR #13451): add nodeId FK, backfill from
relativePath, and eventually derive path from node tree.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants