项目结构

模板先按边界划分——沙箱前端（src/）、特权 Rust 核心（src-tauri/）、以及两侧都读取的跨领域品牌/配置（shared/）——再在每一侧内部按功能划分。

顶层布局

App.tsx

main.tsx

tauri.conf.json

Cargo.toml

vite.config.ts

src/ 是沙箱化的 React SPA。它使用 HashRouter、懒加载路由、TanStack Query、 zustand store、i18next 与 shadcn/ui 组件。

路径	职责
`src/main.tsx`	浏览器入口：校验 Supabase env，再挂载 `App` 或独立的配置错误屏。
`src/App.tsx`	路由树、Provider、应用意图导航、分析路由跟踪、引导门。
`src/routes/`	首页、设置、账户、订阅、关于、日志、帮助、更新、未找到/错误，以及 `auth/` 页面和 `showcase/` 路由。
`src/components/`	外壳 + 侧边栏（`layout/`）、`window/` 标题栏、`command-palette/`、`onboarding/`、`billing/` 与 `ui/` 组件。
`src/services/`	纯 Supabase / Edge Function 调用：`todos`、`profile`、`avatar`、`subscription`、`billing`、`license/`、`analytics`、`error-reporting`。
`src/stores/`	`auth-store` 与 `subscription-store`（zustand）。
`src/showcase/`	`[template-demo]` 能力目录及其类型。
`src/locales/`	`en/` 与 `zh/` JSON 目录（`common`、`auth`、`settings`、`showcase`）。

模块	职责
`lib/tauri/`	对生成绑定的类型化按域封装（`app`、`window`、`secure`、`logs`、`file`、`diagnostics`、`update`），以及 `events.ts` 与 `external-url.ts`。
`lib/bindings.ts`	生成并提交的 `tauri-specta` 类型——切勿手改（见下文）。
`lib/settings/`	Zod `schema`、版本化 `store` 与 `backup` 导入/导出。
`lib/intents/`	`parse` → `dispatcher` 深链/argv 意图，按 `routes.ts` 校验。
`lib/menu/` + `lib/tray/`	原生菜单与托盘，用 TypeScript 构建（Tauri v2 JS API）。
`lib/updates/`	更新 `scheduler`（后台检查节奏）。
`lib/supabase/`	客户端、`env` 校验、类型化 `database.types.ts`、钥匙串会话存储。
`lib/auth/`、`lib/i18n/`、`lib/query/`、`lib/logging/`、`lib/notifications.ts`、`lib/shortcuts.ts`	认证 schema、i18next 引导、查询客户端、脱敏日志、通知与快捷键注册表。
`lib/conveyor/`	从 Electron 模板沿用的移植兼容 shim（见 IPC 的说明）。

src-tauri/src/ 拥有一切特权操作；webview 从不直接触碰 OS。

路径	职责
`src/main.rs`	调用 `run()` 的极简二进制入口。
`src/lib.rs`	注册插件（single-instance 最先）、setup 钩子与 `tauri-specta` 命令 builder。
`src/commands/`	按域划分的命令模块：`app`、`secure`、`logs`、`window`、`diagnostics`、`update`，以及 `redaction.rs`。
`src/error_reporting.rs`	可选的 Rust 侧 Sentry 初始化，带 payload 脱敏。
`capabilities/default.json`	作用于 `main` 窗口的能力 ACL。
`tauri.conf.json`	窗口、CSP、bundle、updater 与深链配置。
`Cargo.toml`	Rust 依赖与 crate feature。
`icons/`	生成的应用图标（`pnpm tauri icon`）。

路径	职责
`shared/constants.ts`	唯一的品牌身份来源（app id、名称、slug、协议、支持/仓库 URL、EULA）。
`shared/config.ts`	中心化 env 读取枢纽：`features`、`billingConfig`、`showcaseConfig`、分析/Sentry 配置。其他地方都不读 `import.meta.env`。
`shared/feature-flags.ts` / `shared/price-config.ts`	原生开关 payload 形状与 Creem 产品 → 层级映射。
`supabase/migrations/` + `supabase/functions/`	提交的 SQL 与 Edge Functions（计费 schema 与 Electron 共享；见 Supabase 配置）。
`resources/`	托盘/图标源素材。
`scripts/`	`rebrand.mjs` 与 `deploy-edge-functions.sh`。
`test/e2e/`	独立的 WebdriverIO + `tauri-driver` 套件，带自己的 `package.json`。
`docs/`	`CUSTOMIZE`、`CAPABILITIES`、`APP_ICONS`、`RELEASE`。

@/ → src/，@/shared/ → shared/（在 vite.config.ts 中把更具体的 @/shared 别名排在前面以胜出）。
TypeScript 使用项目引用：tsconfig.web.json（前端 + shared + test）与 tsconfig.node.json，由根 tsconfig.json 组合。
Vite 使用固定开发端口 1420（strictPort），并将 src-tauri/ 从其 watcher 中排除，使 Rust 改动不会扰动前端。

src/lib/bindings.ts 是从 Rust 命令生成并提交的。它在每次 pnpm dev 与 export_bindings 这个 cargo test 时重新生成，任何漂移都会使 CI 失败。请在 Rust 中修改命令，让该文件自动重写——切勿手改。

测试以 *.test.ts(x) 就近放在被测代码旁。pnpm test（test:core）在 jsdom 下运行快速逻辑套件；pnpm test:all 运行全部。Rust 测试在 crate 内，用 cargo test 运行。
演示代码以 [template-demo] 标记。先用 VITE_SHOWCASE_ENABLED=false 预览应用，再按 Showcase 删除 src/showcase/ 与 src/routes/showcase/ 并清理列举的接触点。