544 lines
12 KiB
Markdown
544 lines
12 KiB
Markdown
# Story: [Feature Name]
|
|
|
|
**Story ID:** JS-[NUMBER]
|
|
**Epic:** [Epic Name]
|
|
**Sprint:** [Sprint Number]
|
|
**Assignee:** [Developer Name]
|
|
**Status:** [To Do | In Progress | In Review | Done]
|
|
**Priority:** [P0 | P1 | P2]
|
|
**Estimated Effort:** [Small | Medium | Large] ([1-2 days | 3-5 days | 1+ weeks])
|
|
|
|
---
|
|
|
|
## Story Description
|
|
|
|
### User Story
|
|
**As a** [type of user]
|
|
**I want** [to do something]
|
|
**So that** [I can achieve some goal or benefit]
|
|
|
|
### Background
|
|
[Provide context about why this story is important and how it fits into the larger feature or product]
|
|
|
|
### Goals
|
|
1. **Goal 1:** [Specific outcome this story should achieve]
|
|
2. **Goal 2:** [Another outcome]
|
|
3. **Goal 3:** [Third outcome]
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional Requirements
|
|
- [ ] **Criterion 1:** [Specific, testable requirement]
|
|
- [ ] **Criterion 2:** [Another requirement]
|
|
- [ ] **Criterion 3:** [Third requirement]
|
|
- [ ] **Criterion 4:** [Fourth requirement]
|
|
|
|
### Technical Requirements
|
|
- [ ] TypeScript types defined with no `any` types
|
|
- [ ] Unit tests written with >80% coverage
|
|
- [ ] Integration tests for critical paths
|
|
- [ ] Error handling implemented
|
|
- [ ] Loading and error states handled in UI
|
|
- [ ] Accessibility requirements met (WCAG 2.1 AA)
|
|
- [ ] Responsive design for mobile, tablet, desktop
|
|
- [ ] API documentation updated (if applicable)
|
|
|
|
### Performance Requirements
|
|
- [ ] Component renders in < 16ms (60fps)
|
|
- [ ] API response time < 200ms (p95)
|
|
- [ ] Bundle size increase < 50KB
|
|
- [ ] Lighthouse score > 90 (if applicable)
|
|
|
|
### Security Requirements
|
|
- [ ] Input validation implemented
|
|
- [ ] XSS prevention measures in place
|
|
- [ ] CSRF protection (if applicable)
|
|
- [ ] Authentication/authorization checked
|
|
- [ ] No sensitive data in logs or error messages
|
|
|
|
---
|
|
|
|
## Technical Specification
|
|
|
|
### Frontend Implementation
|
|
|
|
#### Components to Create/Modify
|
|
1. **Component: `[ComponentName]`**
|
|
- **Location:** `src/components/[path]/[ComponentName].tsx`
|
|
- **Purpose:** [What this component does]
|
|
- **Props Interface:**
|
|
```typescript
|
|
interface [ComponentName]Props {
|
|
prop1: string;
|
|
prop2: number;
|
|
onAction?: () => void;
|
|
}
|
|
```
|
|
- **Key Features:**
|
|
- Feature 1
|
|
- Feature 2
|
|
- **State Management:** [None | Local useState | Context | Zustand | Redux]
|
|
|
|
2. **Component: `[AnotherComponent]`**
|
|
- [Similar structure as above]
|
|
|
|
#### Hooks to Create/Modify
|
|
1. **Hook: `use[HookName]`**
|
|
- **Location:** `src/hooks/use[HookName].ts`
|
|
- **Purpose:** [What this hook does]
|
|
- **Interface:**
|
|
```typescript
|
|
interface Use[HookName]Return {
|
|
data: DataType;
|
|
loading: boolean;
|
|
error: Error | null;
|
|
refetch: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
#### State Management
|
|
- **Approach:** [React Query | Zustand | Redux | Context API]
|
|
- **State Shape:**
|
|
```typescript
|
|
interface [StateName] {
|
|
field1: Type;
|
|
field2: Type;
|
|
}
|
|
```
|
|
- **Actions/Mutations:**
|
|
- `action1`: [Description]
|
|
- `action2`: [Description]
|
|
|
|
#### Styling
|
|
- **Approach:** [Tailwind CSS | CSS Modules | Styled Components]
|
|
- **New Classes/Components:** [List any new UI components or styles]
|
|
- **Responsive Breakpoints:** [mobile, tablet, desktop]
|
|
|
|
#### Route Changes (if applicable)
|
|
- **New Routes:**
|
|
- `/path/to/route` - [Description]
|
|
- **Modified Routes:**
|
|
- `/existing/route` - [Changes]
|
|
|
|
### Backend Implementation
|
|
|
|
#### API Endpoints
|
|
|
|
##### Endpoint 1: `[METHOD] /api/v1/[resource]`
|
|
- **Description:** [What this endpoint does]
|
|
- **Authentication:** [Required | Optional | None]
|
|
- **Authorization:** [Roles/permissions required]
|
|
- **Request:**
|
|
```typescript
|
|
interface Request {
|
|
params: {
|
|
id: string;
|
|
};
|
|
query?: {
|
|
page?: number;
|
|
limit?: number;
|
|
};
|
|
body: {
|
|
field1: string;
|
|
field2: number;
|
|
};
|
|
}
|
|
```
|
|
- **Response:**
|
|
```typescript
|
|
interface SuccessResponse {
|
|
data: {
|
|
id: string;
|
|
field1: string;
|
|
field2: number;
|
|
createdAt: string;
|
|
};
|
|
}
|
|
|
|
interface ErrorResponse {
|
|
error: string;
|
|
details?: string[];
|
|
}
|
|
```
|
|
- **Status Codes:**
|
|
- `200 OK` - Success
|
|
- `400 Bad Request` - Validation error
|
|
- `401 Unauthorized` - Not authenticated
|
|
- `403 Forbidden` - Not authorized
|
|
- `404 Not Found` - Resource not found
|
|
- `500 Internal Server Error` - Server error
|
|
|
|
##### Endpoint 2: `[METHOD] /api/v1/[resource]`
|
|
- [Similar structure as above]
|
|
|
|
#### Database Changes
|
|
|
|
##### Schema Changes
|
|
```typescript
|
|
// Prisma schema changes
|
|
model [ModelName] {
|
|
id String @id @default(cuid())
|
|
field1 String
|
|
field2 Int
|
|
userId String
|
|
user User @relation(fields: [userId], references: [id])
|
|
createdAt DateTime @default(now())
|
|
updatedAt DateTime @updatedAt
|
|
|
|
@@index([userId])
|
|
@@index([field1])
|
|
}
|
|
```
|
|
|
|
##### Migrations
|
|
- **Migration Name:** `add_[feature]_table`
|
|
- **Changes:**
|
|
- Create table `[table_name]`
|
|
- Add column `[column_name]` to `[table_name]`
|
|
- Add index on `[table_name].[column_name]`
|
|
|
|
##### Seeds/Data (if applicable)
|
|
- [Any initial data that needs to be seeded]
|
|
|
|
#### Service Layer
|
|
- **Service:** `[ServiceName]Service`
|
|
- **Location:** `src/services/[serviceName].service.ts`
|
|
- **Methods:**
|
|
- `create(data: CreateDto): Promise<Entity>`
|
|
- `findById(id: string): Promise<Entity | null>`
|
|
- `update(id: string, data: UpdateDto): Promise<Entity>`
|
|
- `delete(id: string): Promise<void>`
|
|
|
|
#### Validation
|
|
- **Schemas:**
|
|
```typescript
|
|
const createSchema = z.object({
|
|
field1: z.string().min(1),
|
|
field2: z.number().positive(),
|
|
});
|
|
```
|
|
|
|
#### Background Jobs (if applicable)
|
|
- **Job:** `[JobName]`
|
|
- **Trigger:** [When this job runs]
|
|
- **Purpose:** [What it does]
|
|
- **Implementation:**
|
|
```typescript
|
|
queue.add('[job-name]', data, {
|
|
attempts: 3,
|
|
backoff: { type: 'exponential', delay: 2000 },
|
|
});
|
|
```
|
|
|
|
### Integration Points
|
|
|
|
#### External APIs
|
|
- **API:** [API Name]
|
|
- **Purpose:** [Why we're calling this API]
|
|
- **Endpoints Used:**
|
|
- `[METHOD] /endpoint` - [Description]
|
|
- **Error Handling:** [How to handle API failures]
|
|
|
|
#### Third-Party Services
|
|
- **Service:** [Service Name]
|
|
- **Purpose:** [What it's used for]
|
|
- **Configuration:** [Any config needed]
|
|
|
|
---
|
|
|
|
## Data Flow
|
|
|
|
### Frontend → Backend
|
|
1. User [performs action]
|
|
2. Frontend calls `[API endpoint]`
|
|
3. Backend validates request
|
|
4. Backend processes request
|
|
5. Backend returns response
|
|
6. Frontend updates UI
|
|
|
|
### Backend → Database
|
|
1. Receive validated request data
|
|
2. Transform data for database
|
|
3. Execute database query
|
|
4. Transform database result
|
|
5. Return to controller
|
|
|
|
### Real-time Updates (if applicable)
|
|
1. Event occurs in backend
|
|
2. Publish event to WebSocket/Redis
|
|
3. Subscribers receive event
|
|
4. Frontend updates UI in real-time
|
|
|
|
---
|
|
|
|
## Testing Strategy
|
|
|
|
### Frontend Tests
|
|
|
|
#### Unit Tests
|
|
- **Component Tests:**
|
|
- Test component renders correctly
|
|
- Test props handling
|
|
- Test event handlers
|
|
- Test conditional rendering
|
|
- Test error states
|
|
|
|
- **Hook Tests:**
|
|
- Test hook return values
|
|
- Test hook state updates
|
|
- Test hook error handling
|
|
|
|
- **Utility Tests:**
|
|
- Test utility functions with various inputs
|
|
- Test edge cases
|
|
|
|
#### Integration Tests
|
|
- **User Flow:**
|
|
1. [Step 1 of user flow]
|
|
2. [Step 2 of user flow]
|
|
3. [Verify expected outcome]
|
|
|
|
- **API Integration:**
|
|
- Mock API calls
|
|
- Test success scenarios
|
|
- Test error scenarios
|
|
- Test loading states
|
|
|
|
### Backend Tests
|
|
|
|
#### Unit Tests
|
|
- **Service Tests:**
|
|
- Test business logic
|
|
- Test error handling
|
|
- Test edge cases
|
|
- Mock database calls
|
|
|
|
#### Integration Tests
|
|
- **API Tests:**
|
|
```typescript
|
|
describe('POST /api/v1/[resource]', () => {
|
|
it('creates a new resource', async () => {
|
|
const response = await request(app)
|
|
.post('/api/v1/[resource]')
|
|
.send(validData)
|
|
.expect(201);
|
|
|
|
expect(response.body).toMatchObject(expectedShape);
|
|
});
|
|
|
|
it('returns 400 for invalid data', async () => {
|
|
const response = await request(app)
|
|
.post('/api/v1/[resource]')
|
|
.send(invalidData)
|
|
.expect(400);
|
|
});
|
|
});
|
|
```
|
|
|
|
- **Database Tests:**
|
|
- Test CRUD operations
|
|
- Test transactions
|
|
- Test constraints and validations
|
|
|
|
### E2E Tests
|
|
- **Critical Path:**
|
|
1. [User action 1]
|
|
2. [User action 2]
|
|
3. [Verify result]
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
### Frontend Error Scenarios
|
|
1. **API Error:**
|
|
- Show error toast notification
|
|
- Log error to monitoring service
|
|
- Provide retry option if applicable
|
|
|
|
2. **Validation Error:**
|
|
- Show inline error messages
|
|
- Highlight invalid fields
|
|
- Prevent form submission
|
|
|
|
3. **Network Error:**
|
|
- Show offline indicator
|
|
- Queue requests for retry
|
|
- Provide manual refresh option
|
|
|
|
### Backend Error Scenarios
|
|
1. **Validation Error:**
|
|
- Return 400 with detailed error messages
|
|
- Include field-specific errors
|
|
|
|
2. **Authentication Error:**
|
|
- Return 401 with clear message
|
|
- Include info about token expiration
|
|
|
|
3. **Authorization Error:**
|
|
- Return 403 with permission info
|
|
- Log unauthorized access attempt
|
|
|
|
4. **Database Error:**
|
|
- Return 500 with generic message to user
|
|
- Log full error details
|
|
- Alert monitoring system
|
|
|
|
---
|
|
|
|
## Performance Considerations
|
|
|
|
### Frontend Performance
|
|
- [ ] Implement code splitting for heavy components
|
|
- [ ] Use React.memo for expensive components
|
|
- [ ] Implement virtualization for long lists
|
|
- [ ] Optimize images (WebP, lazy loading)
|
|
- [ ] Debounce expensive operations
|
|
- [ ] Use React Query caching effectively
|
|
|
|
### Backend Performance
|
|
- [ ] Add database indexes for queried fields
|
|
- [ ] Implement caching for frequently accessed data
|
|
- [ ] Use pagination for large datasets
|
|
- [ ] Optimize database queries (avoid N+1)
|
|
- [ ] Implement request batching if needed
|
|
|
|
### Bundle Size
|
|
- [ ] Check bundle size impact
|
|
- [ ] Use dynamic imports for large dependencies
|
|
- [ ] Tree-shake unused code
|
|
|
|
---
|
|
|
|
## Security Considerations
|
|
|
|
### Frontend Security
|
|
- [ ] Sanitize user inputs
|
|
- [ ] Implement CSP headers
|
|
- [ ] Validate data before rendering
|
|
- [ ] Don't expose sensitive data in client
|
|
- [ ] Use HTTPS only
|
|
|
|
### Backend Security
|
|
- [ ] Validate all inputs
|
|
- [ ] Use parameterized queries
|
|
- [ ] Implement rate limiting
|
|
- [ ] Check authorization on all endpoints
|
|
- [ ] Hash sensitive data
|
|
- [ ] Use security headers (Helmet.js)
|
|
- [ ] Log security events
|
|
|
|
---
|
|
|
|
## Accessibility
|
|
|
|
### Requirements
|
|
- [ ] All interactive elements keyboard accessible
|
|
- [ ] Proper ARIA labels on custom components
|
|
- [ ] Sufficient color contrast (4.5:1 minimum)
|
|
- [ ] Screen reader tested
|
|
- [ ] Focus indicators visible
|
|
- [ ] Form labels and error messages
|
|
- [ ] Skip navigation links (if applicable)
|
|
|
|
### Testing
|
|
- [ ] Run axe DevTools
|
|
- [ ] Test with keyboard only
|
|
- [ ] Test with screen reader (NVDA/VoiceOver)
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### Code Documentation
|
|
- [ ] JSDoc comments on public functions
|
|
- [ ] README updated with new features
|
|
- [ ] Component prop documentation
|
|
- [ ] API endpoint documentation
|
|
|
|
### User Documentation
|
|
- [ ] User guide updated (if applicable)
|
|
- [ ] Help text added to UI
|
|
- [ ] Tooltips for complex features
|
|
|
|
### Developer Documentation
|
|
- [ ] Architecture decision recorded
|
|
- [ ] Setup instructions updated
|
|
- [ ] API documentation generated/updated
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] All acceptance criteria met
|
|
- [ ] Code reviewed and approved
|
|
- [ ] All tests passing (unit, integration, E2E)
|
|
- [ ] Test coverage meets requirements (>80%)
|
|
- [ ] No TypeScript errors
|
|
- [ ] No ESLint errors
|
|
- [ ] Documentation updated
|
|
- [ ] Accessibility requirements met
|
|
- [ ] Performance requirements met
|
|
- [ ] Security review completed
|
|
- [ ] Deployed to staging
|
|
- [ ] QA tested on staging
|
|
- [ ] Product owner approval
|
|
- [ ] Ready for production deployment
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
### Blocked By
|
|
- [ ] [Story ID]: [Description of blocking story]
|
|
- [ ] [Story ID]: [Another blocking story]
|
|
|
|
### Blocks
|
|
- [ ] [Story ID]: [Story that depends on this one]
|
|
- [ ] [Story ID]: [Another dependent story]
|
|
|
|
### Related Stories
|
|
- [Story ID]: [Related story]
|
|
- [Story ID]: [Another related story]
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
### Technical Notes
|
|
- [Any technical considerations or decisions]
|
|
- [Trade-offs made]
|
|
- [Future improvements to consider]
|
|
|
|
### Design Notes
|
|
- [Design decisions]
|
|
- [UX considerations]
|
|
|
|
### Questions/Clarifications Needed
|
|
- [ ] **Question 1:** [Question needing clarification]
|
|
- [ ] **Question 2:** [Another question]
|
|
|
|
---
|
|
|
|
## Timeline
|
|
|
|
- **Started:** [Date]
|
|
- **In Review:** [Date]
|
|
- **Merged:** [Date]
|
|
- **Deployed to Staging:** [Date]
|
|
- **Deployed to Production:** [Date]
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- **Figma Design:** [URL]
|
|
- **PRD:** [URL]
|
|
- **Architecture Doc:** [URL]
|
|
- **API Docs:** [URL]
|
|
- **Pull Request:** [URL]
|
|
- **Staging URL:** [URL]
|
|
- **Production URL:** [URL]
|