feat:钱包的流水增加"备注字段"

fix:合并设备管理的统计模块
2026-08-25 11:11:01 +08:00
1 parent d1cd86dfa4
commit 9d2a0ee1ab
@@ -0,0 +1,24 @@
+package com.bsd.pjcloud.thirdparty.constant.fz;
+
+import lombok.Getter;
+
+/**
+ * 商户分账关系业务场景，编码用于区分同一渠道账号未来可能增加的其他分账用途。
+ */
+@Getter
+public enum ThirdMchFzRelationSceneEnum {
+    /** 商户支付成功后向平台收取服务费的默认分佣关系。 */
+    DEFAULT_PLATFORM_COMMISSION("DEFAULT_PLATFORM_COMMISSION");
+
+    /** 关系表持久化的稳定业务场景编码。 */
+    private final String code;
+
+    /**
+     * 创建关系场景。
+     *
+     * @param code 持久化场景编码
+     */
+    ThirdMchFzRelationSceneEnum(String code) {
+        this.code = code;
+    }
+}
@@ -0,0 +1,32 @@
+package com.bsd.pjcloud.thirdparty.constant.fz;
+
+import lombok.Getter;
+
+/**
+ * 商户渠道分账关系状态，编码持久化到 {@code third_mch_fz_relation.status}，不可随意修改。
+ */
+@Getter
+public enum ThirdMchFzRelationStatusEnum {
+    /** 已建立本地关系事实，等待 Quartz 下发绑定任务。 */
+    PENDING_BIND("PENDING_BIND"),
+    /** Worker 已开始调用渠道，结果不确定时允许使用相同参数重试。 */
+    BINDING("BINDING"),
+    /** 渠道已明确确认分账关系存在，可以创建需要平台抽佣的支付订单。 */
+    BOUND("BOUND"),
+    /** 渠道返回确定性失败，等待修正配置或人工重试。 */
+    BIND_FAILED("BIND_FAILED"),
+    /** 支付配置已变化，该关系不再用于新订单，但为历史订单保留渠道关系和快照。 */
+    SUPERSEDED("SUPERSEDED");
+
+    /** 数据库和内部接口使用的稳定状态编码。 */
+    private final String code;
+
+    /**
+     * 创建关系状态。
+     *
+     * @param code 持久化状态编码
+     */
+    ThirdMchFzRelationStatusEnum(String code) {
+        this.code = code;
+    }
+}
@@ -33,7 +33,7 @@ public enum ThirdPaymentTaskTypeEnum {
    AGGREGATE_SESSION("AGGREGATE_SESSION"),
    /** 历史订单码查单并在渠道确认后关闭。 */
    PAY_CLOSE("PAY_CLOSE"),
-    /** 历史聚合支付会话本地关闭。 */
+    /** 历史聚合会话收口；无渠道单时本地关闭，有渠道单时物化唯一会话补偿任务。 */
    AGGREGATE_CLOSE("AGGREGATE_CLOSE"),
    /** 对账任务预留类型。 */
    RECONCILE("RECONCILE");
@@ -21,6 +21,6 @@ public class ThirdPaymentTaskDispatchDto {
    private Integer batchSize = 100;
    /** 触发来源，固定任务由 Quartz 传入。 */
    private String triggerSource = "QUARTZ";
-    /** Quartz 触发时间。 */
+    /** Quartz 原始触发时间，仅用于调用链诊断；thirdparty 必须使用自身接收时间计算数据库租约。 */
    private LocalDateTime triggerTime;
 }
@@ -0,0 +1,87 @@
+package com.bsd.pjcloud.thirdparty.entity.pay;
+
+import com.baomidou.mybatisplus.annotation.FieldFill;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableLogic;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baomidou.mybatisplus.extension.activerecord.Model;
+import com.bsd.pjcloud.common.core.util.TenantTable;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import java.time.LocalDateTime;
+
+/**
+ * 商户第三方支付分账关系事实，一条记录描述一个 {@code mch_manage} 在一个渠道下的平台分佣接收方。
+ */
+@Data
+@TenantTable
+@TableName("third_mch_fz_relation")
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "商户第三方支付分账关系")
+public class ThirdMchFzRelationEntity extends Model<ThirdMchFzRelationEntity> {
+    /** 关系主键，由应用侧雪花算法生成。 */
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    /** 关系所属租户ID，来源于 mch_manage，作为数据隔离和任务幂等边界。 */
+    private Long tenantId;
+    /** 对应的 mch_manage 商户主键，不跨租户解释。 */
+    private Long mchId;
+    /** 产生该关系的 mch_pay_setting 主键，用于配置变更时识别历史关系。 */
+    private Long paySettingId;
+    /** 支付平台持久化编码，10表示微信、20表示支付宝。 */
+    private String platformType;
+    /** 本地关系场景编码，本期固定为 DEFAULT_PLATFORM_COMMISSION。 */
+    private String relationScene;
+    /** 微信服务商 AppID 或支付宝平台 AppID 快照，用于区分不同平台账号。 */
+    private String channelAppId;
+    /** 微信 sub_mchid 或支付宝 smid/ip_role_id，用于绑定关系与商户支付配置对应。 */
+    private String channelSubMchId;
+    /** 支付宝命名平台账号键；默认支付宝账号及微信关系为空。 */
+    private String accountKey;
+    /** 渠道接收方类型，微信为 MERCHANT_ID，支付宝为 userId 或 loginName。 */
+    private String receiverType;
+    /** 平台分佣接收账号，发起渠道请求时使用；管理端展示必须脱敏。 */
+    private String receiverAccount;
+    /** 平台分佣接收方名称快照，渠道不要求时允许为空。 */
+    private String receiverName;
+    /** 渠道关系类型，微信默认 SERVICE_PROVIDER，支付宝关系允许为空。 */
+    private String channelRelationType;
+    /** 渠道绑定稳定幂等号；支付宝重试必须保持不变，微信用于本地审计。 */
+    private String outRequestNo;
+    /** 当前关系状态，由关系 Worker 使用原状态条件推进。 */
+    private String status;
+    /** 是否为支付配置当前默认关系，0为历史关系、1为新订单使用的默认关系。 */
+    private String isDefault;
+    /** 脱敏后的绑定请求快照，不得包含 app_auth_token、私钥或公钥。 */
+    private String bindReq;
+    /** 最近一次渠道绑定或关系查询响应快照。 */
+    private String bindRes;
+    /** 最近一次绑定错误摘要，不得包含渠道凭据。 */
+    private String bindError;
+    /** 最近一次渠道结果码或外部状态，用于监控聚合。 */
+    private String lastExternalStatus;
+    /** 最近一次调用渠道绑定或查询接口的时间。 */
+    private LocalDateTime lastQueryTime;
+    /** 渠道明确确认关系已绑定的时间。 */
+    private LocalDateTime boundTime;
+    /** 审计创建人，由 MyBatis 填充器写入。 */
+    @TableField(fill = FieldFill.INSERT)
+    private String createBy;
+    /** 本地关系事实创建时间。 */
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createTime;
+    /** 最近修改人，由 MyBatis 填充器维护。 */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private String updateBy;
+    /** 最近一次关系状态、默认标记或渠道快照更新时间。 */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updateTime;
+    /** 逻辑删除标记，0为正常、1为删除；历史关系默认保留而不物理删除。 */
+    @TableLogic
+    @TableField(fill = FieldFill.INSERT)
+    private String delFlag;
+}
@@ -18,33 +18,33 @@ import java.time.LocalDateTime;
@TableName("third_payment_task_attempt")
@EqualsAndHashCode(callSuper = true)
 public class ThirdPaymentTaskAttemptEntity extends Model<ThirdPaymentTaskAttemptEntity> {
-    /** 尝试主键。 */
+    /** 单次执行尝试主键，由应用侧雪花算法生成。 */
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;
-    /** 任务主键。 */
+    /** 所属支付任务主键，来源于 {@code third_payment_task.id}。 */
    private Long taskId;
-    /** 租户ID。 */
+    /** 尝试记录所属租户ID，复制自任务事实并参与租户数据隔离。 */
    private Long tenantId;
-    /** 任务内序号。 */
+    /** 任务内尝试序号，来源于任务成功领取后的累计次数，从一开始递增。 */
    private Integer attemptNo;
-    /** 触发来源。 */
+    /** 本次执行触发来源，例如 QUARTZ、CALLBACK、SYNC_RESPONSE 或 MANUAL。 */
    private String triggerSource;
-    /** Worker实例标识。 */
+    /** 实际执行本次尝试的 thirdparty Worker 实例标识，用于多实例故障定位。 */
    private String workerId;
-    /** 执行租约令牌。 */
+    /** 本次执行对应的租约令牌，用于关联任务 CAS 所有权；任务重领后旧令牌不再有效。 */
    private String leaseToken;
-    /** 脱敏请求快照。 */
+    /** 本次执行的脱敏请求 JSON；允许为空，禁止保存私钥、公钥、完整授权令牌或付款码。 */
    private String requestSnapshot;
-    /** 脱敏响应快照。 */
+    /** 本次执行的脱敏响应 JSON；允许为空，支付凭据及个人敏感字段必须遮蔽。 */
    private String responseSnapshot;
-    /** 外部状态。 */
+    /** 本次执行观察到的渠道或本地编排状态；调用前失败时允许为空。 */
    private String externalStatus;
-    /** 错误码。 */
+    /** 本次执行的渠道或本地错误码；成功执行时允许为空。 */
    private String errorCode;
-    /** 错误摘要。 */
+    /** 本次执行的脱敏错误摘要；成功执行时允许为空，禁止记录敏感配置原文。 */
    private String errorMessage;
-    /** 开始时间。 */
+    /** Worker 开始处理本次尝试的时间，用于计算执行耗时和定位超时租约。 */
    private LocalDateTime startedTime;
-    /** 结束时间。 */
+    /** 本次尝试写入成功、失败或重试结果的时间；Worker 中断且尚未回写时允许为空。 */
    private LocalDateTime finishedTime;
 }
@@ -18,64 +18,64 @@ import java.time.LocalDateTime;
@EqualsAndHashCode(callSuper = true)
@Schema(description = "第三方支付任务")
 public class ThirdPaymentTaskEntity extends Model<ThirdPaymentTaskEntity> {
-    /** 任务主键。 */
+    /** 任务事实主键，由应用侧雪花算法生成，不依赖数据库自增。 */
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;
-    /** 租户ID。 */
+    /** 任务所属租户ID，来源于业务单据或当前租户上下文，也是任务领取和唯一键隔离边界。 */
    private Long tenantId;
-    /** 任务类型持久化编码。 */
+    /** 任务类型持久化编码，取值由 {@code ThirdPaymentTaskTypeEnum} 维护，创建后不得改变。 */
    private String taskType;
-    /** 租户内稳定幂等键。 */
+    /** 租户内稳定幂等键，由任务类型和原业务号组成，外部调用重试时不得重新生成。 */
    private String taskKey;
-    /** 支付订单主键。 */
+    /** 关联支付订单主键；非支付订单类任务允许为空。 */
    private Long payOrderId;
-    /** 分账订单主键。 */
+    /** 关联分账订单主键；非分账及退分账任务允许为空。 */
    private Long fzOrderId;
-    /** 聚合会话主键。 */
+    /** 关联聚合支付会话主键；非聚合支付任务允许为空。 */
    private Long aggregateSessionId;
-    /** 稳定支付单号。 */
+    /** 平台内稳定支付单号，来源于支付订单；未关联支付订单的任务允许为空。 */
    private String payNo;
-    /** 稳定退款单号。 */
+    /** 平台内稳定退款单号，来源于退款业务；非退款任务允许为空。 */
    private String refundNo;
-    /** 稳定分账单号。 */
+    /** 平台内稳定分账单号，来源于分账订单；非分账任务允许为空。 */
    private String fzNo;
-    /** 稳定聚合会话号。 */
+    /** 聚合支付会话稳定业务号，来源于聚合会话；非聚合支付任务允许为空。 */
    private String aggregateNo;
-    /** 当前任务状态。 */
+    /** 当前任务状态持久化编码，由任务状态机通过 CAS 更新，禁止外部直接跳转终态。 */
    private String status;
-    /** 下一次可执行时间。 */
+    /** 下一次允许领取的数据库时间；READY/RETRY 到期后才可由 Quartz 分发触发领取。 */
    private LocalDateTime nextRunTime;
-    /** 优先级，越大越优先。 */
+    /** 同批到期任务的领取优先级，数值越大越先领取。 */
    private Integer priority;
-    /** Worker实例标识。 */
+    /** 当前租约持有的 thirdparty Worker 实例标识；未领取或任务终态时为空。 */
    private String leaseOwner;
-    /** 当前租约令牌。 */
+    /** 当前执行租约的随机令牌，完成更新必须匹配该值，未领取或任务终态时为空。 */
    private String leaseToken;
-    /** 租约到期时间。 */
+    /** 当前执行租约到期时间；只约束 Worker 所有权，不代表外部渠道业务超时。 */
    private LocalDateTime leaseExpireTime;
-    /** 累计尝试次数。 */
+    /** 任务累计领取尝试次数，每次 CAS 领取成功后递增，初始值为零。 */
    private Integer attemptCount;
-    /** 最近外部渠道状态。 */
+    /** 最近一次执行观察到的支付宝、微信或本地编排状态；尚未执行时允许为空。 */
    private String lastExternalStatus;
-    /** 最近错误码。 */
+    /** 最近一次失败的渠道或本地错误码；最近执行成功或尚无错误时允许为空。 */
    private String lastErrorCode;
-    /** 最近错误摘要。 */
+    /** 最近一次失败的脱敏错误摘要，不得包含密钥、完整授权令牌或付款码。 */
    private String lastErrorMessage;
-    /** 任务终态时间。 */
+    /** 进入 SUCCESS、FAILED、ALERT 或 CANCELLED 等终态的时间；处理中任务为空。 */
    private LocalDateTime finishedTime;
-    /** 创建人。 */
+    /** 审计创建人，由 MyBatis 填充器写入；系统任务允许为空或使用系统身份。 */
    @TableField(fill = FieldFill.INSERT)
    private String createBy;
-    /** 创建时间。 */
+    /** 任务事实创建时间，由应用显式写入或 MyBatis 填充器补齐。 */
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
-    /** 修改人。 */
+    /** 最近修改人，由 MyBatis 填充器维护；系统任务允许为空或使用系统身份。 */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private String updateBy;
-    /** 修改时间。 */
+    /** 最近一次任务状态、租约或诊断信息变更时间。 */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
-    /** 逻辑删除标记。 */
+    /** 逻辑删除标记，沿用项目通用 {@code 0/1} 约定；任务状态机不得物理删除任务事实。 */
    @TableLogic
    @TableField(fill = FieldFill.INSERT)
    private String delFlag;
@@ -13,7 +13,7 @@ public class ThirdPaymentTaskDispatchVo {
    private int acceptedCount;
    /** 成功取得租约的任务数。 */
    private int claimedCount;
-    /** 当前 Worker 正在执行数量。 */
+    /** 当前 thirdparty 实例正在执行及已进入有界队列的任务数量。 */
    private int processingCount;
    /** 队列是否达到容量上限。 */
    private boolean busy;