# 项目文档：配送点合同附件管理 v1.0

## 1. 项目概述

配送点管理端将配送合同的“附件地址”文本字段升级为受控 PDF 附件流程。数据库继续使用 `gasorder_contract.file_uri` 保存服务端受控路径，但浏览器只接收附件状态、签名收据和文件 Blob，不读取或提交内部路径。

技术栈：Go、Gin、GORM、Vue 3、TypeScript、Arco Design。运行时依赖现有合同附件目录及服务端签名密钥。

## 2. 目录结构

```text
backend/api/internal/
├── logic/delivery/order.go                 # 配送点范围包装、列表脱敏
├── logic/platform/gasorder/                # 复用 PDF 校验、收据和文件服务
└── routers/delivery.go                     # 上传、清理、读取路由
frontend/delivery_admin/src/
├── api/contract-attachment.ts              # 附件 HTTP 客户端
├── views/resource/ContractAttachmentField.vue
├── views/resource/use-contract-attachment.ts
├── views/resource/ResourceRecordPage.vue   # 详情、表单和保存编排
└── views/shared/ResourceListPage.vue       # 脱敏附件状态入口
```

## 3. 核心流程

1. 新建或草稿编辑页选择单个 PDF，前端预检扩展名、MIME 和 10 MiB 上限。
2. 点击保存后上传至临时目录，服务端校验真实 MIME、`%PDF-` 文件头和 `%%EOF`，并签发绑定当前操作人的 30 分钟收据。
3. 合同创建或更新提交 `attachment_receipt`；替换或移除同时提交 `attachment_version`，避免并发覆盖。
4. 保存失败时调用清理接口；取消编辑不会改变原附件。
5. 预览和下载只接受合同 identity，经当前气站、配送点和 JWT 范围校验后返回 `private, no-store` 的 PDF。

## 4. 安全与业务规则

- 合同列表响应删除 `file_uri`，只返回 `has_attachment`。
- 详情响应使用 `attachment` 元数据，旧路径异常时显示“需重新上传”。
- 只有草稿合同可上传、替换或移除；启用前必须存在有效 PDF。
- 跨配送点读取统一不可访问，不返回文件路径或磁盘信息。
- 新版配送点管理端始终删除载荷中的 `file_uri`；后端旧字段仅为兼容历史调用保留。

## 5. 接口

- `POST /gasorder_contract/attachment/upload`：上传临时 PDF。
- `POST /gasorder_contract/attachment/cleanup`：按签名清理凭证删除临时文件。
- `GET /gasorder_contract/:identity/attachment`：鉴权预览或下载正式附件。

## 6. 维护与验证

修改附件流程后应运行配送逻辑、平台附件服务和路由测试，以及配送前端 `type:check`、`resource-pages:check`、`contract:check` 和生产构建。不得恢复普通 URI 输入框或 `<a href="file_uri">` 直链。

## 7. 变更记录

- v1.0（2026-08-22）：新增配送域附件接口、列表脱敏、详情预览下载及草稿上传替换移除。
- 修正《项目文档_配送点独立资源页面_v1.0》中 2026-08-22 新增的“文本 URI”边界，使其重新符合 2026-07-30 原始敏感数据保护基线。