294 lines
9.1 KiB
Markdown
294 lines
9.1 KiB
Markdown
# Story 6: Deployment Tracking
|
||
|
||
## Story Overview
|
||
|
||
**As a** application manager
|
||
**I want** to record and track deployments
|
||
**So that** I know which version is deployed in each environment
|
||
|
||
**Story Type**: Feature (Core Domain)
|
||
**Priority**: Highest
|
||
**Estimated Effort**: 5-7 days
|
||
**Dependencies**: Story 2 (Applications), Story 4 (Environments), Story 5 (Versions)
|
||
|
||
---
|
||
|
||
## Business Value
|
||
|
||
Deployments are the core tracking mechanism. This enables:
|
||
- Record which application version is in which environment
|
||
- Complete deployment history (audit trail)
|
||
- Current state visibility (what's in production right now)
|
||
- Foundation for compliance and change tracking
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
### In Scope
|
||
✅ Deployment recording (application + version + environment)
|
||
✅ Deployment history (immutable records)
|
||
✅ Current deployment state query
|
||
✅ Deployment metadata (who, when, notes)
|
||
✅ Basic deployment listing and filtering
|
||
|
||
### Out of Scope
|
||
❌ Automated deployment from CI/CD
|
||
❌ Deployment approval workflows
|
||
❌ Rollback functionality
|
||
❌ Deployment health monitoring
|
||
|
||
---
|
||
|
||
## Database Schema
|
||
|
||
```sql
|
||
CREATE TABLE deployment (
|
||
id UUID PRIMARY KEY,
|
||
application_id UUID NOT NULL REFERENCES application(id),
|
||
version_id UUID NOT NULL REFERENCES version(id),
|
||
environment_id UUID NOT NULL REFERENCES environment(id),
|
||
deployment_date TIMESTAMP NOT NULL,
|
||
deployed_by VARCHAR(255), -- Username or system identifier
|
||
notes TEXT,
|
||
created_at TIMESTAMP NOT NULL,
|
||
CONSTRAINT fk_deployment_application FOREIGN KEY (application_id) REFERENCES application(id),
|
||
CONSTRAINT fk_deployment_version FOREIGN KEY (version_id) REFERENCES version(id),
|
||
CONSTRAINT fk_deployment_environment FOREIGN KEY (environment_id) REFERENCES environment(id),
|
||
CONSTRAINT check_version_belongs_to_app CHECK (
|
||
EXISTS (SELECT 1 FROM version WHERE id = version_id AND application_id = deployment.application_id)
|
||
)
|
||
);
|
||
|
||
-- Indexes for common queries
|
||
CREATE INDEX idx_deployment_application ON deployment(application_id);
|
||
CREATE INDEX idx_deployment_environment ON deployment(environment_id);
|
||
CREATE INDEX idx_deployment_date ON deployment(deployment_date DESC);
|
||
CREATE INDEX idx_deployment_app_env ON deployment(application_id, environment_id);
|
||
```
|
||
|
||
---
|
||
|
||
## Key Business Logic
|
||
|
||
### Current Deployment State
|
||
The "current" deployment for an application in an environment is defined as:
|
||
**The deployment with the most recent `deployment_date` for that (application, environment) combination**
|
||
|
||
Query:
|
||
```sql
|
||
SELECT DISTINCT ON (application_id, environment_id) *
|
||
FROM deployment
|
||
WHERE application_id = ? AND environment_id = ?
|
||
ORDER BY application_id, environment_id, deployment_date DESC;
|
||
```
|
||
|
||
### Immutability
|
||
Deployments are **immutable** once created. No updates or deletions allowed (audit requirement). Only soft-delete for admin cleanup.
|
||
|
||
---
|
||
|
||
## Key Endpoints
|
||
|
||
### Recording Deployments
|
||
- `POST /api/deployments` - Record new deployment
|
||
- Request: `{ applicationId, versionId, environmentId, deploymentDate, deployedBy?, notes? }`
|
||
- Validates version belongs to application
|
||
- Validates deployment date not in future
|
||
|
||
### Querying Deployments
|
||
- `GET /api/deployments` - List all deployments (paginated, filtered)
|
||
- Filters: `applicationId`, `environmentId`, `versionId`, `dateFrom`, `dateTo`
|
||
- `GET /api/deployments/{id}` - Get deployment details
|
||
- `GET /api/deployments/current` - Get current state across all environments
|
||
- Query params: `applicationId?`, `environmentId?`
|
||
- `GET /api/applications/{appId}/deployments` - Deployment history for application
|
||
- `GET /api/applications/{appId}/deployments/current` - Current state per environment for app
|
||
- `GET /api/environments/{envId}/deployments/current` - All current deployments in environment
|
||
|
||
---
|
||
|
||
## DTOs
|
||
|
||
```typescript
|
||
export interface Deployment {
|
||
id: string;
|
||
application: { id: string; name: string };
|
||
version: { id: string; versionIdentifier: string };
|
||
environment: { id: string; name: string };
|
||
deploymentDate: Date;
|
||
deployedBy?: string;
|
||
notes?: string;
|
||
createdAt: Date;
|
||
}
|
||
|
||
export interface RecordDeploymentRequest {
|
||
applicationId: string;
|
||
versionId: string;
|
||
environmentId: string;
|
||
deploymentDate: Date;
|
||
deployedBy?: string;
|
||
notes?: string;
|
||
}
|
||
|
||
export interface CurrentDeploymentState {
|
||
application: { id: string; name: string };
|
||
environment: { id: string; name: string };
|
||
version: { id: string; versionIdentifier: string };
|
||
deploymentDate: Date;
|
||
deployedBy?: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Frontend Components
|
||
|
||
### RecordDeploymentComponent
|
||
- Form to record new deployment:
|
||
- Application (dropdown or pre-selected from context)
|
||
- Version (dropdown - load versions for selected application)
|
||
- Environment (dropdown)
|
||
- Deployment Date (datetime picker, default: now)
|
||
- Deployed By (text input, default: current user)
|
||
- Notes (textarea, optional)
|
||
- Validation:
|
||
- All required fields
|
||
- Version belongs to selected application
|
||
- Date not in future
|
||
- Submit creates immutable deployment record
|
||
|
||
### DeploymentHistoryComponent (tab in ApplicationDetailComponent)
|
||
- Timeline view of deployments for an application
|
||
- Group by environment
|
||
- Show: Version, Environment, Date, Deployed By
|
||
- Sort: Most recent first
|
||
- Filter: By environment, by date range
|
||
|
||
### CurrentDeploymentStateComponent
|
||
- Dashboard view showing current state
|
||
- Matrix: Applications (rows) × Environments (columns)
|
||
- Each cell shows: Version number, deployment date
|
||
- Color coding:
|
||
- Green: Recently deployed (< 30 days)
|
||
- Yellow: Older deployment (30-90 days)
|
||
- Red: Very old (> 90 days)
|
||
- Click cell to see deployment details
|
||
- "Record Deployment" action per cell
|
||
|
||
### EnvironmentDeploymentsComponent (tab in Environment detail)
|
||
- List all applications currently deployed in this environment
|
||
- Columns: Application, Version, Deployment Date, Deployed By
|
||
- Link to application detail
|
||
|
||
---
|
||
|
||
## Acceptance Criteria
|
||
|
||
### Backend
|
||
- [ ] Deployment can be recorded with valid data
|
||
- [ ] Version must belong to the specified application
|
||
- [ ] Deployment date cannot be in future
|
||
- [ ] Deployments are immutable (no updates/deletes)
|
||
- [ ] Current deployment state query returns correct version per environment
|
||
- [ ] Deployment history is complete and ordered correctly
|
||
- [ ] All endpoints authenticated
|
||
- [ ] Tests pass (>80% coverage)
|
||
|
||
### Frontend
|
||
- [ ] User can record new deployment
|
||
- [ ] Form validates all fields
|
||
- [ ] Version dropdown shows only versions for selected application
|
||
- [ ] Deployment appears immediately in history
|
||
- [ ] Current state dashboard shows accurate data
|
||
- [ ] Timeline view shows deployment history
|
||
- [ ] User can filter deployment history
|
||
- [ ] Deployment date defaults to current time
|
||
- [ ] Deployed by defaults to current user
|
||
- [ ] Tests pass (>70% coverage)
|
||
|
||
---
|
||
|
||
## Testing Scenarios
|
||
|
||
### Scenario 1: Record Deployment
|
||
1. Navigate to "Record Deployment"
|
||
2. Select Application: "Customer Portal"
|
||
3. Version dropdown loads versions for Customer Portal
|
||
4. Select Version: "1.2.0"
|
||
5. Select Environment: "PROD-EU"
|
||
6. Deployment Date defaults to now
|
||
7. Deployed By defaults to current user
|
||
8. Add notes: "Hotfix for login issue"
|
||
9. Submit
|
||
10. Verify success notification
|
||
11. Verify deployment appears in history
|
||
|
||
### Scenario 2: Invalid Version
|
||
1. Attempt to record deployment
|
||
2. Manually set versionId for different application
|
||
3. Submit
|
||
4. Verify error: "Version does not belong to selected application"
|
||
|
||
### Scenario 3: Future Date Validation
|
||
1. Record deployment
|
||
2. Set deployment date to tomorrow
|
||
3. Submit
|
||
4. Verify error: "Deployment date cannot be in future"
|
||
|
||
### Scenario 4: Current State Query
|
||
1. Record multiple deployments for same app in different environments
|
||
2. Navigate to current state dashboard
|
||
3. Verify each environment shows the most recent deployment
|
||
4. Record new deployment for same app/env
|
||
5. Verify dashboard updates to show new deployment
|
||
|
||
### Scenario 5: Deployment History
|
||
1. Navigate to Application Detail → Deployments tab
|
||
2. Verify all deployments shown, grouped by environment
|
||
3. Verify sorted by date (most recent first)
|
||
4. Filter by environment
|
||
5. Verify only deployments to that environment shown
|
||
|
||
### Scenario 6: Environment View
|
||
1. Navigate to Environment Detail → Deployments tab
|
||
2. Verify all applications deployed to this environment shown
|
||
3. Verify versions and dates correct
|
||
4. Click on application
|
||
5. Verify navigates to application detail
|
||
|
||
---
|
||
|
||
## Integration Points
|
||
|
||
### Application Detail Enhancement
|
||
Add "Deployments" tab showing:
|
||
- Current deployment state (per environment)
|
||
- Deployment history timeline
|
||
- "Record New Deployment" button
|
||
|
||
### Environment Detail Enhancement
|
||
Add "Deployments" tab showing:
|
||
- All applications currently deployed
|
||
- Quick record deployment action
|
||
|
||
### Dashboard (new)
|
||
Create main dashboard showing:
|
||
- Current deployment state matrix
|
||
- Recent deployments (last 10)
|
||
- Quick stats (total apps, total deployments this week)
|
||
|
||
---
|
||
|
||
## Performance Considerations
|
||
|
||
- [ ] Index on (application_id, environment_id, deployment_date) for current state queries
|
||
- [ ] Pagination for deployment history (can grow large)
|
||
- [ ] Consider caching current deployment state (refresh every 5 min)
|
||
- [ ] Optimize DISTINCT ON query for PostgreSQL
|
||
|
||
---
|
||
|
||
**Story Status**: Ready for Development
|
||
**Estimated Completion**: 5-7 days
|