CherryHQ-cherry-studio/v2-refactor-temp/docs/v2-todo.md

V2 Refactor Global TODO (Cross-Cutting)

This file tracks cross-cutting, whole-refactor tasks only in the v1→v2 migration: teardown of the v1 data stacks and UI libraries, migrator and schema finalization, removal-slated @deprecated sites, and release cleanup. Per-module fine-grained TODOs live in their own docs and are not duplicated here.

Counts are approximate values from a code scan and drift as development proceeds; verify before acting. Status legend: ✅ done ／ 🔲 todo ／ 🟡 in progress.

Overview

Category	Scale	Status
Remove Redux	~100 files / 28 slices	✅ done (store/ deleted)
Remove Dexie	~50 files	🟡 mostly migrated, fallback paths pending
Remove ElectronStore	~10 files	🔲 awaiting migration-window close
Remove antd	~145 files	🟡 settings/knowledge pages already clean
Remove styled-components	~112 files	🟡 in progress
Migrator finalization	4 explicit todos	🟡 14 migrators mostly complete
Schema / migration SQL regen	release gate	🔲 before release

1. Data-Layer Teardown

Remove all three v1 data stacks (Redux / Dexie / ElectronStore), replacing them with Cache / Preference / DataApi.

Redux (~100 files, 28 slices) — ✅ done

The Redux store has been fully removed: every slice migrated to Cache / Preference / DataApi, all useAppSelector / useDispatch call sites repointed, the <Provider> wrappers dropped from the window entry points, and src/renderer/store/ plus the stubbed main-process ReduxService bridge deleted.

Dexie (~50 files)

• Entry points (delete last): src/renderer/databases/index.ts, src/renderer/databases/upgrades.ts.
• Messages / files / knowledge / translate are mostly migrated to SQLite; remaining Dexie reads are mostly fallbacks, and src/renderer/services/db/DexieMessageDataSource.ts is a fallback pending removal.
• Migration-only readers (DexieFileReader / DexieSettingsReader) are used by the v1→v2 migration flow; keep them until the migration window closes, then delete (see §6).

ElectronStore (~10 files)

• Entry point (delete last): src/main/services/ConfigManager.ts (@deprecated Scheduled for removal in v2.0.0, new Store()).
• Boot config is already migrated to v2 by BootConfigMigrator; delete ConfigManager once main-process config reads move to v2 preference.
• PreferencesMigrator reads legacy electron-store keys via the readers; this is migration-only (see §6).

2. UI-Layer Teardown

Migrate the prohibited libraries antd / styled-components fully to @cherrystudio/ui (Tailwind + Shadcn). HeroUI is already removed (0 imports); @cherrystudio/ui is adopted in ~400 files, and settings / knowledge / library / code / notes / mini-apps pages are essentially clean.

• antd and styled-components overlap heavily (~21 files import both); prioritizing the overlapping files clears two items at once.
• Migrate by area in batches:

Area	antd	styled	Priority	Notes
home (main chat UI)	~80	~58	high	core UX: Messages / Inputbar / Blocks
shared Popups	~4	~4	high	AddAssistantPopup / AgentModal / SelectModelPopup; high-traffic shared, migrating them cascades unblocks
agents	~22	~6	medium	can batch with home
paintings (per-provider config pages)	~13	~11	medium	all are antd+styled overlap, good consolidation target
windows	~10	~16	medium	quickAssistant / selection / migrationV2 / trace
history / files / launchpad	~5	~8	low	lightweight
single-file holdouts	3	—	low	SkillsSettings, ModelSelectorLegacy, ProviderLogoPicker

• Special case: src/renderer/components/MarkdownShadowDomRenderer.tsx uses styled-components to inject Shadow DOM CSS and needs dedicated handling.

3. Migrator Finalization

The 14 migrators are mostly complete; only the following have explicit unfinished work:

Item	Location	TODO
ChatMigrator i18n	ChatMigrator.ts:761	// TODO: i18n; fallback topic name is hardcoded English Unnamed Topic, needs an i18n key
KnowledgeVectorMigrator failure handling	KnowledgeVectorMigrator.ts	Base-level execution failures are treated as whole-migration failures (README marks IMPORTANT); confirm the design or implement a skippable-base mode
TranslateMigrator missing test	migrators/__tests__/	The only migrator without a matching test; add TranslateMigrator.test.ts
V1_REQUIRED_VERSION lock-in	versionPolicy.ts:34	TODO: update once the final v1 version is determined (currently 1.9.0, expected ~1.9.x)

Documented intentional skips (must be called out in release notes):

• Knowledge: video / memory items not migrated; directory children not rebuilt; legacy sitemap items migrate as URL items; grouping metadata lost (groupId = null).
• KnowledgeVector: the v1 legacy vector DBs are left untouched in place; after a successful migration they remain on disk as orphans (no cleanup trigger currently — a future user-confirmed cleanup would reclaim the disk).
• Note: activeFilePath / activeNodeId not migrated, re-established at runtime.
• MCP: provider cache not migrated, re-fetched at runtime.

4. Schema / Migration SQL Finalization

• migrations/sqlite-drizzle/ currently holds the incremental dev chain (0000–0012 + meta/); the single-clean-migration regeneration below has NOT happened yet.
• Before release, regenerate a single clean initial migration from the final schemas to clear intermediate dev state (already mandated in CLAUDE.md).
• Note drizzle-kit generate still exits 0 on a forked chain; only pnpm db:migrations:check flags it. Mid-development schema drift is acceptable — do not author patch migrations.

5. In-Code @deprecated Markers

~78 occurrences / 58 files, of which ~39 explicitly say Scheduled for removal in v2.0.0. Removal-slated call sites grouped by subsystem:

Group	Scope	Replacement direction
Redux store slices	29 files (store/*)	DataApi + Preference + SQLite
Dexie / message data sources	4 files (databases/, DexieMessageDataSource, DbService)	DataApi (main chat) / AgentMessageDataSource (agent sessions)
Redux-coupled hooks / main bridge	6 files (useStore / useSettings / useTagsLegacy, ReduxService, etc.)	usePreference / useTags(v2); ReduxService already stubbed
Shared data types	agent / message / provider types (pagination response, citation format, legacy provider flags)	OffsetPaginationResponse, MainTextBlock.references, etc.
Protocol / message format	LanFile* JSON format, web-search accessors	binary frame, CitationMessageBlock
Component / service redesign	CodeEditor→@cherrystudio/ui, FileManager (do not extend), deleteMessageFiles→safeDeleteFiles, etc.	see each annotation

Migration-relevant TODO/FIXME (~53 filtered from ~157; the rest are ordinary code notes) — main workstreams:

• Preference / Provider settings migration (largest, ~18, incl. ProviderSettings/utils/v1ProviderShim.ts "delete after Phase 5").
• Service architecture / lifecycle refactor (~10).
• Redux → SQLite/Drizzle (~9, concentrated in apiServer/routes/knowledge/handlers.ts).
• Phase-2 file-service stubs (~8).
• Message-type migration (~5), IPC handler cleanup (~6), DataApi integration (~3).

6. Release & Cleanup

• Delete migration-only code: DexieFileReader, DexieSettingsReader, the electron-store read paths, etc. are used only by the v1→v2 migration flow; remove after the migration window closes (the lowest supported v1 version stops upgrading).
• Aggregate breaking changes: before release the release manager aggregates docs/breaking-changes/ and translates them into the Chinese user-facing release note (see that directory's README).
• Delete the entire v2-refactor-temp/ directory: confirm the tooling is no longer needed, move any docs worth keeping to their canonical locations, delete the directory, and clean up .gitignore references (see the Cleanup plan in this directory's README).