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