488 lines
18 KiB
Markdown
488 lines
18 KiB
Markdown
# 加氢站管理 · 站点信息 — 产品需求说明（PRD）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 文档版本 | v2.0 |
|
||
| 产品模块 | 加氢站管理 → 站点信息 |
|
||
| 文档类型 | 产品需求说明 |
|
||
| 适用读者 | 研发、测试、产品、项目 |
|
||
| 关联模块 | 台账数据 → 车辆氢费明细 |
|
||
| 原型文件 | `web端/加氢站管理/站点信息.jsx` |
|
||
|
||
---
|
||
|
||
## 一、为什么做这件事
|
||
|
||
### 1.1 业务背景
|
||
|
||
加氢站是氢费成本结算的关键节点。运营侧需要维护站点主数据（签约、地址坐标、营业、成本价、预付余额），并在财务周期内按站点与加氢站完成对账、收票与付款闭环。
|
||
|
||
### 1.2 本期目标
|
||
|
||
建设 Web 端「站点信息」页面，支撑：
|
||
|
||
- 站点台账的查询、新建、编辑、查看、删除与批量导入
|
||
- 地图定位、营业状态、多规则成本价格、余额提醒等运营配置
|
||
- 加氢量 / 预付余额下钻分析与充值单发起
|
||
- **按站点生成氢费对账单 → 填写收票信息 → 提交结算**，并与「车辆氢费明细」联动回写
|
||
|
||
### 1.3 用户角色
|
||
|
||
| 角色 | 典型诉求 |
|
||
|------|----------|
|
||
| **加氢站运营** | 维护站点资料、营业与价格；查看加氢量与余额；设置余额提醒 |
|
||
| **财务/结算** | 按周期生成对账单、登记收票、发起充值、完成站点付款闭环 |
|
||
| **管理员** | 批量导入站点、全站余额提醒、删除无效站点、绑定系统账号 |
|
||
|
||
---
|
||
|
||
## 二、页面整体结构
|
||
|
||
用户进入「加氢站管理 → 站点信息」后，页面自上而下为：
|
||
|
||
1. **筛选区** — 名称、是否签约、地区、营业状态
|
||
2. **KPI 分类** — 全部 / 预付余额预警 / 已欠费 / 无加氢；签约站点快捷筛选
|
||
3. **工具栏** — 全站余额提醒设置、批量导入、发起充值单、新建站点
|
||
4. **站点列表** — 主数据 + 运营指标 + 操作列
|
||
5. **子页面 / 弹窗** — 新建/编辑整页、查看、营业状态、价格配置、余额提醒、对账单、对账记录、下钻分析等
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph 列表页
|
||
A[筛选 / KPI] --> B[站点列表]
|
||
B --> C[查看站点]
|
||
B --> D[编辑 / 删除]
|
||
B --> E[更多菜单]
|
||
B --> F[加氢量下钻]
|
||
B --> G[预付余额下钻]
|
||
end
|
||
E --> H[营业状态]
|
||
E --> I[价格配置]
|
||
E --> J[余额提醒设置]
|
||
E --> K[生成对账单]
|
||
E --> L[查看对账记录]
|
||
B --> M[工具栏-发起充值单]
|
||
B --> N[工具栏-全站余额提醒]
|
||
```
|
||
|
||
页面右上角提供 **「查看需求说明」**、**「查看使用说明书」** 入口。
|
||
|
||
---
|
||
|
||
## 三、列表与 KPI 规则
|
||
|
||
### 3.1 列表字段
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| 加氢站名称 | 含签约标签（签约站点 / 签约站点-未上传合同）；下一行展示完整地址 |
|
||
| 合作时间 | 未签约显示为空 |
|
||
| 营业状态 / 营业时间 | 列表只读；在「更多 → 营业状态」维护 |
|
||
| 当前成本价格 | 元/kg；由价格配置规则与生效时间驱动；多客户规则时展示主规则价格 |
|
||
| 加氢次数 / 加氢量 | 加氢量可点击下钻；列表头支持排序 |
|
||
| 预付余额 | 可点击下钻流水；负值标红并显示「已欠费」 |
|
||
| 联系方式 | 联系人 + 电话 |
|
||
| 操作 | 查看 + 更多（⋮） |
|
||
|
||
### 3.2 KPI 分类逻辑
|
||
|
||
| 分类 | 规则 |
|
||
|------|------|
|
||
| 全部加氢站 | 台账内全部站点 |
|
||
| 预付余额预警站点 | 已设置提醒阈值，且预付余额 ≥ 0 且低于阈值（不含已欠费） |
|
||
| 已欠费站点 | 预付余额 < 0 |
|
||
| 无加氢站点 | 加氢次数 = 0 |
|
||
|
||
**签约快捷筛选**（与 KPI 并列展示）：
|
||
|
||
| 分类 | 规则 |
|
||
|------|------|
|
||
| 签约站点 | `isSigned = true` |
|
||
| 普通站点 | `isSigned = false` |
|
||
|
||
点击「预付余额预警站点」「已欠费站点」KPI 卡，打开对应站点列表弹窗，支持 **一键发起充值单**（预填站点与当前余额）。
|
||
|
||
筛选或 KPI 切换后列表回到第 1 页；默认分页 10 条，可选 5 / 10 / 20 / 50。
|
||
|
||
---
|
||
|
||
## 四、站点主数据（新建 / 编辑 / 查看）
|
||
|
||
### 4.1 新建站点
|
||
|
||
**入口**：列表工具栏 → **新建站点**
|
||
|
||
整页表单分三块卡片：
|
||
|
||
#### （1）加氢站基本信息
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| 加氢站名称 | 是 | 不可与已有站点重名 |
|
||
| 省市、通讯地址 | 是 | 只读，由地址解析回填 |
|
||
| 地址解析 | 否 | 粘贴完整地址，失焦后自动解析省/市与详细地址 |
|
||
| 地图定位 | 否 | 见 [4.4 地图定位模块](#44-地图定位模块) |
|
||
| 联系人 | 是 | — |
|
||
| 手机号 / 固定电话 | 至少一项 | 格式校验 |
|
||
| 站点类型 | 否 | 签约站点 / 普通站点；签约须填合作时间与合同附件 |
|
||
|
||
#### （2）系统账号绑定
|
||
|
||
- 选择 **绑定系统账号** 或 **暂不绑定**
|
||
- 绑定支持 **多选**；已被其他站点占用的账号不可选
|
||
- 绑定后所选账号可登录并管理该站点
|
||
|
||
#### （3）供应商相关信息
|
||
|
||
Tab：**关联已有** / **新建供应商** / **不关联供应商**
|
||
|
||
- 关联已有：搜索供应商档案绑定，可 OCR 营业执照
|
||
- 新建供应商：主体、开票、银行、证照上传
|
||
- 不关联：跳过供应商区块
|
||
|
||
**底部**：返回（未保存二次确认）、提交创建（进度达 100% 后可点）
|
||
|
||
### 4.2 编辑 / 查看
|
||
|
||
| 模式 | 交互 |
|
||
|------|------|
|
||
| **编辑** | 整页（与新建同结构）；**不含**供应商；营业状态不在此页；系统账号仅 admin 可改 |
|
||
| **查看** | 弹窗分块：加氢站信息、系统账号、供应商信息、付款信息 |
|
||
|
||
编辑页同样包含 **地图定位模块**，回显已保存经纬度。
|
||
|
||
### 4.3 批量导入
|
||
|
||
**入口**：列表工具栏 → **批量导入**（位于「全站余额提醒设置」右侧）
|
||
|
||
- 下载 CSV 模板 → 上传 `.csv` / `.xlsx` / `.xls`
|
||
- 预览可导入 / 不可导入条数及错误原因
|
||
- 站点名称不可与现有台账重复
|
||
|
||
模板字段与新建表单一致（名称、省、市、详细地址、是否签约、签约起止、营业状态、营业时间、联系人、联系电话等）。
|
||
|
||
### 4.4 地图定位模块
|
||
|
||
**位置**：新建 / 编辑页 → 加氢站基本信息卡片 → 地址解析下方
|
||
|
||
**数据字段**：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `mapAddress` | 地图模块地址（可与通讯地址一致） |
|
||
| `latitude` | 纬度，保留 6 位小数 |
|
||
| `longitude` | 经度，保留 6 位小数 |
|
||
|
||
**交互规则**：
|
||
|
||
1. **地址解析联动**：上方「地址解析」识别成功后，自动将完整地址填入地图地址框并触发定位
|
||
2. **输入定位**：地图地址框支持手动输入；失焦、回车或点击「定位」后，地图自动移动到对应位置
|
||
3. **拖动微调**：地图上标记可拖动，拖动结束后更新经纬度并展示在地图下方
|
||
4. **定位失败**：提示用户拖动标记手动选点
|
||
|
||
**实现说明（原型）**：使用 OpenStreetMap + Leaflet；优先按省市区 Mock 坐标定位，必要时调用 Nominatim 地理编码。
|
||
|
||
### 4.5 删除站点
|
||
|
||
**入口**：更多 → 删除 → 二次确认，不可撤销。
|
||
|
||
---
|
||
|
||
## 五、运营配置
|
||
|
||
### 5.1 营业状态
|
||
|
||
**入口**：更多 → **营业状态**
|
||
|
||
- 顶部站点信息卡（名称、地址、当前状态）
|
||
- **营业状态**：营业中 / 暂停营业 / 停止营业（按钮组）
|
||
- **营业时间**：全天营业 / 自定义时段；非全天须填开始、结束时间（HH:mm）
|
||
- 下方展示 **营业状态变更记录**
|
||
- 保存后列表同步更新
|
||
|
||
### 5.2 价格配置
|
||
|
||
**入口**：更多 → **价格配置**
|
||
|
||
#### 5.2.1 弹窗结构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 顶部：加氢站名称 + 签约站点标签（无则省略） │
|
||
├─────────────────────────────────────────────┤
|
||
│ 当前已生效价格配置（表格） [+ 新增规则] │
|
||
├─────────────────────────────────────────────┤
|
||
│ （点击修改/新增后展开）编辑表单 │
|
||
│ 定价方式 | 适用客户 │
|
||
│ 固定价：成本价格 + 生效时间 │
|
||
│ 阶梯价：阶梯条件 + 重置日/生效时间 │
|
||
├─────────────────────────────────────────────┤
|
||
│ （编辑态）当前规则调整记录 │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 打开弹窗默认为 **查看态**，仅展示已生效配置表格
|
||
- 点击行内 **「修改」** 或 **「+ 新增规则」** 才展开编辑卡片
|
||
- **保存** 后回到查看态，**不关闭**弹窗
|
||
|
||
#### 5.2.2 已生效配置表格
|
||
|
||
| 列 | 说明 |
|
||
|----|------|
|
||
| 适用客户 | 全部客户 / 指定客户名称 |
|
||
| 定价方式 | 固定价格 / 阶梯价格（Tag） |
|
||
| 当前价格 | 元/kg；阶梯价展示当前匹配单价，可附「距下个阶梯还差 X kg」 |
|
||
| 生效时间 | 最近一条已生效日志的生效时间 |
|
||
| 阶梯重置 | 阶梯规则展示「每月 N 日」；固定价显示 — |
|
||
| 操作 | 修改 |
|
||
|
||
#### 5.2.3 定价方式
|
||
|
||
**固定价格**
|
||
|
||
- 成本价格（元/kg）+ 生效时间
|
||
- 适用客户：与阶梯价相同的多选下拉
|
||
- 未选客户 → 保存为「全部客户」规则
|
||
- 已选客户 → 为每个客户各生成一条固定价规则
|
||
- 已有单独规则的客户在下拉中禁用
|
||
- 固定价提示：默认对全部客户生效；已为某客户单独配置的，将自动从本规则中排除
|
||
|
||
**阶梯价格**
|
||
|
||
- 阶梯价格条件：加氢总量阈值（kg）+ 成本单价，可多条
|
||
- 阶梯量重置日期（每月 1～28 日）+ 生效时间
|
||
- 适用客户：多选，至少选一个；可为多个客户批量配置相同阶梯规则
|
||
|
||
#### 5.2.4 生效与列表联动
|
||
|
||
- 保存时写入规则及调整日志
|
||
- 到达生效时间后，列表「当前成本价格」按适用客户范围更新（原型模拟）
|
||
- 同一客户仅允许一套生效规则；保存时校验冲突
|
||
|
||
### 5.3 余额提醒设置
|
||
|
||
#### 5.3.1 单站设置
|
||
|
||
**入口**：更多 → **余额提醒设置**
|
||
|
||
- 展示站点名称、当前预付余额
|
||
- 必填 **提醒金额（元）**，须 > 0
|
||
- 保存后写入 `balanceAlertThreshold`
|
||
- 当预付余额低于阈值时，站点计入 KPI「预付余额预警站点」（已欠费站点不计入预警）
|
||
|
||
#### 5.3.2 全站批量设置
|
||
|
||
**入口**：列表工具栏 → **全站余额提醒设置**（位于批量导入左侧）
|
||
|
||
- 交互与单站余额提醒相同
|
||
- 保存后将同一阈值批量写入 **全部加氢站**
|
||
|
||
### 5.4 发起充值单
|
||
|
||
**入口**：
|
||
|
||
- 列表工具栏 → **发起充值单**（空白行，自选站点）
|
||
- KPI 预警 / 欠费弹窗 → **一键发起充值单**（预填站点）
|
||
|
||
**规则**：
|
||
|
||
- 支持多行，每行选择站点、填写付款金额
|
||
- 自动带出收款公司、银行账号、转账用途等（来自供应商付款信息）
|
||
- 提交后走付款流程（原型提示成功）
|
||
|
||
### 5.5 加氢量 / 预付余额下钻
|
||
|
||
**加氢量下钻**（点击列表加氢量）：
|
||
|
||
- 统计卡：加氢次数、加氢总量、成本总价、加氢总价
|
||
- 明细表字段对齐「车辆氢费明细」
|
||
- 支持导出 CSV
|
||
|
||
**预付余额下钻**（点击列表预付余额）：
|
||
|
||
- 当前余额（负值标「已欠费」）
|
||
- 充值 / 车辆加氢流水
|
||
- 余额趋势图 + 导出 CSV
|
||
|
||
---
|
||
|
||
## 六、核心流程：生成对账单
|
||
|
||
本模块与「车辆氢费明细」配合完成 **站点侧氢费结算闭环**。
|
||
|
||
### 6.1 数据来源
|
||
|
||
对账单明细取自 **车辆氢费明细** 中同时满足以下条件的记录：
|
||
|
||
1. 对账状态 = **已对账**
|
||
2. **尚未**被本站点历史对账单结算过（未绑定 `statementRecordId`）
|
||
3. 加氢时间落在 `[账单开始日期, 账单结束日期]` 内
|
||
4. 加氢站名称与当前操作站点一致
|
||
|
||
> 对账单明细 **仅展示成本字段**，不展示加氢单价、加氢总价。
|
||
|
||
### 6.2 两阶段交互
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[打开「生成对账单」] --> B[选择账单开始/结束日期]
|
||
B --> C[展示上次对账单结束时间]
|
||
C --> D{点击「生成对账单」}
|
||
D -->|无符合条件记录| E[提示调整日期]
|
||
D -->|有记录| F[生成对账记录草稿]
|
||
F --> G[统计：加氢次数/总量/成本总金额]
|
||
G --> H[成本明细表]
|
||
H --> I[填写结算信息]
|
||
I --> J{点击「提交对账单」}
|
||
J -->|校验失败| K[提示必填项]
|
||
J -->|校验通过| L[完成闭环]
|
||
```
|
||
|
||
**阶段一 · 选期生成**
|
||
|
||
- 展示 **上次对账单结束时间**（无则「暂无」）
|
||
- 默认开始日期 = 上次结束日 + 1 天
|
||
- 生成后进入阶段二，日期锁定
|
||
|
||
**阶段二 · 结算提交**
|
||
|
||
| 统计项 | 说明 |
|
||
|--------|------|
|
||
| 加氢次数 | 本账单笔数 |
|
||
| 加氢总量 | kg 合计 |
|
||
| 成本总金额 | 成本总价合计 |
|
||
|
||
**必填结算项**：
|
||
|
||
| 字段 | 规则 |
|
||
|------|------|
|
||
| 结算后加氢站预付款余额 | 只读，= 当前预付余额 − 成本总金额 |
|
||
| 收票日期 | 必填 |
|
||
| 收票金额 | 必填，默认成本总金额 |
|
||
| 发票附件 | 必填 |
|
||
|
||
### 6.3 提交后的系统行为
|
||
|
||
提交成功后需原子性完成：
|
||
|
||
1. 写入对账历史
|
||
2. 扣减站点预付余额
|
||
3. 标记台账记录已结算（`statementRecordId`）
|
||
4. 回写车辆氢费明细：对账日期、收票日期、加氢站付款状态 = 已付款
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 台账 as 车辆氢费明细
|
||
participant 站点 as 站点信息
|
||
participant 财务 as 结算操作人
|
||
|
||
台账->>台账: 完成对账 → 已对账
|
||
财务->>站点: 更多 → 生成对账单
|
||
站点->>台账: 拉取已对账且未结算记录
|
||
财务->>站点: 生成对账记录 + 填收票信息
|
||
财务->>站点: 提交对账单
|
||
站点->>站点: 更新预付余额 / 写对账历史
|
||
站点->>台账: 回写对账日期、收票日期、已付款
|
||
```
|
||
|
||
---
|
||
|
||
## 七、查看对账记录
|
||
|
||
**入口**：更多 → **查看对账记录**
|
||
|
||
### 7.1 历史列表
|
||
|
||
| 列 | 说明 |
|
||
|----|------|
|
||
| 对账日期 | 提交操作时间 |
|
||
| 对账人 | 操作人 |
|
||
| 账单开始/结束日期 | 覆盖区间 |
|
||
| 加氢次数 / 加氢金额 | 本单汇总 |
|
||
| 对账后预付款余额 | 负值标「已欠费」 |
|
||
| 操作 | 查看明细 |
|
||
|
||
### 7.2 查看明细
|
||
|
||
- 账单区间、统计三卡
|
||
- 收票时间、收票金额、发票附件下载
|
||
- 成本明细表
|
||
|
||
---
|
||
|
||
## 八、操作列「更多」菜单
|
||
|
||
| 菜单项 | 作用 |
|
||
|--------|------|
|
||
| 编辑 | 整页编辑站点主数据（含地图） |
|
||
| 营业状态 | 维护营业状态与营业时间 |
|
||
| 价格配置 | 固定价 / 阶梯价多规则配置 |
|
||
| 余额提醒设置 | 单站提醒阈值 |
|
||
| 生成对账单 | 两阶段对账结算 |
|
||
| 查看对账记录 | 历史对账单与明细 |
|
||
| 删除 | 删除站点（不可恢复） |
|
||
|
||
---
|
||
|
||
## 九、校验与异常
|
||
|
||
| 场景 | 处理 |
|
||
|------|------|
|
||
| 新建/编辑：名称重复 | 阻止提交 |
|
||
| 新建/编辑：省市区或详细地址为空 | 阻止提交 |
|
||
| 新建/编辑：联系人或电话缺失 | 阻止提交 |
|
||
| 签约站点：合作时间或合同缺失 | 阻止提交 |
|
||
| 价格配置：未填价格/生效时间/阶梯条件 | 阻止保存 |
|
||
| 阶梯价：未选适用客户 | 阻止保存 |
|
||
| 价格配置：客户已有规则 | 提示编辑原规则 |
|
||
| 余额提醒：金额无效 | 阻止保存 |
|
||
| 对账单：日期无效 / 无已对账记录 | 阻止生成 |
|
||
| 对账单：收票信息不完整 | 阻止提交 |
|
||
| 预付余额结算后为负 | 允许提交，标「已欠费」 |
|
||
| 地图：地址无法定位 | 提示手动拖动选点 |
|
||
|
||
---
|
||
|
||
## 十、研发实现要点
|
||
|
||
1. **价格配置模型**：`priceConfigs[]` 支持 `customerScope: all | customer`、固定价 / 阶梯价、生效日志 `logs[]`；列表价取当前时间已生效日志。
|
||
2. **客户规则互斥**：`h2GetAssignedCustomerIds` 维护已占用客户；保存时 `h2ApplyCustomerExclusion` 处理规则覆盖。
|
||
3. **余额预警**：`balanceAlertThreshold` + `prepaidBalance` 计算 KPI；欠费优先于预警。
|
||
4. **地图字段**：`mapAddress`、`latitude`、`longitude` 随站点主数据持久化。
|
||
5. **对账单幂等**：同一笔已对账记录只能绑定一次 `statementRecordId`。
|
||
6. **跨模块同步**：生产对接统一台账服务；原型通过 `H2_STATION_STATEMENT_LEDGER_UPDATES` / `H2_VEHICLE_LEDGER_API` 模拟回写。
|
||
7. **权限**（后续）：对账提交、全站余额设置建议限制财务 / 管理员角色。
|
||
|
||
### 10.1 主要数据字段（站点）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | string | 加氢站名称 |
|
||
| `region` | string[] | 省、市 |
|
||
| `addressDetail` | string | 详细地址 |
|
||
| `fullAddress` | string | 完整地址展示 |
|
||
| `mapAddress` | string | 地图定位地址 |
|
||
| `latitude` / `longitude` | number | 经纬度 |
|
||
| `isSigned` | boolean | 是否签约 |
|
||
| `contractStart` / `contractEnd` | string | 合作时间 |
|
||
| `businessStatus` / `businessHours` | string | 营业信息 |
|
||
| `costUnitPrice` | number | 列表展示用当前成本价 |
|
||
| `priceConfigs` | array | 价格规则集合 |
|
||
| `balanceAlertThreshold` | number | 余额提醒阈值 |
|
||
| `prepaidBalance` | number | 预付余额 |
|
||
| `bindAccountIds` | string[] | 绑定系统账号 |
|
||
|
||
---
|
||
|
||
## 十一、本期不做
|
||
|
||
- 对账单审批流、ERP 自动过账
|
||
- 发票 OCR 识别与验真
|
||
- 多币种 / 多税率
|
||
- 高德 / 百度地图商用 Key 接入（原型使用 OSM）
|
||
- 按组织架构的复杂数据权限
|
||
|
||
---
|
||
|
||
**文档结束**
|