platforms/docs/项目文档_气站合同附件上传_v1.0.md

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

1. 项目概述

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

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

2. 目录结构说明

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。
• 自动化浏览器没有气站登录态，本次未对真实受保护合同执行上传或读取；完整交互仍需使用测试气站账号验收。