顺德软件定制验收：源码文档交到哪一步

在佛山顺德，家电、五金、模具和装备工厂做软件定制开发，验收常被简化成系统能点开、流程能跑通。但真正决定后续三五年成本的，是源码和技术文档交到什么程度。只拿到编译包和几页截图说明，系统一旦要接新设备、改工艺路线、对接1C或更换服务商，工厂就会被锁住。

一、先定交付层级，再谈验收

建议合同把交付分为三层：L1可运行，交安装包、部署说明和基础手册；L2可维护，交全量源码、构建脚本、数据库脚本、配置模板、接口文档和运维手册；L3可演进，在L2基础上增加架构设计、数据库字典、字段级接口契约、测试报告、第三方组件License清单和完整代码提交历史。MES系统、中俄跨境物流系统和小程序开发，至少按L2验收；涉及智能制造、工业互联网长期投入的项目，建议按L3验收。

二、源码交付的硬标准

源码不是压缩包，而是可重建的工程。交付应包含前端、后端、数据库、定时任务、报表、接口适配层和设备采集服务的全量代码，以及依赖清单、构建脚本、初始化数据、配置模板和部署脚本。验收时在一台干净服务器上，仅凭交付物完成编译、建库、部署和核心流程跑通，才算过线。

• MES系统：工艺路线管理配置、报工规则、设备OEE稼动率采集口径、能耗采集分析点位表、边缘计算网关配置、PLC或OPC UA点表。
• 中俄跨境物流系统：运单状态机、1C接口字段映射、物流轨迹追踪接口、国际铁路联运节点、清关与EAC认证字段、多币种核销规则。
• 小程序开发：前后端源码、微信开放平台主体、类目资质、隐私协议、支付与地图账号、ERP接口说明。

第三方开源组件按License合规使用，商业组件提供授权证明。乙方通用框架可以保留权利，但必须在合同中列明；不得设置时间锁、后门或远程锁定。云服务器、域名、SSL、短信、地图、OCR和微信开放平台账号，应同步过户或移交管理员权限。

三、技术文档要到字段级

文档至少包括需求规格、概要设计、详细设计、数据库字典、接口文档、部署手册、运维手册、用户手册、测试报告、验收报告、数据迁移与回滚方案、账号资产清单、第三方服务清单、漏洞扫描报告和培训记录。接口文档要写清请求响应、错误码、幂等与重试；数据库字典要有表字段注释和主外键；部署手册要写依赖版本、环境变量、端口、备份恢复和回滚步骤。文档版本与代码版本必须一致，建议同仓管理。

四、验收流程与合同条款

验收可分预验收、试运行和终验。预验收按交付物清单逐项打勾；试运行2至4周，用真实工单、真实运单和真实订单跑核心流程；终验前完成代码仓库迁移到甲方Git、第三方账号过户和管理员培训。合同要把尾款支付与源码及文档交付绑定，写明知识产权归属、源码托管、质保期6至12个月、缺陷分级响应和验收不通过整改复验。

五、常见坑要提前写进附件

• 只交编译包，缺数据库脚本和构建依赖，换环境就部署不起来。
• 接口文档只有截图，没有字段、错误码和重试规则，对接1C或ERP反复扯皮。
• 设备协议点表、OEE采集口径和能耗点位表不交付，工业互联网采集无法扩展。
• 小程序只有体验版，微信主体、类目、隐私协议和支付账号未移交。
• 云账号不过户，源码交了但系统仍被原服务商控制。

对顺德工厂来说，验收多花一周把源码和文档点清，远比上线后花几个月补课划算。MES系统的工艺路线、设备OEE稼动率口径，跨境物流的1C映射和物流轨迹追踪，小程序的主体与接口，都是可复用资产。交付不清，智能制造就容易停在展示屏上。