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

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Scope is clearly bounded
• 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

• User description parsed
• Key concepts extracted
• Ambiguities marked
• User scenarios defined
• Requirements generated
• Entities identified
• Review checklist passed

---