ruoyi-vue-pro/docs/education/migration/02-api-mapping.md

Legacy API Mapping

Phase 0 static assessment generated on 2026-07-29. No build, test, application startup, PostgreSQL connection, or Flyway migration was executed during this assessment.

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

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/auth.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/features/tenant/locator.ts, /Users/tiku1/code/tiku-backend/apps/api/src/features/tenant/resolver.ts
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: System + Member + framework tenant support with an Education context adapter
• Reuse: System TenantCommonApi/TenantApiImpl, TenantContextHolder, TenantSecurityWebFilter, Member/System authentication and UserTypeEnum, framework tenant injection and tenant-ignore only for explicitly authorized platform operations.
• Migration conclusion: decision complete; implementation pending EDU-004
• Selected contract: Public inputs are Tenant Locator Claims, not authenticated identity. Production browser routing derives a host-only claim from valid HTTP(S) Origin, falling back to Referer; both are forgeable by non-browser callers and provide browser UX consistency only. A supplied hostname may confirm that claim, and disagreement is a conflict. Headless clients use tenantHandle, explicitly defined as the target's unique System tenant name under a case-sensitive constrained public contract because no distinct stable Tenant Code exists. Legacy public tenantName is rejected rather than silently aliased.
• Threat model: Successful resolution returns tenant ID/display name and therefore permits available-tenant existence probing. Only unknown, disabled, and expired tenants are indistinguishable. Reuse public throttling/ingress controls and structured abuse metrics; a deployment requiring spoof resistance needs a future authenticated/signed locator, not trust in Origin/Referer or forwarding-header controls.
• Normalization and compatibility: Host identity is lowercase, trimmed, trailing-dot-free, bracket-free for IPv6, and independent of all ports. DNS hosts, IPv4, and IPv6 are accepted when valid; credentials, paths, multi-value input, malformed authorities, and unsupported schemes are rejected. Canonical system_tenant.websites values for this resolver are host-only. Scheme/path/port-bearing stored values do not silently normalize or match; configuration correction is required, or a separate Flyway/data ticket if automated correction is later approved.
• Local activation: Only yudao.education.tenant-resolution.local-development-enabled=true enables local/request-host fallback; default and absence are false, and profiles are not authoritative. With the flag true, code-less configured local-host resolution is allowed and an explicit handle takes precedence.
• Authenticated context: /education/context accepts only a Student Principal: an authenticated LoginUser with userType == UserTypeEnum.MEMBER. User and tenant IDs remain security/tenant-context derived. TenantSecurityWebFilter already fills a missing tenant from the authenticated principal, rejects principal/request-tenant mismatch, requires a tenant for non-ignored URLs, and validates tenant availability; EDU-004 preserves rather than duplicates these checks.
• Ownership and seam: Login-method metadata belongs to Member authentication, not System tenant metadata or Education. EDU-004 removes/deprecates Education loginMethods unless a minimal Member-owned interface is proven necessary. Retain generic System-owned TenantCommonApi; make lookup methods required and add focused TenantApiImpl contract tests. EducationTenantController remains the public claim-consistency/redaction adapter.
• Exact public wire contract: Framework business responses remain HTTP 200. Invalid/malformed/missing/local-forbidden claim is code 1005001003, message 租户识别请求无效, null data. Domain/handle or requested-host conflict is code 1005001008, message 租户识别信息冲突, null data. Unknown/disabled/expired is code 1005001004, message 当前租户不可用, null data, with identical shape. Success is code 0 and data contains only tenantId and displayName; never expose or echo handle, websites, expiry, package, status, private config, or login methods.
• Required EDU-004 verification: Education HTTP tests cover Origin resolution, Referer fallback, forged-header threat-model naming, malformed Origin, Origin/requested-host conflict, untrusted arbitrary hostname, explicit handle, legacy tenantName rejection, unavailable-state exact wire equivalence, host normalization, canonical/non-canonical website behavior, local flag false/true and precedence, domain/handle conflict, anonymous/ADMIN/MEMBER context, redaction, and abuse-control attachment/metrics where a reusable seam exists. System owns adapter contract tests; framework owns existing missing-tenant and authenticated mismatch tests.
• Decision evidence: issues/EDU-003-tenant-resolution-decision.md. Static only; no production or database change was made.

Student core learning loop

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/learning.module.ts:23-113, /Users/tiku1/code/tiku-backend/apps/api/src/features/learning/use-cases.ts, /Users/tiku1/code/tiku-backend/apps/api/src/features/learning/access.ts
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: Education
• Reuse: Education provider/adapter boundary, Member/System identity, database uniqueness and transactions, framework locks/idempotency only as supplements—not replacements—for atomic database claims.
• Migration conclusion: partially migrated
• Contract gap: Verified: commit ce02f8a contains committed access/core controllers, safe projections, and focused tests, while native provider/catalog and additional core-loop work are dirty; these statuses must be separated. Verified: native and Scalar providers disagree on malformed/absent options; QuestionCatalogService and SessionResponseAssembler can emit apparently valid empty options. Verified: submit idempotency performs check-then-insert rather than atomic initial reservation. Inference: core-loop completion and concurrency guarantees are not established.
• Required verification: Provider-neutral tests across Scalar and Java, browsing/collection/practice-create/restore safe projections, malformed/unavailable/unpublished fail-closed cases, cross-tenant cases, and PostgreSQL concurrent same-key/different-key submit tests.
• Open decision: Select the pilot-authoritative provider or require a provider-neutral contract; define valid option structure by question type and absent-option semantics; define atomic submit claim/crash recovery; decide entitlement contract before paid/private practice.

Education catalog and question content

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/catalog.module.ts:74-138, /Users/tiku1/code/tiku-backend/apps/nest/tenant-content.module.ts
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: Education
• Reuse: Education Provider boundary, explicit CatalogScopeQuery, framework tenant context, Infra File public API for future assets.
• Migration conclusion: partially migrated
• Contract gap: Verified: current native reads intentionally run inside TenantUtils.executeIgnore and apply explicit scope predicates; this is a controlled manual-isolation boundary, not proof of a current leak. Verified: V4020 uses ordinary single-column foreign keys, so tenant-owned/public graph consistency is not enforced. Inference: every mapper needs audit and content admission needs composite constraints or equivalent enforcement.
• Required verification: Inventory every mapper, provider contract tests, invalid graph insert tests, malformed/unpublished tests, PostgreSQL Flyway syntax/resource-packaging checks, and runtime migration evidence only when executed.
• Open decision: Choose Scalar-only, native PostgreSQL, or explicit coexistence; define tenant_id=0 PUBLIC graph semantics and composite-key strategy; decide whether source RLS/functions/triggers are contractual.

Auth, student profile, and extended learning

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/auth.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/profile.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/learning.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/features/profile/
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: Member + System + Education, with Infra composition
• Reuse: Member/System auth and profile primitives, System/Infra notifications, Member points/levels where semantics match, Education-specific projections and authorization.
• Migration conclusion: pending migration
• Contract gap: Verified source inventory shows these are distinct required Phase 0 domains, not merely generic context or secondary engagement. Target ownership and compatibility are not established. Inference: the definition-of-done is unsupported until each endpoint/state family is classified.
• Required verification: Endpoint/API mapping, principal and tenant tests, profile redaction, progress/report compatibility, vocabulary state transitions, and explicit retired/product-decision checks.
• Open decision: For every Auth/Profile/extended Learning family, assign Member/System/Education/Infra ownership, compatibility requirement, data disposition, and phase; decide vocabulary, analytics, feedback, exam dates, notifications, points, and badges.

Tenant education operations, appearance, integrations, secrets, and codes

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant-admin-classes.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant-admin-appearance.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant-admin-integrations.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant-admin-secrets.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/tenant-admin-codes.module.ts
• 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.

Platform administration and governance

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/platform-admin-overview.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/platform-admin-permissions.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/platform-admin-*.module.ts
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: System + Pay + Mall + Infra + CRM with Education extensions
• Reuse: System RBAC/DataPermission/AdminUserApi, authorized tenant-ignore mechanisms, Pay/Mall/Infra/CRM public APIs, audit/logging.
• Migration conclusion: pending migration
• Contract gap: Verified source surface is broader than one aggregated platform-admin row. Target seams exist, but object-level ownership, data scopes, and cross-tenant operation policy remain incomplete.
• Required verification: Permission matrix, platform-admin integration, cross-tenant negative, audit-redaction, billing/usage reconciliation, and alert/export tests.
• Open decision: Define separate Student App, Tenant Admin, Platform Admin, public, and internal policies; map each platform surface to System/Pay/Mall/Infra/CRM/Education or explicit retirement.

Commercialization and growth

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/commerce-orders.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/commerce-payments.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/commerce-reconciliation.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/referral-growth.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/referral-crm.module.ts
• 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.

Background processing, assets, and operational platform

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/worker/src/worker-jobs.ts, /Users/tiku1/code/tiku-backend/apps/worker/src/jobs/imports.ts, /Users/tiku1/code/tiku-backend/apps/worker/src/jobs/exports.ts, /Users/tiku1/code/tiku-backend/apps/asset-scanner/src/
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: Infra platform plus owning domain modules
• Reuse: Infra Job, Redis MQ, File, locks, idempotency, logging, tracing, Excel utilities, tenant propagation.
• Migration conclusion: partially migrated
• Contract gap: Verified target primitives exist, but durable claim/lease/heartbeat/retry and malware-scanner equivalence are not proven. Education import/export business state is absent or not verified.
• Required verification: Concurrent claim/lease/recovery, retries/dead letters, scan fail-closed, file access, tenant propagation, audit, and deployment smoke tests.
• Open decision: Confirm Infra claim/lease semantics and scanner ownership, file privacy/retention, legacy asset migration/re-scan, and duplicate-safe at-least-once processing.

Secondary learning, media, AI, and engagement

• Legacy locations: /Users/tiku1/code/tiku-backend/apps/api/src/nest/scoreline.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/video.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/nest/ai.module.ts, /Users/tiku1/code/tiku-backend/apps/api/src/features/profile/
• Legacy authorization semantics to preserve: tenant boundary, principal type, visibility, idempotency, state transitions, and redaction as applicable.
• Target: Education plus AI/Infra/Member/System
• Reuse: AI services, Infra File/notifications, Member points/levels, Education authorization/projections.
• Migration conclusion: product decision required
• Contract gap: Verified legacy capabilities exist, but target equivalence and priority are not established. These cannot remain an undifferentiated P3 bucket if Phase 0 must give every capability a disposition.
• Required verification: Per-capability contract, authorization, entitlement, export/redaction, and migration compatibility tests.
• Open decision: For each capability, assign Education, existing platform ownership, explicit retirement, or later product scope; decide entitlement and safe export/redaction requirements.