增加气站合同附件受控上传与预览

docs/06-气站管理系统需求.md

@@ -100,6 +100,7 @@
 - 启用仅适用于草稿合同；已终止合同不得直接启用，只能通过续签填写新的生效时间、到期时间和原因后恢复履约。
 - 配送合同创建、草稿编辑和续签必须填写到期时间，且到期时间必须晚于生效时间；历史缺失值应提示补录，不得推测回填。
 - 合同只能选择当前气站用户及当前气站配送点。
+- 合同附件仅支持单个不超过 10 MiB 的 PDF；创建和草稿编辑时通过受控接口上传、替换或移除，详情页通过气站鉴权和合同归属校验后预览，不向前端暴露内部存储地址。
 - 合同气瓶支持绑定和受控解绑。
 - 合同修订记录只读，不允许修改或删除。
 - 合同修订记录不展示公共软删除时间等无业务意义的基础设施字段。
@@ -199,3 +200,4 @@
 9. 邀请二维码由配置 URL 和当前气站 identity 实时生成，不产生持久化记录。
 10. 后端测试、路由权限测试、前端类型检查、契约检查和生产构建通过。
 11. 20 类标准资源均可从列表进入独立详情页并刷新；11 类可新建资源和 8 类可编辑资源具备对应独立页面。
+12. 配送合同新建和草稿编辑页显示 PDF 选择控件而非附件地址文本框；附件预览、替换和移除均受当前气站数据范围约束。

docs/操作日志_气站合同附件上传_20260818.md

@@ -0,0 +1,51 @@
+# 操作日志：气站合同附件上传
+
+操作时间：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、重复保存、编辑替换、移除、跨气站合同和旧地址不可用。

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

@@ -0,0 +1,71 @@
+# 项目文档：气站合同附件上传 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。
+- 自动化浏览器没有气站登录态，本次未对真实受保护合同执行上传或读取；完整交互仍需使用测试气站账号验收。