施工日记套件 · 快速上手指南

目录〇、套件全景：三步闭环一、启动系统二、建工程与花名册（只需一次）三、手工录入施工日记四、从 AI 生成侧一键导入（canonical）五、验证与签名提交六、查询与导出 WORD / CSV / XLSX 七、命令行用法（无浏览器场景）八、常见问题

〇套件全景：三步闭环

图 1 · 三步闭环：AI 生成初稿 → 人工复核验证 → 正式归档导出

两种使用方式任选：纯手工（直接在 Web 页面录入，跳过①）或 AI 辅助（AI 先出初稿，导入后人工复核）。

1启动系统

运行 start.py（python start.py，组合包内），或在系统目录执行：

python app.py

看到提示后，浏览器打开 http://127.0.0.1:8080 即可使用。

端口被占用时，可用环境变量换端口：set PORT=8090 && python app.py。数据保存在同目录 diary.db（SQLite），照片保存在 photos/ 文件夹，全部本地存储。

2建工程与花名册（只需一次）

进入 「① 基础数据」 页签：

2.1 新增工程

填写工程名称、参建单位（建设/施工/监理）、城市、开竣工日期，点击 + 新增工程。

城市用于自动联网获取当日天气与经纬度，务必填写（如「宜昌市」「武汉市」）。

2.2 导入花名册

选择工程后，在批量框中按 姓名,角色 每行一条粘贴，点击导入花名册：

张三,施工员
李四,施工员
王五,安全员

花名册用于「人员交叉验证」——日记中的参与人员/负责人若不在花名册，验证会给出警告。

3手工录入施工日记

进入 「② 日记录入」 页签，按以下顺序操作：

#	操作	说明
1	选工程、选日期	天气/气温/风力将自动联网填入（也可点「联网获取」或手填）
2	填施工部位、参与人员、负责人	参与人员用逗号分隔，如 `张三,李四`
3	填四大栏目	施工内容（必填）/ 设备运转 / 安全检查 / 施工大事记
4	填材料表格	点「+ 增加材料条目」逐行填材料名称/用量/单位
5	点保存草稿	保存后才能上传照片
6	上传照片	五个栏目下方均有照片框，每栏目最多 6 张，支持删除/替换
7	点提交（施工员签名）	输入姓名签名确认；有必改错误时提交会被阻断

图 2 · 手工录入五步流程

4从 AI 生成侧一键导入（canonical）

如果日记初稿由 AI 生成侧（construction-log-generator）产出，无需重新打字：

4.1 生成侧转出 canonical 文件

python to_canonical.py --spec 你的spec.json --out canonical_diary.json

照片会以 base64 内嵌进 JSON，单文件即携带全部内容。

4.2 Web 页面一键导入

进入 「② 日记录入」 页签顶部的 「从生成侧导入（canonical JSON）」 卡片：

#	操作
1	点「选择文件」，选中一个或多个 `canonical_diary.json`（支持批量）
2	勾选「工程不存在时自动创建」（默认勾选；不勾则要求工程已存在）
3	点导入 canonical
4	页面即时显示：新日记编号、照片入库数、校验错误/警告明细表

导入后日记为草稿状态并已自动跑完校验——这是刻意设计：AI 初稿必须经人工复核（第 5 步）后才能签名提交，保证「AI 生成、人来负责」。

5验证与签名提交

进入 「③ 验证」 页签，选择日记，点运行验证。三类规则：

规则	检查内容	级别
DATE_RANGE	施工日期是否落在工程工期内	错误（阻断提交）
REQUIRED	日期/天气/部位/参与人员/负责人/施工内容等必填项	错误（阻断提交）
ROSTER	参与人员与负责人是否在项目花名册中	警告（不阻断）

验证失败项会同步进入 「④ 异常报告」 页签跟踪，修正后重新验证即可消除。

提交即签名：点提交时输入施工员姓名，系统记录「姓名 + 角色 + 时间戳」入审计轨迹，导出的 WORD 中同样可见。

6查询与导出 WORD / CSV / XLSX

进入 「⑤ 查询导出」 页签：

筛选：按工程、状态、日期范围、施工部位（模糊）组合查询；
单篇 WORD：列表每行的「WORD」按钮，或详情页导出 WORD —— 导出文件含五栏目嵌入照片与签名记录；
批量导出：按当前筛选条件一键导出 WORD（多篇合一文件）/ CSV / XLSX 台账。

录入页保存或提交后也可直接点「导出 WORD」，写完即得正式文档。

7命令行用法（无浏览器场景）

服务器、自动化脚本或 AI Agent 可用 verify_cli.py 完成全部操作：

# 导入 canonical 并自动校验
python verify_cli.py import --json canonical_diary.json

# 校验指定日记
python verify_cli.py validate --id 1

# 导出（docx/csv/xlsx；--id 单篇，--project 按工程，缺省全部）
python verify_cli.py export --format docx --out 日记.docx

# 注入示例工程（演示用）／清空日记保留工程花名册
python verify_cli.py seed
python verify_cli.py clean

# 启动 Web 服务
python verify_cli.py serve --port 8080

8常见问题

问题	解决办法
天气获取失败	检查网络；确认工程「城市」已填规范名称（如「宜昌市」）；也可手动填写天气三项
照片传不上	先点「保存草稿」拿到日记编号再传；单栏目上限 6 张，超出需先删除旧照片
提交被阻断	按弹窗提示修正「错误」级问题（日期超工期/必填缺失），警告不阻断
导入提示「工程不存在」	勾选「工程不存在时自动创建」，或先在①基础数据中手工建工程
端口被占用	`set PORT=8090 && python app.py` 换端口
想要示例数据练手	`python verify_cli.py seed` 注入示例工程与花名册