# 快速开始

## 1. 环境要求

| 项 | 要求 | 检查命令 |
|----|------|----------|
| Python | >= 3.13 | `python --version` |
| uv | 任意版本 | `uv --version` |
| Git LFS | 可选（用于匿名基线库 D） | `git lfs version` |
| 操作系统 | Windows / Linux / macOS | `uname -s` |

## 2. 首次启动

```bash
# 1. 克隆仓库
git clone <repo-url> CertFlow
cd CertFlow

# 2. 一键启动（推荐）
./start.sh
```

`start.sh` 会自动完成 11 个阶段（详见 [`02-architecture.md`](./02-architecture.md) §启动流程）：

1. 环境检查（平台 / .env / 目录 / 数据文件 / 配置文件 / 模板 / 数据库 / 权限）
2. 设置 UTF-8 编码（`PYTHONUTF8=1`）
3. Windows 控制台切到 65001 代码页
4. 加载 `scripts/lib/*.sh` 核心模块
5. 检查 uv
6. 显示环境信息
7. 同步依赖（`uv sync --group dev --group lint`）
8. pre-commit 钩子安装
9. Git LFS 检测
10. 调试库处理（四库模型 A/B/C/D）
11. 启动主程序（`uv run python -m certflow.main`）

## 3. 常用启动变体

```bash
./start.sh --check-only      # 仅环境检查，不启动主程序
./start.sh --reset           # 重置调试库 B（从基线 C/D 重建）
./start.sh --headless-test   # 无头测试模式（offscreen 后端）
```

## 4. 配置环境变量

复制 `.env.example` 为 `.env`，按需填写：

| 变量 | 用途 | 默认 |
|------|------|------|
| `VALVE_SALES_PLAN_PATH` | 销售计划 Excel 路径 | 无 |
| `NUTSTORE_WEBDAV_USER` | 坚果云 WebDAV 用户 | 无（跳过远程同步） |
| `NUTSTORE_WEBDAV_TOKEN` | 坚果云 WebDAV 密码 | 无 |
| `VALVE_DEBUG` | 调试模式 | false |
| `VALVE_SEED_DEBUG` | 播种明细日志 | 跟随 VALVE_DEBUG |
| `CERTFLOW_DB_PATH` | 数据库路径覆盖 | database/debug/certflow-debug.db |
| `CERTFLOW_RESET` | 启动时重置调试库 | 0 |

## 5. 首跑验证

1. 启动后看到主窗口标题 `CertFlow - 阀门合格证管理系统`
2. 状态栏显示 `✅ 系统就绪`
3. 若数据库为空，会自动播种基础字典（材质/型号压力/口径）
4. 日志输出到 `logs/` 目录，启动调试日志 `logs/start_debug_*.log`

## 6. 下一步

- 日常操作流程：[`04-operator-guide.md`](./04-operator-guide.md)
- CLI 命令速查：[`05-cli-reference.md`](./05-cli-reference.md)
- 配置项详解：[`03-configuration.md`](./03-configuration.md)