@gaias/basenode 1.0.13 → 1.0.40

package/CLAUDE.md

@@ -33,7 +33,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+`@gaias/basenode` (v1.0.24) 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
@@ -125,12 +125,14 @@ yarn security:summary
 # Output audit results in JSON format
 yarn security:json
 
-# Generate detailed security report
-yarn security:report
+# Run enhanced security check with mitigation context (recommended)
+yarn security:check
 ```
 
 **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.
 
+**Vulnerability Mitigation:** See `VULNERABILITY_MITIGATION.md` for detailed information about known vulnerabilities and their mitigation status. The enhanced security check (`yarn security:check`) provides contextual information about mitigated vulnerabilities and exit code 0 when all vulnerabilities are properly mitigated.
+
 ### Testing
 ```bash
 # Run all tests
@@ -752,6 +754,7 @@ The project uses Husky for git hooks:
 
 ---
 
-**Last Updated:** 2025-10-19
-**Framework Version:** 1.0.13
+**Last Updated:** 2025-10-23
+**Framework Version:** 1.0.24
+**Build Number:** 251022024
 **Maintainer:** FOT Team

package/README.md

@@ -1,55 +1,590 @@
-# basenode
+# @gaias/basenode
 
+[![Version](https://img.shields.io/badge/version-1.0.24-blue.svg)](https://github.com/gaias/basenode)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-UNLICENSED-red.svg)]()
 
-# README #
+A comprehensive Node.js API development framework built on Koa, TypeORM, TypeDI, and routing-controllers. Provides a microframework architecture with built-in support for RESTful APIs, WebSocket controllers, database ORM, distributed events, Redis caching, and API gateway integration.
 
-## Please follow the step by step to startup your fotapi project.
+## Features
 
-* Set fot npm private repository
-++++
-Already set configs in project level .npmrc & .yarnrc.
-Change the npm password by setting env if you need to submit code.
-++++
-[source, shell]
-----
-echo -n 'myuser:mypassword' | openssl base64
-npm_config__auth=xxxxxx yarn publish
-----
+- **Modern Framework Stack**: Koa 3.x, TypeORM 0.3.x, TypeDI, routing-controllers
+- **TypeScript First**: Full TypeScript support with decorators and strict type checking
+- **RESTful & WebSocket**: Support for both REST APIs and WebSocket controllers
+- **Database ORM**: TypeORM with MySQL/MariaDB support, automatic entity generation
+- **Dependency Injection**: TypeDI-based IoC container for clean architecture
+- **Validation**: class-validator with i18n support for error messages
+- **Caching**: Two-level caching (L1 in-memory, L2 Redis)
+- **Distributed Events**: RabbitMQ-based pub/sub system
+- **API Gateway**: APISIX integration for service registration
+- **Leader Election**: Redis-based leader election for distributed systems
+- **Health Check**: Built-in health check endpoint with system metrics
+- **Pagination**: Complete pagination solution with sorting support
+- **Security**: Built-in security features, vulnerability tracking, and mitigation
+- **OpenAPI**: Automatic OpenAPI/Swagger documentation generation
+- **Development Tools**: Hot reload, linting, testing, code generation
 
-yarn publish --access  restricted
+## Quick Start
 
-----
-* Install yarn packages
-[source, shell]
-----
+### Prerequisites
+
+- Node.js >= 18.0.0
+- Yarn >= 1.22.x
+- MariaDB/MySQL 5.7+ or 8.0+ (for production)
+- Redis 6.0+ (optional, for caching)
+- RabbitMQ 3.8+ (optional, for distributed events)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/gaias/basenode.git
+cd basenode
+
+# Install dependencies
 yarn install
-----
+```
+
+### Configuration
+
+1. **Database Configuration**
+
+Edit `cfg/database.yml`:
+```yaml
+mariaDBUrl: mysql://username:password@localhost:3306/database
+output: ./example
+```
+
+2. **Application Configuration**
+
+Edit `cfg/application.yml`:
+```yaml
+appName: example
+version: 1
+port: 3000
+privateKeyPath: ./keys/privateKey
+publicKeyPath: ./keys/publicKey
+```
+
+3. **Redis Configuration** (Optional)
+
+Edit `cfg/redis.yml`:
+```yaml
+host: localhost
+port: 6379
+password: your_password
+db: 0
+```
+
+4. **RabbitMQ Configuration** (Optional)
+
+Edit `cfg/rabbitmq.yml`:
+```yaml
+url: amqp://localhost:5672
+```
+
+5. **Environment Variables** (Optional)
+
+Create a `.env` file or export variables:
+```bash
+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
+```
+
+### Running the Application
 
-* Set up your marinedb and import the sql data in file mysqlsampledatabase.sql, then change the db address in ./cfg/database.development.yaml
+```bash
+# Development mode with hot reload
+yarn dev
+
+# Development mode with API gateway enabled
+yarn devPro
+
+# Production mode (after building)
+yarn ncc:run
+```
+
+The application will start on `http://localhost:3000` (or configured port).
+
+Access the health check endpoint: `http://localhost:3000/_healthcheck`
+
+## Project Structure
+
+```
+.
+├── src/                    # Framework source code
+│   ├── libs/              # Framework components
+│   │   ├── apisix/        # APISIX HTTP client
+│   │   ├── cache/         # Two-level caching system
+│   │   ├── configure/     # YAML configuration management
+│   │   ├── deps/          # Dependency library exports
+│   │   ├── error/         # Error handling
+│   │   ├── gateway/       # API Gateway integration
+│   │   ├── generator/     # ID generation (nanoid, snowflake)
+│   │   ├── healthcheck/   # Health check endpoint
+│   │   ├── koa/           # Koa server setup
+│   │   ├── leader/        # Redis-based leader election
+│   │   ├── logger/        # Pino logger wrapper
+│   │   ├── network/       # Network utilities
+│   │   ├── orm/           # TypeORM extensions
+│   │   ├── pagination/    # Pagination utilities
+│   │   ├── rabbitmq/      # RabbitMQ distributed events
+│   │   ├── redis/         # Redis client wrapper
+│   │   ├── register/      # API route registration
+│   │   ├── type/          # Type definitions
+│   │   ├── universal/     # Universal CRUD patterns
+│   │   └── validator/     # Validation helpers
+│   ├── server/            # Bootstrap logic
+│   └── utils/             # Utilities (JWT, crypto, YAML)
+├── example/               # Example application
+│   ├── app.ts            # Entry point
+│   ├── controllers/       # RESTful controllers
+│   ├── wsControllers/     # WebSocket controllers
+│   ├── entities/          # TypeORM entities
+│   ├── repositories/      # Repository classes
+│   ├── services/          # Business logic services
+│   ├── vo/                # Value Objects (DTOs)
+│   └── events/            # Distributed event handlers
+├── cfg/                   # YAML configuration files
+│   ├── application.yml    # App settings
+│   ├── 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
+│   ├── RepositoryGenerator.ts    # Generate repositories
+│   └── repository.mst            # Mustache template
+├── docs/                  # Documentation
+├── k8s/                   # Kubernetes manifests
+└── keys/                  # JWT keys (generated)
+```
+
+## Development Commands
 
-* Run project
-[source, shell]
-----
+### Running
+
+```bash
+# Development with hot reload
 yarn dev
-----
 
+# Development with API gateway
+yarn devPro
+
+# Run compiled app
+yarn ncc:run
+```
+
+### Building
+
+```bash
+# Build for publishing
+yarn build:publish
+
+# Build single-file executable
+yarn ncc:build
+```
+
+### Database Code Generation
+
+```bash
+# Generate entities from database schema
+yarn gen:db-schema
+
+# Generate repository classes
+yarn gen:db-repo
+
+# Generate both entities and repositories
+yarn gen:db
+
+# Generate index files
+yarn gen:idx
+```
+
+**Note**: Define tables to generate in `gen_db.json` before running.
+
+### Testing & Quality
+
+```bash
+# Run tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Run tests with coverage
+yarn test:coverage
+
+# Type check and lint
+yarn lint
+
+# Auto-fix linting issues
+yarn lint:fix
+```
+
+### Security
+
+```bash
+# Run security audit
+yarn security
+
+# Show audit summary
+yarn security:summary
+
+# Enhanced security check (recommended)
+yarn security:check
+
+# Generate security report
+yarn security:json
+```
+
+See [docs/SECURITY.md](docs/SECURITY.md) for comprehensive security guidelines.
+
+### Dependency Management
+
+```bash
+# Check for outdated dependencies
+yarn deps:check
+
+# Update dependencies
+yarn deps:update
+```
+
+### Other Tools
+
+```bash
+# Generate RSA keys for JWT
+yarn gen:keys
+
+# Update build number
+yarn buildNum
+```
+
+## Usage Examples
+
+### Creating a RESTful Controller
+
+```typescript
+import { rest, di } from '@/libs/deps';
+import { UniversalController } from '@/libs/universal';
+import { UserService } from './services/UserService';
+import { UserVo } from './vo/UserVo';
+
+@rest.JsonController('/api/users')
+@di.Service()
+export class UserController extends UniversalController {
+  @di.Inject()
+  private userService: UserService;
+
+  @rest.Get('/')
+  async getAll() {
+    return this.userService.getAll(UserVo);
+  }
+
+  @rest.Post('/')
+  async create(@rest.Body() data: UserVo) {
+    return this.userService.create(data);
+  }
+
+  @rest.Get('/:id')
+  async getById(@rest.Param('id') id: number) {
+    return this.userService.readById(id, UserVo);
+  }
+}
+```
+
+### Creating a Service with Repository
+
+```typescript
+import { di } from '@/libs/deps';
+import { UniversalService } from '@/libs/universal';
+import { User } from './entities/User';
+import { UserRepo } from './repositories/UserRepo';
+
+@di.Service()
+export class UserService extends UniversalService<User> {
+  constructor(@di.Inject(() => UserRepo) private userRepo: UserRepo) {
+    super(userRepo);
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.userRepo.findOne({ where: { email } });
+  }
+}
+```
+
+### Validation with VO (Value Object)
+
+```typescript
+import { cv } from '@/libs/deps';
+import { i18n } from '@/libs/validator';
+import { IsSafeUrl } from '@/libs/validator';
+
+export class UserVo {
+  @i18n(cv.IsString)
+  @i18n(cv.MaxLength, 50)
+  userName: string;
+
+  @i18n(cv.IsEmail)
+  email: string;
+
+  @IsSafeUrl()
+  website?: string;
+
+  @i18n(cv.IsOptional)
+  @i18n(cv.MinLength, 6)
+  password?: string;
+}
+```
+
+### Pagination
+
+```typescript
+import { rest, di } from '@/libs/deps';
+import { PaginationIn, PaginationOut } from '@/libs/pagination';
+import { UserService } from './services/UserService';
+import { UserVo } from './vo/UserVo';
+
+@rest.JsonController('/api/users')
+@di.Service()
+export class UserController {
+  @di.Inject()
+  private userService: UserService;
+
+  @rest.Post('/search')
+  async search(@rest.Body() pagination: PaginationIn): Promise<PaginationOut<UserVo, User>> {
+    return this.userService.search(pagination);
+  }
+}
+```
+
+### Caching
+
+```typescript
+import { rest, di } from '@/libs/deps';
+import { L1Cache } from '@/libs/cache';
+import { CacheService } from '@/libs/cache';
+
+@rest.JsonController('/api/data')
+@di.Service()
+export class DataController {
+  @di.Inject()
+  private cacheService: CacheService;
+
+  @rest.Get('/cached')
+  @L1Cache({ ttlSeconds: 60 })
+  async getCachedData() {
+    // L1 cache - in-memory
+    return { data: 'This is cached for 60 seconds' };
+  }
+
+  @rest.Get('/redis')
+  async getRedisData() {
+    // L2 cache - Redis
+    const cached = await this.cacheService.get('key');
+    if (cached) return cached;
+
+    const data = { data: 'Fresh data' };
+    await this.cacheService.set('key', data, 300);
+    return data;
+  }
+}
+```
+
+### Distributed Events
+
+```typescript
+import { di } from '@/libs/deps';
+import { DistributedEvents } from '@/libs/rabbitmq';
+
+@di.Service()
+export class UserService {
+  @di.Inject()
+  private events: DistributedEvents;
+
+  async createUser(data: UserVo) {
+    const user = await this.userRepo.save(data);
+
+    // Publish event to RabbitMQ
+    await this.events.pub('user.created', { userId: user.id });
+
+    return user;
+  }
+}
+
+// Event handler
+@di.Service()
+export class UserEventHandler {
+  @di.Inject()
+  private events: DistributedEvents;
+
+  async init() {
+    // Subscribe to events
+    await this.events.sub(['user.created']);
+
+    this.events.on('RemoteEvent', (eventName, data) => {
+      if (eventName === 'user.created') {
+        console.log('User created:', data);
+      }
+    });
+  }
+}
+```
+
+## Key Technologies
+
+### Core Framework
+- **[Koa](https://koajs.com/)** 3.0.3 - Lightweight web framework
+- **[routing-controllers](https://github.com/typestack/routing-controllers)** 0.11.3 - Decorator-based routing
+- **[socket-controllers](https://github.com/typestack/socket-controllers)** 0.3.1 - WebSocket controllers
+- **[TypeDI](https://github.com/typestack/typedi)** 0.10.0 - Dependency injection
+- **[microframework](https://github.com/typestack/microframework)** 0.6.4 - Loader pattern
+
+### Data Layer
+- **[TypeORM](https://typeorm.io/)** 0.3.27 - SQL ORM
+- **[typeorm-transactional](https://github.com/Aliheym/typeorm-transactional)** 0.5.0 - Transaction management
+- **[mysql2](https://github.com/sidorares/node-mysql2)** 3.15.2 - MySQL/MariaDB driver
+- **[class-validator](https://github.com/typestack/class-validator)** 0.14.2 - Validation
+- **[class-transformer](https://github.com/typestack/class-transformer)** 0.5.1 - Transformation
+
+### Caching & Messaging
+- **[ioredis](https://github.com/luin/ioredis)** 5.8.1 - Redis client
+- **[amqplib](https://github.com/amqp-node/amqplib)** 0.10.9 - RabbitMQ client
+
+### Utilities
+- **[pino](https://github.com/pinojs/pino)** 10.0.0 - High-performance logger
+- **[jsonwebtoken](https://github.com/auth0/node-jsonwebtoken)** 9.0.2 - JWT authentication
+- **[nanoid](https://github.com/ai/nanoid)** 5.1.6 - Unique ID generator
+- **[axios](https://github.com/axios/axios)** 1.12.2 - HTTP client
+- **[helmet](https://github.com/helmetjs/helmet)** 8.1.0 - Security headers
+
+## Documentation
+
+- **[CLAUDE.md](CLAUDE.md)** - Comprehensive framework documentation
+- **[docs/SECURITY.md](docs/SECURITY.md)** - Security guidelines and best practices
+- **[docs/VULNERABILITY_MITIGATION.md](docs/VULNERABILITY_MITIGATION.md)** - Vulnerability tracking
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** - Quick start guide
+- **[docs/PUBLISHING.md](docs/PUBLISHING.md)** - Publishing guide
+- **[docs/BUILD_AND_USE.md](docs/BUILD_AND_USE.md)** - Building and usage instructions
+- **[docs/DOCKER_OPTIMIZATION.md](docs/DOCKER_OPTIMIZATION.md)** - Docker optimization guide
+
+### Module Documentation
+
+- `src/libs/deps/README.md` - Unified dependency exports
+- `src/libs/validator/README.md` - Validation helpers
+- `src/libs/apisix/README.md` - API gateway integration
+- `src/libs/gateway/README.md` - Gateway loader
+- `src/libs/generator/README.md` - ID generation
+- `src/libs/koa/README.md` - Koa server setup
+- `src/libs/network/README.md` - Network utilities
+- `src/libs/rabbitmq/README.md` - Distributed events
+- `src/libs/register/README.md` - API route registration
+- `src/libs/type/README.md` - Type utilities
+- `src/libs/universal/README.md` - Universal CRUD patterns
+
+## Security
+
+This project takes security seriously. We use:
+
+- Regular security audits with `yarn security:check`
+- Dependency vulnerability tracking and mitigation
+- Custom validators to avoid known CVEs (e.g., `@IsSafeUrl()` instead of `@IsUrl()`)
+- Secure dependency resolutions for transitive dependencies
+- Security documentation and best practices
+
+See [docs/SECURITY.md](docs/SECURITY.md) for detailed information.
+
+**Important**: Always use `@IsSafeUrl()` instead of `@IsUrl()` to avoid CVE-2025-56200.
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+1. Fork the repository
+2. Create a feature branch from `develope`
+3. Make your changes with descriptive commits
+4. Run tests and linting: `yarn test && yarn lint`
+5. Run security check: `yarn security:check`
+6. Create a pull request to `develope` branch
+
+### Development Guidelines
+
+- Follow existing code conventions
+- Use TypeScript strict mode
+- Add JSDoc comments for public APIs
+- Write tests for new features
+- Update documentation as needed
+
+## Publishing
+
+This is a private npm package. To publish:
+
+```bash
+# Update version in package.json
+# Update build number
+yarn buildNum
+
+# Run pre-publish checks
+yarn publish:check
+
+# Build for publishing
+yarn build:publish
+
+# Publish to npm
+yarn publish:npmjs
+
+# Or publish to GitHub packages
+yarn publish:github
+```
+
+See [docs/PUBLISHING.md](docs/PUBLISHING.md) for detailed publishing instructions.
+
+## Troubleshooting
+
+### Database Connection Issues
+
+- Verify `cfg/database.yml` connection string
+- Check MariaDB/MySQL is running
+- Ensure database user has proper permissions
+
+### Redis Connection Issues
+
+- Check Redis is running: `redis-cli ping`
+- Verify `cfg/redis.yml` settings
+- Can disable Redis by setting `disableRedis: true` in bootstrap
+
+### TypeORM Entity Not Found
+
+- Ensure entity is registered in bootstrap `entities` array
+- Check entity file has `@Entity()` decorator
+- Verify import path is correct
+
+## License
+
+UNLICENSED - Private package
+
+## Author
+
+FOT Team
+
+## Links
 
+- [Repository](https://github.com/gaias/basenode)
+- [Issue Tracker](https://github.com/gaias/basenode/issues)
+- [npm Package](https://www.npmjs.com/package/@gaias/basenode)
 
-## Document links
-* Restful controller: 
-https://github.com/typestack/routing-controllers/blob/master/README.md[routing-controllers] 
-* Socket.io controller:
-https://github.com/typestack/socket-controllers/blob/master/README.md[socket-controllers]
-* Validation: https://github.com/typestack/class-validator/blob/master/README.md[class-validator]
-* Json <-> Object: https://github.com/typestack/class-transformer/blob/develop/README.md[class-transformer]
-* socket.io: https://socket.io/docs/[socket.io]
-* IoC: https://github.com/typestack/typedi/blob/master/README.md[typedi]
-* ORM: 
-** https://typeorm.io/[typeorm] 
-** https://github.com/odavid/typeorm-transactional-cls-hooked/blob/master/README.md[tx decorators]
-** https://github.com/typeorm/typeorm-typedi-extensions/blob/master/README.md[inject repo/conn]
+## Version History
 
+- **1.0.24** (Current) - Latest updates and improvements
+- **1.0.13** - Security enhancements and dependency updates
+- **1.0.0** - Initial release
 
+---
 
-## Dev
-http://localhost:3000/api/v1/example/query/roles
+**Last Updated**: 2025-10-23
+**Framework Version**: 1.0.24
+**Build Number**: 251022024

package/cfg/apisix.yml

@@ -0,0 +1 @@
+apiKey: yhwj2hUq9H4kGBHGMvwKcKjt

package/cfg/application.development.yml

@@ -0,0 +1 @@
+proxy: http://www.dev.fot.cool:8888

package/cfg/application.yml

@@ -0,0 +1,5 @@
+appName: example
+version: 1
+port: 3000
+privateKeyPath: ./keys/privateKey
+publicKeyPath: ./keys/publicKey

package/cfg/database.yml

@@ -0,0 +1,7 @@
+# 数据库配置 / Database Configuration
+# 优先使用环境变量 DATABASE_URL，如果未设置则使用下面的默认值
+# Environment variable DATABASE_URL takes precedence over this default value
+# 推荐：请在 .env 文件中设置真实的数据库连接信息
+# Recommended: Set real database connection in .env file
+mariaDBUrl: mysql://root:AyEB7kJjm4@192.168.88.10:3306/fotNet
+output: ./example

package/cfg/logger.yml

@@ -0,0 +1,5 @@
+level: debug
+prettyPrint:
+  translateTime: SYS:standard
+  ignore: pid,hostname
+  levelFirst: true

package/cfg/openapiCfg.yml

@@ -0,0 +1 @@
+disabled: false

package/cfg/rabbitmq.yml

@@ -0,0 +1 @@
+connection: amqp://admin:admin@192.168.88.10:5672/