# 项目文档：气站合同附件上传 v1.0

## 1. 项目概述

- 项目：物联网智能瓶阀平台气站管理端。
- 本次功能：在气站管理端 5175 的配送合同新建、草稿编辑和详情页接入与平台总后台 5173 一致的受控 PDF 附件交互。
- 技术栈：Vue 3、TypeScript、Arco Design、Gin、GORM。
- 运行环境：前端 `http://localhost:5175`，后端 `/heqi/gas/v1`。

附件继续复用 `gasorder_contract.file_uri` 保存服务端受控地址。浏览器只接收附件元数据和签名收据，不读取或提交内部存储路径。

## 2. 目录结构说明

```text
platforms/
├── frontend/gas_admin/src/
│   ├── api/
│   │   ├── contract-attachment.ts       # 气站域附件上传、清理和预览客户端
│   │   └── resources.ts                 # 将合同附件声明为专用文件字段
│   └── views/resource/
│       ├── ContractAttachmentField.vue  # PDF 选择、拖拽、预览和移除控件
│       ├── use-contract-attachment.ts   # 上传收据、并发版本和失败清理状态
│       └── ResourceRecordPage.vue       # 标准记录页附件流程编排
├── backend/api/internal/
│   ├── logic/gas/gasorder.go            # 气站范围包装与合同归属校验
│   └── routers/
│       ├── gas_business.go              # 气站合同附件路由
│       └── gas_test.go                  # 路由回归测试
└── docs/
    └── 06-气站管理系统需求.md           # 气站附件需求和验收口径
```

## 3. 核心文件说明

### `frontend/gas_admin/src/views/resource/ResourceRecordPage.vue`

- 新建和编辑页向字段组件传入合同附件状态。
- 保存前上传本地 PDF，并把签名收据加入合同载荷。
- 保存失败时清理临时文件；详情页显示附件可用状态和鉴权预览入口。
- 未保存附件变化纳入离开页面确认。

### `backend/api/internal/logic/gas/gasorder.go`

- 上传和清理入口先验证当前登录账号仍关联有效气站。
- 下载入口额外校验合同属于当前气站，再复用现有受控 PDF 输出逻辑。
- 合同创建和更新继续复用既有绑定、并发版本和旧文件清理事务。

### `frontend/gas_admin/src/api/contract-attachment.ts`

- API 默认前缀改为 `/heqi/gas/v1`，不再误用平台主管接口。
- 上传仅接受 PDF，预览返回 Blob，不暴露 `file_uri`。

## 4. 变更记录

- 将气站合同 `file_uri` 字段由普通文本输入改为“合同附件”专用控件。
- 新增气站域上传、临时清理和鉴权预览路由。
- 补齐新建、草稿编辑、详情预览、替换、移除和失败回滚流程。
- 新增气站附件路由回归测试并同步需求验收项。
- 未新增数据库表、字段或依赖，平台总后台 5173 行为保持不变。

## 5. 维护指南

- 调整大小或文件类型时，前端预检与后端真实内容校验必须同步，后端校验始终是安全边界。
- 新增其他业务端附件能力时，应先做该业务端的数据范围校验，再复用受控存储能力，不得直接开放平台路由。
- 修改气站路由后运行后端路由测试；修改表单后运行类型检查、契约检查和生产构建。
- 人工验收至少覆盖：合法 PDF、新建保存、编辑替换、移除、无效类型、超限文件、跨气站下载和旧地址不可用提示。

## 6. 已知限制

- 当前仅支持单个 PDF，最大 10 MiB。
- 自动化浏览器没有气站登录态，本次未对真实受保护合同执行上传或读取；完整交互仍需使用测试气站账号验收。