s.hajizadeh/esg

Fork 0

forked from Shared/esg

Files

s.hajizadeh b629a47f7f some error handler + error validation + realEstate bug fixed for hamta end moallem

2026-06-14 12:16:48 +03:30

8.7 KiB

Raw Blame History

Inquiry Gateway

Production-grade NestJS + MongoDB unified inquiry gateway for external service providers.

📚 Documentation

Environment Configuration Guide - Complete guide for configuring providers, authentication, and inquiry routing
API Documentation - Full API reference with examples, Swagger definitions, and best practices

Architecture

Client → POST /inquiries/person (unified)
       → InquiryController
       → InquiryService
       → ProviderOrchestratorService (strategy + fallback)
       → ProviderFactory → Hamta | Moallem | TejaratNou
       → LegacyApiProvider (shared base for identical APIs)
       → BaseProvider (retry, timeout, logging, error normalization)
       → MongoDB inquiry_logs

Provider vs Authentication Service

The system distinguishes between:

Inquiry Providers (HAMTA, MOALLEM, TEJARATNOU): Handle actual inquiry requests
Authentication Services (AMITIS): Provide authentication tokens for providers

Each inquiry type can be configured with its own credentials and authentication method. See Environment Configuration Guide for details.

Design patterns

Pattern	Usage
Strategy	`ProviderOrchestratorService` selects and executes providers
Factory	`ProviderFactory` registers and resolves provider instances
Template method	`BaseProvider` defines execution pipeline; subclasses implement `callProvider`
Shared adapter	`LegacyApiProvider` for Hamta/Moallem identical APIs

Project structure

src/
├── main.ts
├── app.module.ts
├── common/          # DTOs, filters, interceptors, helpers, enums
├── config/          # @nestjs/config + inquiry routing
├── auth/            # JWT, RBAC, inquiry access guards
├── users/           # Unified users (ADMIN / USER / SUPER_ADMIN)
├── audit/           # Security audit logs
├── rate-limit/      # Global + per-user throttling
├── logging/         # MongoDB inquiry audit logs
├── providers/       # BaseProvider, LegacyApiProvider, factory, orchestrator
└── inquiry/         # Unified controllers & services

Quick start

cp .env.example .env
# Edit .env with your provider credentials (see Environment Configuration Guide)
npm install
npm run cli:create-super-admin   # interactive — creates SUPER_ADMIN
npm run start:dev

API: http://localhost:8085
Swagger: http://localhost:8085/api/docs

Authentication & users

Role	Capabilities
`SUPER_ADMIN`	Full access; create any user including other super admins
`ADMIN`	Manage users; all inquiry types
`USER`	Inquiry access per `allowedInquiries`

Auth endpoints: POST /auth/login, POST /auth/refresh, POST /auth/logout, GET /auth/profile

User management: POST/GET/PATCH /users, block/unblock, reset password (ADMIN+ only)

# Login
curl -X POST http://localhost:8085/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# Person inquiry (JWT)
curl -X POST http://localhost:8085/inquiries/person \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"nationalCode":"0012345678","birthDate":"1370-05-15"}'

Response envelope (BaseInquiryResponseDto):

{
  "success": true,
  "provider": "HAMTA",
  "trackingCode": "INQ-20250525-A1B2C3D4",
  "message": "Person inquiry completed successfully",
  "data": { "nationalCode": "0012345678", "birthDate": "1370-05-15", "fullName": "..." },
  "duration": 342
}

Provider configuration

Per-inquiry configuration via environment variables:

# Default provider and fallback chain
PERSON_DEFAULT_PROVIDER=PARSIAN
PERSON_FALLBACK_PROVIDERS=HAMTA,TEJARATNOU

# Per-inquiry credentials and authentication
PARSIAN_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
PARSIAN_PERSON_USERNAME=user123
PARSIAN_PERSON_PASSWORD=pass123
PARSIAN_PERSON_AUTH_METHOD=SOAP

# AMITIS authentication service
AMITIS_LOGIN_URL=https://auth.services.centinsur.ir/api/security/login
AMITIS_REFRESH_URL=https://auth.services.centinsur.ir/api/security/RefreshToken

See Environment Configuration Guide for complete configuration options.

Supported inquiry types

Inquiry Type	Providers	Description
`PERSON_INQUIRY`	PARSIAN, HAMTA, TEJARATNOU, MOALLEM	Person information by national code and birth date
`REAL_ESTATE_INQUIRY`	HAMTA	Real estate ownership information
`POSTAL_CODE_INQUIRY`	HAMTA, MOALLEM	Address validation by postal code
`SHAHKAR_INQUIRY`	PARSIAN, HAMTA, MOALLEM	Mobile number verification
`CIVIL_REGISTRATION_INQUIRY`	MOALLEM	Civil registration data
`SHEBA_INQUIRY`	PARSIAN, HAMTA, MOALLEM	Bank account (SHEBA) validation
`SAYAH_INQUIRY`	TEJARATNOU	Sayah system inquiry
`POLICY_BY_CHASSIS_INQUIRY`	PARSIAN	Car policy history by chassis number
`POLICY_BY_PLATE_INQUIRY`	PARSIAN	Car policy history by national plate
`POLICY_BY_NATIONAL_CODE_INQUIRY`	PARSIAN	Car policy history by national code

See API Documentation for detailed request/response formats.

Authentication methods

Method	Description	Use Case
`AMITIS`	Token-based auth via AMITIS service	Most CentInsur APIs
`SOAP`	Direct SOAP authentication	Legacy XML-based services
`OAUTH2`	OAuth 2.0 flow	Modern REST APIs
`NONE`	No authentication required	Public APIs

Token management

Token refresh: Every 20 minutes automatically
Token expiration: Daily at 23:59:59 Tehran time
Retry logic: Automatic retry on HTTP 5xx errors and network failures
Error handling: Graceful fallback to alternative providers

Adding a new provider

Add ProviderName enum value in src/common/enums/provider-name.enum.ts
Add provider configuration in src/config/configuration.ts
Implement provider (extend BaseProvider or LegacyApiProvider)
Register in src/providers/factory/provider.factory.ts
Update inquiry routing env vars — no new HTTP routes required

Adding a new inquiry type

Add InquiryType enum in src/common/enums/inquiry-type.enum.ts
Create request/response DTOs with class-validator in src/inquiry/dto/
Add POST /inquiries/<type> in InquiryController
Implement service method using ProviderOrchestratorService
Configure routing and credentials in .env

Security

JWT: access + refresh tokens (JWT_SECRET, JWT_REFRESH_SECRET)
RBAC: @Roles() + RolesGuard
Inquiry access: allowedInquiries + InquiryAccessGuard (e.g. PERSON_INQUIRY)
Rate limiting: global throttler + per-user requestLimitPerMinute / requestLimitPerDay
Audit: audit_logs for login, user lifecycle events
Request logging: All inquiries logged to MongoDB with masked sensitive data

Error handling

The system provides comprehensive error handling:

Network errors: Automatic retry with exponential backoff
HTTP 5xx errors: Automatic retry (configurable attempts)
Provider failures: Automatic fallback to alternative providers
Validation errors: Detailed error messages with field-level validation
Authentication errors: Automatic token refresh and retry

Monitoring & observability

OpenTelemetry: Distributed tracing support
Inquiry logs: MongoDB collection with full request/response audit trail
Audit logs: Security events and user actions
Performance metrics: Request duration, provider response times
Error tracking: Normalized error codes and messages

Development

# Development mode with hot reload
npm run start:dev

# Build for production
npm run build

# Run tests
npm run test

# Run tests with coverage
npm run test:cov

# Lint code
npm run lint

# Format code
npm run format

Environment variables

Key environment variables (see .env.example for complete list):

# Application
NODE_ENV=development
PORT=8085
API_PREFIX=api

# Database
MONGODB_URI=mongodb://localhost:27017/inquiry-gateway

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=your-refresh-secret
JWT_REFRESH_EXPIRES_IN=7d

# Rate limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100

# Provider configuration (see Environment Configuration Guide)

License

MIT

8.7 KiB Raw Blame History