ruoyi-vue-pro/docs/education/migration/issues/EDU-026-native-mall-coupon.md

EDU-026 — Activate native Mall Promotion coupons

• Status: done — tenant-owned native coupon templates/instances, existing APIs/UI, RBAC, and PostgreSQL evidence delivered
• Type: native module takeover / coupon lifecycle / tenant isolation
• Phase: 5 / commercialization foundation
• Blockers: EDU-025, PostgreSQL Flyway

Problem

RuoYi Vue Pro already provides coupon-template and issued-coupon controllers, services, Product-scope validation, Member lookup, registration issuance, expiry processing, permissions, and Vben pages. The Promotion server dependency was disabled and its two coupon records inherited only BaseDO, so reimplementing coupons inside Education would create a second marketing ledger without fixing tenant ownership.

Legacy public.coupons are code-based campaign rules with plan/region restrictions, first-order rules, usage counters, and coupon_redemptions. Native Promotion coupons are templates that issue member-owned coupon instances before order use. They are not losslessly interchangeable.

Delivered contract

• yudao-server now activates yudao-module-promotion in addition to Product; Trade and Statistics remain disabled until their own ledger slices are verified.
• Existing native /promotion/coupon-template, /promotion/coupon, /app-api/promotion/coupon-template, and /app-api/promotion/coupon contracts remain authoritative. Education adds no coupon controller or duplicate service.
• CouponTemplateDO and CouponDO extend TenantBaseDO, so native mapper/service access participates in the framework tenant interceptor.
• Native template creation reuses Product SPU/category validation. Native coupon administration reuses Member lookup, direct/admin/registration issuance, expiry processing, use/return, and soft-delete recovery rules.
• Promotion's unrelated bargain/combination beans require TradeOrderApi. EDU-027 now activates the native Trade implementation and removes the temporary fail-closed adapter that was used while Trade was absent.
• V4380 mounts the existing Vben template and issued-coupon pages below an Education 优惠券中心 using the original seven controller permissions and unique component names.

Database contract

V4380 creates tenant-scoped PostgreSQL tables:

• promotion_coupon_template
• promotion_coupon

Both use (tenant_id,id) ownership keys and explicitly named identity sequences. Coupon → Template is a tenant-qualified composite foreign key, so an identifier valid in another tenant cannot be referenced. Checks enforce native status/take/scope/validity/discount enums, fixed-date or relative-term validity, non-negative thresholds and discounts, issue/use counter consistency, positive members/orders, and complete used-coupon state. Indexes support template discovery, member/status lookup, template issuance lookup, and expiry jobs. Existing global coupon tables fail closed instead of being silently assigned to a tenant.

V4380 seeds menu IDs 6950–6959 for the coupon root, template page, issued-coupon page, and exact query/create/update/delete/send permissions.

Legacy data decision

V4380 starts the native coupon ledger empty. It does not reinterpret a legacy code campaign as a pre-issued member coupon, invent template/instance IDs, discard plan/region/first-order semantics, or attach historical redemptions to unverified native orders and members. A later compatibility/import slice must explicitly decide whether to preserve code redemption as a separate adapter or transform reviewed campaigns and redemption history.

Verification

• The Promotion coupon tenant contract proves both native coupon records inherit TenantBaseDO; EDU-027 separately verifies the native Trade dependency that replaced the temporary fallback.
• The focused V4380 Flyway scenario passes and proves same IDs can exist across tenants, cross-tenant template references fail, invalid counters/discounts/used state fail, explicit sequences exist, exact menus/permissions are installed, and global-table adoption fails closed.
• All 45 PostgreSQL Flyway integration tests pass.
• mvn -pl yudao-server -am -DskipTests compile succeeds with Product and Promotion enabled.
• @vben/web-antd typecheck and scoped Coupon oxlint/oxfmt checks pass.

Explicitly open

• Legacy code-campaign and redemption compatibility/import remains a separate mapping slice.
• EDU-027 activates the tenant-scoped normal-order core. Coupon-to-special-order and refund composition still depend on deferred Promotion and Trade after-sale slices.
• Discount/reward/seckill/combination/bargain/point/Diy/KeFu Promotion families are not activated at the database/menu level by this slice.
• Target-environment role grants, browser/API smoke evidence, and deliberate template population remain operational work.