常见问题 FAQ¶

🚀 安装与启动¶

Q: 启动时提示 "No module named 'certflow'"¶

A: 未安装项目包。运行 uv sync 或 pip install -e .

Q: 启动时闪退¶

A:

检查日志：logs/certflow.log
检查配置文件：config/config.yaml
检查数据库：data/db/certflow.db

Q: 如何切换语言？¶

A: 在「设置」页面选择语言，或修改 config/userconfig.yaml 中的 language 字段

Q: 如何切换主题？¶

A: 点击右上角的 🌙/☀️ 按钮

📊 数据导入¶

Q: 导入Excel时提示 "列映射错误"¶

A:

检查 Excel 表头是否匹配 config/columns.yaml
使用「导入配置」对话框手动映射
确认表头行号设置正确

Q: 导入后数据乱码¶

A: Excel 文件编码问题。另存为 UTF-8 编码的 CSV 再导入

Q: 导入速度慢¶

A:

使用 CLI 导入：python -m certflow.cli import_sales_plan -f file.xlsx
分批导入大文件
关闭其他占用内存的应用

🖨️ 打印问题¶

Q: 找不到打印机¶

A:

确认打印机已连接并开机
检查 config/config.yaml 中的 printer_name
运行 python -m certflow.cli print_cert --list-printers 查看可用打印机

Q: 打印内容偏移¶

A: 调整 config/templates/coordinates.yaml 中的坐标值：

x_offset: 10  # 水平偏移（毫米）
y_offset: 5   # 垂直偏移（毫米）

Q: 打印字体不对¶

A:

确认系统安装了所需字体
检查模板中的字体配置
在 config/templates/coordinates.yaml 中修改字体名称

Q: 打印输出为空白¶

A:

检查碳带/墨盒
检查打印机驱动
尝试 HTML 降级打印

💾 数据库¶

Q: 如何备份数据库？¶

A:

python -m certflow.cli db_backup

Q: 数据库被锁定¶

A:

关闭所有数据库连接
重启应用
检查是否有其他进程占用

Q: 如何迁移数据库？¶

A:

python -m certflow.cli db_sync --source old.db --target new.db

📁 文件与路径¶

Q: 配置文件在哪里？¶

A:

主配置：config/config.yaml
用户配置：config/userconfig.yaml
UI配置：config/ui.yaml

Q: 日志文件在哪里？¶

A: logs/certflow.log 及 logs/certflow.*.log.zip

Q: 输出文件在哪里？¶

A: output/ 目录下按类型分类

🔧 性能¶

Q: 查询慢怎么办？¶

A:

使用索引字段查询
缩小查询范围（使用日期筛选）
使用 CLI 导出后离线分析

Q: 内存占用高¶

A:

分批处理大数据
使用 --dry-run 预览
增加虚拟内存

❓ 其他¶

Q: 如何获得帮助？¶

A:

查看日志文件
运行调试模式：python run.py --debug
提交 Issue：https://github.com/your-repo/CertFlow-PySide6/issues

Q: 如何报告 Bug？¶

A: 提交 Issue 时请附上：

操作步骤
错误日志
系统环境信息
截图（如有）