完善配送点合同附件管理
This commit is contained in:
czl231
40
docs/操作日志_配送点合同附件管理_20260822.md
Normal file
40
docs/操作日志_配送点合同附件管理_20260822.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# 操作日志：配送点合同附件管理
|
||||
|
||||
操作时间：2026-08-22
|
||||
操作类型：扩展、修改
|
||||
影响模块：配送合同列表、独立记录页、配送域附件接口、项目文档
|
||||
|
||||
## 操作前状态
|
||||
|
||||
配送合同列表直接展示 `/uploads/contracts/...`，新建和编辑页允许手填 `file_uri`；配送域没有附件上传、清理和鉴权读取路由。合同列表 API 也会返回内部附件路径。
|
||||
|
||||
## 具体操作
|
||||
|
||||
1. 在配送域增加上传、临时清理和正式附件读取包装，并在读取前校验当前配送点合同归属。
|
||||
2. 复用平台合同附件的 10 MiB PDF 校验、30 分钟签名收据、并发版本和安全响应头。
|
||||
3. 配送合同列表经过统一敏感字段保护，删除 `file_uri`，增加 `has_attachment`。
|
||||
4. 5176 新增 PDF 选择、拖拽、替换、确认移除、预览、下载和失败清理流程。
|
||||
5. 新版前端保存时主动删除 `file_uri`，仅提交签名收据和附件版本。
|
||||
6. 更新独立资源项目文档，纠正与原始敏感数据保护要求冲突的文本 URI 边界。
|
||||
|
||||
## 行为变化
|
||||
|
||||
- 变更前：页面和网络响应暴露内部存储路径，管理员可手填任意 URI。
|
||||
- 变更后：列表只显示附件状态和鉴权入口；详情可预览、下载；草稿可上传、替换和移除；非草稿只读。
|
||||
- 兼容性：数据库字段、合同 CRUD 路径和后端旧 `file_uri` 输入保持兼容，5176 不再使用旧输入。
|
||||
|
||||
## 验证结果
|
||||
|
||||
- `go test ./internal/logic/common ./internal/logic/delivery ./internal/logic/platform/gasorder ./internal/routers ./cmd/cli`：通过。
|
||||
- `npm.cmd run type:check`：通过。
|
||||
- `npm.cmd run resource-pages:check`：通过，详情 17、新建 9、编辑 5，并覆盖附件三条路由和前端签名收据编排。
|
||||
- `npm.cmd run contract:check`、`npm.cmd run profile:check`：通过。
|
||||
- `npm.cmd run build`：通过，2639 个模块完成生产构建。
|
||||
- 后端已重建并监听 `12426`；浏览器会话当前停留在登录页，登录后的视觉回归待补。
|
||||
|
||||
## 风险评估
|
||||
|
||||
- 临时上传成功但合同保存失败：前端调用签名清理接口，服务端仍有有效期兜底。
|
||||
- 历史附件缺失或格式异常：详情显示需重传，启用操作继续由服务端拒绝。
|
||||
- 并发编辑附件：附件版本与旧 URI 双重条件防止覆盖他人变更。
|
||||
- 5173 列表响应的同类潜在泄露未在本次扩大处理，已登记为后续安全债务。
|
||||
@@ -26,6 +26,7 @@
|
||||
14. 资质列表新增人员姓名上下文、安全返回、重复人员列隐藏；新建预填所属人员，创建和编辑锁定归属。
|
||||
15. 新增后端生成的 `searchFields` 契约；无有效字段时隐藏搜索区，枚举字段支持中文名称和内部编码。
|
||||
16. 标准列表搜索标签统一为“模糊搜索”，输入框继续提示当前资源的具体可搜索字段。
|
||||
17. 配送合同附件由文本 URI 升级为受控 PDF：列表脱敏、详情预览下载、草稿上传替换移除，并增加配送点范围鉴权接口。
|
||||
|
||||
## 操作后状态
|
||||
|
||||
@@ -62,6 +63,7 @@
|
||||
- 列表头像回归：配送人员、用户账户显示受控圆形头像，其他资源不生成无效头像列；数据库 ID 列已从全部标准列表移除；点击刷新后头像重新加载正常。
|
||||
- 资质关联回归：有效人员仅返回本人资质，标题和上下文显示服务端姓名及唯一标识；新建页预填并锁定人员，缺少上下文自动返回，伪造人员标识显示错误且不渲染表格。
|
||||
- 搜索回归：资质页提示“可搜索：资质类型、资质编号”；银行卡页不显示关键字、查询和重置，仅保留刷新。
|
||||
- 合同附件回归：Go 测试、附件路由检查、前端类型检查和生产构建通过；登录后的视觉回归记录在专项操作日志中。
|
||||
|
||||
## 风险评估
|
||||
|
||||
|
||||
53
docs/项目文档_配送点合同附件管理_v1.0.md
Normal file
53
docs/项目文档_配送点合同附件管理_v1.0.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# 项目文档：配送点合同附件管理 v1.0
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
配送点管理端将配送合同的“附件地址”文本字段升级为受控 PDF 附件流程。数据库继续使用 `gasorder_contract.file_uri` 保存服务端受控路径，但浏览器只接收附件状态、签名收据和文件 Blob，不读取或提交内部路径。
|
||||
|
||||
技术栈：Go、Gin、GORM、Vue 3、TypeScript、Arco Design。运行时依赖现有合同附件目录及服务端签名密钥。
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```text
|
||||
backend/api/internal/
|
||||
├── logic/delivery/order.go # 配送点范围包装、列表脱敏
|
||||
├── logic/platform/gasorder/ # 复用 PDF 校验、收据和文件服务
|
||||
└── routers/delivery.go # 上传、清理、读取路由
|
||||
frontend/delivery_admin/src/
|
||||
├── api/contract-attachment.ts # 附件 HTTP 客户端
|
||||
├── views/resource/ContractAttachmentField.vue
|
||||
├── views/resource/use-contract-attachment.ts
|
||||
├── views/resource/ResourceRecordPage.vue # 详情、表单和保存编排
|
||||
└── views/shared/ResourceListPage.vue # 脱敏附件状态入口
|
||||
```
|
||||
|
||||
## 3. 核心流程
|
||||
|
||||
1. 新建或草稿编辑页选择单个 PDF，前端预检扩展名、MIME 和 10 MiB 上限。
|
||||
2. 点击保存后上传至临时目录，服务端校验真实 MIME、`%PDF-` 文件头和 `%%EOF`，并签发绑定当前操作人的 30 分钟收据。
|
||||
3. 合同创建或更新提交 `attachment_receipt`；替换或移除同时提交 `attachment_version`，避免并发覆盖。
|
||||
4. 保存失败时调用清理接口；取消编辑不会改变原附件。
|
||||
5. 预览和下载只接受合同 identity，经当前气站、配送点和 JWT 范围校验后返回 `private, no-store` 的 PDF。
|
||||
|
||||
## 4. 安全与业务规则
|
||||
|
||||
- 合同列表响应删除 `file_uri`，只返回 `has_attachment`。
|
||||
- 详情响应使用 `attachment` 元数据，旧路径异常时显示“需重新上传”。
|
||||
- 只有草稿合同可上传、替换或移除；启用前必须存在有效 PDF。
|
||||
- 跨配送点读取统一不可访问，不返回文件路径或磁盘信息。
|
||||
- 新版配送点管理端始终删除载荷中的 `file_uri`；后端旧字段仅为兼容历史调用保留。
|
||||
|
||||
## 5. 接口
|
||||
|
||||
- `POST /gasorder_contract/attachment/upload`：上传临时 PDF。
|
||||
- `POST /gasorder_contract/attachment/cleanup`：按签名清理凭证删除临时文件。
|
||||
- `GET /gasorder_contract/:identity/attachment`：鉴权预览或下载正式附件。
|
||||
|
||||
## 6. 维护与验证
|
||||
|
||||
修改附件流程后应运行配送逻辑、平台附件服务和路由测试，以及配送前端 `type:check`、`resource-pages:check`、`contract:check` 和生产构建。不得恢复普通 URI 输入框或 `<a href="file_uri">` 直链。
|
||||
|
||||
## 7. 变更记录
|
||||
|
||||
- v1.0（2026-08-22）：新增配送域附件接口、列表脱敏、详情预览下载及草稿上传替换移除。
|
||||
- 修正《项目文档_配送点独立资源页面_v1.0》中 2026-08-22 新增的“文本 URI”边界，使其重新符合 2026-07-30 原始敏感数据保护基线。
|
||||
@@ -86,8 +86,9 @@ npm.cmd run build
|
||||
- 新增配送人员、用户账户的受控头像缩略图，并移除全部标准列表的数据库自增 ID。
|
||||
- 新增配送人员资质的强制人员范围、上下文展示、关系预填锁定和安全返回链路。
|
||||
- 新增后端生成的资源搜索契约，隐藏无效搜索并支持枚举中文名称与稳定编码。
|
||||
- 新增配送合同受控 PDF 附件上传、鉴权预览、下载、替换和移除流程，列表及接口均不暴露内部路径。
|
||||
- 保持配送点资料专用只读页面和现有公共后端接口不变。
|
||||
|
||||
## 7. 已知边界
|
||||
|
||||
独立页面只使用配送端数据范围内的关系查询和 CRUD 能力；头像复用公共受控上传入口，并通过配送点专属鉴权接口读取。不引入合同附件上传、平台角色或跨组织账户摘要接口，附件 URI 字段仍按原后端文本契约展示或填写。
|
||||
独立页面只使用配送端数据范围内的关系查询和 CRUD 能力；头像与合同附件均通过配送点专属鉴权接口读取。合同附件仅接受不超过 10 MiB 的真实 PDF，草稿可上传、替换或确认移除，非草稿只允许预览和下载。页面与配送合同列表响应不得展示或返回内部附件 URI。平台角色和跨组织账户摘要接口仍不在本项目范围内。
|
||||
|
||||
Reference in New Issue
Block a user