# 操作日志：气站合同附件上传

操作时间：2026-08-18 21:43:42
操作类型：扩展
影响模块：气站管理端 5175、气站 API 合同附件路由、气站需求文档

## 操作前状态

- 5175 配送合同表单把 `file_uri` 渲染为“附件地址”文本输入框。
- 气站前端已存在从 5173 复制的附件控件和状态逻辑，但标准记录页未接线，附件客户端默认地址仍误指向平台主管 `/heqi/platform/v1`。
- 后端只有平台主管附件专用路由；气站合同创建和更新虽复用平台业务逻辑，但没有气站鉴权域的上传、清理与预览入口。

## 具体操作

1. 将气站合同字段声明为 `contract-file`，在标准记录页接入选择、拖拽、预览、替换、移除、失败清理和未保存提示。
2. 将气站附件客户端默认 API 前缀修正为 `/heqi/gas/v1`。
3. 在气站 API 新增上传、临时清理和预览路由；上传与清理验证当前气站账号，预览额外校验合同归属。
4. 新增气站附件路由回归测试，并同步气站需求和项目维护文档。

## 操作后状态

- 5175 合同新建和草稿编辑页显示单 PDF 上传控件，不再允许手填内部附件地址。
- 合同详情页可通过鉴权 Blob 预览附件；旧地址不可用时提示重新上传。
- 气站 JWT 只访问气站域附件接口，跨气站合同在下载前被归属校验拦截。
- 5173 平台总后台、合同数据库结构和公共合同接口保持兼容。

## 代码变更

- `backend/api/internal/logic/gas/gasorder.go`：新增 `UploadGasorderContractAttachment`、`CleanupGasorderContractAttachment`、`ServeGasorderContractAttachment`。
- `backend/api/internal/routers/gas_business.go`：新增 3 条合同附件路由。
- `backend/api/internal/routers/gas_test.go`：新增 `TestGasContractAttachmentRoutes`。
- `frontend/gas_admin/src/api/contract-attachment.ts`：改用气站 API 前缀。
- `frontend/gas_admin/src/api/resources.ts`：合同附件改为专用文件字段。
- `frontend/gas_admin/src/views/resource/ResourceRecordPage.vue`：接入完整附件页面流程。

## 验证结果

- `go test ./...`：通过。
- `go vet ./...`：通过。
- `go build ./cmd/main/main.go`：通过。
- `pnpm type:check`：通过。
- `pnpm contract:check`：通过，20 个资源。
- `pnpm build`：通过。
- `pnpm lint`：命令成功，报告 190 条仓库既有警告；本次改动未产生 lint 错误。
- 浏览器只读检查：5175 服务和登录页正常、控制台无错误；因自动化会话没有气站登录态，未提交账号或读取受保护合同。

## 风险评估

- 风险：上传和绑定仍复用平台主管包中的既有实现，操作人名称在气站账号场景可能为空，但操作人 identity、合同 identity、动作和结果仍会记录。
- 缓解：气站路由受独立 JWT 中间件保护，入口验证有效气站账号，下载执行合同归属校验；签名收据继续绑定操作人 identity 并限制有效期。
- 后续人工边界验收：合法 PDF、非 PDF、空文件、超过 10 MiB、重复保存、编辑替换、移除、跨气站合同和旧地址不可用。