怎样在PHP项目中实现合同归档？

wen java案例 2026-07-20 125

本文目录导读：

怎样在PHP项目中实现合同归档？

核心功能模块划分
技术选型建议
数据库表设计（核心表）
核心代码实现（Laravel 示例）
防篡改与法律效力增强
检索与借阅审批
注意事项与最佳实践
扩展阅读（建议深入方向）

在PHP项目中实现合同归档系统,通常涉及流程管理、文件存储、数据库设计、权限控制等多个方面，下面提供一个从设计到编码的系统化实施方案。

核心功能模块划分

一个完整的合同归档系统至少需要包含：

合同录入/导入：录入合同基本信息，上传电子文件。
审批流程：归档前需要经过业务、法务、财务等部门的确认。
电子签章与防篡改：对归档文件进行数字签名或哈希校验。
存储管理：文件存储（本地/云存储/OBS）与元数据分离。
检索与借阅：支持多条件检索、权限控制下的借阅与审批。
销毁管理：到期合同的销毁流程与审计日志。

技术选型建议

模块	技术选型（PHP生态）	说明
框架	Laravel / ThinkPHP 6+ / Symfony	推荐Laravel，ORM、队列、事件系统成熟
数据库	MySQL 8.0+ / PostgreSQL	建议使用InnoDB，支持全文索引
文件存储	本地 + OSS（阿里云/腾讯云/MinIO）	建议对象存储+CDN加速
全文搜索	Elasticsearch / Meilisearch（可选）	合同正文检索
队列	Redis + Laravel Queue / RabbitMQ	异步处理PDF转图片、OCR识别
签章/防篡改	Python/Docker调用第三方签章API	PHP不适合做复杂加密，可调用外部服务

数据库表设计（核心表）

-- 1. 合同主表
CREATE TABLE `contracts` (
    `id` BIGINT UNSIGNED AUTO_INCREMENT,
    `contract_no` VARCHAR(64) NOT NULL COMMENT '合同编号（业务流水号）', VARCHAR(255) NOT NULL COMMENT '合同标题',
    `type` TINYINT NOT NULL COMMENT '合同类型：1销售、2采购、3人事...',
    `party_a` VARCHAR(255) COMMENT '甲方',
    `party_b` VARCHAR(255) COMMENT '乙方',
    `amount` DECIMAL(15,2) DEFAULT 0.00 COMMENT '合同金额',
    `sign_date` DATE COMMENT '签署日期',
    `effective_date` DATE COMMENT '生效日期',
    `expiry_date` DATE COMMENT '到期日期',
    `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态：0草稿 1审批中 2已归档 3已作废 4已销毁',
    `storage_path` VARCHAR(500) COMMENT '最终归档文件路径（加密存储）',
    `hash_sha256` CHAR(64) COMMENT '文件完整性校验哈希',
    `archived_at` DATETIME COMMENT '归档时间',
    `created_by` INT UNSIGNED,
    `updated_at` DATETIME,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_contract_no` (`contract_no`),
    KEY `idx_status` (`status`),
    KEY `idx_expiry` (`expiry_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 2. 合同文件版本表（支持多版本）
CREATE TABLE `contract_files` (
    `id` BIGINT UNSIGNED AUTO_INCREMENT,
    `contract_id` BIGINT UNSIGNED NOT NULL,
    `version` TINYINT NOT NULL DEFAULT 1,
    `original_name` VARCHAR(255),
    `storage_path` VARCHAR(500),
    `file_size` INT,
    `mime_type` VARCHAR(100),
    `hash_sha256` CHAR(64),
    `uploaded_by` INT,
    `created_at` DATETIME,
    PRIMARY KEY (`id`),
    KEY `idx_contract_id` (`contract_id`)
);
-- 3. 归档记录表（审计日志）
CREATE TABLE `archive_logs` (
    `id` BIGINT AUTO_INCREMENT,
    `contract_id` BIGINT,
    `action` VARCHAR(32) COMMENT 'archive(归档) / unarchive(借阅) / destruct(销毁)',
    `operator_id` INT,
    `ip_address` VARCHAR(45),
    `detail` JSON,
    `created_at` DATETIME,
    INDEX `idx_contract_id` (`contract_id`)
);

核心代码实现（Laravel 示例）

1 模型与关系

// app/Models/Contract.php
class Contract extends Model
{
    protected $fillable = [
        'contract_no', 'title', 'type', 'party_a', 'party_b',
        'amount', 'sign_date', 'effective_date', 'expiry_date',
        'status', 'storage_path', 'hash_sha256', 'archived_at'
    ];
    protected $dates = ['sign_date', 'effective_date', 'expiry_date', 'archived_at'];
    public function files()
    {
        return $this->hasMany(ContractFile::class);
    }
    public function archiveLogs()
    {
        return $this->hasMany(ArchiveLog::class);
    }
    // 归档方法
    public function archive(array $metadata = []): bool
    {
        DB::beginTransaction();
        try {
            // 1. 锁定最新版本文件，计算哈希
            $latestFile = $this->files()->latest('id')->first();
            if (!$latestFile) {
                throw new \Exception('合同文件不存在');
            }
            // 2. 将文件移动到只可追加的归档目录（或OSS冷存储）
            $newPath = $this->moveToArchiveStorage($latestFile);
            // 3. 更新合同记录
            $this->status = 2; // 已归档
            $this->storage_path = $newPath;
            $this->hash_sha256 = $latestFile->hash_sha256;
            $this->archived_at = now();
            $this->save();
            // 4. 记录审计日志
            $this->archiveLogs()->create([
                'action' => 'archive',
                'operator_id' => auth()->id(),
                'ip_address' => request()->ip(),
                'detail' => json_encode($metadata),
            ]);
            DB::commit();
            return true;
        } catch (\Exception $e) {
            DB::rollBack();
            Log::error('合同归档失败：' . $e->getMessage());
            return false;
        }
    }
    private function moveToArchiveStorage($file)
    {
        // 实际项目中建议使用 AWS S3 / OSS 的归档存储（GLACIER / Archive）
        // 示例：重命名文件为 合同编号_时间戳_哈希前8位.pdf
        $ext = pathinfo($file->original_name, PATHINFO_EXTENSION);
        $newName = $this->contract_no . '_' . time() . '_' . substr($file->hash_sha256, 0, 8) . '.' . $ext;
        Storage::disk('archive')->putFileAs(
            'contracts/' . date('Y/m'),
            $file->storage_path,
            $newName
        );
        return 'contracts/' . date('Y/m') . '/' . $newName;
    }
}

2 控制器中的归档操作

// app/Http/Controllers/ContractController.php
public function archive(Request $request, $id)
{
    $contract = Contract::with('files')->findOrFail($id);
    // 权限校验：只有特定角色可以归档
    $this->authorize('archive', $contract);
    // 前置校验：合同状态必须为“审批通过”或“待归档”
    if ($contract->status !== 1) { // 假设1=审批通过
        return response()->json(['message' => '合同未通过审批，无法归档'], 422);
    }
    // 归档前提：检查完整性，比如必须上传盖章版PDF
    if (!$contract->files()->where('mime_type', 'application/pdf')->exists()) {
        return response()->json(['message' => '必须上传PDF盖章版合同才能归档'], 422);
    }
    $result = $contract->archive($request->input('metadata', []));
    if ($result) {
        event(new ContractArchived($contract)); // 触发事件：通知相关人员、生成防篡改凭证
        return response()->json(['message' => '归档成功', 'hash' => $contract->hash_sha256]);
    }
    return response()->json(['message' => '归档失败，请稍后重试'], 500);
}

3 文件完整性校验中间件

// app/Http/Middleware/VerifyArchiveIntegrity.php
public function handle($request, Closure $next)
{
    // 在下载、查看归档合同前，自动校验哈希
    if ($request->route()->hasParameter('contract')) {
        $contract = $request->route()->parameter('contract');
        if ($contract->status === 2) { // 已归档
            $currentHash = hash_file('sha256', storage_path('app/archive/' . $contract->storage_path));
            if ($currentHash !== $contract->hash_sha256) {
                Log::warning('合同文件完整性校验失败，可能已被篡改：' . $contract->contract_no);
                abort(403, '归档文件已被篡改或损坏');
            }
        }
    }
    return $next($request);
}

防篡改与法律效力增强

除了基本的存储与校验,建议接入第三方电子签名API（如e签宝、法大大、契约锁）以增强法律效力：

// 调用第三方签章API（示例伪代码）
public function signDocument($filePath) {
    $client = new EsignClient(env('ESIGN_APP_ID'), env('ESIGN_SECRET'));
    $result = $client->addSignature([
        'file' => $filePath,
        'sign_positions' => [
            ['page' => 1, 'x' => 200, 'y' => 300],
        ],
        'signer_name' => '公司法人',
        'certificate_type' => 'CORPORATE',
    ]);
    // 返回签章后的文件路径与验签凭证
    return $result['signed_file_url'];
}

检索与借阅审批

检索示例（Laravel Scope + Elasticsearch）：

// Contract模型
public function scopeSearch($query, $keyword)
{
    return $query->where(function($q) use ($keyword) {
        $q->where('title', 'like', "%{$keyword}%")
          ->orWhere('contract_no', 'like', "%{$keyword}%")
          ->orWhere('party_a', 'like', "%{$keyword}%")
          ->orWhere('party_b', 'like', "%{$keyword}%");
    });
}
// 若需要全文检索（PDF正文），使用 Elasticsearch + Elasticquent 包

借阅审批流程：

创建ContractBorrow表（状态：申请中、已批准、已归还）。
管理员/审批人收到通知后，决定是否允许下载查看。
每次查看/下载均在archive_logs中记录操作时间、IP、用户。

注意事项与最佳实践

文件存储位置：
- 归档文件应禁止直接通过URL访问，必须经过PHP验证权限与完整性后下载。
- 建议使用对象存储的归档存储类（如AWS Glacier、阿里云归档存储）减少成本。
备份策略：
- 数据库每日备份,文件存储启用跨区域复制或异地备份。
- 定期（如每月）对归档文件的哈希值进行全量校验。
合规要求：
- 若涉及电子发票、金融合同等，需要满足《电子签名法》，建议对接电子认证服务机构（CA）。
- 保留至少10年的审计日志（不可被普通管理员删除）。
性能优化：
- 对status、party_a、contract_no等字段建立索引。
- 文件上传使用分片上传+队列处理（如协程转PDF预览图、OCR等）。
测试案例：
- 正常流程：创建合同 → 上传盖章PDF → 审批 → 归档 → 校验哈希 → 借阅 → 销毁。
- 异常流程：伪造哈希值尝试下载 → 篡改文件后校验失败 → 未授权用户试图归档。