feat(代理自充): AUG26-017 代理自充收款方式与线下预存款审批字段

- 受控配置新增代理在线自充允许范围（仅微信/仅支付宝/同时支持），读侧与创建侧取允许范围与可用商户池交集，两侧失败关闭
- 新增允许范围查询与修改端点，读限代理与平台账号、写限超级管理员，复用受控配置写服务留痕
- tb_agent_recharge_record 新增交易流水号、线下收款方式三列快照与其他凭证列（成对迁移 000213）
- 线下申请校验启用的收款方式字典项与必填交易流水号，交易流水号独立于在线渠道交易号、不参与去重
- 扩展 offline_recharge_approval 场景可映射字段白名单与字典引用保护
- 新增付款凭证识别能力与交易流水号预填接口，识别不落库、日志不记录载荷

migrations/000213_add_agent_recharge_offline_fields.down.sql

@@ -0,0 +1,25 @@
+-- 回滚代理线下预存款审批字段。
+-- 新增列仍承载真实人工确认事实时禁止回滚：删除后交易流水号、收款方式快照与其他凭证引用无法恢复。
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1
+        FROM tb_agent_recharge_record
+        WHERE external_transaction_no IS NOT NULL
+           OR offline_payment_method_id IS NOT NULL
+    ) THEN
+        RAISE EXCEPTION '存在仍被引用的线下充值收款方式、交易流水号或其他凭证，禁止回滚代理线下预存款审批字段迁移';
+    END IF;
+END
+$$;
+
+DROP INDEX IF EXISTS idx_agent_recharge_external_transaction_no;
+DROP INDEX IF EXISTS idx_agent_recharge_offline_payment_method;
+
+-- 仅删除本次新增列，不影响既有充值记录读取与在线渠道列。
+ALTER TABLE tb_agent_recharge_record
+    DROP COLUMN IF EXISTS other_voucher_keys,
+    DROP COLUMN IF EXISTS offline_payment_method_name,
+    DROP COLUMN IF EXISTS offline_payment_method_code,
+    DROP COLUMN IF EXISTS offline_payment_method_id,
+    DROP COLUMN IF EXISTS external_transaction_no;

migrations/000213_add_agent_recharge_offline_fields.up.sql

@@ -0,0 +1,26 @@
+-- 代理线下预存款审批字段：收款方式快照、交易流水号与其他凭证。
+-- 新增列保持可空以兼容历史行；不新增唯一约束，交易流水号不参与去重。
+-- external_transaction_no 独立于在线渠道的 payment_transaction_id，两者语义与写入方互不影响。
+
+ALTER TABLE tb_agent_recharge_record
+    ADD COLUMN IF NOT EXISTS external_transaction_no varchar(128),
+    ADD COLUMN IF NOT EXISTS offline_payment_method_id bigint,
+    ADD COLUMN IF NOT EXISTS offline_payment_method_code varchar(64),
+    ADD COLUMN IF NOT EXISTS offline_payment_method_name varchar(100),
+    ADD COLUMN IF NOT EXISTS other_voucher_keys jsonb;
+
+-- 收款方式引用判定与详情查询索引：仅索引有效引用行。
+CREATE INDEX IF NOT EXISTS idx_agent_recharge_offline_payment_method
+    ON tb_agent_recharge_record (offline_payment_method_id)
+    WHERE offline_payment_method_id IS NOT NULL AND deleted_at IS NULL;
+
+-- 交易流水号检索索引：不是唯一约束，允许重复申报。
+CREATE INDEX IF NOT EXISTS idx_agent_recharge_external_transaction_no
+    ON tb_agent_recharge_record (external_transaction_no)
+    WHERE external_transaction_no IS NOT NULL AND external_transaction_no <> '' AND deleted_at IS NULL;
+
+COMMENT ON COLUMN tb_agent_recharge_record.external_transaction_no IS '线下充值交易流水号，由付款凭证识别预填并经人工确认，独立于在线渠道第三方交易号';
+COMMENT ON COLUMN tb_agent_recharge_record.offline_payment_method_id IS '线下收款方式字典ID（关联tb_employee_collection_payment_method.id）';
+COMMENT ON COLUMN tb_agent_recharge_record.offline_payment_method_code IS '线下收款方式稳定编码快照，字典改名或停用不影响历史记录';
+COMMENT ON COLUMN tb_agent_recharge_record.offline_payment_method_name IS '线下收款方式名称快照，字典改名或停用不影响历史记录';
+COMMENT ON COLUMN tb_agent_recharge_record.other_voucher_keys IS '其他凭证对象存储Key列表（jsonb 存储 []string），只保存对象键引用，最多5个';