275 lines
8.9 KiB
Markdown
275 lines
8.9 KiB
Markdown
# Task BE-API-01: API Design Strategy Implementation
|
|
|
|
**Phase:** Backend API Standardization
|
|
**ADR Compliance:** ADR-003 (API Design Strategy), ADR-019 (UUID Strategy)
|
|
**Priority:** 🟡 Important - API Consistency & Developer Experience
|
|
|
|
> **Context:** การ implement Hybrid REST + Action Endpoints ตาม ADR-003 เพื่อให้ API สอดคล้องกันทั่วทั้งระบบ
|
|
|
|
---
|
|
|
|
## 📋 Implementation Tasks
|
|
|
|
### **API-1.1: Base Controller & Patterns**
|
|
- [ ] **Create Base Controller Class:**
|
|
- File: `backend/src/common/controllers/base.controller.ts`
|
|
- Features: Standard CRUD operations, pagination, filtering
|
|
- Methods: `findAll()`, `findOne(uuid)`, `create()`, `update(uuid)`, `remove(uuid)`
|
|
- [ ] **Create Standard Response DTOs:**
|
|
- File: `backend/src/common/dto/response.dto.ts`
|
|
- Types: `ApiResponse<T>`, `PaginatedResponse<T>`, `ActionResponse`
|
|
- Include meta information: timestamp, pagination, version
|
|
- [ ] **Create Action Endpoint Decorator:**
|
|
- File: `backend/src/common/decorators/action-endpoint.decorator.ts`
|
|
- Purpose: Mark business action endpoints for Swagger documentation
|
|
- Usage: `@ActionEndpoint('submit', 'Submit correspondence for routing')`
|
|
|
|
### **API-1.2: Correspondence API Refactor**
|
|
- [ ] **Update Correspondence Controller:**
|
|
- File: `backend/src/modules/correspondence/correspondence.controller.ts`
|
|
- REST endpoints: GET, POST, PUT, PATCH, DELETE `/correspondences`
|
|
- Action endpoints:
|
|
- POST `/correspondences/:uuid/submit`
|
|
- POST `/correspondences/:uuid/approve`
|
|
- POST `/correspondences/:uuid/reject`
|
|
- POST `/correspondences/:uuid/forward`
|
|
- [ ] **Create Action DTOs:**
|
|
- File: `backend/src/modules/correspondence/dto/correspondence-actions.dto.ts`
|
|
- DTOs: `SubmitDto`, `ApproveDto`, `RejectDto`, `ForwardDto`
|
|
- Validation: Business rules for each action
|
|
- [ ] **Update Correspondence Service:**
|
|
- Methods: `submit()`, `approve()`, `reject()`, `forward()`
|
|
- Integration: Workflow engine transitions
|
|
- Error handling: Business exceptions for invalid states
|
|
|
|
### **API-1.3: RFA API Implementation**
|
|
- [ ] **Create RFA Controller:**
|
|
- File: `backend/src/modules/rfa/rfa.controller.ts`
|
|
- REST endpoints: Standard CRUD for RFAs
|
|
- Action endpoints:
|
|
- POST `/rfa/:uuid/submit-for-review`
|
|
- POST `/rfa/:uuid/approve`
|
|
- POST `/rfa/:uuid/request-changes`
|
|
- POST `/rfa/:uuid/final-approve`
|
|
- [ ] **Create RFA Action DTOs:**
|
|
- File: `backend/src/modules/rfa/dto/rfa-actions.dto.ts`
|
|
- DTOs: `SubmitForReviewDto`, `ApproveDto`, `RequestChangesDto`
|
|
- Include: Comments, attachments, change requests
|
|
- [ ] **Update RFA Service:**
|
|
- Workflow integration: Document numbering, state transitions
|
|
- Business logic: Review cycles, approval chains
|
|
- Notifications: Trigger email/LINE notifications
|
|
|
|
### **API-1.4: API Documentation & Testing**
|
|
- [ ] **Update Swagger Configuration:**
|
|
- File: `backend/src/main.ts`
|
|
- Group endpoints by module and type (REST vs Actions)
|
|
- Add examples for all DTOs and responses
|
|
- Configure security: JWT Bearer authentication
|
|
- [ ] **Create API Client Library:**
|
|
- File: `frontend/lib/api/client.ts`
|
|
- Methods: Typed API calls for all endpoints
|
|
- Error handling: Parse structured error responses
|
|
- Type safety: TypeScript interfaces for all DTOs
|
|
- [ ] **Add Integration Tests:**
|
|
- Directory: `backend/test/api/`
|
|
- Coverage: All REST and action endpoints
|
|
- Scenarios: Success cases, error cases, permission tests
|
|
- Tools: Jest, Supertest
|
|
|
|
### **API-1.5: Performance & Optimization**
|
|
- [ ] **Implement Response Caching:**
|
|
- Master data endpoints: Organizations, projects, types
|
|
- Cache keys: `master:${entity}:${projectId}`
|
|
- TTL: 1 hour for master data, 15 minutes for dynamic data
|
|
- [ ] **Add Request Validation:**
|
|
- DTO validation: class-validator decorators
|
|
- Business rule validation: Custom validators
|
|
- Rate limiting: By user role and endpoint type
|
|
- [ ] **Database Query Optimization:**
|
|
- Pagination: Limit/offset with total count
|
|
- Filtering: Dynamic where clauses
|
|
- Relations: Eager loading for common queries
|
|
|
|
---
|
|
|
|
## 🔧 Technical Implementation Details
|
|
|
|
### Base Controller Structure
|
|
|
|
```typescript
|
|
// File: backend/src/common/controllers/base.controller.ts
|
|
export abstract class BaseController<T extends BaseEntity> {
|
|
constructor(
|
|
protected readonly service: BaseService<T>,
|
|
protected readonly entityName: string
|
|
) {}
|
|
|
|
@Get()
|
|
@ApiResponse({ status: 200, description: `List ${entityName}` })
|
|
async findAll(@Query() query: PaginationDto): Promise<PaginatedResponse<T>> {
|
|
return this.service.findAll(query);
|
|
}
|
|
|
|
@Get(':uuid')
|
|
@ApiResponse({ status: 200, description: `Get ${entityName} by UUID` })
|
|
async findOne(@Param('uuid') uuid: string): Promise<ApiResponse<T>> {
|
|
return this.service.findOne(uuid);
|
|
}
|
|
|
|
@Post()
|
|
@ApiResponse({ status: 201, description: `Create ${entityName}` })
|
|
async create(@Body() dto: CreateDto): Promise<ApiResponse<T>> {
|
|
return this.service.create(dto);
|
|
}
|
|
|
|
// ... other standard methods
|
|
}
|
|
```
|
|
|
|
### Action Endpoint Pattern
|
|
|
|
```typescript
|
|
// File: backend/src/modules/correspondence/correspondence.controller.ts
|
|
@Controller('correspondences')
|
|
@ApiTags('Correspondences')
|
|
export class CorrespondenceController extends BaseController<Correspondence> {
|
|
|
|
@Post(':uuid/submit')
|
|
@ActionEndpoint('submit', 'Submit correspondence for routing')
|
|
@ApiResponse({ status: 200, description: 'Correspondence submitted successfully' })
|
|
async submit(
|
|
@Param('uuid') uuid: string,
|
|
@Body() dto: SubmitCorrespondenceDto,
|
|
@CurrentUser() user: User
|
|
): Promise<ActionResponse> {
|
|
return this.correspondenceService.submit(uuid, dto, user.id);
|
|
}
|
|
|
|
@Post(':uuid/approve')
|
|
@ActionEndpoint('approve', 'Approve correspondence')
|
|
async approve(
|
|
@Param('uuid') uuid: string,
|
|
@Body() dto: ApproveCorrespondenceDto,
|
|
@CurrentUser() user: User
|
|
): Promise<ActionResponse> {
|
|
return this.correspondenceService.approve(uuid, dto, user.id);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Frontend API Client
|
|
|
|
```typescript
|
|
// File: frontend/lib/api/correspondence.ts
|
|
export class CorrespondenceApi {
|
|
private client = new ApiClient('/correspondences');
|
|
|
|
// REST operations
|
|
async findAll(query?: CorrespondenceListQuery): Promise<PaginatedCorrespondences> {
|
|
return this.client.get('', { params: query });
|
|
}
|
|
|
|
async findOne(uuid: string): Promise<Correspondence> {
|
|
return this.client.get(`/${uuid}`);
|
|
}
|
|
|
|
async create(dto: CreateCorrespondenceDto): Promise<Correspondence> {
|
|
return this.client.post('', dto);
|
|
}
|
|
|
|
// Action operations
|
|
async submit(uuid: string, dto: SubmitCorrespondenceDto): Promise<ActionResponse> {
|
|
return this.client.post(`/${uuid}/submit`, dto);
|
|
}
|
|
|
|
async approve(uuid: string, dto: ApproveCorrespondenceDto): Promise<ActionResponse> {
|
|
return this.client.post(`/${uuid}/approve`, dto);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Success Criteria
|
|
|
|
### Functional Requirements
|
|
- [ ] All correspondence endpoints follow hybrid pattern
|
|
- [ ] RFA endpoints implemented with actions
|
|
- [ ] Swagger documentation complete with examples
|
|
- [ ] Frontend API client typed and tested
|
|
- [ ] Integration tests cover all scenarios
|
|
|
|
### Non-Functional Requirements
|
|
- [ ] API response times < 200ms (p90)
|
|
- [ ] Error responses consistent and user-friendly
|
|
- [ ] Documentation auto-generated and up-to-date
|
|
- [ ] Type safety across frontend and backend
|
|
- [ ] Rate limiting and security implemented
|
|
|
|
### Compliance Requirements
|
|
- [ ] ADR-003 patterns followed consistently
|
|
- [ ] ADR-019 UUID strategy implemented
|
|
- [ ] ADR-007 error handling integrated
|
|
- [ ] ADR-010 logging for all API calls
|
|
|
|
---
|
|
|
|
## 🚀 Deployment & Rollout
|
|
|
|
### Phase 1: Backend Implementation (Week 1-2)
|
|
- Implement base controller and patterns
|
|
- Refactor correspondence API
|
|
- Create comprehensive tests
|
|
|
|
### Phase 2: Frontend Integration (Week 3)
|
|
- Update API client library
|
|
- Implement error handling UI
|
|
- Add integration tests
|
|
|
|
### Phase 3: Documentation & Monitoring (Week 4)
|
|
- Complete Swagger documentation
|
|
- Add API monitoring
|
|
- Performance testing and optimization
|
|
|
|
---
|
|
|
|
## 📋 Dependencies & Prerequisites
|
|
|
|
### Must Have
|
|
- ✅ ADR-003 Approved
|
|
- ✅ ADR-007 Error Handling Strategy
|
|
- ✅ Base infrastructure (NestJS, TypeORM, Redis)
|
|
- ✅ Authentication system (JWT, CASL)
|
|
|
|
### Nice to Have
|
|
- API analytics dashboard
|
|
- Automated API testing pipeline
|
|
- Client code generation
|
|
|
|
---
|
|
|
|
## 🔄 Review & Acceptance
|
|
|
|
### Code Review Checklist
|
|
- [ ] All endpoints follow hybrid pattern
|
|
- [ ] DTOs properly validated
|
|
- [ ] Error handling consistent
|
|
- [ ] Documentation complete
|
|
- [ ] Tests comprehensive
|
|
- [ ] Performance optimized
|
|
|
|
### Acceptance Criteria
|
|
- [ ] API documentation available at `/api/docs`
|
|
- [ ] All tests passing (>90% coverage)
|
|
- [ ] Performance benchmarks met
|
|
- [ ] Security scan passed
|
|
- [ ] Frontend integration verified
|
|
|
|
---
|
|
|
|
**Owner:** Backend Team Lead
|
|
**Estimated Effort:** 3-4 weeks (1 developer)
|
|
**Risk Level:** Medium (API breaking changes)
|
|
**Rollback Plan:** Version previous API endpoints alongside new ones
|