autocomit
This commit is contained in:
@@ -0,0 +1,447 @@
|
||||
# Story 0: Foundation - Walking Skeleton
|
||||
|
||||
## Story Overview
|
||||
|
||||
**As a** development team
|
||||
**I want** to establish the technical foundation and development patterns
|
||||
**So that** all future features can be built consistently and efficiently
|
||||
|
||||
**Story Type**: Technical Foundation
|
||||
**Priority**: Highest
|
||||
**Estimated Effort**: 2-3 weeks
|
||||
**Dependencies**: None (first story)
|
||||
|
||||
---
|
||||
|
||||
## Business Value
|
||||
|
||||
This story establishes:
|
||||
- Complete tech stack setup (Spring Boot + Angular + PostgreSQL)
|
||||
- Authentication and authorization framework
|
||||
- One complete CRUD example (Environment entity) as a template
|
||||
- CI/CD pipeline foundation
|
||||
- Testing infrastructure
|
||||
- Development patterns for all future stories
|
||||
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
✅ Spring Boot project setup with security
|
||||
✅ PostgreSQL database with Liquibase
|
||||
✅ JWT authentication implementation
|
||||
✅ Angular project setup
|
||||
✅ Authentication UI (login page)
|
||||
✅ Environment entity (complete CRUD) as pattern example
|
||||
✅ API documentation (Swagger)
|
||||
✅ Docker setup for local development
|
||||
✅ Basic CI/CD configuration
|
||||
|
||||
### Out of Scope
|
||||
❌ All business entities except Environment
|
||||
❌ Complex authorization rules (just basic role check)
|
||||
❌ OAuth integration (local auth only)
|
||||
❌ Advanced UI features
|
||||
|
||||
---
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Backend Tasks
|
||||
|
||||
#### 1. Project Setup
|
||||
- [ ] Create Spring Boot project via Spring Initializr
|
||||
- Spring Boot 3.2.x
|
||||
- Dependencies: Web, Security, JPA, PostgreSQL, Liquibase, Validation
|
||||
- [ ] Configure `pom.xml` with additional dependencies
|
||||
- JJWT for JWT handling
|
||||
- Lombok
|
||||
- SpringDoc OpenAPI
|
||||
- Testcontainers
|
||||
- [ ] Setup project structure (packages: config, domain, repository, service, dto, controller, security, exception)
|
||||
|
||||
#### 2. Database Setup
|
||||
- [ ] Create Liquibase changelog master file
|
||||
- [ ] Migration 001: Create `user` table with columns:
|
||||
- `id` (UUID, PK)
|
||||
- `username` (VARCHAR, unique, not null)
|
||||
- `password` (VARCHAR, hashed, not null)
|
||||
- `email` (VARCHAR, unique, not null)
|
||||
- `role` (VARCHAR, not null) - Simple role: ADMIN, USER
|
||||
- `created_at`, `updated_at` (TIMESTAMP)
|
||||
- [ ] Migration 002: Create `environment` table with columns:
|
||||
- `id` (UUID, PK)
|
||||
- `name` (VARCHAR, unique, not null)
|
||||
- `description` (TEXT, nullable)
|
||||
- `is_production` (BOOLEAN, default false)
|
||||
- `criticality_level` (INTEGER, nullable)
|
||||
- `created_at`, `updated_at` (TIMESTAMP)
|
||||
- [ ] Add indexes on `is_production` and `name`
|
||||
|
||||
#### 3. JPA Entities
|
||||
- [ ] Create `BaseEntity` abstract class with:
|
||||
- `id` field with UUID generator
|
||||
- `createdAt`, `updatedAt` with JPA auditing
|
||||
- [ ] Create `User` entity extending `BaseEntity`
|
||||
- [ ] Create `Environment` entity extending `BaseEntity`
|
||||
- [ ] Configure JPA auditing in configuration class
|
||||
|
||||
#### 4. Security Implementation
|
||||
- [ ] Create `JwtTokenProvider` class
|
||||
- `generateToken(Authentication)`: Create JWT token
|
||||
- `getUsernameFromToken(String)`: Extract username
|
||||
- `validateToken(String)`: Validate token
|
||||
- [ ] Create `JwtAuthenticationFilter` extends `OncePerRequestFilter`
|
||||
- Extract JWT from Authorization header
|
||||
- Validate token
|
||||
- Set authentication in SecurityContext
|
||||
- [ ] Create `UserDetailsServiceImpl` implements `UserDetailsService`
|
||||
- Load user from database
|
||||
- Map to Spring Security UserDetails
|
||||
- [ ] Create `SecurityConfig`
|
||||
- Configure HTTP security
|
||||
- Disable CSRF (stateless API)
|
||||
- Configure CORS
|
||||
- Set session management to STATELESS
|
||||
- Define public endpoints: `/api/auth/**`
|
||||
- Require authentication for all other endpoints
|
||||
- Add JWT filter before UsernamePasswordAuthenticationFilter
|
||||
- [ ] Create `AuthController` with endpoints:
|
||||
- `POST /api/auth/register`: Register new user
|
||||
- `POST /api/auth/login`: Authenticate and return JWT
|
||||
- `GET /api/auth/me`: Get current user info
|
||||
|
||||
#### 5. Environment CRUD (Pattern Example)
|
||||
- [ ] Create `EnvironmentRepository` extends `JpaRepository<Environment, UUID>`
|
||||
- [ ] Create DTOs:
|
||||
- `CreateEnvironmentRequest` (name, description, isProduction, criticalityLevel)
|
||||
- `UpdateEnvironmentRequest` (same as create, all optional)
|
||||
- `EnvironmentResponse` (all fields + createdAt, updatedAt)
|
||||
- [ ] Create `EnvironmentService` with methods:
|
||||
- `create(CreateEnvironmentRequest)`: Create new environment
|
||||
- `update(UUID, UpdateEnvironmentRequest)`: Update environment
|
||||
- `findById(UUID)`: Get by ID
|
||||
- `findAll(Pageable)`: List all with pagination
|
||||
- `delete(UUID)`: Delete environment
|
||||
- [ ] Create `EnvironmentController` with endpoints:
|
||||
- `GET /api/environments`: List all (with pagination, sorting)
|
||||
- `GET /api/environments/{id}`: Get by ID
|
||||
- `POST /api/environments`: Create new
|
||||
- `PUT /api/environments/{id}`: Update
|
||||
- `DELETE /api/environments/{id}`: Delete
|
||||
- [ ] Add validation annotations on DTOs
|
||||
- [ ] Add Swagger annotations on controller methods
|
||||
|
||||
#### 6. Exception Handling
|
||||
- [ ] Create custom exceptions:
|
||||
- `ResourceNotFoundException`
|
||||
- `BadRequestException`
|
||||
- `UnauthorizedException`
|
||||
- [ ] Create `GlobalExceptionHandler` with `@ControllerAdvice`
|
||||
- Handle all custom exceptions
|
||||
- Return standardized error response (status, message, timestamp)
|
||||
|
||||
#### 7. Configuration
|
||||
- [ ] Configure `application.yml` for database, JPA, Liquibase
|
||||
- [ ] Configure `application-dev.yml` for development
|
||||
- [ ] Configure `application-prod.yml` for production
|
||||
- [ ] Create `OpenApiConfig` for Swagger documentation
|
||||
- [ ] Create `CorsConfig` for frontend integration
|
||||
|
||||
#### 8. Testing
|
||||
- [ ] Unit tests for `EnvironmentService` (with Mockito)
|
||||
- [ ] Integration tests for `EnvironmentController` (with Testcontainers)
|
||||
- [ ] Security tests for JWT authentication flow
|
||||
- [ ] Test coverage > 80%
|
||||
|
||||
---
|
||||
|
||||
### Frontend Tasks
|
||||
|
||||
#### 1. Project Setup
|
||||
- [ ] Create Angular 18 project: `ng new ldpv2-frontend`
|
||||
- [ ] Add Angular Material or PrimeNG
|
||||
- [ ] Configure TypeScript strict mode
|
||||
- [ ] Setup proxy configuration for API calls
|
||||
- [ ] Configure environments (dev, prod)
|
||||
|
||||
#### 2. Project Structure
|
||||
- [ ] Create folder structure:
|
||||
- `core/` (auth, guards, interceptors, services)
|
||||
- `shared/` (models, components, pipes)
|
||||
- `features/` (feature modules)
|
||||
- [ ] Setup routing module
|
||||
|
||||
#### 3. Authentication Module
|
||||
- [ ] Create models:
|
||||
- `User` interface (id, username, email, role)
|
||||
- `LoginRequest` interface (username, password)
|
||||
- `LoginResponse` interface (token, user)
|
||||
- [ ] Create `AuthService`:
|
||||
- `login(credentials)`: Call login API, store JWT in localStorage
|
||||
- `logout()`: Clear JWT from localStorage
|
||||
- `isAuthenticated()`: Check if JWT exists and is valid
|
||||
- `getCurrentUser()`: Get current user from token
|
||||
- [ ] Create `JwtInterceptor` (implements `HttpInterceptor`):
|
||||
- Add Authorization header with JWT to all requests
|
||||
- [ ] Create `ErrorInterceptor` (implements `HttpInterceptor`):
|
||||
- Handle 401 (redirect to login)
|
||||
- Handle other errors (show notification)
|
||||
- [ ] Create `AuthGuard` (implements `CanActivate`):
|
||||
- Protect routes requiring authentication
|
||||
- Redirect to login if not authenticated
|
||||
- [ ] Create `LoginComponent`:
|
||||
- Reactive form with username and password
|
||||
- Call AuthService.login()
|
||||
- Redirect to dashboard on success
|
||||
- Show error message on failure
|
||||
|
||||
#### 4. Environment Management (Pattern Example)
|
||||
- [ ] Create `Environment` model (TypeScript interface)
|
||||
- [ ] Create `EnvironmentService`:
|
||||
- `getEnvironments(page, size, sort)`: GET /api/environments
|
||||
- `getEnvironment(id)`: GET /api/environments/{id}
|
||||
- `createEnvironment(data)`: POST /api/environments
|
||||
- `updateEnvironment(id, data)`: PUT /api/environments/{id}
|
||||
- `deleteEnvironment(id)`: DELETE /api/environments/{id}
|
||||
- [ ] Create `EnvironmentListComponent`:
|
||||
- Display environments in table/list
|
||||
- Pagination controls
|
||||
- Sort by name, criticality, etc.
|
||||
- Actions: View, Edit, Delete
|
||||
- Button: Create New
|
||||
- [ ] Create `EnvironmentDetailComponent`:
|
||||
- Display full environment details
|
||||
- Edit and Delete buttons
|
||||
- [ ] Create `EnvironmentFormComponent`:
|
||||
- Reactive form for create/edit
|
||||
- Validation (required fields, unique name)
|
||||
- Submit to API
|
||||
- Success/error notifications
|
||||
- [ ] Add routing:
|
||||
- `/environments`: EnvironmentListComponent
|
||||
- `/environments/new`: EnvironmentFormComponent (create mode)
|
||||
- `/environments/:id`: EnvironmentDetailComponent
|
||||
- `/environments/:id/edit`: EnvironmentFormComponent (edit mode)
|
||||
|
||||
#### 5. Shared Components
|
||||
- [ ] Create `HeaderComponent` (navigation, user menu, logout)
|
||||
- [ ] Create `LoadingSpinnerComponent`
|
||||
- [ ] Create `ConfirmDialogComponent` (for delete confirmations)
|
||||
- [ ] Create `NotificationService` (toast notifications)
|
||||
|
||||
#### 6. Styling
|
||||
- [ ] Setup global styles
|
||||
- [ ] Create responsive layout
|
||||
- [ ] Style login page
|
||||
- [ ] Style environment management pages
|
||||
|
||||
#### 7. Testing
|
||||
- [ ] Unit tests for `AuthService`
|
||||
- [ ] Unit tests for `EnvironmentService`
|
||||
- [ ] Component tests for `LoginComponent`
|
||||
- [ ] Component tests for `EnvironmentListComponent`
|
||||
- [ ] E2E test: Login flow
|
||||
- [ ] E2E test: Create environment flow
|
||||
- [ ] Test coverage > 70%
|
||||
|
||||
---
|
||||
|
||||
### DevOps Tasks
|
||||
|
||||
#### 1. Docker Setup
|
||||
- [ ] Create `Dockerfile` for backend
|
||||
- [ ] Create `Dockerfile` for frontend
|
||||
- [ ] Create `docker-compose.yml` with services:
|
||||
- PostgreSQL
|
||||
- Backend
|
||||
- Frontend (optional for dev)
|
||||
- [ ] Document how to run with Docker
|
||||
|
||||
#### 2. CI/CD Pipeline
|
||||
- [ ] Create `.gitlab-ci.yml` or `Jenkinsfile` or GitHub Actions workflow
|
||||
- [ ] Pipeline stages:
|
||||
- Build (backend and frontend)
|
||||
- Test (run all tests)
|
||||
- Code quality check (SonarQube optional)
|
||||
- Build Docker images
|
||||
- Push to registry (optional)
|
||||
- [ ] Configure environment variables
|
||||
|
||||
#### 3. Documentation
|
||||
- [ ] README.md with:
|
||||
- Project description
|
||||
- Prerequisites
|
||||
- How to run locally
|
||||
- How to run with Docker
|
||||
- How to run tests
|
||||
- [ ] API documentation accessible via Swagger UI
|
||||
- [ ] Contribution guidelines (optional)
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Authentication
|
||||
- [ ] User can register a new account
|
||||
- [ ] User can login with username and password
|
||||
- [ ] Upon successful login, JWT token is returned
|
||||
- [ ] JWT token is stored in browser (localStorage)
|
||||
- [ ] JWT token is automatically included in API requests
|
||||
- [ ] User is redirected to login page when token is invalid/expired
|
||||
- [ ] User can logout (token is cleared)
|
||||
|
||||
### Environment CRUD
|
||||
- [ ] User can view a list of all environments
|
||||
- [ ] List is paginated (20 items per page)
|
||||
- [ ] User can sort environments by name or criticality
|
||||
- [ ] User can view details of a specific environment
|
||||
- [ ] User can create a new environment with:
|
||||
- Name (required, unique)
|
||||
- Description (optional)
|
||||
- Production flag (default: false)
|
||||
- Criticality level (optional, 1-5)
|
||||
- [ ] Form validation works correctly (required fields, unique name)
|
||||
- [ ] User can edit an existing environment
|
||||
- [ ] User can delete an environment (with confirmation dialog)
|
||||
- [ ] Success and error notifications are displayed appropriately
|
||||
|
||||
### API Documentation
|
||||
- [ ] Swagger UI is accessible at `/swagger-ui/index.html`
|
||||
- [ ] All endpoints are documented with request/response schemas
|
||||
- [ ] Authentication endpoints are documented
|
||||
- [ ] Environment endpoints are documented
|
||||
|
||||
### Testing
|
||||
- [ ] Backend unit tests pass (>80% coverage)
|
||||
- [ ] Backend integration tests pass
|
||||
- [ ] Frontend unit tests pass (>70% coverage)
|
||||
- [ ] E2E tests pass for critical flows
|
||||
|
||||
### DevOps
|
||||
- [ ] Application runs successfully with `docker-compose up`
|
||||
- [ ] CI/CD pipeline builds and tests successfully
|
||||
- [ ] README documentation is complete and accurate
|
||||
|
||||
---
|
||||
|
||||
## Testing Scenarios
|
||||
|
||||
### Scenario 1: User Registration and Login
|
||||
1. Navigate to registration page
|
||||
2. Fill in username, email, password
|
||||
3. Submit registration form
|
||||
4. Verify success message
|
||||
5. Navigate to login page
|
||||
6. Enter username and password
|
||||
7. Submit login form
|
||||
8. Verify redirect to dashboard
|
||||
9. Verify JWT token in localStorage
|
||||
10. Verify Authorization header in subsequent requests
|
||||
|
||||
### Scenario 2: Create Environment
|
||||
1. Login as authenticated user
|
||||
2. Navigate to environments list
|
||||
3. Click "Create New Environment"
|
||||
4. Fill in form:
|
||||
- Name: "PROD-EU"
|
||||
- Description: "Production environment for Europe"
|
||||
- Production: true
|
||||
- Criticality: 5
|
||||
5. Submit form
|
||||
6. Verify success notification
|
||||
7. Verify redirect to environment list
|
||||
8. Verify new environment appears in list
|
||||
|
||||
### Scenario 3: Edit Environment
|
||||
1. Navigate to environment list
|
||||
2. Click "Edit" on an environment
|
||||
3. Modify description
|
||||
4. Submit form
|
||||
5. Verify success notification
|
||||
6. Verify changes are reflected
|
||||
|
||||
### Scenario 4: Delete Environment
|
||||
1. Navigate to environment list
|
||||
2. Click "Delete" on an environment
|
||||
3. Confirm deletion in dialog
|
||||
4. Verify success notification
|
||||
5. Verify environment is removed from list
|
||||
|
||||
### Scenario 5: Unauthorized Access
|
||||
1. Logout or clear JWT token
|
||||
2. Attempt to access protected route (e.g., `/environments`)
|
||||
3. Verify redirect to login page
|
||||
4. Login again
|
||||
5. Verify redirect to originally requested page
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All backend tasks completed
|
||||
- [ ] All frontend tasks completed
|
||||
- [ ] All DevOps tasks completed
|
||||
- [ ] All acceptance criteria met
|
||||
- [ ] All tests passing (unit, integration, E2E)
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] API documented in Swagger
|
||||
- [ ] User documentation updated
|
||||
- [ ] Demo conducted successfully
|
||||
- [ ] Code merged to main branch
|
||||
|
||||
---
|
||||
|
||||
## Technical Debt & Future Improvements
|
||||
|
||||
### Known Limitations
|
||||
- Simple role-based authorization (ADMIN, USER) - will need environment-specific roles in future
|
||||
- Local authentication only - OAuth integration planned for later
|
||||
- Basic error handling - can be enhanced with more specific error codes
|
||||
- No password reset functionality - to be added later
|
||||
|
||||
### Future Enhancements
|
||||
- Implement refresh token mechanism
|
||||
- Add password strength validation
|
||||
- Implement account activation via email
|
||||
- Add "Remember me" functionality
|
||||
- Implement rate limiting on auth endpoints
|
||||
- Add audit logging for security events
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Blockers
|
||||
|
||||
### Dependencies
|
||||
None - this is the first story
|
||||
|
||||
### Potential Blockers
|
||||
- PostgreSQL setup issues → Use Docker Compose
|
||||
- CORS configuration issues → Properly configure allowed origins
|
||||
- JWT secret management → Use environment variables
|
||||
- Network connectivity between services → Use Docker network
|
||||
|
||||
---
|
||||
|
||||
## Resources & References
|
||||
|
||||
### Spring Boot Documentation
|
||||
- [Spring Security](https://docs.spring.io/spring-security/reference/index.html)
|
||||
- [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/)
|
||||
- [Liquibase with Spring Boot](https://docs.liquibase.com/tools-integrations/springboot/springboot.html)
|
||||
|
||||
### Angular Documentation
|
||||
- [Angular Authentication](https://angular.io/guide/security)
|
||||
- [HTTP Interceptors](https://angular.io/guide/http-interceptor-use-cases)
|
||||
- [Reactive Forms](https://angular.io/guide/reactive-forms)
|
||||
|
||||
### JWT
|
||||
- [JJWT Library](https://github.com/jwtk/jjwt)
|
||||
- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
|
||||
|
||||
---
|
||||
|
||||
**Story Status**: Ready for Development
|
||||
**Story Created**: February 2026
|
||||
**Estimated Completion**: 2-3 weeks from start
|
||||
Reference in New Issue
Block a user