fix: fixing agent issue

This commit is contained in:
Márcio Barroso 2025-09-24 13:07:55 -03:00
parent 6cdae4c3c6
commit 7ee26ab699
23 changed files with 245 additions and 125 deletions

View File

@ -9,6 +9,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js
## ✨ Features ## ✨ Features
### 🤖 Specialized AI Agents ### 🤖 Specialized AI Agents
- **Domain Architect** - Business domain modeling and bounded context definition - **Domain Architect** - Business domain modeling and bounded context definition
- **Next.js Architect** - Feature-Based Architecture and App Router patterns - **Next.js Architect** - Feature-Based Architecture and App Router patterns
- **BaseController Specialist** - Database-agnostic controller patterns and schema-first design - **BaseController Specialist** - Database-agnostic controller patterns and schema-first design
@ -23,6 +24,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js
- **Security Auditor** - Security best practices for modern web applications - **Security Auditor** - Security best practices for modern web applications
### 🔄 Domain-Driven Workflows ### 🔄 Domain-Driven Workflows
- **Feature-Based Project Setup** - Initialize project from `nextjs-new-app` template - **Feature-Based Project Setup** - Initialize project from `nextjs-new-app` template
- **Domain Feature Development** - Complete business domain implementation - **Domain Feature Development** - Complete business domain implementation
- **BaseController Implementation** - Database-agnostic controller setup - **BaseController Implementation** - Database-agnostic controller setup
@ -32,6 +34,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js
- **Deployment Pipeline** - Production deployment with Feature-Based Architecture - **Deployment Pipeline** - Production deployment with Feature-Based Architecture
### 📝 Architecture Templates ### 📝 Architecture Templates
- Feature Structure Template (Complete feature organization) - Feature Structure Template (Complete feature organization)
- BaseController Extension Template (Database-agnostic controller) - BaseController Extension Template (Database-agnostic controller)
- Schema-First Entity Template (Zod validation + TypeScript types) - Schema-First Entity Template (Zod validation + TypeScript types)
@ -40,6 +43,7 @@ This extension pack provides everything needed to build enterprise-grade Next.js
- Custom Hooks Template (Data fetching patterns) - Custom Hooks Template (Data fetching patterns)
### ✅ Architecture Checklists ### ✅ Architecture Checklists
- Feature-Based Architecture Development Checklist - Feature-Based Architecture Development Checklist
- BaseController Implementation Checklist - BaseController Implementation Checklist
- Domain-Driven Design Checklist - Domain-Driven Design Checklist
@ -49,7 +53,9 @@ This extension pack provides everything needed to build enterprise-grade Next.js
## 🚀 Quick Start ## 🚀 Quick Start
### Template Base ### Template Base
This extension pack is designed to work with the `nextjs-new-app` template: This extension pack is designed to work with the `nextjs-new-app` template:
```bash ```bash
# Clone the base template # Clone the base template
git clone https://github.com/marciobarroso/nextjs-new-app.git my-project git clone https://github.com/marciobarroso/nextjs-new-app.git my-project
@ -60,6 +66,7 @@ pnpm install # or npm install
``` ```
### Extension Pack Usage ### Extension Pack Usage
```bash ```bash
# Use BMAD Method with this extension pack # Use BMAD Method with this extension pack
bmad-fba create-feature "user-management" bmad-fba create-feature "user-management"
@ -88,12 +95,14 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
## 📚 Documentation ## 📚 Documentation
### Core Concepts ### Core Concepts
- [Project Structure](docs/project-structure.md) - [Project Structure](docs/project-structure.md)
- [Component Patterns](docs/component-patterns.md) - [Component Patterns](docs/component-patterns.md)
- [API Design](docs/api-design.md) - [API Design](docs/api-design.md)
- [State Management](docs/state-management.md) - [State Management](docs/state-management.md)
### Guides ### Guides
- [Getting Started](docs/getting-started.md) - [Getting Started](docs/getting-started.md)
- [Development Workflow](docs/development-workflow.md) - [Development Workflow](docs/development-workflow.md)
- [Testing Strategy](docs/testing-strategy.md) - [Testing Strategy](docs/testing-strategy.md)
@ -102,6 +111,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
## 🛠️ Technology Stack ## 🛠️ Technology Stack
### Core Technologies (from nextjs-new-app template) ### Core Technologies (from nextjs-new-app template)
- **Next.js 15.5.3** - React framework with App Router - **Next.js 15.5.3** - React framework with App Router
- **React 19.1.0** - Latest React with modern features - **React 19.1.0** - Latest React with modern features
- **TypeScript 5** - Strict type safety - **TypeScript 5** - Strict type safety
@ -110,12 +120,14 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
- **pnpm** - Efficient package management - **pnpm** - Efficient package management
### Development Tools (pre-configured) ### Development Tools (pre-configured)
- **ESLint 9** - Code linting with Next.js integration - **ESLint 9** - Code linting with Next.js integration
- **Prettier 3.6.2** - Code formatting with import sorting - **Prettier 3.6.2** - Code formatting with import sorting
- **Husky 9.1.7** - Git hooks for code quality - **Husky 9.1.7** - Git hooks for code quality
- **Jest** - Testing framework (configured, ready for implementation) - **Jest** - Testing framework (configured, ready for implementation)
### Feature-Based Architecture Additions ### Feature-Based Architecture Additions
- **Zod** - Schema validation and type generation - **Zod** - Schema validation and type generation
- **BaseController Pattern** - Database-agnostic CRUD operations - **BaseController Pattern** - Database-agnostic CRUD operations
- **Domain-Driven Design** - Business domain organization - **Domain-Driven Design** - Business domain organization
@ -124,6 +136,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
## 🎯 Best Practices ## 🎯 Best Practices
### Code Quality ### Code Quality
- Strict TypeScript configuration - Strict TypeScript configuration
- Comprehensive ESLint rules - Comprehensive ESLint rules
- Automatic code formatting with Prettier - Automatic code formatting with Prettier
@ -131,6 +144,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
- API-first design approach - API-first design approach
### Performance ### Performance
- Server Components by default - Server Components by default
- Client Components only when needed - Client Components only when needed
- Image optimization with Next.js Image - Image optimization with Next.js Image
@ -138,6 +152,7 @@ This extension pack implements Feature-Based Architecture with Domain-Driven Des
- Core Web Vitals monitoring - Core Web Vitals monitoring
### Security ### Security
- Input validation with Zod - Input validation with Zod
- CSRF protection - CSRF protection
- Secure headers middleware - Secure headers middleware
@ -195,6 +210,7 @@ This extension pack is part of the BMAD Method project and follows the same MIT
**Current Version:** 1.0.0 **Current Version:** 1.0.0
**Compatibility:** **Compatibility:**
- Next.js 14+ - Next.js 14+
- Node.js 18+ - Node.js 18+
- TypeScript 5+ - TypeScript 5+

View File

@ -1,6 +1,7 @@
# BaseController Implementation Checklist # BaseController Implementation Checklist
## Abstract Class Setup ## Abstract Class Setup
- [ ] BaseController abstract class created in `shared/core/` - [ ] BaseController abstract class created in `shared/core/`
- [ ] Generic type parameter `<T>` properly defined - [ ] Generic type parameter `<T>` properly defined
- [ ] Database client abstraction implemented - [ ] Database client abstraction implemented
@ -8,6 +9,7 @@
- [ ] Constructor properly initializes dependencies - [ ] Constructor properly initializes dependencies
## CRUD Operations Implementation ## CRUD Operations Implementation
- [ ] `getAll` method implemented with pagination - [ ] `getAll` method implemented with pagination
- [ ] `getById` method implemented with proper error handling - [ ] `getById` method implemented with proper error handling
- [ ] `create` method implemented with validation - [ ] `create` method implemented with validation
@ -16,6 +18,7 @@
- [ ] All methods return proper HTTP responses - [ ] All methods return proper HTTP responses
## Search & Filtering ## Search & Filtering
- [ ] Abstract `buildSearchFilter` method defined - [ ] Abstract `buildSearchFilter` method defined
- [ ] Search parameter extraction implemented - [ ] Search parameter extraction implemented
- [ ] Database-agnostic filter pattern established - [ ] Database-agnostic filter pattern established
@ -24,6 +27,7 @@
- [ ] Search performance considered - [ ] Search performance considered
## Validation & Schema Integration ## Validation & Schema Integration
- [ ] Zod schema validation on all inputs - [ ] Zod schema validation on all inputs
- [ ] Create schema validation implemented - [ ] Create schema validation implemented
- [ ] Update schema validation implemented - [ ] Update schema validation implemented
@ -32,6 +36,7 @@
- [ ] Validation error messages are user-friendly - [ ] Validation error messages are user-friendly
## Error Handling ## Error Handling
- [ ] Consistent error response format - [ ] Consistent error response format
- [ ] HTTP status codes properly used - [ ] HTTP status codes properly used
- [ ] Validation errors properly formatted - [ ] Validation errors properly formatted
@ -40,6 +45,7 @@
- [ ] Error messages don't expose sensitive data - [ ] Error messages don't expose sensitive data
## Database Abstraction ## Database Abstraction
- [ ] Database client interface defined - [ ] Database client interface defined
- [ ] Connection management abstracted - [ ] Connection management abstracted
- [ ] Database-specific operations isolated - [ ] Database-specific operations isolated
@ -48,6 +54,7 @@
- [ ] Connection pooling handled - [ ] Connection pooling handled
## Response Formatting ## Response Formatting
- [ ] Consistent API response structure - [ ] Consistent API response structure
- [ ] Success responses properly formatted - [ ] Success responses properly formatted
- [ ] Error responses standardized - [ ] Error responses standardized
@ -56,6 +63,7 @@
- [ ] Content-Type headers set correctly - [ ] Content-Type headers set correctly
## Feature Controller Extension ## Feature Controller Extension
- [ ] Feature controller extends BaseController - [ ] Feature controller extends BaseController
- [ ] Entity-specific `buildSearchFilter` implemented - [ ] Entity-specific `buildSearchFilter` implemented
- [ ] Custom business logic methods added - [ ] Custom business logic methods added
@ -64,6 +72,7 @@
- [ ] Controller singleton pattern implemented (if needed) - [ ] Controller singleton pattern implemented (if needed)
## Type Safety ## Type Safety
- [ ] Generic types properly constrained - [ ] Generic types properly constrained
- [ ] Entity model interfaces defined - [ ] Entity model interfaces defined
- [ ] API response types defined - [ ] API response types defined
@ -72,6 +81,7 @@
- [ ] Return types explicitly defined - [ ] Return types explicitly defined
## Performance Optimization ## Performance Optimization
- [ ] Database queries optimized - [ ] Database queries optimized
- [ ] Proper indexing strategy planned - [ ] Proper indexing strategy planned
- [ ] Pagination limits enforced - [ ] Pagination limits enforced
@ -80,6 +90,7 @@
- [ ] Database connection reuse implemented - [ ] Database connection reuse implemented
## Testing ## Testing
- [ ] Unit tests for BaseController methods - [ ] Unit tests for BaseController methods
- [ ] Mock database client created - [ ] Mock database client created
- [ ] Test data fixtures defined - [ ] Test data fixtures defined
@ -88,6 +99,7 @@
- [ ] Performance tests implemented - [ ] Performance tests implemented
## Documentation ## Documentation
- [ ] BaseController usage documented - [ ] BaseController usage documented
- [ ] Extension patterns documented - [ ] Extension patterns documented
- [ ] Database integration examples provided - [ ] Database integration examples provided
@ -96,6 +108,7 @@
- [ ] Performance considerations documented - [ ] Performance considerations documented
## Logging & Monitoring ## Logging & Monitoring
- [ ] Request/response logging implemented - [ ] Request/response logging implemented
- [ ] Error logging with stack traces - [ ] Error logging with stack traces
- [ ] Performance metrics captured - [ ] Performance metrics captured
@ -104,6 +117,7 @@
- [ ] Audit trail for data changes - [ ] Audit trail for data changes
## Security Considerations ## Security Considerations
- [ ] Input sanitization implemented - [ ] Input sanitization implemented
- [ ] SQL injection prevention (for SQL databases) - [ ] SQL injection prevention (for SQL databases)
- [ ] NoSQL injection prevention (for NoSQL databases) - [ ] NoSQL injection prevention (for NoSQL databases)
@ -112,7 +126,9 @@
- [ ] Sensitive data handling - [ ] Sensitive data handling
## Database-Specific Implementations ## Database-Specific Implementations
### For SQL Databases (Prisma/TypeORM) ### For SQL Databases (Prisma/TypeORM)
- [ ] Proper WHERE clause generation - [ ] Proper WHERE clause generation
- [ ] JOIN operations handled - [ ] JOIN operations handled
- [ ] Transaction support implemented - [ ] Transaction support implemented
@ -120,6 +136,7 @@
- [ ] Relationship loading optimized - [ ] Relationship loading optimized
### For MongoDB (Mongoose) ### For MongoDB (Mongoose)
- [ ] Query object generation - [ ] Query object generation
- [ ] Aggregation pipeline support - [ ] Aggregation pipeline support
- [ ] Index utilization optimized - [ ] Index utilization optimized
@ -127,6 +144,7 @@
- [ ] Connection string security - [ ] Connection string security
### For Serverless Databases ### For Serverless Databases
- [ ] Connection pooling optimized - [ ] Connection pooling optimized
- [ ] Cold start mitigation - [ ] Cold start mitigation
- [ ] Query timeout handling - [ ] Query timeout handling
@ -134,6 +152,7 @@
- [ ] Cost optimization considered - [ ] Cost optimization considered
## Integration Points ## Integration Points
- [ ] Authentication middleware integration - [ ] Authentication middleware integration
- [ ] Authorization checks implemented - [ ] Authorization checks implemented
- [ ] Audit logging integrated - [ ] Audit logging integrated
@ -142,6 +161,7 @@
- [ ] External API integration patterns - [ ] External API integration patterns
## Production Readiness ## Production Readiness
- [ ] Environment variable configuration - [ ] Environment variable configuration
- [ ] Production database connection - [ ] Production database connection
- [ ] Error monitoring integration - [ ] Error monitoring integration

View File

@ -1,12 +1,14 @@
# React Component Development Checklist # React Component Development Checklist
## Pre-Development ## Pre-Development
- [ ] Component purpose and requirements clearly defined - [ ] Component purpose and requirements clearly defined
- [ ] Component interface (props) designed - [ ] Component interface (props) designed
- [ ] Accessibility requirements identified - [ ] Accessibility requirements identified
- [ ] Design mockup/wireframe available - [ ] Design mockup/wireframe available
## Development ## Development
- [ ] TypeScript interface defined for all props - [ ] TypeScript interface defined for all props
- [ ] Component follows naming conventions (PascalCase) - [ ] Component follows naming conventions (PascalCase)
- [ ] Proper file structure and organization - [ ] Proper file structure and organization
@ -14,6 +16,7 @@
- [ ] Error boundaries implemented for critical components - [ ] Error boundaries implemented for critical components
## Styling ## Styling
- [ ] Tailwind CSS classes used consistently - [ ] Tailwind CSS classes used consistently
- [ ] Responsive design implemented - [ ] Responsive design implemented
- [ ] Dark mode support (if applicable) - [ ] Dark mode support (if applicable)
@ -21,6 +24,7 @@
- [ ] CSS class conflicts avoided - [ ] CSS class conflicts avoided
## Accessibility (a11y) ## Accessibility (a11y)
- [ ] Semantic HTML elements used - [ ] Semantic HTML elements used
- [ ] ARIA labels added where needed - [ ] ARIA labels added where needed
- [ ] Keyboard navigation supported - [ ] Keyboard navigation supported
@ -29,6 +33,7 @@
- [ ] Color contrast meets WCAG guidelines - [ ] Color contrast meets WCAG guidelines
## Performance ## Performance
- [ ] Unnecessary re-renders avoided - [ ] Unnecessary re-renders avoided
- [ ] React.memo used where appropriate - [ ] React.memo used where appropriate
- [ ] Heavy computations memoized with useMemo - [ ] Heavy computations memoized with useMemo
@ -36,6 +41,7 @@
- [ ] Large lists virtualized (if applicable) - [ ] Large lists virtualized (if applicable)
## Testing ## Testing
- [ ] Unit tests written and passing - [ ] Unit tests written and passing
- [ ] Component renders without crashing - [ ] Component renders without crashing
- [ ] Props validation tested - [ ] Props validation tested
@ -44,6 +50,7 @@
- [ ] Accessibility testing performed - [ ] Accessibility testing performed
## Code Quality ## Code Quality
- [ ] TypeScript types are strict and accurate - [ ] TypeScript types are strict and accurate
- [ ] ESLint rules pass - [ ] ESLint rules pass
- [ ] Prettier formatting applied - [ ] Prettier formatting applied
@ -52,6 +59,7 @@
- [ ] Comments added for complex logic - [ ] Comments added for complex logic
## Integration ## Integration
- [ ] Component integrates well with parent components - [ ] Component integrates well with parent components
- [ ] State management working correctly - [ ] State management working correctly
- [ ] API calls handled properly (if applicable) - [ ] API calls handled properly (if applicable)
@ -59,12 +67,14 @@
- [ ] Loading states implemented - [ ] Loading states implemented
## Documentation ## Documentation
- [ ] Component documented with JSDoc comments - [ ] Component documented with JSDoc comments
- [ ] Props interface documented - [ ] Props interface documented
- [ ] Usage examples provided - [ ] Usage examples provided
- [ ] Storybook story created (if using Storybook) - [ ] Storybook story created (if using Storybook)
## Review ## Review
- [ ] Code review completed - [ ] Code review completed
- [ ] Design review completed - [ ] Design review completed
- [ ] Performance review completed - [ ] Performance review completed

View File

@ -1,6 +1,7 @@
# Feature-Based Architecture Development Checklist # Feature-Based Architecture Development Checklist
## Domain Analysis & Planning ## Domain Analysis & Planning
- [ ] Business domain clearly identified and defined - [ ] Business domain clearly identified and defined
- [ ] Bounded context boundaries established - [ ] Bounded context boundaries established
- [ ] Domain entities and relationships mapped - [ ] Domain entities and relationships mapped
@ -9,6 +10,7 @@
- [ ] Business requirements thoroughly documented - [ ] Business requirements thoroughly documented
## Project Structure ## Project Structure
- [ ] Feature organized in `(features)/({feature-name})/` route group - [ ] Feature organized in `(features)/({feature-name})/` route group
- [ ] API layer structured in `api/{entity-name}/` directory - [ ] API layer structured in `api/{entity-name}/` directory
- [ ] Components organized in `components/` directory within feature - [ ] Components organized in `components/` directory within feature
@ -17,6 +19,7 @@
- [ ] Feature pages organized in appropriate subdirectories - [ ] Feature pages organized in appropriate subdirectories
## Schema-First Development ## Schema-First Development
- [ ] Zod schema defined for entity validation - [ ] Zod schema defined for entity validation
- [ ] TypeScript interfaces derived from Zod schemas - [ ] TypeScript interfaces derived from Zod schemas
- [ ] Create, Update, and Search schemas properly defined - [ ] Create, Update, and Search schemas properly defined
@ -25,6 +28,7 @@
- [ ] Schema validation covers all business rules - [ ] Schema validation covers all business rules
## BaseController Implementation ## BaseController Implementation
- [ ] Entity controller extends BaseController abstract class - [ ] Entity controller extends BaseController abstract class
- [ ] Database-agnostic design maintained - [ ] Database-agnostic design maintained
- [ ] `buildSearchFilter` method implemented for entity-specific search - [ ] `buildSearchFilter` method implemented for entity-specific search
@ -33,6 +37,7 @@
- [ ] Controller uses Zod schema for validation - [ ] Controller uses Zod schema for validation
## API Routes Development ## API Routes Development
- [ ] Collection routes (`/api/{entity}`) implemented - [ ] Collection routes (`/api/{entity}`) implemented
- [ ] Individual entity routes (`/api/{entity}/[id]`) implemented - [ ] Individual entity routes (`/api/{entity}/[id]`) implemented
- [ ] HTTP methods properly implemented (GET, POST, PUT, DELETE) - [ ] HTTP methods properly implemented (GET, POST, PUT, DELETE)
@ -41,6 +46,7 @@
- [ ] Database connection properly managed - [ ] Database connection properly managed
## Custom Hooks Implementation ## Custom Hooks Implementation
- [ ] Data fetching hooks follow naming convention (`use{Entities}`) - [ ] Data fetching hooks follow naming convention (`use{Entities}`)
- [ ] Mutation hooks follow naming convention (`use{Entity}Mutations`) - [ ] Mutation hooks follow naming convention (`use{Entity}Mutations`)
- [ ] Single entity hooks follow naming convention (`use{Entity}`) - [ ] Single entity hooks follow naming convention (`use{Entity}`)
@ -50,6 +56,7 @@
- [ ] Search functionality integrated - [ ] Search functionality integrated
## React Components ## React Components
- [ ] Components follow PascalCase naming convention - [ ] Components follow PascalCase naming convention
- [ ] Form components implemented (`{Entity}Form`) - [ ] Form components implemented (`{Entity}Form`)
- [ ] List components implemented (`{Entity}List`) - [ ] List components implemented (`{Entity}List`)
@ -60,6 +67,7 @@
- [ ] Components follow accessibility guidelines - [ ] Components follow accessibility guidelines
## Next.js Pages ## Next.js Pages
- [ ] Feature index page implemented (`page.tsx`) - [ ] Feature index page implemented (`page.tsx`)
- [ ] Entity detail pages implemented (`[id]/page.tsx`) - [ ] Entity detail pages implemented (`[id]/page.tsx`)
- [ ] Create new entity page implemented (`new/page.tsx`) - [ ] Create new entity page implemented (`new/page.tsx`)
@ -69,6 +77,7 @@
- [ ] Proper layouts and navigation implemented - [ ] Proper layouts and navigation implemented
## Type Safety ## Type Safety
- [ ] Strict TypeScript configuration enforced - [ ] Strict TypeScript configuration enforced
- [ ] No `any` types used - [ ] No `any` types used
- [ ] End-to-end type safety from database to UI - [ ] End-to-end type safety from database to UI
@ -77,6 +86,7 @@
- [ ] Generic types used appropriately - [ ] Generic types used appropriately
## Code Quality ## Code Quality
- [ ] ESLint rules passing without warnings - [ ] ESLint rules passing without warnings
- [ ] Prettier formatting applied consistently - [ ] Prettier formatting applied consistently
- [ ] No console statements in production code - [ ] No console statements in production code
@ -85,6 +95,7 @@
- [ ] Code follows established conventions - [ ] Code follows established conventions
## Testing ## Testing
- [ ] Unit tests for controller logic - [ ] Unit tests for controller logic
- [ ] API route integration tests - [ ] API route integration tests
- [ ] React component tests - [ ] React component tests
@ -93,6 +104,7 @@
- [ ] Test data and mocks properly implemented - [ ] Test data and mocks properly implemented
## Database Integration ## Database Integration
- [ ] Database connection abstracted properly - [ ] Database connection abstracted properly
- [ ] ORM/ODM integration follows patterns - [ ] ORM/ODM integration follows patterns
- [ ] Migration strategy considered - [ ] Migration strategy considered
@ -101,6 +113,7 @@
- [ ] Data relationships properly modeled - [ ] Data relationships properly modeled
## Performance Considerations ## Performance Considerations
- [ ] Server Components used for data fetching - [ ] Server Components used for data fetching
- [ ] Client Components minimized - [ ] Client Components minimized
- [ ] Database queries optimized - [ ] Database queries optimized
@ -109,6 +122,7 @@
- [ ] Bundle size impact assessed - [ ] Bundle size impact assessed
## Security ## Security
- [ ] Input validation on all API endpoints - [ ] Input validation on all API endpoints
- [ ] Authentication/authorization considered - [ ] Authentication/authorization considered
- [ ] SQL injection prevention (if using SQL database) - [ ] SQL injection prevention (if using SQL database)
@ -117,6 +131,7 @@
- [ ] Error messages don't leak sensitive information - [ ] Error messages don't leak sensitive information
## Documentation ## Documentation
- [ ] Feature purpose and scope documented - [ ] Feature purpose and scope documented
- [ ] API endpoints documented - [ ] API endpoints documented
- [ ] Component usage examples provided - [ ] Component usage examples provided
@ -125,6 +140,7 @@
- [ ] Database schema documented - [ ] Database schema documented
## Integration & Dependencies ## Integration & Dependencies
- [ ] Shared infrastructure properly utilized - [ ] Shared infrastructure properly utilized
- [ ] Cross-feature dependencies minimized - [ ] Cross-feature dependencies minimized
- [ ] Integration points well-defined - [ ] Integration points well-defined
@ -133,6 +149,7 @@
- [ ] Feature can be tested in isolation - [ ] Feature can be tested in isolation
## Deployment Readiness ## Deployment Readiness
- [ ] Environment variables properly configured - [ ] Environment variables properly configured
- [ ] Production build successful - [ ] Production build successful
- [ ] Database migrations ready (if needed) - [ ] Database migrations ready (if needed)
@ -141,6 +158,7 @@
- [ ] Health checks implemented - [ ] Health checks implemented
## Review & Quality Assurance ## Review & Quality Assurance
- [ ] Code review completed - [ ] Code review completed
- [ ] Architecture review completed - [ ] Architecture review completed
- [ ] Business logic verified - [ ] Business logic verified

View File

@ -1,9 +1,11 @@
# Create API Endpoint # Create API Endpoint
## Task Overview ## Task Overview
Create a new API endpoint in Next.js with proper TypeScript typing, validation, and error handling. Create a new API endpoint in Next.js with proper TypeScript typing, validation, and error handling.
## Prerequisites ## Prerequisites
- Next.js project with App Router - Next.js project with App Router
- TypeScript configured - TypeScript configured
- Understanding of HTTP methods and status codes - Understanding of HTTP methods and status codes
@ -11,9 +13,11 @@ Create a new API endpoint in Next.js with proper TypeScript typing, validation,
## Steps ## Steps
### 1. Create API Route File ### 1. Create API Route File
Create `src/app/api/{endpoint}/route.ts`: Create `src/app/api/{endpoint}/route.ts`:
```typescript ```typescript
import { NextRequest, NextResponse } from 'next/server' import { NextRequest, NextResponse } from 'next/server';
// Define request/response types // Define request/response types
interface RequestBody { interface RequestBody {
@ -29,72 +33,65 @@ export async function GET(request: NextRequest) {
// Handle GET request logic // Handle GET request logic
const data: ResponseData = { const data: ResponseData = {
// Your response data // Your response data
} };
return NextResponse.json(data, { status: 200 }) return NextResponse.json(data, { status: 200 });
} catch (error) { } catch (error) {
console.error('API Error:', error) console.error('API Error:', error);
return NextResponse.json( return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
{ error: 'Internal server error' },
{ status: 500 }
)
} }
} }
export async function POST(request: NextRequest) { export async function POST(request: NextRequest) {
try { try {
const body: RequestBody = await request.json() const body: RequestBody = await request.json();
// Validate request body // Validate request body
if (!body) { if (!body) {
return NextResponse.json( return NextResponse.json({ error: 'Request body is required' }, { status: 400 });
{ error: 'Request body is required' },
{ status: 400 }
)
} }
// Handle POST request logic // Handle POST request logic
const data: ResponseData = { const data: ResponseData = {
// Your response data // Your response data
} };
return NextResponse.json(data, { status: 201 }) return NextResponse.json(data, { status: 201 });
} catch (error) { } catch (error) {
console.error('API Error:', error) console.error('API Error:', error);
return NextResponse.json( return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
{ error: 'Internal server error' },
{ status: 500 }
)
} }
} }
``` ```
### 2. Add Request Validation (Optional) ### 2. Add Request Validation (Optional)
Install and use Zod for validation: Install and use Zod for validation:
```bash ```bash
npm install zod npm install zod
``` ```
```typescript ```typescript
import { z } from 'zod' import { z } from 'zod';
const requestSchema = z.object({ const requestSchema = z.object({
name: z.string().min(1), name: z.string().min(1),
email: z.string().email(), email: z.string().email(),
}) });
export async function POST(request: NextRequest) { export async function POST(request: NextRequest) {
try { try {
const body = await request.json() const body = await request.json();
const validatedData = requestSchema.parse(body) const validatedData = requestSchema.parse(body);
// Use validatedData safely // Use validatedData safely
} catch (error) { } catch (error) {
if (error instanceof z.ZodError) { if (error instanceof z.ZodError) {
return NextResponse.json( return NextResponse.json(
{ error: 'Invalid request data', details: error.errors }, { error: 'Invalid request data', details: error.errors },
{ status: 400 } { status: 400 },
) );
} }
// Handle other errors // Handle other errors
} }
@ -102,36 +99,39 @@ export async function POST(request: NextRequest) {
``` ```
### 3. Create API Client Helper ### 3. Create API Client Helper
Create `src/lib/api-client.ts`: Create `src/lib/api-client.ts`:
```typescript ```typescript
class ApiError extends Error { class ApiError extends Error {
constructor(public status: number, message: string) { constructor(
super(message) public status: number,
this.name = 'ApiError' message: string,
) {
super(message);
this.name = 'ApiError';
} }
} }
export async function apiCall<T>( export async function apiCall<T>(url: string, options?: RequestInit): Promise<T> {
url: string,
options?: RequestInit
): Promise<T> {
const response = await fetch(url, { const response = await fetch(url, {
headers: { headers: {
'Content-Type': 'application/json', 'Content-Type': 'application/json',
...options?.headers, ...options?.headers,
}, },
...options, ...options,
}) });
if (!response.ok) { if (!response.ok) {
throw new ApiError(response.status, `HTTP error! status: ${response.status}`) throw new ApiError(response.status, `HTTP error! status: ${response.status}`);
} }
return response.json() return response.json();
} }
``` ```
### 4. Use in Components ### 4. Use in Components
```typescript ```typescript
'use client' 'use client'
@ -164,6 +164,7 @@ export function ExampleComponent() {
``` ```
## Validation Checklist ## Validation Checklist
- [ ] API route file created in correct location - [ ] API route file created in correct location
- [ ] Proper TypeScript types defined - [ ] Proper TypeScript types defined
- [ ] Error handling implemented - [ ] Error handling implemented
@ -173,6 +174,7 @@ export function ExampleComponent() {
- [ ] Error cases handled gracefully - [ ] Error cases handled gracefully
## Best Practices ## Best Practices
- Use proper HTTP status codes - Use proper HTTP status codes
- Implement consistent error response format - Implement consistent error response format
- Add request validation for security - Add request validation for security

View File

@ -1,9 +1,11 @@
# Setup Project from nextjs-new-app Template # Setup Project from nextjs-new-app Template
## Task Overview ## Task Overview
Initialize a new Feature-Based Architecture project using the pre-configured `nextjs-new-app` template with Next.js 15+, TypeScript, Tailwind CSS 4.x, and development tooling. Initialize a new Feature-Based Architecture project using the pre-configured `nextjs-new-app` template with Next.js 15+, TypeScript, Tailwind CSS 4.x, and development tooling.
## Prerequisites ## Prerequisites
- Node.js 20.10.0+ installed - Node.js 20.10.0+ installed
- pnpm (recommended) or npm package manager - pnpm (recommended) or npm package manager
- Git for version control - Git for version control
@ -12,6 +14,7 @@ Initialize a new Feature-Based Architecture project using the pre-configured `ne
## Steps ## Steps
### 1. Clone Template Repository ### 1. Clone Template Repository
```bash ```bash
# Clone the nextjs-new-app template # Clone the nextjs-new-app template
git clone https://github.com/marciobarroso/nextjs-new-app.git {project_name} git clone https://github.com/marciobarroso/nextjs-new-app.git {project_name}
@ -25,6 +28,7 @@ git commit -m "Initial commit from nextjs-new-app template"
``` ```
### 2. Install Dependencies ### 2. Install Dependencies
```bash ```bash
# Install using pnpm (recommended by template) # Install using pnpm (recommended by template)
pnpm install pnpm install
@ -34,7 +38,9 @@ pnpm install
``` ```
### 3. Configure Project Details ### 3. Configure Project Details
Update `package.json`: Update `package.json`:
```json ```json
{ {
"name": "{project_name}", "name": "{project_name}",
@ -45,6 +51,7 @@ Update `package.json`:
``` ```
### 4. Set Up Feature-Based Architecture Structure ### 4. Set Up Feature-Based Architecture Structure
```bash ```bash
# Create the Feature-Based Architecture directories # Create the Feature-Based Architecture directories
mkdir -p app/\(features\) mkdir -p app/\(features\)
@ -60,122 +67,134 @@ mkdir -p app/shared/lib
``` ```
### 5. Implement BaseController Foundation ### 5. Implement BaseController Foundation
Create `app/shared/core/base-controller.ts`: Create `app/shared/core/base-controller.ts`:
```typescript ```typescript
import { z } from 'zod' import { z } from 'zod';
import { NextRequest, NextResponse } from 'next/server' import { NextRequest, NextResponse } from 'next/server';
export abstract class BaseController<T> { export abstract class BaseController<T> {
protected dbClient: any protected dbClient: any;
protected schema?: z.ZodSchema protected schema?: z.ZodSchema;
constructor(dbClient: any, schema?: z.ZodSchema) { constructor(dbClient: any, schema?: z.ZodSchema) {
this.dbClient = dbClient this.dbClient = dbClient;
this.schema = schema this.schema = schema;
} }
// Standard CRUD operations // Standard CRUD operations
async getAll(request: NextRequest): Promise<NextResponse> { async getAll(request: NextRequest): Promise<NextResponse> {
try { try {
const { searchParams } = new URL(request.url) const { searchParams } = new URL(request.url);
const query = searchParams.get('query') const query = searchParams.get('query');
const page = parseInt(searchParams.get('page') || '1') const page = parseInt(searchParams.get('page') || '1');
const limit = parseInt(searchParams.get('limit') || '20') const limit = parseInt(searchParams.get('limit') || '20');
const filter = this.buildSearchFilter(query) const filter = this.buildSearchFilter(query);
// Implement database-specific query here // Implement database-specific query here
return NextResponse.json({ return NextResponse.json({
data: [], data: [],
pagination: { page, limit, total: 0, totalPages: 0 }, pagination: { page, limit, total: 0, totalPages: 0 },
success: true success: true,
}) });
} catch (error) { } catch (error) {
return NextResponse.json( return NextResponse.json(
{ error: 'Failed to fetch records', success: false }, { error: 'Failed to fetch records', success: false },
{ status: 500 } { status: 500 },
) );
} }
} }
async getById(request: NextRequest, { params }: { params: { id: string } }): Promise<NextResponse> { async getById(
request: NextRequest,
{ params }: { params: { id: string } },
): Promise<NextResponse> {
try { try {
// Implement database-specific findById here // Implement database-specific findById here
return NextResponse.json({ data: null, success: true }) return NextResponse.json({ data: null, success: true });
} catch (error) { } catch (error) {
return NextResponse.json( return NextResponse.json(
{ error: 'Failed to fetch record', success: false }, { error: 'Failed to fetch record', success: false },
{ status: 500 } { status: 500 },
) );
} }
} }
async create(request: NextRequest): Promise<NextResponse> { async create(request: NextRequest): Promise<NextResponse> {
try { try {
const body = await request.json() const body = await request.json();
if (this.schema) { if (this.schema) {
const validatedData = this.schema.parse(body) const validatedData = this.schema.parse(body);
// Implement database-specific create here // Implement database-specific create here
} }
return NextResponse.json({ data: null, success: true }, { status: 201 }) return NextResponse.json({ data: null, success: true }, { status: 201 });
} catch (error) { } catch (error) {
if (error instanceof z.ZodError) { if (error instanceof z.ZodError) {
return NextResponse.json( return NextResponse.json(
{ error: 'Validation failed', details: error.errors, success: false }, { error: 'Validation failed', details: error.errors, success: false },
{ status: 400 } { status: 400 },
) );
} }
return NextResponse.json( return NextResponse.json(
{ error: 'Failed to create record', success: false }, { error: 'Failed to create record', success: false },
{ status: 500 } { status: 500 },
) );
} }
} }
async update(request: NextRequest, { params }: { params: { id: string } }): Promise<NextResponse> { async update(
request: NextRequest,
{ params }: { params: { id: string } },
): Promise<NextResponse> {
try { try {
const body = await request.json() const body = await request.json();
if (this.schema) { if (this.schema) {
const validatedData = this.schema.partial().parse(body) const validatedData = this.schema.partial().parse(body);
// Implement database-specific update here // Implement database-specific update here
} }
return NextResponse.json({ data: null, success: true }) return NextResponse.json({ data: null, success: true });
} catch (error) { } catch (error) {
if (error instanceof z.ZodError) { if (error instanceof z.ZodError) {
return NextResponse.json( return NextResponse.json(
{ error: 'Validation failed', details: error.errors, success: false }, { error: 'Validation failed', details: error.errors, success: false },
{ status: 400 } { status: 400 },
) );
} }
return NextResponse.json( return NextResponse.json(
{ error: 'Failed to update record', success: false }, { error: 'Failed to update record', success: false },
{ status: 500 } { status: 500 },
) );
} }
} }
async delete(request: NextRequest, { params }: { params: { id: string } }): Promise<NextResponse> { async delete(
request: NextRequest,
{ params }: { params: { id: string } },
): Promise<NextResponse> {
try { try {
// Implement database-specific delete here // Implement database-specific delete here
return NextResponse.json({ success: true, message: 'Record deleted successfully' }) return NextResponse.json({ success: true, message: 'Record deleted successfully' });
} catch (error) { } catch (error) {
return NextResponse.json( return NextResponse.json(
{ error: 'Failed to delete record', success: false }, { error: 'Failed to delete record', success: false },
{ status: 500 } { status: 500 },
) );
} }
} }
// Abstract method for search filtering // Abstract method for search filtering
protected abstract buildSearchFilter(query: string | null): Record<string, any> protected abstract buildSearchFilter(query: string | null): Record<string, any>;
} }
``` ```
### 6. Add Zod for Schema Validation ### 6. Add Zod for Schema Validation
```bash ```bash
# Install Zod for schema validation # Install Zod for schema validation
pnpm add zod pnpm add zod
@ -183,7 +202,9 @@ pnpm add zod
``` ```
### 7. Configure Environment Variables ### 7. Configure Environment Variables
Create `.env.local`: Create `.env.local`:
```env ```env
# Database Configuration (customize based on your choice) # Database Configuration (customize based on your choice)
DATABASE_URL="your-database-url" DATABASE_URL="your-database-url"
@ -196,7 +217,9 @@ NEXT_PUBLIC_APP_VERSION="1.0.0"
``` ```
### 8. Update TypeScript Configuration ### 8. Update TypeScript Configuration
The template already provides optimal TypeScript configuration, but you can extend `tsconfig.json` if needed: The template already provides optimal TypeScript configuration, but you can extend `tsconfig.json` if needed:
```json ```json
{ {
"compilerOptions": { "compilerOptions": {
@ -210,6 +233,7 @@ The template already provides optimal TypeScript configuration, but you can exte
``` ```
### 9. Test the Setup ### 9. Test the Setup
```bash ```bash
# Run development server # Run development server
pnpm dev pnpm dev
@ -229,6 +253,7 @@ pnpm build
``` ```
### 10. Initialize Git Repository ### 10. Initialize Git Repository
```bash ```bash
# Add remote repository (replace with your repository URL) # Add remote repository (replace with your repository URL)
git remote add origin https://github.com/yourusername/{project_name}.git git remote add origin https://github.com/yourusername/{project_name}.git
@ -249,6 +274,7 @@ git push -u origin main
``` ```
## Validation Checklist ## Validation Checklist
- [ ] Template repository successfully cloned - [ ] Template repository successfully cloned
- [ ] Dependencies installed without errors - [ ] Dependencies installed without errors
- [ ] Development server runs on http://localhost:3000 - [ ] Development server runs on http://localhost:3000
@ -261,6 +287,7 @@ git push -u origin main
- [ ] Git repository initialized and connected - [ ] Git repository initialized and connected
## Template Features Already Configured ## Template Features Already Configured
- ✅ Next.js 15.5.3 with App Router - ✅ Next.js 15.5.3 with App Router
- ✅ React 19.1.0 with latest features - ✅ React 19.1.0 with latest features
- ✅ TypeScript 5 with strict configuration - ✅ TypeScript 5 with strict configuration
@ -274,6 +301,7 @@ git push -u origin main
- ✅ Internationalization setup - ✅ Internationalization setup
## Next Steps After Setup ## Next Steps After Setup
1. Plan your first business domain feature 1. Plan your first business domain feature
2. Implement your chosen database integration (Prisma, TypeORM, Mongoose, etc.) 2. Implement your chosen database integration (Prisma, TypeORM, Mongoose, etc.)
3. Create your first feature following Feature-Based Architecture 3. Create your first feature following Feature-Based Architecture
@ -285,6 +313,7 @@ git push -u origin main
## Database Integration Examples ## Database Integration Examples
### For Prisma (PostgreSQL) ### For Prisma (PostgreSQL)
```bash ```bash
pnpm add prisma @prisma/client pnpm add prisma @prisma/client
pnpm add -D prisma pnpm add -D prisma
@ -292,6 +321,7 @@ npx prisma init
``` ```
### For TypeORM (SQL databases) ### For TypeORM (SQL databases)
```bash ```bash
pnpm add typeorm reflect-metadata pnpm add typeorm reflect-metadata
pnpm add pg # for PostgreSQL pnpm add pg # for PostgreSQL
@ -299,6 +329,7 @@ pnpm add pg # for PostgreSQL
``` ```
### For Mongoose (MongoDB) ### For Mongoose (MongoDB)
```bash ```bash
pnpm add mongoose pnpm add mongoose
pnpm add -D @types/mongoose pnpm add -D @types/mongoose

View File

@ -1,9 +1,11 @@
# Setup Next.js Project # Setup Next.js Project
## Task Overview ## Task Overview
Initialize a new Next.js project with TypeScript, Tailwind CSS, ESLint, and Prettier configuration. Initialize a new Next.js project with TypeScript, Tailwind CSS, ESLint, and Prettier configuration.
## Prerequisites ## Prerequisites
- Node.js 18+ installed - Node.js 18+ installed
- npm or yarn package manager - npm or yarn package manager
- Git for version control - Git for version control
@ -11,19 +13,23 @@ Initialize a new Next.js project with TypeScript, Tailwind CSS, ESLint, and Pret
## Steps ## Steps
### 1. Create Next.js Project ### 1. Create Next.js Project
```bash ```bash
npx create-next-app@latest {project_name} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" npx create-next-app@latest {project_name} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd {project_name} cd {project_name}
``` ```
### 2. Install Additional Dependencies ### 2. Install Additional Dependencies
```bash ```bash
npm install --save-dev prettier prettier-plugin-tailwindcss @types/node npm install --save-dev prettier prettier-plugin-tailwindcss @types/node
npm install lucide-react clsx tailwind-merge npm install lucide-react clsx tailwind-merge
``` ```
### 3. Configure Prettier ### 3. Configure Prettier
Create `.prettierrc.json`: Create `.prettierrc.json`:
```json ```json
{ {
"semi": false, "semi": false,
@ -36,7 +42,9 @@ Create `.prettierrc.json`:
``` ```
### 4. Update ESLint Configuration ### 4. Update ESLint Configuration
Extend `.eslintrc.json`: Extend `.eslintrc.json`:
```json ```json
{ {
"extends": ["next/core-web-vitals", "prettier"], "extends": ["next/core-web-vitals", "prettier"],
@ -48,7 +56,9 @@ Extend `.eslintrc.json`:
``` ```
### 5. Configure TypeScript ### 5. Configure TypeScript
Update `tsconfig.json` for strict mode: Update `tsconfig.json` for strict mode:
```json ```json
{ {
"compilerOptions": { "compilerOptions": {
@ -61,7 +71,9 @@ Update `tsconfig.json` for strict mode:
``` ```
### 6. Set up Scripts ### 6. Set up Scripts
Add to `package.json`: Add to `package.json`:
```json ```json
{ {
"scripts": { "scripts": {
@ -73,6 +85,7 @@ Add to `package.json`:
``` ```
## Validation Checklist ## Validation Checklist
- [ ] Next.js project created with TypeScript - [ ] Next.js project created with TypeScript
- [ ] Tailwind CSS configured and working - [ ] Tailwind CSS configured and working
- [ ] ESLint and Prettier configured - [ ] ESLint and Prettier configured
@ -81,6 +94,7 @@ Add to `package.json`:
- [ ] Project builds without errors - [ ] Project builds without errors
## Next Steps ## Next Steps
- Set up folder structure - Set up folder structure
- Configure environment variables - Configure environment variables
- Create initial components - Create initial components

View File

@ -85,4 +85,12 @@ tasks:
- name: test_suite - name: test_suite
description: Comprehensive test suite for the feature description: Comprehensive test suite for the feature
agents: [domain-architect, nextjs-architect, base-controller-specialist, typescript-specialist, api-developer, tailwind-designer] agents:
[
domain-architect,
nextjs-architect,
base-controller-specialist,
typescript-specialist,
api-developer,
tailwind-designer,
]

View File

@ -53,4 +53,5 @@ tasks:
- name: documentation - name: documentation
description: Feature documentation and usage examples description: Feature documentation and usage examples
agents: [nextjs-architect, typescript-specialist, tailwind-designer, api-developer, testing-engineer] agents:
[nextjs-architect, typescript-specialist, tailwind-designer, api-developer, testing-engineer]