wwjcloud/tools/MIGRATION-RULES.md

WWJCloud Migration Tooling Rules

Purpose: Standardize PHP→NestJS migration for AI-friendly, repeatable generation. Tools only; do not hand-edit generated outputs.

— Scope & Principles —

• NestJS compliance: Follow official module/controller/service/entity/DTO patterns; DI-first; guards/pipes/interceptors.
• Core-only: Generators write strictly under src/core/{module}/.... Do NOT create/modify src/common, src/vendor, or src/config.
• Business-first: Migrate PHP business logic (services/controllers/models/validators). Replace PHP infra calls with src/common/* capabilities.
• Java-structure reference: Organize per module with controllers/, services/, entity/, dto/; controllers orchestrate, services hold business, entities map DB only.

— Contracts & Compatibility —

• Database alignment: Table/column/index/types must match PHP 100%. No new/renamed/removed fields.
• Method alignment: Service method names map 1:1 with PHP. Do not invent names.
• Routing: Keep /adminapi and /api prefixes and controller segmentation consistent with PHP.
• Validation: Map PHP validators to DTO + class-validator/pipes. Behaviorally equivalent.

— Naming & Paths —

• Files: kebab-case filenames
  • Controllers: *.controller.ts
  • Services: *.service.ts
  • Entities: *.entity.ts
• Classes: PascalCase.
• Aliases (tsconfig): @wwjCommon/*, @wwjCore/*, @wwjVendor/*, @/*.

— Infrastructure Mapping —

• Replace PHP infra with Common layer:
  • Guards: @wwjCommon/guards/* (e.g., jwt-auth.guard, roles.guard, optional-auth.guard)
  • Decorators: @wwjCommon/decorators/* (e.g., roles.decorator, public.decorator)
  • Exceptions: @wwjCommon/exceptions/business.exception
  • Pipes: @wwjCommon/validation/pipes/* (e.g., parse-diy-form.pipe, json-transform.pipe)
  • Cache/Queue/DB utilities under @wwjCommon/*
  • Do not reference @wwjCore/* for infra.

— Module Generation —

• Generate src/core/{module}/{module}.module.ts registering discovered controllers/services.
• Entities: detect *.entity.ts; optionally include TypeOrmModule.forFeature([...]) (feature flag).
• Filter non-business directories by default (whitelist/blacklist). Avoid generating modules for technical directories like job/, queue/, workerman/, lang/, etc.

— Generation Stages (feature flags) —

• Commands: disabled by default (we do not use nest-commander).
• Jobs/Listeners: configurable; ensure no duplicate suffixes (avoid JobJob/ListenerListener).
• Routes: no separate route files (NestJS uses decorators).

— Idempotency & Safety —

• Re-runnable: Same inputs → same outputs. Overwrite files in place; create missing directories; never delete parent folders.
• Dry-run mode: Output plan without writing files; provide diff-like summary.
• Logging: Summarize counts for modules/controllers/services/entities/validators, skipped items, and errors.

— Security & Multitenancy —

• Guards: apply standard guards in controllers; enforce role checks and optional auth where applicable.
• Tenant isolation: preserve site_id semantics; avoid exposing sensitive fields in responses.

— Quality Gates —

• After generation (tool-side), optionally run TypeScript compile and ESLint checks. Fail fast and report.
• Remove duplicate imports; standardize import order; ensure resolved alias paths.

— Temporary Artifacts —

• All temporary scripts/docs/reports stay in tools/. Clean up when done. Never write temp files outside tools/.

— Enforcement —

• “Only fix tools, not generated files.” If outputs are wrong, update tools and re-run.

— Versioning & Extensibility —

• Keep infra replacement map versioned and extensible to support future modules and AI evolution.

— Quick Checklist —

• Files are kebab-case; classes are PascalCase
• Controllers only orchestrate/validate; services hold business logic
• Entities map DB 1:1 with PHP schema
• All infra imports use @wwjCommon/*
• /adminapi and /api controllers generated correctly
• Modules register found controllers/services; optional TypeORM feature import
• Commands disabled; jobs/listeners gated; no duplicate suffixes
• Safe write, idempotent, dry-run available; logs emitted