Files
shanxia2.0/docs/superpowers/specs/2026-06-23-pl-site-inventory-link-design.md
T
2026-06-23 23:30:57 +08:00

356 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 出入库单 · 工厂现场人员免登录链接 — 设计文档
> **日期**: 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` |