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

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

操作时间：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、重复保存、编辑替换、移除、跨气站合同和旧地址不可用。