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

# Implementation Plan: Care API - Sistema de gestão de cuidados de saúde

**Branch**: `001-care-api-sistema` | **Date**: 2025-09-12 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-care-api-sistema/spec.md`

## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
4. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
6. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
8. STOP - Ready for /tasks command
```

**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)

## Summary
Develop a comprehensive REST API for KiviCare WordPress plugin to enable healthcare professionals to manage clinic operations, patient records, appointments, medical encounters, prescriptions, and billing through API endpoints. The implementation must maintain data integrity across the existing 35-table KiviCare database schema while providing role-based access control for administrators, doctors, patients, and receptionists.

## Technical Context
**Language/Version**: PHP 8.1+ (WordPress compatibility)
**Primary Dependencies**: WordPress 6.0+, KiviCare plugin, JWT authentication library
**Storage**: MySQL (existing KiviCare 35-table schema)
**Testing**: PHPUnit, WP-CLI testing framework
**Target Platform**: WordPress hosting environments (Linux/Apache/Nginx)
**Project Type**: single (WordPress plugin extension)
**Performance Goals**: <500ms API response time, support 100 concurrent users
**Constraints**: WordPress hosting compatibility, preserve existing KiviCare data integrity, GDPR compliance
**Scale/Scope**: Multi-clinic healthcare management, 1000+ patients per clinic, full medical workflow coverage

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

**Simplicity**:
- Projects: 1 (WordPress plugin only)
- Using framework directly? (Yes - WordPress REST API directly)
- Single data model? (Yes - direct KiviCare entities without DTOs)
- Avoiding patterns? (Yes - no Repository pattern, direct WordPress database access)

**Architecture**:
- EVERY feature as library? (Yes - endpoint libraries, model libraries, auth library)
- Libraries listed: endpoint handlers (API routes), data models (KiviCare entities), auth service (JWT/role management)
- CLI per library: WP-CLI commands for testing/debugging endpoints
- Library docs: Yes, llms.txt format for API documentation

**Testing (NON-NEGOTIABLE)**:
- RED-GREEN-Refactor cycle enforced? (Yes - PHPUnit tests fail first)
- Git commits show tests before implementation? (Yes - test commits before feature commits)
- Order: Contract→Integration→E2E→Unit strictly followed? (Yes - API contract tests first)
- Real dependencies used? (Yes - actual WordPress/MySQL database)
- Integration tests for: API endpoints, database operations, authentication flows
- FORBIDDEN: Implementation before test, skipping RED phase (Acknowledged)

**Observability**:
- Structured logging included? (Yes - WordPress debug.log with structured format)
- Frontend logs → backend? (N/A - pure API, no frontend)
- Error context sufficient? (Yes - HTTP status codes with detailed JSON error responses)

**Versioning**:
- Version number assigned? (1.0.0 - WordPress plugin versioning)
- BUILD increments on every change? (Yes - WordPress plugin version updates)
- Breaking changes handled? (Yes - API versioning via /v1/ namespace, backward compatibility)

## Project Structure

### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
```

### Source Code (repository root)
```
# Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

# Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

# Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]

ios/ or android/
└── [platform-specific structure]
```

**Structure Decision**: Option 1 (Single WordPress plugin project structure)

## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
   - For each NEEDS CLARIFICATION → research task
   - For each dependency → best practices task
   - For each integration → patterns task

2. **Generate and dispatch research agents**:
   ```
   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   ```

3. **Consolidate findings** in `research.md` using format:
   - Decision: [what was chosen]
   - Rationale: [why chosen]
   - Alternatives considered: [what else evaluated]

**Output**: research.md with all NEEDS CLARIFICATION resolved

## Phase 1: Design & Contracts
*Prerequisites: research.md complete*

1. **Extract entities from feature spec** → `data-model.md`:
   - Entity name, fields, relationships
   - Validation rules from requirements
   - State transitions if applicable

2. **Generate API contracts** from functional requirements:
   - For each user action → endpoint
   - Use standard REST/GraphQL patterns
   - Output OpenAPI/GraphQL schema to `/contracts/`

3. **Generate contract tests** from contracts:
   - One test file per endpoint
   - Assert request/response schemas
   - Tests must fail (no implementation yet)

4. **Extract test scenarios** from user stories:
   - Each story → integration test scenario
   - Quickstart test = story validation steps

5. **Update agent file incrementally** (O(1) operation):
   - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
   - If exists: Add only NEW tech from current plan
   - Preserve manual additions between markers
   - Update recent changes (keep last 3)
   - Keep under 150 lines for token efficiency
   - Output to repository root

**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file

## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*

**Task Generation Strategy**:
- Load `/templates/tasks-template.md` as base
- Generate tasks from OpenAPI contracts (8 main endpoints)
- Generate tasks from data model (8 entities with validation)
- Generate tasks from quickstart validation scenarios (5 user stories)
- Each API endpoint → contract test task [P]
- Each entity model → model creation + unit test tasks [P] 
- Each user story → integration test scenario
- Authentication/authorization → JWT service implementation tasks
- WordPress plugin structure → activation/setup tasks

**Ordering Strategy**:
- TDD order: Contract tests → Integration tests → Unit tests → Implementation
- Dependency order: Plugin setup → Models → Auth service → Endpoints → Integration
- WordPress-specific: Database setup → User roles → REST endpoints → Testing
- Mark [P] for parallel execution (independent endpoint files)

**Specific Task Categories**:
1. **Setup Tasks** (1-5): Plugin structure, WordPress integration, database setup
2. **Contract Test Tasks** (6-15): API endpoint contract tests (must fail initially)
3. **Model Tasks** (16-25): Entity classes with validation, database operations
4. **Authentication Tasks** (26-30): JWT service, role-based permissions  
5. **Endpoint Implementation Tasks** (31-45): REST API endpoint handlers
6. **Integration Test Tasks** (46-55): End-to-end user story validation
7. **Performance/Error Handling** (56-60): Caching, logging, error responses

**Estimated Output**: 55-60 numbered, ordered tasks in tasks.md following WordPress TDD practices

**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan

## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*

**Phase 3**: Task execution (/tasks command creates tasks.md)  
**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)

## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*

No constitutional violations identified. All complexity is justified:
- Single WordPress plugin project (within 3-project limit)
- Direct framework usage (WordPress REST API, no wrappers)
- No unnecessary patterns (direct database access via $wpdb)
- TDD enforced with contract tests before implementation
- Libraries properly structured (models, services, endpoints)
- Structured logging and versioning planned


## Progress Tracking
*This checklist is updated during execution flow*

**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed

**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [x] Complexity deviations documented (none found)

---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*