EDU-031 — Activate native Trade brokerage

Status: done — native tenant-owned relationships, commission records, withdrawal/Pay Transfer bridge, exact RBAC, corrected Vben UI, and PostgreSQL evidence delivered
Type: native module takeover / two-level commission / tenant isolation
Phase: 5 / commercialization foundation
Blockers: EDU-024, EDU-027, PostgreSQL Flyway

Problem

The source backend has referral codes, leads, team edges, tracks, QR codes, CRM assignment, tenant commission settings, settlement aggregates/items, and proof/export events. RuoYi already owns a different but substantial Trade brokerage lifecycle: Member-backed promoter relationships, first/second-level order commissions, freeze/unfreeze, cancellation, withdrawals, Pay Transfer composition, app/admin APIs, scheduled settlement work, exact permissions, and three Vben administration pages. Rebuilding those overlapping behaviors in Education would create a second commission ledger and bypass native Member/Trade/Pay coordination.

Primary source evidence remains in:

/Users/tiku1/code/tiku-backend/supabase/migrations/202606210006_growth_referral_crm.sql
/Users/tiku1/code/tiku-backend/supabase/migrations/202606290009_commission_settlements.sql
/Users/tiku1/code/tiku-backend/supabase/migrations/202606290027_commission_settlement_proofs.sql

Delivered contract

BrokerageUserDO, BrokerageRecordDO, and BrokerageWithdrawDO extend TenantBaseDO; native app/admin controllers, services, mappers, jobs, Member lookups, Trade order integration, and Pay Transfer API remain authoritative.
V4430 creates trade_brokerage_user, trade_brokerage_record, and trade_brokerage_withdraw with (tenant_id,id) ownership, explicit record/withdraw sequences, tenant-qualified relationship/source/withdrawal/Pay Transfer/Trade Order references, commission idempotency, amount/state/account/audit/transfer checks, and a 0–99 withdrawal-fee range.
Menu IDs 7020–7031 reuse the existing user, record, and withdrawal pages with exactly eight controller permissions: user query/create/update-bind/clear-bind/update-enable, record query, and withdrawal query/audit.
The Vben user page uses those real permissions for both drill-downs, disables the eligibility switch without update permission, exposes responsive forms/tables, and its API types now match the backend responses. Withdrawal rejection trims and requires a non-blank reason on both sides.
Immediate-settlement commission records now persist a settlement time, so the native time-range summary and ranking SQL includes zero-freeze commissions.

Legacy data decision

V4430 activates the native ledger empty. Source referral/settlement rows use UUID identities and carry CRM lead assignment, referral-code/track attribution, settlement-batch state, and proof/export semantics that have no verified one-to-one mapping to native Member IDs, trade_order rows, two-level promoter relations, Pay Transfer rows, or immutable evidence artifacts. Importing them now would invent identity and settlement facts. Explicit referral CRM and commission-settlement import stays deferred until Member, lead, Order, payment, and proof mappings are reviewed; those source-only semantics are not declared retired.

Verification

The focused V4430 scenario proves table/sequence/check/index shape, same-number cross-tenant identities, tenant-qualified references, exact routes/permissions, and fail-closed adoption of a pre-existing global table.
The tenant contract proves all three native records participate in framework tenant isolation and withdrawal inputs reject missing type, non-positive price, and blank audit reason.
A Spring/MyBatis PostgreSQL integration test imports the real user/record services and production tenant SQL interceptor. Tenants 10 and 20 create the same Member IDs and business ID with different commission percentages; relationship/page reads, balances, MyBatis-Join summaries, and native annotated summary/ranking SQL remain isolated.
The corrected Vben pages pass workspace typecheck and scoped oxlint/oxfmt checks.
The full PostgreSQL Flyway suite passes 50 scenarios through V4430, and the server clean reactor compiles all 28 modules.

Explicitly open

Source referral code/lead/team-edge/track/QR/CRM-assignment semantics and settlement proof/export aggregates require dedicated mapping/import slices.
Special-order Promotion families and explicit legacy Product/coupon/order/refund import remain separate.
Purchase-driven Education entitlement fulfillment and refund-driven entitlement revocation remain separate orchestration work.
Configured Pay runtime, scheduled unfreeze/transfer operation, and deployed order-to-commission-to-withdrawal smoke evidence remain required for production acceptance.

4.7 KiB Raw Blame History Unescape Escape