wangmian/ONE-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86634d1050e0c6824c945c7b488d36065ad0df9e
ONE-OS/web端/加氢站管理/站点信息-产品需求说明.md
王冕 86634d1050 完善加氢站站点信息：价格配置、余额提醒、地图定位与 PRD。 
新增多规则价格配置、全站余额提醒、地图选点及 v2.0 产品需求说明文档。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-23 10:43:30 +08:00

18 KiB
Raw Blame History

加氢站管理 · 站点信息 — 产品需求说明（PRD）

项目 内容
文档版本 v2.0
产品模块 加氢站管理 → 站点信息
文档类型 产品需求说明
适用读者 研发、测试、产品、项目
关联模块 台账数据 → 车辆氢费明细
原型文件 web端/加氢站管理/站点信息.jsx

一、为什么做这件事

1.1 业务背景

加氢站是氢费成本结算的关键节点。运营侧需要维护站点主数据（签约、地址坐标、营业、成本价、预付余额），并在财务周期内按站点与加氢站完成对账、收票与付款闭环。

1.2 本期目标

建设 Web 端「站点信息」页面，支撑：

  • 站点台账的查询、新建、编辑、查看、删除与批量导入
  • 地图定位、营业状态、多规则成本价格、余额提醒等运营配置
  • 加氢量 / 预付余额下钻分析与充值单发起
  • 按站点生成氢费对账单 → 填写收票信息 → 提交结算，并与「车辆氢费明细」联动回写

1.3 用户角色

角色 典型诉求
加氢站运营 维护站点资料、营业与价格；查看加氢量与余额；设置余额提醒
财务/结算 按周期生成对账单、登记收票、发起充值、完成站点付款闭环
管理员 批量导入站点、全站余额提醒、删除无效站点、绑定系统账号

二、页面整体结构

用户进入「加氢站管理 → 站点信息」后，页面自上而下为：

  1. 筛选区 — 名称、是否签约、地区、营业状态
  2. KPI 分类 — 全部 / 预付余额预警 / 已欠费 / 无加氢；签约站点快捷筛选
  3. 工具栏 — 全站余额提醒设置、批量导入、发起充值单、新建站点
  4. 站点列表 — 主数据 + 运营指标 + 操作列
  5. 子页面 / 弹窗 — 新建/编辑整页、查看、营业状态、价格配置、余额提醒、对账单、对账记录、下钻分析等
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 地图定位模块
联系人 是 —
手机号 / 固定电话 至少一项 格式校验
站点类型 否 签约站点 / 普通站点；签约须填合作时间与合同附件

（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 两阶段交互

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. 回写车辆氢费明细：对账日期、收票日期、加氢站付款状态 = 已付款
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）
  • 按组织架构的复杂数据权限

文档结束

Reference in New Issue View Git Blame Copy Permalink