platforms/docs/07-配送点管理系统需求.md

配送点管理系统需求

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 全局配置

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

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 订单金额调整

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

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

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

4.8 财务管理

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

4.9 邀请注册

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

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. 后端测试、权限路由测试、契约检查、前端类型检查和生产构建全部通过。