快速开始

1. 环境要求

项

要求

检查命令

Python

>= 3.13

python --version

uv

任意版本

uv --version

Git LFS

可选（用于匿名基线库 D）

git lfs version

操作系统

Windows / Linux / macOS

uname -s

2. 首次启动

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

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

start.sh 会自动完成 11 个阶段（详见 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. 常用启动变体

./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. 下一步