54 lines
3.0 KiB
Markdown
54 lines
3.0 KiB
Markdown
# 项目文档：配送点合同附件管理 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 原始敏感数据保护基线。
|