从检验批到档案归档：
黔建工程资料管理系统 v2.2.0 完整开发实录

一、为什么工程资料系统不是“表格网站”

一个真实项目里，资料不是孤立存在的。材料进场要先报验，见证取样后等复试；钢筋、模板、混凝土有检验批，防水有基层、附加层、防水层和保护层隐蔽；闭水、淋水试验要留影像，监理问题要整改回复，进度款与签证又要求时间、部位和签字互相对应。

很多系统只做了“新增一条记录、修改一个状态”，看起来功能很多，真正到项目上却会遇到四个问题：资料目录没人跟踪、工序前后关系没人提醒、审批签字没有证据链、竣工后无法组卷移交。黔建 v2.2 的开发重点，不只是把这条链补完整，还要让项目进度、系统配置和代码安全同样能验收。

二、系统架构与技术选型

这套系统没有引入 React/Vue，也没有为了“看起来现代”增加复杂前端构建链。后台管理界面采用原生 HTML5、CSS3 和 JavaScript ES2020+，配合 Y2Ksoft admin-kit 和水世界深色玻璃拟态视觉。单页前端把项目、目录、工序、AI、台账、工资、归档和系统管理组织成统一工作台。

浏览器（桌面 / 手机）
        │ HTTPS
        ▼
Nginx  https://www.y2ksoft.cn/qianjian/
        │ 反向代理、剥离 /qianjian/ 前缀
        ▼
Uvicorn → FastAPI main:app
        ├─ app/catalog.py              66 项目录
        ├─ app/construction_brain.py  11 阶段、57 任务
        ├─ app/schedule_service.py     项目计划与甘特图数据
        ├─ app/system_settings.py      12 分区设置、校验与生效
        ├─ app/ai_service.py           OCR 与结构化预填
        ├─ app/archive_service.py      组卷、PDF、分册、校验
        ├─ app/services.py             校验、导出、序列化
        └─ app/models.py               SQLAlchemy 数据模型
        │
        ├─ /var/lib/y2k-qianjian/qianjian.db
        ├─ /var/lib/y2k-qianjian/uploads/
        ├─ /var/lib/y2k-qianjian/ai_files/
        └─ /var/lib/y2k-qianjian/archive_packages/

三、代码结构与实现方式

`main.py` 是 FastAPI 应用入口，负责创建应用、注册中间件和路由。业务规则没有全部塞进路由：资料目录、施工知识库、AI 识别、归档组卷分别拆进 `app/` 下的独立服务。这样测试时可以针对规则引擎单独验证，归档规则也不会被页面逻辑绑死。

黔建工程资料管理系统/
├─ main.py                    FastAPI 入口与全部业务 API
├─ app/
│  ├─ models.py               业务表、系统设置与关系模型
│  ├─ migrations.py           schema 1 → 10 自动升级
│  ├─ security.py             PBKDF2、随机盐、会话令牌
│  ├─ services.py             校验、摘要、CSV/Excel、备份
│  ├─ catalog.py              九大板块 66 项资料目录
│  ├─ construction_brain.py   11 阶段 57 任务知识库
│  ├─ schedule_service.py     项目甘特图与进度偏差
│  ├─ system_settings.py      12 分区设置与业务规则
│  ├─ ai_service.py           本地 OCR、文档解析、AI 结构化
│  └─ archive_service.py      关门检查、组卷、PDF、分册、ZIP
├─ static/
│  ├─ index.html              单页工作台
│  ├─ app.js                  业务交互与页面渲染
│  ├─ app.css                 水世界主题、呼吸灯、打印样式
│  └─ admin-kit/              Y2Ksoft 官方组件套件
├─ tests/test_api.py          33 项 API 集成测试
├─ e2e/browser_flow.py        32 项真实浏览器业务旅程
└─ docs/使用手册_v2.2.0.pdf  30 页客户使用手册

为什么后端选 FastAPI，而不是只做纯前端

工程资料涉及多用户、审批、冻结、回执和审计，不能把数据只放在浏览器 localStorage。FastAPI 的依赖注入让每个写接口都能统一校验登录、角色、CSRF 和项目权限；Python 生态又能直接处理 PDF、Word、Excel、OCR 和 ReportLab，不需要再维护第二套文档服务。

为什么数据库先用 SQLite

当前定位是单机、局域网和中小团队试点。SQLite 配合 WAL、在线快照和独立持久目录，部署成本低、备份简单、恢复路径清楚。它的限制也很明确：单机写入并发有上限。如果未来出现多公司、高并发或跨地域协作，数据层应迁移 PostgreSQL，并把附件迁到对象存储；这次没有把 SQLite 包装成“无限并发”的假象。

四、schema 10 数据模型：从项目配置到档案的完整关系

schema 10 不是简单加几个字段，而是把项目资料生命周期、系统配置和项目进度都建成可追溯的数据结构。项目下有单位工程、目录状态、阶段任务、资料记录、附件、审批、实名签字；新增 `system_settings` 保存组织、编号、审批、打印、安全、AI 和备份策略；竣工后又关联归档节点、案卷、卷内目录项、归档包、移交事件、回执、保管位置和借阅记录。

版本迁移而不是清库重建

系统已经经历 1.7 到 2.2 多次结构升级，当前 schema 10。`app/migrations.py` 会按版本逐步补表、补字段和迁移历史数据，启动时自动检查 schema。备份中包含版本号，恢复演练使用独立数据库验证，避免“恢复后发现字段不对”。

乐观锁防止多人覆盖

资料记录带有版本号。两个人同时打开同一条资料时，后提交的人必须基于最新版本，否则服务端拒绝静默覆盖。这个问题在多人协作的现场很容易发生，尤其是项目经理审批、资料员补附件同时进行时。

五、权限、CSRF、限流和审计：安全不是上线后再补

系统有四类角色：系统管理员、项目经理、资料员、访客。所有写接口都在服务端检查角色和 CSRF Token，不依赖前端按钮是否隐藏。附件下载、归档包下载和备份接口也绑定当前会话。

# 生产环境关键变量
QIANJIAN_DB_PATH=/var/lib/y2k-qianjian/qianjian.db
QIANJIAN_DATA_DIR=/var/lib/y2k-qianjian
QIANJIAN_SECURE_COOKIE=1
QIANJIAN_TRUSTED_PROXIES=127.0.0.1,::1
QIANJIAN_PUBLIC_URL=https://www.y2ksoft.cn/qianjian
QIANJIAN_ENABLE_API_DOCS=0
QIANJIAN_SEED_DEMO=0

六、九大板块、66 项资料目录：先让资料员知道缺什么

资料目录覆盖工程前期、施工技术与交底、材料进场、试验检测、质量验收、安全文明、农民工劳资、防水专项和竣工验收九大板块。每一项不是静态清单，而是能登记责任人、计划日期、状态、办理说明，并关联项目内资料台账。

• 前期：合同、施工许可、项目部组建、图纸会审、变更洽商、监理通知闭环、进度计划、签证、日志和会议纪要。
• 技术：施工组织设计、专项方案、两级交底、样板引路和防水节点交底。
• 材料与试验：进场报验、合格证、型式检验、见证取样、复试、混凝土试块、蓄水与淋水试验、实体检测。
• 质量：隐蔽验收、检验批、分项、子分部、分部、质量缺陷整改和复查。
• 安全与劳资：三级教育、特种工、隐患排查、应急预案、花名册、合同、考勤、工资表和公示。
• 防水专项：方案、样板、材料、基层隐蔽、附加层、防水层、保护层、闭水淋水、变更签证和整改。
• 竣工：自评、验收申请、竣工图、组卷、分册和档案移交。

关键缺口会进入工作台红色呼吸预警，并与 AI 决策摘要联动。但目录本身不等于正式地方标准：当前内置的是业务覆盖清单和示例模板，正式使用前必须导入项目所在地现行表格和监理认可的表样。

七、施工工序智慧大脑：今天做什么，明天准备什么

用户真正想要的“AI 决策”不是让大模型随口安排施工，而是系统知道当前项目处在哪个阶段、阶段开始多久、哪些关键任务没完成、哪些资料缺失、下一道工序需要什么。我们采用可审计的工序知识库 + 规则依赖，而不是让模型自由编造。

当前知识库包含 11 个阶段、57 个任务和 40 个可阻断前置条件，覆盖进场准备、土方基坑、基础、地下防水、回填、主体、砌体、屋面/厨卫防水、机电、装饰和竣工验收。

关键任务未完成时，服务端返回 409，禁止推进工序，并列出具体缺项。资料录入完成后，系统还会根据模板关联显示后续隐蔽、试验、保护层或验收动作。这样既不盲目前进，也不是只看进度百分比。

七A、项目总进度甘特图：进度必须有计划、有偏差、有依据

v2.2.0 新增“项目进度”页面。它不再只给项目填一个 0–100% 的装饰数字，而是根据项目开竣工日期、11 道施工工序、阶段工期权重和任务完成情况，生成真正的计划时间轴。

图表数字与 API 实时同步。每个阶段条形内直接显示百分比，右侧显示任务完成数，不依赖鼠标悬停；桌面、手机、深色和浅色主题都保留数字。

项目总进度甘特图

实际完成、计划应完成、偏差、关键阻断、剩余天数、今天位置和里程碑在一张图中呈现。

11 道施工工序甘特图 · 数字直接显示

七B、系统设置中心：配置必须真正改变业务，而不是摆设

v2.2.0 将系统设置重构为 12 个分区。设置保存在新增 `system_settings` 表，服务端按分区白名单校验，所有修改都进入审计日志。

审批设置不再是前端开关。例如关闭“资料流转必须电子签字”后，后台提交、审批和归档会按配置执行；关闭“允许项目经理审核本人资料”后，项目经理审批自己创建的记录会收到 403。服务器设置 `QIANJIAN_STRICT_WORKFLOW=1` 时，页面不能关闭严格流程。

系统设置表单

统一中文字体层级，导航、标签、输入框、说明、按钮和状态数字不再出现大小与字重跳变。

组织信息设置 · 统一字体与表单比例

系统运行状态

版本、schema、强制审批、云端 AI 和核心业务数量集中展示。

系统设置中心 · 运行状态与安全提示

八、AI 识别与人工审核：减少录入，不放弃责任

项目资料最耗时的环节之一是重复输入。现场资料可能来自手机拍照、扫描 PDF、Word、Excel，也可能是资料员把文件放在电脑桌面。系统提供三种入口：控制台上传、手机扫码拍照、桌面受控收件箱自动扫描。

本地默认识别链路是 RapidOCR、PyMuPDF、python-docx 和规则匹配，不配置云端密钥也能工作；只有在客户明确配置 API 时才使用大模型增强字段理解。文件通过 SHA256 去重，识别任务有状态、来源、原始文件、提取字段、问题和置信度。

手机扫码入口采用一次性上传会话，二维码 30 分钟内有效。云端部署时上传地址由 `QIANJIAN_PUBLIC_URL` 生成，不再把本机 localhost 地址写进二维码。

九、填报、校验、审批与实名签字

每份资料都保留模板快照。模板以后改版，不会把历史资料的数据含义改掉。字段分为文本、文本域、下拉、日期和检查项；必填、数值范围、检查项结论由服务端校验，避免绕过前端直接提交错误数据。

提交、批准、驳回、付款和归档都绑定登录用户的实名信息、时间、签字摘要，可附加手写签名。签字被包含在资料详情、打印、Excel、CSV、JSON 和 ZIP 备份中。任何审批都不会只改一个彩色状态标签而没有证据。

十、农民工实名制与工资：资料和劳资必须在同一项目里

工程资料不能只管质检表。农民工花名册、身份证、合同、考勤、工资表、银行流水、公示照片和纠纷台账都是迎检高频内容。系统把工人、考勤、工资单、审批和付款签字串起来。

• 工人实名制花名册与项目关联，记录工种、班组、证件和状态。
• 按月录入考勤，工资单进入待审批后由项目经理审批，付款阶段单独确认。
• 工资未付、资料待审批、资料不合格、施工工序阻断、AI 识别待校对、档案退回统一进入分级预警。
• 金额统一按两位小数显示和导出，避免浮点比较造成误差。

十一、打印、导入导出和备份恢复：办公系统的主战场

客户真正每天使用的不是“炫酷图表”，而是打印、导出、签字和恢复。系统支持 A4 浏览器打印、多选连续打印、资料详情打印、CSV、格式化 Excel、模板包 JSON、全量 JSON 和数据库 + 附件 ZIP。

备份不是“数据库文件复制一下”这么简单。SQLite 使用在线备份快照，保证导出时数据库一致性；代码目录和业务数据目录分开，重新部署不会覆盖 `/var/lib/y2k-qianjian`。

十二、竣工组卷与档案移交：项目资料闭环的最后一公里

v2.0 引入了项目级归档，v2.2 继续把系统设置、项目进度和代码审计补齐。归档不再只是把单份资料标记成“已归档”。系统先做竣工关门检查：66 项目录、关键缺口、全部资料审批状态和竣工验收阶段必须同时满足。然后按配置化归档节点建立案卷、卷内目录、页码和分册。

归档包实际包含什么

qianjian-archive-项目编号-版本.zip
├─ archive_manifest.json
├─ SHA256SUMS.txt
├─ volume_catalog.csv
├─ volumes/
│  ├─ 01_工程准备文件.pdf
│  ├─ 02_监理文件.pdf
│  ├─ 03_施工文件.pdf
│  └─ ...
├─ records/
│  └─ records.json
└─ attachments/
   ├─ 隐蔽验收照片.jpg
   ├─ 材料合格证.pdf
   └─ 复试报告.pdf

默认 20 个归档节点覆盖工程准备、监理、施工、竣工验收和归档保存。超过 200 页自动分册并保持连续页次；卷内目录可以追溯到资料编号、模板、项目、单位工程和附件。归档包生成后保存 SHA256，移交时不会只靠文件名判断版本。

接收后登记保管期限、库房位置和借阅归还；逾期借阅有状态提醒。这样，项目资料从进场资料目录一路走到“可交付给甲方、监理或城建档案部门审查的归档包”，而不是停在系统内的某个状态标签。

十三、测试证据与全量代码审计：不是“我自己点了一下”

v2.2.0 采用接口测试、真实浏览器旅程、视觉/无障碍、静态安全扫描和依赖漏洞审计五层验收。测试覆盖资料填报、审批签字、甘特图、设置保存、用户权限、备份校验、AI 校对、工资审批、组卷、退件、重提、接收、冻结和借阅。

• API 测试 33/33 通过，总覆盖率 83%；甘特图服务 85%，系统设置服务 80%。
• 浏览器业务旅程 32/32 通过，甘特图与系统设置专项验收 PASS。
• 控制台错误、页面错误、失败请求均为 0；axe WCAG 检查违规为 0；375px 手机端无横向溢出。
• schema 10 备份包含系统设置、资料、签字、工资、归档包、回执和移交事件。
• Bandit 未发现 high/medium 级真实缺陷；4 条 low 结果经复核为 XML 转义函数和常量名误报。
• pip-audit 初始发现旧 Starlette 0.41.3 共 14 个已知漏洞，升级后 90 个依赖为 0 漏洞。

安全审计不是把“未实现”伪装成“已实现”。项目级成员 ACL、贵州正式表样、住建/档案馆 XML 接口和 CA 签章仍需要客户组织架构、正式规范或接口文档，系统没有用猜测规则代替正式边界。

十四、腾讯云 HTTPS 部署：子路径也能稳定运行

线上部署在腾讯云 OpenCloudOS 9，使用现有域名 `www.y2ksoft.cn` 的 HTTPS 子路径，避免等待新子域名 DNS。Nginx 保留公网路径 `/qianjian/`，代理时转发到本机 3340；应用只绑定回环地址，业务数据库和附件不放在代码目录。

# 服务器目录
/var/www/y2ksoft/qianjian/       代码与虚拟环境
/var/lib/y2k-qianjian/           数据库、附件、AI文件、归档包、回执
/etc/y2k-qianjian.env           生产环境变量，权限 600
/etc/systemd/system/qianjian-doc.service
/etc/nginx/conf.d/y2ksoft-qianjian.inc

前端资源原来使用 `/api/`、`/static/` 绝对路径，放到子路径会跳出应用。本次部署改为基于当前页面目录解析资源，所以本地根路径和云端 `/qianjian/` 都能工作；手机上传页面也使用公开 URL 前缀生成二维码和 API 地址。

systemd 负责自动重启、日志和运行边界：应用以独立 `qianjian` 用户运行，`ProtectSystem=strict`、`ProtectHome=true`、只允许写 `/var/lib/y2k-qianjian`。Nginx 配置修改前已备份，修改后先执行 `nginx -t` 再 reload，避免影响同一台服务器上的其他系统。

v2.2.0 升级前额外保存了部署前代码包和数据库快照：`/root/qianjian-backups/code-before-v2.2.0-20261031_102435.tar.gz` 与 `db-before-v2.2.0-20261031_102435.db`。升级后健康检查返回 `version 2.2.0 / schema 10 / database ok`。

十五、系统实拍：真实页面而不是效果图

01 · 登录与安全入口

水世界深潭蓝玻璃拟态风格，品牌、资料链定位和安全工作区在同一屏讲清楚。

登录页 · 深色玻璃拟态与项目资料链定位

02 · 资料工作台

KPI、预警中心、资料闭环率、目录缺口、待审批和工序任务在同一工作台汇聚。

资料工作台 · 实算 KPI、风险预警和待办

03 · 九大板块 66 项资料目录

每个目录项都有状态、风险级别、责任人、期限和关联资料；关键缺口使用呼吸警示。

项目资料目录 · 九大板块、66 项、责任人与风险

04 · 项目总进度甘特图

11 道工序计划日期、实际与计划完成率、偏差、阻断、剩余天数和今天位置线同屏显示。

项目甘特图 · 数字直接显示，不依赖悬停

05 · 手机项目甘特图

375px 手机端保留 KPI、阶段条形和里程碑，可横向查看工序时间轴。

手机端 · 项目进度随时查看

06 · 系统设置表单

组织信息、字体、输入框、按钮、说明和版本号使用统一层级，适合长时间办公。

系统设置 · 12 分区与统一字体层级

07 · 系统运行状态

版本、schema、严格审批、云端 AI 和业务数据状态集中展示。

运行状态 · v2.2.0 与 schema 10

08 · AI 资料收录

手机扫码、桌面收件箱和文件上传进入识别队列，识别结果进入人工校对后再生成草稿。

AI 资料收录 · 拍照、扫描、结构化预填

09 · 农民工工资闭环

实名制、考勤、工资单、审批、付款和签字统一进入工资台账。

劳务工资 · 审批、付款与风险预警

10 · 竣工归档与移交

关门检查、案卷、卷内目录、归档包、退回重提、接收回执、冻结和借阅形成最终闭环。

竣工归档 · 从组卷到接收冻结

十六、使用手册下载

博客正文讲开发逻辑，客户日常操作请看配套 30 页图文手册。手册按“登录 → 工作台 → 项目/目录/工序/甘特图 → 资料填报与审批 → 系统设置 → AI 收录 → 工资 → 竣工归档移交 → 系统备份”的顺序编写，关键按钮带编号箭头。

十七、已知边界与下一步

这次交付已经形成从项目建立到档案保存借阅的完整可运行闭环，但不能把“完整”理解成“所有地区、所有法定格式都已兼容”。下面这些内容仍在后续路线中：

• 导入贵州项目所在地现行正式资料表样、检验批表头和允许偏差规则。
• 接入客户指定的住建/城建档案部门 XML 接口，不能凭空编造交换格式。
• 需要法律效力的电子签章时，接入 CA 证书、时间戳和验签服务。
• 多人高并发、多个公司隔离时，迁移 PostgreSQL、对象存储和项目级 ACL。
• 继续把新发现的真实业务规则纳入系统设置，而不是新增无法生效的装饰开关。
• 正式批量套打前逐表校验 A4 分页、签字栏、表格边框和打印缩放。

这不是给系统找借口，而是工程软件应有的边界：能验证的功能写清楚，缺客户规范或接口的功能明确列为接入项。真正可用的系统，不是每个按钮都写“AI”，而是每个关键动作都能追溯到数据、规则、责任人和归档证据。