ruoyi-vue-pro/docs/education/migration/GOAL.md

Education SaaS Migration Goal

Status: active goal

Source system: /Users/tiku1/code/tiku-backend

Target system: /Users/tiku1/code/ruoyi-vue-pro

Target branch at goal creation: feature/education-core-loop

Created: 2026-07-29

1. Mission

Migrate the valuable business capabilities, data models, rules, state machines, authorization semantics, idempotency guarantees, and API contracts from tiku-backend into the RuoYi-Vue-Pro architecture.

This is a capability migration, not a file-by-file TypeScript-to-Java translation.

The resulting system must be a multi-tenant education SaaS backend that:

1. Places education-specific behavior in yudao-module-education.
2. Reuses RuoYi-Vue-Pro platform modules before adding new infrastructure.
3. Uses the framework's tenant, authentication, RBAC, logging, file, job, messaging, payment, and membership capabilities.
4. Uses PostgreSQL and module-owned Flyway migrations for all forward database changes.
5. Is independently buildable, testable, migratable, and progressively deployable by vertical slice.
6. Does not require the old NestJS service after migration, except for explicitly documented temporary adapters with an exit plan.

2. Non-negotiable architecture rules

2.1 Reuse before building

Legacy capability	Target capability to evaluate first
Login, token, refresh, logout, verification	Member/System authentication
Student and administrator accounts	Member/System users; Education stores domain extensions only
Tenant lookup, status, and isolation	System Tenant and framework tenant support
Roles, menus, permissions, data permission	System RBAC
Payment, refund, channel, callback	Pay
Generic products and orders	Mall and Pay
Membership, level, entitlement, points	Member first; Education only orchestrates domain rules
Notifications, SMS, email	System/Infra messaging capabilities
Uploads and object storage	Infra File
Scheduled and background work	Infra Job or existing messaging facilities
Audit and operation logs	System/Infra logging
AI generation and recommendation	AI
CRM leads and customer follow-up	CRM
Questions, practice, exams, wrong questions, favorites, reports	Education

Reuse means depending on public APIs, framework extension points, or events. Education must not depend on another module's internal ServiceImpl, Mapper, or DO and must not copy platform implementations.

A change outside Education is allowed only when the existing public capability cannot satisfy the need and the new interface is minimal, generic, backward-compatible, tested, and owned by the module that provides the capability.

2.2 Multi-tenancy and identity

• Tenant business DOs inherit TenantBaseDO.
• MyBatis-Plus tenant injection remains the normal isolation mechanism.
• Request bodies and query parameters are never trusted for tenantId or current userId.
• The current tenant and user come from framework security context.
• Student identity reuses Member; administrator identity reuses System.
• Education stores education profiles and relationships, not passwords, tokens, or generic accounts.
• Cross-tenant platform operations use existing tenant-ignore mechanisms with strict permissions; no custom bypass.
• Unique constraints include tenant_id whenever uniqueness is tenant-scoped.

2.3 Security

• Controllers never return DOs directly.
• Question responses strip answers, explanations, scoring rules, correctness flags, and administrative metadata before leaving the service boundary.
• Invisible questions, unavailable tenants, disabled features, and unavailable catalog sources fail closed.
• Logs do not contain tokens, passwords, verification codes, answers, or payment secrets.
• Student App, Tenant Admin, Platform Admin, public, and internal APIs have explicit and separate authorization models.
• Existing System RBAC and permission annotations are used for admin endpoints.

2.4 PostgreSQL and Flyway

All new or changed schema, indexes, constraints, required seed data, backfills, baselines, and Flyway configuration must use the project flyway-postgresql skill.

Required conventions include:

• BIGINT GENERATED BY DEFAULT AS IDENTITY
• TIMESTAMP and CURRENT_TIMESTAMP
• PostgreSQL BOOLEAN
• ON CONFLICT ... DO NOTHING
• ON CONFLICT (...) DO UPDATE SET ... EXCLUDED.column
• COALESCE, TO_CHAR, and EXTRACT where applicable
• module migration path: <module>/src/main/resources/db/migration/<module>/

Published migrations are immutable. Corrections use higher-version forward migrations. Historical sql/mysql/education files are not the delivery mechanism for new database changes. Application-layer tenant isolation must not be replaced by copied Supabase RLS.

Only an actual successful run against PostgreSQL may be reported as a successful database migration. Static SQL review, compilation, packaging, or resource copying must be described accurately as such.

3. Required Phase 0 investigation

Do not start broad feature implementation before completing this investigation.

3.1 Repository and rule inspection

Read and obey:

• target CLAUDE.md;
• target yudao-module-education/README.md;
• source README.md;
• applicable AGENTS.md, module READMEs, database documentation, and .claude/skills/index.yaml;
• actual runtime configuration and Git state.

Inspect both repositories' working trees and histories. Preserve all existing uncommitted work: no reset, destructive checkout, clean, or unrelated rewrite.

3.2 Historical commit review

Review these commits and determine whether their non-Education changes remain justified:

• 11e9cc6 feat(education): add module application shell
• 0f846fd feat(education): resolve student tenant context

Review at least:

• root pom.xml;
• yudao-server/pom.xml;
• ServiceErrorCodeRange;
• TenantCommonApi;
• TenantRespDTO;
• TenantApiImpl;
• historical sql/mysql/education artifacts;
• Education tenant-resolution logic.

Classify each design as retain, adjust, replace, remove by forward correction, or pending decision. Do not revert whole commits merely because one part is unsuitable.

3.3 Legacy capability inventory

Scan at least:

apps/api/src/features
apps/api/src/nest
apps/worker/src
apps/asset-scanner/src
packages
supabase/migrations
supabase/seed*
docs

Cluster capabilities rather than mechanically mapping every endpoint. Cover Auth, Tenant, Profile, Learning, Catalog, Scoreline, Video, AI, Tenant Content, Tenant Admin, Platform Admin, Referral, Commerce, Worker, Asset Scanner, tables, indexes, constraints, RLS, functions, triggers, and seeds.

3.4 Target capability inventory

Inspect Education's current implementation and reusable capabilities in System, Member, Pay, Mall, Infra, AI, CRM, framework starters, and Server integration. Account for both committed and uncommitted implementation; do not rebuild existing slices.

4. Required migration artifacts

Maintain these artifacts under docs/education/migration/ or a reviewed scratch equivalent while discovery is incomplete:

1. current-state.md — verified implementation and working-tree state.
2. capability-matrix.md — grouped legacy-to-target capability matrix.
3. api-mapping.md — legacy method/path and authorization to target contract.
4. database-object-mapping.md — table/RLS/function/trigger/storage disposition.
5. module-reuse-map.md — reusable public APIs and identified gaps.
6. commit-review-11e9cc6.md.
7. commit-review-0f846fd.md.
8. decisions.md — unresolved product or architecture decisions and ADR links.
9. slice-roadmap.md — vertical slices with blocking edges.
10. first-slice.md — first incomplete, bounded, low-risk delivery slice.

Each capability-matrix row must include:

legacy capability
legacy code location
legacy database objects
business value
target module
existing capability to reuse
Education gap
whether another module must change
priority
risk
verification method
current status
evidence
open decision

Allowed status values:

• replaced by RuoYi-Vue-Pro;
• migrated;
• partially migrated;
• pending migration;
• explicitly retired;
• product decision required.

5. Delivery phases

Phase 0 — inventory and architecture mapping

Complete the artifacts above, review the two historical commits, assess current uncommitted work, correct confirmed obsolete documentation, and select the first incomplete vertical slice.

Phase 1 — tenant, identity, and permission baseline

Reuse System Tenant and Member/System Auth, unify Student/Tenant Admin/Platform Admin identity rules, verify cross-tenant protections, and decide whether the TenantCommonApi extension is a valid generic API.

Phase 2 — student core learning loop

Verify and complete only genuine gaps in:

catalog browsing
→ safe question browsing
→ create practice
→ save answer
→ restore practice
→ submit
→ report
→ wrong questions
→ favorites

The current branch may already implement much of this phase. Review before adding anything.

Phase 3 — education content management

Question banks, questions, classifications, catalogs, publishing, imports/exports, resource associations, question videos, and content access control.

Phase 4 — tenant education management

Classes, education student relationships, invitations, education roles, tenant education configuration, education points/badges, learning insight, and operations metrics. Generic users, roles, and tenants remain in Member/System.

Phase 5 — commercialization

Products, orders, payments, refunds, subscriptions or entitlements, reconciliation, collection, commission, and referral relationships. Prefer composition of Mall, Pay, Member, and CRM. Education owns only education-domain bindings and orchestration.

Phase 6 — asynchronous and operational capabilities

Imports/exports, content processing, billing work, notifications, resource scanning, audit, retries, and observability using Infra Job, messaging, File, and logging capabilities.

Each phase must be independently compilable, testable, deployable, and reversible at the application/configuration level.

6. Workflow operating model

This goal is executed as a decision-first, multi-session program:

Phase 0 read-only multi-agent discovery
→ Wayfinder-style decision map
→ domain modeling and module-boundary design
→ migration specification
→ blocker-aware vertical-slice tickets
→ one fresh implementation context per ticket
→ TDD and PostgreSQL/Flyway when applicable
→ standards/spec review
→ security review
→ simplification
→ focused and integration verification

6.1 Multi-agent use

Use multi-agent workflows for broad read-only discovery, independent commit reviews, module capability mapping, adversarial verification, and completeness checks.

Do not allow multiple agents to edit the current dirty working tree concurrently. Implementation is serial by default. Isolated worktrees are permitted only for independent file sets with an explicit integration plan.

6.2 Ticket shape

Tickets are vertical behaviors, not technical layers. A ticket may include migration, DO, Mapper, Service, Controller, tests, and documentation needed to deliver one observable capability.

Good examples:

• a student can browse published catalog content in the current tenant;
• a student can create and restore a practice session;
• a student can idempotently save one answer;
• a student can idempotently submit and read an immutable report;
• a tenant administrator can publish a question.

Avoid tickets such as “create all DOs” or “create all Controllers.” Declare blocking edges explicitly and implement blockers first.

6.3 Skill selection

• flyway-postgresql: every database or Flyway change.
• mattpocock-skills:domain-modeling: ambiguous or overloaded education language.
• mattpocock-skills:codebase-design: module interfaces, provider/adapter seams, and public API boundaries.
• mattpocock-skills:research: external primary-source research, not local repository inventory.
• mattpocock-skills:prototype: throwaway executable exploration for a single unresolved design question.
• mattpocock-skills:tdd: red-green implementation of a concrete behavior.
• mattpocock-skills:diagnosing-bugs: hard defects after establishing a reliable failing command.
• mattpocock-skills:code-review: standards and specification review from a fixed Git point.
• security-review: tenant, identity, authorization, secret, answer, payment, and file boundaries.
• simplify: reuse and structural cleanup after correctness review.
• run and webapp-testing: real application and student-flow verification.

If a named planning skill is unavailable, preserve the same artifacts and gates using repository documents, issue files, and the workflow tool rather than skipping the phase.

7. Implementation rules

Follow the target layering:

controller
service
dal/dataobject
dal/mysql
convert
enums
api
framework/integration

• Controllers perform protocol adaptation and validation.
• Services own transactions, state transitions, authorization-relevant domain checks, and idempotency semantics.
• Mappers own data access only.
• VO, DTO, and DO responsibilities remain distinct.
• Use project CommonResult, paging, validation, conversion, exception, error-code, Redis, lock, transaction, and audit facilities.
• External or legacy coexistence is hidden behind explicit Provider/Adapter boundaries.
• Do not introduce NestJS runtime dependencies or reproduce NestJS Guard/Decorator architecture.

Idempotency and consistency requirements:

• database uniqueness is the final idempotency guard;
• critical writes are transactional;
• do not rely only on check-then-insert;
• duplicate-request response semantics are explicit;
• concurrency is tested;
• external payment, notification, and file calls do not create long database transactions;
• at-least-once consumers define duplicate handling.

8. Verification gates

Every implementation slice runs the minimum sufficient focused tests plus at least:

git diff --check
mvn -pl yudao-server -am -DskipTests clean compile

Behavior changes require focused tests in Education and every affected module. Database changes additionally require PostgreSQL syntax validation, module packaging, and confirmation that migration files appear under target/classes/db/migration/.

Test applicable negative and concurrent scenarios:

• cross-tenant access;
• unauthenticated access;
• unauthorized access;
• duplicate request;
• concurrent request;
• sensitive-field leakage;
• catalog source failure;
• disabled feature;
• historical-data compatibility.

9. Per-slice reporting contract

Before implementation, report:

1. legacy capability and evidence;
2. legacy files and database objects;
3. target module;
4. RuoYi-Vue-Pro capabilities reused;
5. why another module will or will not change;
6. database changes;
7. tests;
8. risks and rollback method.

After implementation, report:

1. changed files;
2. reused modules;
3. new Education domain capability;
4. reasons for every non-Education change;
5. replaced legacy code;
6. unmigrated capabilities;
7. commands actually run and results;
8. whether PostgreSQL migration was actually executed;
9. known risks and recommended next slice.

Do not state “complete” without verifiable files and command results.

10. Prohibitions

Do not:

• embed the old NestJS project;
• mechanically translate all TypeScript files or all 342 APIs;
• duplicate authentication, tenant, RBAC, payment, membership, notification, file, job, or audit platforms in Education;
• trust client userId or tenantId;
• expose answers or explanations;
• introduce MySQL dialect or new MySQL delivery scripts;
• bypass Flyway or modify published migrations;
• depend on internal implementations of other modules;
• weaken security for backward compatibility;
• overwrite unrelated uncommitted work;
• use destructive Git commands;
• claim tests or migrations succeeded without running them;
• begin a broad implementation before Phase 0 identifies the actual gaps.

11. Definition of done

The migration is complete only when:

1. every legacy capability has a reuse, migration, retirement, or decision status;
2. Education-specific behavior resides in Education;
3. platform capabilities are reused through appropriate boundaries;
4. every non-Education modification has a necessity statement and tests;
5. tenant isolation and sensitive-question-field controls are verified;
6. database changes use PostgreSQL Flyway;
7. core vertical flows have automated tests;
8. required compile and diff checks pass;
9. documentation matches the current PostgreSQL/Flyway architecture;
10. existing user changes have not been overwritten;
11. the target can run without the old service, or every temporary dependency has an owner and exit plan.

12. Immediate execution directive

Phase 0 inventory and the first safe-question slice have been executed. Continue through the blocker-aware tickets under docs/education/migration/issues/.

Current execution order is maintained in docs/education/migration/issues/README.md. Do not duplicate the live order here; completed bounded tickets remain historical dependencies, while current work follows the ticket index and its blockers.

Before every ticket:

1. read this Goal, the ticket, relevant decisions, and current Git status;
2. preserve all existing uncommitted work;
3. state the legacy capability, reuse boundary, database impact, tests, risk, and rollback;
4. use a fresh implementation context and work serially in the dirty tree;
5. use flyway-postgresql for any database or Flyway change;
6. finish with focused tests, git diff --check, and mvn -pl yudao-server -am -DskipTests clean compile;
7. report exact results and never claim PostgreSQL migration success without a real successful run.

Questions that can be answered from code, Git history, configuration, tests, or documentation must be investigated rather than asked. Ask only for genuine product decisions whose outcomes materially change implementation.