wwjcloud-nest-v1/wwjcloud-nest-v1/tools/tools-v1/java-tools/MIGRATION-RULES.md

WWJCloud Migration Tooling Rules

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

— Scope & Principles —

• Java架构参考: 主要架构参考是Java框架 (Spring Boot)，扫描Java项目的service/core, service/admin, service/api结构
• 三层架构: 按照Java的三层结构生成NestJS服务：core(核心业务) + admin(管理服务) + api(接口服务)
• Core依赖: admin/api层服务可以依赖core层服务，类似Java的@Resource ICoreSiteService
• NestJS compliance: Follow official module/controller/service/entity/DTO patterns; DI-first; guards/pipes/interceptors.
• Core-only: Generators write strictly under libs/wwjcloud-core/src/{module}/.... Do NOT create/modify src/common, src/vendor, or src/config.

— 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 (V1 Framework) —

• Use V1框架基础设施层:
  • Cache: @wwjcloud-boot/infra/cache/cache.service (CacheService)
  • Metrics: @wwjcloud-boot/infra/metrics/metrics.service (MetricsService)
  • Tenant: @wwjcloud-boot/infra/tenant/tenant.service (TenantService)
  • Auth: @wwjcloud-boot/infra/auth/* (AuthGuard, RbacGuard)
  • Vendor Services: @wwjcloud-boot/vendor/* (PayService, UploadService, SmsService, NoticeService)
  • 参考Java架构: @Service + 依赖注入，类似Spring Boot模式

— Module Generation —

• Generate libs/wwjcloud-core/src/{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-v1/java-tools/. Clean up when done. Never write temp files outside tools-v1/java-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