Scripts 目录说明¶

scripts/ 目录包含项目的所有辅助脚本，按功能分为以下 7 个子目录。

路径定位机制：所有脚本不依赖自身所在目录推导项目根目录，而是通过统一的定位策略（CERTFLOW_ROOT 环境变量 → git rev-parse --show-toplevel → 向上查找 pyproject.toml → 回退兼容）。

目录¶

scripts/lib/ — Shell/Python 公共库
scripts/setup/ — 环境初始化
scripts/build/ — 打包与构建
scripts/data/ — 数据导入与回填
scripts/query/ — 查询与导出
scripts/ui/ — UI 开发
scripts/docs/ — 文档与辅助工具

1. scripts/lib/ — Shell/Python 公共库¶

被其他脚本通过 source 或 import 引用，提供公共变量、函数和工具。

脚本	类型	用途	被引用者
`core.sh`	Shell	颜色变量、日志函数、`get_project_root()`	所有 Shell 脚本
`env.sh`	Shell	从 `.env` / `.env.example` 加载环境变量	`setup_uv.sh`、`setup_precommit.sh`
`python.sh`	Shell	按优先级查找 Python 可执行文件	`setup_uv.sh`、`setup_precommit.sh`
`_project_root.py`	Python	统一的 `get_project_root()` / `setup_path()`	所有 Python 脚本

get_project_root() 定位策略：

环境变量 CERTFLOW_ROOT
git rev-parse --show-toplevel
向上查找包含 pyproject.toml 的目录
BASH_SOURCE / __file__ 回退兼容

调用关系：

scripts/lib/
  ├── core.sh          ← 颜色、日志、get_project_root()
  ├── env.sh           ← source core.sh, 加载 .env
  ├── python.sh        ← source core.sh, 检测 Python
  └── _project_root.py ← Python 版 get_project_root() / setup_path()

2. scripts/setup/ — 环境初始化¶

首次克隆项目后，执行本组脚本搭建完整开发环境。

脚本	类型	用途
`init.sh`	Shell	一站式入口，依次执行 `setup_uv.sh` → 创建目录 → `setup_precommit.sh`
`setup_uv.sh`	Shell	安装 `uv`，创建 `.venv`，同步 `pyproject.toml` 依赖
`setup_env.sh`	Shell	按场景安装依赖组：`prod` / `dev` / `docs` / `lint` / `typing` / `full` / `ci`
`setup_dirs.sh`	Shell	创建完整的项目目录骨架
`create_config.sh`	Shell	创建配置目录和模板文件
`setup_precommit.sh`	Shell	安装 Git pre-commit 钩子

调用关系：

init.sh
  ├── setup_uv.sh ────── 依赖 core.sh, env.sh, python.sh
  ├── (mkdir -p 创建目录)
  └── setup_precommit.sh ─ 依赖 core.sh, env.sh, python.sh

使用示例：

# 完整初始化
bash scripts/setup/init.sh

# 跳过 pre-commit 钩子
bash scripts/setup/init.sh --no-precommit

# 按场景安装依赖
bash scripts/setup/setup_env.sh dev

3. scripts/build/ — 打包与构建¶

将项目打包为 Windows 独立可执行文件。默认使用 Nuitka（编译为原生机器码，体积更小），可通过 --pyinstaller 切换。

脚本	类型	用途
`build_exe.py`	Python	核心打包脚本。Git 分支隔离、环境验证、Nuitka 编译（默认）/ PyInstaller 打包、复制配置、生成启动文件
`build.bat`	Batch	Windows 入口，设置控制台编码，调用 `build_exe.py`（Nuitka 默认）
`build.sh`	Shell	Linux/macOS/Git Bash 入口，激活 `.venv`，验证依赖，调用 `build_exe.py`
`clean_for_build.sh`	Shell	打包前精细清理，支持 `--dry-run`
`clean.sh`	Shell	简化版清理，删除 `__pycache__`、`build/`、`dist/`、缓存目录

调用关系：

build.bat ──→ build_exe.py
build.sh  ──→ build_exe.py
                  ├── GitManager (创建/切换/删除分支)
                  ├── FileCleaner (清理不必要文件)
                  ├── run_nuitka() → Nuitka（默认）
                  │    └── dist/main.dist/ → dist/CertFlow/
                  ├── run_pyinstaller() → PyInstaller（--pyinstaller）
                  └── copy_config_files() / create_startup_files()

使用示例：

# Windows（Nuitka 默认）
scripts\builder\build.bat

# Linux / macOS / Git Bash（Nuitka 默认）
bash scripts/builder/build.sh

# 切换为 PyInstaller
bash scripts/builder/build.sh --pyinstaller

# 跳过 Git 分支隔离
python scripts/builder/build_exe.py --no-git

# 仅清理，不打包
python scripts/builder/build_exe.py --clean-only

4. scripts/data/ — 数据导入与回填¶

从 Excel 文件批量处理销售数据到数据库。

脚本	类型	用途
`import_sales_plan.py`	Python	主要导入工具。从 Excel 各月份工作表导入销售计划到 `sale_plans` 表
`backfill_supply_type.py`	Python	从"已完成工单"Excel 读取"供货类型"，按生产令号回填到数据库
`match_update_from_excel.py`	Python	从合格证 Excel 读取"产品编号"，按生产令号匹配并更新 `product_code`（一次性任务）

调用关系：

import_sales_plan.py ──── SalePlanService.import_from_excel_with_config()
backfill_supply_type.py ─ SalePlan (ORM) + DatabaseManager (直接更新)
match_update_from_excel.py ─ SalePlan (ORM) + 硬编码路径

使用示例：

# 列出 Excel 中的工作表
python scripts/data/import_sales_plan.py --file data/销售计划.xlsx --list-sheets

# 导入所有月份
python scripts/data/import_sales_plan.py --file data/销售计划.xlsx --all-sheets

# 回填供货类型（先试运行）
python scripts/data/backfill_supply_type.py --dry-run --verbose

5. scripts/query/ — 查询与导出¶

命令行数据查询工具，是主应用 GUI 查询功能的补充。

脚本	类型	用途
`quick_query.py`	Python	按客户/产品/订单/状态查询销售数据，显示统计图表，导出 Excel

依赖：certflow.services.QueryService、tabulate

使用示例：

# 列出所有客户
python scripts/query/quick_query.py --list-customers

# 模糊搜索
python scripts/query/quick_query.py --customer "华" --status "生产中"

# 导出结果
python scripts/query/quick_query.py --customer "腾讯" --export result.xlsx

6. scripts/ui/ — UI 开发¶

PySide6 Qt Designer 的编辑与编译工具。

脚本	类型	用途
`compile_ui.py`	Python	将 `src/certflow/ui/designer/.ui` 编译为 `src/certflow/ui/generated/ui_.py`
`designer.sh`	Shell	启动 PySide6 Qt Designer，支持自动打开最近修改的 UI 文件

工作流：

designer.sh (编辑 UI) → 保存 .ui 文件 → compile_ui.py (编译为 Python)

compile_ui.py 还支持 --watch 开发模式，使用 watchdog 自动监听 .ui 变化并即时编译。

7. scripts/docs/ — 文档与辅助工具¶

脚本	类型	用途
`generate_db_schema.py`	Python	从 SQLAlchemy `SalePlan` 模型生成 `docs/DATABASE_SCHEMA.md`
`docs_helper.sh`	Shell	Sphinx 文档构建：`build` / `serve`（实时预览）/ `clean` / `status`
`check_coverage.py`	Python	运行 `pytest --cov` 并解析覆盖率百分比
`tree_structure.py`	Python	递归打印项目目录树
`test_import.py`	Python	早期开发验证脚本

使用示例：

# 生成数据库 Schema 文档
python scripts/docs/generate_db_schema.py

# 构建 Sphinx 文档并启动实时预览
bash scripts/docs/docs_helper.sh build
bash scripts/docs/docs_helper.sh serve

# 查看项目目录树
python scripts/docs/tree_structure.py

总结¶

scripts/
├── lib/                        # Shell/Python 公共库
│   ├── core.sh                 颜色 & 日志 & get_project_root()
│   ├── env.sh                  环境变量加载
│   ├── python.sh               Python 查找
│   └── _project_root.py        Python 版项目根目录定位
│
├── setup/                      # 环境初始化（首次使用）
│   ├── init.sh                 ★ 一站式入口
│   ├── setup_uv.sh             创建虚拟环境
│   ├── setup_env.sh            按场景安装依赖
│   ├── setup_dirs.sh           创建目录结构
│   ├── create_config.sh        创建配置文件模板
│   └── setup_precommit.sh      配置 Git 钩子
│
├── builder/                      # 打包与构建
│   ├── build_exe.py            ★ 核心打包脚本（Nuitka 默认 / PyInstaller 备选）
│   ├── build.bat               Windows 入口
│   ├── build.sh                Unix 入口
│   ├── clean_for_build.sh      打包前清理
│   └── clean.sh                简化清理
│
├── data/                       # 数据导入与回填
│   ├── import_sales_plan.py    ★ 销售计划导入
│   ├── backfill_supply_type.py 供货类型回填
│   └── match_update_from_excel.py 产品编号更新
│
├── query/                      # 查询与导出
│   └── quick_query.py          命令行数据查询
│
├── ui/                         # UI 开发
│   ├── compile_ui.py           UI 编译
│   └── designer.sh             Qt Designer 启动
│
└── docs/                       # 文档与辅助
    ├── generate_db_schema.py   数据库 Schema 文档
    ├── docs_helper.sh          Sphinx 文档构建
    ├── check_coverage.py       覆盖率检查
    ├── tree_structure.py       目录树打印
    └── test_import.py          早期验证脚本

路径定位机制¶

所有脚本使用统一的 get_project_root() 策略，不再依赖 __file__ 或 BASH_SOURCE 推导目录层级：

优先级	策略	说明
1	`CERTFLOW_ROOT` 环境变量	用户显式指定，优先级最高
2	`git rev-parse --show-toplevel`	Git 仓库中自动定位
3	向上查找 `pyproject.toml`	非 Git 环境自动定位
4	回退兼容	保持向后兼容

这意味着脚本可以放在任意子目录中，只要满足上述任一条件，就能正确找到项目根目录。