heqiapp/platforms
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化平台总后台与核心API

Browse Source
This commit is contained in:
yanweidong
2026-07-26 18:06:14 +08:00
parent 44122809b1
commit 4382641e19
38 changed files with 1837 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/01-项目总览与边界.md
View File

@@ -19,10 +19,10 @@
| 角色 | 主要职责 | 数据范围 |
| --- | --- | --- |
| 普通用户 | 管理智能瓶阀、接收告警、下单、预约、投诉 | 本人及授权家庭成员的设备、地址、订单 |
| 配送员 | 接收配送单、导航、配送取证、提现 | 分配给自己的订单与收益 |
| 安装维修员 | 安装、维修、环境验收、取证 | 分配给自己的工单与设备安装信息 |
| 安检员 | 上门安检、判定等级、复检 | 分配区域/工单内的用户与设备 |
| 普通用户 | 管理智能瓶阀、接收告警、下单、预约、投诉、押金/发票与紧急联系人 | 本人及授权家庭成员的设备、地址、订单 |
| 配送员 | 接收配送单、导航、轨迹上报、随瓶安检、交接取证、空瓶回收、提现 | 分配给自己的订单与收益 |
| 安装维修员 | 安装、维修、环境验收、设备激活、取证 | 分配给自己的工单与设备安装信息 |
| 安检员 | 上门安检、判定等级、整改复检 | 分配区域/工单内的用户与设备 |
| 可燃气体站管理员 | 管理本站商品、优惠券、订单核销、对账提现 | 所属可燃气体站及其服务范围 |
| 平台管理员 | 全局配置、用户/服务人员/气站、运营、资金审核 | 全平台，按后台权限进一步拆分 |
| 扩展：客服 | 工单受理、消息答复、回访 | 被分配的客户与工单，不能改资金和安全判定 |
@@ -60,12 +60,16 @@
| 整改 | 对不合格项采取维修、更换、通风、复检等措施并形成证据 |
| 服务订单 | 商品订单拆分出的配送、安装、维修、安检等履约任务 |
| 气站 | 销售、服务和结算的经营主体，可管理其商品与服务区域 |
| 用户服务关系 | 用户与气站、配送点之间可追溯的服务归属关系；不等同于用户全局账户归属 |
| 邀请注册二维码 | 仅承载可撤销、可过期的签名邀请令牌或短链接，用于注册归因和服务关系建立 |
| 配送轨迹 | 配送任务履约期间的状态节点与定位点记录；仅在履约目的和授权范围内使用 |
## 5. 范围清单
### 5.1 设备与安全
- 设备扫码绑定、列表、详情、远程开/关、控制结果确认。
- 设备分组、家庭成员查看/控制授权、紧急联系人及高风险告警后的通知。
- 上报并展示智能瓶阀状态、电量、电池温度、环境压力和可扩展传感器指标。
- 发生达到规则阈值的安全问题时，自动关闭智能瓶阀（由设备侧/云侧双重保障），创建安全事件并通知用户和平台。
- 安检申请、平台派单、上门检查、不合格分级、整改、复检、抽查与超时升级。
@@ -73,8 +77,9 @@
### 5.2 商城与履约
- 商品分类、商品详情、购物车、收藏、优惠券、收货/安装地址、下单与订单状态。
- 微信、支付宝、余额支付；电子合同第三方签署；配送/安装预约。
- 自动或规则化派单、导航、到达/完成取证、售后、投诉建议。
- 微信、支付宝、余额支付；电子合同第三方签署；配送/安装预约；气瓶押金、退瓶退押金和电子发票。
- 自动或规则化派单、导航、到达/完成取证、配送轨迹、随瓶安检、空瓶回收、售后、投诉建议。
- 气站/配送点邀请二维码扫码注册、地址与服务范围校验、服务关系建立和来源归因。
### 5.3 平台运营
@@ -90,6 +95,9 @@
4. 一个订单可以包含多件商品，但配送、安装、维修可拆为多个服务任务；订单主状态由所有必需任务综合计算。
5. 服务人员只能处理被分配且处于工作时间/服务区域内的任务；异常改派须说明原因并保留记录。
6. 用户注销前应校验未完成订单、未关闭安全事件、余额和数据保留义务；满足条件后执行去标识化而非直接删除审计记录。
7. 服务人员自主注册或由组织创建后均须经过角色、资质、培训、上班状态及授权设备校验；任一前置条件不满足时不得开始任务。
8. 邀请注册二维码必须由服务端校验状态、范围、有效期、次数、地址和用户登录状态；不得重复创建用户账户或覆盖既有服务关系。
9. 配送定位仅在履约期间按最小必要原则采集和展示；用户仅查看本人订单的简化轨迹，精确轨迹回放、导出和跨组织访问须审批审计。
## 7. 待确认事项

26
docs/02-核心业务流程.md
View File

@@ -66,14 +66,36 @@ SLA 从事件创建还是用户确认开始计时须由业务方确认；系统
6. 服务人员接单、导航、到达并完成取证。安装订单还须提交环境验收。
7. 所有必需任务完成并通过必要审核，订单转“已完成”；用户可在售后期内发起售后。
## 4. 安装环境不合格
### 3.1 配送、随瓶安检与空瓶回收
1. 配送员仅在资质、每日培训、上班状态、服务区域、车辆与库存能力均通过校验后接单。
2. 到达后，配送员扫描或通过蓝牙读取气瓶/智能瓶阀设备编码，校验规格、所属、状态和是否已被其他任务占用。
3. 按任务规则完成随瓶安检、分类照片/视频、地理围栏、用户签名或签收码；不合格时创建安全事件或整改任务，禁止直接完成配送。
4. 配送员仅能确认已核验的线上支付结果或平台授权的线下收款，金额差异进入对账异常，不能由配送员修改订单金额。
5. 空瓶回收时记录气瓶编码、回收状态、时间、操作者和去向，分别更新气瓶、库存、押金和订单状态；拒收、损坏、逾期或编码不符均进入异常处理。
## 4. 邀请注册与服务关系建立
1. 气站或配送点创建二维码，平台生成带签名、可撤销的邀请码或短链接，并配置归属组织、服务区域、有效期、使用次数与活动来源。
2. 用户在用户端 App 或浏览器扫码后，服务端校验二维码状态、地址服务范围、风控结果和登录状态；失效、越界或停用时明确提示原因。
3. 新用户完成手机号验证、协议同意和服务地址确认后创建全局账户；已有用户登录确认后只建立或变更服务关系，不重复建账号。
4. 系统记录二维码、来源、扫码、注册、地址校验、服务关系与转化结果；重复扫码不得覆盖既有服务关系，变更须展示影响并取得用户确认。
## 5. 服务人员准入与作业闭环
1. 服务人员可在服务端 App 提交配送、安装维修或安检角色申请，也可由气站/配送点创建；申请成功仅生成待审核账户。
2. 平台或授权组织核验实名信息、角色资质、培训、车辆/工具、服务区域和组织归属后授予对应角色能力；安全相关角色须安全主管复核。
3. 每日首次进入工作台前完成角色化安全培训；开始任务前校验上班状态、服务区域、授权设备、资质有效期和任务前置条件。
4. App 弱网时可加密暂存已分配任务、定位和现场材料，恢复后按原始采集时间补传；服务端校验幂等键、时间顺序、完整性与冲突，不得篡改采集时间。
## 6. 安装环境不合格
- 安装维修员按检查表填写不合格项、风险等级、图像/视频证据和处理建议。
- 系统创建或关联安全事件，禁止将设备标记为“已安装可用”；对需要关阀的场景执行安全策略。
- 用户和平台收到明确的整改项、时限和预约入口；必要时分派维修/安检复查任务。
- 复查合格后才允许激活设备、解除限制或继续订单完成流转。
## 5. 资金与提现
## 7. 资金与提现
- 支付、充值、退款、佣金、提现均以不可变资金流水记录，余额是流水聚合结果而非唯一事实来源。
- 提现流程：服务人员/气站提交申请 -> 系统校验可提现余额、实名与风控 -> 财务审核 -> 线下打款/三方打款 -> 回填凭证和结果。

17
docs/05-平台总后台需求.md
View File

@@ -9,11 +9,12 @@
| 功能域 | 核心功能 | 数据边界 |
| --- | --- | --- |
| 组织权限 | 管理员、角色、权限、可燃气体站、配送点、生产单位、服务区域、数据范围 | 全局；支持按组织、区域、对象归属授权 |
| 用户与服务人员 | 用户 360、服务人员资质、角色、冻结、分账、跨组织调配 | 查看敏感数据受字段权限和审计控制 |
| 用户与服务人员 | 用户 360、服务关系、服务人员准入/培训/打卡、资质、角色、冻结、分账、跨组织调配 | 查看敏感数据受字段权限和审计控制 |
| 设备与安全 | 设备模型、绑定、遥测、命令、规则、事件、SLA、安检/整改、强制升级 | 全局安全规则和高风险动作仅授权角色可操作 |
| 商品交易 | 全局商品主数据、价格策略、订单、售后、支付、合同、优惠规则 | 站点商品与库存由站点系统主责，平台可治理与审计 |
| 资金结算 | 充值、支付、退款、分账、结算、提现、对账、打款凭证 | 财务角色分离，关键审批支持双人复核 |
| 内容与客服 | 轮播、公告、协议、宣教内容、消息模板、客服配置、投诉工单 | 发布有审核、版本和撤回能力 |
| 邀请与轨迹治理 | 气站/配送点邀请二维码、注册归因、配送轨迹、定位访问与导出审批 | 二维码、服务关系和定位均按最小权限、可撤销与审计治理 |
| 全局运营 | 用户/订单/设备/事件/履约指标，地图和异常看板 | 支持跨组织下钻但遵循权限和脱敏 |
| 审计合规 | 操作审计、导出审计、敏感访问、数据留存、注销与合规工单 | 不可由普通管理员删除或篡改 |
@@ -61,9 +62,9 @@
#### 服务人员关键操作
- 平台可批量导入、审核、分配组织/区域、授予角色、设置分账比例、调整可接单状态和发起跨组织调配；气站可在本站授权范围内创建、维护和提交服务人员审核。
- 平台可批量导入、审核、分配组织/区域、授予角色、设置分账比例、调整可接单状态和发起跨组织调配；气站可在本站授权范围内创建、维护和提交服务人员审核。服务人员通过 App 自主注册时，后台应展示申请来源、角色、材料、审核意见和生效记录。
- 平台不得直接替服务人员完成工单；改派、取消、强制下线和资质豁免必须记录原因、审批依据和受影响任务。
- 安装维修与安检等安全相关角色的资质、培训和违规记录应成为派单前置校验；配送任务还应校验配送点、班次、车辆/库存能力。
- 安装维修与安检等安全相关角色的资质、培训、每日培训、上/下班和违规记录应成为派单前置校验；配送任务还应校验配送点、班次、车辆/库存能力。后台可查看授权设备、打卡异常、培训未完成和离线补传异常，但不得替代服务人员提交现场事实。
### 3.4 用户统一管理
@@ -99,11 +100,21 @@ flowchart TB
- 跨组织协作通过任务、调拨、结算和事件记录实现，不允许任一系统直接修改另一主体的核心主档或资金流水。
- 组织合并、区域调整、服务人员调动、用户设备转移均需要影响评估，至少校验未完成任务、在途库存、安全事件、余额和结算状态。
### 3.6 邀请注册二维码与配送轨迹治理
| 管理项 | 平台要求 |
| --- | --- |
| 邀请二维码 | 查看气站/配送点二维码的归属、类型、服务区域、适用活动、有效期、次数、状态、扫码/注册/首单转化及异常拦截；平台可按权限停用、冻结或重新生成，不得直接暴露令牌明文、用户隐私或接口密钥 |
| 服务关系 | 查看用户与气站/配送点的建立来源、二维码归因、生效时间、历史变更和确认记录；重复扫码不重复建档，变更关系须保留原关系和影响评估 |
| 轨迹运营 | 按订单、组织、配送员、区域、时间和异常类型查看轨迹质量、时效和任务事件；用户端只读简化轨迹，完整轨迹遵循组织边界 |
| 精确轨迹访问 | 地图回放、精确坐标和轨迹导出须申请用途、审批期限、字段范围和水印；记录访问人、对象、用途、时间、导出结果及二次传播责任 |
## 4. 安全运营中心
- 实时显示设备离线、低电量、压力/温度异常、人工检查不合格等事件，按等级、超时、是否已关阀和责任方排序。
- 管理告警规则版本、阈值、持续时间、适用设备型号、自动关阀、消息模板、静默期和灰度范围。
- 触发后生成事件、通知、责任任务和升级链路。对强制开阀、降级、关闭高风险事件要求二次确认和完整审计。
- 用户端首次登录或安全宣教更新后的强制阅读内容、展示范围、版本、频率和阅读确认由平台配置；紧急告警不得被宣教弹窗阻断。
## 5. 平台与其他 Web 系统的权责

7
docs/06-气站管理系统需求.md
View File

@@ -10,7 +10,7 @@
| --- | --- | --- |
| 站点与人员 | 站点资料、营业时间、服务区、站内账号、服务人员归属与排班 | 账号与数据仅限本组织；跨站调配需平台审批 |
| 配送点管理 | 创建、编辑、启停本站配送点；负责人、覆盖区域、服务能力、配送仓和配送人员 | 配送点自动归属本站；编码全局唯一；跨站迁移、删除和超范围区域须平台审批 |
| 服务人员管理 | 创建和管理配送员、安装维修员、安检员；角色、资质、排班、服务范围、接单状态与绩效 | 仅限本站人员；安全相关角色须平台/安全主管审核后可接单；不能授予超出站点授权的角色 |
| 服务人员管理 | 创建、导入或审核 App 自主注册的配送员、安装维修员、安检员；角色、资质、培训、打卡、服务范围、接单状态与绩效 | 仅限本站人员；安全相关角色须平台/安全主管审核后可接单；不能授予超出站点授权的角色 |
| 商品与库存 | 本站可售商品/SKU、价格、库存、批次、上下架、库存预警、盘点 | 全局商品主数据由平台治理；已履约商品不可物理删除 |
| 营销 | 满减券、折扣券、发放、核销、适用范围与统计 | 受平台营销政策和预算控制，券核销可追溯 |
| 订单与服务 | 订单、安装/维修/安检任务、预约、异常、售后、核销 | 只处理本站订单；高风险安全事件自动同步平台总后台 |
@@ -37,10 +37,10 @@
| 功能 | 需求与规则 |
| --- | --- |
| 创建与导入 | 录入实名资料、联系方式、紧急联系人、所属配送点/站点、服务区域和入职信息；手机号重复时提示关联现有人员或提交平台合并申请 |
| 创建、导入与自主申请 | 录入实名资料、联系方式、紧急联系人、所属配送点/站点、服务区域和入职信息；接收 App 自主注册申请并审核角色、材料与来源；手机号重复时提示关联现有人员或提交平台合并申请 |
| 角色配置 | 可授予配送员、安装维修员、安检员角色；分别维护证书、培训、技能、保险、设备/车辆能力和到期时间 |
| 审核与生效 | 配送角色可按平台规则自动/人工审核；安装维修、安检等安全相关角色须平台或安全主管审核通过后才能接收任务 |
| 排班与调度 | 设置上班状态、班次、最大负载、预约时段和服务区域；可对本站任务派单、改派和暂停接单，不可跨站直接派单 |
| 作业前置与调度 | 查看每日培训、上/下班、授权设备、定位权限和离线补传异常；设置班次、最大负载、预约时段和服务区域；任一作业前置不满足时不可派单或开始任务 |
| 绩效与处置 | 查看任务、时效、评分、投诉、违规、收益和分账；可发起冻结、离职、调动申请，最终生效遵循平台审批规则 |
## 5. 用户管理
@@ -74,6 +74,7 @@
- 站点创建或确认需配送的任务，向配送点发布履约需求；配送点确认人员和配送计划后回传状态。
- 商品从站点仓转至配送点仓时，创建调拨单、出入库和签收记录；在途库存独立核算。
- 配送异常、货损、拒收、退货回流均必须同步订单、库存和资金待处理状态。
- 站点可查看本站任务的配送轨迹质量、随瓶安检、气瓶扫码/蓝牙识别、收款确认、空瓶回收与异常对账状态；现场原始证据只能由服务端 App 提交，后台不得补录为已完成。
## 7. 数据边界、审核与审计

7
docs/07-配送点管理系统需求.md
View File

@@ -9,7 +9,7 @@
| 模块 | 功能 |
| --- | --- |
| 配送点基础资料 | 配送点地址、覆盖区域、营业时段、车辆、容量、联系人和状态 |
| 服务人员管理 | 创建和管理配送员、安装维修员、安检员的本站/本点归属、资质、班次、可接单状态、负载、评分和异常率；安全相关角色须经平台审核后生效 |
| 服务人员管理 | 创建、导入或审核 App 自主注册的配送员、安装维修员、安检员的本站/本点归属、资质、培训、打卡、班次、可接单状态、负载、评分和异常率；安全相关角色须经平台审核后生效 |
| 用户管理 | 创建线下用户待激活档案、邀请注册、管理本点服务用户、地址、配送偏好、订单、预约、回访与投诉协同 |
| 邀请注册二维码 | 创建、下载、分享、停用和分析本点邀请注册二维码；扫码注册后自动建立本点用户服务关系 |
| 订单调度 | 接收站点/平台配送需求，自动分单、人工改派、预约、路线、配送轨迹、时效预警 |
@@ -23,10 +23,10 @@
| 功能 | 需求与规则 |
| --- | --- |
| 创建与关联 | 录入姓名、手机号、实名资料、紧急联系人、服务区域、所属气站/配送点和入职信息；已有平台人员可申请关联到本点，不重复创建账号 |
| 创建、关联与自主申请 | 录入姓名、手机号、实名资料、紧急联系人、服务区域、所属气站/配送点和入职信息；审核 App 自主注册申请的角色、材料与来源；已有平台人员可申请关联到本点，不重复创建账号 |
| 角色与能力 | 配置配送、安装维修、安检角色，以及车辆、工具、技能、证书、培训、保险和有效期；角色能力独立生效 |
| 审核与启用 | 配送角色按平台规则审核；安装维修和安检等安全相关角色必须经平台或安全主管审核后才可接收对应任务 |
| 班次与调度 | 设置班次、上班状态、最大负载、预约窗口、服务区域和可服务商品/设备型号；可对本点任务派单、改派、暂停接单 |
| 作业前置与调度 | 查看每日培训、上/下班、授权设备、定位权限和离线补传异常；设置班次、最大负载、预约窗口、服务区域和可服务商品/设备型号；任一作业前置不满足时不可派单或开始任务 |
| 绩效与处置 | 查看任务时效、签收/完工质量、评分、投诉、违规、收益和分账；可发起离职、冻结、跨点支援或调动申请，最终生效按气站/平台审批规则执行 |
## 4. 用户管理
@@ -61,6 +61,7 @@
- 高优先级安全相关配送任务可插单，但应记录影响订单、调度人或规则版本。
- 配送员未在时限内接单、长期无定位/无进度、异常率超过阈值时触发回收、改派或人工干预。
- 签收成功才扣减配送点实际库存；发生拒收或货损时先冻结对应库存与结算，待审核后再回流或报损。
- 配送完成前，调度审核视图必须显示到达校验、气瓶扫码/蓝牙识别、随瓶安检、照片/视频、签收、收款确认和空瓶回收的完成或异常状态；后台只能审核异常，不能补造现场证据。
### 配送轨迹管理

8
docs/08-生产管理系统需求.md
View File

@@ -29,6 +29,14 @@ flowchart LR
G --> H[调拨至站点/配送点或销售库存]
```
### 3.1 出厂设备主档同步契约
生产系统向平台设备域同步的最小信息必须包括：设备序列号、二维码状态、设备型号、硬件/固件版本、设备证书状态、生产批次、出厂质检结论、激活资格和同步时间。平台仅允许“质检合格且具备激活资格”的设备进入销售、安装或用户绑定流程。
- 设备二维码在出厂、作废、换码、召回时均须同步状态；用户端绑定、服务端 App 安装激活和后台设备查询必须校验该状态。
- 生产系统不写入用户、订单、服务关系或现场履约事实；发现设备质量问题时通过设备身份、批次和召回任务与平台安全/履约域关联。
- 同步失败、重复同步、型号/批次不一致或证书失效时进入可追踪异常队列，不得以“已同步”掩盖失败结果。
## 4. 扩展能力
- MES/ERP 集成、供应商质量管理、电子作业指导书、自动测试台、碳足迹、预测性质量分析和召回演练。

4
docs/09-API中心管理系统需求.md
View File

@@ -8,7 +8,7 @@ API 中心管理系统用于治理平台向可燃气体站、生产合作方、
| 模块 | 功能 | 规则 |
| --- | --- | --- |
| API 目录 | 设备查询、遥测订阅、订单同步、库存调拨、售后、内容等 API 产品 | 按业务域、版本、环境、受众、数据等级和 SLA 管理 |
| API 目录 | 设备查询、遥测订阅、订单同步、库存调拨、售后、邀请注册归因、配送轨迹摘要、内容等 API 产品 | 按业务域、版本、环境、受众、数据等级和 SLA 管理 |
| 生命周期 | 设计、评审、发布、灰度、废弃、下线 | OpenAPI/AsyncAPI 契约版本化；破坏性变更需弃用期和通知 |
| 应用接入 | 合作方组织、应用、回调地址、用途、负责人、资质审核 | 一应用一身份；生产环境需审核后开通 |
| 认证授权 | OAuth 2.1/OIDC、客户端凭证、mTLS、签名、密钥轮换和吊销 | 最小权限、短期令牌、密钥不可明文回显 |
@@ -21,6 +21,8 @@ API 中心管理系统用于治理平台向可燃气体站、生产合作方、
- 默认不开放远程开阀、强制解除安全限制、提现审核等高危能力；确需开放须独立 API 产品、最小范围、双重鉴权、审批和实时审计。
- 对外查询仅返回调用方业务所需字段，用户手机号、地址、定位、视频、资金信息按数据分类和授权协议最小化提供。
- Webhook 必须校验回调地址、签名、超时、重试和幂等；失败事件进入可追踪的死信队列。
- 邀请注册 API 仅允许校验短链接、查询脱敏转化统计或经授权建立服务关系；不得返回邀请码明文、用户账户凭证、完整地址或组织管理员信息。
- 配送轨迹 API 默认只提供订单履约状态、预计到达和用户可见的简化轨迹。精确坐标、轨迹回放、服务人员非履约位置、签名和现场视频属于受限数据，须独立产品、审批、短期授权和用途审计。
## 4. 开发者体验与扩展

13
docs/10-技术实现规划.md
View File

@@ -26,6 +26,7 @@
| 缓存与任务 | Redis | 限流、会话、幂等、短期状态、延迟任务；关键事实仍落 PostgreSQL |
| 消息/事件 | Redis Streams + Consumer Group | 遥测流、告警、订单状态、通知、对账异步化；使用消费组、重试、死信与幂等消费者保障可恢复处理 |
| 文件与证据 | S3 兼容对象存储（MinIO/云 OSS） | 商品图、安装/安检证据、签收图片、视频和合同；采用短期签名 URL 与生命周期策略 |
| 移动端离线与定位 | Flutter 安全存储 + 本地加密数据库 + 地图/定位 SDK | 服务端 App 的已分配任务、现场材料和配送轨迹可弱网暂存；保留原始采集时间并按幂等键补传 |
| Web 入口与部署 | Caddy + Shell 脚本 | TLS 终止、反向代理、静态文件、压缩、健康检查与受控发布；配置和脚本纳入版本控制 |
| 可观测性 | OpenTelemetry + Prometheus + Grafana + Loki | 指标、链路、日志、告警与审计关联 |
@@ -66,6 +67,12 @@ flowchart LR
业务项目应通过共享包、模板或上游同步机制复用标准库，禁止将标准库目录复制到每个子项目后自行漂移。标准库升级需要记录版本、影响范围、兼容策略和回滚方式。
### 4.1 移动端定位、离线与取证基线
- 服务端 App 仅在配送或现场任务执行期间申请并采集定位；必须显式展示定位授权、后台运行、最后更新时间和权限失效状态。用户端仅消费本人订单所需的简化轨迹。
- 已分配任务、轨迹点、照片/视频元数据、签名、扫描结果和收款确认可在弱网下加密暂存。补传必须携带原始采集时间、服务端接收时间、任务 `identity`、操作者 `identity`、来源、完整性标记与幂等键，禁止以补传时间覆盖采集时间。
- 后端负责乱序校正、重复去除、异常速度/精度标记、证据哈希与状态机校验；前端离线缓存、按钮禁用或页面显示不能替代服务端权限、金额、地理围栏和完成条件校验。
## 5. 研发目录规划（建议）
```text
@@ -128,13 +135,13 @@ platforms/
| 模块 | 表前缀 | 典型表 |
| --- | --- | --- |
| 身份与权限 | `idn_` | `idn_account`、`idn_role`、`idn_permission` |
| 组织与服务关系 | `org_` | `org_gas_station`、`org_delivery_point`、`org_service_person`、`org_user_service_relation` |
| 组织与服务关系 | `org_` | `org_gas_station`、`org_delivery_point`、`org_service_person`、`org_user_service_relation`、`org_invitation_qr_code` |
| 设备与物联网 | `dev_` | `dev_device`、`dev_telemetry`、`dev_command` |
| 安全与安检 | `saf_` | `saf_event`、`saf_rule`、`saf_inspection`、`saf_rectification` |
| 商品与营销 | `cat_` | `cat_product`、`cat_sku`、`cat_coupon`、`cat_cart` |
| 订单与履约 | `ord_` | `ord_order`、`ord_payment`、`ord_service_task`、`ord_delivery_track` |
| 调度与配送 | `dsp_` | `dsp_assignment`、`dsp_shift`、`dsp_delivery_track_point` |
| 钱包与结算 | `wal_` | `wal_ledger`、`wal_settlement`、`wal_withdrawal` |
| 钱包与结算 | `wal_` | `wal_wallet_ledger`、`wal_settlement`、`wal_withdrawal` |
| 内容与通知 | `cnt_`、`ntf_` | `cnt_article`、`cnt_banner`、`ntf_message`、`ntf_template` |
| 生产与质量 | `mfg_` | `mfg_work_order`、`mfg_batch`、`mfg_quality_check` |
| 开放接口 | `api_` | `api_product`、`api_client`、`api_subscription` |
@@ -160,6 +167,8 @@ platforms/
- 所有实体一律使用单数：一个 `org_gas_station` 既可表示单个站点模型，也可作为列表返回项的模型名称。列表、批量和分页仅在 API 动词或响应字段表达，例如 `GET /org/gas-station/list`、`items: []`；不改变实体名。
- 关联表使用参与实体的单数词根和明确关系词，例如 `org_user_service_relation`、`idn_account_role_relation`，不得使用 `users_roles`、`user_roles` 等复数或含糊名称。
- `ord_delivery_track` 是配送任务的状态轨迹主表，`dsp_delivery_track_point` 是其定位点明细表；二者均为独立实体，不得再创建同义的 `delivery_tracks`、`track_points` 等表或模型。定位点通过 `delivery_track_identity` 关联主表。
- 钱包事实流水的唯一实体名为 `wal_wallet_ledger`；用户和服务人员的资金归属通过关联对象字段区分，禁止另建同义的 `wal_ledger`、`wallet_ledgers` 或 `service_wallet_ledger`。
- 文件目录可以按业务模块组织，但目录名不参与实体命名；模型、迁移、契约、测试文件都必须能从其文件名唯一定位到同名的数据库表和模型。
- 新增实体前应先登记规范名称；重命名须同时修改表、模型、文件、契约、迁移和中文注释，并进行全仓引用检查，禁止仅改其中一层。

14
docs/11-数据接口与安全.md
View File

@@ -11,12 +11,12 @@
| 数据域 | 核心实体 | 关键约束 |
| --- | --- | --- |
| 身份组织 | `idn_account`、`idn_role`、`idn_permission`、`org_gas_station`、`org_service_area`、`idn_emergency_contact` | 手机号/账号唯一；角色和数据范围均生效；紧急联系人授权范围单独记录 |
| 身份组织 | `idn_account`、`idn_role`、`idn_permission`、`org_gas_station`、`org_service_area`、`org_service_person`、`org_user_service_relation`、`org_invitation_qr_code`、`idn_emergency_contact` | 手机号/账号唯一；角色和数据范围均生效；紧急联系人授权范围、二维码归因和服务关系历史单独记录 |
| 设备 | `dev_device`、`dev_device_binding`、`dev_device_group`、`dev_cylinder`、`dev_telemetry`、`dev_command` | 设备序列号唯一；绑定有有效期与历史；命令含幂等键与回执；气瓶信息保留来源和有效期 |
| 安全 | `saf_rule`、`saf_event`、`saf_repair_request`、`saf_inspection`、`saf_rectification` | 事件编号唯一；等级、状态、SLA、证据、操作者完整可追溯；报修图片/定位需有采集时间 |
| 商品交易 | `cat_category`、`cat_product`、`cat_sku`、`cat_cart`、`cat_coupon`、`ord_order`、`ord_payment`、`ord_invoice` | 金额使用最小货币单位整数；库存扣减有事务/预占规则；预约时段、库存快照和开票状态可追溯 |
| 履约 | `ord_service_task`、`dsp_assignment`、`ord_delivery_track`、`dsp_delivery_track_point` | 任务状态转换受限；定位、轨迹和证据均有采集时间 |
| 资金与押金 | `wal_wallet_ledger`、`wal_deposit`、`wal_deposit_refund`、`wal_settlement`、`wal_withdrawal`、`wal_reconciliation` | 流水不可更新删除；金额方向、关联对象和余额快照可校验；退押金保留验收、扣减和退款去向 |
| 资金与押金 | `wal_wallet_ledger`、`wal_deposit`、`wal_deposit_refund`、`wal_settlement`、`wal_withdrawal`、`wal_reconciliation` | `wal_wallet_ledger` 为唯一钱包事实流水；金额方向、关联对象和余额快照可校验；退押金保留验收、扣减和退款去向 |
| 用气统计 | `dev_usage_stat`、`dev_usage_report` | 明确统计周期、单位、来源、计算版本和最后更新时间；报表导出留痕 |
| 内容审计 | `cnt_article`、`cnt_banner`、`cnt_notice`、`aud_operation_log` | 发布有版本；审计日志追加写入且设置留存期限 |
@@ -64,7 +64,13 @@
- 用户端只返回本人订单所需的简化轨迹、最近有效位置、预计到达和事件节点；配送点/气站/平台按组织和职责获取更详细数据。精确轨迹回放及导出应审批并记录用途。
- 轨迹属于敏感定位数据，传输与存储加密、最小化留存、访问审计；订单完结后按留存策略降精度展示或限制访问。严禁将配送员非履约时间的位置用于无关用途。
## 3.3 服务端 App 工单、取证与结算要求
### 3.3 移动端离线、定位与现场证据要求
- 服务端 App 只有在任务执行期间可采集后台定位；定位权限撤销、后台运行受限、精度不足或长时间无位置时必须提示服务人员并向任务记录写入状态，不得伪造实时轨迹。
- 离线队列中的任务材料、定位点、照片/视频元数据、签名、扫描结果和收款确认必须本地加密。补传请求携带原始采集时间、服务端接收时间、`identity`、幂等键、来源和完整性标记；服务端按任务状态和证据哈希进行去重、乱序校正和冲突处置。
- 定位、签名和现场证据的采集开关、保留时长、可见角色、精度降级与导出权限由平台配置；客户端展示或本地删除不能绕过服务端留存、审计和安全事件证据义务。
### 3.4 服务端 App 工单、取证与结算要求
| 场景 | 核心实体 | 必要数据与规则 |
| --- | --- | --- |
@@ -73,7 +79,7 @@
| 维修工单 | `ord_service_task`、`ord_repair_evidence`、`ord_repair_material`、`ord_repair_receipt` | 维修前中后证据、材料、价格快照、应收/实收、签字和支付差异可追溯；不能由服务人员修改订单定价 |
| 安装工单 | `ord_installation_condition`、`ord_installation_material`、`ord_installation_step`、`ord_installation_test`、`ord_installation_receipt` | 使用条件、备料、安装步骤、测试、前期安检、设备激活和收款按顺序记录；不合格或测试失败不能完成/激活 |
| 配送与回收 | `dsp_delivery_cylinder_scan`、`dsp_delivery_evidence`、`dsp_delivery_payment_confirmation`、`dsp_cylinder_return` | 气瓶/设备编码、蓝牙/扫码来源、随瓶安检照片视频、收款确认、空瓶回收、押金和库存状态均与配送任务关联 |
| 服务收入 | `wal_service_income`、`wal_service_withdrawal`、`wal_bank_card` | 收入由已完成且符合结算规则的任务生成；提现以可提现余额、银行卡验证、审核和打款回执为准 |
| 服务收入 | `wal_service_income`、`wal_withdrawal`、`wal_bank_card` | 收入由已完成且符合结算规则的任务生成；`wal_withdrawal` 是所有钱包提现的唯一实体，以可提现余额、银行卡验证、审核和打款回执为准 |
- 现场照片、视频、电子签字、蓝牙扫描、定位和收款确认属于取证数据。必须记录原始采集时间、服务端接收时间、任务、操作者、来源、完整性标记和对象存储哈希；客户端离线补传不得覆盖原始采集时间。
- 强制取证项由任务类型、设备型号、风险等级和组织规则确定。服务端在工单完成前校验必填检查项、照片/视频数量、签字、地理围栏、材料和支付状态，前端按钮禁用不能替代服务端校验。

7
docs/12-验收与迭代规划.md
View File

@@ -6,7 +6,7 @@
| 版本 | 必须交付 | 可后置 |
| --- | --- | --- |
| M0 基础底座 | 账号/RBAC、气站/区域、设备接入、审计、通知、基础后台 | 多站点结算、复杂 BI |
| M0 基础底座 | 账号/RBAC、气站/区域、服务关系、设备接入、审计、通知、基础后台 | 多站点结算、复杂 BI |
| M1 安全闭环 | 绑定、状态/遥测、开关控制回执、告警分级、自动关阀、安检/整改/复检、用户/平台通知 | 设备共享、固件 OTA、视频会诊 |
| M2 交易履约 | 商品、购物车、订单、支付、地址、配送/安装任务、配送轨迹、核销、售后基础 | 发票、订阅、复杂促销 |
| M3 资金运营 | 钱包充值、佣金、提现审核、对账、数据看板、内容运营 | 自动打款、预测模型、合作方开放平台 |
@@ -34,6 +34,11 @@
| AC-17 | 安装/维修工单闭环 | 新装任务按使用条件、备料、安装、测试、安检、完成、收款顺序流转；维修任务保存前中后证据、材料和签字；不合格、测试失败或收费差异均不能直接完成 |
| AC-18 | 配送、随瓶安检与回收 | 配送员完成到达校验、气瓶蓝牙/扫码、随瓶安检照片/视频、结论和收款确认后才能完成配送；空瓶回收同步更新气瓶、押金和库存状态，异常可追溯 |
| AC-19 | 服务人员资质与收入 | 角色注册后处于待审核；证照、培训或上班状态不满足时无法接单；完成任务后收入按结算规则进入可提现余额，提现和银行卡信息受审核与审计保护 |
| AC-20 | 邀请注册与服务关系 | 气站/配送点二维码可按范围、有效期和次数生效或停用；扫码地址越界、二维码失效及风控失败均被拦截；已有用户不重复建档，服务关系变更须确认且归因可追溯 |
| AC-21 | 服务人员作业前置与离线补传 | 自主注册仅生成待审核账户；资质、每日培训、上班、区域和授权设备任一不满足时不能开始任务；弱网补传保留原始采集时间并去重，不能伪造轨迹或覆盖现场事实 |
| AC-22 | 设备共享与紧急联系人 | 设备所有者可独立授予或撤销成员查看/控制权限；高风险告警自动关阀后仅通知已授权紧急联系人，且审计完整 |
| AC-23 | 二维码与轨迹隐私 | 二维码不包含用户隐私、账号凭证或接口密钥；用户只看本人订单简化轨迹，精确轨迹回放/导出须经审批、水印和审计，非履约位置不可访问 |
| AC-24 | 钱包实体命名一致性 | 数据库迁移、表、Go/Flutter/Vue 模型和契约均使用 `wal_wallet_ledger`；不得出现 `wal_ledger`、复数表名或同义钱包流水实体 |
## 3. 非功能验收

2
docs/README.md
View File

@@ -23,6 +23,8 @@
- “应/必须”表示上线验收项；“建议”表示增强项；“可选”表示扩展能力。
- 需求变更应先更新本目录中的对应文档，并记录版本、变更人、变更原因和影响范围。
- 两类 App 的最新需求以 [03-用户端 App 需求](03-用户端App需求.md) 与 [04-服务端 App 需求](04-服务端App需求.md) 为端侧基线。涉及邀请注册、服务关系、配送轨迹、现场取证、人员准入或离线定位的变更，必须同步审查总览、流程、后台、技术、接口与验收文档。
- 同一数据实体的表名、模型名、文件名、迁移和接口 Schema 必须遵循 [技术实现规划](10-技术实现规划.md) 的唯一命名；命名变更须在变更记录中说明旧名、目标名和兼容/迁移方案。
- 涉及阀门自动关闭、告警分级、支付、合同、提现、隐私信息的变更，须由产品、技术、安全/法务共同评审。
- 原附件只给出功能脑图，未明确的业务口径已在文档中标记为“待确认”或作为可配置规则提出，不应直接视为既定政策。