Vault/uniprop-manual

Fork 0

Files

Willie 82de3396bb vault backup: 2026-05-26 00:58:14

2026-05-26 00:58:14 +08:00

7.5 KiB

Raw Blame History

title, aliases, tags, audience, status, sub_feature, last_review, code_version

title

aliases

场景:月度物业费 300 户批量生成

每月 1 日,物业为社区所有业户批量生成本月物业费账单。走 GeneratePeriodicBillsAction,默认 SkipExisting 策略。

典型情境

[!example] 真实情境 5 月 1 日上午 9 点,嘉禾花园物业财务王主管打开后台:

300 户业户(住宅 + 商铺)

物业费 RatePlan:住宅 ¥3 / m²(平均面积 100 m² → ¥300),商铺 ¥8 / m²

王主管:1 次点击 + 1 个 Modal,300 张账单全部建好

业务人员视角

第 1 步:打开 BillsList

后台 → 账单 → 列表 → 顶部 "批量生成周期账单" 按钮(GeneratePeriodicBillsAction)。

第 2 步:Modal 填参数

参数	填什么
期次(billing_period)	2026 年 5 月(start: 5/1, end: 5/31)
费用类型(fee_type_id)	物业费(下拉选)
社区范围(community_id)	嘉禾花园
业户范围	全社区业户(默认)
合并策略(merge_strategy)	`SkipExisting`(默认,详见 periodic-bill-generation)
备注	选填,如 "5 月例行物业费生成"
到期日(due_at)	6 月 15 日(本月 + 15 天宽限期)

第 3 步:提交

[!warning] Policy 守护按钮 ->authorize('create', Bill::class),需要 bill.create 权限。

系统执行(后台逻辑):

flowchart TD
  A[扫描候选业户清单<br/>SELECT * FROM community_user_profiles<br/>WHERE community_id=? AND status=active] --> B[300 业户]

  B --> C[每户:]
  C --> D{该户该期次<br/>已有 Bill?}
  D -->|是| E[Skip(默认策略)]
  D -->|否| F[查 RatePlan 算金额<br/>3 * 100 = 300]
  F --> G[建 Bill]
  G --> H[活动日志]

  E --> I[报告]
  H --> I

第 4 步:看结果报告

2026 年 5 月物业费生成完成

✅ 已生成:298 张
⏭️ 已跳过:2 张(本月已存在,SkipExisting 策略)
❌ 失败:0 张

总金额:¥120,400
平均每户:¥401

第 5 步:抽样核对

业务人员抽 2-3 张账单看金额是否对(尤其 RatePlan 改过后)。

第 6 步:推送给业户

视物业策略:

自动推送(若集成微信公众号 / 小程序)
或单独触发"通知本月账单"动作

系统流程

sequenceDiagram
    participant 王主管
    participant Filament
    participant Action[GeneratePeriodicBillsAction]
    participant DB
    participant Notify[通知服务]

    王主管->>Filament: 批量生成周期账单 → Modal 填参数 → 提交
    Filament->>Action: handle(community, feeType, period, strategy)
    Action->>DB: 扫描候选业户清单

    loop 每户
      Action->>DB: 查该户该期次是否已有 Bill
      alt 已有
        Action->>Action: 按策略处理(默认 Skip)
      else 无
        Action->>DB: 查 RatePlan + 算金额
        Action->>DB: 建 Bill (status=Unpaid, period, due_at)
      end
    end

    Action->>Notify: 触发"批量账单已生成"通知(可选)
    Action-->>Filament: 报告(生成 / 跳过 / 失败统计)
    Filament-->>王主管: Modal 显示统计

业户视角

业户 5 月 1 日 / 2 日陆续收到推送:

张阿姨您好,您的 2026 年 5 月物业费 ¥300 已生成,请于 6 月 15 日前付清。

可选付款方式:

微信小程序付

到前台付现金 / 微信 / POS

您预存款余额 ¥1,200 足够,可自动抵扣(若开通自动抵扣)

业户可选:

立即付(collect-payment-single / collect-payment-batch)
等到期日前付
不付 → 到期日后变逾期(exception-overdue-bills)

异常处理

部分业户失败(RatePlan 缺失)

异常	处置
某户没分配 RatePlan(新业户)	Action 跳过该户 + 报告标记 → 业务人员手动配 RatePlan 后单独生成
某户面积字段缺失	同上
系统级故障(DB / 内存)	Action 抛错 + 部分生成的 Bill 在事务内回滚

Merge 策略案例(进阶)

如果业务人员想"同业户的物业费 + 电视费 + 网络费合并到一张账单":

Modal 选 merge_strategy = Merge
系统找到已生成的物业费 Bill,把电视费 / 网络费追加进同一张 Bill(amount 累加)
业户看到的是一张合并账单 ¥XX(明细几项)

详见 periodic-bill-generation"策略 2:Merge"段。

Replace 策略案例(罕见)

业务人员发现 5 月物业费 RatePlan 配错了 → 选 merge_strategy = Replace:

找到已有 Bill → 作废(VoidBillAction)
按新 RatePlan 重新生成

[!warning] Replace 风险 Replace 对已付的 Bill 慎用,会让业户已付的钱"卡在 Void 状态",需配套退款流程。

常见问题

[!question] 同一户能否生成两次同期次同费用类型? 业务上不应(违反一户一月一物业费规则)。系统层面通常有 unique 索引拦截。SkipExisting 策略也避免重复。

[!question] 一次生成失败一半怎么办? Action 内部对单户失败容错(跳过失败户,继续其他),不会因一户失败回滚全部。报告会列出失败户,业务人员单独处理。

[!question] 周期账单生成后想推迟到期日? Bill 创建后 due_at 字段通常可编辑(若 status=Unpaid)。批量改可能需要专门的"批量推迟到期日" Action(当前没,可手工逐张改或运维 tinker)。

[!question] 业务人员忘了月初生成怎么办? 月中或月底再触发,系统正常生成(due_at 仍按原计划,可能立即逾期)。业户体验不好(账单晚到),需提前通知。

[!question] 自动化(Scheduled Job)有吗? issue.md Q6 未明确(meter 和 prepaid 也都有"自动化待补"的待办)。当前手动触发。未来可加:

月初 1 日 00:30 自动触发(类似 prepaid 自动抵扣)

触发后立即触发预存款抵扣(无缝)

业户次日早收到推送

[!question] 业户拒绝接收推送怎么办? 系统层面不影响(账单仍在,可在小程序 / 后台查)。推送只是触达手段。业户拒收推送 → 物业改用电话 / 短信 / 上门通知。

[!question] 不同费用类型(物业费 + 电视费)能一次性都生成吗? 当前 GeneratePeriodicBillsAction 一次只生成一个费用类型。批量需触发多次(物业费 1 次 + 电视费 1 次 + ...)。或者业务方反馈后增加"多费用类型批量"功能。

与计量账单生成的对比

| 维度 | 本场景(周期账单)| create-meter-bill-auto | |---|---|---| | 触发 | 业务人员手动 | 抄表完成后自动 / 批量 | | 金额 | 固定(RatePlan)| 浮动(用量计算)| | 数量 | 每户每期 1 张 | 每抄表 1 张 | | sourceable | null(或周期任务 ID)| MeterReading | | 频率 | 月度 1 次 | 看抄表频率 |

异常分支

计量账单生成 → create-meter-bill-auto
临时手动建单 → create-single-bill-manual
业务人员要批量删错的 → bulk-delete-batch-mistake
业户收到账单要付款 → collect-payment-single

7.5 KiB Raw Blame History