356 lines
15 KiB
Markdown
356 lines
15 KiB
Markdown
# 出入库单 · 工厂现场人员免登录链接 — 设计文档
|
||
|
||
> **日期**: 2026-06-23
|
||
> **状态**: 已批准(2026-06-23)
|
||
> **前置**: `docs/运输计划管理-需求说明文档.md`(§6 流程、BR-11)、`docs/superpowers/specs/2026-06-20-pl-arrange-dibang-design.md`(Phase 2 现场页)、`docs/superpowers/specs/2026-06-21-pl-arrange-transport-refine-design.md`(调整运输与地磅 revoke)
|
||
> **界面模式**: 公共移动端页参考 `views/public/pl/transport/index.vue`(Vant 4 + `PublicMobileShell`);管理端复制链接参考安排成功态「复制司机链接」
|
||
|
||
## 目标
|
||
|
||
为 **地磅出入库单**(`db_inbound_outbound`,入库/出库)生成 **工厂现场人员免登录链接**。现场人员打开链接后可查看单据摘要,上传附件并填写备注;计划专员在安排运输成功后可复制链接发给现场(微信等)。
|
||
|
||
---
|
||
|
||
## 已确认决策(2026-06-23)
|
||
|
||
| # | 决策 | 说明 |
|
||
|---|------|------|
|
||
| S1 | **免登录 token 链接(方案 A)** | 与司机链接一致:`token` 即凭证,**不使用门户 JWT** |
|
||
| S2 | **链接粒度:每出入库单一条** | 一产品一行地磅单 → 一条 `site_access_token` + 一条 URL |
|
||
| S3 | **首期能力边界** | 现场仅可:**查看摘要** + **上传附件** + **填写/更新备注**;**不可**在公共页修改数量、车牌、地磅重量等核心字段 |
|
||
| S4 | **覆盖式保存** | 备注与附件 URL 列表可多次保存,以最新一次为准(与司机回执页一致) |
|
||
| S5 | **token 生成时机** | **任意**创建 `db_inbound_outbound` 时均生成 token:运输地磅 bridge、地磅模块手工新建、计划生成出入库等;历史数据 token 为空时由补全脚本或首次访问管理端「复制链接」时 lazy 生成 |
|
||
| S6 | **调整运输联动** | 出入库单被软删 → 旧 token **404**;重建的新单生成 **新 token**(不保留旧链接) |
|
||
| S7 | **修订 BR-33** | 原「现场人员扫码需登录」改为:**现场人员链接免登录**;司机与现场均为 token 链接,管理端内操作仍走 JWT |
|
||
| S8 | **已完成不可补传** | `status=已完成` 时公共页**只读**:可查看摘要与历史回执,**禁止** POST feedback / 上传附件 |
|
||
| S9 | **全量出入库单均有链接** | 不限于运输联动;地磅模块**手工新建**的出入库单同样在创建时生成 `site_access_token` |
|
||
| S10 | **未完成可删改附件** | `待入库` / `待出库` 等可编辑态:Uploader 支持删除已传项并重新上传;保存时整表覆盖(与司机页一致) |
|
||
| S11 | **复制链接 UX** | 多单时同时提供「复制全部现场链接」(按产品换行拼接)与「复制本条」 |
|
||
| S12 | **计划作废展示** | 与司机页一致:链接仍可打开,展示「运输计划已作废」空态,**禁止**提交 |
|
||
| S13 | **附件类型不限制** | 公共上传**不校验 MIME/扩展名**;仅保留单文件大小上限(与门户统一上传策略一致) |
|
||
|
||
---
|
||
|
||
## 非目标(本期不做)
|
||
|
||
- 现场人员门户账号 / 短信验证码 / PIN 二次校验
|
||
- 地磅硬件对接;公共页填写磅重、毛皮净重
|
||
- 公共页创建/编辑地磅单(`db_weighing_slip`)
|
||
- 系统消息 / 微信模板自动推送(本期仅「复制链接」)
|
||
- 直销单(`plan_type=direct`)— 本就不生成出入库单
|
||
- 运输 N:N 拼车下一链接聚合多单(见 S2)
|
||
|
||
---
|
||
|
||
## 一、业务语义
|
||
|
||
### 1.1 角色与单据
|
||
|
||
| 角色 | 链接 | 关联实体 | 主要动作 |
|
||
|------|------|----------|----------|
|
||
| 司机 | `/public/pl/transport/{token}` | `pl_transport` | 运输回执、附件、备注 |
|
||
| **工厂现场人员** | **`/public/db/inventory/{token}`** | **`db_inbound_outbound`** | **出入库附件、现场备注** |
|
||
|
||
### 1.2 触发链路
|
||
|
||
**路径 A:运输安排 + 地磅联动**
|
||
|
||
```
|
||
计划专员:安排运输 + 勾选「生成地磅计划」
|
||
→ pl_dibang_bridge 创建 db_inbound_outbound(每产品一行)
|
||
→ 每行生成 site_access_token
|
||
→ arrange 响应 inventoryRecords[] 含 siteUrl
|
||
→ 成功弹窗:复制司机链接 + 复制现场链接 + 复制磅单二维码
|
||
```
|
||
|
||
**路径 B:地磅模块手工新建出入库单(S9)**
|
||
|
||
```
|
||
专员:/#/db/inventory 新建入库/出库单
|
||
→ POST create inventory
|
||
→ 后端创建时 _ensure_site_access_token
|
||
→ 列表/详情「复制现场链接」(P3)
|
||
```
|
||
|
||
**现场使用(共通)**
|
||
|
||
```
|
||
现场人员:打开 siteUrl → 上传附件、填备注 → 保存(未完成态可删改附件,S10)
|
||
计划专员:计划查看 / 地磅 Tab / 出入库列表查看现场回执
|
||
```
|
||
|
||
### 1.3 与「调整运输」的关系
|
||
|
||
沿用 `2026-06-21` 的 revoke 规则:
|
||
|
||
- 再次调整且存在历史 `pl_transport_db_link` → 先 `revoke_regeneratable_dibang_for_transport`
|
||
- 可作废的出入库单:`del_flag=1` → 其 `site_access_token` 仍保留在库中但公共 GET 因 `del_flag` 返回 **404**
|
||
- 新建出入库单 → **新 token**;专员须重新发送链接
|
||
- 已完成 / 已关联磅单不可作废 → 调整运输整体 **阻断**(与现逻辑一致)
|
||
|
||
### 1.4 公共页只读条件
|
||
|
||
| 条件 | 公共页行为 |
|
||
|------|------------|
|
||
| `del_flag=1` | 404 链接无效 |
|
||
| `status` 为 `已完成` | 可查看摘要与历史回执;**禁止**上传附件与修改备注(**不可补传**,S8) |
|
||
| 关联运输计划已作废 | 链接仍可 GET;页面展示「运输计划已作废」空态(S12,对齐司机页);**禁止** POST / 上传 |
|
||
|
||
---
|
||
|
||
## 二、现场免登录页(公共路由)
|
||
|
||
### 2.1 路由
|
||
|
||
在 `web-admin/src/router/routes/staticRoutes.ts` 注册(**不需登录**):
|
||
|
||
```ts
|
||
{
|
||
path: '/public/db/inventory/:token',
|
||
name: 'PublicDbInventorySite',
|
||
component: () => import('@views/public/db/inventory/index.vue'),
|
||
meta: { title: '出入库单', isHideTab: true, isPublicMobile: true }
|
||
}
|
||
```
|
||
|
||
### 2.2 技术栈
|
||
|
||
| 项 | 选择 |
|
||
|----|------|
|
||
| 组件库 | **Vant 4**(与司机页相同 chunk 策略) |
|
||
| 布局 | `PublicMobileShell` |
|
||
| 样式 | Fresh Mint `--primary #10b981` |
|
||
| HTTP | 新建 `utils/http/public-db.ts`(或扩展 `public-pl.ts` 为通用 `public-api.ts`),**无 JWT、无 API 加密** |
|
||
|
||
### 2.3 页面能力
|
||
|
||
| 区域 | 内容 |
|
||
|------|------|
|
||
| 单据摘要(只读) | 出入库单号(`batch_no`)、业务类型(入库/出库)、日期、往来单位、产品/规格、数量(吨)、车牌、地磅计划号 |
|
||
| 附件上传 | 多文件(上限 9,与司机页一致);**不限制文件类型**(S13);MinIO;未完成态可删除已传项(S10) |
|
||
| 现场备注 | 文本域,`site_feedback_remark`,max 500 字 |
|
||
| 历史回显 | 再次打开:展示已保存附件、`site_feedback_remark`、`site_feedback_time` |
|
||
| 底部操作 | 「保存回执」;已完成/作废态隐藏或禁用 |
|
||
|
||
**交互**:进入即可操作,无登录、无验证码(S1)。
|
||
|
||
参考:`views/public/pl/transport/index.vue`、`simple-dibang-xiaoshou/mobile-h5/src/views/inventory/fill.vue`(仅借鉴卡片布局,**不**引入其「完善数量/车牌后锁定」逻辑 — 本期字段已由专员在安排运输时写入)。
|
||
|
||
---
|
||
|
||
## 三、数据模型
|
||
|
||
### 3.1 `db_inbound_outbound` 新增字段
|
||
|
||
```sql
|
||
ALTER TABLE db_inbound_outbound
|
||
ADD COLUMN site_access_token VARCHAR(64) NULL COMMENT '现场人员免登录访问令牌' AFTER remark,
|
||
ADD COLUMN site_feedback_remark VARCHAR(500) NULL COMMENT '现场回执备注' AFTER site_access_token,
|
||
ADD COLUMN site_feedback_images TEXT NULL COMMENT '现场回执附件URLs(JSON数组)' AFTER site_feedback_remark,
|
||
ADD COLUMN site_feedback_time DATETIME NULL COMMENT '现场回执保存时间' AFTER site_feedback_images;
|
||
|
||
CREATE UNIQUE INDEX uk_db_inbound_outbound_site_token
|
||
ON db_inbound_outbound(site_access_token);
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `remark` | **保留**:系统/专员备注(如「运输计划 XXX」),公共页**只读展示** |
|
||
| `site_feedback_remark` | 现场人员填写,与 `remark` **分离** |
|
||
| `site_feedback_images` | JSON 字符串数组,与 `pl_transport.feedback_images` 同结构 |
|
||
| `site_access_token` | `secrets.token_urlsafe(32)[:64]`;**所有** `db_inbound_outbound` INSERT 路径调用 `_ensure_site_access_token` |
|
||
|
||
**生成 token 的代码路径(均需覆盖)**
|
||
|
||
| 路径 | 模块 |
|
||
|------|------|
|
||
| 运输安排地磅 bridge | `pl_dibang_bridge_service._create_db_inventory` |
|
||
| 地磅手工新建 | `backend/app/api/db/inventory.py` → `create` / 批量创建 |
|
||
| 地磅计划生成出入库 | `backend/app/api/db/plans.py` 或等价 create 逻辑 |
|
||
|
||
抽取公共函数:`backend/app/services/db_inventory_site_token.py`(或 `app/utils/db_site_token.py`)→ `_ensure_site_access_token(row)`.
|
||
|
||
同步:`docs/sql/` 增量脚本 + `shanxia2.0.sql` 快照。
|
||
|
||
### 3.2 ORM
|
||
|
||
`backend/app/models/db_models.py` → `DbInboundOutbound` 增加上述四列。
|
||
|
||
---
|
||
|
||
## 四、后端 API
|
||
|
||
### 4.1 现场公共 API(免登录)
|
||
|
||
新建 `backend/app/api/db/public_inventory.py`(或 `app/api/public_db_inventory.py`),前缀 **`/api/public/db/inventory`**:
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/{token}` | 单据摘要 + 已保存现场回执 |
|
||
| POST | `/{token}/feedback` | 保存 `siteFeedbackRemark`、`siteFeedbackImages` |
|
||
| POST | `/{token}/attachments` | multipart 上传 → MinIO,`biz_type=db_inventory_site_feedback` |
|
||
|
||
校验:
|
||
|
||
```python
|
||
db.query(DbInboundOutbound).filter(
|
||
DbInboundOutbound.site_access_token == token,
|
||
DbInboundOutbound.del_flag == 0,
|
||
).first()
|
||
# 不存在 → 404「链接无效或已失效」
|
||
```
|
||
|
||
**须加入** `API_ENCRYPT_EXCLUDE_PATHS`:
|
||
|
||
```
|
||
/api/public/db/inventory
|
||
```
|
||
|
||
### 4.2 响应 Schema(GET 示例)
|
||
|
||
```json
|
||
{
|
||
"batchNo": "CRKDH0000005",
|
||
"businessType": "出库",
|
||
"date": "2026-06-20",
|
||
"partnerCompany": "安徽哇哈哈有限责任公司",
|
||
"product": "试剂氨水",
|
||
"specification": "AR",
|
||
"quantity": 1,
|
||
"vehicleNo": "皖P13123",
|
||
"planNo": "SX-20260620203540001",
|
||
"status": "待出库",
|
||
"remark": "运输计划 SXDDH20260620000003",
|
||
"siteFeedbackRemark": "现场确认无误",
|
||
"siteFeedbackImages": ["db/inventory_site/202606/..."],
|
||
"siteFeedbackTime": "2026-06-23 10:00:00",
|
||
"readOnly": false,
|
||
"voided": false
|
||
}
|
||
```
|
||
|
||
`readOnly`: `status == "已完成"`(S8);`voided`: 关联 `pl_plan.follow_status=cancelled`(S12,仍可 GET 展示作废空态)。
|
||
|
||
### 4.3 扩展 arrange / bridge 响应
|
||
|
||
`TransportInventoryLinkRead` 增加:
|
||
|
||
```python
|
||
site_access_token: Optional[str] = Field(alias="siteAccessToken")
|
||
site_url: Optional[str] = Field(alias="siteUrl")
|
||
```
|
||
|
||
URL 构建(与司机链接一致):
|
||
|
||
```python
|
||
f"{PUBLIC_WEB_ORIGIN}/#/public/db/inventory/{site_access_token}"
|
||
```
|
||
|
||
在 `pl_dibang_bridge_service._create_db_inventory` 及 `inventory.py` 等所有创建路径内:创建后 `_ensure_site_access_token(inventory)`.
|
||
|
||
`GET /transport/plan/{id}/arrange-info` 的 `inventoryRecords` 同样返回 `siteUrl`(便于「调整运输」后复制)。
|
||
|
||
### 4.4 管理端只读扩展
|
||
|
||
- `InboundOutboundRead`(`backend/app/schemas/db/inventory.py`)增加 `siteFeedbackRemark`、`siteFeedbackImages`、`siteFeedbackTime`;**列表/详情不返回** `siteAccessToken`(防泄露)
|
||
- 新增管理端接口(可选 P1.5):`GET /db/inventory/{id}/site-url` — 仅登录用户可复制链接(用于事后补发)
|
||
|
||
---
|
||
|
||
## 五、前端(管理端)
|
||
|
||
### 5.1 安排运输成功态(`PlPlanArrangeDialog`)
|
||
|
||
在现有「复制司机链接 / 复制磅单二维码」旁(S11):
|
||
|
||
| 场景 | UI |
|
||
|------|-----|
|
||
| `inventoryRecords.length === 1` | 「复制现场链接」 |
|
||
| `inventoryRecords.length > 1` | 「复制全部现场链接」(`产品名:url` 换行拼接)+ 每条记录旁「复制本条」 |
|
||
|
||
### 5.2 计划查看 · 地磅 Tab(`PlPlanViewTabs`)
|
||
|
||
在出入库卡片增加:
|
||
|
||
- 现场备注、附件缩略图/下载
|
||
- 上次保存时间
|
||
- 按钮「复制现场链接」(调 arrange-info 或 inventory site-url API)
|
||
|
||
### 5.3 地磅出入库列表(P3,S9)
|
||
|
||
操作列「复制现场链接」:**所有**未删除出入库单均可用(含手工新建);已完成单仍可复制链接供查看(公共页只读)。
|
||
|
||
---
|
||
|
||
## 六、安全与约束
|
||
|
||
| 项 | 规则 |
|
||
|----|------|
|
||
| Token 熵 | 与 `driver_access_token` 相同生成方式 |
|
||
| 暴露面 | 列表 API **不返回** token;仅 arrange 成功、arrange-info、管理员 site-url 接口 |
|
||
| 上传 | **不限制 MIME/扩展名**(S13);单文件大小上限与门户统一上传策略一致;最多 9 个附件 URL |
|
||
| 租户 | 上传路径带 `tenant_no`;OSS `biz_type=db_inventory_site_feedback` |
|
||
| 已完成单 | 公共 POST / 上传均返回 400「单据已完成,无法修改回执」(S8:不允许补传) |
|
||
|
||
---
|
||
|
||
## 七、流程图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant UI as 安排运输弹窗
|
||
participant API as POST arrange
|
||
participant BR as pl_dibang_bridge
|
||
participant DB as db_inbound_outbound
|
||
participant Site as 现场 H5
|
||
|
||
UI->>API: arrange + generateDibangPlan
|
||
API->>BR: sync_dibang_for_transport
|
||
loop 每个产品行
|
||
BR->>DB: INSERT + site_access_token
|
||
end
|
||
API-->>UI: inventoryRecords[].siteUrl
|
||
UI->>Site: 专员复制链接 → 微信发送
|
||
Site->>DB: GET/POST public feedback + attachments
|
||
```
|
||
|
||
---
|
||
|
||
## 八、验收标准
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| V1 | 出库单安排 + 勾地磅,1 个产品 | 返回 `siteUrl`;手机浏览器免登录打开;可上传附件与备注 |
|
||
| V2 | 2 个产品 | 2 条不同 `siteUrl`;互不影响 |
|
||
| V3 | 保存后刷新链接 | 回显备注与附件 |
|
||
| V4 | 调整运输重建地磅单 | 旧链接 404;新链接可用 |
|
||
| V5 | 出入库单已完成 | 公共页只读或禁止 POST |
|
||
| V6 | 计划作废 | 公共页展示作废空态;POST 拒绝(S12) |
|
||
| V7 | 管理端列表 | 不泄露 token;查看 Tab 可见现场回执 |
|
||
| V8 | 未勾地磅 | arrange 无 `inventoryRecords`;手工新建单仍有 siteUrl(S9) |
|
||
| V9 | 地磅模块手工新建出入库单 | 创建后即有 token;列表可「复制现场链接」 |
|
||
| V10 | 未完成态删附件后保存 | 列表不再含已删附件(S10) |
|
||
|
||
---
|
||
|
||
## 九、实施分期
|
||
|
||
| Phase | 内容 |
|
||
|-------|------|
|
||
| **P1** | DDL + ORM + 全路径 token 生成 + 公共 GET/POST + Vant 页 |
|
||
| **P2** | 安排成功态复制链接(含复制全部)+ `PlPlanViewTabs` 回显 |
|
||
| **P3** | 出入库列表复制链接 + `GET site-url` 补发 + 历史 token 补全 + 文档修订 BR-33 |
|
||
|
||
---
|
||
|
||
## 十、参考路径
|
||
|
||
| 说明 | 路径 |
|
||
|------|------|
|
||
| 司机公共页(模板) | `web-admin/src/views/public/pl/transport/index.vue` |
|
||
| 司机公共 API | `backend/app/api/pl/public_transport.py` |
|
||
| 地磅 bridge 创建出入库 | `backend/app/services/pl_dibang_bridge_service.py` |
|
||
| 安排弹窗成功态 | `web-admin/src/components/business/pl-plan-arrange-dialog/index.vue` |
|
||
| 磅单二维码 | `web-admin/src/components/business/db/DbPoundSlipQrcodeDialog.vue` |
|
||
| 原 H5 参考 | `simple-dibang-xiaoshou/mobile-h5/src/views/inventory/fill.vue` |
|