常见问题排查（构建、数据库、数据重置、调试）

1) 构建/依赖下载失败

现象：

  • cargo build / cargo run 下载 crates 失败
  • 报错类似 “couldn't resolve host / failed to download”

原因：

  • 网络环境无法访问 crates.io 或 DNS/代理问题

解决建议：

  • 确认网络可访问 crates（必要时配置代理）
  • CI 环境确保网络稳定
  • 先用 cargo check 快速定位类型问题（避免每次都 full build）

2) 应用能启动，但数据“看起来丢了”

常见原因：

  • 你切换了 DB 路径（设置了 ASSET_LIGHT_DB_PATH）
  • 迁移发生了破坏性升级，表被 drop（学习期允许）

排查步骤：

  1. 检查是否设置了 ASSET_LIGHT_DB_PATH
  2. 查看 src/db/connection.rs 的 run_migrations() 是否 drop 过表（schema_version < 2）

3) 想要重置数据（不影响真实 DB）

推荐方式：换一个临时 DB 路径启动

ASSET_LIGHT_DB_PATH=/tmp/asset-light-dev.db cargo run

4) UI 没刷新/数据没更新

排查思路：

  • 写库成功后是否刷新 state？
    • 例如保存资产后是否调用 AssetRepository::find_all() 并写入 state.assets
  • 是否存在“读写借用作用域过长”导致逻辑没执行到？
    • 尽量缩小 .read()/.write() 的使用范围

5) 快照创建中途失败，数据不一致

现状：

  • SnapshotRepository::create() 是“多步写入”（主表 + N 条明细）
  • 目前未显式使用事务

建议：

  • 用 rusqlite transaction 改为原子操作（见 docs/rust-guide/07-sqlite-and-rusqlite.md）

6) 如何快速定位某个功能在哪实现

建议从“页面入口”反查：

  • 路由：src/router.rs
  • 页面：src/pages/*.rs
  • 页面组合组件：src/components/*
  • 数据访问：src/db/*_repo.rs
  • 领域模型：src/models/*
  • 计算逻辑：src/services/*

7) 调试建议（学习期最实用）

  • 先用 println!/eprintln! 快速定位数据流（之后再引入日志库）
  • 在关键写入点打印：
    • “写库前数据是什么”
    • “写库结果是什么”
    • “刷新 state 后数据长度/关键字段是什么”