care-api/specs/001-care-api-sistema/tasks.md

Tasks: Care API - Sistema de gestão de cuidados de saúde

Input: Design documents from /specs/001-care-api-sistema/ Prerequisites: plan.md (required), research.md, data-model.md, contracts/

Execution Flow (main)

1. Load plan.md from feature directory
   → Tech stack: PHP 8.1+, WordPress 6.0+, KiviCare plugin, JWT, PHPUnit
   → Structure: Single WordPress plugin project
2. Load design documents:
   → data-model.md: 8 entities (Clinic, Patient, Doctor, Appointment, Encounter, Prescription, Bill, Service)
   → contracts/openapi.yaml: 6 endpoint groups, JWT authentication
   → quickstart.md: 5 user story validation scenarios
3. Generate tasks by category (62 total tasks)
4. Apply TDD ordering: Tests before implementation
5. Mark [P] for parallel execution (different files)
6. SUCCESS: All contracts, entities, and user stories covered

Format: [ID] [P?] Description

• [P]: Can run in parallel (different files, no dependencies)
• File paths relative to repository root

Path Conventions

Single WordPress plugin project structure:

• Plugin files: src/ directory
• Tests: tests/ directory
• WordPress integration: Standard plugin activation/hooks

Phase 3.1: Setup & WordPress Plugin Foundation

• T001 Create WordPress plugin directory structure at src/ with standard plugin headers and main file
• T002 Initialize composer.json with PHPUnit, WordPress testing framework, and JWT authentication dependencies
• T003 [P] Configure PHPUnit with WordPress testing framework in phpunit.xml
• T004 [P] Set up WordPress coding standards (WPCS) and linting configuration
• T005 Create plugin activation/deactivation hooks in src/kivicare-api.php with KiviCare dependency check
• T006 Register REST API namespace '/wp-json/kivicare/v1' in src/class-api-init.php

Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3

CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation

Contract Tests (API Endpoints)

• T007 [P] Contract test POST /wp-json/kivicare/v1/auth/login in tests/contract/test-auth-endpoints.php
• T008 [P] Contract test GET /wp-json/kivicare/v1/clinics in tests/contract/test-clinic-endpoints.php
• T009 [P] Contract test POST /wp-json/kivicare/v1/clinics in tests/contract/test-clinic-endpoints.php
• T010 [P] Contract test GET /wp-json/kivicare/v1/patients in tests/contract/test-patient-endpoints.php
• T011 [P] Contract test POST /wp-json/kivicare/v1/patients in tests/contract/test-patient-endpoints.php
• T012 [P] Contract test GET /wp-json/kivicare/v1/appointments in tests/contract/test-appointment-endpoints.php
• T013 [P] Contract test POST /wp-json/kivicare/v1/appointments in tests/contract/test-appointment-endpoints.php
• T014 [P] Contract test GET /wp-json/kivicare/v1/encounters in tests/contract/test-encounter-endpoints.php
• T015 [P] Contract test POST /wp-json/kivicare/v1/encounters in tests/contract/test-encounter-endpoints.php
• T016 [P] Contract test POST /wp-json/kivicare/v1/encounters/{id}/prescriptions in tests/contract/test-prescription-endpoints.php

Integration Tests (User Stories)

• T017 [P] Integration test doctor creates patient record in tests/integration/test-patient-creation-workflow.php
• T018 [P] Integration test doctor creates encounter with prescriptions in tests/integration/test-encounter-workflow.php
• T019 [P] Integration test multi-doctor clinic data access in tests/integration/test-clinic-data-access.php
• T020 [P] Integration test automatic billing generation in tests/integration/test-billing-automation.php
• T021 [P] Integration test role-based access control in tests/integration/test-role-permissions.php

Phase 3.3: Core Implementation (ONLY after tests are failing)

Entity Models

• T022 [P] Clinic model class in src/models/class-clinic.php with validation rules
• T023 [P] Patient model class in src/models/class-patient.php with wp_users integration
• T024 [P] Doctor model class in src/models/class-doctor.php with clinic mappings
• T025 [P] Appointment model class in src/models/class-appointment.php with scheduling logic
• T026 [P] Encounter model class in src/models/class-encounter.php with appointment linkage
• T027 [P] Prescription model class in src/models/class-prescription.php with encounter linkage
• T028 [P] Bill model class in src/models/class-bill.php with payment tracking
• T029 [P] Service model class in src/models/class-service.php with pricing data

Authentication & Authorization Service

• T030 JWT authentication service in src/services/class-jwt-auth.php
• T031 Role-based permission service in src/services/class-role-permissions.php
• T032 User session management in src/services/class-session-manager.php

Database Services

• T033 [P] Clinic database service in src/services/class-clinic-service.php
• T034 [P] Patient database service in src/services/class-patient-service.php
• T035 [P] Doctor database service in src/services/class-doctor-service.php
• T036 [P] Appointment database service in src/services/class-appointment-service.php
• T037 [P] Encounter database service in src/services/class-encounter-service.php
• T038 [P] Prescription database service in src/services/class-prescription-service.php
• T039 [P] Bill database service in src/services/class-bill-service.php

REST API Endpoints

• T040 Authentication endpoints in src/endpoints/class-auth-endpoints.php
• T041 Clinic CRUD endpoints in src/endpoints/class-clinic-endpoints.php
• T042 Patient CRUD endpoints in src/endpoints/class-patient-endpoints.php
• T043 Appointment CRUD endpoints in src/endpoints/class-appointment-endpoints.php
• T044 Encounter CRUD endpoints in src/endpoints/class-encounter-endpoints.php
• T045 Prescription endpoints in src/endpoints/class-prescription-endpoints.php

Validation & Error Handling

• T046 Input validation service in src/utils/class-input-validator.php
• T047 Error response formatter in src/utils/class-error-handler.php
• T048 Request/response logging in src/utils/class-api-logger.php

Phase 3.4: Integration & Middleware

• T049 Connect all database services to WordPress $wpdb with prepared statements
• T050 Implement JWT middleware for all protected endpoints
• T051 Add clinic isolation middleware for multi-clinic data security
• T052 WordPress user role integration with KiviCare roles
• T053 Add structured error responses with proper HTTP status codes
• T054 Implement request/response logging with WordPress debug.log integration

Phase 3.5: Caching & Performance

• T055 WordPress Object Cache implementation for patient encounters in src/services/class-cache-manager.php
• T056 Cache invalidation on data updates for appointment schedules
• T057 Database query optimization with proper indexes
• T058 API response time monitoring and performance logging

Phase 3.6: Polish & Documentation

• T059 [P] Unit tests for all validation rules in tests/unit/test-input-validation.php
• T060 [P] Unit tests for model classes in tests/unit/test-models.php
• T061 [P] Performance tests ensuring <500ms response times in tests/performance/test-api-performance.php
• T062 Execute quickstart.md validation scenarios and fix any issues

Dependencies

Setup Phase (T001-T006):

• T001 blocks all other tasks (plugin structure required)
• T002-T006 can run in parallel after T001

Tests Phase (T007-T021):

• Must complete before any implementation (TDD requirement)
• All contract tests (T007-T016) can run in parallel
• All integration tests (T017-T021) can run in parallel

Core Implementation (T022-T048):

• T022-T029 (models) can run in parallel after tests
• T030-T032 (auth) sequential (shared authentication state)
• T033-T039 (services) can run in parallel, depend on models
• T040-T045 (endpoints) sequential (shared REST namespace registration)
• T046-T048 (utils) can run in parallel

Integration Phase (T049-T054):

• T049 blocks T050-T054 (database connection required)
• T050-T054 can run in parallel after T049

Performance & Polish (T055-T062):

• T055-T058 can run in parallel
• T059-T061 can run in parallel (different test files)
• T062 must be last (validation requires complete system)

Parallel Example

# Launch contract tests together (Phase 3.2):
Task: "Contract test POST /wp-json/kivicare/v1/auth/login in tests/contract/test-auth-endpoints.php"
Task: "Contract test GET /wp-json/kivicare/v1/clinics in tests/contract/test-clinic-endpoints.php" 
Task: "Contract test GET /wp-json/kivicare/v1/patients in tests/contract/test-patient-endpoints.php"
Task: "Contract test GET /wp-json/kivicare/v1/appointments in tests/contract/test-appointment-endpoints.php"

# Launch model creation together (Phase 3.3):
Task: "Clinic model class in src/models/class-clinic.php with validation rules"
Task: "Patient model class in src/models/class-patient.php with wp_users integration"
Task: "Doctor model class in src/models/class-doctor.php with clinic mappings"
Task: "Appointment model class in src/models/class-appointment.php with scheduling logic"

WordPress-Specific Notes

• Follow WordPress coding standards (WPCS) for all PHP code
• Use WordPress hooks and filters for extensibility
• Implement proper capability checks for each endpoint
• Use WordPress nonce verification where appropriate
• Ensure compatibility with WordPress multisite installations
• All database operations must use prepared statements via $wpdb
• Plugin must gracefully handle KiviCare plugin deactivation

Validation Checklist

• All 6 endpoint groups have contract tests (T007-T016)
• All 8 entities have model tasks (T022-T029)
• All 5 user stories have integration tests (T017-T021)
• Tests come before implementation (Phase 3.2 → 3.3)
• Parallel tasks are truly independent (different files)
• Each task specifies exact file path
• WordPress plugin structure properly planned
• KiviCare database schema integration covered
• JWT authentication and role-based permissions included
• Performance and caching requirements addressed

WordPress Development Commands

# Plugin development
wp plugin activate kivicare-api
wp plugin deactivate kivicare-api

# Testing
vendor/bin/phpunit tests/
wp db query "SELECT * FROM wp_kc_clinics LIMIT 5"

# Debugging
wp config set WP_DEBUG true
wp config set WP_DEBUG_LOG true
tail -f wp-content/debug.log

---

Task Generation Complete: 62 tasks ready for WordPress TDD implementation