@gaias/basenode 1.0.12 → 1.0.13

package/CLAUDE.md

@@ -0,0 +1,757 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Quick Start](#quick-start)
+- [Development Commands](#development-commands)
+- [Database Code Generation](#database-code-generation)
+- [Architecture](#architecture)
+  - [Bootstrap System](#bootstrap-system)
+  - [Configuration Management](#configuration-management)
+  - [Dependency Injection](#dependency-injection)
+  - [Controller Pattern](#controller-pattern)
+  - [Data Layer](#data-layer)
+  - [Validation and Transformation](#validation-and-transformation)
+  - [Health Check](#health-check)
+  - [Pagination](#pagination)
+  - [Caching](#caching)
+  - [Distributed Events](#distributed-events)
+  - [Leader Election](#leader-election)
+  - [API Gateway Integration](#api-gateway-integration)
+  - [Error Handling](#error-handling)
+  - [Logging](#logging)
+- [TypeScript Configuration](#typescript-configuration)
+- [Project Structure](#project-structure)
+- [Key Dependencies](#key-dependencies)
+- [Entry Point](#entry-point)
+- [Best Practices](#best-practices)
+- [Module References](#module-references)
+- [Publishing](#publishing)
+
+## Project Overview
+
+`@gaias/basenode` (v1.0.13) is a Node.js API development framework built on Koa, TypeORM, TypeDI, and routing-controllers. It provides a microframework architecture with built-in support for RESTful APIs, WebSocket controllers, database ORM, distributed events via RabbitMQ, Redis caching, and API gateway integration with APISIX.
+
+**Requirements:**
+- Node.js: >=18.0.0
+- Yarn: >=1.22.x
+- MariaDB/MySQL: 5.7+ or 8.0+ (for production use)
+- Redis: 6.0+ (optional, for caching and leader election)
+- RabbitMQ: 3.8+ (optional, for distributed events)
+
+## Quick Start
+
+1. **Install dependencies:**
+   ```bash
+   yarn install
+   ```
+
+2. **Configure database:**
+   - Edit `cfg/database.yml` with your MariaDB/MySQL connection details
+   - Edit `cfg/redis.yml` for Redis (if using caching)
+   - Edit `cfg/rabbitmq.yml` for RabbitMQ (if using distributed events)
+
+3. **Set environment variables (optional):**
+   ```bash
+   # Create .env file or export variables
+   NODE_ENV=development                        # Environment: development, production, test
+   ENABLE_API_GATEWAY=true                     # Enable APISIX gateway registration
+   API_GATEWAY_HOST_PORT=192.168.1.100:9180    # Gateway admin API address
+   DOMAINS=example.com,*.example.com           # Allowed domains for gateway
+   ```
+
+4. **Generate database code (optional):**
+   ```bash
+   # Define tables in gen_db.json, then:
+   yarn gen:db
+   ```
+
+5. **Run development server:**
+   ```bash
+   yarn dev
+   # App starts on http://localhost:3000 (or configured port)
+   # Health check: http://localhost:3000/_healthcheck
+   ```
+
+6. **Run tests and linting:**
+   ```bash
+   yarn test
+   yarn lint
+   ```
+
+## Development Commands
+
+### Running the Application
+```bash
+# Development mode with hot reload
+yarn dev
+
+# Development mode with API gateway enabled (production-like)
+yarn devPro
+
+# Run compiled example app using ncc
+yarn ncc:run
+```
+
+### Building
+```bash
+# Build for publishing (transpiles src/ to dist/)
+yarn prepublish
+
+# Build single-file executable with ncc
+yarn ncc:build
+```
+
+### Linting
+```bash
+# Type check and lint
+yarn lint
+
+# Auto-fix linting issues
+yarn lint:fix
+```
+
+### Security
+```bash
+# Run security audit on dependencies
+yarn security
+
+# Show audit summary only
+yarn security:summary
+
+# Output audit results in JSON format
+yarn security:json
+
+# Generate detailed security report
+yarn security:report
+```
+
+**Security Policy:** See `SECURITY.md` for comprehensive security guidelines, vulnerability reporting procedures, and mitigation strategies. The project includes automated security auditing via `yarn audit` and custom reporting tools.
+
+### Testing
+```bash
+# Run all tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Run tests with coverage report
+yarn test:coverage
+```
+
+**Testing Framework:** Jest is configured for unit and integration testing. Test files should use `*.test.ts` or `*.spec.ts` naming convention.
+
+### Dependency Management
+```bash
+# Check for outdated dependencies
+yarn deps:check
+
+# Update dependencies to latest versions
+yarn deps:update
+
+# Update dependencies (alternative command)
+yarn upver
+```
+
+### Database Code Generation
+
+The framework includes automated code generation tools for database entities and repositories:
+
+```bash
+# Generate entities from database schema
+yarn gen:db-schema
+
+# Generate repository classes from entities
+yarn gen:db-repo
+
+# Generate both entities and repositories, then fix linting
+yarn gen:db
+
+# Generate index.ts files for all modules
+yarn gen:idx
+```
+
+**Important:** Before running database generation:
+1. Ensure MariaDB/MySQL is running and accessible
+2. Configure database connection in `cfg/database.yml`
+3. Define which tables to generate in `gen_db.json` (array of table names)
+
+The generators use `typeorm-model-generator` with custom Mustache templates (`tools/repository.mst`) to create:
+- **Entities** in `example/entities/` (or configured output path)
+- **Repositories** in `example/repositories/` with `Repo` suffix
+
+Generated repositories extend `BaseRepository<T>` and won't be overwritten if they already exist.
+
+### Other Commands
+```bash
+# Generate RSA keys for JWT (stored in ./keys/)
+yarn gen:keys
+
+# Update build number
+yarn buildNum
+
+# Pre-commit hook (runs linting)
+yarn precommit
+```
+
+## Architecture
+
+### Bootstrap System
+
+The application uses a microframework loader pattern orchestrated by `src/server/bootstrap.ts`. The bootstrap function accepts a `BootstrapOption` that combines multiple loader configurations and sequentially initializes:
+
+1. **TypeORM Loader** - Database connection and entity registration
+2. **Redis Loader** - Redis client initialization
+3. **RabbitMQ Loader** - Distributed event system setup
+4. **Koa Loader** - Web server with RESTful and WebSocket controllers
+5. **API Gateway Loader** - APISIX integration for service registration
+
+Each loader can be disabled via flags (`disableDatabase`, `disableRedis`, `disableEvent`).
+
+### Configuration Management
+
+Configuration is managed through YAML files in the `cfg/` directory, loaded by `ConfigManager`:
+
+- `application.yml` - App name, version, port, and general settings
+- `database.yml` - MariaDB/MySQL connection configuration
+- `redis.yml` - Redis connection settings (host, port, password, db)
+- `rabbitmq.yml` - RabbitMQ connection URL and settings
+- `logger.yml` - Pino logger configuration (level, pretty print)
+- `apisix.yml` - API gateway settings (admin URL, credentials)
+- `openapiCfg.yml` - OpenAPI/Swagger documentation configuration
+
+Configuration files support environment-specific overrides (e.g., `application.development.yml`, `application.production.yml`). The system automatically loads the base config and merges environment-specific settings based on `NODE_ENV`.
+
+Access configuration via:
+```typescript
+import { ConfigManager } from '@/libs/configure';
+
+const appConfig = ConfigManager.getConfig<ApplicationConfig>('application');
+const dbConfig = ConfigManager.getConfig<DatabaseConfig>('database');
+```
+
+### Dependency Injection
+
+The framework uses TypeDI for IoC. Services and repositories are decorated with `@Service()` and injected via `@Inject()` or constructor injection. The `Container` is automatically configured during bootstrap.
+
+**Simplified Imports via `deps` Module:**
+
+The framework provides a unified dependency export module (`src/libs/deps`) with short namespace aliases for cleaner imports. See `src/libs/deps/README.md` for comprehensive documentation.
+
+```typescript
+import { rest, di, orm, cv, ct, ws, api, tx } from '@/libs/deps';
+
+// Instead of:
+// import { Service } from 'typedi';
+// import { JsonController, Get, Post, Body } from 'routing-controllers';
+// import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
+// import { IsString, IsEmail } from 'class-validator';
+
+@rest.JsonController('/users')  // routing-controllers
+@di.Service()                    // typedi
+class UserController {
+  @rest.Get('/')
+  async getAll() { return []; }
+
+  @rest.Post('/')
+  async create(@rest.Body() data: CreateUserDto) {
+    // rest.Body auto-enables excludeExtraneousValues for security
+    return {};
+  }
+}
+```
+
+**Namespace Aliases:**
+- `ct` = class-transformer
+- `cv` = class-validator
+- `di` = typedi
+- `orm` = typeorm
+- `tx` = typeorm-transactional
+- `rest` = routing-controllers (enhanced with secure Body decorator)
+- `ws` = socket-controllers
+- `api` = routing-controllers-openapi
+
+### Controller Pattern
+
+**RESTful Controllers** extend `UniversalController` and use `routing-controllers` decorators:
+- `@JsonController()` - Define controller class
+- `@Get()`, `@Post()`, `@Put()`, `@Delete()` - HTTP methods with optional scopes
+- Method signature: `@Method(path, scope?, module?)`
+- `UniversalController` provides CRUD operations for entities via `getUniversalService(Entity)`
+
+**WebSocket Controllers** use `socket-controllers`:
+- Use `@OnConnect`, `@OnDisconnect`, `@OnMessage` decorators
+- Registered via `wsControllers` in bootstrap options
+
+### Data Layer
+
+**Entities** are TypeORM entities with decorators (`@Entity`, `@Column`, `@PrimaryGeneratedColumn`, etc.). Auto-generated from database schema.
+
+**Repositories** extend `BaseRepository<Entity>` providing:
+- `find()`, `findOne()`, `findById()`
+- `save()`, `update()`, `delete()`
+
+**UniversalService** provides high-level CRUD with transformation:
+- `create()`, `readById()`, `update()`, `remove()`
+- `getAll(VoClass)`, `query(search, options)` - With pagination support
+- Automatic VO transformation using `class-transformer`
+
+### Validation and Transformation
+
+Use `class-validator` decorators on VO (Value Object) classes wrapped with `@i18n()` for internationalized error messages:
+```typescript
+class UserVo {
+  @i18n(IsString)
+  @i18n(MaxLength, 50)
+  userName: string;
+}
+```
+
+**⚠️ Security - URL Validation:**
+Use `@IsSafeUrl()` instead of `@IsUrl()` to avoid CVE-2025-56200 in validator.js:
+```typescript
+import { IsSafeUrl } from '@/libs/validator';
+
+class UserVo {
+  @IsSafeUrl()  // ✅ Secure
+  website: string;
+
+  @IsSafeUrl({ protocols: ['https'] })
+  secureUrl: string;
+}
+```
+See `src/libs/validator/README.md` and `SECURITY.md` for details.
+
+Transform responses with `@Transform(VoClass)` decorator on controller methods.
+
+### Health Check
+
+Built-in health check endpoint at `/_healthcheck` provided by `HealthCheckController`:
+
+```typescript
+// Basic health check
+GET /_healthcheck
+// Response: { healthy: true, dbAlive: true }
+
+// Detailed health check with OS info
+GET /_healthcheck?os=true
+// Response includes system info: hostname, platform, CPU, memory, network
+```
+
+The health check automatically:
+- Tests database connectivity
+- Reports server network information
+- Optionally provides OS-level metrics (CPU, memory, uptime)
+
+### Pagination
+
+Complete pagination solution in `src/libs/pagination` with TypeORM integration:
+
+**PaginationIn** - Standardized pagination request parameters:
+```typescript
+class PaginationIn {
+  pageIndex?: number;    // Page number (starts from 1)
+  recordIndex?: number;  // Record offset (starts from 0) - for infinite scroll
+  pageSize: number = 25; // Items per page
+  search?: string;       // Search keyword
+  sort?: string;         // Sort fields (e.g., "!createdAt" for DESC)
+}
+```
+
+**PaginationOut** - Pagination response with auto-transformation:
+```typescript
+// Service example
+async search(pagination: PaginationIn): Promise<PaginationOut<UserVo, User>> {
+  const qb = this.userRepo.createQueryBuilder('user');
+
+  // Add search conditions
+  if (pagination.search) {
+    qb.where('user.name LIKE :search', { search: `%${pagination.search}%` });
+  }
+
+  // Add sorting (auto-converts camelCase to snake_case)
+  setSorting(qb, 'user', ...pagination.sort?.split(',') || []);
+
+  // Calculate pagination
+  const total = await qb.getCount();
+  const { skip, take } = skipAndTake(total, pagination);
+  const data = await qb.skip(skip).take(take).getMany();
+
+  // Return with auto-transformation to VO
+  return new PaginationOut(total, pagination.pageSize, UserVo, data);
+}
+```
+
+**Sorting features:**
+- Single/multiple field sorting: `"createdAt"` or `"status,!createdAt"`
+- Descending order: prefix with `!` (e.g., `"!updatedAt"`)
+- Auto-converts camelCase to snake_case for database columns
+- Helper functions: `setSorting()`, `getSorting()`, `skipAndTake()`
+
+### Caching
+
+Two-level caching system:
+
+**L1 Cache** - In-memory with TTL:
+```typescript
+@Get('/path')
+@L1Cache({ ttlSeconds: 60 })
+async method() { }
+```
+
+**L2 Cache** - Redis-backed via `CacheService`:
+```typescript
+@Inject()
+private cacheService: CacheService;
+
+await this.cacheService.set('key', value, ttl);
+await this.cacheService.get('key');
+```
+
+### Distributed Events
+
+RabbitMQ-based pub/sub system via `DistributedEvents`:
+
+**Publishing events:**
+```typescript
+events.pub('eventName', { data });
+```
+
+**Subscribing to events:**
+```typescript
+events.sub(['event.pattern.*']);
+events.on('RemoteEvent', (eventName, data) => { });
+```
+
+Event handlers are classes decorated with `@Service()` registered in `eventsHandlers` bootstrap option.
+
+### Leader Election
+
+Redis-based leader election for distributed systems using the `Leader` service:
+```typescript
+await Container.get(Leader).config({ project: 'ProjectName' }).elect();
+```
+
+Emits `elected` and `revoked` events. Useful for scheduled tasks that should only run on one instance.
+
+### API Gateway Integration
+
+Automatic service registration with APISIX when `ENABLE_API_GATEWAY=true`. Routes are auto-discovered and registered with the gateway on startup.
+
+### Error Handling
+
+Use `BizError` for business logic errors with i18n support:
+```typescript
+throw new BizError('error.key');
+// or with params
+throw new BizError({ key: 'error.key', param: { name: 'value' } });
+```
+
+Use `ValidationHelper.check()` for custom validation logic.
+
+### Logging
+
+Pino-based logging via `Logger.getLogger(context)`:
+```typescript
+private logger = Logger.getLogger(MyClass);
+this.logger.info('message');
+this.logger.error('error', err);
+```
+
+## TypeScript Configuration
+
+- Outputs to `temp/` during development
+- Uses path alias `@/*` for `src/*`
+- Decorators enabled (`experimentalDecorators`, `emitDecoratorMetadata`)
+- Strict mode enabled
+
+## Project Structure
+
+```
+src/
+  libs/              # Framework components
+    apisix/          # APISIX HTTP client and templates
+    cache/           # Two-level caching (L1/L2)
+    configure/       # YAML configuration management
+    deps/            # Dependency library exports (ct, cv, di, orm, rest, ws, api, tx)
+    error/           # Error handling (BizError, ErrorHandler)
+    gateway/         # API Gateway integration loader
+    generator/       # ID generation (nanoid, snowflake)
+    healthcheck/     # Health check endpoint controller
+    koa/             # Koa server setup and middleware
+    leader/          # Redis-based leader election
+    logger/          # Pino logger wrapper
+    network/         # Network utilities (local IP detection)
+    orm/             # TypeORM extensions (BaseRepository)
+    pagination/      # Pagination utilities (PaginationIn/Out, sorting)
+    rabbitmq/        # RabbitMQ distributed events
+    redis/           # Redis client wrapper
+    register/        # API route registration and metadata
+    type/            # Type definitions and builders
+    universal/       # UniversalController/Service for CRUD
+    validator/       # Validation helpers (i18n, SafeUrlValidator)
+  server/            # Bootstrap logic
+  utils/             # Utilities (JWT, crypto, YAML, transformer)
+
+example/             # Example application
+  app.ts             # Entry point
+  controllers/       # RESTful controllers
+  wsControllers/     # WebSocket controllers
+  entities/          # TypeORM entities (auto-generated)
+  repositories/      # Repository classes (auto-generated)
+  services/          # Business logic services
+  vo/                # Value Objects (DTOs)
+  events/            # Distributed event handlers
+
+cfg/                 # YAML configuration files
+  application.yml    # App settings (name, version, port)
+  database.yml       # Database connection
+  redis.yml          # Redis connection
+  rabbitmq.yml       # RabbitMQ connection
+  logger.yml         # Logger settings
+  apisix.yml         # API gateway settings
+  openapiCfg.yml     # OpenAPI/Swagger config
+
+tools/               # Development tools
+  DBSchemaGenerator.ts      # Generate entities from DB schema
+  RepositoryGenerator.ts    # Generate repository classes
+  repository.mst            # Mustache template for repos
+```
+
+## Key Dependencies
+
+### Core Framework
+- **Koa** (^3.0.3) - Lightweight web framework
+- **routing-controllers** (^0.11.3) - Decorator-based RESTful API routing
+- **socket-controllers** (^0.3.1) - Decorator-based WebSocket controllers
+- **TypeDI** (^0.10.0) - Dependency injection container
+- **microframework** (^0.6.4) - Loader pattern for modular bootstrap
+
+### Data Layer
+- **TypeORM** (^0.3.27) - SQL ORM with full TypeScript support
+- **typeorm-transactional** (^0.5.0) - Declarative transaction management
+- **mysql2** (^3.15.2) - MySQL/MariaDB driver
+- **class-validator** (^0.14.2) - Decorator-based validation
+- **class-transformer** (^0.5.1) - Object-to-class transformation
+
+### Caching & Messaging
+- **ioredis** (^5.8.1) - Redis client with clustering support
+- **amqplib** (^0.10.9) - RabbitMQ client for distributed events
+
+### API Documentation
+- **routing-controllers-openapi** (^5.0.0) - OpenAPI/Swagger spec generation
+- **class-validator-jsonschema** (^5.1.0) - JSON Schema from validators
+
+### Utilities
+- **pino** (^10.0.0) + **pino-pretty** (^11.0.0) - High-performance logger
+- **jsonwebtoken** (^9.0.2) - JWT authentication
+- **lodash** (^4.17.21) - Utility functions
+- **nanoid** (^5.1.6) - Compact unique ID generator
+- **axios** (^1.12.2) - HTTP client
+- **js-yaml** (^4.1.0) - YAML parser for configuration
+
+### Recent Dependency Updates & Migration Notes
+
+**TypeORM Transaction Management:** The project has migrated from `typeorm-transactional-cls-hooked` to `typeorm-transactional` (v0.5.0). The new library:
+- No longer depends on `cls-hooked`, improving performance and compatibility
+- Provides the same `@Transactional()` decorator API (no code changes needed)
+- Requires `addTransactionalDataSource(dataSource)` during TypeORM initialization
+- Better support for async/await and modern Node.js versions
+
+**Repository Injection:** `typeorm-typedi-extensions` has been removed. Use direct TypeDI injection instead:
+```typescript
+// Old way (deprecated)
+// import { OrmRepository } from 'typeorm-typedi-extensions';
+// @OrmRepository(User) private userRepo: Repository<User>;
+
+// New way (current)
+@Service()
+class UserService {
+  @Inject(() => UserRepo)
+  private userRepo: UserRepo;
+}
+```
+
+**Security Updates:** The project uses Yarn resolutions to enforce secure versions of transitive dependencies:
+- `validator` (^13.12.0) - Addresses CVE-2025-56200 (mitigated via SafeUrlValidator)
+- `xml2js` (^0.6.2) - Fixes XML parsing vulnerabilities
+- `tmp` (^0.2.4) - Secure temporary file handling
+- `axios` (^1.12.2+) - Latest security patches
+- See `package.json` resolutions and `SECURITY.md` for complete list
+
+## Entry Point
+
+Example app entry: `example/app.ts`
+
+Import and call `bootstrap()` with configuration:
+```typescript
+bootstrap({
+  restfulControllers: [...controllers],
+  wsControllers: [...wsControllers],
+  entities: [...entities],
+  eventsHandlers: [...handlers],
+})
+```
+
+## Best Practices
+
+### Controller Design
+- Extend `UniversalController` for standard CRUD operations
+- Use `@rest.Body()` for request body (auto-enables security filtering)
+- Apply `@Transform(VoClass)` decorator for response transformation
+- Group related endpoints under a single controller
+- Use scopes for role-based access control (e.g., `@Get('/', 'admin')`)
+
+### Service Layer
+- Keep controllers thin, business logic in services
+- Use `UniversalService` for common CRUD operations
+- Apply `@Transactional()` decorator for database transactions
+- Inject repositories via TypeDI: `@Inject(() => UserRepo)`
+
+### Data Validation
+- Always validate input with `class-validator` decorators
+- Wrap validators with `@i18n()` for internationalized error messages
+- Use `@IsSafeUrl()` instead of `@IsUrl()` to avoid CVE-2025-56200
+- Mark optional fields with `@IsOptional()`
+
+### Database Operations
+- Use TypeORM query builder for complex queries
+- Apply pagination with `PaginationIn` and `PaginationOut`
+- Use `setSorting()` helper for dynamic sorting
+- Never concatenate user input into SQL queries (use parameterized queries)
+
+### Error Handling
+- Throw `BizError` for business logic errors with i18n keys
+- Let the framework handle routing-controllers validation errors
+- Use `ValidationHelper.check()` for custom validation logic
+- Log errors with context: `this.logger.error('message', error)`
+
+### Performance
+- Use L1 cache (`@L1Cache`) for frequently accessed, rarely changing data
+- Use L2 cache (Redis) for shared state across instances
+- Implement pagination for list endpoints
+- Use leader election for scheduled tasks in distributed systems
+
+### Security
+- Review `SECURITY.md` before adding dependencies
+- Run `yarn security:report` regularly
+- Never commit sensitive data (use `.env` files)
+- Use `@Authorized()` decorator for protected endpoints
+- Validate all user input, sanitize output
+
+## Module References
+
+For detailed documentation on specific modules:
+- **deps module**: `src/libs/deps/README.md` - Unified dependency exports
+- **validator**: `src/libs/validator/README.md` - Validation helpers and SafeUrlValidator
+- **apisix**: `src/libs/apisix/README.md` - API gateway integration
+- **gateway**: `src/libs/gateway/README.md` - Gateway loader
+- **generator**: `src/libs/generator/README.md` - ID generation
+- **koa**: `src/libs/koa/README.md` - Koa server setup
+- **network**: `src/libs/network/README.md` - Network utilities
+- **rabbitmq**: `src/libs/rabbitmq/README.md` - Distributed events
+- **register**: `src/libs/register/README.md` - API route registration
+- **type**: `src/libs/type/README.md` - Type utilities
+- **universal**: `src/libs/universal/README.md` - Universal CRUD patterns
+- **Security**: `SECURITY.md` - Comprehensive security guidelines
+
+## Publishing
+
+This is a private npm package (`UNLICENSED`). Publishing requires authentication:
+```bash
+npm_config__auth=<base64_token> yarn publish --access restricted
+```
+
+Before publishing:
+1. Update version in `package.json`
+2. Run `yarn buildNum` to update build number
+3. Run `yarn security:report` to check for vulnerabilities
+4. Run `yarn test` to ensure all tests pass
+5. Run `yarn lint` to check code quality
+6. Update changelog/release notes
+
+## Contributing Guidelines
+
+### Code Style
+- Follow existing code conventions
+- Use TypeScript strict mode
+- Run `yarn lint:fix` before committing
+- Use meaningful variable and function names
+- Add JSDoc comments for public APIs
+
+### Git Workflow
+1. Create feature branch from `develope`
+2. Make changes with descriptive commits
+3. Run tests and linting
+4. Create pull request to `develope` (not `main`)
+5. Wait for code review
+
+### Pre-commit Hooks
+The project uses Husky for git hooks:
+- Automatic linting on commit
+- Tests run before push (if configured)
+
+### Adding New Dependencies
+1. Check for security vulnerabilities: `npm info <package>`
+2. Add dependency: `yarn add <package>`
+3. Run security audit: `yarn security:report`
+4. Document breaking changes or new features
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Database connection fails**
+- Verify `cfg/database.yml` connection string
+- Check MariaDB/MySQL is running
+- Ensure database user has proper permissions
+
+**Issue: Redis connection fails**
+- Check Redis is running: `redis-cli ping`
+- Verify `cfg/redis.yml` settings
+- Can disable Redis by setting `disableRedis: true` in bootstrap
+
+**Issue: TypeORM entity not found**
+- Ensure entity is registered in bootstrap `entities` array
+- Check entity file has `@Entity()` decorator
+- Verify import path is correct
+
+**Issue: Validation errors not showing**
+- Ensure DTO uses `@i18n()` wrapper for validators
+- Check `class-validator` decorators are applied
+- Verify `class-transformer` is properly configured
+
+**Issue: Build fails with decorator errors**
+- Check `tsconfig.json` has `experimentalDecorators: true`
+- Ensure `emitDecoratorMetadata: true` is set
+- Verify `reflect-metadata` is imported at app entry
+
+## Additional Resources
+
+### Framework Documentation
+- [TypeORM Documentation](https://typeorm.io/)
+- [routing-controllers Guide](https://github.com/typestack/routing-controllers)
+- [TypeDI Documentation](https://github.com/typestack/typedi)
+- [class-validator Decorators](https://github.com/typestack/class-validator)
+- [class-transformer Guide](https://github.com/typestack/class-transformer)
+
+### Infrastructure
+- [Koa.js Website](https://koajs.com/)
+- [Redis Documentation](https://redis.io/docs/)
+- [RabbitMQ Tutorials](https://www.rabbitmq.com/tutorials)
+- [APISIX Documentation](https://apisix.apache.org/docs/)
+
+### Tools
+- [Pino Logger](https://github.com/pinojs/pino)
+- [Jest Testing](https://jestjs.io/)
+- [ESLint Rules](https://eslint.org/docs/rules/)
+
+---
+
+**Last Updated:** 2025-10-19
+**Framework Version:** 1.0.13
+**Maintainer:** FOT Team