csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d24e777a4cce077db2925560344945a83cd009b7
junhong_cmp_fiber/internal/model/dto/employee_collection_dto.go
break 5ed6b39deb
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Has been cancelled
Details
feat(收口): 补齐 8 月迭代缺口并同步 Spec 与证据链 
- 新增六对成对迁移 000232–000237：H5 弹窗类型、退款结算标识与申请人备注、优先轮询事实字段与两个新终态、通道阈值命中留痕、手机号最近解绑人、提现资格校验留痕
- 退款：原因必填与申请人备注、来源支付与渠道流水冻结、线下处理流水号补录审计、按订单查询可选退款方式、企微审批材料补齐且新增字段缺失映射即明确失败
- 优先轮询：人工关闭、有效期到期独立周期任务、失败与过期人工重触发、事实字段与异常重试查询、资产解析端点只读投影
- 通道阈值：命中事实同事务留痕与命中记录查询；员工账单：列表筛选与详情投影；商户池：列表投影与统计周期语义；H5：弹窗类型与类别排序
- 手机号：有效关联数量与最近解绑人、短信验证码失败次数限制；导出：佣金明细十五列与报表序号列
- 时间筛选：三处新增筛选纳入统一严格解析契约，员工账单产生时间参数改名
- 同步 12 份主 Spec 需求、两端点与异步任务证据链，门禁 context-health 与 OpenSpec 校验通过
2026-09-18 15:34:29 +08:00

344 lines
34 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package dto
import "time"
// CreateEmployeeCollectionPaymentMethodRequest 创建线下收款方式请求
// 枚举说明：enabled 对应 constants.EmployeeCollectionPaymentMethodStatusEnabled/Disabled（1 启用、0 停用）。
type CreateEmployeeCollectionPaymentMethodRequest struct {
Code string `json:"code" validate:"required,min=1,max=64" required:"true" minLength:"1" maxLength:"64" description:"收款方式稳定编码，1-64 字符，未删除记录中唯一，被核销申请引用后不可修改"`
Name string `json:"name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"收款方式名称，1-100 字符"`
Sort *int64 `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值，非负整数，默认 0"`
Enabled *bool `json:"enabled" description:"是否启用，默认启用；停用后新核销申请不可选择该方式"`
Remark string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注，最多 500 字符"`
}
// UpdateEmployeeCollectionPaymentMethodRequest 更新线下收款方式请求
// 全部字段可选：仅传入的字段被修改；已启用即被核销申请引用的记录不允许修改稳定编码。
type UpdateEmployeeCollectionPaymentMethodRequest struct {
Code *string `json:"code" validate:"omitempty,min=1,max=64" minLength:"1" maxLength:"64" description:"收款方式稳定编码，仅未被核销申请引用时可修改"`
Name *string `json:"name" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"收款方式名称"`
Sort *int64 `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值，非负整数"`
Enabled *bool `json:"enabled" description:"是否启用；停用后新核销申请不可选择该方式，历史申请仍展示冻结名称"`
Remark *string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注，最多 500 字符"`
}
// EmployeeCollectionPaymentMethodListRequest 查询线下收款方式列表请求
type EmployeeCollectionPaymentMethodListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
Enabled *bool `json:"enabled" query:"enabled" description:"按启用状态过滤；超级管理员可查询全部，其他后台账号仅返回启用项"`
Keyword string `json:"keyword" query:"keyword" validate:"omitempty,max=100" maxLength:"100" description:"按稳定编码或名称模糊搜索，最多 100 字符"`
}
// EmployeeCollectionPaymentMethodResponse 线下收款方式响应
// 对外契约字段固定为 id/code/name/enabled，其余字段为维护与展示补充。
type EmployeeCollectionPaymentMethodResponse struct {
ID uint `json:"id" description:"收款方式ID"`
Code string `json:"code" description:"收款方式稳定编码"`
Name string `json:"name" description:"收款方式名称"`
Enabled bool `json:"enabled" description:"是否启用；停用后新核销申请不可选择该方式"`
Sort int64 `json:"sort" description:"排序值"`
Remark string `json:"remark" description:"备注"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// EmployeeCollectionPaymentMethodListResponse 线下收款方式列表响应
type EmployeeCollectionPaymentMethodListResponse struct {
List []*EmployeeCollectionPaymentMethodResponse `json:"items" description:"收款方式列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页码"`
PageSize int `json:"size" description:"每页条数"`
}
// EmployeeCollectionBillListRequest 查询员工代收款账单列表请求。
// 枚举说明：source_type 对应 constants.EmployeeCollectionSourceTypeOrder/Recharge，
// status 对应 constants.EmployeeCollectionBillStatusPending/Partial/Settled/Closed。
type EmployeeCollectionBillListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
BillID *uint `json:"bill_id" query:"bill_id" validate:"omitempty,min=1" minimum:"1" description:"按账单编号精确过滤；账单编号即账单记录标识（主键ID）"`
SourceType *string `json:"source_type" query:"source_type" validate:"omitempty,oneof=order recharge" enum:"order,recharge" description:"按来源类型过滤 (order:后台线下套餐订单, recharge:代理线下充值)"`
SourceNo *string `json:"source_no" query:"source_no" validate:"omitempty,max=64" maxLength:"64" description:"按来源单号精确过滤"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按账单状态过滤 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
DebtorAccountID *uint `json:"debtor_account_id" query:"debtor_account_id" description:"按欠款人后台账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
DebtorKeyword *string `json:"debtor_keyword" query:"debtor_keyword" validate:"omitempty,max=50" maxLength:"50" description:"按欠款人姓名或账号模糊过滤，取去空白后的子串匹配，最多 50 字符；无需先取得账号ID"`
CustomerKeyword *string `json:"customer_keyword" query:"customer_keyword" validate:"omitempty,max=50" maxLength:"50" description:"按客户名称模糊过滤，取去空白后的子串匹配，最多 50 字符；无需先取得客户ID"`
CustomerID *uint `json:"customer_id" query:"customer_id" description:"按来源客户或店铺ID过滤，匹配来源订单买家或充值归属店铺"`
StartTime *string `json:"start_time" query:"start_time" description:"账单产生时间起始，必须是带显式时区的 RFC3339 秒级时间（如 2026-09-01T00:00:00+08:00），闭区间含该时刻"`
EndTime *string `json:"end_time" query:"end_time" description:"账单产生时间截止，必须是带显式时区的 RFC3339 秒级时间，闭区间含该时刻"`
DecidedStartTime *string `json:"decided_start_time" query:"decided_start_time" description:"核销通过时间起始，取该账单已通过分摊关联的申请表审批终态时间；格式与 start_time 相同，闭区间含该时刻"`
DecidedEndTime *string `json:"decided_end_time" query:"decided_end_time" description:"核销通过时间截止，取该账单已通过分摊关联的申请表审批终态时间；格式与 end_time 相同，闭区间含该时刻"`
}
// EmployeeCollectionBillStatisticsRequest 查询员工代收款账单统计请求。
// 与账单列表使用同一批筛选字段与可见性范围，但不接受分页参数。
type EmployeeCollectionBillStatisticsRequest struct {
BillID *uint `json:"bill_id" query:"bill_id" validate:"omitempty,min=1" minimum:"1" description:"按账单编号精确过滤；账单编号即账单记录标识（主键ID）"`
SourceType *string `json:"source_type" query:"source_type" validate:"omitempty,oneof=order recharge" enum:"order,recharge" description:"按来源类型过滤 (order:后台线下套餐订单, recharge:代理线下充值)"`
SourceNo *string `json:"source_no" query:"source_no" validate:"omitempty,max=64" maxLength:"64" description:"按来源单号精确过滤"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按账单状态过滤 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
DebtorAccountID *uint `json:"debtor_account_id" query:"debtor_account_id" description:"按欠款人后台账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
DebtorKeyword *string `json:"debtor_keyword" query:"debtor_keyword" validate:"omitempty,max=50" maxLength:"50" description:"按欠款人姓名或账号模糊过滤，取去空白后的子串匹配，最多 50 字符；无需先取得账号ID"`
CustomerKeyword *string `json:"customer_keyword" query:"customer_keyword" validate:"omitempty,max=50" maxLength:"50" description:"按客户名称模糊过滤，取去空白后的子串匹配，最多 50 字符；无需先取得客户ID"`
CustomerID *uint `json:"customer_id" query:"customer_id" description:"按来源客户或店铺ID过滤，匹配来源订单买家或充值归属店铺"`
StartTime *string `json:"start_time" query:"start_time" description:"账单产生时间起始，必须是带显式时区的 RFC3339 秒级时间（如 2026-09-01T00:00:00+08:00），闭区间含该时刻"`
EndTime *string `json:"end_time" query:"end_time" description:"账单产生时间截止，必须是带显式时区的 RFC3339 秒级时间，闭区间含该时刻"`
DecidedStartTime *string `json:"decided_start_time" query:"decided_start_time" description:"核销通过时间起始，取该账单已通过分摊关联的申请表审批终态时间；格式与 start_time 相同，闭区间含该时刻"`
DecidedEndTime *string `json:"decided_end_time" query:"decided_end_time" description:"核销通过时间截止，取该账单已通过分摊关联的申请表审批终态时间；格式与 end_time 相同，闭区间含该时刻"`
}
// EmployeeCollectionBillResponse 员工代收款账单行响应。
type EmployeeCollectionBillResponse struct {
ID uint `json:"id" description:"账单ID"`
SourceType string `json:"source_type" description:"来源类型 (order:后台线下套餐订单, recharge:代理线下充值)"`
SourceTypeName string `json:"source_type_name" description:"来源类型中文名称"`
SourceID uint `json:"source_id" description:"来源业务主键ID"`
SourceNo string `json:"source_no" description:"来源单号"`
DebtorAccountID uint `json:"debtor_account_id" description:"欠款人后台账号ID"`
DebtorSnapshot map[string]any `json:"debtor_snapshot" description:"欠款人账号只读快照（账号ID、名称、类型）"`
CustomerSnapshot map[string]any `json:"customer_snapshot" description:"来源客户或店铺只读快照，不含付款凭证内容"`
ReceivableAmount int64 `json:"receivable_amount" description:"应收金额（分）"`
ReceivedAmount int64 `json:"received_amount" description:"已核销金额（分），仅企业微信最终通过的分摊计入"`
UnsettledAmount int64 `json:"unsettled_amount" description:"未核销金额（分），应收金额减已核销金额；已关闭账单为 0"`
ReservedAmount int64 `json:"reserved_amount" description:"审批中预占金额（分）"`
RemainingAmount int64 `json:"remaining_amount" description:"剩余可核销金额（分），已关闭账单为 0"`
Status int `json:"status" description:"账单状态 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
StatusName string `json:"status_name" description:"账单状态中文名称"`
ApprovalPending bool `json:"approval_pending" description:"是否存在审批中分摊（预占大于零）"`
ClosedReason string `json:"closed_reason" description:"关闭原因，仅已关闭账单有值"`
ClosedAt *time.Time `json:"closed_at,omitempty" description:"关闭时间"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
UpdatedAt time.Time `json:"updated_at" description:"最近更新时间"`
}
// EmployeeCollectionBillListResponse 员工代收款账单列表响应。
type EmployeeCollectionBillListResponse struct {
List []*EmployeeCollectionBillResponse `json:"items" description:"账单列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页码"`
PageSize int `json:"size" description:"每页条数"`
}
// EmployeeCollectionBillStatisticsResponse 员工代收款账单统计响应。
// 与账单列表使用同一筛选条件与可见性范围。
type EmployeeCollectionBillStatisticsResponse struct {
ReceivableTotal int64 `json:"receivable_total" description:"应收金额合计（分）"`
ReceivedTotal int64 `json:"received_total" description:"已核销金额合计（分）"`
UnsettledTotal int64 `json:"unsettled_total" description:"未核销金额合计（分），已关闭账单未核销余额按 0 计入"`
PendingBillCount int64 `json:"pending_bill_count" description:"待处理账单数，即待核销或部分核销账单数量"`
}
// EmployeeCollectionBillRefundResponse 账单退款冲销关联响应。
type EmployeeCollectionBillRefundResponse struct {
ID uint `json:"id" description:"冲销关联ID"`
RefundID uint `json:"refund_id" description:"退款申请ID"`
SourceOrderID uint `json:"source_order_id" description:"账单来源订单ID"`
RefundAmount int64 `json:"refund_amount" description:"本次退款成功金额（分）"`
BillReceivableAmount int64 `json:"bill_receivable_amount" description:"冲销前账单应收金额快照（分）"`
Outcome string `json:"outcome" description:"处理结果 (closed_full:来源订单全额退款关闭, reduced:按退款金额冲减应收, hint_only:仅记录退款关联提示)"`
OutcomeName string `json:"outcome_name" description:"处理结果中文名称"`
ReducedAmount int64 `json:"reduced_amount" description:"实际冲减应收金额（分）"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// EmployeeCollectionBillAllocationResponse 账单分摊响应。
type EmployeeCollectionBillAllocationResponse struct {
ID uint `json:"id" description:"分摊ID"`
ApplicationID uint `json:"application_id" description:"核销申请ID"`
ApplicationStatus int `json:"application_status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
ApplicationStatusName string `json:"application_status_name" description:"申请状态中文名称"`
AttemptID uint `json:"attempt_id" description:"所属审批尝试记录ID"`
Amount int64 `json:"amount" description:"本次分摊金额（分）"`
Status int `json:"status" description:"分摊状态 (0:审批中预占, 1:已通过, 2:已驳回或已释放)"`
StatusName string `json:"status_name" description:"分摊状态中文名称"`
ReleasedAt *time.Time `json:"released_at,omitempty" description:"预占释放时间，审批中为空"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// EmployeeCollectionBillAttemptResponse 申请审批尝试记录响应，材料为本次提交的冻结快照。
type EmployeeCollectionBillAttemptResponse struct {
ID uint `json:"id" description:"审批尝试记录ID，同时是通用审批业务ID"`
AttemptNo int `json:"attempt_no" description:"第几次提交，从 1 递增"`
PaymentMethodID uint `json:"payment_method_id" description:"本次冻结的收款方式字典ID"`
PaymentMethodCode string `json:"payment_method_code" description:"本次冻结的收款方式稳定编码"`
PaymentMethodName string `json:"payment_method_name" description:"本次冻结的收款方式名称"`
PaidAmount int64 `json:"paid_amount" description:"本次冻结的付款金额（分）"`
PayerName string `json:"payer_name" description:"付款方名称"`
PaidAt time.Time `json:"paid_at" description:"付款时间"`
ExternalTransactionNo string `json:"external_transaction_no" description:"人工确认的外部交易流水号，申请人可原样核对与重用"`
PaymentVoucherKeys []string `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
Remark string `json:"remark" description:"本次提交备注"`
SubmittedByAccountID uint `json:"submitted_by_account_id" description:"本次实际提交账号ID，代办时为超级管理员"`
ActingReason string `json:"acting_reason" description:"本次代办原因，非代办为空"`
AllocationSnapshot []map[string]any `json:"allocation_snapshot" description:"本次冻结的账单分摊快照"`
ApprovalInstanceID *uint `json:"approval_instance_id,omitempty" description:"本次尝试关联的通用审批实例ID"`
ApprovalStatus *int `json:"approval_status,omitempty" description:"通用审批实例状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
ApprovalStatusName string `json:"approval_status_name" description:"通用审批实例状态中文名称"`
ApprovalOpinion string `json:"approval_opinion" description:"渠道审批意见文本，取自通用审批实例终态决策快照；无意见时为空"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// EmployeeCollectionBillApplicationResponse 账单关联的核销申请响应，含审批历史。
type EmployeeCollectionBillApplicationResponse struct {
ID uint `json:"id" description:"核销申请ID"`
ApplicantAccountID uint `json:"applicant_account_id" description:"申请人后台账号ID"`
ActingOperatorID uint `json:"acting_operator_id" description:"实际代办的超级管理员账号ID，0 表示本人办理"`
ActingReason string `json:"acting_reason" description:"代办原因，非代办为空"`
PaymentMethodID uint `json:"payment_method_id" description:"线下收款方式字典ID"`
PaymentMethodCode string `json:"payment_method_code" description:"收款方式稳定编码快照"`
PaymentMethodName string `json:"payment_method_name" description:"收款方式名称快照"`
PaidAmount int64 `json:"paid_amount" description:"人工确认的付款金额（分）"`
PayerName string `json:"payer_name" description:"付款方名称"`
PaidAt time.Time `json:"paid_at" description:"付款时间"`
ExternalTransactionNo string `json:"external_transaction_no" description:"外部交易流水号"`
PaymentVoucherKeys []string `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
Remark string `json:"remark" description:"申请备注"`
Status int `json:"status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
StatusName string `json:"status_name" description:"申请状态中文名称"`
LatestApprovalInstanceID uint `json:"latest_approval_instance_id" description:"最新通用审批实例ID，仅用于展示"`
DecidedAt *time.Time `json:"decided_at,omitempty" description:"审批终态到达时间"`
TerminalReason string `json:"terminal_reason" description:"异常终态说明，如企业微信通过后撤销"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
Attempts []*EmployeeCollectionBillAttemptResponse `json:"attempts" description:"该申请的审批尝试记录，按提交顺序排列"`
}
// EmployeeCollectionBillDetailResponse 员工代收款账单详情响应。
type EmployeeCollectionBillDetailResponse struct {
Bill *EmployeeCollectionBillResponse `json:"bill" description:"账单事实"`
Refunds []*EmployeeCollectionBillRefundResponse `json:"refunds" description:"来源订单退款冲销关联"`
Allocations []*EmployeeCollectionBillAllocationResponse `json:"allocations" description:"该账单的核销分摊"`
Applications []*EmployeeCollectionBillApplicationResponse `json:"applications" description:"涉及该账单的核销申请与审批历史"`
Operations []*EmployeeCollectionBillOperationLogResponse `json:"operations" description:"该账单的操作日志投影，按操作时间升序；仅含安全摘要，不含凭证内容与完整收款原文"`
SourceOrder *EmployeeCollectionBillSourceSnapshotResponse `json:"source_order" description:"来源订单或来源充值记录的只读快照；来源不可读或字段缺失时对应字段为空值，不影响详情其余内容"`
}
// EmployeeCollectionBillOperationLogResponse 是账单维度既有审计事实的安全投影。
// 只返回动作、操作账号名称快照、操作时间与变更前后摘要（白名单字段），
// MUST NOT 返回支付凭证内容、完整收款信息或其它敏感原文。
type EmployeeCollectionBillOperationLogResponse struct {
ActionCode string `json:"action_code" description:"稳定动作编码"`
ActionName string `json:"action_name" description:"动作中文名称"`
Summary string `json:"summary" description:"事件中文摘要"`
OperatorName string `json:"operator_name" description:"操作账号名称快照"`
OccurredAt time.Time `json:"occurred_at" description:"操作发生时间"`
Result string `json:"result" description:"操作结果 (success:成功, failed:失败, denied:拒绝, partial:部分成功, unknown:未知)"`
BeforeSummary map[string]any `json:"before_summary" description:"变更前安全摘要，只包含允许展示的账单字段"`
AfterSummary map[string]any `json:"after_summary" description:"变更后安全摘要，只包含允许展示的账单字段"`
}
// EmployeeCollectionBillSourceSnapshotResponse 是来源订单或来源充值记录的只读快照投影。
// 来源记录已不可读或字段缺失时对应字段为空值，详情其余内容正常返回。
type EmployeeCollectionBillSourceSnapshotResponse struct {
SourceType string `json:"source_type" description:"来源业务类型 (order:后台线下套餐订单, recharge:代理线下充值)"`
SourceTypeName string `json:"source_type_name" description:"来源业务类型中文名称"`
SourceNo string `json:"source_no" description:"来源单号"`
Amount int64 `json:"amount" description:"来源实收金额或充值金额（分）"`
CreatedAt *time.Time `json:"created_at,omitempty" description:"来源记录创建时间"`
AssetIdentifier string `json:"asset_identifier" description:"来源资产标识（卡为ICCID，设备优先虚拟号其次IMEI）；来源无资产维度或不可读时为空"`
}
// CloseEmployeeCollectionBillRequest 关闭员工代收款账单请求
type CloseEmployeeCollectionBillRequest struct {
Reason string `json:"reason" validate:"required,min=1,max=500" required:"true" minLength:"1" maxLength:"500" description:"关闭原因，必填，最多 500 字符"`
}
// EmployeeCollectionApplicationAllocationRequest 核销申请中的单张账单分摊。
type EmployeeCollectionApplicationAllocationRequest struct {
BillID uint `json:"bill_id" validate:"required" required:"true" description:"目标员工代收款账单ID"`
Amount int64 `json:"amount" validate:"required,min=1" required:"true" minimum:"1" description:"本次分摊金额（分），必须大于零且不超过该账单可核销余额"`
}
// SubmitEmployeeCollectionApplicationRequest 创建或重提核销申请请求。
// 枚举说明：allocations 由申请人提交，服务端按账单可核销余额与付款金额严格校验。
type SubmitEmployeeCollectionApplicationRequest struct {
PaymentMethodID uint `json:"payment_method_id" validate:"required" required:"true" description:"线下收款方式字典ID，必须是启用中的字典项"`
PaidAmount int64 `json:"paid_amount" validate:"required,min=1" required:"true" minimum:"1" description:"人工确认的付款金额（分），必须大于零"`
PayerName string `json:"payer_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"付款方名称，1-100 字符"`
PaidAt string `json:"paid_at" validate:"required" required:"true" description:"付款时间，带时区的 RFC3339 格式，如 2026-08-31T10:00:00+08:00"`
ExternalTransactionNo string `json:"external_transaction_no" validate:"required,min=1,max=128" required:"true" minLength:"1" maxLength:"128" description:"经人工确认的外部交易流水号，OCR 结果必须人工更正后提交"`
PaymentVoucherKeys []string `json:"payment_voucher_keys" validate:"required,min=1,max=5,dive,min=1,max=512" required:"true" minItems:"1" maxItems:"5" description:"支付凭证对象存储Key列表，1-5 个既有对象键引用"`
Remark string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"申请备注，最多 500 字符"`
ActingReason string `json:"acting_reason" validate:"omitempty,max=500" maxLength:"500" description:"超级管理员代办原因，1-500 字符；代办时必填，本人办理不得填写"`
Allocations []EmployeeCollectionApplicationAllocationRequest `json:"allocations" validate:"required,min=1,max=50,dive" required:"true" minItems:"1" maxItems:"50" description:"账单分摊列表，至少一条；每张账单本次只能出现一次"`
}
// EmployeeCollectionApplicationListRequest 查询核销申请列表请求。
type EmployeeCollectionApplicationListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按申请状态过滤 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
ApplicantAccountID *uint `json:"applicant_account_id" query:"applicant_account_id" description:"按申请人账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
PaymentMethodID *uint `json:"payment_method_id" query:"payment_method_id" description:"按线下收款方式字典ID过滤"`
CreatedFrom *string `json:"created_from" query:"created_from" description:"创建时间起始（YYYY-MM-DD，含当日 00:00:00）"`
CreatedTo *string `json:"created_to" query:"created_to" description:"创建时间截止（YYYY-MM-DD，含当日 23:59:59）"`
}
// EmployeeCollectionApplicationResponse 核销申请行响应。
type EmployeeCollectionApplicationResponse struct {
ID uint `json:"id" description:"核销申请ID"`
ApplicantAccountID uint `json:"applicant_account_id" description:"申请人后台账号ID"`
ActingOperatorID uint `json:"acting_operator_id" description:"实际代办的超级管理员账号ID，0 表示本人办理"`
ActingReason string `json:"acting_reason" description:"代办原因，非代办为空"`
PaymentMethodID uint `json:"payment_method_id" description:"线下收款方式字典ID"`
PaymentMethodCode string `json:"payment_method_code" description:"收款方式稳定编码快照"`
PaymentMethodName string `json:"payment_method_name" description:"收款方式名称快照，字典改名不影响历史申请"`
PaidAmount int64 `json:"paid_amount" description:"人工确认的付款金额（分）"`
PayerName string `json:"payer_name" description:"付款方名称"`
PaidAt time.Time `json:"paid_at" description:"付款时间"`
ExternalTransactionNo string `json:"external_transaction_no" description:"人工确认的外部交易流水号，申请人可原样核对与重用"`
PaymentVoucherKeys []string `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
Remark string `json:"remark" description:"申请备注"`
Status int `json:"status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
StatusName string `json:"status_name" description:"申请状态中文名称"`
LatestAttemptID uint `json:"latest_attempt_id" description:"最新审批尝试记录ID，仅用于展示"`
LatestApprovalInstanceID uint `json:"latest_approval_instance_id" description:"最新通用审批实例ID，仅用于展示"`
DecidedAt *time.Time `json:"decided_at,omitempty" description:"审批终态到达时间"`
TerminalReason string `json:"terminal_reason" description:"异常终态说明，如企业微信通过后撤销"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
UpdatedAt time.Time `json:"updated_at" description:"最近更新时间"`
}
// EmployeeCollectionApplicationListResponse 核销申请列表响应。
type EmployeeCollectionApplicationListResponse struct {
List []*EmployeeCollectionApplicationResponse `json:"items" description:"核销申请列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页码"`
PageSize int `json:"size" description:"每页条数"`
}
// EmployeeCollectionApplicationAllocationResponse 核销申请分摊响应，含目标账单只读摘要。
type EmployeeCollectionApplicationAllocationResponse struct {
ID uint `json:"id" description:"分摊ID"`
BillID uint `json:"bill_id" description:"目标账单ID"`
Amount int64 `json:"amount" description:"本次分摊金额（分）"`
Status int `json:"status" description:"分摊状态 (0:审批中预占, 1:已通过, 2:已驳回或已释放)"`
StatusName string `json:"status_name" description:"分摊状态中文名称"`
ReleasedAt *time.Time `json:"released_at,omitempty" description:"预占释放时间，审批中为空"`
BillSourceType string `json:"bill_source_type" description:"账单来源类型 (order:后台线下套餐订单, recharge:代理线下充值)"`
BillSourceNo string `json:"bill_source_no" description:"账单来源单号"`
BillReceivableAmount int64 `json:"bill_receivable_amount" description:"账单应收金额（分）"`
BillReceivedAmount int64 `json:"bill_received_amount" description:"账单已核销金额（分）"`
BillReservedAmount int64 `json:"bill_reserved_amount" description:"账单审批中预占金额（分）"`
BillStatus int `json:"bill_status" description:"账单状态 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
BillStatusName string `json:"bill_status_name" description:"账单状态中文名称"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// EmployeeCollectionApplicationSubmitResponse 创建或重提核销申请响应。
type EmployeeCollectionApplicationSubmitResponse struct {
Application *EmployeeCollectionApplicationResponse `json:"application" description:"核销申请事实"`
Attempt *EmployeeCollectionBillAttemptResponse `json:"attempt" description:"本次新增的审批尝试记录与冻结快照"`
Allocations []*EmployeeCollectionApplicationAllocationResponse `json:"allocations" description:"本次账单分摊与预占结果"`
ApprovalInstanceID uint `json:"approval_instance_id" description:"本次创建的企业微信通用审批实例ID"`
ApprovalStatus int `json:"approval_status" description:"通用审批实例状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
ApprovalStatusName string `json:"approval_status_name" description:"通用审批实例状态中文名称"`
}
// EmployeeCollectionApplicationDetailResponse 核销申请详情响应。
type EmployeeCollectionApplicationDetailResponse struct {
Application *EmployeeCollectionApplicationResponse `json:"application" description:"核销申请事实与最新审批引用"`
Allocations []*EmployeeCollectionApplicationAllocationResponse `json:"allocations" description:"该申请当前的账单分摊"`
Attempts []*EmployeeCollectionBillAttemptResponse `json:"attempts" description:"全部审批尝试记录，按提交顺序排列，历史材料不被覆盖"`
}
Reference in New Issue View Git Blame Copy Permalink