# 配送点管理系统需求

## 1. 文档目的

本文以 `docs/05-平台总后台需求.md` 的资源、权限、状态机和验收口径为基线，定义配送点管理系统的实施范围。

- 前端：`frontend/delivery_admin`。
- 后端：复用 `backend/api`，业务逻辑位于 `internal/logic/delivery`。
- API 前缀：`/heqi/delivery/v1`。
- 前端开发端口：`5176`。
- 数据模型：复用现有 `backend/api/internal/models`，本期不新增角色、菜单、邀请、库存或质控表。

## 2. 系统定位与边界

配送点管理系统面向配送点管理员，负责当前配送点的人员、用户、合同、订单调度、财务和邀请注册。所有资源必须以后端 JWT 中的 `delivery_basic_identity` 为数据范围。

本期包含：

- 本点运营概览及订单状态报表。
- 配送点资料只读视图。
- 本点配送人员、账号和资质管理。
- 本点用户、地址和唯一服务关系管理。
- 本点用户配送合同、合同气瓶和修订记录。
- 创建配送订单、调整金额、分配、回收及本点改派。
- 订单异常、恢复和取消。
- 本点钱包、银行卡、支付、流水、退款、充值、提现和结算。
- 基于所属气站及当前配送点 identity 的邀请二维码。

本期明确不包含：

- 库存、配送仓、库存流水、调拨和盘点。
- 电商商品、购物车、商城订单、评价和营销。
- 营业设置、班次、组织变更申请、独立质控记录、服务记录、用户变更申请和对账异议。
- 平台治理、生产设备和客服工单。
- Web 后台补录配送、定位、扫码、签收、收款或现场证据。

## 3. 配置、身份与鉴权

### 3.1 全局配置

气站端、配送点端和平台钱包共用：

```yaml
Global:
  UserRegisterURL: http://localhost:5174/register
  ManualRechargeMaxAmount: 100000000
```

充值上限单位为分。启动时必须校验注册地址为有效 HTTP/HTTPS URL，充值上限大于零。

### 3.2 登录与会话

- 配送点管理员账号由平台或所属气站创建。
- 仅启用、关联启用配送点且 `role_code = admin` 的 `delivery_account` 可以登录。
- JWT 客户端固定为 `delivery_admin`，与平台和气站管理端会话隔离。
- 菜单由后端 `delivery_menu` 接口按 `role_code` 返回，前端登录后据此渲染。
- 修改本人密码必须校验当前密码；新密码只要求不少于 6 位。
- 配送人员和用户账号新增或重置密码时同样只要求不少于 6 位。
- 不新增角色表或菜单表。

### 3.3 数据身份与归属

- HTTP、前端、日志和审计统一使用 `identity`，不暴露数据库自增 ID。
- 配送点只能访问 `delivery_basic_id` 为当前配送点的人员、用户关系、合同和订单。
- 当前配送点所属气站由后端解析，前端不能提交其他气站或配送点改变归属。
- 每个用户只能存在一条未归档服务关系，并固定归属一个气站和一个配送点。
- 所有删除均为归档；订单、合同修订、资金流水、轨迹、签收和支付事实不得物理删除。

## 4. 菜单与功能

### 4.1 数据概述

| 菜单 | 能力 |
| --- | --- |
| 运营概览 | 本点配送人员、用户、合同和订单数量 |
| 订单报表 | 本点订单状态分布 |

报表只使用当前配送点真实数据，不混入其他配送点或电商数据。

### 4.2 配送点资料

- 查看当前配送点编码、名称、负责人、地址、所属气站和状态。
- 配送点不能在本系统修改组织主数据、归属气站或状态。

### 4.3 配送人员管理

- 配送点可创建、编辑、启停、重置密码和归档本点配送人员。
- 新建人员的 `role_code` 由服务端固定为 `delivery`。
- 人员的气站及配送点归属由服务端固定为当前范围。
- 资质支持新增、编辑、启停和归档。
- 删除均为归档；存在未完成订单时禁止归档人员。
- 不允许创建安装、运维、仓管、调度员或质控角色账号。

### 4.4 用户管理

- 支持本点用户新增、编辑、启停、重置密码和归档。
- 创建用户时在同一事务内建立所属气站与当前配送点服务关系。
- 支持本点用户地址新增、编辑、启停和归档。
- 配送点不能将用户迁移到其他配送点或其他气站。
- 归档用户时同时归档地址及服务关系。
- 用户存在未完成订单、未关闭工单、钱包余额、可提现余额或待处理提现时禁止归档。

### 4.5 合同管理

- 配送点可完整管理当前配送点用户的配送合同。
- 支持创建、草稿编辑、启用、续签和终止。
- 支持绑定和受控解绑当前用户已有气瓶。
- 合同修订记录只读。
- 服务端强制合同所属气站和配送点为当前范围。
- 不得查看或操作所属气站下其他配送点的合同。

### 4.6 配送订单与调度

- 配送点可根据当前配送点生效合同创建订单。
- 服务端强制订单创建方为当前配送点。
- 商品金额依据合同气瓶单价由服务端计算。
- 配送点可分配、回收或在本点配送人员之间改派。
- 可选配送人员必须同时满足：
  - 属于当前配送点及所属气站；
  - 账号启用且未归档；
  - `role_code = delivery`；
  - `work_status = on_duty`；
  - 至少有一条启用且未过期的资质。
- 不支持跨配送点调度。
- 配送点后台可执行：创建、分配、回收、改派、调整金额、标记异常、恢复、取消。
- 配送点后台不得执行：开始罐装、罐装完成、开始配送、到达、等待签收、完成订单。
- App 产生的定位、扫码、照片、视频、签名、收款、签收和现场证据只读，后台不得补造或修改。

### 4.7 订单金额调整

- 仅待处理或已分配订单允许调整。
- 存在成功支付记录后禁止调整。
- 只允许修改配送费和优惠金额。
- 商品金额保持合同计算结果。
- 应付金额由服务端重新计算：

```text
应付金额 = 商品金额 + 配送费 - 优惠金额
```

- 配送费和优惠金额不得为负，应付金额必须大于零，并校验整数溢出。
- 每次调整必须填写原因，记录调整操作人和不可变历史。
- 前端不得直接提交或覆盖商品金额和最终应付金额。

### 4.8 财务管理

- 本点钱包、银行卡、支付记录、钱包流水、退款和结算结果只读。
- 配送点可以创建提现申请，但不能审批、驳回或标记完成。
- 配送点管理员可以给当前配送点钱包自主充值。
- 充值必须填写幂等号、金额、原因和备注。
- 单笔充值金额必须大于零且不超过 `Global.ManualRechargeMaxAmount`。
- 充值在数据库事务内增加钱包余额并创建不可变 `wallet_record`。
- 自主充值不增加可提现余额，防止充值后直接提现。
- 充值流水记录配送点管理员 identity 和显示名称。
- 禁止给其他配送点充值，禁止修改或删除充值流水。
- 现有对账模型没有配送点归属字段，因此本期不展示平台全局对账记录，也不新增对账异议模型。

### 4.9 邀请注册

- 邀请二维码不持久化，不新增邀请表。
- 后端基于 `Global.UserRegisterURL` 实时生成：

```text
register?gas_identity={所属气站identity}&delivery_identity={当前配送点identity}
```

- 前端生成二维码并支持下载 PNG。
- 不提供启停、过期、扫码记录和邀请统计。
- 二维码不得携带数据库 ID、密码或 JWT。

## 5. 资源页面模式

| 资源 | 模式 | 说明 |
| --- | --- | --- |
| `delivery_profile` | `readonly` | 当前配送点资料 |
| `staff_account`、`staff_credential` | `writable` | 仅配送角色，删除为归档 |
| `user_account`、`user_address` | `writable` | 服务关系由服务端事务维护 |
| `gasorder_contract` | `managed` | 生命周期使用专用动作 |
| `gasorder_contract_product` | `append_only` | 解绑使用专用动作 |
| `gasorder_contract_revision`、`product_info` | `readonly` | 合同历史及可选气瓶 |
| `gasorder_basic` | `append_only` | 创建及专用调度/状态动作 |
| `wallet_basic`、`wallet_bank`、`wallet_payment`、`wallet_record`、`wallet_refund` | `readonly` | 当前配送点钱包范围 |
| `wallet_recharge`、`wallet_apply_cash` | `append_only` | 充值及提现申请 |
| `fin_settlement` | `readonly` | 当前配送点结算结果 |

## 6. 菜单输出

菜单定义位于 `backend/api/internal/logic/delivery/menu.go`，仅 `admin` 返回：

1. 数据概述：运营概览、订单报表。
2. 配送点资料：本点资料。
3. 配送人员管理：新增配送人员、配送人员列表；资质为隐藏子资源。
4. 用户管理：用户账户；地址和服务关系为隐藏子资源。
5. 合同管理：配送合同；合同气瓶、修订记录、可选气瓶为隐藏子资源。
6. 配送订单：创建订单、订单列表；分配、状态、轨迹、签收、支付记录为隐藏只读子资源。
7. 财务管理：钱包、银行卡、支付记录、钱包流水、退款记录、钱包充值、提现申请、结算结果。
8. 邀请注册：邀请二维码。

菜单中不得出现库存、配送仓、电商、平台治理、生产设备、客服工单或独立质控模块。

## 7. 接口与安全要求

- 匿名接口仅允许登录，其余接口必须验证 JWT、客户端、角色、账号状态和当前配送点。
- 路由、菜单、资源模式、后端契约和前端页面必须同步。
- 状态流转、金额、归属、调度资质、用户唯一服务关系和归档阻断均由服务端校验。
- 密码、银行卡密文和证件密文不得返回前端。
- 手机号、地址、定位、合同文件及现场证据遵循统一敏感数据保护规则。
- 订单创建、金额调整、分配、回收、改派、充值和提现必须记录操作人及原因。
- 充值、订单创建和提现使用幂等号，重复请求不得重复生成业务事实。
- 前端菜单隐藏和按钮禁用不构成权限控制。

## 8. 验收标准

1. 配送点管理员登录后由后端菜单渲染前端，非 `admin` 角色无菜单。
2. 平台、气站和配送点 JWT 互相隔离。
3. 所有业务资源只能访问当前配送点数据。
4. 配送人员、用户、合同、订单调度、财务和邀请功能可用。
5. 系统中没有库存、配送仓、电商和无模型支撑的规划功能。
6. 调度严格校验本点归属、配送角色、在岗状态和有效资质。
7. 金额调整只影响配送费和优惠金额，成功支付后不可调整。
8. Web 后台不暴露罐装、开始配送、到达、签收或完成订单动作。
9. 自主充值只增加余额、不增加可提现余额，并产生不可变资金流水。
10. 用户、人员等删除均为归档，并正确执行未完成业务阻断。
11. 邀请二维码实时生成且不持久化。
12. 后端测试、权限路由测试、契约检查、前端类型检查和生产构建全部通过。