care-book-block-ultimate/specs/001-wordpress-plugin-para/spec.md

# Feature Specification: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare

**Feature Branch**: `001-wordpress-plugin-para`  
**Created**: 2025-09-10  
**Status**: Draft  
**Input**: User description: "WordPress plugin para controlo seguro de agendamentos KiviCare com abordagem CSS-first e theme-level integration para evitar instabilidade crítica identificada em versões anteriores"

## Execution Flow (main)
```
1. Parse user description from Input
   → Extracted: WordPress plugin, KiviCare integration, CSS-first approach, stability focus
2. Extract key concepts from description
   → Actors: clinic administrators, patients, staff
   → Actions: control appointment visibility, secure integration
   → Data: doctor/service restrictions, appointment forms
   → Constraints: avoid system instability, CSS-first approach
3. For each unclear aspect:
   → Marked with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
   → Primary user journey: administrator configures restrictions
5. Generate Functional Requirements
   → Each requirement focused on safe appointment control
6. Identify Key Entities
   → Doctor restrictions, service restrictions, appointments
7. Run Review Checklist
   → Focus on business value and stability requirements
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")

---

## User Scenarios & Testing *(mandatory)*

### Primary User Story
O plugin KiviCare para WordPress não permite um controlo granular sobre a visibilidade de médicos e serviços no sistema de agendamento público. Este projeto resolve essa limitação, permitindo ocultar seletivamente médicos e/ou serviços específicos do frontend, sem afetar a gestão no painel de administração.

**Utilizadores Finais:**
- **Administradores da Clínica (Utilizadores do Painel WP):** Gestores que configuram a plataforma, definindo quais médicos e serviços devem estar visíveis para agendamento online
- **Pacientes/Clientes (Utilizadores do Site Público):** Pessoas que acedem ao site para marcar consultas e que verão uma lista filtrada de opções

**Valor de Negócio:**
Aumentar a flexibilidade operacional das clínicas que usam KiviCare, permitindo-lhes gerir a sua oferta de serviços online de forma mais estratégica (ex: ocultar médicos sem disponibilidade, oferecer serviços específicos apenas presencialmente). Melhora a experiência do cliente final e otimiza a gestão interna.

### Jornadas de Utilizador Detalhadas

**Jornada do Administrador:**
1. O administrador acede ao painel do WordPress
2. Navega para o novo menu "Care Booking Control"
3. Numa interface simples (com checkboxes), seleciona os médicos que deseja ocultar do agendamento público
4. Expande a configuração de um médico específico e seleciona os serviços desse médico que devem ser ocultados
5. Grava as alterações. O sistema invalida a cache relevante automaticamente
6. O administrador pode, a qualquer momento, reverter estas alterações

**Jornada do Paciente/Cliente:**
1. O paciente acede à página de agendamento do site
2. Interage com o formulário de agendamento do KiviCare
3. As listas de seleção de médicos e serviços já não mostram as opções que o administrador ocultou
4. O paciente consegue completar o seu agendamento apenas com as combinações permitidas

### Acceptance Scenarios
1. **Given** múltiplos médicos no KiviCare, **When** administrador marca médicos específicos como "bloqueados", **Then** esses médicos não aparecem no formulário público mas mantêm-se acessíveis no admin
2. **Given** médico oferece múltiplos serviços, **When** administrador oculta serviços específicos, **Then** apenas serviços visíveis aparecem quando pacientes selecionam esse médico
3. **Given** plugin ativo, **When** KiviCare é atualizado, **Then** sistema de restrições continua funcionando sem instabilidade
4. **Given** alterações nas configurações, **When** paciente visualiza formulário, **Then** alterações refletem-se imediatamente (cache invalidado automaticamente)

### Cenários Extremos e Limitações

**Cenários de Erro:**
- **KiviCare desativado**: Site não deve quebrar; funcionalidade de restrição simplesmente deixa de funcionar
- **Médico/serviço eliminado no KiviCare**: Regras de restrição associadas devem ser limpas ou ignoradas para evitar IDs órfãos
- **Conflitos com plugins de cache**: Cache do site (ex: WP Rocket) deve ser limpa quando restrições são atualizadas
- **Todos os médicos bloqueados para um serviço**: Sistema deve mostrar mensagem apropriada
- **Base de dados corrompida**: Sistema deve ter mecanismo de recovery

**Limitações Técnicas:**
- Restrições dependem da estrutura e hooks do KiviCare; atualizações majoritárias podem quebrar funcionalidade
- Performance pode ser fator em sites com milhares de médicos/serviços, exigindo otimização
- Deve ser desenvolvido como plugin WordPress standard seguindo boas práticas
- Manter compatibilidade com versões mais recentes do WordPress e KiviCare

## Requirements *(mandatory)*

### Functional Requirements

**Core Obrigatórios:**
- **FR-001**: System MUST provide admin panel to activate/deactivate doctor visibility
- **FR-002**: System MUST provide admin panel to activate/deactivate service visibility per doctor
- **FR-003**: Restrictions MUST apply only to frontend (public booking); backend MUST maintain full visibility
- **FR-004**: System MUST integrate transparently with KiviCare hooks to filter doctor and service lists
- **FR-005**: System MUST create database table (`wp_care_booking_restrictions`) to persist rules
- **FR-006**: System MUST use CSS-first approach to avoid shortcode conflicts from previous versions
- **FR-007**: System MUST provide visual confirmation when restriction changes are saved
- **FR-008**: System MUST gracefully handle KiviCare plugin deactivation without breaking website
- **FR-009**: System MUST have <5% performance overhead on appointment page loading
- **FR-010**: System MUST restrict management to WordPress administrators and editors

**Nice-to-Have (Roadmap):**
- **FR-011**: System SHOULD log all restriction changes (who changed what and when)
- **FR-012**: System SHOULD provide Import/Export functionality for restriction configurations
- **FR-013**: System SHOULD show admin notifications about recent changes

**Success Metrics:**
- 100% reduction of bookings for doctors/services that should be hidden
- <2 minutes configuration time for administrators
- 100% adoption by platform administrators in first month
- 0 support tickets for "cannot find doctor X" when intentionally hidden

### Key Entities *(include if feature involves data)*

**wp_care_booking_restrictions Table:**
- **id**: Auto-increment primary key
- **restriction_type**: ENUM('doctor', 'service') - Type of restriction
- **target_id**: INT - ID of doctor or service being restricted
- **doctor_id**: INT - For service restrictions, which doctor it applies to
- **is_blocked**: BOOLEAN - Whether the item is blocked from public view
- **created_at**: TIMESTAMP - When restriction was created
- **updated_at**: TIMESTAMP - When restriction was last modified

**Future Entities (Nice-to-Have):**
- **wp_care_booking_logs**: Audit trail of all changes
- **Scheduling Data**: Start/end dates for temporary restrictions

---

## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*

### Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed

### Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous  
- [x] Success criteria are measurable
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified

### Technical Constraints
- WordPress 5.0+ required
- KiviCare Plugin 3.0.0+ required
- PHP 7.4+ required
- MySQL database access required

---

## Execution Status
*Updated by main() during processing*

- [x] User description parsed
- [x] Key concepts extracted
- [x] Ambiguities marked
- [x] User scenarios defined
- [x] Requirements generated
- [x] Entities identified
- [x] Review checklist passed

---