docs(education): update migration status and add EDU-017~033 tickets

docs/education/migration/02-api-mapping.md

@@ -2,6 +2,8 @@
 
 > Phase 0 static assessment generated on 2026-07-29. No build, test, application startup, PostgreSQL connection, or Flyway migration was executed during this assessment.
 
+> Runtime mapping update 2026-08-01: EDU-027 keeps native Trade order/config contracts authoritative, EDU-028 keeps native Discount/Reward APIs authoritative, EDU-029 activates delivery, EDU-030 activates after-sale/Pay Refund, EDU-031 activates Member-backed brokerage, EDU-032 activates native Promotion Seckill, and EDU-033 activates native Promotion Combination activity/group/Trade Order contracts. Education adds no shadow commerce, refund, commission, or special-order API. Configured target Pay runtime, Bargain/Point and other special orders, legacy commerce/referral/settlement-proof mapping, fulfillment/revocation, and deployed checkout/refund/commission/promotion evidence remain open.
+
 This Phase 0 artifact maps API families rather than all 342 operations. Endpoint-level method/path/request/response mapping remains required before implementing each family.
 
 ## Tenant resolution, identity, and student context
@@ -60,10 +62,28 @@ This Phase 0 artifact maps API families rather than all 342 operations. Endpoint
 - **Legacy authorization semantics to preserve:** tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
 - **Target:** Education + System + Member + Mall/Pay + Infra
 - **Reuse:** System Tenant/RBAC/DataPermission/AdminUserApi, Member relationships, Mall/Pay/Member APIs, Infra secret/file/message/audit facilities.
-- **Migration conclusion:** pending migration
-- **Contract gap:** Verified: classes/supervision were only part of the source tenant-admin surface. Appearance/theme lifecycle, domains/payment/auth integrations, secret rotation, and codes/coupons are separate migration/security surfaces with no verified target equivalent. Inference: collapsing them into one row would hide authorization and secret-handling decisions.
-- **Required verification:** Permission matrix, row-scope negatives, secret redaction/rotation, integration authorization, code/coupon idempotency, audit, and cross-tenant tests.
-- **Open decision:** Define class/student/teacher scope semantics and separately decide appearance, domain, payment/auth integration, secret, activation-code, coupon, public-bank grant, and marketing ownership or retirement.
+- **Migration conclusion:** partially migrated — class/supervision, appearance, native Pay/System integration and ledgers, learning activation codes, native Mall Product/Coupon, and V4390–V4450 normal Trade order/checkout/delivery/after-sale/brokerage/seckill/combination activation delivered
+- **Delivered activation-code contracts:** Admin `GET /education/activation-code/batch/page`, `POST /batch`, `PUT /batch/{id}`, `POST /batch/{id}/generate`, `GET /code/page`, and `PUT /code/{id}/disable`; Member-only app `POST /education/activation-code/check` and `POST /education/activation-code/redeem`. Query/manage/generate permissions are independent. Generation returns plaintext once, while persistence and later reads expose only digest/mask. Redemption locks the code row and composes `EducationEntitlementService` with `sourceSystem=ACTIVATION_CODE`.
+- **Delivered legacy Pay import contracts:** Pay-owned `POST /pay/legacy-account-import/import` requires App+Channel create permissions and maps one explicitly reviewed `tenant_collect` WeChat/Alipay manifest through native Pay services. `GET /pay/legacy-account-import/page` requires both query permissions and returns the tenant-filtered redacted audit. Same source-account/checksum replays; checksum conflicts, non-equivalent modes/providers, channel-family mismatch, ambiguous rotating keys, and unsafe Alipay endpoints fail closed. The existing Pay App Vben page owns the import modal.
+- **Delivered native Pay transaction contracts:** Existing `/pay/order`, `/pay/refund`, and `/pay/notify` query/detail/export/callback contracts and the `pay/order/index`, `pay/refund/index`, and `pay/notify/index` Vben pages are reused. V4340 supplies tenant-scoped PostgreSQL order/extension/refund/notification tables and composite tenant foreign keys; callback processing retains channel-derived `TenantUtils` context and notification retries retain `@TenantJob` execution.
+- **Delivered legacy transaction bridge:** `POST /pay/legacy-transaction-import/import` accepts one terminal, reconciled order/payment/refund manifest under `pay:legacy-transaction:import`; `GET /pay/legacy-transaction-import/page` exposes redacted tenant audit under `pay:legacy-transaction:query`. It requires an EDU-021 account mapping, exact cent/status/provider reconciliation, source UUID/checksum idempotency, and explicit optional native Member ID. It writes native Pay ledgers without SDK calls, callbacks, notifications, raw payloads, or error originals. The native order page owns the import/history modal.
+- **Delivered native Transfer/Wallet contracts:** Existing `/pay/transfer`, `/pay/wallet`, `/pay/wallet-transaction`, `/pay/wallet-recharge`, and `/pay/wallet-recharge-package` controllers remain authoritative. V4360 activates empty tenant-scoped native ledgers and existing `pay/transfer/index`, `pay/wallet/balance/index`, and `pay/wallet/rechargePackage/index` pages. Five data objects use `TenantBaseDO`, Transfer sync retains `@TenantJob`, wallet locks include tenant ID, administrator reductions use conditional subtraction, and recharge refund has a dedicated permission. No legacy wallet balance is inferred.
+- **Delivered native Product contracts:** Existing `/product/brand`, `/product/category`, `/product/property`, `/product/property/value`, `/product/spu`, `/product/comment`, `/product/favorite`, and `/product/browse-history` controllers remain authoritative. V4370 activates nine tenant-scoped Product tables and the existing SPU, Category, Brand, Property, and Comment Vben pages. Nine Product data objects use `TenantBaseDO`; PostgreSQL composite tenant references enforce the catalog graph. The legacy display-only `products` projection is not automatically imported.
+- **Delivered native Coupon contracts:** Existing `/promotion/coupon-template`, `/promotion/coupon`, and app coupon controllers remain authoritative. V4380 activates tenant-scoped template/issued-instance persistence, Product SPU/category scope validation, Member lookup/issuance, registration issuance, expiry processing, and the existing template/record Vben pages. Both coupon records use `TenantBaseDO`; the template reference is tenant-qualified. Legacy code campaigns/redemptions are not automatically imported.
+- **Delivered native Trade contracts:** Existing `/trade/order`, `/trade/config`, `/app-api/trade/order`, and `/app-api/trade/cart` controllers remain authoritative. V4390 activates tenant-scoped Order/Item/Log/Cart/Config persistence, native `TradeOrderApiImpl`, exact order/config permissions, and the existing Vben pages. Legacy aggregate orders are not automatically imported.
+- **Delivered native checkout Promotion contracts:** Existing `/promotion/discount-activity`, `/promotion/reward-activity`, `DiscountActivityApi`, and `RewardActivityApi` remain authoritative. V4400 activates tenant-scoped Discount Activity/Product and Reward Activity persistence, exact action permissions, and the two existing Vben pages. Real empty API lookups are proven on PostgreSQL; no legacy campaigns are inferred.
+- **Delivered native delivery contracts:** Existing `/trade/delivery/express`, `/trade/delivery/express-template`, `/trade/delivery/pick-up-store`, app delivery reads, and `TradeDeliveryPriceCalculator` remain authoritative. V4410 activates tenant-scoped company/template/rule/store persistence, Product/Order references, exact permissions, three existing Vben pages, and a real PostgreSQL express-fee calculation; no source delivery data is inferred.
+- **Delivered native after-sale contracts:** Existing Member application/cancel/delivery reads, `/trade/after-sale/page`, `/get-detail`, `/agree`, `/disagree`, `/receive`, `/refuse`, `/refund`, Pay refund callback handling, and operation logs remain authoritative. V4420 supplies tenant-scoped persistence/references and exact permissions. Vben now sends `auditReason`, requires `refuseMemo`, shows the application `createTime`, and permission-guards every action.
+- **Legacy refund mapping:** `commerce_refund_requests` and `commerce_refund_events` are aggregate UUID records without verified native Member, Order Item, Product/SKU, return-logistics, or Pay Refund identities. V4420 deliberately imports none; mapping follows explicit legacy Product/Member/Order Item reconciliation.
+- **Delivered native brokerage contracts:** Existing app/admin relationship, eligibility, team/rank, commission-record, freeze/unfreeze/cancel, withdrawal/audit, Pay Transfer callback, and scheduled job contracts remain authoritative. V4430 supplies tenant-owned persistence, references, exact eight permissions, and corrected user/record/withdrawal pages. Immediate settlements now participate in time-range statistics.
+- **Legacy referral/settlement mapping:** Source referral codes/leads/team edges/tracks/QR/CRM assignment and UUID settlement/item/proof/export rows lack verified native Member, Order, relationship, Pay Transfer, and evidence identities. V4430 deliberately imports none; they remain explicit mapping/import work rather than being treated as native-equivalent.
+- **Delivered native Seckill contracts:** Existing `/promotion/seckill-config`, `/promotion/seckill-activity`, supporting app reads, Product lookups, atomic stock updates, and Trade Order seckill fields remain authoritative. V4440 supplies empty tenant-owned time/activity/product persistence, Product/Trade references, consistency triggers, exact nine permissions, and corrected activity/config pages. Duplicate SKU, price/stock overrun, invalid time/limit inputs, unsafe restoration, and deletion of an in-use slot fail closed.
+- **Source Seckill disposition:** Repository-wide source inventory found no seckill capability. V4440 deliberately starts empty; ordinary products, coupons, and aggregate orders are not reinterpreted as activities.
+- **Delivered native Combination contracts:** Existing `/promotion/combination-activity`, `/promotion/combination-record`, supporting app reads/jobs, Product/Member lookups, and Trade Order combination fields remain authoritative. V4450 supplies empty tenant-owned activity/product/record persistence, capacity and reference triggers, exact six permissions, and corrected activity/record pages. Duplicate/mismatched SKUs, price/time/limit errors, cross-activity heads, over-capacity joins, inconsistent orders, and deletion with records fail closed.
+- **Source Combination disposition:** The source `combination` token is an education combination-question type, not group buying. V4450 deliberately starts empty; no content question, ordinary product, or aggregate order is reinterpreted as a promotion group.
+- **Contract gap:** Native Pay, Product, Coupon, normal Trade order, Promotion discount/reward/seckill/combination, Trade delivery, Trade after-sale, and native Trade brokerage administration are operational. Production bulk export/runbooks, reviewed UUID-to-Member/opening-balance artifacts, explicit legacy commerce/referral/settlement-proof mapping, Bargain/Point and other special-order activation, provider settlement equivalence, XPay/Xunhu replacement, and generic credential encryption remain open. V4310 does not claim legacy activation-code data import. Domains remain System Tenant websites. Tenant PNVS, private encrypted secrets, fulfillment, refund-to-entitlement revocation, and other marketing surfaces remain separate.
+- **Required verification:** Permission matrix, row-scope negatives, secret redaction/rotation, integration authorization, legacy import idempotency/audit, and cross-tenant tests. Pay/Coupon/Trade/Seckill/Combination tests are delivered through V4450, including composite after-sale/brokerage/special-order references, state/amount/stock/capacity validation, exact menus, real tenant-isolated service/statistics/concurrency reads and writes, and fail-closed adoption.
+- **Open decision:** Compose payments through Pay, products/coupons/promotions/orders/refunds/commissions through Mall Product/Promotion/Trade, and auth providers through System/Member. Continue Bargain/Point and other Promotion families, explicit legacy commerce/referral/settlement-proof imports, production financial/order/refund runbooks, reviewed balances, non-equivalent provider replacement, private secret rotation, automatic fulfillment, and refund revocation separately. Activation codes remain Education-owned learning credentials composed with Mall SPU binding and the entitlement pipeline.
 
 ## Platform administration and governance
 
@@ -82,10 +102,10 @@ This Phase 0 artifact maps API families rather than all 342 operations. Endpoint
 - **Legacy authorization semantics to preserve:** tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
 - **Target:** Mall + Pay + Member + CRM with Education binding
 - **Reuse:** Mall/Pay DTO APIs, Member identity/entitlement/points, CRM services, Infra Job/MQ/audit.
-- **Migration conclusion:** product decision required
-- **Contract gap:** Verified target Pay/Mall APIs expose core seams, but scoped entitlement issuance/revocation, activation codes, reconciliation, commissions, dunning, and referral semantics are not proven. One prior evidence path was malformed; corrected source location is /Users/tiku1/code/tiku-backend/apps/api/src/nest/commerce-reconciliation.module.ts.
-- **Required verification:** Callback/idempotency/amount/refund, entitlement lifecycle, reconciliation, and education fulfillment contract tests.
-- **Open decision:** Choose entitlement/activation-code/coupon model and confirm issuance, revocation, callback, refund, reconciliation, commission, and referral contracts before paid practice.
+- **Migration conclusion:** partially migrated — bounded Education binding/entitlement and activation redemption, native Pay ledgers, terminal legacy aggregate import, tenant-scoped native Mall Product persistence/UI, and native Promotion Coupon template/instance persistence/UI are proven; commerce orchestration remains open
+- **Contract gap:** V4340 provides tenant-scoped native transaction ledgers, callbacks, retry tasks, and existing admin UI; V4350 adds bounded terminal import; V4360 activates native Transfer/Wallet ledgers; V4370 activates native Product; V4380 activates native coupon templates/instances without translating legacy code campaigns. These slices do not connect successful purchases to Education entitlements. Explicit legacy product/code-coupon import, production bulk migration, reviewed opening balances, automatic Pay/Mall fulfillment, refund-driven entitlement revocation, legacy activation-code import, Trade/other Promotion families, settlement reconciliation, commissions, dunning, and referral semantics remain unproven. One prior evidence path was malformed; corrected source location is /Users/tiku1/code/tiku-backend/apps/api/src/nest/commerce-reconciliation.module.ts.
+- **Required verification:** Native order/refund/notify service, tenant-database, and terminal amount/status/provider mapping contracts are delivered. Production export/reconciliation evidence, callback/idempotency integration, entitlement lifecycle, settlement reconciliation, and education fulfillment contract tests remain required.
+- **Open decision:** Keep V4310 activation codes separate from Mall Promotion coupons; confirm automatic issuance, callback, refund, reconciliation, coupon, commission, and referral contracts before broader commerce migration.
 
 ## Background processing, assets, and operational platform