diff --git a/docs/rental-address-onchain.md b/docs/rental-address-onchain.md index 600e23f..d415d1d 100644 --- a/docs/rental-address-onchain.md +++ b/docs/rental-address-onchain.md @@ -2,6 +2,10 @@ ## 业务与费用 +同一网络、同一接收地址只能存在一笔待处理的地址上链订单,限制跨应用、跨用户生效。WAITING、EXECUTING、VERIFYING、MANUAL_REVIEW 均占用名额;只有 SUCCESS、FAILED、CANCELLED 释放。相同商户订单号及参数重试仍返回原单,不重复冻结。失败或取消后可重试,但仍须通过链上未激活校验。数据库唯一索引防止并发绕过检查。 + +已有数据库需先执行 `sql/rent_onchain_pending_migration.sql`;若有历史重复待处理订单,脚本拒绝升级,需人工核实交易和资金状态后处理,禁止直接删除或批量取消。 + 用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 rent_node 及已证明所有权的 rent_wallet 执行,不需要供应商创建 rent_app。 地址上链使用独立路径 `/api/rental/v1/address-onchain/quote`、`/create`、`/query`,订单类型由路径固定为 `ADDRESS_ONCHAIN`,请求可省略order_type;若提交只能为ADDRESS_ONCHAIN。原 `/api/rental/v1/quote`、`/create`、`/query` 仅处理 `RESOURCE_RENTAL`,拒绝混用订单类型。两者复用签名、应用归属、商户单号幂等、账务及回调机制。原地址上链接入方需同时更新请求URL和HMAC签名中的完整路径,不能用旧路径签名请求新接口;已有订单可通过新的query路径按原商户单号查询。 diff --git a/docs/rental-income-settlement.md b/docs/rental-income-settlement.md new file mode 100644 index 0000000..9e45e62 --- /dev/null +++ b/docs/rental-income-settlement.md @@ -0,0 +1,28 @@ +# 供应商收益结算与提现付款 + +## 资金流程 + +履约成功且收入已确认 → 管理员创建收益结算单 → 另一管理员审核 → 待结算收益转入可用余额 → 供应商申请提现 → 冻结金额 → 管理员或Telegram审核 → 执行付款 → 人工登记并核验或自动扫描匹配 → 扣除冻结金额。 + +结算仅做内部划转,提现才对应链上出款。沿用现有提现配置、权限和到账机制,供应商需具备 `rent:withdraw:create` 权限。 + +## 表与接口 + +- `rent_settlement.settlement_mode`:新单固定 `INTERNAL_TRANSFER`,历史单为 `LEGACY_PAYOUT`,不接受前端指定模式。 +- `rent_settlement_item`:同一供应商账户、同网络订单净收益快照;每单只允许一次有效结算,拒绝后释放来源。 +- `POST /rental/settlement`:提交1至100个不重复的 `order_ids`,均须 `SUCCESS` 且 `CHARGED`。 +- `POST /rental/settlement/{id}/approve`:提交 `reason`,审批者不能是创建者;同事务验证明细和账户ACTIVE状态,以唯一流水 `INCOME_SETTLE:{id}` 增加可用、等额减少待结算。结果为 `SETTLED` 并记录 `settled_at`。重复审批不重复划转。 +- `POST /rental/settlement/{id}/reject`:其他管理员拒绝待审单,不修改资金,释放明细占位。 +- 新单禁止 `pay/unknown/confirm`,完成结算后不允许拒绝撤销。提现使用原 `/rental/withdraw/create` 等接口。 + +SETTLED后仍保留来源占位。沿用退款保护:被结算占用的来源不得直接冲正供应商收入或向其返还手续费;待审单可先拒绝后处理退款。已结算收益的后续冲正需独立资金追偿业务,不能从其他订单待结算收益中冒扣,此版本不开放该操作。 + +## 升级与旧单 + +停服备份后执行 `sql/rent_income_settlement_migration.sql`,再部署新后端和前端。脚本可重复执行,仅增加模式与入账时间字段,不更改余额和历史状态。不要在旧、新版本混跑时创建结算单。 + +所有历史单保持 `LEGACY_PAYOUT`,继续原审批、付款授权和交易核验,完成只扣待结算,不增加可用,防止重复提现。历史PENDING/APPROVED且明确未付款的单可先按原规则拒绝,再创建新收益结算单;PAYING/UNKNOWN不能自动拒绝或转换。不得直接改模式或删除明细绕过来源占位。 + +## 排查 + +按 `settlementId` 查创建、审批幂等、入账或拒绝日志。核对明细合计、来源订单净应收、账户状态及 `rent_ledger` 的 `INCOME_SETTLE` 记录。划转前后可用与待结算之和不变,冻结与平台手续费不变;提现另外记账。 diff --git a/docs/rental/implementation.md b/docs/rental/implementation.md index df274b0..701fbea 100644 --- a/docs/rental/implementation.md +++ b/docs/rental/implementation.md @@ -106,7 +106,7 @@ node --env-file=.env src/index.js 每天UTC02:00自动进行账账核对,发现差异只告警,不直接修复余额或释放未知本金。运营可在资金账户/流水页主动执行完整分页核对。 -结算 `pay` 先持久化唯一 `payout_no` 及本次收款地址,再由人工付款;重试返回原授权,不产生新的付款。`confirm` 根据原授权收款地址、账户网络及精确USDT金额核对原交易日志。后端不自动对外出金。 +新结算单使用 `INTERNAL_TRANSFER` 模式,其他管理员 `approve` 后将供应商净收益从待结算转入可用余额,状态为 `SETTLED`,不执行链上付款。对外付款统一通过提现处理。`LEGACY_PAYOUT` 仅兼容升级前付款单,保留原授权和交易核验,不转入内部余额。见 `../rental-income-settlement.md`。 ## 6. 外部商户签名接口 diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlement.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlement.java index fa9caf3..26dbf16 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlement.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlement.java @@ -25,6 +25,18 @@ public class RentSettlement extends BaseEntity @Excel(name = "结算单号") private String settlementNo; + /** INTERNAL_TRANSFER为收益入账;LEGACY_PAYOUT仅处理升级前付款单。 */ + @Excel(name = "结算模式") + private String settlementMode; + /** 内部结算完成时间,与历史链上付款时间分开记录。 */ + @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") + private Date settledAt; + + public String getSettlementMode() { return settlementMode; } + public void setSettlementMode(String settlementMode) { this.settlementMode = settlementMode; } + public Date getSettledAt() { return settledAt; } + public void setSettledAt(Date settledAt) { this.settledAt = settledAt; } + /** 供应商rent_account.id */ @Excel(name = "供应商rent_account.id") private Long accountId; diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlementPlus.java b/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlementPlus.java index 4a866c2..3fc9cc5 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlementPlus.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/domain/RentSettlementPlus.java @@ -26,6 +26,18 @@ public class RentSettlementPlus implements Serializable /** 结算单号 */ @Excel(name = "结算单号") private String settlementNo; + + /** INTERNAL_TRANSFER为收益入账;LEGACY_PAYOUT仅处理升级前付款单。 */ + @Excel(name = "结算模式") + private String settlementMode; + /** 内部结算完成时间,与历史链上付款时间分开记录。 */ + @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") + private Date settledAt; + + public String getSettlementMode() { return settlementMode; } + public void setSettlementMode(String settlementMode) { this.settlementMode = settlementMode; } + public Date getSettledAt() { return settledAt; } + public void setSettledAt(Date settledAt) { this.settledAt = settledAt; } /** 供应商rent_account.id */ @Excel(name = "供应商rent_account.id") private Long accountId; diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalController.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalController.java index 7ad9e11..384b0e6 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalController.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalController.java @@ -362,6 +362,8 @@ public class RentalController { Map row = store.get("settlement", id, false), account = store.get("account", number(row, "account_id"), false); Map authorization; + require("LEGACY_PAYOUT".equals(text(row, "settlement_mode")), + "收益结算不接受链上付款登记,请使用提现功能"); try { authorization = new com.fasterxml.jackson.databind.ObjectMapper() diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalOrders.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalOrders.java index f30e216..59108c4 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalOrders.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalOrders.java @@ -209,6 +209,15 @@ public class RentalOrders { log.info("地址上链幂等命中 orderId={} network={}", existing.get("id"), network); return existing; } + // 跨应用、跨用户检查;人工核对仍可能已广播,不能视为可重新下单。 + Map pending = store.one("SELECT id FROM rent_order WHERE network=?" + + " AND receiver_address=? AND order_type='ADDRESS_ONCHAIN'" + + " AND status NOT IN ('SUCCESS','FAILED','CANCELLED') LIMIT 1", network, receiver); + if (pending != null) { + log.warn("地址上链重复下单已拒绝 network={} receiver={} pendingOrderId={} userId={}", + network, receiver, pending.get("id"), user); + throw new IllegalArgumentException("该地址在当前网络已有待处理的上链订单,请等待原订单完成"); + } Map price = onchain.quote(request); // 在任何账户创建、订单写入和资金冻结前查询最新链上状态;RPC未知时直接中止。 // 必须位于原单幂等返回之后,已成功激活的原订单仍可安全重试和查询。 @@ -234,7 +243,19 @@ public class RentalOrders { "status", "WAITING", "payer_account_id", account.get("id"), "fund_status", "HELD", "dispatch_deadline", after(300), "reclaim_status", "NOT_REQUIRED", "notify_url", notify.isEmpty() ? null : notify); - long orderId = store.insert("order", order); + long orderId; + try { + // 数据库唯一索引兜底,防止不同应用或服务实例同时通过上面的预检查。 + orderId = store.insert("order", order); + } catch (org.springframework.dao.DuplicateKeyException exception) { + if (exception.getMostSpecificCause().getMessage() != null + && exception.getMostSpecificCause().getMessage().toLowerCase(java.util.Locale.ROOT) + .contains("uk_order_onchain_pending")) { + log.warn("地址上链并发重复下单已拒绝 network={} receiver={} userId={}", network, receiver, user); + throw new IllegalArgumentException("该地址在当前网络已有待处理的上链订单,请等待原订单完成"); + } + throw exception; + } order.put("id", orderId); funds.hold(order); log.info("地址上链分账已锁定 orderId={} platformPercent={} platformFeeUsdt={} supplierNetUsdt={}", diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalReviews.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalReviews.java index bc6f27e..24eef9a 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalReviews.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalReviews.java @@ -10,7 +10,10 @@ import java.util.*; /** 人工退款及结算审批;审批者与发起者分离,付款未知绝不释放来源。 */ @Service +@lombok.extern.slf4j.Slf4j public class RentalReviews { + /** 新单仅内部划转;历史单继续按原付款授权处理,禁止混用两种记账方式。 */ + private static final String INTERNAL_TRANSFER = "INTERNAL_TRANSFER"; private final RentalStore store; private final RentalFunds funds; private final RentalOrders orders; @@ -202,6 +205,9 @@ public class RentalReviews { for (long orderId : sorted) { Map order = store.get("order", orderId, true); require("CHARGED".equals(text(order, "fund_status")), "来源订单尚未确认收入"); + require("SUCCESS".equals(text(order, "status")), "仅履约成功订单允许收益结算"); + require(store.one("SELECT id FROM rent_settlement_item WHERE order_id=? AND active_slot=1", orderId) + == null, "来源订单已被结算占用或已结算"); long current = number(order, "supplier_account_id"); require(account == null || account == current, "只允许同一供应商同网络的来源"); account = current; @@ -225,6 +231,8 @@ public class RentalReviews { total, "status", "PENDING", + "settlement_mode", + INTERNAL_TRANSFER, "created_by", actor)); for (Map source : sources) { @@ -233,6 +241,8 @@ public class RentalReviews { store.insert("settlement_item", source); } store.event("SETTLEMENT", id, "CREATE", actor, "占用订单净应收来源"); + log.info("收益结算单创建 settlementId={} accountId={} amountUsdt={} sourceCount={} actorId={} mode={}", + id, account, total, sorted.size(), actor, INTERNAL_TRANSFER); return id; } @@ -240,6 +250,12 @@ public class RentalReviews { public Map transition(long id, String action, long actor, String reason) { Map row = store.get("settlement", id, true); String state = text(row, "status"); + log.info("结算操作检查 settlementId={} mode={} state={} action={} actorId={}", + id, text(row, "settlement_mode"), state, action, actor); + if (INTERNAL_TRANSFER.equals(text(row, "settlement_mode"))) { + return internalSettlement(row, action, actor, reason); + } + require("LEGACY_PAYOUT".equals(text(row, "settlement_mode")), "结算模式无效,请检查数据库升级"); if ("approve".equals(action)) { require("PENDING".equals(state) && number(row, "created_by") != actor, "审批须职责分离"); store.update( @@ -279,10 +295,67 @@ public class RentalReviews { return store.get("settlement", id, false); } + /** + * 调用方已锁结算单。审批、来源核对、余额划转及审计在同一事务提交。 + * SETTLED不代表对外付款;来源占位永久保留,之后仅可从可用余额申请提现。 + */ + private Map internalSettlement(Map row, String action, long actor, String reason) { + long id = number(row, "id"); + String state = text(row, "status"); + if ("approve".equals(action)) { + if ("SETTLED".equals(state)) { + log.info("收益结算审批幂等返回 settlementId={} actorId={}", id, actor); + return row; + } + require("PENDING".equals(state) && number(row, "created_by") != actor, "审批须职责分离且结算单待审核"); + List> items = store.rows( + "SELECT * FROM rent_settlement_item WHERE settlement_id=? ORDER BY order_id", id); + require(!items.isEmpty(), "结算来源不能为空"); + BigDecimal total = ZERO; + for (Map item : items) { + Map order = store.get("order", number(item, "order_id"), true); + BigDecimal net = amount(order, "supplier_net_amount") + .subtract(amount(order, "supplier_reversed_amount")) + .add(amount(order, "supplier_fee_returned_amount")); + require(number(item, "active_slot") == 1 && "CHARGED".equals(text(order, "fund_status")) + && "SUCCESS".equals(text(order, "status")) + && number(order, "supplier_account_id") == number(row, "account_id") + && net.signum() > 0 && net.compareTo(amount(item, "amount")) == 0, + "来源订单状态或净应收已变更,请拒绝后重新创建结算单"); + total = total.add(net); + } + require(total.compareTo(amount(row, "amount")) == 0, "结算明细金额不一致"); + Map account = store.get("account", number(row, "account_id"), true); + require("ACTIVE".equals(text(account, "status")), "供应商账户已冻结,暂不能结算"); + funds.post(number(row, "account_id"), "INCOME_SETTLE:" + id, "INCOME_SETTLE", + total, ZERO, total.negate(), ZERO, null, id, null, actor, null, + "收益结算转入可用余额:" + reason); + store.update("settlement", id, map("status", "SETTLED", "approved_by", actor, + "settled_at", now(), "remark", reason)); + store.event("SETTLEMENT", id, "INCOME_SETTLE", actor, reason); + log.info("收益结算完成 settlementId={} accountId={} amountUsdt={} actorId={} sourceCount={}", + id, row.get("account_id"), total, actor, items.size()); + } else if ("reject".equals(action)) { + if ("REJECTED".equals(state)) { + return row; + } + require("PENDING".equals(state) && number(row, "created_by") != actor, "只能由其他审批人拒绝待审收益结算单"); + store.update("settlement", id, map("status", "REJECTED", "approved_by", actor, "remark", reason)); + store.execute("UPDATE rent_settlement_item SET active_slot=NULL,version=version+1,updated_at=? WHERE settlement_id=?", now(), id); + store.event("SETTLEMENT", id, "REJECT", actor, reason); + log.info("收益结算拒绝并释放来源 settlementId={} actorId={}", id, actor); + } else { + log.warn("收益结算拒绝旧付款操作 settlementId={} action={} actorId={}", id, action, actor); + throw new IllegalArgumentException("收益结算只支持审核入账或拒绝;对外付款请使用提现功能"); + } + return store.get("settlement", id, false); + } + /** 由链上只读服务独立核对付款后调用;不接受前端的verified=true作为依据。 */ @Transactional(rollbackFor = Exception.class) public void paid(long id, String reference, String evidence, long actor) { Map row = store.get("settlement", id, true); + require("LEGACY_PAYOUT".equals(text(row, "settlement_mode")), "收益结算不能登记链上付款,请通过提现付款"); if ("PAID".equals(text(row, "status"))) { require(reference.equals(text(row, "payment_reference")), "付款凭据冲突"); return; diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalStore.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalStore.java index 92def11..b86a973 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalStore.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalStore.java @@ -7,7 +7,6 @@ import org.springframework.jdbc.support.GeneratedKeyHolder; import org.springframework.stereotype.Repository; import java.sql.PreparedStatement; -import java.sql.Statement; import java.util.*; /** 租赁事务仓储。动态标识符只接受内部白名单,业务值全部使用占位符。 行锁由调用方事务持有;RPC必须在事务外执行,避免占用数据库连接等待链上响应。 */ @@ -93,7 +92,8 @@ public class RentalStore { jdbc.update( connection -> { PreparedStatement ps = - connection.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS); + // 只读取自增主键,避免生成列也被驱动返回为 generated keys。 + connection.prepareStatement(sql, new String[] {"id"}); int index = 1; for (Object value : values.values()) { ps.setObject(index++, value); diff --git a/ruoyi-system/src/main/resources/mapper/system/RentSettlementMapper.xml b/ruoyi-system/src/main/resources/mapper/system/RentSettlementMapper.xml index 4fe2940..72ffb00 100644 --- a/ruoyi-system/src/main/resources/mapper/system/RentSettlementMapper.xml +++ b/ruoyi-system/src/main/resources/mapper/system/RentSettlementMapper.xml @@ -7,6 +7,8 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" + + @@ -24,7 +26,7 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" - select id, settlement_no, account_id, amount, status, payout_no, payment_started_at, payment_evidence, payment_reference, created_by, approved_by, paid_at, remark, version, created_at, updated_at from rent_settlement + select id, settlement_no, settlement_mode, settled_at, account_id, amount, status, payout_no, payment_started_at, payment_evidence, payment_reference, created_by, approved_by, paid_at, remark, version, created_at, updated_at from rent_settlement