From f3e5ebdb0ad3e8f40aa5d399d6f43cd7b9c192cf Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:09:11 +0800 Subject: [PATCH 001/117] chore: clean Tauri package metadata --- src-tauri/Cargo.toml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index eeb0a99..181ca3e 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -1,16 +1,13 @@ [package] name = "timeprism" version = "0.1.0" -description = "A Tauri App" -authors = ["you"] +description = "A Windows-first, local-first desktop time and attention tracker." +authors = ["Air000000"] edition = "2021" - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +license = "MIT" +repository = "https://github.com/Air000000/timeprism" [lib] -# The `_lib` suffix may seem redundant but it is necessary -# to make the lib name unique and wouldn't conflict with the bin name. -# This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519 name = "timeprism_lib" crate-type = ["staticlib", "cdylib", "rlib"] @@ -32,4 +29,3 @@ windows-sys = { version = "0.59", features = [ "Win32_System_Threading" ] } tauri-plugin-single-instance = "2" - From b04ca82d1ebfb611952e72593609fb9bfe954551 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:12:03 +0800 Subject: [PATCH 002/117] test: define database lifecycle regression coverage --- src-tauri/src/db/tests.rs | 269 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 src-tauri/src/db/tests.rs diff --git a/src-tauri/src/db/tests.rs b/src-tauri/src/db/tests.rs new file mode 100644 index 0000000..30f1c18 --- /dev/null +++ b/src-tauri/src/db/tests.rs @@ -0,0 +1,269 @@ +use std::fs; +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use rusqlite::Connection; + +fn temp_db_path(label: &str) -> PathBuf { + let unique = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("system time after unix epoch") + .as_nanos(); + std::env::temp_dir().join(format!( + "timeprism-{label}-{}-{unique}.db", + std::process::id() + )) +} + +fn remove_sqlite_files(path: &Path) { + let _ = fs::remove_file(path); + for suffix in ["-wal", "-shm"] { + let _ = fs::remove_file(format!("{}{}", path.display(), suffix)); + } +} + +fn table_exists(conn: &Connection, table: &str) -> bool { + conn.query_row( + "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)", + [table], + |row| row.get::<_, i64>(0), + ) + .expect("query sqlite_master") + == 1 +} + +fn column_exists(conn: &Connection, table: &str, column: &str) -> bool { + let mut stmt = conn + .prepare(&format!("PRAGMA table_info({table})")) + .expect("prepare table info"); + stmt.query_map([], |row| row.get::<_, String>(1)) + .expect("query table info") + .map(|row| row.expect("read column name")) + .any(|name| name == column) +} + +#[test] +fn fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens() { + let path = temp_db_path("fresh"); + remove_sqlite_files(&path); + + { + let conn = Connection::open(&path).expect("open fresh sqlite file"); + super::migrations::initialize_connection(&conn).expect("initialize database"); + + let foreign_keys: i64 = conn + .pragma_query_value(None, "foreign_keys", |row| row.get(0)) + .expect("read foreign_keys pragma"); + assert_eq!(foreign_keys, 1); + + for table in [ + "categories", + "task_sessions", + "app_usage_logs", + "app_rules", + "app_config", + "app_whitelist", + "reminders", + "daily_heatmap_snapshot", + ] { + assert!(table_exists(&conn, table), "missing table {table}"); + } + + let browser_mode: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'browser_title_mode'", + [], + |row| row.get(0), + ) + .expect("read default browser mode"); + assert_eq!(browser_mode, "BLUR"); + + let code_rule: String = conn + .query_row( + "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", + [], + |row| row.get(0), + ) + .expect("read default code rule"); + assert_eq!(code_rule, "LEARN"); + } + + { + let reopened = Connection::open(&path).expect("reopen initialized sqlite file"); + assert!(table_exists(&reopened, "app_rules")); + let rule_count: i64 = reopened + .query_row("SELECT COUNT(*) FROM app_rules", [], |row| row.get(0)) + .expect("count persisted rules"); + assert!(rule_count >= 10); + } + + remove_sqlite_files(&path); +} + +#[test] +fn database_initialization_is_idempotent_and_preserves_user_values() { + let path = temp_db_path("idempotent"); + remove_sqlite_files(&path); + let conn = Connection::open(&path).expect("open sqlite file"); + + super::migrations::initialize_connection(&conn).expect("first initialization"); + conn.execute( + "UPDATE app_config SET value = 'NONE' WHERE key = 'browser_title_mode'", + [], + ) + .expect("customize browser title mode"); + conn.execute( + "UPDATE app_rules SET mapped_type = 'REST' WHERE process_name = 'code.exe'", + [], + ) + .expect("customize code rule"); + + super::migrations::initialize_connection(&conn).expect("second initialization"); + + let browser_mode: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'browser_title_mode'", + [], + |row| row.get(0), + ) + .expect("read customized browser mode"); + assert_eq!(browser_mode, "NONE"); + + let code_rule: String = conn + .query_row( + "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", + [], + |row| row.get(0), + ) + .expect("read customized code rule"); + assert_eq!(code_rule, "REST"); + + let root_count: i64 = conn + .query_row( + "SELECT COUNT(*) FROM categories WHERE id IN (1, 2)", + [], + |row| row.get(0), + ) + .expect("count root categories"); + assert_eq!(root_count, 2); + + drop(conn); + remove_sqlite_files(&path); +} + +#[test] +fn legacy_schema_is_upgraded_without_losing_existing_rows() { + let path = temp_db_path("legacy-schema"); + remove_sqlite_files(&path); + let conn = Connection::open(&path).expect("open legacy sqlite file"); + + conn.execute_batch( + r#" + CREATE TABLE app_rules ( + process_name TEXT PRIMARY KEY, + mapped_type TEXT NOT NULL, + privacy_level TEXT NOT NULL + ); + INSERT INTO app_rules (process_name, mapped_type, privacy_level) + VALUES ('legacy.exe', 'LEARN', 'NORMAL'); + + CREATE TABLE reminders ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + content TEXT NOT NULL, + repeat_rule TEXT NOT NULL, + remind_at INTEGER NULL, + daily_time_minutes INTEGER NULL, + is_completed INTEGER NOT NULL DEFAULT 0, + completed_day_key TEXT NULL, + completed_at INTEGER NULL, + snooze_until INTEGER NULL, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ); + INSERT INTO reminders ( + content, repeat_rule, remind_at, daily_time_minutes, is_completed, + completed_day_key, completed_at, snooze_until, created_at, updated_at + ) VALUES ('legacy reminder', 'DAILY', NULL, 540, 0, NULL, NULL, NULL, 100, 100); + "#, + ) + .expect("create legacy schema"); + + super::migrations::initialize_connection(&conn).expect("migrate legacy schema"); + + assert!(column_exists(&conn, "app_rules", "created_at")); + assert!(column_exists(&conn, "app_rules", "updated_at")); + assert!(column_exists(&conn, "reminders", "weekly_days")); + assert!(column_exists(&conn, "reminders", "sort_order")); + + let mapped_type: String = conn + .query_row( + "SELECT mapped_type FROM app_rules WHERE process_name = 'legacy.exe'", + [], + |row| row.get(0), + ) + .expect("legacy app rule survived migration"); + assert_eq!(mapped_type, "LEARN"); + + let reminder: (String, i64) = conn + .query_row( + "SELECT content, daily_time_minutes FROM reminders WHERE content = 'legacy reminder'", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .expect("legacy reminder survived migration"); + assert_eq!(reminder, ("legacy reminder".to_string(), 540)); + + drop(conn); + remove_sqlite_files(&path); +} + +#[test] +fn legacy_database_file_is_copied_once_to_preferred_location() { + let legacy_path = temp_db_path("legacy-file"); + let preferred_path = temp_db_path("preferred-file"); + remove_sqlite_files(&legacy_path); + remove_sqlite_files(&preferred_path); + + { + let legacy = Connection::open(&legacy_path).expect("create legacy sqlite file"); + legacy + .execute_batch( + "CREATE TABLE marker (value TEXT NOT NULL); INSERT INTO marker VALUES ('legacy');", + ) + .expect("seed legacy database"); + } + + super::connection::migrate_legacy_db_files(&legacy_path, &preferred_path) + .expect("copy legacy database"); + + { + let preferred = Connection::open(&preferred_path).expect("open copied preferred db"); + let marker: String = preferred + .query_row("SELECT value FROM marker", [], |row| row.get(0)) + .expect("read copied marker"); + assert_eq!(marker, "legacy"); + preferred + .execute("UPDATE marker SET value = 'preferred'", []) + .expect("customize preferred database"); + } + + { + let legacy = Connection::open(&legacy_path).expect("reopen legacy db"); + legacy + .execute("UPDATE marker SET value = 'changed-legacy'", []) + .expect("change legacy database"); + } + + super::connection::migrate_legacy_db_files(&legacy_path, &preferred_path) + .expect("second legacy migration is a no-op"); + + let preferred = Connection::open(&preferred_path).expect("reopen preferred db"); + let marker: String = preferred + .query_row("SELECT value FROM marker", [], |row| row.get(0)) + .expect("read preserved preferred marker"); + assert_eq!(marker, "preferred"); + + drop(preferred); + remove_sqlite_files(&legacy_path); + remove_sqlite_files(&preferred_path); +} From 970267cd42cf91c3e8581fd48eef04a763bf277a Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:12:09 +0800 Subject: [PATCH 003/117] test: enable database lifecycle regression suite --- src-tauri/src/db/mod.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src-tauri/src/db/mod.rs b/src-tauri/src/db/mod.rs index 221c82c..45fc809 100644 --- a/src-tauri/src/db/mod.rs +++ b/src-tauri/src/db/mod.rs @@ -1,2 +1,5 @@ pub mod connection; pub mod migrations; + +#[cfg(test)] +mod tests; From cd6797a35644cf30bc28c30948e91342c764820e Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:12:26 +0800 Subject: [PATCH 004/117] test: define database initialization integration coverage --- src-tauri/src/db/database_tests.rs | 152 +++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 src-tauri/src/db/database_tests.rs diff --git a/src-tauri/src/db/database_tests.rs b/src-tauri/src/db/database_tests.rs new file mode 100644 index 0000000..f7a8916 --- /dev/null +++ b/src-tauri/src/db/database_tests.rs @@ -0,0 +1,152 @@ +use rusqlite::Connection; + +use super::migrations::init_connection; + +fn table_exists(conn: &Connection, table: &str) -> bool { + conn.query_row( + "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)", + [table], + |row| row.get::<_, i64>(0), + ) + .expect("query table existence") + == 1 +} + +fn column_exists(conn: &Connection, table: &str, column: &str) -> bool { + let mut stmt = conn + .prepare(&format!("PRAGMA table_info({table})")) + .expect("prepare table info"); + stmt.query_map([], |row| row.get::<_, String>(1)) + .expect("query table info") + .any(|name| name.expect("parse column name") == column) +} + +#[test] +fn fresh_database_initialization_creates_schema_and_defaults() { + let conn = Connection::open_in_memory().expect("open in-memory db"); + + init_connection(&conn).expect("initialize fresh database"); + + for table in [ + "categories", + "task_sessions", + "app_usage_logs", + "app_rules", + "app_config", + "app_whitelist", + "reminders", + "daily_heatmap_snapshot", + ] { + assert!(table_exists(&conn, table), "missing table: {table}"); + } + + let learn_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 1", [], |row| row.get(0)) + .expect("load LEARN root name"); + let rest_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 2", [], |row| row.get(0)) + .expect("load REST root name"); + assert_eq!(learn_name, "学习"); + assert_eq!(rest_name, "休息"); + + let browser_mode: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'browser_title_mode'", + [], + |row| row.get(0), + ) + .expect("load browser_title_mode"); + assert_eq!(browser_mode, "BLUR"); + + let code_rule: (String, String) = conn + .query_row( + "SELECT mapped_type, privacy_level FROM app_rules WHERE process_name = 'code.exe'", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .expect("load code.exe rule"); + assert_eq!(code_rule, ("LEARN".into(), "NORMAL".into())); + + let foreign_keys: i64 = conn + .query_row("PRAGMA foreign_keys", [], |row| row.get(0)) + .expect("read foreign_keys pragma"); + assert_eq!(foreign_keys, 1); +} + +#[test] +fn database_initialization_is_idempotent_and_preserves_user_values() { + let conn = Connection::open_in_memory().expect("open in-memory db"); + init_connection(&conn).expect("initialize database first time"); + + conn.execute( + "UPDATE app_config SET value = '3600' WHERE key = 'heatmap_goal_seconds'", + [], + ) + .expect("customize heatmap goal"); + conn.execute( + "UPDATE app_rules SET mapped_type = 'REST' WHERE process_name = 'code.exe'", + [], + ) + .expect("customize code.exe rule"); + + init_connection(&conn).expect("initialize database second time"); + + let goal: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'heatmap_goal_seconds'", + [], + |row| row.get(0), + ) + .expect("load customized goal"); + let code_mapping: String = conn + .query_row( + "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", + [], + |row| row.get(0), + ) + .expect("load customized code mapping"); + + assert_eq!(goal, "3600"); + assert_eq!(code_mapping, "REST"); +} + +#[test] +fn legacy_reminders_schema_is_upgraded_without_losing_rows() { + let conn = Connection::open_in_memory().expect("open in-memory db"); + conn.execute_batch( + r#" + CREATE TABLE reminders ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + content TEXT NOT NULL, + repeat_rule TEXT NOT NULL CHECK(repeat_rule IN ('NONE', 'DAILY')), + remind_at INTEGER NULL, + daily_time_minutes INTEGER NULL, + is_completed INTEGER NOT NULL DEFAULT 0, + completed_day_key TEXT NULL, + completed_at INTEGER NULL, + snooze_until INTEGER NULL, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ); + INSERT INTO reminders ( + content, repeat_rule, remind_at, daily_time_minutes, + is_completed, created_at, updated_at + ) VALUES ('legacy reminder', 'DAILY', NULL, 540, 0, 1, 1); + "#, + ) + .expect("create legacy reminders schema"); + + init_connection(&conn).expect("upgrade legacy database"); + + assert!(column_exists(&conn, "reminders", "weekly_days")); + assert!(column_exists(&conn, "reminders", "sort_order")); + + let reminder: (String, String, Option, i64) = conn + .query_row( + "SELECT content, repeat_rule, weekly_days, sort_order FROM reminders WHERE id = 1", + [], + |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)), + ) + .expect("load migrated reminder"); + assert_eq!(reminder, ("legacy reminder".into(), "DAILY".into(), None, 0)); +} From 80ed2ba8d5850dd587e5c9d9b8d6e146872cb4c1 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:16:31 +0800 Subject: [PATCH 005/117] ci: add reproducible Windows release workflow --- .github/workflows/release.yml | 100 ++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..ecd5d12 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,100 @@ +name: Windows Release + +on: + workflow_dispatch: + push: + tags: + - "v*" + +permissions: + contents: write + +jobs: + windows: + name: Build Windows installers + runs-on: windows-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Enable pnpm + run: | + corepack enable + corepack prepare pnpm@9.15.9 --activate + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@stable + + - name: Cache Rust build output + uses: Swatinem/rust-cache@v2 + with: + workspaces: "./src-tauri -> target" + + - name: Install frontend dependencies + run: pnpm install --frozen-lockfile + + - name: Validate synchronized versions + shell: pwsh + run: | + $tauriVersion = (Get-Content src-tauri/tauri.conf.json | ConvertFrom-Json).version + $packageVersion = (Get-Content package.json | ConvertFrom-Json).version + $cargoMetadata = cargo metadata --manifest-path src-tauri/Cargo.toml --no-deps --format-version 1 | ConvertFrom-Json + $cargoVersion = ($cargoMetadata.packages | Where-Object { $_.name -eq 'timeprism' } | Select-Object -First 1).version + + if ($tauriVersion -ne $packageVersion -or $tauriVersion -ne $cargoVersion) { + throw "Version mismatch: tauri=$tauriVersion package=$packageVersion cargo=$cargoVersion" + } + + if ($env:GITHUB_REF_TYPE -eq 'tag') { + $expectedTag = "v$tauriVersion" + if ($env:GITHUB_REF_NAME -ne $expectedTag) { + throw "Tag/version mismatch: pushed=$env:GITHUB_REF_NAME expected=$expectedTag" + } + } + + "TIMEPRISM_VERSION=$tauriVersion" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append + + - name: Typecheck frontend + run: pnpm run typecheck + + - name: Test Rust backend + working-directory: src-tauri + run: cargo test + + - name: Build installers for manual validation + if: github.event_name == 'workflow_dispatch' + run: pnpm tauri build -- --bundles nsis,msi + + - name: Upload manual-build installers + if: github.event_name == 'workflow_dispatch' + uses: actions/upload-artifact@v4 + with: + name: TimePrism-${{ env.TIMEPRISM_VERSION }}-windows-installers + if-no-files-found: error + path: | + src-tauri/target/release/bundle/nsis/*-setup.exe + src-tauri/target/release/bundle/msi/*.msi + + - name: Build and create draft GitHub Release + if: github.event_name == 'push' && github.ref_type == 'tag' + uses: tauri-apps/tauri-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tagName: v__VERSION__ + releaseName: TimePrism v__VERSION__ + releaseBody: | + Windows-first, local-first TimePrism desktop release. + + Download either the NSIS setup executable or MSI installer from the release assets. + This project is currently unsigned, so Windows SmartScreen may warn about an unknown publisher. + releaseDraft: true + prerelease: false + generateReleaseNotes: true + args: --bundles nsis,msi From 212543e70e68c4e60e9f93ab8d2d385876287836 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:16:44 +0800 Subject: [PATCH 006/117] docs: document Windows release gate --- docs/RELEASE_CHECKLIST.md | 72 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/RELEASE_CHECKLIST.md diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000..80b3a4e --- /dev/null +++ b/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,72 @@ +# Release Checklist + +TimePrism publishes Windows installers from GitHub Actions. Releases are created as **drafts** first so the generated installers can be smoke-tested before they become public. + +## Release artifacts + +The Windows release workflow builds both Tauri-supported installer formats: + +- NSIS setup executable: `*-setup.exe` +- WiX/MSI installer: `*.msi` + +The current project is unsigned. Windows SmartScreen can therefore show an unknown-publisher warning until code signing is added. + +## Before tagging + +1. Confirm `main` CI is green. +2. Update the same semantic version in: + - `package.json` + - `src-tauri/Cargo.toml` + - `src-tauri/tauri.conf.json` +3. Run or verify: + + ```text + pnpm run typecheck + pnpm run build:check + cargo test --manifest-path src-tauri/Cargo.toml + ``` + +4. Smoke-test the desktop flows listed in `docs/SMOKE_TESTS.md`. +5. Commit the synchronized version bump to `main`. + +The release workflow rejects mismatched Node/Cargo/Tauri versions. Tag-triggered runs also reject a tag that does not equal `v`. + +## Dry-run installer build + +Run **Windows Release** manually from GitHub Actions before creating a tag. + +The `workflow_dispatch` path: + +1. validates version synchronization; +2. runs frontend typecheck and Rust tests; +3. builds both NSIS and MSI installers on `windows-latest`; +4. uploads the installers as workflow artifacts; +5. does **not** create a GitHub Release. + +Install and smoke-test at least one generated installer on Windows before publishing a version tag. + +## Publish a release draft + +Create and push a tag that exactly matches the app version, for example: + +```text +git tag v0.2.0 +git push origin v0.2.0 +``` + +The tag-triggered workflow validates the tag/version match and uses `tauri-apps/tauri-action` to create a draft GitHub Release with the NSIS and MSI assets attached. + +## Verify the draft + +Before publishing the draft Release: + +- install from the NSIS `-setup.exe` asset; +- install or inspect the `.msi` asset; +- launch TimePrism and confirm the main window renders normally; +- verify Home, Insights, Focus Guard, reminders, privacy settings, and desktop pet flows; +- verify full-app quit behavior; +- confirm local data survives app restart; +- confirm Release notes describe any known limitations; +- explicitly retain the unsigned/SmartScreen note until Windows code signing exists. + +Only after this verification should the GitHub Release be published. From 8d820af3b9a7ab4a4638d9a2687d96a9ec738871 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:17:35 +0800 Subject: [PATCH 007/117] docs: define real product media capture gate --- docs/media/README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/media/README.md diff --git a/docs/media/README.md b/docs/media/README.md new file mode 100644 index 0000000..0f6f7c7 --- /dev/null +++ b/docs/media/README.md @@ -0,0 +1,56 @@ +# Product Media Capture Guide + +This directory is reserved for **real TimePrism application captures** used by the repository README and Releases. Do not use mockups or generated UI images as evidence of implemented behavior. + +## Required captures + +Capture these from a current Windows build using synthetic or sanitized data: + +| File | Surface | What must be visible | +| --- | --- | --- | +| `timeprism-home.png` | Home | Today totals, rhythm/progress, reminders, navigation | +| `timeprism-insights.png` | Insights | Top apps plus at least one historical/heatmap view | +| `timeprism-focus-guard.png` | Focus Guard | Rule classification or idle-resolution workflow without private titles | +| `timeprism-pet.png` | Desktop pet | Pet together with its compact panel or prompt | +| `timeprism-demo.gif` | Short product flow | Home -> Insights -> Focus Guard -> desktop pet | + +## Privacy gate + +Foreground-window data can contain private information. Before committing any capture: + +- use synthetic application/process names where practical; +- remove real window titles, document names, URLs, account names, and notification text; +- do not expose the real SQLite database path or local username; +- verify Focus Guard diagnostics contain no raw private titles; +- inspect every GIF frame, not only its first frame. + +If sanitization would make a capture ambiguous, create a clean demo database instead of editing pixels after capture. + +## Presentation rules + +- Capture the actual application, not Figma/mockups/generated UI. +- Keep the main window at its normal aspect ratio; do not stretch screenshots. +- Prefer one coherent theme across all captures. +- Crop surrounding desktop chrome when it adds no information. +- Keep screenshots readable on a GitHub README at roughly 900-1200 px display width. +- Keep the GIF focused on interaction; avoid cursor wandering and long idle pauses. + +## README layout after capture + +Place the GIF directly below the repository badges, then use a compact two-column screenshot table: + +```markdown +

+ TimePrism product walkthrough +

+ +| Home | Insights | +| --- | --- | +| ![Home](docs/media/timeprism-home.png) | ![Insights](docs/media/timeprism-insights.png) | + +| Focus Guard | Desktop pet | +| --- | --- | +| ![Focus Guard](docs/media/timeprism-focus-guard.png) | ![Desktop pet](docs/media/timeprism-pet.png) | +``` + +Do not add these references to the root README until the corresponding files exist, because broken image placeholders are worse than a text-only README. From 76fcdc9b624fe76083b32779995324d7643b67c5 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:18:14 +0800 Subject: [PATCH 008/117] test: fix database regression helper lifetime --- src-tauri/src/db/tests.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src-tauri/src/db/tests.rs b/src-tauri/src/db/tests.rs index 30f1c18..1eb7bb2 100644 --- a/src-tauri/src/db/tests.rs +++ b/src-tauri/src/db/tests.rs @@ -36,10 +36,12 @@ fn column_exists(conn: &Connection, table: &str, column: &str) -> bool { let mut stmt = conn .prepare(&format!("PRAGMA table_info({table})")) .expect("prepare table info"); - stmt.query_map([], |row| row.get::<_, String>(1)) + let has_column = stmt + .query_map([], |row| row.get::<_, String>(1)) .expect("query table info") .map(|row| row.expect("read column name")) - .any(|name| name == column) + .any(|name| name == column); + has_column } #[test] From c8b981079bd211474aff072655ca25682a9b03d2 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:18:22 +0800 Subject: [PATCH 009/117] test: remove duplicate database regression file --- src-tauri/src/db/database_tests.rs | 152 ----------------------------- 1 file changed, 152 deletions(-) delete mode 100644 src-tauri/src/db/database_tests.rs diff --git a/src-tauri/src/db/database_tests.rs b/src-tauri/src/db/database_tests.rs deleted file mode 100644 index f7a8916..0000000 --- a/src-tauri/src/db/database_tests.rs +++ /dev/null @@ -1,152 +0,0 @@ -use rusqlite::Connection; - -use super::migrations::init_connection; - -fn table_exists(conn: &Connection, table: &str) -> bool { - conn.query_row( - "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?1)", - [table], - |row| row.get::<_, i64>(0), - ) - .expect("query table existence") - == 1 -} - -fn column_exists(conn: &Connection, table: &str, column: &str) -> bool { - let mut stmt = conn - .prepare(&format!("PRAGMA table_info({table})")) - .expect("prepare table info"); - stmt.query_map([], |row| row.get::<_, String>(1)) - .expect("query table info") - .any(|name| name.expect("parse column name") == column) -} - -#[test] -fn fresh_database_initialization_creates_schema_and_defaults() { - let conn = Connection::open_in_memory().expect("open in-memory db"); - - init_connection(&conn).expect("initialize fresh database"); - - for table in [ - "categories", - "task_sessions", - "app_usage_logs", - "app_rules", - "app_config", - "app_whitelist", - "reminders", - "daily_heatmap_snapshot", - ] { - assert!(table_exists(&conn, table), "missing table: {table}"); - } - - let learn_name: String = conn - .query_row("SELECT name FROM categories WHERE id = 1", [], |row| row.get(0)) - .expect("load LEARN root name"); - let rest_name: String = conn - .query_row("SELECT name FROM categories WHERE id = 2", [], |row| row.get(0)) - .expect("load REST root name"); - assert_eq!(learn_name, "学习"); - assert_eq!(rest_name, "休息"); - - let browser_mode: String = conn - .query_row( - "SELECT value FROM app_config WHERE key = 'browser_title_mode'", - [], - |row| row.get(0), - ) - .expect("load browser_title_mode"); - assert_eq!(browser_mode, "BLUR"); - - let code_rule: (String, String) = conn - .query_row( - "SELECT mapped_type, privacy_level FROM app_rules WHERE process_name = 'code.exe'", - [], - |row| Ok((row.get(0)?, row.get(1)?)), - ) - .expect("load code.exe rule"); - assert_eq!(code_rule, ("LEARN".into(), "NORMAL".into())); - - let foreign_keys: i64 = conn - .query_row("PRAGMA foreign_keys", [], |row| row.get(0)) - .expect("read foreign_keys pragma"); - assert_eq!(foreign_keys, 1); -} - -#[test] -fn database_initialization_is_idempotent_and_preserves_user_values() { - let conn = Connection::open_in_memory().expect("open in-memory db"); - init_connection(&conn).expect("initialize database first time"); - - conn.execute( - "UPDATE app_config SET value = '3600' WHERE key = 'heatmap_goal_seconds'", - [], - ) - .expect("customize heatmap goal"); - conn.execute( - "UPDATE app_rules SET mapped_type = 'REST' WHERE process_name = 'code.exe'", - [], - ) - .expect("customize code.exe rule"); - - init_connection(&conn).expect("initialize database second time"); - - let goal: String = conn - .query_row( - "SELECT value FROM app_config WHERE key = 'heatmap_goal_seconds'", - [], - |row| row.get(0), - ) - .expect("load customized goal"); - let code_mapping: String = conn - .query_row( - "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", - [], - |row| row.get(0), - ) - .expect("load customized code mapping"); - - assert_eq!(goal, "3600"); - assert_eq!(code_mapping, "REST"); -} - -#[test] -fn legacy_reminders_schema_is_upgraded_without_losing_rows() { - let conn = Connection::open_in_memory().expect("open in-memory db"); - conn.execute_batch( - r#" - CREATE TABLE reminders ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - content TEXT NOT NULL, - repeat_rule TEXT NOT NULL CHECK(repeat_rule IN ('NONE', 'DAILY')), - remind_at INTEGER NULL, - daily_time_minutes INTEGER NULL, - is_completed INTEGER NOT NULL DEFAULT 0, - completed_day_key TEXT NULL, - completed_at INTEGER NULL, - snooze_until INTEGER NULL, - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL - ); - INSERT INTO reminders ( - content, repeat_rule, remind_at, daily_time_minutes, - is_completed, created_at, updated_at - ) VALUES ('legacy reminder', 'DAILY', NULL, 540, 0, 1, 1); - "#, - ) - .expect("create legacy reminders schema"); - - init_connection(&conn).expect("upgrade legacy database"); - - assert!(column_exists(&conn, "reminders", "weekly_days")); - assert!(column_exists(&conn, "reminders", "sort_order")); - - let reminder: (String, String, Option, i64) = conn - .query_row( - "SELECT content, repeat_rule, weekly_days, sort_order FROM reminders WHERE id = 1", - [], - |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)), - ) - .expect("load migrated reminder"); - assert_eq!(reminder, ("legacy reminder".into(), "DAILY".into(), None, 0)); -} From 5c28cb855bbdcc11e4c6e3454da20ee0df9515d9 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:19:44 +0800 Subject: [PATCH 010/117] ci: modernize Windows checks and cache Rust builds --- .github/workflows/ci.yml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0bf3e9..b431e2f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,10 +14,10 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 - name: Setup Node - uses: actions/setup-node@v4 + uses: actions/setup-node@v7 with: node-version: 20 @@ -26,6 +26,15 @@ jobs: corepack enable corepack prepare pnpm@9.15.9 --activate + - name: Install Rust stable + uses: dtolnay/rust-toolchain@stable + + - name: Cache Rust build output + uses: Swatinem/rust-cache@v2 + with: + workspaces: "./src-tauri -> target" + cache-on-failure: true + - name: Install frontend dependencies run: pnpm install --frozen-lockfile @@ -35,9 +44,9 @@ jobs: - name: Build frontend to temporary output run: pnpm run build:check - - name: Check Rust backend + - name: Check all Rust targets working-directory: src-tauri - run: cargo check + run: cargo check --all-targets - name: Test Rust backend working-directory: src-tauri From db427f76219f3b69ab529d4ee5410d40efafae80 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:20:05 +0800 Subject: [PATCH 011/117] ci: use current GitHub action runtimes for releases --- .github/workflows/release.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ecd5d12..09388a7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -16,10 +16,10 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 - name: Setup Node - uses: actions/setup-node@v4 + uses: actions/setup-node@v7 with: node-version: 20 @@ -73,7 +73,7 @@ jobs: - name: Upload manual-build installers if: github.event_name == 'workflow_dispatch' - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v7 with: name: TimePrism-${{ env.TIMEPRISM_VERSION }}-windows-installers if-no-files-found: error From 3c79357982b201dcd823731724817ee808002c4d Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:21:49 +0800 Subject: [PATCH 012/117] docs: expose distribution and product evidence gates --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cc31bc4..89f7af5 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@

+ Windows Releases | What It Demonstrates | Architecture | Engineering Highlights | @@ -31,6 +32,8 @@ Rather than relying on manual start/stop timers, it samples the foreground appli The project is intentionally scoped as a Windows-first, local-first desktop application. It does not depend on cloud accounts, remote sync, or external services for its core workflow. +> **Release status:** the currently published `v0.1.0-preview` is an early portable build and predates the latest architecture/reliability work. The repository now includes a gated Windows release pipeline for NSIS `-setup.exe` and MSI installers; releases are created as drafts and smoke-tested before publication. + ## What It Demonstrates TimePrism is primarily a desktop full-stack engineering project. The repository demonstrates: @@ -144,7 +147,7 @@ SQLite persistence | Backend | Rust | | Storage | SQLite / rusqlite | | Platform integration | Windows + Tauri window APIs | -| Validation | GitHub Actions, `vue-tsc`, Vite build, `cargo check`, `cargo test` | +| Validation | GitHub Actions, `vue-tsc`, Vite build, `cargo check --all-targets`, `cargo test` | ## Project Structure @@ -178,12 +181,12 @@ timeprism/ ## Validation -Every push to `main` and `refactor/**`, plus pull requests, runs the repository CI workflow on Windows: +Every push to `main` and `refactor/**`, plus pull requests, runs the repository CI workflow on Windows. Rust build output is cached between runs and all test targets are compiled before the test phase: ```text pnpm run typecheck pnpm run build:check -cargo check +cargo check --all-targets cargo test ``` @@ -191,6 +194,15 @@ The current desktop flow has also been manually smoke-tested on Windows for star CI and smoke tests are used as project-level regression evidence; they are not a claim of production-grade hardening. +## Distribution + +`.github/workflows/release.yml` provides two release paths on `windows-latest`: + +- **Manual dry run:** builds NSIS and MSI installers and uploads them as workflow artifacts without creating a Release. +- **Version tag:** requires the tag to exactly match the synchronized Cargo/Node/Tauri app version, then creates a **draft** GitHub Release with both installer formats. + +The project is currently unsigned, so Windows SmartScreen may warn about an unknown publisher. Release publication is deliberately separated from installer generation so the generated build can be smoke-tested first. See [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md). + ## Privacy TimePrism is designed around local storage and explicit privacy boundaries. @@ -242,7 +254,7 @@ pnpm dev pnpm run typecheck pnpm run build:check cd src-tauri -cargo check +cargo check --all-targets cargo test ``` @@ -277,8 +289,12 @@ Engineering notes and design rationale live under `docs/`, including: - database and privacy notes - smoke-test catalog - testing strategy +- release checklist +- product-media capture guide - ADRs and refactor traceability +Real product screenshots/GIF are only added from sanitized current Windows builds; the capture/privacy requirements are documented in [`docs/media/README.md`](docs/media/README.md) so generated or mock UI is not presented as implementation evidence. + ## License TimePrism is licensed under the MIT License. From 38bc4a0b7d0a5fc78782476d9df9c459764fdac5 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:23:55 +0800 Subject: [PATCH 013/117] ci: pass installer bundle flags directly to Tauri CLI --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 09388a7..b1f3645 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -69,7 +69,7 @@ jobs: - name: Build installers for manual validation if: github.event_name == 'workflow_dispatch' - run: pnpm tauri build -- --bundles nsis,msi + run: pnpm tauri build --bundles nsis,msi - name: Upload manual-build installers if: github.event_name == 'workflow_dispatch' From 44ad6bc478c50bf277c0d03214731ec3db59448c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:24:25 +0800 Subject: [PATCH 014/117] refactor: expose legacy database file migration seam --- src-tauri/src/db/connection.rs | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src-tauri/src/db/connection.rs b/src-tauri/src/db/connection.rs index e93e680..4e9d23d 100644 --- a/src-tauri/src/db/connection.rs +++ b/src-tauri/src/db/connection.rs @@ -27,17 +27,15 @@ fn db_path(app: &AppHandle) -> Result { Ok(data_dir.join("timeprism.db")) } -fn try_migrate_legacy_db(app: &AppHandle, target_path: &Path) -> Result<(), String> { - if target_path.exists() { - return Ok(()); - } - - let legacy_path = legacy_db_path(app)?; - if !legacy_path.exists() { +pub(super) fn migrate_legacy_db_files( + legacy_path: &Path, + target_path: &Path, +) -> Result<(), String> { + if target_path.exists() || !legacy_path.exists() { return Ok(()); } - fs::copy(&legacy_path, target_path).map_err(|e| { + fs::copy(legacy_path, target_path).map_err(|e| { format!( "failed to migrate legacy sqlite db from {} to {}: {e}", legacy_path.display(), @@ -62,6 +60,11 @@ fn try_migrate_legacy_db(app: &AppHandle, target_path: &Path) -> Result<(), Stri Ok(()) } +fn try_migrate_legacy_db(app: &AppHandle, target_path: &Path) -> Result<(), String> { + let legacy_path = legacy_db_path(app)?; + migrate_legacy_db_files(&legacy_path, target_path) +} + pub fn open_connection(app: &AppHandle) -> Result { let preferred_path = db_path(app)?; let migration_error = try_migrate_legacy_db(app, &preferred_path).err(); @@ -78,15 +81,12 @@ pub fn open_connection(app: &AppHandle) -> Result { match Connection::open(&preferred_path) { Ok(conn) => Ok(conn), - Err(primary_err) => { - Connection::open(&legacy_path).map_err(|fallback_err| { - format!( - "failed to open preferred sqlite db {}: {primary_err}; fallback legacy db {} also failed: {fallback_err}", - preferred_path.display(), - legacy_path.display() - ) - }) - } + Err(primary_err) => Connection::open(&legacy_path).map_err(|fallback_err| { + format!( + "failed to open preferred sqlite db {}: {primary_err}; fallback legacy db {} also failed: {fallback_err}", + preferred_path.display(), + legacy_path.display() + ) + }), } } - From 8b4f1b434472f302105a386720ce27ad2a076d4f Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:24:56 +0800 Subject: [PATCH 015/117] refactor: extract connection-based database initializer --- src-tauri/src/db/migrations.rs | 68 ++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/src-tauri/src/db/migrations.rs b/src-tauri/src/db/migrations.rs index 7605a12..caac340 100644 --- a/src-tauri/src/db/migrations.rs +++ b/src-tauri/src/db/migrations.rs @@ -174,8 +174,7 @@ pub fn ensure_heatmap_snapshot_table(conn: &Connection) -> Result<(), String> { Ok(()) } -pub fn init_database(app: &AppHandle) -> Result<(), String> { - let conn = open_connection(app)?; +pub(super) fn initialize_connection(conn: &Connection) -> Result<(), String> { conn.pragma_update(None, "foreign_keys", "ON") .map_err(|e| format!("failed to enable foreign keys: {e}"))?; @@ -211,44 +210,44 @@ pub fn init_database(app: &AppHandle) -> Result<(), String> { privacy_level TEXT NOT NULL CHECK(privacy_level IN ('NORMAL', 'BLUR_TITLE', 'WHITELIST_ONLY')) ); - CREATE TABLE IF NOT EXISTS app_config ( - key TEXT PRIMARY KEY, - value TEXT NOT NULL - ); - - CREATE TABLE IF NOT EXISTS app_whitelist ( - process_name TEXT PRIMARY KEY - ); - - CREATE TABLE IF NOT EXISTS reminders ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - content TEXT NOT NULL, - repeat_rule TEXT NOT NULL CHECK(repeat_rule IN ('NONE', 'DAILY', 'WEEKLY')), - sort_order INTEGER NOT NULL DEFAULT 0, - remind_at INTEGER NULL, - daily_time_minutes INTEGER NULL, - weekly_days TEXT NULL, - is_completed INTEGER NOT NULL DEFAULT 0, - completed_day_key TEXT NULL, - completed_at INTEGER NULL, - snooze_until INTEGER NULL, - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL - ); + CREATE TABLE IF NOT EXISTS app_config ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL + ); + + CREATE TABLE IF NOT EXISTS app_whitelist ( + process_name TEXT PRIMARY KEY + ); + + CREATE TABLE IF NOT EXISTS reminders ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + content TEXT NOT NULL, + repeat_rule TEXT NOT NULL CHECK(repeat_rule IN ('NONE', 'DAILY', 'WEEKLY')), + sort_order INTEGER NOT NULL DEFAULT 0, + remind_at INTEGER NULL, + daily_time_minutes INTEGER NULL, + weekly_days TEXT NULL, + is_completed INTEGER NOT NULL DEFAULT 0, + completed_day_key TEXT NULL, + completed_at INTEGER NULL, + snooze_until INTEGER NULL, + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL + ); CREATE INDEX IF NOT EXISTS idx_task_sessions_start_time ON task_sessions(start_time); CREATE INDEX IF NOT EXISTS idx_app_usage_logs_start ON app_usage_logs(start_timestamp); CREATE INDEX IF NOT EXISTS idx_app_usage_logs_process ON app_usage_logs(process_name); - CREATE INDEX IF NOT EXISTS idx_reminders_due_none ON reminders(repeat_rule, remind_at, is_completed); - CREATE INDEX IF NOT EXISTS idx_reminders_due_daily ON reminders(repeat_rule, daily_time_minutes, completed_day_key); + CREATE INDEX IF NOT EXISTS idx_reminders_due_none ON reminders(repeat_rule, remind_at, is_completed); + CREATE INDEX IF NOT EXISTS idx_reminders_due_daily ON reminders(repeat_rule, daily_time_minutes, completed_day_key); "#, ) .map_err(|e| format!("failed to run schema init: {e}"))?; - ensure_app_rules_time_columns(&conn)?; - ensure_heatmap_snapshot_table(&conn)?; - ensure_reminders_weekly_columns(&conn)?; - ensure_reminders_sort_order(&conn)?; + ensure_app_rules_time_columns(conn)?; + ensure_heatmap_snapshot_table(conn)?; + ensure_reminders_weekly_columns(conn)?; + ensure_reminders_sort_order(conn)?; conn.execute_batch( r#" CREATE INDEX IF NOT EXISTS idx_reminders_due_none ON reminders(repeat_rule, remind_at, is_completed); @@ -325,3 +324,8 @@ pub fn init_database(app: &AppHandle) -> Result<(), String> { Ok(()) } + +pub fn init_database(app: &AppHandle) -> Result<(), String> { + let conn = open_connection(app)?; + initialize_connection(&conn) +} From 1f48690f28267ae608de54f406d34fec8f3fb50b Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:25:59 +0800 Subject: [PATCH 016/117] refactor: preserve legacy migration short-circuit semantics --- src-tauri/src/db/connection.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src-tauri/src/db/connection.rs b/src-tauri/src/db/connection.rs index 4e9d23d..f2f2019 100644 --- a/src-tauri/src/db/connection.rs +++ b/src-tauri/src/db/connection.rs @@ -61,6 +61,10 @@ pub(super) fn migrate_legacy_db_files( } fn try_migrate_legacy_db(app: &AppHandle, target_path: &Path) -> Result<(), String> { + if target_path.exists() { + return Ok(()); + } + let legacy_path = legacy_db_path(app)?; migrate_legacy_db_files(&legacy_path, target_path) } From 48de5c260eda3845534a35b5aeb5474e8efe5f6a Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:26:41 +0800 Subject: [PATCH 017/117] ci: cancel superseded pull-request runs --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b431e2f..816d49b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,6 +7,10 @@ on: - main - "refactor/**" +concurrency: + group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + jobs: checks: name: Typecheck, Vite build, Rust check/test From 1f14230570f33c152c18bf1f48c1e1a7861d118f Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:29:51 +0800 Subject: [PATCH 018/117] ci: move validation to Node 24 LTS --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 816d49b..707bc58 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,7 +23,7 @@ jobs: - name: Setup Node uses: actions/setup-node@v7 with: - node-version: 20 + node-version: 24 - name: Enable pnpm run: | From cee67e6236b1bc800e55920f3e008e7204c1e0b6 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:30:06 +0800 Subject: [PATCH 019/117] ci: use Node 24 LTS for Windows releases --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b1f3645..8689b53 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -21,7 +21,7 @@ jobs: - name: Setup Node uses: actions/setup-node@v7 with: - node-version: 20 + node-version: 24 - name: Enable pnpm run: | From 78986c5916420c572bd22bfef02ce77495109591 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:30:38 +0800 Subject: [PATCH 020/117] chore: declare Node 24 development baseline --- package.json | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/package.json b/package.json index aa045b9..2857ea8 100644 --- a/package.json +++ b/package.json @@ -3,14 +3,17 @@ "private": true, "version": "0.1.0", "packageManager": "pnpm@9.15.9", + "engines": { + "node": "24.x" + }, "type": "module", "scripts": { - "dev": "vite", - "typecheck": "vue-tsc --noEmit", - "build:check": "vue-tsc --noEmit && vite build --outDir dist-codex-check --emptyOutDir", - "build": "vue-tsc --noEmit && vite build", - "preview": "vite preview", - "tauri": "tauri" + "dev": "vite", + "typecheck": "vue-tsc --noEmit", + "build:check": "vue-tsc --noEmit && vite build --outDir dist-codex-check --emptyOutDir", + "build": "vue-tsc --noEmit && vite build", + "preview": "vite preview", + "tauri": "tauri" }, "dependencies": { "vue": "^3.5.13", From 0f0d591f995250ebf816511c81e7429adb2a8e65 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:31:05 +0800 Subject: [PATCH 021/117] docs: align prerequisites with Node 24 LTS --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 89f7af5..1045e11 100644 --- a/README.md +++ b/README.md @@ -222,7 +222,7 @@ Because active-window data can be sensitive, privacy is treated as part of the d Recommended local development environment: -- Node.js 20 +- Node.js 24 LTS - pnpm 9 - Rust toolchain - Tauri v2 system prerequisites From 89a72fe6a7dce48d0197a1fff44efdb3792905b1 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:31:25 +0800 Subject: [PATCH 022/117] docs: align testing strategy with current coverage --- docs/TESTING_STRATEGY.md | 118 +++++++++++++++++++-------------------- 1 file changed, 56 insertions(+), 62 deletions(-) diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md index 02c3337..e94874b 100644 --- a/docs/TESTING_STRATEGY.md +++ b/docs/TESTING_STRATEGY.md @@ -1,12 +1,12 @@ # Testing Strategy -The goal is not perfect coverage before refactor. The goal is enough feedback to make change safe. +The goal is not nominal coverage. The goal is enough deterministic feedback to make refactors and desktop-runtime changes safe. ## Test Categories ### 1. Static Checks -Use for every frontend or backend batch. +Run for every frontend or backend batch. Frontend: @@ -18,67 +18,70 @@ pnpm.cmd run build:check Backend: ```powershell -cargo check +cargo check --all-targets +cargo test ``` -### 2. Characterization Tests +CI runs these checks on Windows so the platform-specific backend and the Rust test target are compiled in the same environment used by the application. -Purpose: lock current behavior before moving risky code. +### 2. Characterization Tests -Use for: +Purpose: lock important existing behavior before moving or rewriting risky code. -- Business-day window calculation. -- Interval merging and overlap. -- Reminder recurrence. -- Privacy title transformation. -- App rule normalization. -- Heatmap level calculation. -- Usage-stack aggregation. +Covered areas include: -Important: characterization tests describe current behavior. They do not prove the behavior is ideal. +- business-day window calculation; +- interval merging and overlap; +- reminder recurrence and wall-clock semantics; +- privacy title transformation and diagnostic redaction; +- app-rule normalization; +- analytics aggregation; +- idle-interval replacement. -### 3. Contract Tests +Characterization tests describe current behavior. They are regression evidence, not proof that every existing behavior is ideal. -Purpose: ensure command payloads and return shapes remain compatible. +### 3. Contract Checks -Target: +Purpose: ensure frontend callers and Tauri command boundaries remain compatible. -- `src/api.ts` types. -- Tauri command names in `src-tauri/src/lib.rs`. -- Pet and pet-panel command usage. +Current safeguards: -Early practical approach: +- TypeScript typecheck for command payload/return usage; +- Tauri command inventory in `docs/API_CONTRACTS.md`; +- Rust compilation of all targets; +- manual smoke coverage for multi-window behavior that is not practical to prove with pure unit tests. -- TypeScript typecheck. -- Manual command/caller table in `docs/API_CONTRACTS.md`. -- Add automated command smoke tests later when a stable test harness exists. +Automated end-to-end Tauri command tests remain a later hardening option if a stable desktop test harness is introduced. ### 4. Repository / Database Tests -Purpose: protect schema, migration, and query semantics. +Purpose: protect schema, migration, seed, and file-lifecycle semantics. -Target: +`src-tauri/src/db/tests.rs` uses synthetic temporary SQLite files and covers: -- Fresh DB initialization. -- Legacy DB path fallback. -- Default app rules/config insertion. -- Reminder table migrations. -- Heatmap snapshot table creation. +- fresh database initialization; +- required schema/table creation; +- default app rules and config insertion; +- close/reopen persistence; +- repeated initialization without overwriting user-modified values; +- legacy `app_rules` / `reminders` schema migration without losing rows; +- one-time migration from the legacy database location to the preferred location. -Use temporary SQLite files. Do not test against the user's real app data. +Service-level tests also use in-memory SQLite connections for rules, privacy, reminders, usage, and analytics behavior. -### 5. Manual Smoke Tests +Never run automated tests against the user's real TimePrism database. -Use `docs/SMOKE_TESTS.md`. +### 5. Manual Smoke Tests -Manual smoke tests are required when changing: +Use `docs/SMOKE_TESTS.md` when changing: -- Window behavior. -- Pet behavior. -- Privacy settings. -- Capture loop. -- Reminder workflows. -- Navigation and page structure. +- window behavior; +- pet behavior; +- privacy settings; +- capture loop; +- reminder workflows; +- navigation and page structure; +- packaged Windows installers. ## Risk-Based Validation Matrix @@ -88,30 +91,21 @@ Manual smoke tests are required when changing: | Type-only frontend change | `vue-tsc` | | Frontend component change | `vue-tsc`, Vite temp build, relevant smoke test | | API wrapper change | `vue-tsc`, API contracts reviewed | -| Rust pure helper extraction | `cargo check`, unit/characterization test if available | -| Tauri command wrapper change | `cargo check`, frontend typecheck if caller touched | -| SQLite query change | `cargo check`, DB/repository test or manual DB smoke | -| Privacy/capture change | `cargo check`, privacy checklist, manual capture smoke | -| Pet/window change | Vite temp build, `cargo check`, pet smoke test | -| Full packaging change | full Tauri build | - -## Initial Tests To Add First - -Recommended first automated tests: - -1. Business day starts at 04:00 local time. -2. `merge_intervals_total` handles overlapping and adjacent intervals. -3. Reminder daily/weekly next due calculation. -4. Browser/private title mode transformation. -5. Rule process-name normalization. +| Rust pure helper extraction | `cargo check --all-targets`, relevant unit/characterization test | +| Tauri command wrapper change | `cargo check --all-targets`, frontend typecheck if caller touched | +| SQLite query/schema change | `cargo check --all-targets`, `cargo test`, DB lifecycle/repository test | +| Privacy/capture change | Rust checks/tests, privacy checklist, manual capture smoke | +| Pet/window change | Vite temp build, Rust checks/tests, pet smoke test | +| Full packaging change | release-workflow dry run, installer smoke test | ## Test Data Rules -- Use synthetic process names such as `code.exe`, `chrome.exe`, `game.exe`. -- Use synthetic titles that include private/incognito keywords. -- Use deterministic timestamps. +- Use synthetic process names such as `code.exe`, `chrome.exe`, and `game.exe`. +- Use synthetic titles that include private/incognito keywords where privacy behavior is under test. +- Use deterministic timestamps unless a test explicitly targets current-time behavior. +- Use in-memory or temporary-file SQLite databases. - Never rely on the user's real SQLite database. -- Never assert raw private titles should be stored. +- Never assert that raw private titles should be persisted. ## Temporary Build Output @@ -123,4 +117,4 @@ For source validation, use: pnpm.cmd run build:check ``` -Then delete `dist-codex-check`. +Then delete `dist-codex-check` if it is not needed. From 56657a54b47220804f124ad25ed9d953de863ea9 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:35:33 +0800 Subject: [PATCH 023/117] test: expose corrupted root category seed names --- src-tauri/src/db/tests.rs | 43 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/src-tauri/src/db/tests.rs b/src-tauri/src/db/tests.rs index 1eb7bb2..bde3cf0 100644 --- a/src-tauri/src/db/tests.rs +++ b/src-tauri/src/db/tests.rs @@ -88,6 +88,15 @@ fn fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens() { ) .expect("read default code rule"); assert_eq!(code_rule, "LEARN"); + + let learn_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 1", [], |row| row.get(0)) + .expect("read LEARN root name"); + let rest_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 2", [], |row| row.get(0)) + .expect("read REST root name"); + assert_eq!(learn_name, "学习"); + assert_eq!(rest_name, "休息"); } { @@ -153,6 +162,40 @@ fn database_initialization_is_idempotent_and_preserves_user_values() { remove_sqlite_files(&path); } +#[test] +fn database_initialization_repairs_only_known_mojibake_root_names() { + let path = temp_db_path("root-name-repair"); + remove_sqlite_files(&path); + let conn = Connection::open(&path).expect("open sqlite file"); + + super::migrations::initialize_connection(&conn).expect("first initialization"); + conn.execute( + "UPDATE categories SET name = '瀛︿範' WHERE id = 1 AND root_type = 'LEARN'", + [], + ) + .expect("seed known LEARN mojibake"); + conn.execute( + "UPDATE categories SET name = '我的休息' WHERE id = 2 AND root_type = 'REST'", + [], + ) + .expect("customize REST root name"); + + super::migrations::initialize_connection(&conn).expect("repair known root names"); + + let learn_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 1", [], |row| row.get(0)) + .expect("read repaired LEARN root name"); + let rest_name: String = conn + .query_row("SELECT name FROM categories WHERE id = 2", [], |row| row.get(0)) + .expect("read customized REST root name"); + + assert_eq!(learn_name, "学习"); + assert_eq!(rest_name, "我的休息"); + + drop(conn); + remove_sqlite_files(&path); +} + #[test] fn legacy_schema_is_upgraded_without_losing_existing_rows() { let path = temp_db_path("legacy-schema"); From 4a785ba1f88ecfa5d2e4c3aa5db9e785029b6978 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:40:43 +0800 Subject: [PATCH 024/117] fix: repair corrupted root category seed names --- src-tauri/src/db/migrations.rs | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src-tauri/src/db/migrations.rs b/src-tauri/src/db/migrations.rs index caac340..277b0b4 100644 --- a/src-tauri/src/db/migrations.rs +++ b/src-tauri/src/db/migrations.rs @@ -258,17 +258,29 @@ pub(super) fn initialize_connection(conn: &Connection) -> Result<(), String> { .map_err(|e| format!("failed to ensure reminder indexes: {e}"))?; conn.execute( - "INSERT OR IGNORE INTO categories (id, parent_id, name, color_hex, root_type) VALUES (1, NULL, '瀛︿範', '#22c55e', 'LEARN')", + "INSERT OR IGNORE INTO categories (id, parent_id, name, color_hex, root_type) VALUES (1, NULL, '学习', '#22c55e', 'LEARN')", [], ) .map_err(|e| format!("failed to seed LEARN root: {e}"))?; conn.execute( - "INSERT OR IGNORE INTO categories (id, parent_id, name, color_hex, root_type) VALUES (2, NULL, '浼戞伅', '#f97316', 'REST')", + "INSERT OR IGNORE INTO categories (id, parent_id, name, color_hex, root_type) VALUES (2, NULL, '休息', '#f97316', 'REST')", [], ) .map_err(|e| format!("failed to seed REST root: {e}"))?; + conn.execute( + "UPDATE categories SET name = '学习' WHERE id = 1 AND root_type = 'LEARN' AND name = '瀛︿範'", + [], + ) + .map_err(|e| format!("failed to repair LEARN root name: {e}"))?; + + conn.execute( + "UPDATE categories SET name = '休息' WHERE id = 2 AND root_type = 'REST' AND name = '浼戞伅'", + [], + ) + .map_err(|e| format!("failed to repair REST root name: {e}"))?; + let default_rules = [ ("code.exe", "LEARN", "NORMAL"), ("pycharm64.exe", "LEARN", "NORMAL"), From da7dcc4f620b68bbf1def4ab7b10dcb1ac36f71d Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:59:20 +0800 Subject: [PATCH 025/117] ci: validate Windows installers on packaging PRs --- .github/workflows/release.yml | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8689b53..80377d4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,6 +1,16 @@ name: Windows Release on: + pull_request: + branches: + - main + paths: + - ".github/workflows/release.yml" + - "src-tauri/tauri.conf.json" + - "src-tauri/Cargo.toml" + - "src-tauri/Cargo.lock" + - "package.json" + - "pnpm-lock.yaml" workflow_dispatch: push: tags: @@ -67,15 +77,15 @@ jobs: working-directory: src-tauri run: cargo test - - name: Build installers for manual validation - if: github.event_name == 'workflow_dispatch' + - name: Build installers for validation + if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' run: pnpm tauri build --bundles nsis,msi - - name: Upload manual-build installers - if: github.event_name == 'workflow_dispatch' + - name: Upload validation installers + if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' uses: actions/upload-artifact@v7 with: - name: TimePrism-${{ env.TIMEPRISM_VERSION }}-windows-installers + name: TimePrism-${{ env.TIMEPRISM_VERSION }}-windows-installers-${{ github.event_name }} if-no-files-found: error path: | src-tauri/target/release/bundle/nsis/*-setup.exe From e54b9fd04770e64589525926af2f96bc57dc6389 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:00:20 +0800 Subject: [PATCH 026/117] chore: retrigger packaging workflow discovery --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 80377d4..3649ae4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,6 @@ name: Windows Release +# Packaging PRs build real Windows installers without publishing a Release. on: pull_request: branches: From b84d1c31405c0f47d00bd19b1f6f01bfdd1b120c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:05:29 +0800 Subject: [PATCH 027/117] fix: pass Windows bundle targets as separate arguments --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3649ae4..4bb9d76 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -80,7 +80,7 @@ jobs: - name: Build installers for validation if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' - run: pnpm tauri build --bundles nsis,msi + run: pnpm tauri build --bundles nsis msi - name: Upload validation installers if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' @@ -108,4 +108,4 @@ jobs: releaseDraft: true prerelease: false generateReleaseNotes: true - args: --bundles nsis,msi + args: --bundles nsis msi From 9f06e8e45e81baa26fb3d9f1da1b71c66907daae Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:18:00 +0800 Subject: [PATCH 028/117] docs: document automated installer packaging gate --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1045e11..8f0324d 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Rather than relying on manual start/stop timers, it samples the foreground appli The project is intentionally scoped as a Windows-first, local-first desktop application. It does not depend on cloud accounts, remote sync, or external services for its core workflow. -> **Release status:** the currently published `v0.1.0-preview` is an early portable build and predates the latest architecture/reliability work. The repository now includes a gated Windows release pipeline for NSIS `-setup.exe` and MSI installers; releases are created as drafts and smoke-tested before publication. +> **Release status:** the currently published `v0.1.0-preview` is an early portable build and predates the latest architecture/reliability work. The repository now includes a gated Windows release pipeline for NSIS `-setup.exe` and MSI installers; packaging changes are validated on Windows before merge, while public releases remain draft-first and require an interactive installer smoke test before publication. ## What It Demonstrates @@ -190,18 +190,23 @@ cargo check --all-targets cargo test ``` +Release-related pull requests also run an independent Windows packaging gate that builds both NSIS and MSI installers and uploads them as workflow artifacts. This verifies that the current tree can reach real Tauri installer artifacts without publishing a Release. + The current desktop flow has also been manually smoke-tested on Windows for startup behavior, main views, reminder workflows, pet interactions, and full-app quit behavior. -CI and smoke tests are used as project-level regression evidence; they are not a claim of production-grade hardening. +CI, packaging validation, and smoke tests are used as project-level regression evidence; they are not a claim of production-grade hardening. ## Distribution -`.github/workflows/release.yml` provides two release paths on `windows-latest`: +`.github/workflows/release.yml` separates installer generation from publication on `windows-latest`: -- **Manual dry run:** builds NSIS and MSI installers and uploads them as workflow artifacts without creating a Release. +- **Packaging PR:** release-related pull requests validate synchronized versions, run frontend/Rust checks, build both NSIS and MSI installers, and upload the real installer artifacts without publishing anything. +- **Manual dry run:** `workflow_dispatch` performs the same installer build on demand after merge and uploads the installers as workflow artifacts without creating a Release. - **Version tag:** requires the tag to exactly match the synchronized Cargo/Node/Tauri app version, then creates a **draft** GitHub Release with both installer formats. -The project is currently unsigned, so Windows SmartScreen may warn about an unknown publisher. Release publication is deliberately separated from installer generation so the generated build can be smoke-tested first. See [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md). +Automated packaging proves that the installers can be generated; it does not replace the interactive Windows gate. At least one generated installer must still be downloaded, installed, launched, and smoke-tested before the draft Release is made public. + +The project is currently unsigned, so Windows SmartScreen may warn about an unknown publisher. See [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) for the full publication gate. ## Privacy From 5d8aa3432693504d301ecf1807537c6099577996 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:18:16 +0800 Subject: [PATCH 029/117] docs: separate packaging and installer smoke gates --- docs/RELEASE_CHECKLIST.md | 60 ++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md index 80b3a4e..4465f7c 100644 --- a/docs/RELEASE_CHECKLIST.md +++ b/docs/RELEASE_CHECKLIST.md @@ -11,14 +11,24 @@ The Windows release workflow builds both Tauri-supported installer formats: The current project is unsigned. Windows SmartScreen can therefore show an unknown-publisher warning until code signing is added. +## Two-layer installer gate + +Installer validation is deliberately split into two layers: + +1. **Automated packaging gate:** release-related pull requests build both NSIS and MSI installers on `windows-latest` and upload them as workflow artifacts. This proves the current tree can reach real installer artifacts before merge. +2. **Interactive Windows smoke:** a generated installer is downloaded to a real Windows desktop, installed, launched, exercised, and checked for restart/data/lifecycle behavior. CI cannot replace this interaction-level gate. + +A green packaging job is therefore necessary evidence, but it is not sufficient by itself to publish a Release. + ## Before tagging 1. Confirm `main` CI is green. -2. Update the same semantic version in: +2. Confirm the latest relevant packaging PR produced both installer formats successfully. +3. Update the same semantic version in: - `package.json` - `src-tauri/Cargo.toml` - `src-tauri/tauri.conf.json` -3. Run or verify: +4. Run or verify: ```text pnpm run typecheck @@ -26,24 +36,46 @@ The current project is unsigned. Windows SmartScreen can therefore show an unkno cargo test --manifest-path src-tauri/Cargo.toml ``` -4. Smoke-test the desktop flows listed in `docs/SMOKE_TESTS.md`. -5. Commit the synchronized version bump to `main`. +5. Smoke-test the desktop flows listed in `docs/SMOKE_TESTS.md`. +6. Commit the synchronized version bump to `main`. The release workflow rejects mismatched Node/Cargo/Tauri versions. Tag-triggered runs also reject a tag that does not equal `v`. -## Dry-run installer build +## Pull-request packaging validation -Run **Windows Release** manually from GitHub Actions before creating a tag. +When a pull request changes release/package inputs, **Windows Release** runs automatically. -The `workflow_dispatch` path: +The pull-request path: 1. validates version synchronization; 2. runs frontend typecheck and Rust tests; 3. builds both NSIS and MSI installers on `windows-latest`; -4. uploads the installers as workflow artifacts; +4. uploads both installers as one workflow artifact; 5. does **not** create a GitHub Release. -Install and smoke-test at least one generated installer on Windows before publishing a version tag. +The packaging job uses `if-no-files-found: error`, so a green upload step also verifies that both configured installer paths resolved to real files. + +## Manual dry-run installer build + +After the workflow is on `main`, **Windows Release** can also be started manually from GitHub Actions before creating a tag. + +The `workflow_dispatch` path performs the same version checks, tests, installer build, and artifact upload without creating a GitHub Release. Use this when you want a fresh installer candidate from the default branch even if no packaging-related pull request is open. + +Download the generated artifact and perform the interactive Windows smoke before publishing a version tag. + +## Interactive installer smoke + +At minimum, verify one generated installer end to end on Windows: + +- install from the NSIS `-setup.exe` or MSI artifact; +- launch TimePrism and confirm the main window renders normally; +- verify Home, Insights, Focus Guard, reminders, privacy settings, and desktop pet flows; +- verify main-window close/background behavior and full-app quit behavior; +- restart the app and confirm local data survives; +- uninstall the tested installer and confirm the uninstall flow completes normally; +- retain the unsigned/SmartScreen note until Windows code signing exists. + +If the installer or installed application fails this gate, fix the issue and produce a fresh artifact before tagging. ## Publish a release draft @@ -60,13 +92,9 @@ The tag-triggered workflow validates the tag/version match and uses `tauri-apps/ Before publishing the draft Release: -- install from the NSIS `-setup.exe` asset; -- install or inspect the `.msi` asset; -- launch TimePrism and confirm the main window renders normally; -- verify Home, Insights, Focus Guard, reminders, privacy settings, and desktop pet flows; -- verify full-app quit behavior; -- confirm local data survives app restart; +- confirm the expected NSIS and MSI assets are attached; +- install at least one draft asset if it differs from the previously smoke-tested artifact; - confirm Release notes describe any known limitations; - explicitly retain the unsigned/SmartScreen note until Windows code signing exists. -Only after this verification should the GitHub Release be published. +Only after these checks should the GitHub Release be published. From f6f5c1ab785541724ee6eb1f83450c87682a620a Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:38:26 +0800 Subject: [PATCH 030/117] docs: specify first-run tracking activation --- ...-08-timeprism-first-run-tracking-design.md | 440 ++++++++++++++++++ 1 file changed, 440 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-08-timeprism-first-run-tracking-design.md diff --git a/docs/superpowers/specs/2026-09-08-timeprism-first-run-tracking-design.md b/docs/superpowers/specs/2026-09-08-timeprism-first-run-tracking-design.md new file mode 100644 index 0000000..5a15b6f --- /dev/null +++ b/docs/superpowers/specs/2026-09-08-timeprism-first-run-tracking-design.md @@ -0,0 +1,440 @@ +# TimePrism First-Run Tracking Design + +Date: 2026-09-08 +Status: Proposed / user-approved direction, pending written-spec review +Scope: First-run startup safety, tracking consent/activation, persistent tracking state, and first-run explanation + +## 1. Problem statement + +A real Windows installer smoke test exposed three related problems: + +1. A fresh install can briefly render `failed to prepare summary query: no such table: app_usage_logs` even though the database becomes usable moments later. +2. Raw application usage can appear in Insights while the desktop pet remains at `0`, which is technically valid but unexplained: Insights includes observed application time while the pet only shows time classified as `LEARN` or `REST`. +3. A first-time user is dropped directly into the product with foreground capture already enabled, before the product explains what is collected, where it is stored, or how learning/rest classification works. + +The current behavior also stores the auto-capture toggle only in frontend memory, so an explicit pause is lost after restart. + +## 2. Goals + +This change must: + +- eliminate the fresh-install database/WebView startup race; +- ensure no foreground capture begins before the first-run explanation is acknowledged; +- match the common automatic-tracker model: one-time activation, then automatic tracking on future launches unless the user pauses it; +- persist the user's tracking pause/resume choice across restarts; +- keep the current approximately 5-second capture and UI refresh cadence; +- explain the difference between observed application activity and classified `LEARN` / `REST` time; +- preserve existing-user behavior during migration; +- fail closed if the database cannot be initialized rather than launching a partially initialized product shell. + +## 3. Non-goals + +This work will not: + +- change the 5-second foreground sampling interval; +- change the 5-second Home/pet refresh cadence; +- redesign the analytics model; +- add cloud accounts, telemetry, or remote consent storage; +- add a multi-step tutorial carousel; +- add screenshots, keyboard logging, or any new capture source; +- re-architect the existing `services / domain / db` backend structure; +- change application classification thresholds except where needed to explain them in UI copy. + +## 4. Product behavior + +### 4.1 Fresh installation + +A genuinely new TimePrism database starts with: + +- `onboarding_completed = false` +- `auto_capture_enabled = false` + +The first visible product surface is a one-time welcome / tracking-disclosure screen in the main window. + +Before the user accepts: + +- foreground capture is not started; +- no foreground application metadata is read by TimePrism's sampler; +- Home/Insights/Guard polling is not started; +- the desktop pet is not shown as an active tracking surface; +- normal product data reads that are unrelated to rendering the onboarding screen are not started. + +The primary action is: + +`开始使用 TimePrism` + +The user may close/quit the application instead of accepting. No separate persistent "browse without tracking" mode is introduced. + +### 4.2 First-run disclosure + +The welcome screen must state, in plain language: + +- TimePrism identifies the current foreground application and measures how long it remains active; +- application/window metadata can be stored locally for time analysis; +- browser titles are privacy-processed by default; +- private/incognito browser windows are not recorded by the current privacy rules; +- TimePrism does not capture screenshots or keystroke contents; +- core data is stored locally in SQLite and is not uploaded by the current product; +- Insights can show observed application activity, while the pet's `学 / 休` counters only include applications classified as `LEARN` or `REST`. + +The disclosure is informational and activation-oriented rather than a long legal flow. + +### 4.3 Activation + +When the user selects `开始使用 TimePrism`, the backend performs one atomic product-state transition: + +- `onboarding_completed = true` +- `auto_capture_enabled = true` + +Only after that transition succeeds may the frontend start the capture sampler and normal product polling. + +The first capture still behaves as a baseline-only sample; this is retained to avoid synthetic +5-second overcounting. + +### 4.4 Subsequent launches + +On later launches: + +- if `onboarding_completed = true` and `auto_capture_enabled = true`, TimePrism automatically resumes normal capture; +- if the user previously paused capture, `auto_capture_enabled = false` remains false after restart; +- onboarding is not shown again after successful first activation. + +This matches the intended automatic-tracker model: activate once, then run automatically unless explicitly paused. + +### 4.5 Pause / resume semantics + +The existing auto-capture control becomes persistent. + +Changing the toggle updates the SQLite-backed tracking preference, not only a Vue `ref`. + +Rules: + +- pause: persist `auto_capture_enabled = false`, then stop the sampler; +- resume: persist `auto_capture_enabled = true`, then start the sampler; +- a failed persistence write must not silently change the runtime state; +- enabling capture before onboarding is complete is rejected by the backend invariant rather than trusted to the UI. + +## 5. Startup architecture + +### 5.1 Root cause to remove + +The current configuration allows WebViews to be created before `.setup()` completes, while database initialization currently runs inside `.setup()`. Main and pet frontends can therefore invoke database-backed commands before `app_usage_logs` and the rest of the schema exist. + +### 5.2 Required startup ordering + +The startup order becomes: + +```text +Tauri process starts + -> resolve/open database path + -> run schema initialization and migrations + -> load tracking state + -> create desktop WebViews + -> render main window + -> if onboarding incomplete: show onboarding only + -> if onboarding complete: start normal product runtime according to persisted auto_capture_enabled +``` + +The key invariant is: + +> No database-backed product WebView may issue product queries before database initialization has completed successfully. + +### 5.3 Window creation + +Configured windows should no longer auto-create before database initialization. + +The Tauri window configs remain the source of truth for window shape/URL/behavior, but startup code creates the required WebViews only after successful database initialization. + +Main-window reveal still occurs after Vue mount so the prior blank-startup regression remains fixed. + +Desktop-pet behavior: + +- on first run before activation: keep the pet hidden; +- after first activation: show/settle the pet using the existing window service; +- on subsequent launches: pet visibility follows the normal application behavior, independent of whether tracking is paused; +- when tracking is paused, the pet displays a paused/not-recording state rather than implying active capture. + +### 5.4 Database initialization failure + +Database initialization is no longer treated as a warning that allows the app to continue. + +If initialization/migration fails: + +- do not start normal product WebViews and polling; +- do not start foreground capture; +- fail startup with an explicit error path/log rather than showing a partially functional UI that later emits table-missing errors. + +A richer recovery UI is out of scope for this change. + +## 6. Persistent state model + +Use the existing `app_config` table rather than introducing another settings database. + +Required keys: + +- `onboarding_completed` +- `auto_capture_enabled` + +A backend tracking-state model should expose both values together, e.g. conceptually: + +```text +TrackingState { + onboarding_completed: bool, + auto_capture_enabled: bool +} +``` + +Backend operations should be explicit rather than exposing arbitrary `app_config` writes to the frontend: + +- read current tracking state; +- complete onboarding and enable tracking atomically; +- set auto-capture enabled/disabled after onboarding. + +This preserves invariants in Rust rather than relying on frontend sequencing. + +## 7. Migration semantics + +Existing installations must not unexpectedly stop tracking after upgrading. + +Initialization must distinguish a genuinely fresh database from a pre-existing TimePrism database before inserting the new tracking-state keys. + +### Fresh database + +```text +onboarding_completed = false +auto_capture_enabled = false +``` + +### Existing database without the new keys + +```text +onboarding_completed = true +auto_capture_enabled = true +``` + +Rationale: existing users have already been using automatic capture; forcing them through a new consent screen or silently disabling capture would be a backward-incompatible behavior change. + +### Existing database with the new keys + +Never overwrite user choices. + +In particular: + +- a persisted pause remains paused; +- completed onboarding remains completed. + +An empty/corrupt file with no recognizable TimePrism schema can be treated as a fresh database; database corruption recovery beyond that is out of scope. + +## 8. Frontend runtime gate + +The current main-window lifecycle starts Home refresh, polling, settings warmup, and the auto-capture sampler on mount. This must be split into two phases. + +### Phase A: shell initialization + +Allowed before onboarding completion: + +- locale initialization; +- theme initialization; +- load tracking state; +- render/reveal the main window; +- render onboarding when needed. + +### Phase B: product runtime + +Started only after onboarding is complete: + +- Home core data refresh; +- Home analytics refresh scheduling; +- settings warmup; +- main refresh polling; +- auto-capture sampler only if `auto_capture_enabled = true`; +- Insights/Guard listeners and normal product orchestration. + +The transition from onboarding to normal product runtime occurs without requiring an app restart. + +Runtime startup must be idempotent so the same polling/sampler is not started twice. + +## 9. Tracking status and pet semantics + +The 5-second cadence remains unchanged. + +Current timing model remains: + +```text +capture sampler: about every 5 seconds +main data polling: about every 5 seconds +pet summary refresh: about every 5 seconds +``` + +Because the first foreground sample is baseline-only, a newly classified LEARN/REST interval can take several seconds before it becomes visible. This is acceptable; the UI should communicate the tracking state rather than simulate second-by-second updates. + +The pet should distinguish at least: + +- active tracking: e.g. `自动记录中`; +- tracking paused: e.g. `记录已暂停`; +- pre-onboarding: pet hidden, so no ambiguous state is needed. + +The pet continues to show only `LEARN` and `REST` totals. It does not become a raw observed-app timer. + +## 10. Explain observed activity vs. classified time + +The product should add concise first-run copy explaining: + +- Insights may immediately show observed applications because it reports captured application activity; +- `学 / 休` totals remain zero until those applications map to `LEARN` or `REST`; +- unknown applications can later be classified in Focus Guard. + +This explanation belongs in onboarding and may be repeated as lightweight helper text where the classification workflow is introduced. It does not require changing the analytics computation. + +Obvious system/self processes that should never require meaningful user classification can be evaluated separately as a small cleanup, but changing default rule coverage is not required to complete this first-run design. + +## 11. Error handling + +### Startup/database + +- initialization failure prevents normal runtime startup; +- no schema-missing message should be rendered as a persistent red footer during a normal fresh launch. + +### Frontend data errors + +The global error surface should no longer preserve a stale transient startup error forever after later refreshes succeed. + +Minimum behavior: + +- successful refresh after a transient data-read error clears the relevant global error; +- onboarding/runtime errors remain visible when they block the requested transition. + +This is secondary to fixing the database race at the source; frontend error clearing is not a substitute for startup ordering. + +### Tracking state writes + +- failed activation leaves onboarding incomplete and capture off; +- failed pause/resume keeps the prior persisted/runtime state and reports an error; +- no optimistic state that contradicts SQLite should survive a failed write. + +## 12. Backend boundaries + +Keep the current architecture: + +```text +Tauri command wrappers + -> service layer + -> db / app_config +``` + +Add a focused tracking-preferences boundary rather than placing SQL in command wrappers. + +Expected responsibility split: + +- `db/migrations`: fresh-vs-existing defaults and schema/config migration; +- tracking service: read state, complete onboarding, persist pause/resume invariant; +- `lib.rs`: thin commands plus startup/window ordering; +- existing foreground service: capture mechanics remain unchanged; +- existing window service: reuse current reveal/show/settle semantics. + +Do not perform another broad backend directory refactor. + +## 13. Frontend boundaries + +Prefer a focused composable for persisted tracking/onboarding state rather than adding more startup booleans directly to `App.vue`. + +Conceptual responsibilities: + +- load backend tracking state; +- expose onboarding-complete and auto-capture state; +- perform activation; +- perform pause/resume with persistence; +- trigger product-runtime start only after state permits it. + +The existing auto-capture sampler remains responsible only for periodic sampling; it should not own persistence or onboarding policy. + +## 14. Tests + +Implementation must be test-driven where practical. + +### Rust/database tests + +Add tests covering: + +1. fresh DB receives `onboarding_completed=false` and `auto_capture_enabled=false`; +2. recognizable legacy/existing DB with missing keys migrates to `true / true`; +3. rerunning initialization never overwrites persisted `auto_capture_enabled=false`; +4. completing onboarding atomically produces `true / true`; +5. pause persists `false` while keeping onboarding complete; +6. resume persists `true` after onboarding; +7. backend rejects enabling capture when onboarding is incomplete; +8. existing database lifecycle/migration tests continue to pass. + +### Frontend tests / pure-logic characterization + +Where existing test infrastructure permits, cover runtime-state decisions as pure logic rather than requiring full WebView automation: + +- incomplete onboarding -> no product runtime/capture start; +- completed + enabled -> product runtime + capture start; +- completed + paused -> product runtime starts but sampler stays stopped; +- activation transitions to normal runtime once; +- pause/resume does not create duplicate sampling intervals. + +If the repository still lacks a Vue unit-test runner, keep the state-transition logic small/pure and cover the Rust invariant plus Windows smoke path; do not add a large new test framework solely for this change. + +### CI + +Final gates remain: + +```text +pnpm run typecheck +pnpm run build:check +cargo check --all-targets +cargo test +``` + +Windows installer packaging must still produce both NSIS and MSI artifacts. + +## 15. Manual Windows acceptance test + +Use a clean/sandboxed TimePrism data directory. + +A fresh install passes only if: + +1. no `no such table: app_usage_logs` error appears; +2. no foreground activity is captured before first-run activation; +3. onboarding clearly explains foreground-app metadata, local storage, browser privacy, no screenshots/keystrokes, and classified `学 / 休` semantics; +4. clicking `开始使用 TimePrism` starts tracking without restart; +5. Insights begins to show observed application activity after sampling; +6. pet totals remain classification-based and update after LEARN/REST activity with the existing several-second cadence; +7. pausing capture stops new samples; +8. closing/reopening TimePrism preserves the pause; +9. resuming persists across a later restart; +10. onboarding does not reappear after successful activation; +11. pet shows an appropriate paused state when tracking is paused; +12. existing close-to-background / full-quit behavior still works. + +An upgrade test with an existing pre-change database passes only if tracking remains enabled and onboarding is treated as already complete. + +## 16. Rollout / release impact + +The current `0.1.0` installer candidate exposed this first-run issue, so it should not be published as the polished recruiting/demo release. + +After implementation: + +- rerun Windows CI; +- rerun NSIS + MSI packaging smoke; +- perform the fresh-install and upgrade manual tests above; +- capture final sanitized Home / Insights / Focus Guard / pet screenshots only from the corrected build; +- then move the PR out of Draft, merge, and create the intended public release. + +## 17. Acceptance summary + +This design is complete when the product has the following observable behavior: + +```text +Fresh install + -> DB fully initialized before product WebViews query it + -> one-time tracking disclosure + -> no capture before activation + -> Start TimePrism + -> tracking ON and persisted + -> future launches auto-track + -> user Pause persists across restart +``` + +And the existing 5-second capture/refresh model remains intact. From 5a878a079c3a7237e034cd699539c6988aa7e996 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:49:56 +0800 Subject: [PATCH 031/117] docs: plan first-run tracking implementation --- ...2026-09-08-timeprism-first-run-tracking.md | 1196 +++++++++++++++++ 1 file changed, 1196 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md diff --git a/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md b/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md new file mode 100644 index 0000000..d8e5638 --- /dev/null +++ b/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md @@ -0,0 +1,1196 @@ +# TimePrism First-Run Tracking Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make a fresh TimePrism install initialize SQLite before any product WebView can query it, show a one-time tracking disclosure before foreground capture starts, and persist tracking pause/resume state across restarts. + +**Architecture:** Keep the existing `commands -> services -> domain/db` structure. Add a small SQLite-backed tracking-state service, manually create configured Tauri windows only after database initialization, and gate the existing Vue runtime behind a persisted `TrackingState`. The foreground sampler keeps its current approximately 5-second cadence; policy/persistence stays outside the sampler. + +**Tech Stack:** Tauri 2, Rust, rusqlite/SQLite, Vue 3, TypeScript, Vite, GitHub Actions on Windows. + +**Spec:** `docs/superpowers/specs/2026-09-08-timeprism-first-run-tracking-design.md` + +## Global Constraints + +- Fresh databases start with `onboarding_completed=false` and `auto_capture_enabled=false`. +- Existing pre-change TimePrism databases migrate to `onboarding_completed=true` and `auto_capture_enabled=true` unless either key already exists. +- No foreground capture may occur before onboarding activation succeeds. +- A user-initiated pause persists across restart; restart must never silently turn capture back on. +- Keep the foreground sampling interval at approximately 5 seconds. +- Keep Home and pet refresh cadence at approximately 5 seconds. +- The first foreground sample remains baseline-only to avoid synthetic overcounting. +- No new frontend test framework is added solely for this feature. +- Database initialization failure must prevent normal product runtime startup. +- Do not perform another broad backend or frontend directory refactor. +- Product copy must state that TimePrism reads foreground application/window metadata, stores core data locally, privacy-processes browser titles, does not capture screenshots/keystroke contents, and that Insights activity differs from classified `LEARN` / `REST` totals. + +--- + +## File Structure + +### Create + +- `src-tauri/src/domain/tracking.rs` — serialized backend `TrackingState` contract. +- `src-tauri/src/services/tracking.rs` — SQLite-backed tracking-state invariants and transitions. +- `src/api/commands/tracking.ts` — typed frontend wrappers for tracking-state Tauri commands. +- `src/api/commands/window.ts` — typed main-window wrapper for showing the pet after first activation. +- `src/composables/useTrackingState.ts` — frontend persistence-facing tracking state only; no timer ownership. +- `src/components/OnboardingView.vue` — one-screen first-run disclosure and activation UI. + +### Modify + +- `src-tauri/src/db/migrations.rs` — classify fresh vs recognizable existing DB before schema creation; seed tracking keys with migration-safe defaults. +- `src-tauri/src/db/tests.rs` — file-backed regression coverage for fresh/existing tracking defaults and persisted pause preservation. +- `src-tauri/src/domain/mod.rs` — expose tracking domain model. +- `src-tauri/src/services/mod.rs` — expose tracking service. +- `src-tauri/src/lib.rs` — thin tracking commands; fail-closed DB startup; create windows only after DB init; gate startup pet creation/shortcut by onboarding state. +- `src-tauri/src/services/window.rs` — create main/pet windows from `tauri.conf.json` config after DB readiness instead of duplicating startup config. +- `src-tauri/tauri.conf.json` — set configured WebViews to `create: false` so Tauri cannot auto-create them before `.setup()` completes. +- `src/api/types.ts` and `src/api.ts` — expose `TrackingState` to TypeScript callers. +- `src/api/commands/index.ts` — export tracking/window command modules. +- `src/composables/useAutoCaptureSampler.ts` — timer only; remove policy ownership from the sampler. +- `src/composables/useGuardData.ts` — consume persisted auto-capture state rather than creating `ref(true)`. +- `src/composables/useMainWindowLifecycle.ts` — split shell initialization from idempotent product-runtime start. +- `src/composables/useErrorMessage.ts` — add explicit clearing for a recovered transient read error. +- `src/composables/useHomeData.ts` — clear its own transient global read error after a successful core refresh. +- `src/App.vue` — composition-root wiring for tracking state, onboarding, activation, pause/resume, runtime start, and pet reveal. +- `src/pet.ts` — render active vs paused tracking state while retaining 5-second summary polling. +- `src/styles/app.css` — onboarding layout/styles using existing visual tokens. +- `docs/SMOKE_TESTS.md` and `docs/RELEASE_CHECKLIST.md` — record fresh-install and upgrade acceptance gates. + +--- + +### Task 1: Add migration-safe tracking defaults + +**Files:** +- Modify: `src-tauri/src/db/migrations.rs` around `initialize_connection` +- Modify/Test: `src-tauri/src/db/tests.rs` around the fresh/idempotent/legacy database tests + +**Interfaces:** +- Consumes: existing `app_config(key TEXT PRIMARY KEY, value TEXT NOT NULL)` table. +- Produces: guaranteed `onboarding_completed` and `auto_capture_enabled` config keys after every successful `initialize_connection(&Connection)` call. + +- [ ] **Step 1: Add failing database tests for fresh tracking defaults** + +Extend `fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens` with exact assertions: + +```rust +let onboarding: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'onboarding_completed'", + [], + |row| row.get(0), + ) + .expect("read onboarding default"); +let auto_capture: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", + [], + |row| row.get(0), + ) + .expect("read auto capture default"); +assert_eq!(onboarding, "false"); +assert_eq!(auto_capture, "false"); +``` + +- [ ] **Step 2: Add failing migration tests for an existing recognizable database** + +In `legacy_schema_is_upgraded_without_losing_existing_rows`, after creating the legacy `app_rules` / `reminders` schema and calling `initialize_connection`, assert: + +```rust +let onboarding: String = conn.query_row( + "SELECT value FROM app_config WHERE key = 'onboarding_completed'", + [], + |row| row.get(0), +).expect("read migrated onboarding state"); +let auto_capture: String = conn.query_row( + "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", + [], + |row| row.get(0), +).expect("read migrated capture state"); +assert_eq!(onboarding, "true"); +assert_eq!(auto_capture, "true"); +``` + +- [ ] **Step 3: Add a failing regression test proving initialization preserves a user pause** + +Add: + +```rust +#[test] +fn database_initialization_preserves_persisted_tracking_pause() { + let path = temp_db_path("tracking-pause"); + remove_sqlite_files(&path); + let conn = Connection::open(&path).expect("open sqlite file"); + + super::migrations::initialize_connection(&conn).expect("initialize fresh database"); + conn.execute( + "UPDATE app_config SET value = 'true' WHERE key = 'onboarding_completed'", + [], + ).expect("mark onboarding complete"); + conn.execute( + "UPDATE app_config SET value = 'false' WHERE key = 'auto_capture_enabled'", + [], + ).expect("persist capture pause"); + + super::migrations::initialize_connection(&conn).expect("reinitialize database"); + + let state: (String, String) = conn.query_row( + "SELECT + (SELECT value FROM app_config WHERE key = 'onboarding_completed'), + (SELECT value FROM app_config WHERE key = 'auto_capture_enabled')", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + ).expect("read persisted tracking state"); + assert_eq!(state, ("true".to_string(), "false".to_string())); + + drop(conn); + remove_sqlite_files(&path); +} +``` + +- [ ] **Step 4: Run the focused tests and confirm RED** + +Run: + +```bash +cd src-tauri +cargo test db::tests::fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens +cargo test db::tests::legacy_schema_is_upgraded_without_losing_existing_rows +cargo test db::tests::database_initialization_preserves_persisted_tracking_pause +``` + +Expected: the first two fail because the new keys do not exist; the third cannot observe the requested keys yet. + +- [ ] **Step 5: Detect whether the DB was recognizable before schema creation** + +Add a helper before `initialize_connection`: + +```rust +fn has_recognizable_timeprism_schema(conn: &Connection) -> Result { + let count: i64 = conn + .query_row( + "SELECT COUNT(*) + FROM sqlite_master + WHERE type = 'table' + AND name IN ('categories', 'task_sessions', 'app_usage_logs', 'app_rules', 'app_config', 'reminders')", + [], + |row| row.get(0), + ) + .map_err(|e| format!("failed to inspect existing TimePrism schema: {e}"))?; + Ok(count > 0) +} +``` + +At the start of `initialize_connection`, before the existing `CREATE TABLE IF NOT EXISTS ...` batch: + +```rust +let was_existing_timeprism_db = has_recognizable_timeprism_schema(conn)?; +``` + +- [ ] **Step 6: Seed tracking keys with fresh-vs-upgrade defaults using `INSERT OR IGNORE`** + +After the existing default config loop, add: + +```rust +let tracking_defaults = if was_existing_timeprism_db { + [("onboarding_completed", "true"), ("auto_capture_enabled", "true")] +} else { + [("onboarding_completed", "false"), ("auto_capture_enabled", "false")] +}; + +for (key, value) in tracking_defaults { + conn.execute( + "INSERT OR IGNORE INTO app_config (key, value) VALUES (?1, ?2)", + params![key, value], + ) + .map_err(|e| format!("failed to seed tracking config {key}: {e}"))?; +} +``` + +Do not update existing rows; `INSERT OR IGNORE` is the preservation mechanism. + +- [ ] **Step 7: Run focused tests and the full Rust suite** + +Run: + +```bash +cd src-tauri +cargo test db::tests::fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens +cargo test db::tests::legacy_schema_is_upgraded_without_losing_existing_rows +cargo test db::tests::database_initialization_preserves_persisted_tracking_pause +cargo test +``` + +Expected: all pass; existing DB lifecycle and mojibake tests stay green. + +- [ ] **Step 8: Commit Task 1** + +```bash +git add src-tauri/src/db/migrations.rs src-tauri/src/db/tests.rs +git commit -m "feat(db): persist first-run tracking defaults" +``` + +--- + +### Task 2: Add the backend tracking-state invariant + +**Files:** +- Create: `src-tauri/src/domain/tracking.rs` +- Create: `src-tauri/src/services/tracking.rs` +- Modify: `src-tauri/src/domain/mod.rs` +- Modify: `src-tauri/src/services/mod.rs` +- Modify: `src-tauri/src/lib.rs` command imports/handlers + +**Interfaces:** +- Produces: `TrackingState { onboarding_completed: bool, auto_capture_enabled: bool }`. +- Produces: `get_tracking_state_entry(&Connection) -> Result`. +- Produces: `complete_onboarding_entry(&Connection) -> Result`. +- Produces: `set_auto_capture_enabled_entry(&Connection, bool) -> Result`. +- Produces Tauri commands: `get_tracking_state`, `complete_tracking_onboarding`, `set_auto_capture_enabled`. + +- [ ] **Step 1: Create the domain contract** + +`src-tauri/src/domain/tracking.rs`: + +```rust +use serde::Serialize; + +#[derive(Clone, Debug, PartialEq, Eq, Serialize)] +pub struct TrackingState { + pub onboarding_completed: bool, + pub auto_capture_enabled: bool, +} +``` + +Expose it from `domain/mod.rs`: + +```rust +pub mod tracking; +``` + +- [ ] **Step 2: Write failing service tests before the service implementation** + +Create `src-tauri/src/services/tracking.rs` with a `#[cfg(test)]` module first. Use a minimal in-memory table: + +```rust +#[cfg(test)] +mod tests { + use rusqlite::{params, Connection}; + + use super::{ + complete_onboarding_entry, get_tracking_state_entry, set_auto_capture_enabled_entry, + }; + + fn tracking_conn(onboarding: bool, enabled: bool) -> Connection { + let conn = Connection::open_in_memory().expect("open tracking test db"); + conn.execute_batch( + "CREATE TABLE app_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);", + ).expect("create app_config"); + for (key, value) in [ + ("onboarding_completed", onboarding.to_string()), + ("auto_capture_enabled", enabled.to_string()), + ] { + conn.execute( + "INSERT INTO app_config (key, value) VALUES (?1, ?2)", + params![key, value], + ).expect("seed tracking state"); + } + conn + } + + #[test] + fn completing_onboarding_atomically_enables_capture() { + let conn = tracking_conn(false, false); + let state = complete_onboarding_entry(&conn).expect("complete onboarding"); + assert!(state.onboarding_completed); + assert!(state.auto_capture_enabled); + assert_eq!(get_tracking_state_entry(&conn).unwrap(), state); + } + + #[test] + fn pause_and_resume_persist_after_onboarding() { + let conn = tracking_conn(true, true); + assert!(!set_auto_capture_enabled_entry(&conn, false).unwrap().auto_capture_enabled); + assert!(set_auto_capture_enabled_entry(&conn, true).unwrap().auto_capture_enabled); + } + + #[test] + fn enabling_capture_before_onboarding_is_rejected() { + let conn = tracking_conn(false, false); + let err = set_auto_capture_enabled_entry(&conn, true).unwrap_err(); + assert!(err.contains("onboarding")); + assert!(!get_tracking_state_entry(&conn).unwrap().auto_capture_enabled); + } +} +``` + +- [ ] **Step 3: Run the tracking tests and confirm RED** + +Run: + +```bash +cd src-tauri +cargo test services::tracking::tests +``` + +Expected: compile/test failure because the service functions do not exist yet. + +- [ ] **Step 4: Implement strict config reads and the three state transitions** + +Use exact boolean parsing rather than a default that could hide a missing/corrupt key: + +```rust +use rusqlite::{params, Connection}; +use crate::domain::tracking::TrackingState; + +fn read_bool_config(conn: &Connection, key: &str) -> Result { + let value: String = conn + .query_row("SELECT value FROM app_config WHERE key = ?1", [key], |row| row.get(0)) + .map_err(|e| format!("failed to read tracking config {key}: {e}"))?; + match value.trim().to_lowercase().as_str() { + "true" => Ok(true), + "false" => Ok(false), + other => Err(format!("invalid boolean tracking config {key}: {other}")), + } +} + +pub(crate) fn get_tracking_state_entry(conn: &Connection) -> Result { + Ok(TrackingState { + onboarding_completed: read_bool_config(conn, "onboarding_completed")?, + auto_capture_enabled: read_bool_config(conn, "auto_capture_enabled")?, + }) +} +``` + +`complete_onboarding_entry` must use one SQLite transaction and update both rows before commit: + +```rust +pub(crate) fn complete_onboarding_entry(conn: &Connection) -> Result { + let tx = conn.unchecked_transaction() + .map_err(|e| format!("failed to begin onboarding transaction: {e}"))?; + tx.execute( + "UPDATE app_config SET value = 'true' WHERE key IN ('onboarding_completed', 'auto_capture_enabled')", + [], + ).map_err(|e| format!("failed to complete onboarding: {e}"))?; + tx.commit().map_err(|e| format!("failed to commit onboarding: {e}"))?; + get_tracking_state_entry(conn) +} +``` + +`set_auto_capture_enabled_entry` must read current state first, reject `true` before onboarding, write one key, then re-read and return persisted state. + +- [ ] **Step 5: Expose the service module and run tests GREEN** + +Add to `services/mod.rs`: + +```rust +pub mod tracking; +``` + +Run: + +```bash +cd src-tauri +cargo test services::tracking::tests +cargo test +``` + +Expected: all pass. + +- [ ] **Step 6: Add thin Tauri command wrappers** + +In `lib.rs`, import the model/service and add: + +```rust +#[tauri::command(async)] +fn get_tracking_state(app: AppHandle) -> Result { + let conn = open_connection(&app)?; + get_tracking_state_entry(&conn) +} + +#[tauri::command] +fn complete_tracking_onboarding(app: AppHandle) -> Result { + let conn = open_connection(&app)?; + complete_onboarding_entry(&conn) +} + +#[tauri::command] +fn set_auto_capture_enabled(app: AppHandle, enabled: bool) -> Result { + let conn = open_connection(&app)?; + set_auto_capture_enabled_entry(&conn, enabled) +} +``` + +Register all three in `tauri::generate_handler!`. + +- [ ] **Step 7: Compile all Rust targets** + +Run: + +```bash +cd src-tauri +cargo check --all-targets +cargo test +``` + +Expected: pass. + +- [ ] **Step 8: Commit Task 2** + +```bash +git add src-tauri/src/domain/tracking.rs src-tauri/src/domain/mod.rs src-tauri/src/services/tracking.rs src-tauri/src/services/mod.rs src-tauri/src/lib.rs +git commit -m "feat(tracking): add persisted tracking state invariant" +``` + +--- + +### Task 3: Eliminate the DB/WebView startup race + +**Files:** +- Modify: `src-tauri/tauri.conf.json` window definitions +- Modify: `src-tauri/src/services/window.rs` creation/reveal helpers and tests +- Modify: `src-tauri/src/lib.rs` `.setup()` and global shortcut handler + +**Interfaces:** +- Consumes: `get_tracking_state_entry(&Connection)` from Task 2. +- Produces: `create_configured_window(app: &AppHandle, label: &str) -> Result`. +- Invariant: no configured product WebView exists before `init_database` succeeds. + +- [ ] **Step 1: Add a failing config characterization test** + +In `services/window.rs` tests, add: + +```rust +#[test] +fn configured_product_windows_require_manual_creation() { + let config: serde_json::Value = serde_json::from_str(include_str!("../../tauri.conf.json")) + .expect("parse tauri config"); + let windows = config["app"]["windows"].as_array().expect("window config array"); + for label in ["main", "pet", "pet-panel"] { + let item = windows.iter() + .find(|item| item["label"] == label) + .unwrap_or_else(|| panic!("missing window config {label}")); + assert_eq!(item["create"], false, "{label} must not auto-create before DB init"); + } +} +``` + +- [ ] **Step 2: Run the test and confirm RED** + +Run: + +```bash +cd src-tauri +cargo test services::window::tests::configured_product_windows_require_manual_creation +``` + +Expected: failure because `create` is absent/default-true. + +- [ ] **Step 3: Set every configured WebView to manual creation** + +In each of the `main`, `pet`, and `pet-panel` objects in `tauri.conf.json`, add: + +```json +"create": false +``` + +Keep all existing URL, size, decoration, transparency, visibility, and icon settings unchanged. + +- [ ] **Step 4: Add one config-driven window creation helper** + +In `services/window.rs`: + +```rust +pub(crate) fn create_configured_window( + app: &AppHandle, + label: &str, +) -> Result { + if let Some(existing) = app.get_webview_window(label) { + return Ok(existing); + } + let config = app.config().app.windows.iter() + .find(|item| item.label == label) + .ok_or_else(|| format!("window config not found: {label}"))?; + tauri::WebviewWindowBuilder::from_config(app, config) + .map_err(|e| format!("failed to build window config {label}: {e}"))? + .build() + .map_err(|e| format!("failed to create configured window {label}: {e}")) +} +``` + +Use this helper for the startup creation path. Do not rewrite unrelated panel/docking behavior in this task. + +- [ ] **Step 5: Make `.setup()` fail closed and order initialization before window creation** + +Replace the warning-only DB startup with this order: + +```rust +.setup(|app| { + init_database(app.handle()).map_err(std::io::Error::other)?; + + let conn = open_connection(app.handle()).map_err(std::io::Error::other)?; + let tracking = get_tracking_state_entry(&conn).map_err(std::io::Error::other)?; + drop(conn); + + let main_window = window_service::create_configured_window(app.handle(), "main") + .map_err(std::io::Error::other)?; + window_service::set_main_close_behavior(&main_window); + + if tracking.onboarding_completed { + window_service::create_configured_window(app.handle(), "pet") + .map_err(std::io::Error::other)?; + window_service::ensure_pet_window_position(app.handle(), true) + .map_err(std::io::Error::other)?; + } + + // existing global shortcut registration remains after the DB/window readiness boundary + Ok(()) +}) +``` + +Do not create `pet-panel` at startup; existing lazy panel creation remains. + +- [ ] **Step 6: Prevent the global shortcut from revealing a pre-onboarding pet** + +In the shortcut handler, read tracking state first. Only call `window_service::summon_pet_window` when `onboarding_completed` is true. If DB/state read fails, log the error and do not create the pet. + +The policy belongs in the composition root (`lib.rs`); keep `window_service` free of DB reads. + +- [ ] **Step 7: Run Rust verification** + +Run: + +```bash +cd src-tauri +cargo test services::window::tests::configured_product_windows_require_manual_creation +cargo check --all-targets +cargo test +``` + +Expected: pass. + +- [ ] **Step 8: Commit Task 3** + +```bash +git add src-tauri/tauri.conf.json src-tauri/src/services/window.rs src-tauri/src/lib.rs +git commit -m "fix(startup): initialize database before webviews" +``` + +--- + +### Task 4: Add typed frontend tracking state and separate sampler mechanism from policy + +**Files:** +- Modify: `src/api/types.ts` +- Modify: `src/api.ts` +- Create: `src/api/commands/tracking.ts` +- Create: `src/api/commands/window.ts` +- Modify: `src/api/commands/index.ts` +- Create: `src/composables/useTrackingState.ts` +- Modify: `src/composables/useAutoCaptureSampler.ts` + +**Interfaces:** +- Produces TS type `TrackingState`. +- Produces `getTrackingState()`, `completeTrackingOnboarding()`, `setAutoCaptureEnabled(enabled)`, `summonPetWindow()`. +- Produces composable refs `trackingState`, `trackingStateLoading`, `trackingActionLoading`, `onboardingCompleted`, `autoCaptureEnabled` plus persistence methods. +- Sampler `startAutoCaptureSampler()` / `stopAutoCaptureSampler()` remains idempotent and is started only by the runtime gate. + +- [ ] **Step 1: Add the shared TypeScript contract and command wrappers** + +In `src/api/types.ts`: + +```ts +export type TrackingState = { + onboarding_completed: boolean; + auto_capture_enabled: boolean; +}; +``` + +Export it from `src/api.ts`. + +Create `src/api/commands/tracking.ts`: + +```ts +import { invokeCommand } from "../client"; +import type { TrackingState } from "../types"; + +export async function getTrackingState(): Promise { + return invokeCommand("get_tracking_state"); +} + +export async function completeTrackingOnboarding(): Promise { + return invokeCommand("complete_tracking_onboarding"); +} + +export async function setAutoCaptureEnabled(enabled: boolean): Promise { + return invokeCommand("set_auto_capture_enabled", { enabled }); +} +``` + +Create `src/api/commands/window.ts`: + +```ts +import { invokeCommand } from "../client"; + +export async function summonPetWindow(): Promise { + await invokeCommand("summon_pet_window"); +} +``` + +Export both modules from `src/api/commands/index.ts`. + +- [ ] **Step 2: Create `useTrackingState` with persistence-only responsibility** + +Implement: + +```ts +import { computed, ref } from "vue"; +import { + completeTrackingOnboarding, + getTrackingState, + setAutoCaptureEnabled, + type TrackingState, +} from "../api"; + +export function useTrackingState(setErrorMessage: (error: unknown) => void) { + const trackingState = ref(null); + const trackingStateLoading = ref(true); + const trackingActionLoading = ref(false); + const onboardingCompleted = computed(() => trackingState.value?.onboarding_completed === true); + const autoCaptureEnabled = computed(() => trackingState.value?.auto_capture_enabled === true); + + async function loadTrackingState() { + trackingStateLoading.value = true; + try { + trackingState.value = await getTrackingState(); + return trackingState.value; + } catch (error) { + setErrorMessage(error); + throw error; + } finally { + trackingStateLoading.value = false; + } + } + + async function activateTracking() { + trackingActionLoading.value = true; + try { + trackingState.value = await completeTrackingOnboarding(); + return trackingState.value; + } finally { + trackingActionLoading.value = false; + } + } + + async function persistAutoCaptureEnabled(enabled: boolean) { + trackingActionLoading.value = true; + try { + trackingState.value = await setAutoCaptureEnabled(enabled); + return trackingState.value; + } finally { + trackingActionLoading.value = false; + } + } + + return { + trackingState, + trackingStateLoading, + trackingActionLoading, + onboardingCompleted, + autoCaptureEnabled, + loadTrackingState, + activateTracking, + persistAutoCaptureEnabled, + }; +} +``` + +Route action errors through `setErrorMessage` in the final implementation; never mutate the ref optimistically before the backend returns. + +- [ ] **Step 3: Remove policy from `useAutoCaptureSampler`** + +Change `AutoCaptureSamplerOptions` so it no longer accepts `autoCaptureEnabled`. `sampleAutoCapture()` should always perform one `captureForegroundOnce(intervalMs)` call when the sampler is running. `startAutoCaptureSampler()` remains responsible for `stop -> immediate baseline sample -> setInterval(5000)` and `stopAutoCaptureSampler()` clears the timer. + +This makes the runtime gate the sole authority for whether the sampler is running. + +- [ ] **Step 4: Run frontend static validation** + +There is no existing Vue unit-test runner, so do not add one for this task. + +Run: + +```bash +pnpm run typecheck +pnpm run build:check +``` + +Expected: pass. + +- [ ] **Step 5: Commit Task 4** + +```bash +git add src/api/types.ts src/api.ts src/api/commands/tracking.ts src/api/commands/window.ts src/api/commands/index.ts src/composables/useTrackingState.ts src/composables/useAutoCaptureSampler.ts +git commit -m "feat(ui): add persisted tracking state client" +``` + +--- + +### Task 5: Gate the Vue product runtime and persist Guard pause/resume + +**Files:** +- Modify: `src/composables/useMainWindowLifecycle.ts` +- Modify: `src/composables/useGuardData.ts` +- Modify: `src/lib/guardFeedback.ts` +- Modify: `src/App.vue` script wiring + +**Interfaces:** +- Consumes: `loadTrackingState`, `onboardingCompleted`, `autoCaptureEnabled`, `persistAutoCaptureEnabled` from Task 4. +- Produces from `useMainWindowLifecycle`: `startProductRuntime(captureEnabled: boolean)`, `syncCaptureRuntime(captureEnabled: boolean)`, `stopProductRuntime()`. +- Guard consumes one authoritative `autoCaptureEnabled` ref/computed and async `setAutoCaptureEnabled(next)` callback. + +- [ ] **Step 1: Make product runtime start idempotent** + +Refactor `useMainWindowLifecycle` so `onMounted` performs only locale/theme initialization plus `await loadTrackingState()`. Add internal `let productRuntimeStarted = false` and a returned function: + +```ts +async function startProductRuntime(captureEnabled: boolean) { + if (!productRuntimeStarted) { + productRuntimeStarted = true; + await loadHeatmapGoalSecondsSetting(); + resetGuardFeedback(); + resetPrivacyFeedback(); + void refreshHomeData(); + startSettingsWarmup(); + startMainRefreshPolling(); + await startInsightsSectionNavigationListener(); + } + syncCaptureRuntime(captureEnabled); +} + +function syncCaptureRuntime(captureEnabled: boolean) { + if (!productRuntimeStarted) return; + if (captureEnabled) startAutoCaptureSampler(); + else stopAutoCaptureSampler(); +} +``` + +If the loaded state is already onboarded, `onMounted` calls `startProductRuntime(state.auto_capture_enabled)`. If incomplete, it returns without starting Home polling/settings warmup/sampler/listeners. + +`onUnmounted` must stop polling, sampler, warmups/listeners, and reset `productRuntimeStarted=false`. + +- [ ] **Step 2: Make Guard consume persisted state instead of `ref(true)`** + +Change `UseGuardDataOptions` to accept: + +```ts +autoCaptureEnabled: Readonly>; +setAutoCaptureEnabled: (enabled: boolean) => Promise; +``` + +Delete: + +```ts +const autoCaptureEnabled = ref(true); +``` + +Change `onAutoCaptureToggle` to parse the checkbox state and call the injected async setter. Do not flip the shared state locally; the backend response updates it through `useTrackingState`. + +Add a feedback helper in `guardFeedback.ts`: + +```ts +export function guardAutoCaptureStateFeedback(enabled: boolean, tx: TranslateFn): string { + return enabled + ? tx("自动采样已开启", "Auto capture enabled") + : tx("记录已暂停；重启后仍保持暂停", "Tracking paused; pause persists after restart"); +} +``` + +Update feedback only after successful persistence. + +- [ ] **Step 3: Wire persistence to sampler start/stop in `App.vue`** + +At the composition root, create one async bridge: + +```ts +async function handleSetAutoCaptureEnabled(enabled: boolean) { + const state = await persistAutoCaptureEnabled(enabled); + syncCaptureRuntime(state.auto_capture_enabled); +} +``` + +Pass `autoCaptureEnabled` and this callback into `useGuardData`. + +Do not let `useGuardData`, `useTrackingState`, or `useAutoCaptureSampler` own all three responsibilities; `App.vue` remains the orchestration boundary. + +- [ ] **Step 4: Run frontend static gates** + +Run: + +```bash +pnpm run typecheck +pnpm run build:check +``` + +Expected: pass and there is no remaining `ref(true)` tracking authority in `useGuardData`. + +- [ ] **Step 5: Commit Task 5** + +```bash +git add src/composables/useMainWindowLifecycle.ts src/composables/useGuardData.ts src/lib/guardFeedback.ts src/App.vue +git commit -m "feat(tracking): gate runtime on persisted state" +``` + +--- + +### Task 6: Add the one-time onboarding surface and activation transition + +**Files:** +- Create: `src/components/OnboardingView.vue` +- Modify: `src/App.vue` +- Modify: `src/styles/app.css` + +**Interfaces:** +- Consumes: `trackingStateLoading`, `onboardingCompleted`, `trackingActionLoading`, `activateTracking`. +- Emits from `OnboardingView`: `activate` only; there is no persistent browse-without-tracking branch. +- Activation order: backend state commit -> product runtime start -> pet reveal. + +- [ ] **Step 1: Create a single-screen disclosure component** + +Use the existing `tx(zh, en)` translation pattern. Component API: + +```ts +const props = defineProps<{ + tx: (zh: string, en: string) => string; + loading: boolean; +}>(); +const emit = defineEmits<{ activate: [] }>(); +``` + +Required visible content, expressed concisely rather than as a carousel: + +```text +欢迎使用 TimePrism + +自动记录你的电脑时间流向，数据保存在本机。 + +开始后，TimePrism 会： +• 读取当前前台应用及窗口信息，用于计算使用时长 +• 默认对浏览器标题做隐私处理，并跳过无痕/隐私窗口 +• 将核心数据保存在本机 SQLite；当前版本不会上传到云端 + +TimePrism 不会： +• 截屏 +• 记录键盘输入内容 + +“数据看板”展示观察到的应用活动；桌宠的“学 / 休”只统计已分类为学习或休息的应用。 + +[开始使用 TimePrism] +``` + +English copy must communicate the same claims. The primary button is disabled while `loading` is true. + +- [ ] **Step 2: Style onboarding as the first product surface** + +In `app.css`, add focused classes such as `.onboarding-shell`, `.onboarding-card`, `.onboarding-points`, `.onboarding-primary`. Reuse existing background, card, text, hint, button radii, and spacing tokens; do not introduce a new visual system. + +The content must fit the existing 888x900 main-window minimum without scrolling on the default Windows scale used by the app. + +- [ ] **Step 3: Conditionally render onboarding before the normal product shell** + +In `App.vue` template, structure the top-level condition as: + +```vue + + +

+ +
+``` + +Do not start Home/Insights/Guard data flows merely because the normal DOM exists; Task 5's runtime gate remains authoritative. + +- [ ] **Step 4: Implement the activation order without optimistic tracking** + +In `App.vue`: + +```ts +async function handleActivateTracking() { + try { + const state = await activateTracking(); + await startProductRuntime(state.auto_capture_enabled); + await summonPetWindow(); + } catch (error) { + setErrorMessage(error); + } +} +``` + +If the backend state write fails, onboarding remains visible and the sampler remains stopped. If the later pet reveal fails, tracking state remains valid; report the pet error without rolling the persisted activation back. + +- [ ] **Step 5: Run frontend and Rust static gates** + +Run: + +```bash +pnpm run typecheck +pnpm run build:check +cd src-tauri +cargo check --all-targets +cargo test +``` + +Expected: pass. + +- [ ] **Step 6: Commit Task 6** + +```bash +git add src/components/OnboardingView.vue src/App.vue src/styles/app.css +git commit -m "feat(onboarding): require first-run tracking activation" +``` + +--- + +### Task 7: Make the pet communicate persisted tracking state + +**Files:** +- Modify: `src/pet.ts` + +**Interfaces:** +- Consumes: `getTrackingState()` and existing `getTodaySummary()`. +- Behavior: pet remains hidden pre-onboarding by Rust startup policy; when present, mood says active vs paused while the counters remain `LEARN` / `REST` totals. + +- [ ] **Step 1: Read summary and tracking state in the same existing 5-second refresh** + +Change `refreshSummary()` to use: + +```ts +const [summary, tracking] = await Promise.all([ + getTodaySummary(), + getTrackingState(), +]); +``` + +Keep `renderPetSummary` totals exactly based on `summary.learn_seconds` and `summary.rest_seconds`. + +Set mood text from persisted state: + +```ts +const trackingMood = tracking.auto_capture_enabled + ? tx("自动记录中", "Auto tracking") + : tx("记录已暂停", "Tracking paused"); +``` + +Pass `trackingMood` into `renderPetSummary`. + +- [ ] **Step 2: Do not change timer frequency** + +Keep the existing: + +```ts +window.setInterval(..., 5000) +``` + +No 1-second animation or synthetic counter increment is introduced. + +- [ ] **Step 3: Run frontend validation** + +Run: + +```bash +pnpm run typecheck +pnpm run build:check +``` + +Expected: pass. + +- [ ] **Step 4: Commit Task 7** + +```bash +git add src/pet.ts +git commit -m "feat(pet): show persisted tracking status" +``` + +--- + +### Task 8: Clear recovered Home read errors without masking write failures + +**Files:** +- Modify: `src/composables/useErrorMessage.ts` +- Modify: `src/composables/useHomeData.ts` +- Modify: `src/App.vue` wiring + +**Interfaces:** +- Produces: `clearErrorMessage()`. +- Home core refresh clears the global read error only after its own successful `Promise.all` completes. +- Tracking/onboarding action failures stay visible until another explicit user action or relevant successful operation replaces/clears them. + +- [ ] **Step 1: Add an explicit clear function** + +In `useErrorMessage.ts`: + +```ts +function clearErrorMessage() { + error.value = ""; +} + +return { + error, + setErrorMessage, + clearErrorMessage, +}; +``` + +- [ ] **Step 2: Clear only after successful Home core data assignment** + +Add `clearErrorMessage: () => void` to `UseHomeDataOptions`. In `refreshHomeCoreData()`, call it only after all five reads succeed and the refs are assigned: + +```ts +todaySummary.value = summary; +recentLogs.value = logs; +pendingRuleProcesses.value = pendingRules; +idlePrompts.value = pendingIdle; +reminders.value = reminderRows; +clearErrorMessage(); +``` + +Do not clear in `finally`, and do not clear on a failed refresh. + +- [ ] **Step 3: Wire `clearErrorMessage` from `App.vue` and run gates** + +Run: + +```bash +pnpm run typecheck +pnpm run build:check +``` + +Expected: pass. + +- [ ] **Step 4: Commit Task 8** + +```bash +git add src/composables/useErrorMessage.ts src/composables/useHomeData.ts src/App.vue +git commit -m "fix(ui): clear recovered home read errors" +``` + +--- + +### Task 9: Update acceptance docs and perform final automated verification + +**Files:** +- Modify: `docs/SMOKE_TESTS.md` +- Modify: `docs/RELEASE_CHECKLIST.md` +- Review only: `.github/workflows/ci.yml`, `.github/workflows/release.yml` + +**Interfaces:** +- Produces: explicit fresh-install and upgrade smoke checklist tied to the corrected installer. +- Does not alter the release workflow unless verification exposes a separate workflow defect. + +- [ ] **Step 1: Add a first-run smoke section** + +Document these exact manual assertions in `docs/SMOKE_TESTS.md`: + +```text +Fresh install / clean app-data directory +1. Launch TimePrism. +2. Confirm no `no such table: app_usage_logs` message appears. +3. Before activation, switch foreground apps for >10 seconds; confirm no usage rows are captured. +4. Confirm the onboarding disclosure states foreground app/window metadata, local SQLite storage, browser privacy, no screenshots/keystroke contents, and Insights vs 学/休 semantics. +5. Click 开始使用 TimePrism. +6. Confirm capture begins without restart. +7. Confirm Insights shows observed usage after sampling. +8. Confirm pet 学/休 remains classification-based and updates on the existing several-second cadence. +9. Pause capture; wait >10 seconds while switching apps; confirm no new capture is appended. +10. Fully quit and reopen; confirm capture remains paused and onboarding does not reappear. +11. Resume capture; quit/reopen again; confirm capture automatically resumes. +12. Confirm close-to-background, pet behavior, and Quit TimePrism remain correct. +``` + +Add a separate upgrade assertion: a pre-change DB without the two new keys starts as onboarded + capture enabled, without showing onboarding. + +- [ ] **Step 2: Add the first-run gate to `RELEASE_CHECKLIST.md`** + +Before public release, require both a clean-data fresh install and an upgrade-from-old-DB smoke. Keep the unsigned/SmartScreen note. + +- [ ] **Step 3: Run the full repository gates from a clean dependency/build state as practical** + +Run: + +```bash +pnpm install --frozen-lockfile +pnpm run typecheck +pnpm run build:check +cd src-tauri +cargo check --all-targets +cargo test +``` + +Expected: all pass. Record the Rust test count from actual output; do not reuse the previous `35 passed` claim if the suite count changes. + +- [ ] **Step 4: Push and require both Windows workflows to pass on the final HEAD** + +Verify GitHub Actions: + +```text +CI +- typecheck +- Vite build +- cargo check --all-targets +- cargo test + +Windows Release PR packaging +- synchronized version check +- frontend typecheck +- cargo test +- Tauri NSIS build +- Tauri MSI build +- installer artifact upload +``` + +The PR packaging run must generate both `*-setup.exe` and `*.msi` on the final code HEAD. + +- [ ] **Step 5: Commit docs if they were not included with an earlier task** + +```bash +git add docs/SMOKE_TESTS.md docs/RELEASE_CHECKLIST.md +git commit -m "docs: add first-run tracking release gates" +``` + +- [ ] **Step 6: Stop before merge and perform the real Windows acceptance test** + +Use a clean/sandboxed app-data directory for the fresh path and a backed-up pre-change database for the upgrade path. Do not mark PR #2 ready or publish a release until both pass. + +After the corrected build passes, capture sanitized current-build screenshots for Home, Insights, Focus Guard, and the desktop pet, then wire those real files into README as the separate product-media gate already documented in `docs/media/README.md`. + +--- + +## Final Review Checklist + +Before claiming implementation complete: + +- [ ] Fresh database defaults are `false / false`. +- [ ] Existing recognizable pre-change database defaults are `true / true`. +- [ ] Re-initialization preserves an explicit persisted pause. +- [ ] Backend rejects enabling capture before onboarding completion. +- [ ] Onboarding activation writes both state keys atomically. +- [ ] `tauri.conf.json` has `create: false` for `main`, `pet`, and `pet-panel`. +- [ ] `.setup()` initializes/migrates DB before creating the main WebView. +- [ ] DB initialization failure prevents normal runtime startup. +- [ ] Pre-onboarding main UI does not start foreground sampling or normal product polling. +- [ ] Pre-onboarding pet cannot be summoned via startup or global shortcut. +- [ ] Successful activation starts normal runtime without restart and shows the pet. +- [ ] Guard pause/resume is persisted before sampler state changes. +- [ ] Restart preserves pause; restart after resume automatically tracks. +- [ ] Sampler and UI refresh intervals remain 5 seconds. +- [ ] First capture remains baseline-only. +- [ ] Pet counters remain classified `LEARN / REST` totals and mood shows active vs paused. +- [ ] A recovered transient Home read error does not remain as a stale red footer. +- [ ] `pnpm run typecheck`, `pnpm run build:check`, `cargo check --all-targets`, and `cargo test` pass on final HEAD. +- [ ] Final Windows PR packaging produces both NSIS and MSI installers. +- [ ] Fresh-install and upgrade manual acceptance tests pass before PR/release promotion. From c2e1b8d4fbe884a8343cafb4623a42b7b392d7e2 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:52:30 +0800 Subject: [PATCH 032/117] docs: tighten first-run tracking implementation plan --- ...2026-09-08-timeprism-first-run-tracking.md | 815 ++++++++---------- 1 file changed, 382 insertions(+), 433 deletions(-) diff --git a/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md b/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md index d8e5638..006762c 100644 --- a/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md +++ b/docs/superpowers/plans/2026-09-08-timeprism-first-run-tracking.md @@ -4,7 +4,7 @@ **Goal:** Make a fresh TimePrism install initialize SQLite before any product WebView can query it, show a one-time tracking disclosure before foreground capture starts, and persist tracking pause/resume state across restarts. -**Architecture:** Keep the existing `commands -> services -> domain/db` structure. Add a small SQLite-backed tracking-state service, manually create configured Tauri windows only after database initialization, and gate the existing Vue runtime behind a persisted `TrackingState`. The foreground sampler keeps its current approximately 5-second cadence; policy/persistence stays outside the sampler. +**Architecture:** Keep the existing `commands -> services -> domain/db` structure. Add a small SQLite-backed tracking-state service, manually create configured Tauri windows only after database initialization, and gate the Vue product runtime behind a persisted `TrackingState`. The foreground sampler keeps its current approximately 5-second cadence; persistence and onboarding policy stay outside the sampler. **Tech Stack:** Tauri 2, Rust, rusqlite/SQLite, Vue 3, TypeScript, Vite, GitHub Actions on Windows. @@ -13,16 +13,16 @@ ## Global Constraints - Fresh databases start with `onboarding_completed=false` and `auto_capture_enabled=false`. -- Existing pre-change TimePrism databases migrate to `onboarding_completed=true` and `auto_capture_enabled=true` unless either key already exists. +- Existing pre-change TimePrism databases migrate to `onboarding_completed=true` and `auto_capture_enabled=true` unless a key already exists. +- Existing values are never overwritten by migration defaults. - No foreground capture may occur before onboarding activation succeeds. - A user-initiated pause persists across restart; restart must never silently turn capture back on. -- Keep the foreground sampling interval at approximately 5 seconds. -- Keep Home and pet refresh cadence at approximately 5 seconds. -- The first foreground sample remains baseline-only to avoid synthetic overcounting. +- Keep foreground sampling, Home refresh, and pet refresh at approximately 5 seconds. +- The first foreground sample remains baseline-only. - No new frontend test framework is added solely for this feature. -- Database initialization failure must prevent normal product runtime startup. -- Do not perform another broad backend or frontend directory refactor. -- Product copy must state that TimePrism reads foreground application/window metadata, stores core data locally, privacy-processes browser titles, does not capture screenshots/keystroke contents, and that Insights activity differs from classified `LEARN` / `REST` totals. +- Database initialization failure prevents normal product runtime startup. +- Do not perform another broad backend/frontend directory refactor. +- Product copy must state foreground app/window metadata, local storage, browser privacy processing, no screenshots/keystroke contents, and the difference between observed activity and classified `LEARN` / `REST` time. --- @@ -30,72 +30,59 @@ ### Create -- `src-tauri/src/domain/tracking.rs` — serialized backend `TrackingState` contract. -- `src-tauri/src/services/tracking.rs` — SQLite-backed tracking-state invariants and transitions. -- `src/api/commands/tracking.ts` — typed frontend wrappers for tracking-state Tauri commands. -- `src/api/commands/window.ts` — typed main-window wrapper for showing the pet after first activation. -- `src/composables/useTrackingState.ts` — frontend persistence-facing tracking state only; no timer ownership. -- `src/components/OnboardingView.vue` — one-screen first-run disclosure and activation UI. +- `src-tauri/src/domain/tracking.rs` — serialized backend `TrackingState`. +- `src-tauri/src/services/tracking.rs` — SQLite-backed tracking invariants/transitions. +- `src/api/commands/tracking.ts` — typed tracking-state Tauri wrappers. +- `src/api/commands/window.ts` — typed `showMainWindow` / `summonPetWindow` wrappers. +- `src/composables/useTrackingState.ts` — persisted tracking state only; no timer ownership. +- `src/components/OnboardingView.vue` — one-screen first-run disclosure. ### Modify -- `src-tauri/src/db/migrations.rs` — classify fresh vs recognizable existing DB before schema creation; seed tracking keys with migration-safe defaults. -- `src-tauri/src/db/tests.rs` — file-backed regression coverage for fresh/existing tracking defaults and persisted pause preservation. -- `src-tauri/src/domain/mod.rs` — expose tracking domain model. -- `src-tauri/src/services/mod.rs` — expose tracking service. -- `src-tauri/src/lib.rs` — thin tracking commands; fail-closed DB startup; create windows only after DB init; gate startup pet creation/shortcut by onboarding state. -- `src-tauri/src/services/window.rs` — create main/pet windows from `tauri.conf.json` config after DB readiness instead of duplicating startup config. -- `src-tauri/tauri.conf.json` — set configured WebViews to `create: false` so Tauri cannot auto-create them before `.setup()` completes. -- `src/api/types.ts` and `src/api.ts` — expose `TrackingState` to TypeScript callers. -- `src/api/commands/index.ts` — export tracking/window command modules. -- `src/composables/useAutoCaptureSampler.ts` — timer only; remove policy ownership from the sampler. -- `src/composables/useGuardData.ts` — consume persisted auto-capture state rather than creating `ref(true)`. -- `src/composables/useMainWindowLifecycle.ts` — split shell initialization from idempotent product-runtime start. -- `src/composables/useErrorMessage.ts` — add explicit clearing for a recovered transient read error. -- `src/composables/useHomeData.ts` — clear its own transient global read error after a successful core refresh. -- `src/App.vue` — composition-root wiring for tracking state, onboarding, activation, pause/resume, runtime start, and pet reveal. -- `src/pet.ts` — render active vs paused tracking state while retaining 5-second summary polling. -- `src/styles/app.css` — onboarding layout/styles using existing visual tokens. -- `docs/SMOKE_TESTS.md` and `docs/RELEASE_CHECKLIST.md` — record fresh-install and upgrade acceptance gates. +- `src-tauri/src/db/migrations.rs`, `src-tauri/src/db/tests.rs` +- `src-tauri/src/domain/mod.rs`, `src-tauri/src/services/mod.rs` +- `src-tauri/src/lib.rs`, `src-tauri/src/services/window.rs`, `src-tauri/tauri.conf.json` +- `src/api/types.ts`, `src/api.ts`, `src/api/commands/index.ts` +- `src/composables/useAutoCaptureSampler.ts`, `src/composables/useGuardData.ts`, `src/composables/useMainWindowLifecycle.ts` +- `src/composables/useErrorMessage.ts`, `src/composables/useHomeData.ts` +- `src/lib/guardFeedback.ts` +- `src/App.vue`, `src/main.ts`, `src/pet.ts`, `src/styles/app.css` +- `docs/SMOKE_TESTS.md`, `docs/RELEASE_CHECKLIST.md` --- ### Task 1: Add migration-safe tracking defaults **Files:** -- Modify: `src-tauri/src/db/migrations.rs` around `initialize_connection` -- Modify/Test: `src-tauri/src/db/tests.rs` around the fresh/idempotent/legacy database tests +- Modify: `src-tauri/src/db/migrations.rs` (`initialize_connection` and helpers) +- Modify/Test: `src-tauri/src/db/tests.rs` (fresh/idempotent/legacy tests) **Interfaces:** -- Consumes: existing `app_config(key TEXT PRIMARY KEY, value TEXT NOT NULL)` table. -- Produces: guaranteed `onboarding_completed` and `auto_capture_enabled` config keys after every successful `initialize_connection(&Connection)` call. +- Consumes: existing `app_config(key TEXT PRIMARY KEY, value TEXT NOT NULL)`. +- Produces: guaranteed `onboarding_completed` and `auto_capture_enabled` keys after successful DB initialization. -- [ ] **Step 1: Add failing database tests for fresh tracking defaults** +- [ ] **Step 1: Add RED assertions for a fresh DB** -Extend `fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens` with exact assertions: +Extend `fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens`: ```rust -let onboarding: String = conn - .query_row( - "SELECT value FROM app_config WHERE key = 'onboarding_completed'", - [], - |row| row.get(0), - ) - .expect("read onboarding default"); -let auto_capture: String = conn - .query_row( - "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", - [], - |row| row.get(0), - ) - .expect("read auto capture default"); +let onboarding: String = conn.query_row( + "SELECT value FROM app_config WHERE key = 'onboarding_completed'", + [], + |row| row.get(0), +).expect("read onboarding default"); +let auto_capture: String = conn.query_row( + "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", + [], + |row| row.get(0), +).expect("read auto capture default"); assert_eq!(onboarding, "false"); assert_eq!(auto_capture, "false"); ``` -- [ ] **Step 2: Add failing migration tests for an existing recognizable database** +- [ ] **Step 2: Add RED assertions for a recognizable legacy DB** -In `legacy_schema_is_upgraded_without_losing_existing_rows`, after creating the legacy `app_rules` / `reminders` schema and calling `initialize_connection`, assert: +Extend `legacy_schema_is_upgraded_without_losing_existing_rows` after `initialize_connection`: ```rust let onboarding: String = conn.query_row( @@ -112,9 +99,7 @@ assert_eq!(onboarding, "true"); assert_eq!(auto_capture, "true"); ``` -- [ ] **Step 3: Add a failing regression test proving initialization preserves a user pause** - -Add: +- [ ] **Step 3: Add RED regression for a persisted pause** ```rust #[test] @@ -149,9 +134,7 @@ fn database_initialization_preserves_persisted_tracking_pause() { } ``` -- [ ] **Step 4: Run the focused tests and confirm RED** - -Run: +- [ ] **Step 4: Run focused tests and verify RED** ```bash cd src-tauri @@ -160,37 +143,33 @@ cargo test db::tests::legacy_schema_is_upgraded_without_losing_existing_rows cargo test db::tests::database_initialization_preserves_persisted_tracking_pause ``` -Expected: the first two fail because the new keys do not exist; the third cannot observe the requested keys yet. +Expected: missing tracking keys cause failure. -- [ ] **Step 5: Detect whether the DB was recognizable before schema creation** +- [ ] **Step 5: Detect recognizable TimePrism schema before creating tables** -Add a helper before `initialize_connection`: +Add before `initialize_connection`: ```rust fn has_recognizable_timeprism_schema(conn: &Connection) -> Result { - let count: i64 = conn - .query_row( - "SELECT COUNT(*) - FROM sqlite_master - WHERE type = 'table' - AND name IN ('categories', 'task_sessions', 'app_usage_logs', 'app_rules', 'app_config', 'reminders')", - [], - |row| row.get(0), - ) - .map_err(|e| format!("failed to inspect existing TimePrism schema: {e}"))?; + let count: i64 = conn.query_row( + "SELECT COUNT(*) + FROM sqlite_master + WHERE type = 'table' + AND name IN ('categories', 'task_sessions', 'app_usage_logs', 'app_rules', 'app_config', 'reminders')", + [], + |row| row.get(0), + ).map_err(|e| format!("failed to inspect existing TimePrism schema: {e}"))?; Ok(count > 0) } ``` -At the start of `initialize_connection`, before the existing `CREATE TABLE IF NOT EXISTS ...` batch: +At the very start of `initialize_connection`, before the existing schema `CREATE TABLE` batch: ```rust let was_existing_timeprism_db = has_recognizable_timeprism_schema(conn)?; ``` -- [ ] **Step 6: Seed tracking keys with fresh-vs-upgrade defaults using `INSERT OR IGNORE`** - -After the existing default config loop, add: +- [ ] **Step 6: Seed migration-safe defaults after `app_config` exists** ```rust let tracking_defaults = if was_existing_timeprism_db { @@ -203,16 +182,13 @@ for (key, value) in tracking_defaults { conn.execute( "INSERT OR IGNORE INTO app_config (key, value) VALUES (?1, ?2)", params![key, value], - ) - .map_err(|e| format!("failed to seed tracking config {key}: {e}"))?; + ).map_err(|e| format!("failed to seed tracking config {key}: {e}"))?; } ``` -Do not update existing rows; `INSERT OR IGNORE` is the preservation mechanism. - -- [ ] **Step 7: Run focused tests and the full Rust suite** +`INSERT OR IGNORE` is required so existing explicit values survive re-initialization. -Run: +- [ ] **Step 7: Verify GREEN and full regression** ```bash cd src-tauri @@ -222,9 +198,7 @@ cargo test db::tests::database_initialization_preserves_persisted_tracking_pause cargo test ``` -Expected: all pass; existing DB lifecycle and mojibake tests stay green. - -- [ ] **Step 8: Commit Task 1** +- [ ] **Step 8: Commit** ```bash git add src-tauri/src/db/migrations.rs src-tauri/src/db/tests.rs @@ -237,9 +211,8 @@ git commit -m "feat(db): persist first-run tracking defaults" **Files:** - Create: `src-tauri/src/domain/tracking.rs` -- Create: `src-tauri/src/services/tracking.rs` -- Modify: `src-tauri/src/domain/mod.rs` -- Modify: `src-tauri/src/services/mod.rs` +- Create/Test: `src-tauri/src/services/tracking.rs` +- Modify: `src-tauri/src/domain/mod.rs`, `src-tauri/src/services/mod.rs` - Modify: `src-tauri/src/lib.rs` command imports/handlers **Interfaces:** @@ -249,7 +222,7 @@ git commit -m "feat(db): persist first-run tracking defaults" - Produces: `set_auto_capture_enabled_entry(&Connection, bool) -> Result`. - Produces Tauri commands: `get_tracking_state`, `complete_tracking_onboarding`, `set_auto_capture_enabled`. -- [ ] **Step 1: Create the domain contract** +- [ ] **Step 1: Create and expose the domain contract** `src-tauri/src/domain/tracking.rs`: @@ -263,21 +236,16 @@ pub struct TrackingState { } ``` -Expose it from `domain/mod.rs`: - -```rust -pub mod tracking; -``` +Add `pub mod tracking;` to `domain/mod.rs`. -- [ ] **Step 2: Write failing service tests before the service implementation** +- [ ] **Step 2: Create the tracking module, expose it, and add RED tests before functions** -Create `src-tauri/src/services/tracking.rs` with a `#[cfg(test)]` module first. Use a minimal in-memory table: +Create `src-tauri/src/services/tracking.rs` with the tests below and add `pub mod tracking;` to `services/mod.rs` immediately so `cargo test services::tracking::tests` actually compiles the new module. ```rust #[cfg(test)] mod tests { use rusqlite::{params, Connection}; - use super::{ complete_onboarding_entry, get_tracking_state_entry, set_auto_capture_enabled_entry, }; @@ -303,16 +271,16 @@ mod tests { fn completing_onboarding_atomically_enables_capture() { let conn = tracking_conn(false, false); let state = complete_onboarding_entry(&conn).expect("complete onboarding"); - assert!(state.onboarding_completed); - assert!(state.auto_capture_enabled); + assert_eq!(state.onboarding_completed, true); + assert_eq!(state.auto_capture_enabled, true); assert_eq!(get_tracking_state_entry(&conn).unwrap(), state); } #[test] fn pause_and_resume_persist_after_onboarding() { let conn = tracking_conn(true, true); - assert!(!set_auto_capture_enabled_entry(&conn, false).unwrap().auto_capture_enabled); - assert!(set_auto_capture_enabled_entry(&conn, true).unwrap().auto_capture_enabled); + assert_eq!(set_auto_capture_enabled_entry(&conn, false).unwrap().auto_capture_enabled, false); + assert_eq!(set_auto_capture_enabled_entry(&conn, true).unwrap().auto_capture_enabled, true); } #[test] @@ -320,34 +288,33 @@ mod tests { let conn = tracking_conn(false, false); let err = set_auto_capture_enabled_entry(&conn, true).unwrap_err(); assert!(err.contains("onboarding")); - assert!(!get_tracking_state_entry(&conn).unwrap().auto_capture_enabled); + assert_eq!(get_tracking_state_entry(&conn).unwrap().auto_capture_enabled, false); } } ``` -- [ ] **Step 3: Run the tracking tests and confirm RED** - -Run: +- [ ] **Step 3: Run and verify RED** ```bash cd src-tauri cargo test services::tracking::tests ``` -Expected: compile/test failure because the service functions do not exist yet. +Expected: compile failure because the referenced tracking functions do not exist. -- [ ] **Step 4: Implement strict config reads and the three state transitions** - -Use exact boolean parsing rather than a default that could hide a missing/corrupt key: +- [ ] **Step 4: Implement strict reads and state transitions** ```rust use rusqlite::{params, Connection}; use crate::domain::tracking::TrackingState; fn read_bool_config(conn: &Connection, key: &str) -> Result { - let value: String = conn - .query_row("SELECT value FROM app_config WHERE key = ?1", [key], |row| row.get(0)) - .map_err(|e| format!("failed to read tracking config {key}: {e}"))?; + let value: String = conn.query_row( + "SELECT value FROM app_config WHERE key = ?1", + [key], + |row| row.get(0), + ).map_err(|e| format!("failed to read tracking config {key}: {e}"))?; + match value.trim().to_lowercase().as_str() { "true" => Ok(true), "false" => Ok(false), @@ -363,32 +330,45 @@ pub(crate) fn get_tracking_state_entry(conn: &Connection) -> Result Result { let tx = conn.unchecked_transaction() .map_err(|e| format!("failed to begin onboarding transaction: {e}"))?; - tx.execute( - "UPDATE app_config SET value = 'true' WHERE key IN ('onboarding_completed', 'auto_capture_enabled')", - [], - ).map_err(|e| format!("failed to complete onboarding: {e}"))?; + for key in ["onboarding_completed", "auto_capture_enabled"] { + tx.execute( + "INSERT INTO app_config (key, value) VALUES (?1, 'true') + ON CONFLICT(key) DO UPDATE SET value = 'true'", + [key], + ).map_err(|e| format!("failed to persist onboarding config {key}: {e}"))?; + } tx.commit().map_err(|e| format!("failed to commit onboarding: {e}"))?; get_tracking_state_entry(conn) } ``` -`set_auto_capture_enabled_entry` must read current state first, reject `true` before onboarding, write one key, then re-read and return persisted state. - -- [ ] **Step 5: Expose the service module and run tests GREEN** - -Add to `services/mod.rs`: +Implement `set_auto_capture_enabled_entry` as: ```rust -pub mod tracking; +pub(crate) fn set_auto_capture_enabled_entry( + conn: &Connection, + enabled: bool, +) -> Result { + let current = get_tracking_state_entry(conn)?; + if enabled && !current.onboarding_completed { + return Err("cannot enable auto capture before onboarding is complete".to_string()); + } + conn.execute( + "INSERT INTO app_config (key, value) VALUES ('auto_capture_enabled', ?1) + ON CONFLICT(key) DO UPDATE SET value = excluded.value", + [if enabled { "true" } else { "false" }], + ).map_err(|e| format!("failed to persist auto capture state: {e}"))?; + get_tracking_state_entry(conn) +} ``` -Run: +- [ ] **Step 5: Verify GREEN** ```bash cd src-tauri @@ -396,11 +376,9 @@ cargo test services::tracking::tests cargo test ``` -Expected: all pass. +- [ ] **Step 6: Add thin Tauri commands and register them** -- [ ] **Step 6: Add thin Tauri command wrappers** - -In `lib.rs`, import the model/service and add: +In `lib.rs`: ```rust #[tauri::command(async)] @@ -422,23 +400,15 @@ fn set_auto_capture_enabled(app: AppHandle, enabled: bool) -> Result Result`. -- Invariant: no configured product WebView exists before `init_database` succeeds. +- Consumes: `get_tracking_state_entry` from Task 2. +- Produces: `create_configured_window(app, label) -> Result`. +- Invariant: no product WebView exists before `init_database` succeeds. -- [ ] **Step 1: Add a failing config characterization test** +- [ ] **Step 1: Add RED config test** -In `services/window.rs` tests, add: +In `services/window.rs` tests: ```rust #[test] @@ -476,30 +446,24 @@ fn configured_product_windows_require_manual_creation() { } ``` -- [ ] **Step 2: Run the test and confirm RED** - -Run: +- [ ] **Step 2: Verify RED** ```bash cd src-tauri cargo test services::window::tests::configured_product_windows_require_manual_creation ``` -Expected: failure because `create` is absent/default-true. - -- [ ] **Step 3: Set every configured WebView to manual creation** +- [ ] **Step 3: Set all configured product windows to manual creation** -In each of the `main`, `pet`, and `pet-panel` objects in `tauri.conf.json`, add: +Add to each `main`, `pet`, `pet-panel` object in `tauri.conf.json`: ```json "create": false ``` -Keep all existing URL, size, decoration, transparency, visibility, and icon settings unchanged. - -- [ ] **Step 4: Add one config-driven window creation helper** +Do not change their other config values. -In `services/window.rs`: +- [ ] **Step 4: Add config-driven creation helper** ```rust pub(crate) fn create_configured_window( @@ -519,11 +483,9 @@ pub(crate) fn create_configured_window( } ``` -Use this helper for the startup creation path. Do not rewrite unrelated panel/docking behavior in this task. +- [ ] **Step 5: Make `.setup()` fail closed and order DB before windows** -- [ ] **Step 5: Make `.setup()` fail closed and order initialization before window creation** - -Replace the warning-only DB startup with this order: +Required order in `lib.rs`: ```rust .setup(|app| { @@ -544,22 +506,35 @@ Replace the warning-only DB startup with this order: .map_err(std::io::Error::other)?; } - // existing global shortcut registration remains after the DB/window readiness boundary + // register existing shortcut only after DB/window readiness Ok(()) }) ``` -Do not create `pet-panel` at startup; existing lazy panel creation remains. +Delete the current `eprintln!("database init warning...")` continue-on-error behavior. -- [ ] **Step 6: Prevent the global shortcut from revealing a pre-onboarding pet** +- [ ] **Step 6: Gate both shortcut and Tauri pet command before onboarding** -In the shortcut handler, read tracking state first. Only call `window_service::summon_pet_window` when `onboarding_completed` is true. If DB/state read fails, log the error and do not create the pet. +For the global shortcut handler: open DB, read `TrackingState`, and summon only when `onboarding_completed=true`. On read failure, log and do nothing. -The policy belongs in the composition root (`lib.rs`); keep `window_service` free of DB reads. +For the `summon_pet_window` Tauri command wrapper, enforce the same backend policy: -- [ ] **Step 7: Run Rust verification** +```rust +#[tauri::command] +fn summon_pet_window(app: AppHandle) -> Result<(), String> { + let conn = open_connection(&app)?; + let state = get_tracking_state_entry(&conn)?; + if !state.onboarding_completed { + return Err("pet is unavailable before onboarding is complete".to_string()); + } + drop(conn); + window_service::summon_pet_window(&app) +} +``` -Run: +The window service itself remains DB-agnostic. + +- [ ] **Step 7: Verify Rust** ```bash cd src-tauri @@ -568,9 +543,7 @@ cargo check --all-targets cargo test ``` -Expected: pass. - -- [ ] **Step 8: Commit Task 3** +- [ ] **Step 8: Commit** ```bash git add src-tauri/tauri.conf.json src-tauri/src/services/window.rs src-tauri/src/lib.rs @@ -579,26 +552,24 @@ git commit -m "fix(startup): initialize database before webviews" --- -### Task 4: Add typed frontend tracking state and separate sampler mechanism from policy +### Task 4: Add typed frontend tracking/window APIs and make the sampler mechanism-only **Files:** -- Modify: `src/api/types.ts` -- Modify: `src/api.ts` -- Create: `src/api/commands/tracking.ts` -- Create: `src/api/commands/window.ts` -- Modify: `src/api/commands/index.ts` +- Modify: `src/api/types.ts`, `src/api.ts`, `src/api/commands/index.ts` +- Create: `src/api/commands/tracking.ts`, `src/api/commands/window.ts` - Create: `src/composables/useTrackingState.ts` - Modify: `src/composables/useAutoCaptureSampler.ts` **Interfaces:** -- Produces TS type `TrackingState`. -- Produces `getTrackingState()`, `completeTrackingOnboarding()`, `setAutoCaptureEnabled(enabled)`, `summonPetWindow()`. -- Produces composable refs `trackingState`, `trackingStateLoading`, `trackingActionLoading`, `onboardingCompleted`, `autoCaptureEnabled` plus persistence methods. -- Sampler `startAutoCaptureSampler()` / `stopAutoCaptureSampler()` remains idempotent and is started only by the runtime gate. +- Produces TS `TrackingState`. +- Produces `getTrackingState`, `completeTrackingOnboarding`, `setAutoCaptureEnabled`. +- Produces `showMainWindow`, `summonPetWindow`. +- Produces `useTrackingState` refs/methods. +- Sampler owns only immediate sample + 5-second interval + stop. -- [ ] **Step 1: Add the shared TypeScript contract and command wrappers** +- [ ] **Step 1: Add typed contracts/wrappers** -In `src/api/types.ts`: +`src/api/types.ts`: ```ts export type TrackingState = { @@ -607,42 +578,41 @@ export type TrackingState = { }; ``` -Export it from `src/api.ts`. +Export `TrackingState` from `src/api.ts`. -Create `src/api/commands/tracking.ts`: +`src/api/commands/tracking.ts`: ```ts import { invokeCommand } from "../client"; import type { TrackingState } from "../types"; -export async function getTrackingState(): Promise { - return invokeCommand("get_tracking_state"); -} +export const getTrackingState = (): Promise => + invokeCommand("get_tracking_state"); -export async function completeTrackingOnboarding(): Promise { - return invokeCommand("complete_tracking_onboarding"); -} +export const completeTrackingOnboarding = (): Promise => + invokeCommand("complete_tracking_onboarding"); -export async function setAutoCaptureEnabled(enabled: boolean): Promise { - return invokeCommand("set_auto_capture_enabled", { enabled }); -} +export const setAutoCaptureEnabled = (enabled: boolean): Promise => + invokeCommand("set_auto_capture_enabled", { enabled }); ``` -Create `src/api/commands/window.ts`: +`src/api/commands/window.ts`: ```ts import { invokeCommand } from "../client"; +export async function showMainWindow(): Promise { + await invokeCommand("show_main_window"); +} + export async function summonPetWindow(): Promise { await invokeCommand("summon_pet_window"); } ``` -Export both modules from `src/api/commands/index.ts`. - -- [ ] **Step 2: Create `useTrackingState` with persistence-only responsibility** +Export both new modules from `src/api/commands/index.ts`. -Implement: +- [ ] **Step 2: Create persistence-only `useTrackingState`** ```ts import { computed, ref } from "vue"; @@ -660,11 +630,12 @@ export function useTrackingState(setErrorMessage: (error: unknown) => void) { const onboardingCompleted = computed(() => trackingState.value?.onboarding_completed === true); const autoCaptureEnabled = computed(() => trackingState.value?.auto_capture_enabled === true); - async function loadTrackingState() { + async function loadTrackingState(): Promise { trackingStateLoading.value = true; try { - trackingState.value = await getTrackingState(); - return trackingState.value; + const next = await getTrackingState(); + trackingState.value = next; + return next; } catch (error) { setErrorMessage(error); throw error; @@ -673,21 +644,29 @@ export function useTrackingState(setErrorMessage: (error: unknown) => void) { } } - async function activateTracking() { + async function activateTracking(): Promise { trackingActionLoading.value = true; try { - trackingState.value = await completeTrackingOnboarding(); - return trackingState.value; + const next = await completeTrackingOnboarding(); + trackingState.value = next; + return next; + } catch (error) { + setErrorMessage(error); + throw error; } finally { trackingActionLoading.value = false; } } - async function persistAutoCaptureEnabled(enabled: boolean) { + async function persistAutoCaptureEnabled(enabled: boolean): Promise { trackingActionLoading.value = true; try { - trackingState.value = await setAutoCaptureEnabled(enabled); - return trackingState.value; + const next = await setAutoCaptureEnabled(enabled); + trackingState.value = next; + return next; + } catch (error) { + setErrorMessage(error); + throw error; } finally { trackingActionLoading.value = false; } @@ -706,54 +685,84 @@ export function useTrackingState(setErrorMessage: (error: unknown) => void) { } ``` -Route action errors through `setErrorMessage` in the final implementation; never mutate the ref optimistically before the backend returns. - -- [ ] **Step 3: Remove policy from `useAutoCaptureSampler`** +No optimistic ref mutation is allowed. -Change `AutoCaptureSamplerOptions` so it no longer accepts `autoCaptureEnabled`. `sampleAutoCapture()` should always perform one `captureForegroundOnce(intervalMs)` call when the sampler is running. `startAutoCaptureSampler()` remains responsible for `stop -> immediate baseline sample -> setInterval(5000)` and `stopAutoCaptureSampler()` clears the timer. +- [ ] **Step 3: Remove policy ownership from `useAutoCaptureSampler`** -This makes the runtime gate the sole authority for whether the sampler is running. +Delete `autoCaptureEnabled` from `AutoCaptureSamplerOptions` and delete the early return in `sampleAutoCapture()`. The sampler runs only when `startAutoCaptureSampler()` has been called. Preserve: -- [ ] **Step 4: Run frontend static validation** +```ts +function startAutoCaptureSampler() { + stopAutoCaptureSampler(); + sampleAutoCapture(); + captureTimer = window.setInterval(sampleAutoCapture, intervalMs); +} +``` -There is no existing Vue unit-test runner, so do not add one for this task. +Keep default `intervalMs = 5000`. -Run: +- [ ] **Step 4: Static verification and commit** ```bash pnpm run typecheck pnpm run build:check -``` - -Expected: pass. - -- [ ] **Step 5: Commit Task 4** - -```bash git add src/api/types.ts src/api.ts src/api/commands/tracking.ts src/api/commands/window.ts src/api/commands/index.ts src/composables/useTrackingState.ts src/composables/useAutoCaptureSampler.ts git commit -m "feat(ui): add persisted tracking state client" ``` --- -### Task 5: Gate the Vue product runtime and persist Guard pause/resume +### Task 5: Gate Vue runtime, delay main reveal until state is loaded, and persist Guard pause/resume **Files:** - Modify: `src/composables/useMainWindowLifecycle.ts` - Modify: `src/composables/useGuardData.ts` - Modify: `src/lib/guardFeedback.ts` -- Modify: `src/App.vue` script wiring +- Modify: `src/App.vue` +- Modify: `src/main.ts` **Interfaces:** -- Consumes: `loadTrackingState`, `onboardingCompleted`, `autoCaptureEnabled`, `persistAutoCaptureEnabled` from Task 4. -- Produces from `useMainWindowLifecycle`: `startProductRuntime(captureEnabled: boolean)`, `syncCaptureRuntime(captureEnabled: boolean)`, `stopProductRuntime()`. -- Guard consumes one authoritative `autoCaptureEnabled` ref/computed and async `setAutoCaptureEnabled(next)` callback. +- Consumes: Task 4 tracking state/APIs. +- Produces: `startProductRuntime(captureEnabled)`, `syncCaptureRuntime(captureEnabled)`, `stopProductRuntime`. +- Main WebView remains hidden until tracking state has loaded; first visible UI is onboarding or normal product shell, not an empty shell. + +- [ ] **Step 1: Remove unconditional main reveal from `src/main.ts`** + +Replace current mount-plus-`invoke("show_main_window")` code with: + +```ts +import { createApp } from "vue"; +import App from "./App.vue"; +import "./styles/app.css"; + +createApp(App).mount("#app"); +``` + +Main window is already created hidden by Rust after DB init. It will be revealed only after tracking state loads. -- [ ] **Step 1: Make product runtime start idempotent** +- [ ] **Step 2: Refactor lifecycle into shell-init + idempotent product runtime** -Refactor `useMainWindowLifecycle` so `onMounted` performs only locale/theme initialization plus `await loadTrackingState()`. Add internal `let productRuntimeStarted = false` and a returned function: +Add `loadTrackingState` and `showMainWindow` dependencies. `onMounted` order: ```ts +onMounted(async () => { + initLocale(); + initThemeModeSafely(); + + const tracking = await loadTrackingState(); + await showMainWindow(); + + if (tracking.onboarding_completed) { + await startProductRuntime(tracking.auto_capture_enabled); + } +}); +``` + +Use: + +```ts +let productRuntimeStarted = false; + async function startProductRuntime(captureEnabled: boolean) { if (!productRuntimeStarted) { productRuntimeStarted = true; @@ -773,30 +782,45 @@ function syncCaptureRuntime(captureEnabled: boolean) { if (captureEnabled) startAutoCaptureSampler(); else stopAutoCaptureSampler(); } -``` -If the loaded state is already onboarded, `onMounted` calls `startProductRuntime(state.auto_capture_enabled)`. If incomplete, it returns without starting Home polling/settings warmup/sampler/listeners. +function stopProductRuntime() { + stopMainRefreshPolling(); + stopAutoCaptureSampler(); + cleanupSettingsWarmup(); + cleanupInsightsSectionNavigation(); + cleanupHeatmapGoalSetting(); + productRuntimeStarted = false; +} +``` -`onUnmounted` must stop polling, sampler, warmups/listeners, and reset `productRuntimeStarted=false`. +Return `startProductRuntime`, `syncCaptureRuntime`, `stopProductRuntime`; call `stopProductRuntime()` on unmount. -- [ ] **Step 2: Make Guard consume persisted state instead of `ref(true)`** +- [ ] **Step 3: Make Guard consume the authoritative persisted state** -Change `UseGuardDataOptions` to accept: +Change `UseGuardDataOptions` to include: ```ts autoCaptureEnabled: Readonly>; setAutoCaptureEnabled: (enabled: boolean) => Promise; ``` -Delete: +Import `type Ref` from Vue and delete local `const autoCaptureEnabled = ref(true)`. + +`onAutoCaptureToggle` becomes async: ```ts -const autoCaptureEnabled = ref(true); +async function onAutoCaptureToggle(event: Event) { + const enabled = guardCheckedFromEvent(event); + try { + await setAutoCaptureEnabled(enabled); + autoCaptureFeedback.value = guardAutoCaptureStateFeedback(enabled, tx); + } catch (error) { + setErrorMessage(error); + } +} ``` -Change `onAutoCaptureToggle` to parse the checkbox state and call the injected async setter. Do not flip the shared state locally; the backend response updates it through `useTrackingState`. - -Add a feedback helper in `guardFeedback.ts`: +Add to `guardFeedback.ts`: ```ts export function guardAutoCaptureStateFeedback(enabled: boolean, tx: TranslateFn): string { @@ -806,11 +830,9 @@ export function guardAutoCaptureStateFeedback(enabled: boolean, tx: TranslateFn) } ``` -Update feedback only after successful persistence. - -- [ ] **Step 3: Wire persistence to sampler start/stop in `App.vue`** +- [ ] **Step 4: Wire persistence to sampler only after backend success** -At the composition root, create one async bridge: +In `App.vue`: ```ts async function handleSetAutoCaptureEnabled(enabled: boolean) { @@ -819,45 +841,30 @@ async function handleSetAutoCaptureEnabled(enabled: boolean) { } ``` -Pass `autoCaptureEnabled` and this callback into `useGuardData`. - -Do not let `useGuardData`, `useTrackingState`, or `useAutoCaptureSampler` own all three responsibilities; `App.vue` remains the orchestration boundary. +Pass `autoCaptureEnabled` and `handleSetAutoCaptureEnabled` into `useGuardData`. -- [ ] **Step 4: Run frontend static gates** - -Run: +- [ ] **Step 5: Verify and commit** ```bash pnpm run typecheck pnpm run build:check -``` - -Expected: pass and there is no remaining `ref(true)` tracking authority in `useGuardData`. - -- [ ] **Step 5: Commit Task 5** - -```bash -git add src/composables/useMainWindowLifecycle.ts src/composables/useGuardData.ts src/lib/guardFeedback.ts src/App.vue +git add src/main.ts src/composables/useMainWindowLifecycle.ts src/composables/useGuardData.ts src/lib/guardFeedback.ts src/App.vue git commit -m "feat(tracking): gate runtime on persisted state" ``` --- -### Task 6: Add the one-time onboarding surface and activation transition +### Task 6: Add one-time onboarding and activation transition **Files:** - Create: `src/components/OnboardingView.vue` -- Modify: `src/App.vue` -- Modify: `src/styles/app.css` +- Modify: `src/App.vue`, `src/styles/app.css` **Interfaces:** -- Consumes: `trackingStateLoading`, `onboardingCompleted`, `trackingActionLoading`, `activateTracking`. -- Emits from `OnboardingView`: `activate` only; there is no persistent browse-without-tracking branch. -- Activation order: backend state commit -> product runtime start -> pet reveal. - -- [ ] **Step 1: Create a single-screen disclosure component** +- Emits `activate` only; no persistent browse-without-tracking branch. +- Activation order: backend commit -> start runtime -> reveal/create pet. -Use the existing `tx(zh, en)` translation pattern. Component API: +- [ ] **Step 1: Create disclosure component** ```ts const props = defineProps<{ @@ -867,11 +874,10 @@ const props = defineProps<{ const emit = defineEmits<{ activate: [] }>(); ``` -Required visible content, expressed concisely rather than as a carousel: +Required Chinese meaning (English copy must match): ```text 欢迎使用 TimePrism - 自动记录你的电脑时间流向，数据保存在本机。 开始后，TimePrism 会： @@ -888,17 +894,13 @@ TimePrism 不会： [开始使用 TimePrism] ``` -English copy must communicate the same claims. The primary button is disabled while `loading` is true. - -- [ ] **Step 2: Style onboarding as the first product surface** - -In `app.css`, add focused classes such as `.onboarding-shell`, `.onboarding-card`, `.onboarding-points`, `.onboarding-primary`. Reuse existing background, card, text, hint, button radii, and spacing tokens; do not introduce a new visual system. +Disable the primary button while `loading`. -The content must fit the existing 888x900 main-window minimum without scrolling on the default Windows scale used by the app. +- [ ] **Step 2: Add focused onboarding styles** -- [ ] **Step 3: Conditionally render onboarding before the normal product shell** +Use `.onboarding-shell`, `.onboarding-card`, `.onboarding-points`, `.onboarding-primary`; reuse existing colors/radii/spacing. Fit within 888x900 without default-scale scrolling. -In `App.vue` template, structure the top-level condition as: +- [ ] **Step 3: Render onboarding before normal product shell** ```vue
- +
``` -Do not start Home/Insights/Guard data flows merely because the normal DOM exists; Task 5's runtime gate remains authoritative. +The hidden main window is revealed by Task 5 only after tracking state resolves, so users do not see an empty shell during this conditional decision. -- [ ] **Step 4: Implement the activation order without optimistic tracking** - -In `App.vue`: +- [ ] **Step 4: Implement activation without optimistic tracking** ```ts async function handleActivateTracking() { try { const state = await activateTracking(); await startProductRuntime(state.auto_capture_enabled); - await summonPetWindow(); + try { + await summonPetWindow(); + } catch (petError) { + setErrorMessage(petError); + } } catch (error) { setErrorMessage(error); } } ``` -If the backend state write fails, onboarding remains visible and the sampler remains stopped. If the later pet reveal fails, tracking state remains valid; report the pet error without rolling the persisted activation back. - -- [ ] **Step 5: Run frontend and Rust static gates** +A backend activation failure leaves onboarding visible and sampler stopped. A later pet-show failure does not roll back successfully persisted activation. -Run: +- [ ] **Step 5: Verify and commit** ```bash pnpm run typecheck @@ -943,112 +945,83 @@ pnpm run build:check cd src-tauri cargo check --all-targets cargo test -``` - -Expected: pass. - -- [ ] **Step 6: Commit Task 6** - -```bash +cd .. git add src/components/OnboardingView.vue src/App.vue src/styles/app.css git commit -m "feat(onboarding): require first-run tracking activation" ``` --- -### Task 7: Make the pet communicate persisted tracking state +### Task 7: Make pet show active vs paused tracking state **Files:** - Modify: `src/pet.ts` **Interfaces:** -- Consumes: `getTrackingState()` and existing `getTodaySummary()`. -- Behavior: pet remains hidden pre-onboarding by Rust startup policy; when present, mood says active vs paused while the counters remain `LEARN` / `REST` totals. +- Consumes `getTrackingState` + `getTodaySummary`. +- Counters remain classified `LEARN` / `REST`; only mood reflects tracking state. -- [ ] **Step 1: Read summary and tracking state in the same existing 5-second refresh** - -Change `refreshSummary()` to use: +- [ ] **Step 1: Read state in existing summary refresh** ```ts const [summary, tracking] = await Promise.all([ getTodaySummary(), getTrackingState(), ]); -``` - -Keep `renderPetSummary` totals exactly based on `summary.learn_seconds` and `summary.rest_seconds`. - -Set mood text from persisted state: - -```ts const trackingMood = tracking.auto_capture_enabled ? tx("自动记录中", "Auto tracking") : tx("记录已暂停", "Tracking paused"); ``` -Pass `trackingMood` into `renderPetSummary`. - -- [ ] **Step 2: Do not change timer frequency** - -Keep the existing: - -```ts -window.setInterval(..., 5000) -``` +Pass `formatSeconds(summary.learn_seconds)`, `formatSeconds(summary.rest_seconds)`, and `trackingMood` to `renderPetSummary`. -No 1-second animation or synthetic counter increment is introduced. +- [ ] **Step 2: Preserve 5-second cadence** -- [ ] **Step 3: Run frontend validation** +Keep the existing `window.setInterval(..., 5000)` and baseline-only capture behavior. Do not synthesize per-second increments. -Run: +- [ ] **Step 3: Verify and commit** ```bash pnpm run typecheck pnpm run build:check -``` - -Expected: pass. - -- [ ] **Step 4: Commit Task 7** - -```bash git add src/pet.ts git commit -m "feat(pet): show persisted tracking status" ``` --- -### Task 8: Clear recovered Home read errors without masking write failures +### Task 8: Clear only the recovered Home error, never a newer tracking error **Files:** - Modify: `src/composables/useErrorMessage.ts` - Modify: `src/composables/useHomeData.ts` -- Modify: `src/App.vue` wiring +- Modify: `src/App.vue` **Interfaces:** -- Produces: `clearErrorMessage()`. -- Home core refresh clears the global read error only after its own successful `Promise.all` completes. -- Tracking/onboarding action failures stay visible until another explicit user action or relevant successful operation replaces/clears them. - -- [ ] **Step 1: Add an explicit clear function** +- Produces compare-and-clear API: `clearErrorMessage(expected?: unknown)`. +- Home remembers the exact error string it last published and clears only that same string after recovery. -In `useErrorMessage.ts`: +- [ ] **Step 1: Add compare-and-clear semantics** ```ts -function clearErrorMessage() { - error.value = ""; +function clearErrorMessage(expected?: unknown) { + if (expected === undefined || error.value === `${expected}`) { + error.value = ""; + } } - -return { - error, - setErrorMessage, - clearErrorMessage, -}; ``` -- [ ] **Step 2: Clear only after successful Home core data assignment** +Return it with `error` and `setErrorMessage`. -Add `clearErrorMessage: () => void` to `UseHomeDataOptions`. In `refreshHomeCoreData()`, call it only after all five reads succeed and the refs are assigned: +- [ ] **Step 2: Track the last Home-owned read error** + +In `useHomeData`: + +```ts +let lastHomeCoreError = ""; +``` + +Add `clearErrorMessage: (expected?: unknown) => void` to options. On successful core assignment: ```ts todaySummary.value = summary; @@ -1056,71 +1029,64 @@ recentLogs.value = logs; pendingRuleProcesses.value = pendingRules; idlePrompts.value = pendingIdle; reminders.value = reminderRows; -clearErrorMessage(); +if (lastHomeCoreError) { + clearErrorMessage(lastHomeCoreError); + lastHomeCoreError = ""; +} ``` -Do not clear in `finally`, and do not clear on a failed refresh. - -- [ ] **Step 3: Wire `clearErrorMessage` from `App.vue` and run gates** - -Run: +On failure: -```bash -pnpm run typecheck -pnpm run build:check +```ts +lastHomeCoreError = `${e}`; +setErrorMessage(e); ``` -Expected: pass. +If a newer tracking write error has replaced the global message, `clearErrorMessage(lastHomeCoreError)` does nothing, so polling cannot erase the newer failure. -- [ ] **Step 4: Commit Task 8** +- [ ] **Step 3: Wire and verify** ```bash +pnpm run typecheck +pnpm run build:check git add src/composables/useErrorMessage.ts src/composables/useHomeData.ts src/App.vue -git commit -m "fix(ui): clear recovered home read errors" +git commit -m "fix(ui): clear only recovered home read errors" ``` --- -### Task 9: Update acceptance docs and perform final automated verification +### Task 9: Update acceptance docs and run final automated gates **Files:** -- Modify: `docs/SMOKE_TESTS.md` -- Modify: `docs/RELEASE_CHECKLIST.md` -- Review only: `.github/workflows/ci.yml`, `.github/workflows/release.yml` - -**Interfaces:** -- Produces: explicit fresh-install and upgrade smoke checklist tied to the corrected installer. -- Does not alter the release workflow unless verification exposes a separate workflow defect. +- Modify: `docs/SMOKE_TESTS.md`, `docs/RELEASE_CHECKLIST.md` +- Review only unless a new defect appears: `.github/workflows/ci.yml`, `.github/workflows/release.yml` -- [ ] **Step 1: Add a first-run smoke section** +- [ ] **Step 1: Add exact fresh-install smoke assertions** -Document these exact manual assertions in `docs/SMOKE_TESTS.md`: +Document: ```text -Fresh install / clean app-data directory -1. Launch TimePrism. -2. Confirm no `no such table: app_usage_logs` message appears. -3. Before activation, switch foreground apps for >10 seconds; confirm no usage rows are captured. -4. Confirm the onboarding disclosure states foreground app/window metadata, local SQLite storage, browser privacy, no screenshots/keystroke contents, and Insights vs 学/休 semantics. -5. Click 开始使用 TimePrism. -6. Confirm capture begins without restart. -7. Confirm Insights shows observed usage after sampling. -8. Confirm pet 学/休 remains classification-based and updates on the existing several-second cadence. -9. Pause capture; wait >10 seconds while switching apps; confirm no new capture is appended. -10. Fully quit and reopen; confirm capture remains paused and onboarding does not reappear. -11. Resume capture; quit/reopen again; confirm capture automatically resumes. -12. Confirm close-to-background, pet behavior, and Quit TimePrism remain correct. +1. Clean/sandbox the TimePrism app-data directory and launch. +2. Confirm no `no such table: app_usage_logs` error appears. +3. Before activation, switch foreground apps for >10 seconds and confirm no usage rows are captured. +4. Confirm onboarding explains foreground app/window metadata, local SQLite, browser privacy, no screenshots/keystroke contents, and Insights vs 学/休 semantics. +5. Click 开始使用 TimePrism; confirm capture begins without restart. +6. Confirm Insights shows observed activity after sampling. +7. Confirm pet 学/休 remains classification-based and updates on the existing several-second cadence. +8. Pause capture; switch apps for >10 seconds; confirm no new samples are appended. +9. Fully quit/reopen; confirm pause persists and onboarding does not reappear. +10. Resume; quit/reopen; confirm automatic tracking resumes. +11. Confirm pet says paused while paused. +12. Confirm close-to-background, pet, and Quit TimePrism behavior still works. ``` -Add a separate upgrade assertion: a pre-change DB without the two new keys starts as onboarded + capture enabled, without showing onboarding. - -- [ ] **Step 2: Add the first-run gate to `RELEASE_CHECKLIST.md`** +Add upgrade test: pre-change DB without the new keys starts onboarded + capture enabled without showing onboarding. -Before public release, require both a clean-data fresh install and an upgrade-from-old-DB smoke. Keep the unsigned/SmartScreen note. +- [ ] **Step 2: Add fresh + upgrade gates to release checklist** -- [ ] **Step 3: Run the full repository gates from a clean dependency/build state as practical** +Require both before public release; keep unsigned/SmartScreen note. -Run: +- [ ] **Step 3: Run repository gates** ```bash pnpm install --frozen-lockfile @@ -1131,66 +1097,49 @@ cargo check --all-targets cargo test ``` -Expected: all pass. Record the Rust test count from actual output; do not reuse the previous `35 passed` claim if the suite count changes. - -- [ ] **Step 4: Push and require both Windows workflows to pass on the final HEAD** +Record actual test count from output; do not reuse `35 passed` if it changes. -Verify GitHub Actions: +- [ ] **Step 4: Push final HEAD and require both Windows workflows GREEN** -```text -CI -- typecheck -- Vite build -- cargo check --all-targets -- cargo test - -Windows Release PR packaging -- synchronized version check -- frontend typecheck -- cargo test -- Tauri NSIS build -- Tauri MSI build -- installer artifact upload -``` +CI must pass typecheck, Vite build, `cargo check --all-targets`, `cargo test`. -The PR packaging run must generate both `*-setup.exe` and `*.msi` on the final code HEAD. +Windows Release PR packaging must pass synchronized-version check, typecheck, Rust tests, `tauri build --bundles nsis msi`, and artifact upload. Verify both `*-setup.exe` and `*.msi` exist on the final code HEAD. -- [ ] **Step 5: Commit docs if they were not included with an earlier task** +- [ ] **Step 5: Commit docs** ```bash git add docs/SMOKE_TESTS.md docs/RELEASE_CHECKLIST.md git commit -m "docs: add first-run tracking release gates" ``` -- [ ] **Step 6: Stop before merge and perform the real Windows acceptance test** +- [ ] **Step 6: Stop before merge for real Windows acceptance** -Use a clean/sandboxed app-data directory for the fresh path and a backed-up pre-change database for the upgrade path. Do not mark PR #2 ready or publish a release until both pass. +Use a clean app-data directory for fresh install and a backed-up pre-change DB for upgrade. Do not mark PR #2 ready or publish a release until both pass. -After the corrected build passes, capture sanitized current-build screenshots for Home, Insights, Focus Guard, and the desktop pet, then wire those real files into README as the separate product-media gate already documented in `docs/media/README.md`. +After acceptance, capture sanitized Home / Insights / Focus Guard / pet screenshots from this corrected build and wire only those real product images into README. --- ## Final Review Checklist -Before claiming implementation complete: - -- [ ] Fresh database defaults are `false / false`. -- [ ] Existing recognizable pre-change database defaults are `true / true`. -- [ ] Re-initialization preserves an explicit persisted pause. -- [ ] Backend rejects enabling capture before onboarding completion. -- [ ] Onboarding activation writes both state keys atomically. -- [ ] `tauri.conf.json` has `create: false` for `main`, `pet`, and `pet-panel`. -- [ ] `.setup()` initializes/migrates DB before creating the main WebView. -- [ ] DB initialization failure prevents normal runtime startup. -- [ ] Pre-onboarding main UI does not start foreground sampling or normal product polling. -- [ ] Pre-onboarding pet cannot be summoned via startup or global shortcut. -- [ ] Successful activation starts normal runtime without restart and shows the pet. -- [ ] Guard pause/resume is persisted before sampler state changes. -- [ ] Restart preserves pause; restart after resume automatically tracks. -- [ ] Sampler and UI refresh intervals remain 5 seconds. -- [ ] First capture remains baseline-only. -- [ ] Pet counters remain classified `LEARN / REST` totals and mood shows active vs paused. -- [ ] A recovered transient Home read error does not remain as a stale red footer. -- [ ] `pnpm run typecheck`, `pnpm run build:check`, `cargo check --all-targets`, and `cargo test` pass on final HEAD. -- [ ] Final Windows PR packaging produces both NSIS and MSI installers. -- [ ] Fresh-install and upgrade manual acceptance tests pass before PR/release promotion. +- [ ] Fresh DB defaults are `false / false`. +- [ ] Existing recognizable pre-change DB defaults are `true / true`. +- [ ] Re-initialization preserves explicit pause. +- [ ] Backend rejects enabling capture before onboarding. +- [ ] Onboarding activation atomically persists `true / true`. +- [ ] `main`, `pet`, `pet-panel` all have `create:false`. +- [ ] DB initializes before main WebView creation. +- [ ] DB init failure prevents normal startup. +- [ ] Main stays hidden until tracking state loads. +- [ ] Pre-onboarding runtime starts no sampler/polling. +- [ ] Pre-onboarding pet cannot be created through startup, shortcut, or Tauri command. +- [ ] Activation starts runtime without restart and then reveals pet. +- [ ] Guard pause/resume persists before sampler changes. +- [ ] Restart preserves pause; restart after resume auto-tracks. +- [ ] Sampling/Home/pet intervals remain 5 seconds. +- [ ] First sample remains baseline-only. +- [ ] Pet counters remain `LEARN / REST`; mood shows active vs paused. +- [ ] Recovered Home error clears only if still the active Home-owned error. +- [ ] Final typecheck/build/Rust gates pass. +- [ ] Final Windows packaging produces NSIS + MSI. +- [ ] Fresh-install and upgrade manual acceptance pass before PR/release promotion. From 97406b116efda2dbd55206ce612a44e6bcd26951 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:56:02 +0800 Subject: [PATCH 033/117] test(db): specify first-run tracking defaults --- src-tauri/src/db/tests.rs | 69 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/src-tauri/src/db/tests.rs b/src-tauri/src/db/tests.rs index bde3cf0..8b30853 100644 --- a/src-tauri/src/db/tests.rs +++ b/src-tauri/src/db/tests.rs @@ -80,6 +80,23 @@ fn fresh_file_database_initialization_seeds_schema_and_defaults_and_reopens() { .expect("read default browser mode"); assert_eq!(browser_mode, "BLUR"); + let onboarding: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'onboarding_completed'", + [], + |row| row.get(0), + ) + .expect("read onboarding default"); + let auto_capture: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", + [], + |row| row.get(0), + ) + .expect("read auto capture default"); + assert_eq!(onboarding, "false"); + assert_eq!(auto_capture, "false"); + let code_rule: String = conn .query_row( "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", @@ -162,6 +179,41 @@ fn database_initialization_is_idempotent_and_preserves_user_values() { remove_sqlite_files(&path); } +#[test] +fn database_initialization_preserves_persisted_tracking_pause() { + let path = temp_db_path("tracking-pause"); + remove_sqlite_files(&path); + let conn = Connection::open(&path).expect("open sqlite file"); + + super::migrations::initialize_connection(&conn).expect("initialize fresh database"); + conn.execute( + "UPDATE app_config SET value = 'true' WHERE key = 'onboarding_completed'", + [], + ) + .expect("mark onboarding complete"); + conn.execute( + "UPDATE app_config SET value = 'false' WHERE key = 'auto_capture_enabled'", + [], + ) + .expect("persist capture pause"); + + super::migrations::initialize_connection(&conn).expect("reinitialize database"); + + let state: (String, String) = conn + .query_row( + "SELECT + (SELECT value FROM app_config WHERE key = 'onboarding_completed'), + (SELECT value FROM app_config WHERE key = 'auto_capture_enabled')", + [], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .expect("read persisted tracking state"); + assert_eq!(state, ("true".to_string(), "false".to_string())); + + drop(conn); + remove_sqlite_files(&path); +} + #[test] fn database_initialization_repairs_only_known_mojibake_root_names() { let path = temp_db_path("root-name-repair"); @@ -240,6 +292,23 @@ fn legacy_schema_is_upgraded_without_losing_existing_rows() { assert!(column_exists(&conn, "reminders", "weekly_days")); assert!(column_exists(&conn, "reminders", "sort_order")); + let onboarding: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'onboarding_completed'", + [], + |row| row.get(0), + ) + .expect("read migrated onboarding state"); + let auto_capture: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = 'auto_capture_enabled'", + [], + |row| row.get(0), + ) + .expect("read migrated capture state"); + assert_eq!(onboarding, "true"); + assert_eq!(auto_capture, "true"); + let mapped_type: String = conn .query_row( "SELECT mapped_type FROM app_rules WHERE process_name = 'legacy.exe'", From 9920dd48d252872fb4ea36d1e1c23739868d518c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:59:32 +0800 Subject: [PATCH 034/117] feat(db): persist first-run tracking defaults --- src-tauri/src/db/migrations.rs | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src-tauri/src/db/migrations.rs b/src-tauri/src/db/migrations.rs index 277b0b4..1d14263 100644 --- a/src-tauri/src/db/migrations.rs +++ b/src-tauri/src/db/migrations.rs @@ -174,7 +174,23 @@ pub fn ensure_heatmap_snapshot_table(conn: &Connection) -> Result<(), String> { Ok(()) } +fn has_recognizable_timeprism_schema(conn: &Connection) -> Result { + let count: i64 = conn + .query_row( + "SELECT COUNT(*) + FROM sqlite_master + WHERE type = 'table' + AND name IN ('categories', 'task_sessions', 'app_usage_logs', 'app_rules', 'app_config', 'reminders')", + [], + |row| row.get(0), + ) + .map_err(|e| format!("failed to inspect existing TimePrism schema: {e}"))?; + Ok(count > 0) +} + pub(super) fn initialize_connection(conn: &Connection) -> Result<(), String> { + let was_existing_timeprism_db = has_recognizable_timeprism_schema(conn)?; + conn.pragma_update(None, "foreign_keys", "ON") .map_err(|e| format!("failed to enable foreign keys: {e}"))?; @@ -319,6 +335,25 @@ pub(super) fn initialize_connection(conn: &Connection) -> Result<(), String> { .map_err(|e| format!("failed to seed app config {key}: {e}"))?; } + let tracking_defaults = if was_existing_timeprism_db { + [ + ("onboarding_completed", "true"), + ("auto_capture_enabled", "true"), + ] + } else { + [ + ("onboarding_completed", "false"), + ("auto_capture_enabled", "false"), + ] + }; + for (key, value) in tracking_defaults { + conn.execute( + "INSERT OR IGNORE INTO app_config (key, value) VALUES (?1, ?2)", + params![key, value], + ) + .map_err(|e| format!("failed to seed tracking config {key}: {e}"))?; + } + let default_whitelist = [ "code.exe", "pycharm64.exe", From 8feb50df1f2a1b38a91d8ffbce655086c7f65901 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:02:07 +0800 Subject: [PATCH 035/117] feat(tracking): add tracking state contract --- src-tauri/src/domain/tracking.rs | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 src-tauri/src/domain/tracking.rs diff --git a/src-tauri/src/domain/tracking.rs b/src-tauri/src/domain/tracking.rs new file mode 100644 index 0000000..2f12fea --- /dev/null +++ b/src-tauri/src/domain/tracking.rs @@ -0,0 +1,7 @@ +use serde::Serialize; + +#[derive(Clone, Debug, PartialEq, Eq, Serialize)] +pub struct TrackingState { + pub onboarding_completed: bool, + pub auto_capture_enabled: bool, +} From 38001ce7297df5b22d745070c61d892f1932aea6 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:02:17 +0800 Subject: [PATCH 036/117] test(tracking): specify persisted state invariants --- src-tauri/src/services/tracking.rs | 57 ++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 src-tauri/src/services/tracking.rs diff --git a/src-tauri/src/services/tracking.rs b/src-tauri/src/services/tracking.rs new file mode 100644 index 0000000..052343f --- /dev/null +++ b/src-tauri/src/services/tracking.rs @@ -0,0 +1,57 @@ +#[cfg(test)] +mod tests { + use rusqlite::{params, Connection}; + + use super::{ + complete_onboarding_entry, get_tracking_state_entry, set_auto_capture_enabled_entry, + }; + + fn tracking_conn(onboarding: bool, enabled: bool) -> Connection { + let conn = Connection::open_in_memory().expect("open tracking test db"); + conn.execute_batch( + "CREATE TABLE app_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);", + ) + .expect("create app_config"); + for (key, value) in [ + ("onboarding_completed", onboarding.to_string()), + ("auto_capture_enabled", enabled.to_string()), + ] { + conn.execute( + "INSERT INTO app_config (key, value) VALUES (?1, ?2)", + params![key, value], + ) + .expect("seed tracking state"); + } + conn + } + + #[test] + fn completing_onboarding_atomically_enables_capture() { + let conn = tracking_conn(false, false); + let state = complete_onboarding_entry(&conn).expect("complete onboarding"); + assert!(state.onboarding_completed); + assert!(state.auto_capture_enabled); + assert_eq!(get_tracking_state_entry(&conn).unwrap(), state); + } + + #[test] + fn pause_and_resume_persist_after_onboarding() { + let conn = tracking_conn(true, true); + assert!(!set_auto_capture_enabled_entry(&conn, false) + .unwrap() + .auto_capture_enabled); + assert!(set_auto_capture_enabled_entry(&conn, true) + .unwrap() + .auto_capture_enabled); + } + + #[test] + fn enabling_capture_before_onboarding_is_rejected() { + let conn = tracking_conn(false, false); + let err = set_auto_capture_enabled_entry(&conn, true).unwrap_err(); + assert!(err.contains("onboarding")); + assert!(!get_tracking_state_entry(&conn) + .unwrap() + .auto_capture_enabled); + } +} From 8d8e34648f7514afa565cf8fa7bfd17cf91e0e1e Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:02:27 +0800 Subject: [PATCH 037/117] feat(tracking): expose tracking domain --- src-tauri/src/domain/mod.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src-tauri/src/domain/mod.rs b/src-tauri/src/domain/mod.rs index 34e65ea..08edc15 100644 --- a/src-tauri/src/domain/mod.rs +++ b/src-tauri/src/domain/mod.rs @@ -3,4 +3,5 @@ pub mod idle; pub mod privacy; pub mod reminders; pub mod rules; +pub mod tracking; pub mod window; From 11ee4a934b65880ef8478f77f296229840077ca6 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:02:37 +0800 Subject: [PATCH 038/117] test(tracking): compile tracking invariant tests --- src-tauri/src/services/mod.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src-tauri/src/services/mod.rs b/src-tauri/src/services/mod.rs index 6b2c937..be13c28 100644 --- a/src-tauri/src/services/mod.rs +++ b/src-tauri/src/services/mod.rs @@ -10,5 +10,6 @@ pub mod rules; pub mod sessions; pub mod startup; pub mod time; +pub mod tracking; pub mod usage; pub mod window; From 6b64c27124c3c6aeb56698f10f547c00c3678957 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:06:03 +0800 Subject: [PATCH 039/117] feat(tracking): add persisted tracking state invariant --- src-tauri/src/services/tracking.rs | 89 ++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/src-tauri/src/services/tracking.rs b/src-tauri/src/services/tracking.rs index 052343f..1b0a96b 100644 --- a/src-tauri/src/services/tracking.rs +++ b/src-tauri/src/services/tracking.rs @@ -1,3 +1,79 @@ +use rusqlite::{params, Connection}; + +use crate::domain::tracking::TrackingState; + +fn read_bool_config(conn: &Connection, key: &str) -> Result { + let value: String = conn + .query_row( + "SELECT value FROM app_config WHERE key = ?1", + [key], + |row| row.get(0), + ) + .map_err(|e| format!("failed to read tracking config {key}: {e}"))?; + + match value.trim().to_lowercase().as_str() { + "true" => Ok(true), + "false" => Ok(false), + other => Err(format!("invalid boolean tracking config {key}: {other}")), + } +} + +pub(crate) fn get_tracking_state_entry(conn: &Connection) -> Result { + Ok(TrackingState { + onboarding_completed: read_bool_config(conn, "onboarding_completed")?, + auto_capture_enabled: read_bool_config(conn, "auto_capture_enabled")?, + }) +} + +pub(crate) fn complete_onboarding_entry(conn: &Connection) -> Result { + let tx = conn + .unchecked_transaction() + .map_err(|e| format!("failed to begin onboarding transaction: {e}"))?; + + let changed = tx + .execute( + "UPDATE app_config + SET value = 'true' + WHERE key IN ('onboarding_completed', 'auto_capture_enabled')", + [], + ) + .map_err(|e| format!("failed to complete onboarding: {e}"))?; + if changed != 2 { + return Err(format!( + "failed to complete onboarding: expected 2 tracking config rows, updated {changed}" + )); + } + + tx.commit() + .map_err(|e| format!("failed to commit onboarding: {e}"))?; + + get_tracking_state_entry(conn) +} + +pub(crate) fn set_auto_capture_enabled_entry( + conn: &Connection, + enabled: bool, +) -> Result { + let current = get_tracking_state_entry(conn)?; + if enabled && !current.onboarding_completed { + return Err("cannot enable auto capture before onboarding is complete".to_string()); + } + + let changed = conn + .execute( + "UPDATE app_config SET value = ?1 WHERE key = 'auto_capture_enabled'", + params![enabled.to_string()], + ) + .map_err(|e| format!("failed to update auto capture state: {e}"))?; + if changed != 1 { + return Err(format!( + "failed to update auto capture state: expected 1 config row, updated {changed}" + )); + } + + get_tracking_state_entry(conn) +} + #[cfg(test)] mod tests { use rusqlite::{params, Connection}; @@ -54,4 +130,17 @@ mod tests { .unwrap() .auto_capture_enabled); } + + #[test] + fn completing_onboarding_rejects_missing_tracking_key() { + let conn = tracking_conn(false, false); + conn.execute( + "DELETE FROM app_config WHERE key = 'auto_capture_enabled'", + [], + ) + .expect("remove tracking key"); + + let err = complete_onboarding_entry(&conn).unwrap_err(); + assert!(err.contains("expected 2 tracking config rows")); + } } From 7676da03f69b4a464e6890d69011c68ff3dc0776 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:07:43 +0800 Subject: [PATCH 040/117] test(startup): require manual product window creation --- src-tauri/src/services/window_config_tests.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 src-tauri/src/services/window_config_tests.rs diff --git a/src-tauri/src/services/window_config_tests.rs b/src-tauri/src/services/window_config_tests.rs new file mode 100644 index 0000000..98b489e --- /dev/null +++ b/src-tauri/src/services/window_config_tests.rs @@ -0,0 +1,19 @@ +#[test] +fn configured_product_windows_require_manual_creation() { + let config: serde_json::Value = serde_json::from_str(include_str!("../../tauri.conf.json")) + .expect("parse tauri config"); + let windows = config["app"]["windows"] + .as_array() + .expect("window config array"); + + for label in ["main", "pet", "pet-panel"] { + let item = windows + .iter() + .find(|item| item["label"] == label) + .unwrap_or_else(|| panic!("missing window config {label}")); + assert_eq!( + item["create"], false, + "{label} must not auto-create before DB init" + ); + } +} From 9ba30c5805e74dc603603e06bf9c0b09928b4ff6 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:07:55 +0800 Subject: [PATCH 041/117] test(startup): compile window creation gate --- src-tauri/src/services/mod.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src-tauri/src/services/mod.rs b/src-tauri/src/services/mod.rs index be13c28..ac86113 100644 --- a/src-tauri/src/services/mod.rs +++ b/src-tauri/src/services/mod.rs @@ -13,3 +13,6 @@ pub mod time; pub mod tracking; pub mod usage; pub mod window; + +#[cfg(test)] +mod window_config_tests; From 705a997042b01c484038e415136ba8807eb504f9 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:10:39 +0800 Subject: [PATCH 042/117] fix(startup): require manual webview creation --- src-tauri/tauri.conf.json | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index 93b7bd6..d67ad28 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -4,10 +4,10 @@ "version": "0.1.0", "identifier": "com.air.timeprism", "build": { - "beforeDevCommand": "pnpm vite", - "devUrl": "http://localhost:1420", - "beforeBuildCommand": "pnpm build", - "frontendDist": "../dist" + "beforeDevCommand": "pnpm vite", + "devUrl": "http://localhost:1420", + "beforeBuildCommand": "pnpm build", + "frontendDist": "../dist" }, "app": { "windows": [ @@ -18,7 +18,8 @@ "height": 900, "minWidth": 888, "minHeight": 900, - "visible": false + "visible": false, + "create": false }, { "label": "pet", @@ -31,7 +32,8 @@ "resizable": false, "alwaysOnTop": true, "skipTaskbar": true, - "shadow": false + "shadow": false, + "create": false }, { "label": "pet-panel", @@ -45,7 +47,8 @@ "alwaysOnTop": true, "skipTaskbar": true, "shadow": false, - "visible": false + "visible": false, + "create": false } ], "security": { From 895300a9432190833a45898b93919862b4f078af Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:10:46 +0800 Subject: [PATCH 043/117] feat(startup): add configured window factory --- src-tauri/src/services/window_factory.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src-tauri/src/services/window_factory.rs diff --git a/src-tauri/src/services/window_factory.rs b/src-tauri/src/services/window_factory.rs new file mode 100644 index 0000000..2ed74f9 --- /dev/null +++ b/src-tauri/src/services/window_factory.rs @@ -0,0 +1,23 @@ +use tauri::{AppHandle, Manager, WebviewWindow}; + +pub(crate) fn create_configured_window( + app: &AppHandle, + label: &str, +) -> Result { + if let Some(existing) = app.get_webview_window(label) { + return Ok(existing); + } + + let config = app + .config() + .app + .windows + .iter() + .find(|item| item.label == label) + .ok_or_else(|| format!("window config not found: {label}"))?; + + tauri::WebviewWindowBuilder::from_config(app, config) + .map_err(|e| format!("failed to build window config {label}: {e}"))? + .build() + .map_err(|e| format!("failed to create configured window {label}: {e}")) +} From d6fe7c36bc46d7b7e8af165e2446d21572d15a12 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:10:56 +0800 Subject: [PATCH 044/117] feat(startup): expose configured window factory --- src-tauri/src/services/mod.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src-tauri/src/services/mod.rs b/src-tauri/src/services/mod.rs index ac86113..278effe 100644 --- a/src-tauri/src/services/mod.rs +++ b/src-tauri/src/services/mod.rs @@ -13,6 +13,7 @@ pub mod time; pub mod tracking; pub mod usage; pub mod window; +pub mod window_factory; #[cfg(test)] mod window_config_tests; From e905a1d8c2c193d0c786f40ac39e92b02b292821 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:11:53 +0800 Subject: [PATCH 045/117] fix(startup): initialize database before webviews --- src-tauri/src/lib.rs | 103 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 82 insertions(+), 21 deletions(-) diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index c61906d..fdbc156 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -17,6 +17,7 @@ use domain::reminders::{ ReminderEntry, SaveReminderInput, SetReminderDoneInput, SetReminderOrderInput, }; use domain::rules::{AppRuleEntry, DeviationCheck, PendingRuleProcess, SaveAppRuleInput}; +use domain::tracking::TrackingState; use domain::window::{ForegroundCaptureDiagnostic, PetWindowSettleResult, SettlePetWindowInput}; use services::analytics::{ heatmap_goal_seconds_setting, learn_heatmap, list_recent_log_entries, @@ -25,6 +26,7 @@ use services::analytics::{ usage_stack, }; use services::categories::{create_category_entry, list_category_entries}; +use services::focus::{check_focus_deviation_state, snooze_focus_guard_state}; use services::foreground as foreground_service; use services::privacy::{ get_privacy_settings_entry, list_whitelist_entries, set_whitelist_item_entry, @@ -35,13 +37,14 @@ use services::reminders::{ set_reminder_done_entry, set_reminder_order_entries, snooze_reminder_entry, }; use services::rules::{list_app_rule_entries, list_pending_rule_process_entries, save_app_rule_entry}; -use services::focus::{ - check_focus_deviation_state, snooze_focus_guard_state, -}; use services::sessions::{start_session_entry, stop_active_session_entry}; use services::startup::{get_auto_start_enabled_state, set_auto_start_enabled_state}; +use services::tracking::{ + complete_onboarding_entry, get_tracking_state_entry, set_auto_capture_enabled_entry, +}; use services::usage::append_usage_log_record; use services::window as window_service; +use services::window_factory::create_configured_window; #[tauri::command(async)] fn list_reminders( @@ -86,7 +89,7 @@ fn set_reminder_order(app: AppHandle, input: SetReminderOrderInput) -> Result) -> Result { let conn = open_connection(&app)?; - snooze_reminder_entry(&conn, id, snooze_seconds) + snooze_reminder_entry(&conn, id) } #[tauri::command] @@ -122,7 +125,13 @@ fn append_app_usage_log( duration_ms: i64, ) -> Result { let conn = open_connection(&app)?; - let (stored, _) = append_usage_log_record(&conn, &process_name, &window_title, start_timestamp, duration_ms)?; + let (stored, _) = append_usage_log_record( + &conn, + &process_name, + &window_title, + start_timestamp, + duration_ms, + )?; Ok(stored) } @@ -173,7 +182,10 @@ fn list_app_rules(app: AppHandle, limit: Option) -> Result) -> Result, String> { +fn list_pending_rule_processes( + app: AppHandle, + limit: Option, +) -> Result, String> { let conn = open_connection(&app)?; let cap = limit.unwrap_or(10).clamp(1, 200); list_pending_rule_process_entries(&conn, cap) @@ -277,6 +289,24 @@ fn set_auto_start_enabled(enabled: bool) -> Result { set_auto_start_enabled_state(enabled) } +#[tauri::command(async)] +fn get_tracking_state(app: AppHandle) -> Result { + let conn = open_connection(&app)?; + get_tracking_state_entry(&conn) +} + +#[tauri::command] +fn complete_tracking_onboarding(app: AppHandle) -> Result { + let conn = open_connection(&app)?; + complete_onboarding_entry(&conn) +} + +#[tauri::command] +fn set_auto_capture_enabled(app: AppHandle, enabled: bool) -> Result { + let conn = open_connection(&app)?; + set_auto_capture_enabled_entry(&conn, enabled) +} + #[tauri::command] fn list_whitelist(app: AppHandle) -> Result, String> { let conn = open_connection(&app)?; @@ -289,8 +319,16 @@ fn set_whitelist_item(app: AppHandle, input: SetWhitelistItemInput) -> Result<() set_whitelist_item_entry(&conn, input) } -#[tauri::command] +#[tauri::command(async)] fn summon_pet_window(app: AppHandle) -> Result<(), String> { + let conn = open_connection(&app)?; + let tracking = get_tracking_state_entry(&conn)?; + drop(conn); + if !tracking.onboarding_completed { + return Err("cannot show pet before tracking onboarding is complete".to_string()); + } + + create_configured_window(&app, "pet")?; window_service::summon_pet_window(&app) } @@ -367,32 +405,52 @@ pub fn run() { tauri::Builder::default() .plugin(tauri_plugin_opener::init()) .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| { - if let Some(main_window) = app.get_webview_window("main") { - let _ = main_window.show(); - let _ = main_window.unminimize(); - let _ = main_window.set_focus(); - } window_service::reveal_main_window(app); })) .plugin( tauri_plugin_global_shortcut::Builder::new() .with_handler(|app, _shortcut, event| { - if event.state == ShortcutState::Pressed { - let _ = window_service::summon_pet_window(app); + if event.state != ShortcutState::Pressed { + return; } + + let handle = app.clone(); + std::thread::spawn(move || { + let tracking = open_connection(&handle) + .and_then(|conn| get_tracking_state_entry(&conn)); + match tracking { + Ok(state) if state.onboarding_completed => { + if let Err(err) = create_configured_window(&handle, "pet") + .and_then(|_| window_service::summon_pet_window(&handle)) + { + eprintln!("global shortcut warning: failed to summon pet: {err}"); + } + } + Ok(_) => {} + Err(err) => { + eprintln!("global shortcut warning: failed to read tracking state: {err}"); + } + } + }); }) .build(), ) .setup(|app| { - if let Err(err) = init_database(app.handle()) { - eprintln!("database init warning: {err}"); - } + init_database(app.handle()).map_err(std::io::Error::other)?; - if let Some(main_window) = app.get_webview_window("main") { - window_service::set_main_close_behavior(&main_window); - } + let conn = open_connection(app.handle()).map_err(std::io::Error::other)?; + let tracking = get_tracking_state_entry(&conn).map_err(std::io::Error::other)?; + drop(conn); + + let main_window = create_configured_window(app.handle(), "main") + .map_err(std::io::Error::other)?; + window_service::set_main_close_behavior(&main_window); - let _ = window_service::ensure_pet_window_position(app.handle(), true); + if tracking.onboarding_completed { + create_configured_window(app.handle(), "pet").map_err(std::io::Error::other)?; + window_service::ensure_pet_window_position(app.handle(), true) + .map_err(std::io::Error::other)?; + } let shortcut = Shortcut::new(Some(Modifiers::CONTROL | Modifiers::SHIFT), Code::KeyT); if let Err(err) = app.global_shortcut().register(shortcut) { @@ -437,6 +495,9 @@ pub fn run() { update_privacy_settings, get_auto_start_enabled, set_auto_start_enabled, + get_tracking_state, + complete_tracking_onboarding, + set_auto_capture_enabled, list_whitelist, set_whitelist_item, show_main_window, From 4490e50353a74ec7d64b9468d0957d1a2e08e160 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:14:46 +0800 Subject: [PATCH 046/117] fix(reminders): preserve snooze duration argument --- src-tauri/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index fdbc156..5c94ca6 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -89,7 +89,7 @@ fn set_reminder_order(app: AppHandle, input: SetReminderOrderInput) -> Result) -> Result { let conn = open_connection(&app)?; - snooze_reminder_entry(&conn, id) + snooze_reminder_entry(&conn, id, snooze_seconds) } #[tauri::command] From 30999d90d57f8aa41aa5fd2bc1e0aeacc34c4091 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:27:23 +0800 Subject: [PATCH 047/117] test(frontend): add tracking API type contract --- src/api/tracking.contract.ts | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 src/api/tracking.contract.ts diff --git a/src/api/tracking.contract.ts b/src/api/tracking.contract.ts new file mode 100644 index 0000000..41a66ab --- /dev/null +++ b/src/api/tracking.contract.ts @@ -0,0 +1,16 @@ +import { + completeTrackingOnboarding, + getTrackingState, + setAutoCaptureEnabled, + type TrackingState, +} from "../api"; + +type ReadTrackingState = () => Promise; +type CompleteTrackingOnboarding = () => Promise; +type SetAutoCaptureEnabled = (enabled: boolean) => Promise; + +export const trackingApiContract = { + get: getTrackingState satisfies ReadTrackingState, + completeOnboarding: completeTrackingOnboarding satisfies CompleteTrackingOnboarding, + setAutoCaptureEnabled: setAutoCaptureEnabled satisfies SetAutoCaptureEnabled, +}; From 24e53f81cbc8ce9b624a19fd0d2b3b792c2c8ccf Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:27:35 +0800 Subject: [PATCH 048/117] test(frontend): move capture policy out of sampler contract --- src/composables/useAutoCaptureSampler.contract.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 src/composables/useAutoCaptureSampler.contract.ts diff --git a/src/composables/useAutoCaptureSampler.contract.ts b/src/composables/useAutoCaptureSampler.contract.ts new file mode 100644 index 0000000..49deabc --- /dev/null +++ b/src/composables/useAutoCaptureSampler.contract.ts @@ -0,0 +1,13 @@ +import { ref } from "vue"; +import { useAutoCaptureSampler } from "./useAutoCaptureSampler"; + +const sampler = useAutoCaptureSampler({ + autoCaptureFeedback: ref(""), + tx: (_zh, en) => en, + intervalMs: 5000, +}); + +export const autoCaptureSamplerContract = sampler satisfies { + startAutoCaptureSampler: () => void; + stopAutoCaptureSampler: () => void; +}; From 75085a33caba537aeaa6ed1ce595875ae5cd9fb3 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:29:22 +0800 Subject: [PATCH 049/117] feat(frontend): add persisted tracking state type --- src/api/types.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/api/types.ts b/src/api/types.ts index d162f94..4619393 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -64,6 +64,11 @@ export type PrivacySettings = { whitelist_only_enabled: boolean; }; +export type TrackingState = { + onboarding_completed: boolean; + auto_capture_enabled: boolean; +}; + export type ForegroundCaptureDiagnostic = { id: number; captured_at_ms: number; From 89bfaccefcc7801f145c08c025a7ff24907182bd Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:29:32 +0800 Subject: [PATCH 050/117] feat(frontend): add tracking command client --- src/api/commands/tracking.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 src/api/commands/tracking.ts diff --git a/src/api/commands/tracking.ts b/src/api/commands/tracking.ts new file mode 100644 index 0000000..026bc1c --- /dev/null +++ b/src/api/commands/tracking.ts @@ -0,0 +1,14 @@ +import { invokeCommand } from "../client"; +import type { TrackingState } from "../types"; + +export function getTrackingState(): Promise { + return invokeCommand("get_tracking_state"); +} + +export function completeTrackingOnboarding(): Promise { + return invokeCommand("complete_tracking_onboarding"); +} + +export function setAutoCaptureEnabled(enabled: boolean): Promise { + return invokeCommand("set_auto_capture_enabled", { enabled }); +} From 934c2e900f3f95f8851c9215261dc40c947d0d79 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:29:45 +0800 Subject: [PATCH 051/117] feat(frontend): export tracking commands --- src/api/commands/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/api/commands/index.ts b/src/api/commands/index.ts index 8c8a3d2..611d3c3 100644 --- a/src/api/commands/index.ts +++ b/src/api/commands/index.ts @@ -6,4 +6,5 @@ export * from "./reminders"; export * from "./rules"; export * from "./sessions"; export * from "./startup"; +export * from "./tracking"; export * from "./usage"; From 7a3dc9b081717226e6d4a51fbe4b7d9ba25ce549 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:29:58 +0800 Subject: [PATCH 052/117] feat(frontend): export tracking state --- src/api.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/api.ts b/src/api.ts index b7a3d90..abe2f46 100644 --- a/src/api.ts +++ b/src/api.ts @@ -14,6 +14,7 @@ export type { Reminder, TodaySummary, TopApp, + TrackingState, UsageRootFilter, UsageStackDay, UsageStackSegment, From cf3071fdbe5219d770a02b499c7541cbacdeaee4 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:30:11 +0800 Subject: [PATCH 053/117] refactor(frontend): make capture sampler policy-free --- src/composables/useAutoCaptureSampler.ts | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/composables/useAutoCaptureSampler.ts b/src/composables/useAutoCaptureSampler.ts index 9b1e992..d28132e 100644 --- a/src/composables/useAutoCaptureSampler.ts +++ b/src/composables/useAutoCaptureSampler.ts @@ -4,14 +4,12 @@ import { captureForegroundOnce } from "../api"; type TranslateFn = (zh: string, en: string) => string; type AutoCaptureSamplerOptions = { - autoCaptureEnabled: Ref; autoCaptureFeedback: Ref; tx: TranslateFn; intervalMs?: number; }; export function useAutoCaptureSampler({ - autoCaptureEnabled, autoCaptureFeedback, tx, intervalMs = 5000, @@ -19,10 +17,6 @@ export function useAutoCaptureSampler({ let captureTimer: number | null = null; function sampleAutoCapture() { - if (!autoCaptureEnabled.value) { - return; - } - void captureForegroundOnce(intervalMs) .then((stored) => { autoCaptureFeedback.value = stored From 75b484fad73cb3213a9451568030414e4d8f3dae Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:32:46 +0800 Subject: [PATCH 054/117] refactor(frontend): keep legacy sampler option inert --- src/composables/useAutoCaptureSampler.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/composables/useAutoCaptureSampler.ts b/src/composables/useAutoCaptureSampler.ts index d28132e..709c472 100644 --- a/src/composables/useAutoCaptureSampler.ts +++ b/src/composables/useAutoCaptureSampler.ts @@ -7,6 +7,7 @@ type AutoCaptureSamplerOptions = { autoCaptureFeedback: Ref; tx: TranslateFn; intervalMs?: number; + autoCaptureEnabled?: Ref; }; export function useAutoCaptureSampler({ From 3ff8317e88dea22ff988a37c9c74a797d5863ea5 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:35:49 +0800 Subject: [PATCH 055/117] test(frontend): define tracking runtime contract --- src/composables/useTrackingState.contract.ts | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 src/composables/useTrackingState.contract.ts diff --git a/src/composables/useTrackingState.contract.ts b/src/composables/useTrackingState.contract.ts new file mode 100644 index 0000000..ab58af0 --- /dev/null +++ b/src/composables/useTrackingState.contract.ts @@ -0,0 +1,17 @@ +import type { Ref } from "vue"; +import { useTrackingState } from "./useTrackingState"; + +const tracking = useTrackingState({ + setErrorMessage: (_error: unknown) => {}, +}); + +export const trackingStateContract = tracking satisfies { + trackingReady: Readonly>; + onboardingCompleted: Readonly>; + autoCaptureEnabled: Readonly>; + captureShouldRun: Readonly>; + trackingActionLoading: Readonly>; + loadTrackingState: () => Promise; + completeOnboarding: () => Promise; + persistAutoCaptureEnabled: (enabled: boolean) => Promise; +}; From df250fd6786909c35df8829535b91d3b927eac01 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:36:02 +0800 Subject: [PATCH 056/117] test(frontend): require persisted guard capture toggle --- src/composables/useGuardData.contract.ts | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 src/composables/useGuardData.contract.ts diff --git a/src/composables/useGuardData.contract.ts b/src/composables/useGuardData.contract.ts new file mode 100644 index 0000000..7dc48c0 --- /dev/null +++ b/src/composables/useGuardData.contract.ts @@ -0,0 +1,18 @@ +import { ref } from "vue"; +import { useGuardData } from "./useGuardData"; + +const autoCaptureEnabled = ref(false); + +const guard = useGuardData({ + tx: (_zh, en) => en, + mappedTypeText: (mappedType) => mappedType, + refreshData: async () => {}, + setErrorMessage: (_error: unknown) => {}, + autoCaptureEnabled, + persistAutoCaptureEnabled: async (_enabled: boolean) => {}, +}); + +export const guardTrackingContract = guard satisfies { + autoCaptureEnabled: Readonly; + onAutoCaptureToggle: (event: Event) => Promise; +}; From b6428b4cae11a536d2c80527b84d2869c67b30fc Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:36:14 +0800 Subject: [PATCH 057/117] test(frontend): require tracking gate before main runtime --- .../useMainWindowLifecycle.contract.ts | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 src/composables/useMainWindowLifecycle.contract.ts diff --git a/src/composables/useMainWindowLifecycle.contract.ts b/src/composables/useMainWindowLifecycle.contract.ts new file mode 100644 index 0000000..09a2b50 --- /dev/null +++ b/src/composables/useMainWindowLifecycle.contract.ts @@ -0,0 +1,19 @@ +import { useMainWindowLifecycle } from "./useMainWindowLifecycle"; + +export const mainWindowLifecycleContract: Parameters[0] = { + initLocale: () => {}, + initThemeModeSafely: () => {}, + loadTrackingState: async () => {}, + loadHeatmapGoalSecondsSetting: async () => {}, + resetGuardFeedback: () => {}, + resetPrivacyFeedback: () => {}, + refreshHomeData: async () => {}, + startSettingsWarmup: () => {}, + startMainRefreshPolling: () => {}, + startInsightsSectionNavigationListener: async () => {}, + stopMainRefreshPolling: () => {}, + stopAutoCaptureSampler: () => {}, + cleanupSettingsWarmup: () => {}, + cleanupInsightsSectionNavigation: () => {}, + cleanupHeatmapGoalSetting: () => {}, +}; From 3fae87e30812af1aa3f9d4d0280b3e82d22f6ca4 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:40:07 +0800 Subject: [PATCH 058/117] feat(frontend): centralize persisted tracking state --- src/composables/useTrackingState.ts | 84 +++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 src/composables/useTrackingState.ts diff --git a/src/composables/useTrackingState.ts b/src/composables/useTrackingState.ts new file mode 100644 index 0000000..01d64c1 --- /dev/null +++ b/src/composables/useTrackingState.ts @@ -0,0 +1,84 @@ +import { computed, ref } from "vue"; +import { + completeTrackingOnboarding, + getTrackingState, + setAutoCaptureEnabled, + type TrackingState, +} from "../api"; + +type UseTrackingStateOptions = { + setErrorMessage: (error: unknown) => void; +}; + +export function useTrackingState({ setErrorMessage }: UseTrackingStateOptions) { + const trackingState = ref(null); + const trackingReady = ref(false); + const trackingActionLoading = ref(false); + + const onboardingCompleted = computed( + () => trackingState.value?.onboarding_completed === true, + ); + const autoCaptureEnabled = computed( + () => trackingState.value?.auto_capture_enabled === true, + ); + const captureShouldRun = computed( + () => + trackingReady.value && + onboardingCompleted.value && + autoCaptureEnabled.value, + ); + + async function loadTrackingState(): Promise { + try { + trackingState.value = await getTrackingState(); + trackingReady.value = true; + } catch (error) { + trackingReady.value = false; + setErrorMessage(error); + } + } + + async function completeOnboarding(): Promise { + if (trackingActionLoading.value) { + return; + } + + trackingActionLoading.value = true; + try { + trackingState.value = await completeTrackingOnboarding(); + trackingReady.value = true; + } catch (error) { + setErrorMessage(error); + throw error; + } finally { + trackingActionLoading.value = false; + } + } + + async function persistAutoCaptureEnabled(enabled: boolean): Promise { + if (trackingActionLoading.value) { + return; + } + + trackingActionLoading.value = true; + try { + trackingState.value = await setAutoCaptureEnabled(enabled); + } catch (error) { + setErrorMessage(error); + throw error; + } finally { + trackingActionLoading.value = false; + } + } + + return { + trackingReady, + onboardingCompleted, + autoCaptureEnabled, + captureShouldRun, + trackingActionLoading, + loadTrackingState, + completeOnboarding, + persistAutoCaptureEnabled, + }; +} From f456736883672af399e53e84a16454b1c7e512cc Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:40:41 +0800 Subject: [PATCH 059/117] feat(frontend): persist focus guard capture toggle --- src/composables/useGuardData.ts | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/composables/useGuardData.ts b/src/composables/useGuardData.ts index c37d432..c0da770 100644 --- a/src/composables/useGuardData.ts +++ b/src/composables/useGuardData.ts @@ -1,4 +1,4 @@ -import { computed, ref } from "vue"; +import { computed, ref, type Ref } from "vue"; import { getIdleMemoryState, listAppRules, @@ -56,6 +56,8 @@ type UseGuardDataOptions = { mappedTypeText: (mappedType: RuleMappedType) => string; refreshData: () => Promise; setErrorMessage: (error: unknown) => void; + autoCaptureEnabled: Readonly>; + persistAutoCaptureEnabled: (enabled: boolean) => Promise; }; export function useGuardData({ @@ -63,9 +65,10 @@ export function useGuardData({ mappedTypeText, refreshData, setErrorMessage, + autoCaptureEnabled, + persistAutoCaptureEnabled, }: UseGuardDataOptions) { const loadingGuard = ref(false); - const autoCaptureEnabled = ref(true); const autoCaptureFeedback = ref(defaultGuardAutoCaptureFeedback(tx)); const guardFeedback = ref(defaultGuardCheckFeedback(tx)); const guardFeedbackType = ref("info"); @@ -215,8 +218,20 @@ export function useGuardData({ ); } - function onAutoCaptureToggle(event: Event) { - autoCaptureEnabled.value = guardCheckedFromEvent(event); + async function onAutoCaptureToggle(event: Event): Promise { + const enabled = guardCheckedFromEvent(event); + try { + await persistAutoCaptureEnabled(enabled); + autoCaptureFeedback.value = enabled + ? tx("自动采样已恢复。", "Auto capture resumed.") + : tx("自动采样已暂停。", "Auto capture paused."); + } catch (e) { + setErrorMessage(e); + autoCaptureFeedback.value = tx( + `切换自动采样失败：${e}`, + `Failed to change auto capture: ${e}`, + ); + } } function onIdleRememberChoiceChange(event: Event) { From 7a21d918324329d7116585a3bc1de0b72acbdb3c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:41:00 +0800 Subject: [PATCH 060/117] feat(frontend): load persisted tracking before runtime startup --- src/composables/useMainWindowLifecycle.ts | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/composables/useMainWindowLifecycle.ts b/src/composables/useMainWindowLifecycle.ts index 3354ccc..30f92ae 100644 --- a/src/composables/useMainWindowLifecycle.ts +++ b/src/composables/useMainWindowLifecycle.ts @@ -3,13 +3,13 @@ import { onMounted, onUnmounted } from "vue"; type MainWindowLifecycleOptions = { initLocale: () => void; initThemeModeSafely: () => void; + loadTrackingState: () => Promise; loadHeatmapGoalSecondsSetting: () => Promise; resetGuardFeedback: () => void; resetPrivacyFeedback: () => void; refreshHomeData: () => Promise | void; startSettingsWarmup: () => void; startMainRefreshPolling: () => void; - startAutoCaptureSampler: () => void; startInsightsSectionNavigationListener: () => Promise; stopMainRefreshPolling: () => void; stopAutoCaptureSampler: () => void; @@ -21,13 +21,13 @@ type MainWindowLifecycleOptions = { export function useMainWindowLifecycle({ initLocale, initThemeModeSafely, + loadTrackingState, loadHeatmapGoalSecondsSetting, resetGuardFeedback, resetPrivacyFeedback, refreshHomeData, startSettingsWarmup, startMainRefreshPolling, - startAutoCaptureSampler, startInsightsSectionNavigationListener, stopMainRefreshPolling, stopAutoCaptureSampler, @@ -39,6 +39,7 @@ export function useMainWindowLifecycle({ initLocale(); initThemeModeSafely(); + await loadTrackingState(); await loadHeatmapGoalSecondsSetting(); resetGuardFeedback(); @@ -47,8 +48,6 @@ export function useMainWindowLifecycle({ startSettingsWarmup(); startMainRefreshPolling(); - startAutoCaptureSampler(); - await startInsightsSectionNavigationListener(); }); From eb3cf2aa5dc27269dbcb8b8d345850b27622d43b Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:41:39 +0800 Subject: [PATCH 061/117] feat(frontend): gate capture runtime on persisted tracking state --- src/App.vue | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/src/App.vue b/src/App.vue index d27393e..b4b7e38 100644 --- a/src/App.vue +++ b/src/App.vue @@ -1,4 +1,5 @@ + + + + From 4be13900f6737bab9a705787f2ca8c14f33b01c4 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:53:01 +0800 Subject: [PATCH 069/117] feat(frontend): gate first-run UI and activate tracking without restart --- src/App.vue | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 2 deletions(-) diff --git a/src/App.vue b/src/App.vue index b4b7e38..b1cbe3c 100644 --- a/src/App.vue +++ b/src/App.vue @@ -1,11 +1,13 @@ + + From 2183bded77b3d8cf7ad8b78cb4f8f4688010fa9c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 22:55:32 +0800 Subject: [PATCH 070/117] fix(frontend): expose runtime tracking UI overload --- src/lib/trackingUi.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/lib/trackingUi.ts b/src/lib/trackingUi.ts index e4ef937..7babab2 100644 --- a/src/lib/trackingUi.ts +++ b/src/lib/trackingUi.ts @@ -12,6 +12,10 @@ export function trackingUiMode( trackingReady: true, onboardingCompleted: true, ): "app"; +export function trackingUiMode( + trackingReady: boolean, + onboardingCompleted: boolean, +): TrackingUiMode; export function trackingUiMode( trackingReady: boolean, onboardingCompleted: boolean, From 8850a9724f36cce0b7c122581c1e47ac01dab9e5 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:02:06 +0800 Subject: [PATCH 071/117] test(frontend): forbid capture policy in sampler API --- src/composables/useAutoCaptureSampler.contract.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/composables/useAutoCaptureSampler.contract.ts b/src/composables/useAutoCaptureSampler.contract.ts index 49deabc..54d047f 100644 --- a/src/composables/useAutoCaptureSampler.contract.ts +++ b/src/composables/useAutoCaptureSampler.contract.ts @@ -7,6 +7,14 @@ const sampler = useAutoCaptureSampler({ intervalMs: 5000, }); +// Runtime policy belongs to useTrackingState/App, not to the sampler API. +// @ts-expect-error autoCaptureEnabled must not be accepted by the sampler. +useAutoCaptureSampler({ + autoCaptureEnabled: ref(true), + autoCaptureFeedback: ref(""), + tx: (_zh, en) => en, +}); + export const autoCaptureSamplerContract = sampler satisfies { startAutoCaptureSampler: () => void; stopAutoCaptureSampler: () => void; From 7ca48a4c7b124889535915417ac3cb04fbb66264 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:05:03 +0800 Subject: [PATCH 072/117] refactor(frontend): remove capture policy from sampler API --- src/composables/useAutoCaptureSampler.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/composables/useAutoCaptureSampler.ts b/src/composables/useAutoCaptureSampler.ts index 709c472..d28132e 100644 --- a/src/composables/useAutoCaptureSampler.ts +++ b/src/composables/useAutoCaptureSampler.ts @@ -7,7 +7,6 @@ type AutoCaptureSamplerOptions = { autoCaptureFeedback: Ref; tx: TranslateFn; intervalMs?: number; - autoCaptureEnabled?: Ref; }; export function useAutoCaptureSampler({ From cce1dcff9916babaa2e2e96a33f33381767264d3 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:07:00 +0800 Subject: [PATCH 073/117] test(frontend): pin sampler policy rejection to property --- src/composables/useAutoCaptureSampler.contract.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/composables/useAutoCaptureSampler.contract.ts b/src/composables/useAutoCaptureSampler.contract.ts index 54d047f..c5d8156 100644 --- a/src/composables/useAutoCaptureSampler.contract.ts +++ b/src/composables/useAutoCaptureSampler.contract.ts @@ -8,8 +8,8 @@ const sampler = useAutoCaptureSampler({ }); // Runtime policy belongs to useTrackingState/App, not to the sampler API. -// @ts-expect-error autoCaptureEnabled must not be accepted by the sampler. useAutoCaptureSampler({ + // @ts-expect-error autoCaptureEnabled must not be accepted by the sampler. autoCaptureEnabled: ref(true), autoCaptureFeedback: ref(""), tx: (_zh, en) => en, From 67e323ef839a102a7543c85b840eedde70a29a2c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:20:45 +0800 Subject: [PATCH 074/117] test(pet): require persisted tracking mood contract --- src/pet.tracking.contract.ts | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 src/pet.tracking.contract.ts diff --git a/src/pet.tracking.contract.ts b/src/pet.tracking.contract.ts new file mode 100644 index 0000000..1ea505a --- /dev/null +++ b/src/pet.tracking.contract.ts @@ -0,0 +1,6 @@ +import { petTrackingMood } from "./pet"; + +const tx = (zh: string, en: string) => `${zh}|${en}`; + +export const activePetTrackingMoodContract: string = petTrackingMood(true, tx); +export const pausedPetTrackingMoodContract: string = petTrackingMood(false, tx); From 94a318e8f97818cd850d17a095c4a9b970e2d0cb Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:24:55 +0800 Subject: [PATCH 075/117] feat(pet): show persisted tracking status --- src/pet.ts | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/src/pet.ts b/src/pet.ts index 0ae6ac7..9e2db50 100644 --- a/src/pet.ts +++ b/src/pet.ts @@ -1,8 +1,8 @@ -import { invoke } from "@tauri-apps/api/core"; +import { invoke } from "@tauri-apps/api/core"; import { LogicalPosition } from "@tauri-apps/api/dpi"; import { Menu } from "@tauri-apps/api/menu"; import { currentMonitor, getCurrentWindow } from "@tauri-apps/api/window"; -import { getTodaySummary, type TodaySummary } from "./api"; +import { getTodaySummary, getTrackingState } from "./api"; import { LOCALE_STORAGE_KEY, getStoredOrBrowserLocale, @@ -57,6 +57,8 @@ import "./pet.css"; const petWindow = getCurrentWindow(); const EDGE_SNAP_THRESHOLD = 72; +type PetTranslateFn = (zh: string, en: string) => string; + function getLocale(): LocaleCode { return getStoredOrBrowserLocale(); } @@ -65,6 +67,15 @@ function tx(zh: string, en: string): string { return translateForLocale(getLocale(), zh, en); } +export function petTrackingMood( + autoCaptureEnabled: boolean, + translate: PetTranslateFn, +): string { + return autoCaptureEnabled + ? translate("自动记录中", "Auto tracking") + : translate("记录已暂停", "Tracking paused"); +} + let petState: PetDockState = "free"; let isDragging = false; let expanded = false; @@ -408,12 +419,15 @@ function scheduleSettleRetry(attempt = 0) { async function refreshSummary() { try { - const summary: TodaySummary = await getTodaySummary(); + const [summary, tracking] = await Promise.all([ + getTodaySummary(), + getTrackingState(), + ]); renderPetSummary( { learn, rest, mood }, formatSeconds(summary.learn_seconds), formatSeconds(summary.rest_seconds), - tx("自动记录中", "Auto tracking"), + petTrackingMood(tracking.auto_capture_enabled, tx), ); } catch { setMood(tx("状态同步失败，请打开设置查看详情", "Sync failed, open settings for details")); @@ -564,4 +578,3 @@ window.addEventListener("beforeunload", () => { closeContextMenu(); }); - From aff2660c59658d9d2146c375ba3d7141035f785b Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:27:50 +0800 Subject: [PATCH 076/117] test(ui): require compare-and-clear error ownership --- src/composables/errorOwnership.contract.ts | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 src/composables/errorOwnership.contract.ts diff --git a/src/composables/errorOwnership.contract.ts b/src/composables/errorOwnership.contract.ts new file mode 100644 index 0000000..de8aa7b --- /dev/null +++ b/src/composables/errorOwnership.contract.ts @@ -0,0 +1,17 @@ +import type { Ref } from "vue"; +import { useErrorMessage } from "./useErrorMessage"; +import { useHomeData } from "./useHomeData"; + +const errorApi = useErrorMessage(); + +export const errorOwnershipContract = errorApi satisfies { + error: Ref; + setErrorMessage: (error: unknown) => void; + clearErrorMessage: (expected?: unknown) => void; +}; + +type HomeDataOptions = Parameters[0]; + +export const homeErrorOwnershipContract = { + clearErrorMessage: (_expected?: unknown) => undefined, +} satisfies Pick; From 56f305bf9f24c60c68132714952316755b9fa063 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:30:03 +0800 Subject: [PATCH 077/117] fix(ui): add compare-and-clear error API --- src/composables/useErrorMessage.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/composables/useErrorMessage.ts b/src/composables/useErrorMessage.ts index 11efe7d..133d284 100644 --- a/src/composables/useErrorMessage.ts +++ b/src/composables/useErrorMessage.ts @@ -7,8 +7,15 @@ export function useErrorMessage() { error.value = `${e}`; } + function clearErrorMessage(expected?: unknown) { + if (expected === undefined || error.value === `${expected}`) { + error.value = ""; + } + } + return { error, setErrorMessage, + clearErrorMessage, }; } From 9f3aeb1d94f7671b3a9276c62b11b167755e9792 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:30:19 +0800 Subject: [PATCH 078/117] fix(ui): preserve newer errors during home recovery --- src/composables/useHomeData.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/composables/useHomeData.ts b/src/composables/useHomeData.ts index 543a7c5..6b3716c 100644 --- a/src/composables/useHomeData.ts +++ b/src/composables/useHomeData.ts @@ -27,6 +27,7 @@ type UseHomeDataOptions = { getHeatmapFetchDays: () => number; getHeatmapGoalSeconds: () => number; setErrorMessage: (error: unknown) => void; + clearErrorMessage: (expected?: unknown) => void; }; export function useHomeData({ @@ -40,10 +41,12 @@ export function useHomeData({ getHeatmapFetchDays, getHeatmapGoalSeconds, setErrorMessage, + clearErrorMessage, }: UseHomeDataOptions) { const loadingHomeCore = ref(false); const loadingHomeAnalytics = ref(false); let initialHomeRefresh = true; + let lastHomeCoreError = ""; async function refreshHomeCoreData() { if (loadingHomeCore.value) { @@ -64,7 +67,12 @@ export function useHomeData({ pendingRuleProcesses.value = pendingRules; idlePrompts.value = pendingIdle; reminders.value = reminderRows; + if (lastHomeCoreError) { + clearErrorMessage(lastHomeCoreError); + lastHomeCoreError = ""; + } } catch (e) { + lastHomeCoreError = `${e}`; setErrorMessage(e); } finally { loadingHomeCore.value = false; From ebf65931df48cc53bf999e7e5eba6cb49fe7b06c Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:31:05 +0800 Subject: [PATCH 079/117] fix(ui): clear only recovered home read errors --- src/App.vue | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/App.vue b/src/App.vue index b1cbe3c..0ca7050 100644 --- a/src/App.vue +++ b/src/App.vue @@ -46,7 +46,7 @@ import { trackingUiMode } from "./lib/trackingUi"; const { locale, tx, initLocale, watchLocaleChanges, onLocaleChange } = useLocale(); watchLocaleChanges(); const { themeMode, toggleThemeMode, initThemeModeSafely } = useThemeMode(); -const { error, setErrorMessage } = useErrorMessage(); +const { error, setErrorMessage, clearErrorMessage } = useErrorMessage(); const { trackingReady, onboardingCompleted, @@ -349,6 +349,7 @@ const { refreshHomeData } = useHomeData({ getHeatmapFetchDays, getHeatmapGoalSeconds, setErrorMessage, + clearErrorMessage, }); bindMainDataRefreshHandlers({ refreshHomeData, From 1970a4946244dd947819861f6e8defa008fe056d Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:33:51 +0800 Subject: [PATCH 080/117] docs: add first-run tracking smoke gates --- docs/SMOKE_TESTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/SMOKE_TESTS.md b/docs/SMOKE_TESTS.md index a71a15b..f6203d8 100644 --- a/docs/SMOKE_TESTS.md +++ b/docs/SMOKE_TESTS.md @@ -25,6 +25,50 @@ Cleanup: Remove-Item -LiteralPath .\dist-codex-check -Recurse -Force ``` +## S-050 Fresh Install And First-Run Tracking + +Use a clean or sandboxed TimePrism app-data directory so this path exercises a truly fresh database. + +1. Launch TimePrism with no existing app database. +2. Confirm no `no such table: app_usage_logs` or other pre-initialization database error appears. +3. Before activation, switch foreground apps for more than 10 seconds and confirm no usage rows are captured. +4. Confirm onboarding explains: + - foreground application/window metadata is observed for duration tracking; + - core data is stored in local SQLite; + - browser titles receive privacy processing and private/incognito windows are skipped; + - TimePrism does not capture screenshots or keystroke contents; + - Insights shows observed application activity while pet `学 / 休` counters include only activity classified as `LEARN / REST`. +5. Click `开始使用 TimePrism` and confirm tracking becomes active without restarting the app. +6. Switch foreground apps and confirm Insights begins showing observed activity after the normal sampling interval. +7. Confirm pet `学 / 休` remains classification-based and refreshes on the existing several-second cadence rather than synthetic per-second increments. +8. Pause capture from Focus Guard, switch foreground apps for more than 10 seconds, and confirm no new samples are appended. +9. Fully quit and reopen TimePrism; confirm the pause persists and onboarding does not reappear. +10. Resume capture, fully quit and reopen again, and confirm automatic tracking resumes. +11. While capture is paused, confirm the pet mood reports `记录已暂停` / `Tracking paused`. +12. Confirm close-to-background, pet summon/hide, and `Quit TimePrism` behavior still works. + +Expected: + +- Database initialization completes before product WebViews query SQLite. +- Fresh installs remain capture-off until explicit onboarding activation succeeds. +- Pause/resume is persisted, not reset by restart. +- Tracking, Home, and pet updates retain the existing approximately 5-second cadence. + +## S-060 Upgrade From A Pre-Tracking-State Database + +Use a backed-up database created by a TimePrism build from before the `onboarding_completed` and `auto_capture_enabled` keys existed. + +1. Launch the current build against the backed-up pre-change database. +2. Confirm existing records remain present. +3. Confirm onboarding does not appear. +4. Confirm tracking starts enabled by default for this recognized legacy database. +5. Pause capture, fully quit, and reopen; confirm the explicit pause is preserved. + +Expected: + +- Recognizable legacy databases migrate to onboarded + capture-enabled defaults without overwriting later explicit tracking choices. +- Existing user data survives migration. + ## S-100 Main Window 1. Launch the app. From c34410a2f544db9dcd90df375c05cdf8f8d00980 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:34:15 +0800 Subject: [PATCH 081/117] docs: add first-run tracking release gates --- docs/RELEASE_CHECKLIST.md | 49 ++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md index 4465f7c..75051b0 100644 --- a/docs/RELEASE_CHECKLIST.md +++ b/docs/RELEASE_CHECKLIST.md @@ -20,24 +20,59 @@ Installer validation is deliberately split into two layers: A green packaging job is therefore necessary evidence, but it is not sufficient by itself to publish a Release. +## Mandatory first-run and upgrade acceptance + +Before a public release, both tracking-state migration paths must pass on a real Windows machine using the exact release candidate build. + +### Fresh-install gate + +Use a clean or sandboxed TimePrism app-data directory and complete `S-050 Fresh Install And First-Run Tracking` in `docs/SMOKE_TESTS.md`. + +Release-blocking assertions include: + +- SQLite is initialized before product WebViews query it; no `no such table` startup failure appears. +- No foreground capture occurs before the user accepts the first-run tracking disclosure. +- The disclosure accurately describes foreground app/window metadata, local SQLite storage, browser privacy processing, no screenshot/keystroke-content capture, and the distinction between observed activity and classified `LEARN / REST` time. +- Activation begins tracking without an application restart. +- Pause persists across full quit/reopen; resume also persists and restores automatic tracking after restart. +- The desktop pet reports active versus paused tracking while keeping `学 / 休` counters classification-based. + +### Upgrade gate + +Use a backed-up recognizable TimePrism database created before the tracking-state keys existed and complete `S-060 Upgrade From A Pre-Tracking-State Database`. + +Release-blocking assertions include: + +- existing rows survive migration; +- onboarding does not unexpectedly reappear for an existing user; +- the legacy database starts onboarded with capture enabled; +- a later explicit pause is preserved across reinitialization and restart. + +Do not publish a release, mark a release candidate accepted, or promote a tracking-state PR solely from automated CI evidence if either interactive gate has not passed. + ## Before tagging 1. Confirm `main` CI is green. 2. Confirm the latest relevant packaging PR produced both installer formats successfully. -3. Update the same semantic version in: +3. Confirm both mandatory acceptance paths above passed on the release candidate: + - fresh install (`S-050`); + - pre-tracking-state upgrade (`S-060`). +4. Update the same semantic version in: - `package.json` - `src-tauri/Cargo.toml` - `src-tauri/tauri.conf.json` -4. Run or verify: +5. Run or verify: ```text + pnpm install --frozen-lockfile pnpm run typecheck pnpm run build:check + cargo check --manifest-path src-tauri/Cargo.toml --all-targets cargo test --manifest-path src-tauri/Cargo.toml ``` -5. Smoke-test the desktop flows listed in `docs/SMOKE_TESTS.md`. -6. Commit the synchronized version bump to `main`. +6. Smoke-test the remaining desktop flows listed in `docs/SMOKE_TESTS.md`. +7. Commit the synchronized version bump to `main`. The release workflow rejects mismatched Node/Cargo/Tauri versions. Tag-triggered runs also reject a tag that does not equal `v`. @@ -68,10 +103,11 @@ Download the generated artifact and perform the interactive Windows smoke before At minimum, verify one generated installer end to end on Windows: - install from the NSIS `-setup.exe` or MSI artifact; -- launch TimePrism and confirm the main window renders normally; +- run the fresh-install tracking acceptance with a clean/sandboxed app-data directory; +- separately run the upgrade acceptance against a backed-up pre-tracking-state database; - verify Home, Insights, Focus Guard, reminders, privacy settings, and desktop pet flows; - verify main-window close/background behavior and full-app quit behavior; -- restart the app and confirm local data survives; +- restart the app and confirm local data and tracking pause/resume state survive as expected; - uninstall the tested installer and confirm the uninstall flow completes normally; - retain the unsigned/SmartScreen note until Windows code signing exists. @@ -94,6 +130,7 @@ Before publishing the draft Release: - confirm the expected NSIS and MSI assets are attached; - install at least one draft asset if it differs from the previously smoke-tested artifact; +- confirm both fresh-install and upgrade acceptance evidence corresponds to the same code/release candidate; - confirm Release notes describe any known limitations; - explicitly retain the unsigned/SmartScreen note until Windows code signing exists. From f297c1bf16d7811e0cf1274d00d1b75af4652846 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:20:52 +0800 Subject: [PATCH 082/117] test(idle): require previous-app attribution contract --- src/api/idleAttribution.contract.ts | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 src/api/idleAttribution.contract.ts diff --git a/src/api/idleAttribution.contract.ts b/src/api/idleAttribution.contract.ts new file mode 100644 index 0000000..ce9d173 --- /dev/null +++ b/src/api/idleAttribution.contract.ts @@ -0,0 +1,17 @@ +import { resolveIdlePrompt } from "./commands/foreground"; +import type { IdlePrompt } from "./types"; + +const prompt: IdlePrompt = { + id: 1, + start_timestamp: 100, + end_timestamp: 400, + duration_ms: 300_000, + attribution_process_name: "code.exe", +}; + +export const idleAttributionProcessContract: string | null = prompt.attribution_process_name; + +void resolveIdlePrompt({ + prompt_id: prompt.id, + decision: "APP", +}); From 8062ce1ac7b1defbcd6cbbb4c57eb80f24aaac5b Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:22:38 +0800 Subject: [PATCH 083/117] feat(api): expose idle attribution candidate --- src/api/types.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/api/types.ts b/src/api/types.ts index 4619393..d9328fb 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -100,6 +100,7 @@ export type IdlePrompt = { end_timestamp: number; duration_ms: number; deferred_until_timestamp?: number | null; + attribution_process_name: string | null; }; export type IdleMemoryState = { @@ -121,4 +122,4 @@ export type Reminder = { completed_at: number | null; created_at: number; updated_at: number; -}; +}; \ No newline at end of file From 0264cd2b7a9ae7ef34d3664ff3c019f79418d28d Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:22:50 +0800 Subject: [PATCH 084/117] feat(api): accept idle app attribution decision --- src/api/commands/foreground.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/commands/foreground.ts b/src/api/commands/foreground.ts index 5f4cdd3..aa36c68 100644 --- a/src/api/commands/foreground.ts +++ b/src/api/commands/foreground.ts @@ -18,7 +18,7 @@ export async function listPendingIdlePrompts(limit = 5): Promise { export async function resolveIdlePrompt(input: { prompt_id: number; - decision: "LEARN" | "REST" | "IDLE" | "SKIP"; + decision: "APP" | "LEARN" | "REST" | "IDLE" | "SKIP"; remember_this_session?: boolean; }): Promise { return invokeCommand("resolve_idle_prompt", { input }); From 2875b7cd89ab01dcc1bacd3483381e6fa905d7db Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:23:33 +0800 Subject: [PATCH 085/117] test(idle): require app-attributed interval persistence --- src-tauri/src/services/usage.rs | 77 ++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/src-tauri/src/services/usage.rs b/src-tauri/src/services/usage.rs index 44fa885..994af84 100644 --- a/src-tauri/src/services/usage.rs +++ b/src-tauri/src/services/usage.rs @@ -137,7 +137,7 @@ pub(crate) fn append_usage_log_record( mod tests { use rusqlite::{params, Connection}; - use super::persist_idle_prompt_decision; + use super::{persist_idle_prompt_app_decision, persist_idle_prompt_decision}; use crate::domain::idle::IdlePromptEntry; fn usage_test_conn() -> Connection { @@ -218,4 +218,79 @@ mod tests { ] ); } + + #[test] + fn idle_app_decision_attributes_interval_without_overwriting_app_rule() { + let conn = usage_test_conn(); + conn.execute( + "INSERT INTO app_rules (process_name, mapped_type, privacy_level, created_at, updated_at) + VALUES ('code.exe', 'REST', 'NORMAL', 1, 1)", + [], + ) + .expect("seed app rule"); + conn.execute( + "INSERT INTO app_usage_logs (process_name, window_title, start_timestamp, duration_ms) + VALUES (?1, ?2, ?3, ?4)", + params!["code.exe", "Project", 100_i64, 400_000_i64], + ) + .expect("insert foreground segment crossing idle start"); + conn.execute( + "INSERT INTO app_usage_logs (process_name, window_title, start_timestamp, duration_ms) + VALUES (?1, ?2, ?3, ?4)", + params!["lockapp.exe", "Lock Screen", 350_i64, 100_000_i64], + ) + .expect("insert foreground segment inside idle interval"); + + let prompt = IdlePromptEntry { + id: 2, + start_timestamp: 300, + end_timestamp: 600, + duration_ms: 300_000, + deferred_until_timestamp: None, + }; + + persist_idle_prompt_app_decision(&conn, &prompt, "code.exe") + .expect("persist app-attributed idle decision"); + + let rows = conn + .prepare( + "SELECT process_name, window_title, start_timestamp, duration_ms + FROM app_usage_logs + ORDER BY start_timestamp, id", + ) + .expect("prepare usage rows") + .query_map([], |row| { + Ok(( + row.get::<_, String>(0)?, + row.get::<_, String>(1)?, + row.get::<_, i64>(2)?, + row.get::<_, i64>(3)?, + )) + }) + .expect("query usage rows") + .collect::, _>>() + .expect("collect usage rows"); + + assert_eq!( + rows, + vec![ + ("code.exe".to_string(), "Project".to_string(), 100, 200_000), + ( + "code.exe".to_string(), + "Idle Confirmed · Previous App".to_string(), + 300, + 300_000, + ), + ] + ); + + let mapped_type: String = conn + .query_row( + "SELECT mapped_type FROM app_rules WHERE process_name = 'code.exe'", + [], + |row| row.get(0), + ) + .expect("query app rule"); + assert_eq!(mapped_type, "REST"); + } } From 229b463974e22816f6b9897a06e288bffdc8563e Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:26:07 +0800 Subject: [PATCH 086/117] feat(idle): persist app-attributed idle intervals --- src-tauri/src/services/usage.rs | 53 ++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 11 deletions(-) diff --git a/src-tauri/src/services/usage.rs b/src-tauri/src/services/usage.rs index 994af84..0f642e6 100644 --- a/src-tauri/src/services/usage.rs +++ b/src-tauri/src/services/usage.rs @@ -59,19 +59,18 @@ fn append_usage_log_direct( Ok(true) } -pub(crate) fn persist_idle_prompt_decision( +fn replace_idle_interval_with_usage( conn: &Connection, prompt: &IdlePromptEntry, - decision: &str, + process_name: &str, + title: &str, + mapped_type: Option<&str>, ) -> Result { - let (process_name, mapped_type, title) = match decision { - "LEARN" => ("__idle_learn__.exe", "LEARN", "Idle Segment · Learn"), - "REST" => ("__idle_rest__.exe", "REST", "Idle Segment · Rest"), - "IDLE" => ("__idle__.exe", "IGNORE", "Idle Segment · Unclassified"), - _ => return Err("invalid idle decision".to_string()), - }; - let process_key = normalize_process_key(process_name); + if process_key.trim().is_empty() { + return Err("idle app attribution requires a process name".to_string()); + } + let idle_start = prompt.start_timestamp.max(0); let idle_end = prompt.end_timestamp.max(idle_start); let tx = conn @@ -80,7 +79,7 @@ pub(crate) fn persist_idle_prompt_decision( // Foreground samples can be persisted during the idle threshold window before the sampler // knows the interval is idle. Resolving the prompt commits the retroactive classification, - // so replace those provisional rows instead of adding an overlapping idle row on top. + // so replace those provisional rows instead of adding an overlapping row on top. tx.execute( "UPDATE app_usage_logs SET duration_ms = MAX(0, (?1 - start_timestamp) * 1000) @@ -97,7 +96,10 @@ pub(crate) fn persist_idle_prompt_decision( ) .map_err(|e| format!("failed to remove usage inside idle interval: {e}"))?; - upsert_app_rule_entry(&tx, &process_key, mapped_type, "NORMAL")?; + if let Some(mapped_type) = mapped_type { + upsert_app_rule_entry(&tx, &process_key, mapped_type, "NORMAL")?; + } + let stored = append_usage_log_direct( &tx, &process_key, @@ -111,6 +113,35 @@ pub(crate) fn persist_idle_prompt_decision( Ok(stored) } +pub(crate) fn persist_idle_prompt_decision( + conn: &Connection, + prompt: &IdlePromptEntry, + decision: &str, +) -> Result { + let (process_name, mapped_type, title) = match decision { + "LEARN" => ("__idle_learn__.exe", "LEARN", "Idle Segment · Learn"), + "REST" => ("__idle_rest__.exe", "REST", "Idle Segment · Rest"), + "IDLE" => ("__idle__.exe", "IGNORE", "Idle Segment · Unclassified"), + _ => return Err("invalid idle decision".to_string()), + }; + + replace_idle_interval_with_usage(conn, prompt, process_name, title, Some(mapped_type)) +} + +pub(crate) fn persist_idle_prompt_app_decision( + conn: &Connection, + prompt: &IdlePromptEntry, + process_name: &str, +) -> Result { + replace_idle_interval_with_usage( + conn, + prompt, + process_name, + "Idle Confirmed · Previous App", + None, + ) +} + pub(crate) fn append_usage_log_record( conn: &Connection, process_name: &str, From 60325f1a9ee0ebe754dec2a17f7095b934c185df Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:26:38 +0800 Subject: [PATCH 087/117] feat(idle): carry previous-app attribution candidate --- src-tauri/src/domain/idle.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src-tauri/src/domain/idle.rs b/src-tauri/src/domain/idle.rs index 6e6076d..eba3168 100644 --- a/src-tauri/src/domain/idle.rs +++ b/src-tauri/src/domain/idle.rs @@ -7,6 +7,7 @@ pub(crate) struct IdlePromptEntry { pub(crate) end_timestamp: i64, pub(crate) duration_ms: i64, pub(crate) deferred_until_timestamp: Option, + pub(crate) attribution_process_name: Option, } #[derive(Deserialize)] From a60f0ebbc55cd302f3d8fc92ad8fc001d4bff6aa Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:27:25 +0800 Subject: [PATCH 088/117] test(idle): carry attribution field through usage fixtures --- src-tauri/src/services/usage.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src-tauri/src/services/usage.rs b/src-tauri/src/services/usage.rs index 0f642e6..1ed53eb 100644 --- a/src-tauri/src/services/usage.rs +++ b/src-tauri/src/services/usage.rs @@ -218,6 +218,7 @@ mod tests { end_timestamp: 600, duration_ms: 300_000, deferred_until_timestamp: None, + attribution_process_name: None, }; persist_idle_prompt_decision(&conn, &prompt, "REST").expect("persist idle decision"); @@ -278,6 +279,7 @@ mod tests { end_timestamp: 600, duration_ms: 300_000, deferred_until_timestamp: None, + attribution_process_name: Some("code.exe".to_string()), }; persist_idle_prompt_app_decision(&conn, &prompt, "code.exe") From 27d8f6668069560e30bd2a2c1a530c8c49044563 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:30:42 +0800 Subject: [PATCH 089/117] feat(idle): capture and resolve previous-app attribution --- src-tauri/src/services/foreground.rs | 84 ++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 6 deletions(-) diff --git a/src-tauri/src/services/foreground.rs b/src-tauri/src/services/foreground.rs index 4707813..7874d16 100644 --- a/src-tauri/src/services/foreground.rs +++ b/src-tauri/src/services/foreground.rs @@ -21,7 +21,9 @@ use windows_sys::Win32::UI::WindowsAndMessaging::{ use super::privacy::normalize_process_key; use super::rules::resolve_rule_mapping; -use super::usage::{append_usage_log_record, persist_idle_prompt_decision}; +use super::usage::{ + append_usage_log_record, persist_idle_prompt_app_decision, persist_idle_prompt_decision, +}; use crate::db::connection::open_connection; use crate::domain::idle::{IdleMemoryState, IdlePromptEntry, ResolveIdlePromptInput}; use crate::domain::window::ForegroundCaptureDiagnostic; @@ -35,6 +37,7 @@ struct ForegroundSampleState { last: Option, diagnostics: Vec, idle_segment_start_ms: Option, + idle_attribution_process_name: Option, pending_idle_prompts: Vec, next_idle_prompt_id: i64, remembered_idle_decision: Option, @@ -47,6 +50,18 @@ struct ForegroundSnapshot { captured_at_ms: i64, } +fn idle_attribution_candidate(snapshot: Option<&ForegroundSnapshot>) -> Option { + let process_name = snapshot.map(|item| normalize_process_key(&item.process_name))?; + if process_name == "unknown.exe" + || process_name == "lockapp.exe" + || process_name == "logonui.exe" + || process_name.starts_with("pid-") + { + return None; + } + Some(process_name) +} + fn push_foreground_diagnostic(mut entry: ForegroundCaptureDiagnostic) -> Result<(), String> { entry.observed_window_title = "Hidden for Privacy".to_string(); @@ -151,6 +166,9 @@ pub(crate) fn capture_foreground_once( let mut state = FOREGROUND_SAMPLE_STATE .lock() .map_err(|e| format!("failed to lock foreground sample state: {e}"))?; + if state.idle_segment_start_ms.is_none() { + state.idle_attribution_process_name = idle_attribution_candidate(state.last.as_ref()); + } let seg_start = state.idle_segment_start_ms.get_or_insert(idle_start_ms); if idle_start_ms < *seg_start { *seg_start = idle_start_ms; @@ -177,6 +195,7 @@ pub(crate) fn capture_foreground_once( .lock() .map_err(|e| format!("failed to lock foreground sample state: {e}"))?; if let Some(idle_start_ms) = state.idle_segment_start_ms.take() { + let attribution_process_name = state.idle_attribution_process_name.take(); let duration = (now_ms - idle_start_ms).max(0); if duration >= IDLE_PROMPT_THRESHOLD_MS { let prompt_id = if state.next_idle_prompt_id <= 0 { @@ -191,6 +210,7 @@ pub(crate) fn capture_foreground_once( end_timestamp: (now_ms / 1000).max(0), duration_ms: duration, deferred_until_timestamp: None, + attribution_process_name, }; if let Some(remembered) = state.remembered_idle_decision.clone() { @@ -214,6 +234,8 @@ pub(crate) fn capture_foreground_once( } } } + } else { + state.idle_attribution_process_name = None; } } @@ -353,8 +375,8 @@ pub(crate) fn resolve_idle_prompt( ) -> Result { let decision = input.decision.trim().to_uppercase(); let remember_this_session = input.remember_this_session.unwrap_or(false); - if !matches!(decision.as_str(), "LEARN" | "REST" | "IDLE" | "SKIP") { - return Err("decision must be LEARN, REST, IDLE, or SKIP".to_string()); + if !matches!(decision.as_str(), "APP" | "LEARN" | "REST" | "IDLE" | "SKIP") { + return Err("decision must be APP, LEARN, REST, IDLE, or SKIP".to_string()); } if decision == "SKIP" { @@ -373,6 +395,21 @@ pub(crate) fn resolve_idle_prompt( return Ok(false); } + if decision == "APP" { + let state = FOREGROUND_SAMPLE_STATE + .lock() + .map_err(|e| format!("failed to lock foreground sample state: {e}"))?; + let has_candidate = state + .pending_idle_prompts + .iter() + .find(|item| item.id == input.prompt_id) + .and_then(|item| item.attribution_process_name.as_ref()) + .is_some(); + if !has_candidate { + return Err("idle prompt has no previous-app attribution candidate".to_string()); + } + } + let prompt = { let mut state = FOREGROUND_SAMPLE_STATE .lock() @@ -388,9 +425,17 @@ pub(crate) fn resolve_idle_prompt( return Ok(false); }; let conn = open_connection(app)?; - let stored = persist_idle_prompt_decision(&conn, &prompt, &decision)?; + let stored = if decision == "APP" { + let process_name = prompt + .attribution_process_name + .as_deref() + .ok_or_else(|| "idle prompt has no previous-app attribution candidate".to_string())?; + persist_idle_prompt_app_decision(&conn, &prompt, process_name)? + } else { + persist_idle_prompt_decision(&conn, &prompt, &decision)? + }; - if remember_this_session { + if remember_this_session && matches!(decision.as_str(), "LEARN" | "REST" | "IDLE") { let mut state = FOREGROUND_SAMPLE_STATE .lock() .map_err(|e| format!("failed to lock foreground sample state: {e}"))?; @@ -468,7 +513,8 @@ pub(crate) fn list_foreground_capture_diagnostics( #[cfg(test)] mod tests { use super::{ - list_foreground_capture_diagnostics, push_foreground_diagnostic, FOREGROUND_SAMPLE_STATE, + idle_attribution_candidate, list_foreground_capture_diagnostics, push_foreground_diagnostic, + ForegroundSnapshot, FOREGROUND_SAMPLE_STATE, }; use crate::domain::window::ForegroundCaptureDiagnostic; @@ -479,6 +525,32 @@ mod tests { state.diagnostics.clear(); } + #[test] + fn idle_attribution_uses_normalized_previous_app_without_title() { + let snapshot = ForegroundSnapshot { + process_name: r#"C:\Program Files\Microsoft VS Code\Code.exe"#.to_string(), + window_title: "Secret project title".to_string(), + captured_at_ms: 1, + }; + + assert_eq!( + idle_attribution_candidate(Some(&snapshot)), + Some("code.exe".to_string()) + ); + } + + #[test] + fn idle_attribution_rejects_lock_and_unknown_processes() { + for process_name in ["LockApp.exe", "LogonUI.exe", "unknown.exe", "pid-42.exe"] { + let snapshot = ForegroundSnapshot { + process_name: process_name.to_string(), + window_title: "Hidden".to_string(), + captured_at_ms: 1, + }; + assert_eq!(idle_attribution_candidate(Some(&snapshot)), None); + } + } + #[test] fn diagnostics_do_not_expose_raw_window_titles() { clear_diagnostics(); From bdbdc080918b7053b7fd6eb53552b5fe1d07cba1 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:31:48 +0800 Subject: [PATCH 090/117] test(idle): require app attribution in guard decisions --- src/lib/guardIdleAttribution.contract.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 src/lib/guardIdleAttribution.contract.ts diff --git a/src/lib/guardIdleAttribution.contract.ts b/src/lib/guardIdleAttribution.contract.ts new file mode 100644 index 0000000..ed7ee4b --- /dev/null +++ b/src/lib/guardIdleAttribution.contract.ts @@ -0,0 +1,13 @@ +import { + guardIdleDecisionFeedback, + shouldRememberGuardIdleDecision, + type GuardIdleDecision, +} from "./guardIdle"; + +const decision: GuardIdleDecision = "APP"; +export const rememberAppAttributionContract: boolean = shouldRememberGuardIdleDecision(true, decision); +export const appAttributionFeedbackContract: string = guardIdleDecisionFeedback( + decision, + false, + (_zh, en) => en, +).text; From fe5d44aa411884182f5b55455155ed8ce917c49f Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:33:17 +0800 Subject: [PATCH 091/117] feat(idle): add app attribution guard decision --- src/lib/guardIdle.ts | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/lib/guardIdle.ts b/src/lib/guardIdle.ts index aae8ae5..afd295f 100644 --- a/src/lib/guardIdle.ts +++ b/src/lib/guardIdle.ts @@ -3,7 +3,7 @@ import type { IdlePrompt } from "../api"; type TranslateFn = (zh: string, en: string) => string; type GuardFeedbackTone = "info" | "ok" | "warn" | "error"; -export type GuardIdleDecision = "LEARN" | "REST" | "IDLE" | "SKIP"; +export type GuardIdleDecision = "APP" | "LEARN" | "REST" | "IDLE" | "SKIP"; export type GuardIdleDecisionFeedback = { type: GuardFeedbackTone; @@ -24,7 +24,7 @@ export function shouldRememberGuardIdleDecision( rememberChoice: boolean, decision: GuardIdleDecision, ): boolean { - return rememberChoice && decision !== "SKIP"; + return rememberChoice && decision !== "SKIP" && decision !== "APP"; } export function guardIdleDecisionFeedback( @@ -32,6 +32,16 @@ export function guardIdleDecisionFeedback( rememberChoice: boolean, tx: TranslateFn, ): GuardIdleDecisionFeedback { + if (decision === "APP") { + return { + type: "ok", + text: tx( + "已将该时段归入无输入前使用的应用。", + "This segment is attributed to the app used before the idle period.", + ), + }; + } + if (decision === "LEARN") { return { type: "ok", From 23f7061203aa2d713a9bffe42b6204d882900016 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:33:58 +0800 Subject: [PATCH 092/117] feat(idle): expose app attribution to view contexts --- src/components/viewContexts.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/components/viewContexts.ts b/src/components/viewContexts.ts index 77c7ce3..da71b05 100644 --- a/src/components/viewContexts.ts +++ b/src/components/viewContexts.ts @@ -19,7 +19,7 @@ import type { ThemeMode } from "../composables/useThemeMode"; export type TranslateFn = (zh: string, en: string) => string; export type AllTimeFilter = UsageRootFilter; export type RuleMappedType = AppRuleMappedType; -export type IdleDecision = "LEARN" | "REST" | "IDLE" | "SKIP"; +export type IdleDecision = "APP" | "LEARN" | "REST" | "IDLE" | "SKIP"; export type RuleSortKey = "alpha_asc" | "alpha_desc" | "time_desc" | "time_asc"; export type FeedbackTone = "info" | "ok" | "warn" | "error"; @@ -105,6 +105,7 @@ export type IdlePromptBannerContext = { tx: TranslateFn; currentIdlePrompt: IdlePrompt; formatIdlePromptSpan: (item: IdlePrompt) => string; + cleanProcessName: (name: string) => string; idleRememberChoice: boolean; onIdleRememberChoiceChange: (event: Event) => void; idleActionLoading: boolean; From 7c165bed5ec60101103451bcde08ab82b04d0e1a Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:34:41 +0800 Subject: [PATCH 093/117] feat(idle): pass app name formatter to idle banner --- src/composables/useIdlePromptBannerContext.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/composables/useIdlePromptBannerContext.ts b/src/composables/useIdlePromptBannerContext.ts index e7f71ac..2d4a068 100644 --- a/src/composables/useIdlePromptBannerContext.ts +++ b/src/composables/useIdlePromptBannerContext.ts @@ -9,6 +9,7 @@ type IdlePromptBannerContextOptions = { tx: TranslateFn; currentIdlePrompt: Readonly>; formatIdlePromptSpan: IdlePromptBannerContext["formatIdlePromptSpan"]; + cleanProcessName: IdlePromptBannerContext["cleanProcessName"]; idleRememberChoice: Readonly>; onIdleRememberChoiceChange: IdlePromptBannerContext["onIdleRememberChoiceChange"]; idleActionLoading: Readonly>; @@ -19,6 +20,7 @@ export function useIdlePromptBannerContext({ tx, currentIdlePrompt, formatIdlePromptSpan, + cleanProcessName, idleRememberChoice, onIdleRememberChoiceChange, idleActionLoading, @@ -33,6 +35,7 @@ export function useIdlePromptBannerContext({ tx, currentIdlePrompt: currentIdlePrompt.value, formatIdlePromptSpan, + cleanProcessName, idleRememberChoice: idleRememberChoice.value, onIdleRememberChoiceChange, idleActionLoading: idleActionLoading.value, From 6558b0237a70ae0184072f13d5e52c3477ce8c6a Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:35:55 +0800 Subject: [PATCH 094/117] refactor(idle): keep banner context minimal --- src/components/viewContexts.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/components/viewContexts.ts b/src/components/viewContexts.ts index da71b05..2199b1d 100644 --- a/src/components/viewContexts.ts +++ b/src/components/viewContexts.ts @@ -105,7 +105,6 @@ export type IdlePromptBannerContext = { tx: TranslateFn; currentIdlePrompt: IdlePrompt; formatIdlePromptSpan: (item: IdlePrompt) => string; - cleanProcessName: (name: string) => string; idleRememberChoice: boolean; onIdleRememberChoiceChange: (event: Event) => void; idleActionLoading: boolean; From d10272832ddfb256b5f77547c452c5cfd647d554 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:36:08 +0800 Subject: [PATCH 095/117] refactor(idle): keep banner formatter local --- src/composables/useIdlePromptBannerContext.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/composables/useIdlePromptBannerContext.ts b/src/composables/useIdlePromptBannerContext.ts index 2d4a068..e7f71ac 100644 --- a/src/composables/useIdlePromptBannerContext.ts +++ b/src/composables/useIdlePromptBannerContext.ts @@ -9,7 +9,6 @@ type IdlePromptBannerContextOptions = { tx: TranslateFn; currentIdlePrompt: Readonly>; formatIdlePromptSpan: IdlePromptBannerContext["formatIdlePromptSpan"]; - cleanProcessName: IdlePromptBannerContext["cleanProcessName"]; idleRememberChoice: Readonly>; onIdleRememberChoiceChange: IdlePromptBannerContext["onIdleRememberChoiceChange"]; idleActionLoading: Readonly>; @@ -20,7 +19,6 @@ export function useIdlePromptBannerContext({ tx, currentIdlePrompt, formatIdlePromptSpan, - cleanProcessName, idleRememberChoice, onIdleRememberChoiceChange, idleActionLoading, @@ -35,7 +33,6 @@ export function useIdlePromptBannerContext({ tx, currentIdlePrompt: currentIdlePrompt.value, formatIdlePromptSpan, - cleanProcessName, idleRememberChoice: idleRememberChoice.value, onIdleRememberChoiceChange, idleActionLoading: idleActionLoading.value, From 6ee3ff49973211d716faad1bce44e2e3c7da2080 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:37:04 +0800 Subject: [PATCH 096/117] feat(idle): add progressive idle attribution banner --- src/components/IdlePromptBanner.vue | 113 +++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 11 deletions(-) diff --git a/src/components/IdlePromptBanner.vue b/src/components/IdlePromptBanner.vue index 2a8c8a0..71f22a1 100644 --- a/src/components/IdlePromptBanner.vue +++ b/src/components/IdlePromptBanner.vue @@ -1,23 +1,114 @@ From acda1d865aa13d2e4174a363bf956589211e7d99 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:37:58 +0800 Subject: [PATCH 097/117] feat(idle): simplify attribution choices in guard --- src/components/GuardView.vue | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/src/components/GuardView.vue b/src/components/GuardView.vue index e8c8fa2..cf4e544 100644 --- a/src/components/GuardView.vue +++ b/src/components/GuardView.vue @@ -67,11 +67,38 @@ const props = defineProps<{ ctx: GuardViewContext }>();
{{ props.ctx.formatIdlePromptSpan(item) }}
-
+
+ + {{ props.ctx.tx("无输入前：", "Before inactivity: ") }} + {{ props.ctx.cleanProcessName(item.attribution_process_name) }} + +
+ +
+ + +
+ {{ props.ctx.tx("其他…", "Other…") }} +
+ + + +
+
+
+ +
- - + +
+ {{ props.ctx.tx("其他…", "Other…") }} +
+ +
+
  • {{ props.ctx.tx("暂无待确认离开时段", "No idle segments pending") }}
    • From 75a40f0e0f4c539d6d91b58981084781a335e420 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:38:22 +0800 Subject: [PATCH 098/117] feat(pet): carry idle attribution candidate --- src/lib/petPrompts.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/lib/petPrompts.ts b/src/lib/petPrompts.ts index 6ae1805..7c21294 100644 --- a/src/lib/petPrompts.ts +++ b/src/lib/petPrompts.ts @@ -3,6 +3,7 @@ export type IdlePromptLite = { start_timestamp: number; end_timestamp: number; duration_ms: number; + attribution_process_name?: string | null; }; export type PendingRuleProcessLite = { From 8f72ebbfc41ebb8103272a7e8f174ac595fe6512 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:38:57 +0800 Subject: [PATCH 099/117] feat(pet): simplify idle attribution prompt --- src/lib/petPromptDescriptors.ts | 66 +++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/src/lib/petPromptDescriptors.ts b/src/lib/petPromptDescriptors.ts index 643b7e2..65991b3 100644 --- a/src/lib/petPromptDescriptors.ts +++ b/src/lib/petPromptDescriptors.ts @@ -7,13 +7,14 @@ import type { } from "./petPrompts"; type TranslateFn = (zh: string, en: string) => string; -type IdleDecision = "LEARN" | "REST" | "IDLE" | "SKIP"; +type IdleDecision = "APP" | "LEARN" | "REST" | "IDLE" | "SKIP"; type RuleMappedType = AppRuleMappedType; type PetPromptDescriptorActions = { completeReminder: (reminder: ReminderLite) => Promise; snoozeReminder: (reminder: ReminderLite) => Promise; resolveIdle: (idle: IdlePromptLite, decision: IdleDecision, promptKey: string) => Promise; + openIdleDetails: (idle: IdlePromptLite) => Promise; saveRule: (processName: string, mappedType: RuleMappedType) => Promise; postponeRule: (promptKey: string) => Promise; }; @@ -62,31 +63,50 @@ export function buildPetPromptDescriptors({ for (const idle of idleItems) { const idleSeconds = Math.max(0, Math.floor(idle.duration_ms / 1000)); const key = `idle-${idle.id}`; + const processName = idle.attribution_process_name ?? ""; + const appName = processName ? cleanProcessName(processName) : ""; + descriptors.push({ key, title: tx("离开时段待确认", "Idle Segment Confirmation"), - detail: tx( - `持续 ${formatSeconds(idleSeconds)}，请尽快归类`, - `${formatSeconds(idleSeconds)} idle time, please classify`, - ), - actions: [ - { - label: tx("学习", "Learn"), - run: () => actions.resolveIdle(idle, "LEARN", key), - }, - { - label: tx("休息", "Break"), - run: () => actions.resolveIdle(idle, "REST", key), - }, - { - label: tx("离开", "Away"), - run: () => actions.resolveIdle(idle, "IDLE", key), - }, - { - label: tx("稍后提醒", "Remind later"), - run: () => actions.resolveIdle(idle, "SKIP", key), - }, - ], + detail: appName + ? tx( + `${formatSeconds(idleSeconds)} 无输入 · 之前在 ${appName}`, + `${formatSeconds(idleSeconds)} inactive · previously ${appName}`, + ) + : tx( + `持续 ${formatSeconds(idleSeconds)}，请选择实际状态`, + `${formatSeconds(idleSeconds)} inactive, choose what happened`, + ), + actions: appName + ? [ + { + label: tx(`继续 ${appName}`, `Continue ${appName}`), + run: () => actions.resolveIdle(idle, "APP", key), + }, + { + label: tx("离开", "Away"), + run: () => actions.resolveIdle(idle, "IDLE", key), + }, + { + label: tx("其他…", "Other…"), + run: () => actions.openIdleDetails(idle), + }, + ] + : [ + { + label: tx("学习", "Learn"), + run: () => actions.resolveIdle(idle, "LEARN", key), + }, + { + label: tx("休息", "Break"), + run: () => actions.resolveIdle(idle, "REST", key), + }, + { + label: tx("离开", "Away"), + run: () => actions.resolveIdle(idle, "IDLE", key), + }, + ], }); } From 6e95509ca552768cc5cef018db4356921ae76dde Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:40:53 +0800 Subject: [PATCH 100/117] feat(pet): route idle attribution other choice to guard --- src/pet.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/pet.ts b/src/pet.ts index 9e2db50..533e507 100644 --- a/src/pet.ts +++ b/src/pet.ts @@ -264,7 +264,9 @@ async function refreshPromptBubble() { await invoke("resolve_idle_prompt", { input: { prompt_id: idle.id, decision, remember_this_session: false }, }); - if (decision === "LEARN") { + if (decision === "APP") { + setTransientMood(tx("已归入之前使用的应用", "Attributed to previous app")); + } else if (decision === "LEARN") { setTransientMood(tx("已标记为学习", "Marked as Learn")); } else if (decision === "REST") { setTransientMood(tx("已标记为休息", "Marked as Break")); @@ -275,6 +277,11 @@ async function refreshPromptBubble() { } await refreshPromptBubble(); }, + openIdleDetails: async (idle) => { + await invoke("show_main_window_section", { section: "guard" }); + promptSnoozeUntilByKey.set(`idle-${idle.id}`, Date.now() + 60_000); + await refreshPromptBubble(); + }, saveRule: async (processName, mappedType) => { await invoke("save_app_rule", { input: { process_name: processName, mapped_type: mappedType, privacy_level: "NORMAL" }, @@ -577,4 +584,3 @@ window.addEventListener("beforeunload", () => { clearMoodResetTimer(); closeContextMenu(); }); - From 03e472f4d5b8e46a5d89e085a600aec2b32373e1 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:42:44 +0800 Subject: [PATCH 101/117] test(idle): forbid attribution privacy bypass --- src-tauri/src/services/usage.rs | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src-tauri/src/services/usage.rs b/src-tauri/src/services/usage.rs index 1ed53eb..f45536c 100644 --- a/src-tauri/src/services/usage.rs +++ b/src-tauri/src/services/usage.rs @@ -175,6 +175,11 @@ mod tests { let conn = Connection::open_in_memory().expect("open in-memory usage db"); conn.execute_batch( r#" + CREATE TABLE app_config ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL + ); + CREATE TABLE app_rules ( process_name TEXT PRIMARY KEY, mapped_type TEXT NOT NULL, @@ -183,6 +188,10 @@ mod tests { updated_at INTEGER NOT NULL DEFAULT 0 ); + CREATE TABLE app_whitelist ( + process_name TEXT PRIMARY KEY + ); + CREATE TABLE app_usage_logs ( id INTEGER PRIMARY KEY AUTOINCREMENT, process_name TEXT NOT NULL, @@ -326,4 +335,31 @@ mod tests { .expect("query app rule"); assert_eq!(mapped_type, "REST"); } + + #[test] + fn idle_app_decision_cannot_bypass_curtain_privacy() { + let conn = usage_test_conn(); + conn.execute( + "INSERT INTO app_config (key, value) VALUES ('curtain_enabled', 'true')", + [], + ) + .expect("enable curtain"); + + let prompt = IdlePromptEntry { + id: 3, + start_timestamp: 300, + end_timestamp: 600, + duration_ms: 300_000, + deferred_until_timestamp: None, + attribution_process_name: Some("code.exe".to_string()), + }; + + let result = persist_idle_prompt_app_decision(&conn, &prompt, "code.exe"); + assert!(result.is_err(), "privacy curtain must block app attribution"); + + let count: i64 = conn + .query_row("SELECT COUNT(*) FROM app_usage_logs", [], |row| row.get(0)) + .expect("count usage rows"); + assert_eq!(count, 0); + } } From b17e63360b79ca9b4beaffa4b4cfd12edd388450 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:48:54 +0800 Subject: [PATCH 102/117] fix(idle): enforce privacy before app attribution --- src-tauri/src/services/usage.rs | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src-tauri/src/services/usage.rs b/src-tauri/src/services/usage.rs index f45536c..4ca5741 100644 --- a/src-tauri/src/services/usage.rs +++ b/src-tauri/src/services/usage.rs @@ -133,11 +133,20 @@ pub(crate) fn persist_idle_prompt_app_decision( prompt: &IdlePromptEntry, process_name: &str, ) -> Result { + let (processed, block_reason) = + process_log_with_privacy(conn, process_name, "Idle Confirmed · Previous App")?; + let Some((safe_process_name, safe_window_title)) = processed else { + let reason = block_reason.unwrap_or_else(|| "privacy_policy".to_string()); + return Err(format!( + "idle app attribution blocked by privacy policy: {reason}" + )); + }; + replace_idle_interval_with_usage( conn, prompt, - process_name, - "Idle Confirmed · Previous App", + &safe_process_name, + &safe_window_title, None, ) } From b5791e16b047b63332ef36507d4421d9e2d9ed8b Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:51:34 +0800 Subject: [PATCH 103/117] fix(idle): restore prompt when attribution persistence fails --- src-tauri/src/services/foreground.rs | 53 +++++++++++++++------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/src-tauri/src/services/foreground.rs b/src-tauri/src/services/foreground.rs index 7874d16..99eb59d 100644 --- a/src-tauri/src/services/foreground.rs +++ b/src-tauri/src/services/foreground.rs @@ -395,21 +395,6 @@ pub(crate) fn resolve_idle_prompt( return Ok(false); } - if decision == "APP" { - let state = FOREGROUND_SAMPLE_STATE - .lock() - .map_err(|e| format!("failed to lock foreground sample state: {e}"))?; - let has_candidate = state - .pending_idle_prompts - .iter() - .find(|item| item.id == input.prompt_id) - .and_then(|item| item.attribution_process_name.as_ref()) - .is_some(); - if !has_candidate { - return Err("idle prompt has no previous-app attribution candidate".to_string()); - } - } - let prompt = { let mut state = FOREGROUND_SAMPLE_STATE .lock() @@ -424,15 +409,35 @@ pub(crate) fn resolve_idle_prompt( let Some(prompt) = prompt else { return Ok(false); }; - let conn = open_connection(app)?; - let stored = if decision == "APP" { - let process_name = prompt - .attribution_process_name - .as_deref() - .ok_or_else(|| "idle prompt has no previous-app attribution candidate".to_string())?; - persist_idle_prompt_app_decision(&conn, &prompt, process_name)? - } else { - persist_idle_prompt_decision(&conn, &prompt, &decision)? + + let persist_result = (|| -> Result { + let conn = open_connection(app)?; + if decision == "APP" { + let process_name = prompt + .attribution_process_name + .as_deref() + .ok_or_else(|| "idle prompt has no previous-app attribution candidate".to_string())?; + persist_idle_prompt_app_decision(&conn, &prompt, process_name) + } else { + persist_idle_prompt_decision(&conn, &prompt, &decision) + } + })(); + + let stored = match persist_result { + Ok(stored) => stored, + Err(err) => { + let mut state = FOREGROUND_SAMPLE_STATE + .lock() + .map_err(|e| format!("failed to restore idle prompt after persistence failure: {e}"))?; + if !state.pending_idle_prompts.iter().any(|item| item.id == prompt.id) { + state.pending_idle_prompts.push(prompt); + if state.pending_idle_prompts.len() > 20 { + let drop_count = state.pending_idle_prompts.len() - 20; + state.pending_idle_prompts.drain(0..drop_count); + } + } + return Err(err); + } }; if remember_this_session && matches!(decision.as_str(), "LEARN" | "REST" | "IDLE") { From 3ba2267fc2415dfd33f3ad2e1e85e235f34d8ee2 Mon Sep 17 00:00:00 2001 From: Air000000 <73988854+Air000000@users.noreply.github.com> Date: Fri, 11 Sep 2026 20:54:47 +0800 Subject: [PATCH 104/117] docs(ui): explain idle app attribution semantics --- src/components/IdlePromptBanner.vue | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/components/IdlePromptBanner.vue b/src/components/IdlePromptBanner.vue index 71f22a1..7379c44 100644 --- a/src/components/IdlePromptBanner.vue +++ b/src/components/IdlePromptBanner.vue @@ -47,6 +47,14 @@ watch( ) }}

    +

    + {{ + props.ctx.tx( + `选择“继续使用 ${attributionAppName}”会把整段归入该应用，并沿用它现有的学习 / 休息 / 未分类规则。`, + `Choosing “Continue ${attributionAppName}” attributes the whole segment to that app and keeps its existing Learn / Break / Unclassified rule.`, + ) + }} +

    -
    +
    -
    - - - -
    - {{ props.ctx.tx("其他…", "Other…") }} -
    - -
    -
    -
    +
  • {{ props.ctx.tx("暂无待确认离开时段", "No idle segments pending") }}
    • @@ -173,3 +170,31 @@ const props = defineProps<{ ctx: GuardViewContext }>(); + + diff --git a/src/components/IdlePromptBanner.vue b/src/components/IdlePromptBanner.vue index 7379c44..a157ae3 100644 --- a/src/components/IdlePromptBanner.vue +++ b/src/components/IdlePromptBanner.vue @@ -83,10 +83,10 @@ watch( - +
    +