merge: 合并 main 并保留寄卖内部匹配与客户退款

This commit is contained in:
2026-11-05 18:02:47 +08:00
105 changed files with 7248 additions and 665 deletions
+38
View File
@@ -24,10 +24,23 @@ const MIGRATIONS_DIR = path.join(CURRENT_DIR, 'migrations')
const MIGRATIONS_TABLE = 'schema_migrations'
const SHORT_NUMERIC_PREFIX_MESSAGE = /^Can't determine timestamp for \d+$/
const MIGRATION_FILE_PATTERN = /^(\d{3})_.+\.sql$/i
/**
* 合并 main 后寄卖迁移从 129-131 顺延为 135-137(main 已占用 129-134)。
* 已跑过旧编号的环境要清掉旧记录,让新编号按正常顺序重跑(迁移本身幂等)。
*/
const RENAMED_MIGRATIONS: Array<{ legacyName: string; currentName: string }> = [
{ legacyName: '129_consignment_matching', currentName: '135_consignment_matching' },
{ legacyName: '130_consignment_dynamic_specs', currentName: '136_consignment_dynamic_specs' },
{
legacyName: '131_consignment_surnan_default_profile',
currentName: '137_consignment_surnan_default_profile',
},
]
export async function runDatabaseMigrations() {
assertMigrationFilesOrdered()
await ensureNodePgMigrateMetadataCompatibility()
await dropRenamedMigrationRecords()
console.info(`[db:migrate] 迁移目录: ${MIGRATIONS_DIR}`)
@@ -180,6 +193,31 @@ async function ensureNodePgMigrateMetadataCompatibility() {
`)
}
/**
* 合并 main 后寄卖迁移编号顺延:清掉旧编号的已执行记录。
* 只在新文件存在、旧文件已不存在、且新编号尚未记录时执行,
* 之后由 runner 按新编号正常重跑(寄卖迁移均为幂等脚本)。
*/
async function dropRenamedMigrationRecords() {
for (const { legacyName, currentName } of RENAMED_MIGRATIONS) {
if (fs.existsSync(path.join(MIGRATIONS_DIR, `${legacyName}.sql`))) continue
if (!fs.existsSync(path.join(MIGRATIONS_DIR, `${currentName}.sql`))) continue
const result = await query(
`
DELETE FROM ${MIGRATIONS_TABLE}
WHERE name = $1
AND NOT EXISTS (
SELECT 1 FROM ${MIGRATIONS_TABLE} WHERE name = $2
)
`,
[legacyName, currentName],
)
if ((result.rowCount ?? 0) > 0) {
console.info(`[db:migrate] 迁移编号已顺延: ${legacyName} -> ${currentName}`)
}
}
}
async function syncLegacyMigrationColumns() {
await query(`
UPDATE ${MIGRATIONS_TABLE}
@@ -0,0 +1,129 @@
-- 129_fulfillment_retry_semantics.sql
--
-- 履约载体重试语义:
-- 1. 同一订单项/单元只限制一个“活跃”任务,历史 closed/failed 任务保留;
-- 2. 载体补建使用独立水位,避免每次重复扫描最早的 200 条;
-- 3. 回填历史内部 SKU 的大小写/全半角/空白规范化结果,并合并规范后重复渠道。
-- 允许同一订单项/单元在旧任务关闭后创建新的履约尝试。
ALTER TABLE fulfillment_tasks
DROP CONSTRAINT IF EXISTS fulfillment_tasks_order_item_id_unit_index_key;
DROP INDEX IF EXISTS fulfillment_tasks_order_item_id_unit_index_key;
CREATE UNIQUE INDEX IF NOT EXISTS uq_fulfillment_tasks_active_unit
ON fulfillment_tasks (order_item_id, unit_index)
WHERE task_status NOT IN (
'closed', 'expired', 'failed', 'manual_review', 'retry_pending', 'cancelled'
);
COMMENT ON INDEX uq_fulfillment_tasks_active_unit IS
'同一订单项/单元只允许一个活跃履约载体;关闭、失败、待重试和人工复核任务保留为历史记录';
ALTER TABLE work_orders
DROP CONSTRAINT IF EXISTS idx_work_orders_order_item_unique;
DROP INDEX IF EXISTS idx_work_orders_order_item_unique;
CREATE UNIQUE INDEX IF NOT EXISTS uq_work_orders_active_order_item
ON work_orders (order_item_id)
WHERE order_item_id IS NOT NULL AND status <> 'cancelled';
COMMENT ON INDEX uq_work_orders_active_order_item IS
'同一订单项只允许一个未取消工单;取消工单保留为历史并可重新建单';
INSERT INTO finance_watermarks (pipeline, last_item_id, last_success_at)
VALUES ('carrier_reconcile', 0, NULL)
ON CONFLICT (pipeline) DO NOTHING;
COMMENT ON COLUMN finance_watermarks.pipeline IS
'同步管道:channel_assign / carrier_reconcile / carrier_dispatch / product_normalize / cost_snapshot / cost_snapshot_hot / sales_facts / ledger_post';
-- 规范化前先收敛跨渠道主渠道。同一规范 SKU 只能有一个 enabled 主渠道;
-- 优先保留带载体参数的行,再按优先级、id 稳定选择。
WITH ranked_primary AS (
SELECT
id,
ROW_NUMBER() OVER (
PARTITION BY canonicalize_internal_sku(internal_sku)
ORDER BY
CASE WHEN config_json = '{}'::jsonb THEN 1 ELSE 0 END,
priority,
id
) AS candidate_rank
FROM internal_sku_channels
WHERE enabled = TRUE AND is_fallback = FALSE
)
UPDATE internal_sku_channels channel
SET is_fallback = TRUE,
priority = GREATEST(priority, 90),
updated_at = NOW()
FROM ranked_primary
WHERE channel.id = ranked_primary.id
AND ranked_primary.candidate_rank > 1;
-- 同一规范 SKU + 渠道只保留一行,优先保留启用、带载体参数的行。
WITH ranked AS (
SELECT
internal_sku,
channel,
id,
canonicalize_internal_sku(internal_sku) AS canonical_sku,
ROW_NUMBER() OVER (
PARTITION BY canonicalize_internal_sku(internal_sku), channel
ORDER BY
enabled DESC,
CASE WHEN config_json = '{}'::jsonb THEN 1 ELSE 0 END,
is_fallback,
priority,
id
) AS candidate_rank
FROM internal_sku_channels
)
DELETE FROM internal_sku_channels channel
USING ranked
WHERE channel.id = ranked.id
AND ranked.candidate_rank > 1;
UPDATE internal_sku_channels
SET internal_sku = canonicalize_internal_sku(internal_sku),
updated_at = NOW()
WHERE internal_sku <> canonicalize_internal_sku(internal_sku);
-- 人工 SKU 登记表是扫描派生数据。历史数据可能因大小写/空白差异登记了多行,
-- 规范化后会撞唯一键;先去重,优先保留有配置、统计更完整且更新时间更晚的行。
WITH ranked_registry AS (
SELECT
id,
ROW_NUMBER() OVER (
PARTITION BY canonicalize_internal_sku(sku_key)
ORDER BY
(config_id IS NOT NULL) DESC,
item_count DESC,
updated_at DESC,
id DESC
) AS candidate_rank
FROM manual_sku_registry
WHERE canonicalize_internal_sku(sku_key) IS NOT NULL
)
DELETE FROM manual_sku_registry registry
USING ranked_registry ranked
WHERE registry.id = ranked.id
AND ranked.candidate_rank > 1;
UPDATE manual_fulfillment_configs
SET sku_key = canonicalize_internal_sku(sku_key),
updated_at = NOW()
WHERE sku_key <> canonicalize_internal_sku(sku_key);
UPDATE manual_sku_registry
SET sku_key = canonicalize_internal_sku(sku_key),
updated_at = NOW()
WHERE sku_key <> canonicalize_internal_sku(sku_key);
UPDATE internal_sku_mappings
SET match_value = canonicalize_internal_sku(match_value),
internal_sku = canonicalize_internal_sku(internal_sku),
updated_at = NOW()
WHERE match_value <> canonicalize_internal_sku(match_value)
OR internal_sku <> canonicalize_internal_sku(internal_sku);
@@ -0,0 +1,50 @@
-- 延迟核销任务。
--
-- 业务事件只负责投递任务,真正的外部平台核销由定时任务稍后执行;
-- 任务持久化到数据库,服务重启也不会丢失延迟核销。
CREATE TABLE IF NOT EXISTS voucher_consume_jobs (
id BIGSERIAL PRIMARY KEY,
provider TEXT NOT NULL
CHECK (provider IN ('kuaishou_industry', 'douyin_mashida')),
channel TEXT NOT NULL
CHECK (channel IN ('affiliate_dash', 'work_order', 'manual', 'third_party_voucher')),
trigger_event TEXT NOT NULL,
target_key TEXT NOT NULL,
platform_order_id TEXT NOT NULL DEFAULT '',
order_id BIGINT REFERENCES orders(id) ON DELETE SET NULL,
order_item_id BIGINT REFERENCES order_items(id) ON DELETE SET NULL,
task_id BIGINT REFERENCES fulfillment_tasks(id) ON DELETE SET NULL,
work_order_id BIGINT REFERENCES work_orders(id) ON DELETE SET NULL,
due_at TIMESTAMPTZ NOT NULL,
status TEXT NOT NULL DEFAULT 'pending'
CHECK (status IN ('pending', 'processing', 'succeeded', 'failed', 'cancelled')),
attempt_count INTEGER NOT NULL DEFAULT 0,
max_attempts INTEGER NOT NULL DEFAULT 8,
locked_until TIMESTAMPTZ,
last_error TEXT NOT NULL DEFAULT '',
result_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
finished_at TIMESTAMPTZ
);
-- 同一平台、同一个核销目标只保留一个活跃或已成功任务。
-- 失败任务允许后续业务事件重新投递;成功任务阻止重复投递。
CREATE UNIQUE INDEX IF NOT EXISTS uq_voucher_consume_jobs_active_target
ON voucher_consume_jobs(provider, target_key)
WHERE status IN ('pending', 'processing', 'succeeded');
CREATE INDEX IF NOT EXISTS idx_voucher_consume_jobs_due
ON voucher_consume_jobs(status, due_at, id);
CREATE INDEX IF NOT EXISTS idx_voucher_consume_jobs_order
ON voucher_consume_jobs(order_id, order_item_id, id DESC);
CREATE INDEX IF NOT EXISTS idx_voucher_consume_jobs_updated
ON voucher_consume_jobs(updated_at DESC, id DESC);
COMMENT ON TABLE voucher_consume_jobs IS
'延迟核销任务:业务事件负责投递,定时任务负责执行';
COMMENT ON COLUMN voucher_consume_jobs.target_key IS
'稳定去重目标:优先订单项,没有订单项时使用任务或订单';
@@ -0,0 +1,18 @@
-- 允许待履约订单项保留已经选择的履约渠道。
--
-- pending + 渠道:渠道已确定,但载体、商品或成本配置尚未完成;
-- assigned:真实履约载体已经创建完成。
ALTER TABLE order_items
DROP CONSTRAINT IF EXISTS chk_order_items_fulfillment_channel_status;
ALTER TABLE order_items
ADD CONSTRAINT chk_order_items_fulfillment_channel_status
CHECK (
fulfillment_status = 'pending'
OR (fulfillment_status = 'assigned' AND fulfillment_channel IS NOT NULL)
OR fulfillment_status = 'archived'
);
COMMENT ON CONSTRAINT chk_order_items_fulfillment_channel_status ON order_items IS
'pending 允许保留已选择渠道并等待配置完成;assigned 必须存在履约渠道';
@@ -0,0 +1,93 @@
-- 132_on_account_and_manual_channels.sql
--
-- 新增“统一结算”履约渠道,并支持一个内部 SKU 配置多个人工履约渠道。
-- 客服确认履约时选择本次实际渠道;统一结算只生成虚拟账单,不扣积分或备用金。
-- 1. 订单项履约渠道增加 on_account。
ALTER TABLE order_items
DROP CONSTRAINT IF EXISTS chk_order_items_fulfillment_channel;
ALTER TABLE order_items
ADD CONSTRAINT chk_order_items_fulfillment_channel
CHECK (
fulfillment_channel IS NULL
OR fulfillment_channel IN (
'work_order', 'affiliate_dash', 'third_party_voucher', 'manual', 'on_account'
)
);
-- 2. 内部 SKU 渠道配置增加 on_account。
ALTER TABLE internal_sku_channels
DROP CONSTRAINT IF EXISTS internal_sku_channels_channel_check;
ALTER TABLE internal_sku_channels
ADD CONSTRAINT internal_sku_channels_channel_check
CHECK (channel IN ('work_order', 'affiliate_dash', 'third_party_voucher', 'manual', 'on_account'));
-- 3. 自动核销任务允许记录 on_account 渠道。
ALTER TABLE voucher_consume_jobs
DROP CONSTRAINT IF EXISTS voucher_consume_jobs_channel_check;
ALTER TABLE voucher_consume_jobs
ADD CONSTRAINT voucher_consume_jobs_channel_check
CHECK (channel IN ('affiliate_dash', 'work_order', 'manual', 'third_party_voucher', 'on_account'));
-- 4. 人工 SKU 配置支持多个渠道明细,旧单渠道字段继续保留用于兼容。
ALTER TABLE manual_fulfillment_configs
ADD COLUMN IF NOT EXISTS channels_json JSONB NOT NULL DEFAULT '[]'::jsonb;
ALTER TABLE manual_fulfillment_configs
DROP CONSTRAINT IF EXISTS chk_manual_fulfillment_configs_platform;
ALTER TABLE manual_fulfillment_configs
ADD CONSTRAINT chk_manual_fulfillment_configs_platform
CHECK (platform_key IN ('nanhang', 'lewan', 'rock', 'fund_cash', 'on_account'));
UPDATE manual_fulfillment_configs
SET channels_json = jsonb_build_array(
jsonb_build_object(
'platformKey', platform_key,
'creditQuantity', credit_quantity,
'costMode', cost_mode,
'enabled', enabled
)
)
WHERE channels_json = '[]'::jsonb;
COMMENT ON COLUMN manual_fulfillment_configs.channels_json IS
'人工履约渠道明细:platformKey / creditQuantity / costMode / enabled;旧 platform_key 字段保留兼容';
-- 5. 统一结算虚拟账单。后续统一对账以该表为待办真源。
CREATE TABLE IF NOT EXISTS on_account_bills (
id BIGSERIAL PRIMARY KEY,
bill_no TEXT NOT NULL UNIQUE,
order_id BIGINT NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
order_item_id BIGINT NOT NULL REFERENCES order_items(id) ON DELETE CASCADE,
sku_key TEXT NOT NULL DEFAULT '',
canonical_product_id BIGINT REFERENCES product_catalog(id) ON DELETE SET NULL,
platform_order_id TEXT NOT NULL DEFAULT '',
amount_fen BIGINT NOT NULL CHECK (amount_fen >= 0),
status TEXT NOT NULL DEFAULT 'pending'
CHECK (status IN ('pending', 'reconciled', 'void')),
payee_name TEXT NOT NULL DEFAULT '',
note TEXT NOT NULL DEFAULT '',
metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_by_admin_user_id BIGINT REFERENCES admin_users(id) ON DELETE SET NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
reconciled_at TIMESTAMPTZ
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_on_account_bills_order_item
ON on_account_bills(order_item_id);
CREATE INDEX IF NOT EXISTS idx_on_account_bills_status_created
ON on_account_bills(status, created_at DESC, id DESC);
CREATE INDEX IF NOT EXISTS idx_on_account_bills_order
ON on_account_bills(order_id, order_item_id);
COMMENT ON TABLE on_account_bills IS
'统一结算虚拟账单:确认履约时生成,不扣客服积分或备用金,后续统一对账';
COMMENT ON COLUMN on_account_bills.status IS
'pending 待对账 / reconciled 已对账 / void 已作废';
@@ -0,0 +1,21 @@
-- 133_manual_credit_quantity_decimal.sql
--
-- 人工履约的现金金额支持最多 2 位小数;积分渠道仍只接受整数。
-- 成本金额仍按整数分保存,避免把金额精度扩散到财务快照和总账。
ALTER TABLE manual_fulfillment_configs
ALTER COLUMN credit_quantity TYPE NUMERIC(18, 2)
USING ROUND(credit_quantity::numeric, 2);
COMMENT ON COLUMN manual_fulfillment_configs.credit_quantity IS
'每单消耗量;积分渠道必须为整数,备用金现金/统一结算为元且最多 2 位小数;0 表示成本不固定';
ALTER TABLE manual_fulfillment_configs
DROP CONSTRAINT IF EXISTS chk_manual_fulfillment_configs_integer_credit;
ALTER TABLE manual_fulfillment_configs
ADD CONSTRAINT chk_manual_fulfillment_configs_integer_credit
CHECK (
platform_key IN ('fund_cash', 'on_account')
OR credit_quantity = TRUNC(credit_quantity)
);
@@ -0,0 +1,98 @@
-- 134_customer_refund_operations.sql
--
-- 客户退款编排:
-- 1. 平台售后单落库,支持抖音从 refund_RefundCreated 消息自动发现;
-- 2. 一键退款操作记录平台调用、本地退款和业务关闭步骤,保证可重试且不重复退款。
INSERT INTO admin_permissions (permission_key, permission_name, permission_group, description)
VALUES (
'worker_order.customer_refund',
'客户退款并关闭订单',
'接单管理',
'同意平台用户售后,冲正核销,并关闭订单关联履约、资料和领取任务'
)
ON CONFLICT (permission_key) DO UPDATE SET
permission_name = EXCLUDED.permission_name,
permission_group = EXCLUDED.permission_group,
description = EXCLUDED.description,
updated_at = NOW();
-- 客服和运营默认具备前台退款处置能力;高风险管理员仍可在角色权限里收回。
INSERT INTO admin_role_permissions (role_key, permission_key)
SELECT role_key, 'worker_order.customer_refund'
FROM (VALUES ('admin'), ('operator'), ('support')) AS roles(role_key)
ON CONFLICT DO NOTHING;
CREATE TABLE IF NOT EXISTS platform_after_sales (
id BIGSERIAL PRIMARY KEY,
provider TEXT NOT NULL,
platform_order_id TEXT NOT NULL,
sub_order_id TEXT NOT NULL DEFAULT '',
external_after_sale_id TEXT NOT NULL,
local_order_id BIGINT REFERENCES orders(id) ON DELETE SET NULL,
local_order_item_id BIGINT REFERENCES order_items(id) ON DELETE SET NULL,
amount_fen BIGINT NOT NULL DEFAULT 0 CHECK (amount_fen >= 0),
after_sale_status INTEGER,
after_sale_type INTEGER,
refund_status INTEGER,
platform_update_time TEXT NOT NULL DEFAULT '',
state TEXT NOT NULL DEFAULT 'open'
CHECK (state IN ('open', 'agreed', 'refused', 'closed', 'success', 'failed')),
raw_json JSONB NOT NULL DEFAULT '{}'::jsonb,
applied_at TIMESTAMPTZ,
last_event_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_platform_after_sales_external
ON platform_after_sales(provider, external_after_sale_id);
CREATE INDEX IF NOT EXISTS idx_platform_after_sales_order
ON platform_after_sales(provider, platform_order_id, state, last_event_at DESC);
CREATE INDEX IF NOT EXISTS idx_platform_after_sales_local_order
ON platform_after_sales(local_order_id, state, last_event_at DESC)
WHERE local_order_id IS NOT NULL;
COMMENT ON TABLE platform_after_sales IS
'平台电商售后单:抖音由退款消息落库,供后台自动选择待处理退款;不是打手履约售后单';
COMMENT ON COLUMN platform_after_sales.platform_update_time IS
'平台售后版本时间;抖音 afterSale.operate 必须回传该值防止版本过期';
CREATE TABLE IF NOT EXISTS refund_cancel_operations (
id BIGSERIAL PRIMARY KEY,
operation_no TEXT NOT NULL UNIQUE,
order_id BIGINT NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
order_item_id BIGINT NOT NULL REFERENCES order_items(id) ON DELETE CASCADE,
work_order_id BIGINT REFERENCES work_orders(id) ON DELETE SET NULL,
provider TEXT NOT NULL,
external_after_sale_id TEXT NOT NULL,
amount_fen BIGINT NOT NULL CHECK (amount_fen > 0),
status TEXT NOT NULL DEFAULT 'pending'
CHECK (status IN (
'pending', 'platform_approved', 'refund_recorded', 'closed', 'failed'
)),
current_step TEXT NOT NULL DEFAULT 'created',
error_message TEXT NOT NULL DEFAULT '',
result_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_by_admin_user_id BIGINT REFERENCES admin_users(id) ON DELETE SET NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
completed_at TIMESTAMPTZ
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_refund_cancel_operations_external
ON refund_cancel_operations(provider, external_after_sale_id, order_item_id);
CREATE INDEX IF NOT EXISTS idx_refund_cancel_operations_order
ON refund_cancel_operations(order_id, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_refund_cancel_operations_status
ON refund_cancel_operations(status, updated_at DESC);
COMMENT ON TABLE refund_cancel_operations IS
'客户退款并关闭订单的幂等编排记录:平台同意、本地退款、业务关闭分步留痕,可安全重试';
COMMENT ON COLUMN work_order_shares.cancelled_reason IS
'取消来源:timeout/worker_request/admin/admin_partial/problem/settlement/customer_refund';
@@ -1,4 +1,4 @@
-- 129_consignment_matching.sql
-- 135_consignment_matching.sql
-- 寄卖配置化 + 库存数量/售价 + 内部匹配/自动匹配 + 拼单库存分配。
-- 全部语句幂等,可安全重跑;不改动历史迁移。
@@ -1,4 +1,4 @@
-- 130_consignment_dynamic_specs.sql
-- 136_consignment_dynamic_specs.sql
-- 寄卖动态规格:提报/库存增加 spec_values_json、spec_key、spec_text 与改价上限。
-- 全部语句幂等,可安全重跑;不改动历史迁移。
@@ -1,4 +1,4 @@
-- 131_consignment_surnan_default_profile.sql
-- 137_consignment_surnan_default_profile.sql
-- 苏尔南手枪默认寄卖配置:五个规格字段(与旧发布页一致),直接发布 v1。
-- 幂等:该分类已有寄卖配置时不做任何事,避免覆盖运营已保存/已发布的配置。