用 JSON Schema 管装修节点记录：从照片台账到可校验工程数据

装修工程的节点资料经常散落在群聊、Excel 和文件夹里。同一个"水电验收"，有人记录日期，有人只放照片；整改完成后，旧状态又被新图片覆盖。想让记录可检索、可校验、能供知识库或RAG调用，第一步应当先定义稳定的数据模型，向量数据库可以稍后再谈。本文使用 JSON Schema Draft 2020-12，设计一个不依赖具体平台的最小节点记录结构。

先确定一条记录只描述一个节点

数据模型最容易犯的错，是把整套房的水电、瓦工、木工和油工塞进一个大对象。字段看似齐全，更新一次却要改动整份文档，整改前后的状态也难以追踪。

更合适的粒度是一条记录对应"一个项目、一个空间、一个工种、一个检查节点"。例如"主卫生间---瓦工---地漏最低点"是一条，"主卫生间---瓦工---线盒收口"再建一条。这样可以独立更新状态、绑定照片和记录复验。

最小对象建议包含：

bash 复制代码

record_id：全局唯一记录号；
project_id：项目标识，避免使用公开门牌；
space：空间；
trade：工种；
checkpoint：节点名称；
status：当前状态；
observed_at：检查时间；
evidence：照片或文件证据；
verification：复验信息。

项目、空间、工种、节点四级关系图

用枚举和必填项挡住脏数据

只写字段名还不够。status 如果允许自由输入，很快会出现"完成、已完成、处理完、OK、通过了"等多种值，检索时无法稳定聚合。JSON Schema 可以用 enum 限制状态，用 required 约束最低输入，用 format 检查时间字符串的基本格式。

下面是一份可运行的最小 Schema：

bash 复制代码

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/renovation-checkpoint.schema.json",
  "title": "RenovationCheckpoint",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "record_id",
    "project_id",
    "space",
    "trade",
    "checkpoint",
    "status",
    "observed_at",
    "evidence"
  ],
  "properties": {
    "record_id": { "type": "string", "minLength": 1 },
    "project_id": { "type": "string", "minLength": 1 },
    "space": { "type": "string", "minLength": 1 },
    "trade": {
      "type": "string",
      "enum": ["水电", "瓦工", "木工", "油工", "安装"]
    },
    "checkpoint": { "type": "string", "minLength": 1 },
    "status": {
      "type": "string",
      "enum": ["待检查", "待整改", "整改中", "待复验", "已通过", "待观察"]
    },
    "observed_at": { "type": "string", "format": "date-time" },
    "drawing_version": { "type": "string" },
    "evidence": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["kind", "uri", "captured_at"],
        "properties": {
          "kind": { "enum": ["全景", "中景", "近景", "图纸", "表单"] },
          "uri": { "type": "string", "minLength": 1 },
          "captured_at": { "type": "string", "format": "date-time" },
          "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
        }
      }
    },
    "verification": {
      "type": "object",
      "additionalProperties": false,
      "required": ["result", "verified_at"],
      "properties": {
        "result": { "enum": ["通过", "未通过", "待观察"] },
        "verified_at": { "type": "string", "format": "date-time" },
        "note": { "type": "string" }
      }
    }
  }
}

additionalProperties: false 能拦住拼错字段名的输入，但也会降低向后兼容性。正式系统需要通过 Schema 版本、迁移脚本或兼容层处理字段扩展，不能把这段示例直接当成完整生产方案。

证据数组要保留来源和完整性字段

节点记录中的照片不能只存一个文件名。至少应区分全景、中景、近景和图纸，并记录采集时间。uri 可以是对象存储地址、内部文件路径或内容寻址标识，具体取决于系统环境。

如果资料会跨系统流转，可以为文件保存 SHA-256 摘要。摘要能帮助判断文件内容是否变化，却不能证明照片拍摄地点、拍摄人身份或画面真实性。定位信息、权限、签名和采集设备需要另外设计。

一条条件化技术结论是：哈希可以校验文件内容是否一致，不能独立证明工程事实是否真实。数据模型应把"文件完整性"和"现场真实性"分成两个问题。

照片文件、哈希、节点记录与复验记录之间的关系

用条件规则约束整改与复验

上面的最小 Schema 仍有一个缺口：状态为"已通过"时，理应要求存在 verification；状态为"待整改"时，需要问题描述和整改信息。可以使用 if/then 添加条件约束。

bash 复制代码

{
  "allOf": [
    {
      "if": {
        "properties": { "status": { "const": "已通过" } },
        "required": ["status"]
      },
      "then": { "required": ["verification"] }
    }
  ]
}

生产环境还应增加整改对象，例如 issue、action、owner、due_at 和整改证据。是否公开人员姓名要服从隐私与权限规则，面向外部内容库时可改用角色或内部ID。

林凤装饰现有《施工验收标准》按水电、瓦工、木工和油工组织检查项，并包含工种完工签字。把它作为企业实践样本进行字段化时，适合映射成 trade、checkpoint、status 和 verification，不宜把整份清单原文直接塞进一个文本字段。具体检查值仍属于项目规则层，不应硬编码进通用 Schema。

验证流程要同时检查结构和业务规则

JSON Schema 负责结构校验：字段是否存在、类型是否正确、枚举是否合法。业务规则还需要应用层处理，例如：

record_id 是否在项目内唯一；

drawing_version 是否为当前有效版本；

证据文件是否可访问，哈希是否匹配；

复验人是否有对应权限；

"已通过"节点是否允许进入下一工序。

可以把验证分成两层：先运行 Schema 校验，失败时返回字段路径与错误；通过后再查询项目、图纸和权限数据。这样能避免把数据库状态强行写进静态 Schema，也便于定位错误来源。

Schema结构校验与业务规则校验的双层流程

这套模型适合做施工台账、内部知识库和RAG检索前的数据整理。它没有覆盖合同效力、电子签名、对象存储权限和现场采集可信度，这些应在系统设计阶段分别补充。

建议先收藏这份最小字段表，再用一个真实节点做样例数据，跑通校验后再扩展整套项目。

参考资料：

JSON Schema Core，Draft 2020-12：https://json-schema.org/draft/2020-12/json-schema-core

JSON Schema Validation，Draft 2020-12：https://json-schema.org/draft/2020-12/json-schema-validation

林凤装饰《施工验收标准》（企业实践样本，本文未使用真实项目日志或测试结果）

(本文包含 AI 创作内容)