77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
|
### 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
|
||
|
|
|
||
|
|
|