4a7b232f68
- Added GitHub spec-kit for development workflow - Standardized file signatures to Descomplicar® format - Updated development configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
133 lines
8.3 KiB
Markdown
133 lines
8.3 KiB
Markdown
# Feature Specification: Care API - Sistema de gestão de cuidados de saúde
|
|
|
|
**Feature Branch**: `001-care-api-sistema`
|
|
**Created**: 2025-09-12
|
|
**Status**: Draft
|
|
**Input**: User description: "Care API - Sistema de gestão de cuidados de saúde"
|
|
|
|
## Execution Flow (main)
|
|
```
|
|
1. Parse user description from Input
|
|
→ If empty: ERROR "No feature description provided"
|
|
2. Extract key concepts from description
|
|
→ Identify: actors, actions, data, constraints
|
|
3. For each unclear aspect:
|
|
→ Mark with [NEEDS CLARIFICATION: specific question]
|
|
4. Fill User Scenarios & Testing section
|
|
→ If no clear user flow: ERROR "Cannot determine user scenarios"
|
|
5. Generate Functional Requirements
|
|
→ Each requirement must be testable
|
|
→ Mark ambiguous requirements
|
|
6. Identify Key Entities (if data involved)
|
|
7. Run Review Checklist
|
|
→ If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
|
|
→ If implementation details found: ERROR "Remove tech details"
|
|
8. Return: SUCCESS (spec ready for planning)
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ Quick Guidelines
|
|
- ✅ Focus on WHAT users need and WHY
|
|
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
|
|
- 👥 Written for business stakeholders, not developers
|
|
|
|
### Section Requirements
|
|
- **Mandatory sections**: Must be completed for every feature
|
|
- **Optional sections**: Include only when relevant to the feature
|
|
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
|
|
|
|
### For AI Generation
|
|
When creating this spec from a user prompt:
|
|
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
|
|
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
|
|
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
|
|
4. **Common underspecified areas**:
|
|
- User types and permissions
|
|
- Data retention/deletion policies
|
|
- Performance targets and scale
|
|
- Error handling behaviors
|
|
- Integration requirements
|
|
- Security/compliance needs
|
|
|
|
---
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### Primary User Story
|
|
Healthcare professionals using KiviCare (WordPress-based clinic management system) need to access and manage comprehensive patient care data through a robust REST API. This includes managing clinic operations, patient records, appointment scheduling, medical encounters, prescriptions, and billing - all while maintaining data integrity across the existing 35-table database structure.
|
|
|
|
### Acceptance Scenarios
|
|
1. **Given** a doctor is authenticated via JWT token, **When** they create a new patient via `/wp-json/kivicare/v1/patients`, **Then** the system creates entries in wp_users and wp_kc_patient_clinic_mappings tables and returns the patient ID
|
|
2. **Given** a patient has an appointment, **When** a doctor creates an encounter via `/wp-json/kivicare/v1/encounters`, **Then** the system links it to wp_kc_patient_encounters and allows prescription creation
|
|
3. **Given** multiple doctors from the same clinic, **When** one doctor updates a patient's medical history, **Then** other doctors with clinic access can retrieve the updated data via the patients endpoint
|
|
4. **Given** an encounter is completed, **When** the doctor finalizes the visit, **Then** the system automatically generates billing data in wp_kc_bills with proper encounter linkage
|
|
5. **Given** a receptionist role user, **When** they access appointment endpoints, **Then** they can manage appointments but cannot access sensitive medical data per role-based permissions
|
|
|
|
### Edge Cases
|
|
- What happens when WordPress database connection fails during API calls?
|
|
- How does system handle concurrent updates to the same appointment or encounter record?
|
|
- What occurs when patient data needs to be exported or transferred between different clinic systems?
|
|
- How does the API respond when KiviCare base plugin is deactivated?
|
|
- What happens when JWT tokens expire during long-running operations?
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
- **FR-001**: System MUST provide REST API endpoints for all core KiviCare operations (clinics, patients, doctors, appointments, encounters, billing)
|
|
- **FR-002**: System MUST authenticate users via JWT tokens based on WordPress wp_users table with role-based access control
|
|
- **FR-003**: System MUST maintain data integrity across existing KiviCare database schema (35 tables) without breaking existing WordPress plugin functionality
|
|
- **FR-004**: System MUST support four user roles: administrator (all operations), doctor (patient care, encounters), patient (own data, appointments), receptionist (appointments, basic patient data)
|
|
- **FR-005**: System MUST provide CRUD operations for clinics (wp_kc_clinics), patients (wp_users + mappings), and appointments (wp_kc_appointments)
|
|
- **FR-006**: System MUST enable doctors to create patient encounters (wp_kc_patient_encounters) linked to appointments with prescription management
|
|
- **FR-007**: System MUST generate billing records (wp_kc_bills) automatically from completed encounters with payment tracking
|
|
- **FR-008**: System MUST provide reporting endpoints for appointments, revenue, patients, and doctor statistics
|
|
- **FR-009**: System MUST implement proper error handling with standardized HTTP status codes and JSON error responses
|
|
- **FR-010**: System MUST include caching mechanisms for frequently accessed data (patient encounters, appointment schedules) with configurable TTL
|
|
- **FR-011**: System MUST verify KiviCare base plugin dependency and fail gracefully if not available
|
|
- **FR-012**: System MUST support clinic-specific data isolation ensuring users only access data from their authorized clinics
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
- **Clinic**: Healthcare facility (wp_kc_clinics) with admin, contact details, specialties, and operational settings
|
|
- **Patient**: Individual receiving care (wp_users + wp_kc_patient_clinic_mappings) with demographics, medical history, and clinic associations
|
|
- **Doctor**: Healthcare provider (wp_users + wp_kc_doctor_clinic_mappings) with specialties, schedules, and clinic permissions
|
|
- **Appointment**: Scheduled healthcare visit (wp_kc_appointments) linking patient, doctor, clinic with time slots and service mappings
|
|
- **Encounter**: Actual medical consultation (wp_kc_patient_encounters) documenting diagnosis, treatment, and prescriptions
|
|
- **Prescription**: Medication orders (wp_kc_prescription) linked to encounters with dosage, frequency, and instructions
|
|
- **Bill**: Financial record (wp_kc_bills) for services rendered with payment tracking and encounter linkage
|
|
- **Service**: Medical services offered (wp_kc_services) with pricing and availability for appointment booking
|
|
|
|
---
|
|
|
|
## Review & Acceptance Checklist
|
|
*GATE: Automated checks run during main() execution*
|
|
|
|
### Content Quality
|
|
- [x] No implementation details (languages, frameworks, APIs) - Business requirements focus maintained
|
|
- [x] Focused on user value and business needs - Healthcare professional workflow centered
|
|
- [x] Written for non-technical stakeholders - Clear business language used
|
|
- [x] All mandatory sections completed - User scenarios, requirements, entities defined
|
|
|
|
### Requirement Completeness
|
|
- [x] No [NEEDS CLARIFICATION] markers remain - All ambiguities resolved with KiviCare specifications
|
|
- [x] Requirements are testable and unambiguous - Specific API endpoints and data models defined
|
|
- [x] Success criteria are measurable - Clear CRUD operations and role-based access defined
|
|
- [x] Scope is clearly bounded - WordPress plugin API for existing KiviCare system
|
|
- [x] Dependencies and assumptions identified - KiviCare base plugin dependency specified
|
|
|
|
---
|
|
|
|
## Execution Status
|
|
*Updated by main() during processing*
|
|
|
|
- [x] User description parsed - KiviCare healthcare management system requirements identified
|
|
- [x] Key concepts extracted - WordPress plugin, REST API, healthcare workflows, role-based access
|
|
- [x] Ambiguities marked and resolved - Technical specifications provided for all unclear aspects
|
|
- [x] User scenarios defined - Healthcare professional workflows with specific API endpoints
|
|
- [x] Requirements generated - 12 functional requirements covering all core system capabilities
|
|
- [x] Entities identified - 8 key data entities mapped to KiviCare database schema
|
|
- [x] Review checklist passed - All quality and completeness criteria met
|
|
|
|
**SUCCESS**: Specification ready for planning phase
|
|
|
|
--- |