# 车辆收费系统需求文档 (PRD) v1.8.0

## 修订历史

| 版本号 | 修订日期 | 修订内容 | 修订人 | 状态 |
| :--- | :--- | :--- | :--- | :--- |
| v1.0.0 | 2026-01-27 | 初始版本：初始化车辆收费系统基础功能框架 | Antigravity | 已发布 |
| v1.1.0 | 2026-01-27 | 扩展版本：专注“车辆收费”核心逻辑，细化计费规则与支付体系 | Antigravity | 已发布 |
| v1.2.0 | 2026-01-28 | 完善版本：整合车辆管理与收费标准逻辑，增加收费内容状态管理、一车一账及账单作废功能 | Antigravity | 已发布 |
| v1.3.0 | 2026-01-28 | 修正版本：优化账单状态判定逻辑，明确作废/退款规则，调整支付金额匹配机制 | Antigravity | 已发布 |
| v1.4.0 | 2026-01-28 | 迭代版本：增加手动新增收费、状态动态展示、限制实缴上限 | Antigravity | 已发布 |
| v1.5.0 | 2026-01-29 | 澄清版本：明确单一车牌可关联多条不同收费规则生成的账单 | Antigravity | 已发布 |
| v1.6.0 | 2026-01-29 | 增强版本：增加访客冲突检测、临停过期清除、黑名单强制追缴、换车账单继承及多账单重叠处理逻辑 | Antigravity | 已发布 |
| v1.7.0 | 2026-01-29 | 细化版本：增加一位多车溢出计费规则、明确有效期滚动更新机制、修正临时车欠费阻断删除逻辑 | Antigravity | 已发布 |
| v1.8.0 | 2026-01-30 | 优化版本：放开一位多车绑定数量限制（按进场优先），修正有效期更新算法（MAX逻辑）及支付顺序约束 | Antigravity | 草案 |

---

## 1. 目标
实现停车场收费业务的精细化管理，建立“一车一账”的费用归集体系，通过严格的账单状态机管理与支付/退款流程，确保财务数据的准确性与操作的可审计性。

## 2. 核心功能需求

### 2.1 账单状态管理 (Bill Lifecycle & Status)
每笔账单必须具备明确的**账单状态**，用于描述该笔费用的时间有效性。

- **状态定义**：
  - **未生效 (Unactivated)**：当前时间 < 账单有效期的开始时间。
  - **生效中 (Activated)**：账单有效期的开始时间 <= 当前时间 <= 账单有效期的结束时间。
  - **已失效 (Expired)**：当前时间 > 账单有效期的结束时间。
- **展示要求**：
  - **动态展示**：账单状态必须在管理后台列表页及详情页进行实时/动态展示，确保操作人员能清晰分辨账单的当前时效性。
- **关联判定逻辑**：
  - 账单状态需结合**支付状态**共同判断业务可用性。
  - 系统需支持根据时间自动推进状态（如每日零点更新），或在查询时实时计算。

### 2.2 缴费与金额规则 (Payment & Amount Rules)
- **缴费支持**：
  - 支持对“待支付”状态的账单进行缴费。
  - **不支持部分缴费**：单次支付必须核销整笔账单，不支持分多次支付同一笔账单。
  - **支付顺序约束**：
    - 若同一车辆存在多笔待支付的时效性账单（如连续3个月的月租账单），系统要求**必须按账单周期顺序支付**，或支持**一并合并支付**。
    - **禁止跳跃支付**（例如：不能在未支付1月账单的情况下，直接支付3月账单），以保证有效期的连续性。
- **金额匹配机制**：
  - **实缴上限约束**：**实缴金额不能超过应交金额**。系统需在支付录入环节进行校验，拦截溢缴情况。
  - **允许金额不匹配**：系统支持实缴金额小于应交金额的情况（如手动折扣、抹零等）。
  - **记录要求**：必须在流水中分别记录“应交金额”与“实缴金额”两个字段。

### 2.3 支付状态与操作流转 (Payment Status & Operations)
- **支付状态定义**：
  - **待支付**：账单已创建，等待用户缴费。
  - **已支付**：款项已成功入账。
  - **已退款**：已针对原支付记录完成退款操作。
  - **已作废**：账单已被管理员手动废弃。
- **核心操作规则**：
  - **账单作废 (Voiding)**：**只能作废“待支付”状态的账单**。已支付或已失效的账单不允许直接作废。
  - **退款操作 (Refund)**：**只有“已支付”状态的账单可以发起退款**。退款完成后，支付状态变更为“已退款”。

### 2.4 “一车一账”费用汇总与冲突处理 (Unified Vehicle Ledger & Conflict Resolution)
- **多账单并行逻辑**：
  - **原则**：系统支持一个车牌号下存在多条并行的收费账单。
  - **临停与长租共存**：在车辆未成为“长租车”前，可能已存在“待支付”的临停账单。
  - **重叠处理 (Conflict Resolution)**：
    - 当审批通过或新增一笔“长租/月租”业务时，若该车辆已存在且处于“待支付”状态的临停账单，且**临停有效期与新的长租生效时间重叠**。
    - **系统行为**：必须弹出提示，询问物业员工“检测到该时段存在未缴费临停账单，是否作废？”。
- **一位多车溢出计费 (Overflow Charging with Unlimited Binding)**：
  - **场景**：车位容量管理**不设数量限制**，一个车位允许绑定多辆车（如 A、B、C...）。
  - **计费优先级规则（按进场时间）**：
    - **首位优先**：当该车位绑定的任意一辆车（例如 C车）**最先入场**时，该车享受车位绑定的优惠规则（如月租/免费）。
    - **溢出计费**：在首位车辆（C车）未离场期间，该车位绑定的其他车辆（A车、B车...）若进入车场，系统**自动按车场默认收费规则**（如临停标准）计费。
    - **权益释放**：只有当享受优惠的首位车辆（C车）**出场后**，车位的优惠权益才被释放，供下一辆入场的绑定车辆使用。
- **账单生成时机**：
  - **收费标准变更**：若车辆关联的收费标准发生变更，**新账单将在当前计费周期结束时生成**，当前周期内仍按原标准执行。

### 2.5 特殊业务场景处理 (Special Scenarios)
#### 2.5.1 访客车辆登记冲突
- **场景**：在进行访客登记时，系统需检测输入的车牌号是否已存在于系统中。
- **冲突逻辑**：
  - 若检测到该车牌已登记为某住户的车辆（长租/业主车）。
  - **提示信息**：“该车牌已登记为XX住户的车辆，不用将车辆添加为访客车”。
  - **收费逻辑**：保持不变，继续按该车辆原有的绑定规则（如月租免费或业主优惠）执行计费，不应用访客收费标准。

#### 2.5.2 临时车欠费阻断清除 (Temp Vehicle Liquidation)
- **有效期管理**：临时车辆设置默认有效期（如2年）。
- **过期与欠费检查**：
  - 当有效期到达时，系统**首先执行欠费检查**，判断该车辆是否存在“待支付”账单。
- **分支处理逻辑**：
  - **Case A：存在欠费**
    - **动作**：禁止删除档案。
    - **状态标记**：将车辆状态更新为“**已过期待清算**”。
    - **通知触达**：向住户推送提醒：“临时车已过期，请缴清欠费后重新申请”。
    - **用户端展示**：住户可在小程序中看到标记为“已过期”的车辆及其关联的欠费账单。
  - **Case B：无欠费**
    - **动作**：执行**软删除**（保留历史数据引用的有效性），车辆状态置为“失效/已归档”。

#### 2.5.3 黑名单追缴机制
- **强制执行**：对于被列入黑名单的车辆，其名下的未缴账单将强制执行追缴。
- **移除限制**：
  - 当尝试将车辆移出黑名单时，系统必须强制进行“欠费检查”。
  - 若存在未缴账单，**禁止移除**，并提示“请先缴纳欠费账单后，再进行黑名单移除操作”。

#### 2.5.4 换车申请账单逻辑
- **场景**：住户申请更换名下车辆（如：旧车A -> 新车B）。
- **账单继承与生成**：
  - **旧车账单**：原车辆（旧车A）已生成的已支付/待支付账单保持不变，不进行迁移。
  - **有效期继承**：新车辆（新车B）直接继承原车辆的剩余有效期（结束时间）。
  - **新账单生成**：新车辆在继承的有效期结束之后，按其对应的收费规则生成新的账单。
- **备注要求**：
  - 在新车辆的档案或首笔账单备注中，系统自动添加说明：“原车辆[旧车牌]通过换车申请变更为新车辆”。

## 3. 业务规则补充

### 3.1 授权有效期滚动更新 (Rolling Validity Logic)
- **初始有效期**：以车辆**第一次申请进入系统**的时间为准。
- **更新算法 (Validity Update)**：
  - 术语明确：使用“**更新**”而非“延长”或“挪动”，确保语义准确。
  - **计算公式**：
    `车辆最新授权有效期 = MAX( 当前系统记录的有效期, 所有已支付账单中的最晚结束时间 )`
  - **目的**：确保有效期始终向后覆盖，避免因支付旧账单导致有效期回退。
- **触发机制**：
  - 仅在用户**成功支付**时效性账单后触发更新计算。
- **通行与计费判定**：
  - 底层道闸及计费系统必须**以车辆最新的授权有效期**为准，判断是否放行或是否需要触发临时计费。

### 3.2 手动新增车辆收费 (Manual Bill Creation)
- **功能描述**：支持管理员手动为特定车辆创建收费账单。
- **适用场景**：特殊欠费补录、线下协商收费、非系统自动感应产生的费用录入。
- **录入字段**：车牌号、费用类型、应交金额、有效期范围、备注/原因。
- **校验逻辑**：录入后账单初始状态默认为“待支付”。

### 3.3 联动影响
- **车辆管理联动**：
  - 时效性账单（月租）在“已支付”且处于“生效中”时，车辆管理模块应同步更新车辆的有效期及白名单状态。
- **退款联动**：
  - 若月租类账单发起退款，系统应自动缩短或撤销对应的车辆有效期，并同步至底层设备。

## 4. 待确认事项 (Q&A)
1. 临时车“已过期待清算”状态下，若车辆再次入场，是禁止入场还是按临时车计费？（建议：按临时车计费，并再次提示欠费）。