Skip to content

1398281322-a11y/java-backend-guardrails / skills/java-backend-guardrails/finance-ledger

finance-ledger

Verified

Use when implementing 记账流水, 账户余额, 借贷, 日切, 不可改历史流水, or 余额必须能用流水重放。Not for GMV dashboards (backend-finance-stats) or merchant payout bills (backend-finance-settlement).

FileKindSize
SKILL.mdskill md2.5 KB
---
name: finance-ledger
description: Use when implementing 记账流水, 账户余额, 借贷, 日切, 不可改历史流水, or 余额必须能用流水重放。Not for GMV dashboards (backend-finance-stats) or merchant payout bills (backend-finance-settlement).
---

# 财务流水 / 记账

## When to Invoke

用户余额、平台备付金、积分、佣金账户、面试「余额怎么保证对得上」。

## When NOT

报表口径 → `finance-stats`。商家账期打款 → `finance-settlement`。支付渠道回调 → `pay-notify`。

## 风险(面试考点)

只 UPDATE 余额、没有流水:对不上、无法审计、并发丢更新。只插流水不算余额:每次都 SUM,账户热、还可能漏。

正确:**流水是事实,余额是物化视图**。入账 = 同一本地事务里 `INSERT 流水(uk 业务号)` + `余额 += n WHERE` 或乐观版本。重复业务号插流水失败则整单回滚。

禁止改、删已入账流水。冲正用反向流水。日切后当日流水只读。

金额分;禁止 float。账户类型分开:用户余额、商家待结算、平台佣金,不要一个字段打天下。

## 方案选型(轻量优先)

```sql
t_account (id, type, owner_id, balance_fen, version)
t_ledger  (id, account_id, biz_no, delta_fen, balance_after, uk(account_id, biz_no))
```

```java
@Transactional
void credit(long accountId, String bizNo, long fen) {
    try {
        ledgerMapper.insert(row(accountId, bizNo, fen));
    } catch (DuplicateKeyException e) { return; }
    int n = accountMapper.update(null, Wrappers.<Account>lambdaUpdate()
        .setSql("balance_fen = balance_fen + " + fen)
        .eq(Account::getId, accountId));
    if (n != 1) throw new IllegalStateException("account missing");
}
```

扣减必须 `balance_fen >= fen`。热点账户见 `hot-account`。

日终:对每个账户 `期初 + SUM(当日流水) = 期末`,不平进差错(`reconciliation`)。

## 反例

错误:`setBalance(getBalance()+n)` 无版本无流水。
正确:流水 uk + 条件更新。

错误:客服改余额 UPDATE 一行。
正确:调账也走流水,类型 `ADJUST`,留审核。

错误:统计直接 SUM 流水当实时余额给交易用。
正确:交易读账户表;SUM 只给对账。

## 验证

- 同一 bizNo 入账两次,余额只加一次。
- 并发扣到 0,不会扣成负。
- 用流水重放得到的余额 = 账户表。

## 评审清单

- [ ] 有流水且业务号唯一
- [ ] 余额与流水同事务
- [ ] 不改历史、冲正走反向
- [ ] 单位分
---
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall