19 KiB
领域术语表
资产（Asset）
IoT 卡 / IotCard：物联网流量卡，以 ICCID 为唯一标识。分为独立卡（is_standalone=true，未绑定设备）和设备卡（绑定在设备上）。
设备 / Device：硬件设备，以虚拟号（VirtualNo）为业务标识，可插卡使用。
资产世代 / Generation：generation 字段记录卡/设备经历"换货+旧资产转新"操作的次数。初始值为 1；每完成一次换货且旧资产执行"转新"后加 1。generation > 1 说明该资产曾作为旧资产经历过换货并被重新投入使用。
资产业务状态 / AssetStatus：asset_status 字段表示资产在 CMP 内部的业务生命周期（1=在库, 2=已销售, 3=已换货, 4=已停用）。换货完成时旧资产置为 3；执行"旧资产转新"后重置为 1，同时 generation+1。
企业授权（Enterprise Authorization）
卡企业授权：将独立卡授权给企业使用的操作。业务约束：一张卡在同一时间只能授权给一个企业（与设备授权保持一致，数据库通过部分唯一索引强制约束）。
有效授权：revoked_at IS NULL AND deleted_at IS NULL 的授权记录。撤回授权后（revoked_at 有值）视为历史记录，不计入当前授权关系。
设备企业授权：将设备（含其绑定卡）授权给企业使用的操作。同一台设备同一时间只能授权给一个企业（uq_active_device_auth 唯一约束）。
代理资金（Agent Funds）
代理主钱包 / Agent Main Wallet：代理店铺承担订单结算和债务的唯一钱包；信用额度只属于该钱包，不属于角色、平台员工、佣金钱包或资产钱包。
信用额度 / Credit Limit：平台授予某个代理主钱包、允许其现金不足时继续使用的最高资金边界。额度本身不是余额，也不是一笔充值。
角色默认信用模板 / Role Default Credit Template：客户角色为未来新建代理提供的信用开关和额度默认值；创建主钱包时复制一次，之后与该钱包实际信用额度相互独立。
现金可用金额 / Cash Available Amount：代理主钱包的账面余额减冻结金额，不包含信用额度。
总可用金额 / Total Available Amount：现金可用金额加当前启用的信用额度，是主钱包扣款和冻结可否执行的资金边界。
欠款 / Debt：代理主钱包账面余额低于零的部分；冻结信用不直接形成欠款。
代理自主在线充值 / Agent Self-service Online Recharge：代理只能为当前登录账号所属店铺的主钱包发起在线充值，请求不接受目标 shop_id；代理选择支付方式 wechat 或 alipay，无需审批。平台、超级管理员和企业账号不能用该路径替代理创建在线支付二维码。
代理充值金额边界 / Agent Recharge Amount Boundary：代理在线扫码充值金额为 10000～100000000 分（100 元至 100 万元）；平台或超级管理员线下代充值保持现有 1～100000000 分，即金额必须大于 0 且最高 100 万元。两条路径使用各自的金额校验，不能把在线起付金额套在线下代充值上。
平台线下代充值 / Platform Offline Recharge：平台或超级管理员为指定代理店铺主钱包发起的 offline 充值，必须明确目标 shop_id 并进入企业微信审批；代理和企业账号不能发起该路径。
线下代充值申请资料 / Offline Recharge Application Materials：平台或超级管理员创建线下代充值时，目标 shop_id 和充值金额必填；付款凭证必传 1～5 个，每项提交本地对象存储的 file_key、原始 file_name 和 file_size；备注选填且最多 500 字。充值金额在创建时固定，企微审批人只能同意或拒绝，不能修改金额。
线下代充值驳回终结 / Offline Recharge Rejection Finalization：企微拒绝后，原线下充值单以 6=已驳回终结，原申请资料、审批结果和拒绝原因保留用于审计。系统不提供退回修改、7=已退回或原单重新提交；修正金额、凭证或备注后仍需充值时，必须创建新的充值单和企微审批。
线下代充值审批撤销 / Offline Recharge Approval Cancellation：企微在通过前撤销或删除时，充值单改为 4=已关闭且不入账，可以重新创建；企微通过后、钱包尚未入账时发生撤销，终止入账并关闭充值单；钱包已经入账后再收到撤销时不自动扣减代理余额，充值单保持已完成，同时记录严重 Audit Event 并通知财务人工处理。
线下代充值停机迁移 / Offline Recharge Cutover Migration：停机发布时，历史已完成、已关闭、已退款和已驳回的线下充值只读保留，不补企微审批。仍待处理的线下充值仅在真实提交人平台账号已绑定企微且申请资料完整时创建真实企微审批继续处理；其余记录进入明确的迁移异常清单，不自动入账，也不能再通过旧 offline-pay 处理。
代理充值支付配置 / Agent Recharge Payment Configuration：代理只选择支付方式 wechat 或 alipay，前端不提交、不选择支付通道。后端分别使用当前配置好的微信或支付宝支付参数创建支付单；本期不建设多通道池、优先级、自动切换或故障转移。支付单仍需固化创建时使用的支付配置，以便后续查询、回调验签和对账使用原配置。
代理充值可用支付方式 / Available Agent Recharge Payment Methods：GET /api/admin/agent-recharges/payment-methods 只返回配置完整且当前能够创建支付的 wechat 和/或 alipay，不向前端暴露商户号、支付通道或敏感配置诊断。创建充值时必须再次校验所选方式；配置在列表查询后失效时直接拒绝创建。
代理充值付款码内容 / Agent Recharge QR Content：微信或支付宝预下单返回的字符串或 HTTPS URL 由后端通过 qr_content 原样交给前端，前端自行渲染二维码；后端不生成二维码图片，也不提供独立的二维码生成接口。创建接口不返回 expires_at，前端不展示精确倒计时；用户重新拉起支付时创建全新的充值单和支付单，不复用原单。
代理充值第三方失效 / Agent Recharge Third-party Expiration：本地计算时间不能代表微信或支付宝订单的真实有效期，也不能据此直接关闭业务单。第三方查单确认订单未支付且已经关闭或失效后，不新增支付单状态码，现有 tb_payment 使用 2=已失败并记录第三方失效原因，对应充值单使用 4=已关闭。用户后续重新创建新充值单和新支付单。
代理充值迟到成功回调 / Late Successful Recharge Callback：本地因付款码过期而标记失败或关闭后，若收到微信或支付宝的有效成功回调，并完成第三方交易号、金额、创建时支付配置及业务关联核验，则以支付平台真实收款事实为准，将支付单恢复为已支付并对原充值单执行幂等钱包入账，不能吞掉用户已经支付的资金。
代理充值预下单结果未知 / Unknown Recharge Pre-order Result：微信或支付宝明确返回预下单失败时，支付单记为已失败、充值单记为已关闭，用户使用新的 request_id 创建新单。请求超时或结果未知时，不得直接关闭或另建支付；必须先按原支付单号向原支付配置查单，确认失败后才能关闭，确认成功则返回原 qr_content。同一提交账号重复使用相同 request_id 时始终返回原业务结果；参数发生变化则拒绝幂等冲突。
代理充值主动新建 / Deliberate New Agent Recharge：request_id 只防止同一次提交因网络重试重复创建。代理每次主动点击创建或拉起支付，都必须使用新的 request_id，后端创建全新的充值单、支付单和 qr_content，不根据相同金额或既有未过期支付单复用旧单。此前未付款的支付单继续等待各自自然过期；多张支付单若均真实付款，则分别幂等入账。
代理在线充值支付验收 / Agent Online Recharge Payment Acceptance：本地和 Agent 自动化不调用真实微信或支付宝，复用 C 端已经验证的支付基础能力，并在支付网络边界使用可控替身验证后台充值的预下单契约、回调分发、金额与业务关联校验、状态推进、幂等入账及异常恢复。真实微信 Native 和支付宝 PreCreate 扫码支付在部署测试环境后由用户手工验收，不作为本地实现完成门禁；线下充值依赖的真实企微验收仍按企微公共能力执行。
代理充值支付状态同步 / Agent Recharge Payment Status Synchronization：前端每 3 秒调用轻量支付状态接口时只读取本地状态，不直接触发微信或支付宝查单。后端可靠任务按受控频率查询仍待支付的第三方订单，用于补偿回调丢失并确认第三方关闭或失效；查单结果和支付回调进入同一个幂等支付确认用例。只有第三方明确返回支付成功或已关闭时才推进本地状态，查询超时或未知状态继续保持待支付；用户主动创建新支付不影响旧单继续同步和自然收敛。
充值支付状态与入账状态 / Recharge Payment and Processing Status：payment_status 只表达第三方支付是否完成；processing_status 统一表达在线支付成功或线下审批通过后的钱包入账进度，固定为 0=未触发, 1=处理中, 2=处理成功, 3=处理失败，不再提供同义字段 wallet_posting_status。第三方已经收款但钱包入账失败时，支付状态仍为成功，处理状态为失败并由可靠任务重试；前端不得提供人工重复入账按钮。
代理充值两阶段入账 / Two-stage Agent Recharge Posting：在线支付回调事务只固化真实收款事实：支付单变为已支付、充值单变为 2=已支付、processing_status=1，并可靠写入入账 Outbox；随后由 Worker 在独立事务中更新代理主钱包余额和版本、创建唯一充值流水、把充值单改为 3=已完成与 processing_status=2，并写资金 Audit Event。Worker 失败不回滚支付事实，改为 processing_status=3并可靠重试；支付回调在收款事实成功落库后即可向渠道返回成功，不等待钱包入账。
代理充值到账通知 / Agent Recharge Posted Notification：无论代理在线扫码充值还是平台线下代充值，只要目标代理主钱包实际入账成功，都必须向目标代理发送一条站内“充值到账”通知。线下充值的企微审批结果仍由企微公共能力另行通知真实业务提交人，审批结果与实际到账是两类不同通知；通知投递失败不回滚资金事务，并按充值单与接收人防重。入账持续失败、通过后撤销等内部异常只通知平台财务或运维，不向代理暴露内部错误。
代理充值查看范围 / Agent Recharge Visibility：充值记录不按创建账号隔离。代理账号在具备充值查看权限时，按既有店铺层级数据范围查看本店及有权管理的下级店铺充值，可读取充值金额、支付方式、付款凭证、真实提交人、审批状态和钱包入账结果，但不能读取企微审批人、内部意见、审批人附件或支付配置等内部信息。平台和超级管理员沿用既有数据范围，企业账号不可访问；列表、详情和支付状态接口使用完全相同的数据范围。
企业微信审批（WeCom Approval）
业务提交人 / Business Submitter：在本系统实际创建退款或线下充值申请的登录账号，是审批单展示、通知、数据权限和审计中的真实发起人。
企微发起身份 / WeCom Creator Identity：调用企微 applyevent 时使用的成员 userid。平台/超级管理员使用当前系统账号扫码绑定的本人 userid；代理使用部署配置中的固定企微账号代提交。无论身份来源如何，审批实例和表单都必须独立保存真实业务提交人。
单次退款申请 / Single Refund Application：一张退款单只对应一条企微审批申请。企微拒绝后，审批和该退款单同时终结，原退款单不可修改、不可重提；业务人员纠正问题后若仍需退款，必须重新创建退款单，生成新的退款 ID、退款单号、业务快照和企微审批申请。
整单退款终结 / Whole-order Refund Finalization：退款创建接口只接受订单 ID、申请退款金额、原因、备注和附件；订单实收金额由后端读取并固化快照，不接受前端提交的 actual_received_amount，也不再接受 package_usage_id。申请退款金额必须大于 0 且小于等于订单实收金额，提交后不可由企微审批修改。无论申请金额是否等于实收金额，企微通过后的业务处理都按整张订单终结：订单标记已退款、该订单产生的套餐整体失效、该订单已入账佣金整体回扣；该订单不能再对未退差额发起第二次退款。
资产钱包订单退款 / Asset-wallet Order Refund：个人客户使用资产钱包余额购买的订单允许创建退款申请，但退款资金不自动回充资产钱包。财务必须先在系统外向客户完成人工退款，再在企微同意；企微同意后系统只执行整单终结，不调用支付渠道，也不产生资产钱包退款入账。只有代理主钱包支付的订单才按原扣款流水自动回溯原代理主钱包。
退款申请资料 / Refund Application Materials：退款原因必填，最多 1000 字；申请备注选填，最多 500 字。退款业务凭证必传 1～5 个，每项提交本地对象存储的 file_key、原始 file_name 和 file_size；本地业务资料是权威事实，上传企微的文件仅为审批副本，不能用审批人附件替代申请凭证。
退款佣金失效 / Refund Commission Invalidation：订单整单退款时，该订单尚未发放、解冻中、冻结中或待人工处理的佣金不再具备发放资格，直接改为已失效；已经发放的佣金先从对应佣金钱包全额扣回，钱包余额允许为负，再将佣金记录改为已失效。佣金记录使用结构化 invalid_reason 区分 order_refund 与 manual_resolution，因退款失效时同时保存退款单引用和失效时间，不能只在备注中写原因。每条已发放佣金以退款单和佣金记录组成业务防重键；佣金状态、钱包余额、扣回流水与统一 Audit Event 在同一事务提交，审计关联退款、订单、佣金、钱包和流水并保存变更前后事实。
固定退款金额审批 / Fixed Refund Amount Approval：创建退款时后端校验 0 < requested_refund_amount <= actual_received_amount 并固化金额。企微审批单只读展示订单实收金额、可退款区间和本次申请金额；审批人只能同意或拒绝，不能修改金额，认为金额有误时应拒绝，由业务人员创建新退款单。本系统不回改企微审批结论：企微已通过后即使本地资金或整单终结处理失败，审批状态和退款状态仍保持已通过，以独立 processing_status=失败、失败摘要和可靠重试表达本地失败。
实际退款金额 / Actual Refund Amount：actual_refund_amount 只表示资金已经实际完成的金额，不等同于审批金额。非代理钱包由财务先在系统外退款再同意企微，企微通过时写入申请金额；代理主钱包只有余额回溯与唯一退款流水事务成功后才写入申请金额。驳回、撤销、删除及尚未完成代理钱包回溯时为空；资金已完成但佣金或套餐处理失败时保留该金额，并由业务处理状态说明整单终结尚未完成。旧 approved_refund_amount 只保留历史兼容，不作为新业务对外概念。
代理退款查看范围 / Agent Refund Visibility：退款申请向代理开放后，不再按创建账号隔离。代理主账号及店铺内具备退款查看权限的账号按既有店铺层级数据范围查看本店及有权管理的下级店铺退款；退款资料、业务凭证、真实提交人、审批状态和业务处理结果仍受业务权限与数据范围约束。任何代理均不得看到企微审批人、内部意见或审批人附件；平台和超级管理员只有同时具备退款业务查看权限时才可读取完整审批详情。
批量订购（Bulk Purchase）
批量订购批次 / Bulk Purchase Batch：内部员工选择一个套餐和一种统一支付方式后提交的一份 CSV 订购任务。CSV 只提供资产标识；批次不绑定单一代理，同一批次可以包含不同代理名下的资产。
结算代理 / Settlement Agent：批量订购每一行根据资产处理时的当前归属解析出的代理。该行的套餐授权、成本价和代理主钱包均以结算代理为准；结算代理不是前端提交的批次参数。
批量订购重复行 / Duplicate Bulk Purchase Row：Worker 通过统一资产解析能力将输入标识解析为唯一的资产类型和资产 ID 后，同一 CSV 中再次指向该资产的行。一个批次只有一个套餐，因此无需再把套餐作为重复键；同一资产使用不同可识别标识仍属于重复，首次出现的行正常处理，后续重复行失败并指向首次出现的行号。
批量订购资产标识 / Bulk Purchase Asset Identifier：批量订购 CSV 中唯一由用户填写的业务字段。Worker 复用系统统一资产解析能力，由标识识别资产类型和资产 ID；当前统一能力可识别 ICCID、卡 virtual_no、MSISDN、设备 virtual_no、IMEI 和 SN。未命中或无法唯一解析时该行失败。
批量订购钱包支付 / Bulk Purchase Wallet Payment：批量订购的 payment_method=wallet 复用现有后台订单枚举，逐行扣该资产结算代理的主钱包；不使用同义值 agent_wallet。
批量订购文件级失败 / Bulk Purchase File-level Failure：创建接口只检查对象存储对象、上传主体、文件类型和 10MB 大小。Worker 发现编码、表头、未知列、CSV 语法、空文件或超过 1000 行时，任务整体失败且不创建订单；可部分成功仅适用于文件有效后的逐行业务校验。
批量订购钱包行序 / Bulk Purchase Wallet Row Order：wallet 批次按 CSV 行号逐行结算，不预占整批或某一代理全部行的金额。余额不足只失败当前行并继续后续行，所以同一代理资金不足时，CSV 行序就是订购优先级。
异步任务完成 / Async Task Completed：异步任务已经把其可处理工作执行到终点，不等于每个业务项都成功。全部成功、部分成功和全部业务项失败由成功数与失败数表达；只有任务无法完成解析或执行时才属于任务失败。