209 lines
4.7 KiB
Markdown
209 lines
4.7 KiB
Markdown
# Development Guide
|
|
|
|
This guide provides comprehensive instructions for setting up and developing the DBIS Core Banking System.
|
|
|
|
## Development Workflow
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph "Development Cycle"
|
|
CLONE[Clone Repository]
|
|
INSTALL[Install Dependencies]
|
|
SETUP[Setup Environment]
|
|
DEV[Develop Features]
|
|
TEST[Run Tests]
|
|
LINT[Lint & Format]
|
|
COMMIT[Commit Changes]
|
|
end
|
|
|
|
CLONE --> INSTALL
|
|
INSTALL --> SETUP
|
|
SETUP --> DEV
|
|
DEV --> TEST
|
|
TEST --> LINT
|
|
LINT --> COMMIT
|
|
COMMIT --> DEV
|
|
```
|
|
|
|
## Local Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20.x or higher
|
|
- PostgreSQL 15.x or higher
|
|
- npm or yarn
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Set up environment variables:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
4. Set up the database:
|
|
```bash
|
|
npx prisma generate
|
|
npx prisma migrate dev
|
|
```
|
|
|
|
5. Start the development server:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Run tests in watch mode
|
|
npm run test:watch
|
|
|
|
# Run tests with coverage
|
|
npm run test:coverage
|
|
```
|
|
|
|
### Test Structure
|
|
|
|
- Unit tests: `src/__tests__/unit/`
|
|
- Integration tests: `src/__tests__/integration/`
|
|
- E2E tests: `src/__tests__/e2e/`
|
|
- Test utilities: `src/__tests__/utils/`
|
|
|
|
### Writing Tests
|
|
|
|
1. Use the test utilities provided in `src/__tests__/utils/`
|
|
2. Follow the existing test patterns
|
|
3. Aim for 80%+ coverage for financial operations
|
|
4. Use descriptive test names
|
|
|
|
## Code Quality
|
|
|
|
### Linting
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
### Formatting
|
|
|
|
```bash
|
|
npm run format
|
|
```
|
|
|
|
### Type Checking
|
|
|
|
```bash
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
## Code Contribution Guidelines
|
|
|
|
1. Follow TypeScript best practices
|
|
2. Use the shared utilities for common operations
|
|
3. Replace all `console.*` calls with the logger
|
|
4. Use the singleton Prisma client from `@/shared/database/prisma`
|
|
5. Add tests for new features
|
|
6. Update documentation as needed
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Connection Issues
|
|
|
|
- Verify `DATABASE_URL` in `.env`
|
|
- Check PostgreSQL is running
|
|
- Verify database exists
|
|
|
|
### Environment Variable Errors
|
|
|
|
- Run the application to see validation errors
|
|
- Check `.env.example` for required variables
|
|
- Ensure all required variables are set
|
|
|
|
### Test Failures
|
|
|
|
- Ensure test database is set up
|
|
- Check `TEST_DATABASE_URL` in environment
|
|
- Verify Prisma client is generated
|
|
|
|
## Development Best Practices
|
|
|
|
### Code Organization
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph "Development Practices"
|
|
STRUCTURE[Follow Directory Structure]
|
|
PATTERNS[Use Design Patterns]
|
|
UTILS[Use Shared Utilities]
|
|
TYPES[Type Safety]
|
|
end
|
|
|
|
STRUCTURE --> QUALITY[Code Quality]
|
|
PATTERNS --> QUALITY
|
|
UTILS --> QUALITY
|
|
TYPES --> QUALITY
|
|
```
|
|
|
|
### Development Recommendations
|
|
|
|
**Priority: High**
|
|
|
|
1. **Use Shared Utilities**
|
|
- **Description**: Use shared utilities for common operations
|
|
- **Implementation**:
|
|
- Use `@/shared/utils/date-helpers` for date operations
|
|
- Use `@/shared/utils/decimal-helpers` for decimal calculations
|
|
- Use `@/shared/utils/validation-helpers` for validation
|
|
- **Impact**: Ensures consistency and reduces code duplication
|
|
- **Dependencies**: Shared utilities available
|
|
|
|
2. **Database Client Management**
|
|
- **Description**: Always use singleton Prisma client
|
|
- **Implementation**:
|
|
- Import from `@/shared/database/prisma`
|
|
- Never create new PrismaClient instances
|
|
- Use connection pooling
|
|
- **Impact**: Prevents connection pool exhaustion
|
|
- **Dependencies**: Singleton Prisma client configured
|
|
|
|
3. **Logging Standards**
|
|
- **Description**: Use Winston logger instead of console
|
|
- **Implementation**:
|
|
- Import logger from `@/infrastructure/monitoring/logger`
|
|
- Use appropriate log levels
|
|
- Include correlation IDs
|
|
- **Impact**: Enables proper log aggregation and analysis
|
|
- **Dependencies**: Winston logger configured
|
|
|
|
4. **Error Handling**
|
|
- **Description**: Use custom error classes and proper error handling
|
|
- **Implementation**:
|
|
- Use error helpers from `@/shared/utils/error-helpers`
|
|
- Provide meaningful error messages
|
|
- Log errors with context
|
|
- **Impact**: Improves debugging and error tracking
|
|
- **Dependencies**: Error helpers available
|
|
|
|
5. **Testing Coverage**
|
|
- **Description**: Maintain high test coverage
|
|
- **Implementation**:
|
|
- Aim for 80%+ coverage for financial operations
|
|
- Write unit tests for all services
|
|
- Add integration tests for API endpoints
|
|
- **Impact**: Reduces bugs and improves code quality
|
|
- **Dependencies**: Test framework configured
|
|
|
|
For more detailed best practices, see [BEST_PRACTICES.md](./BEST_PRACTICES.md).
|
|
|