chore: add spec-kit and standardize signatures
- 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>
This commit is contained in:
Emanuel Almeida
172
specs/001-wordpress-plugin-para/spec.md
Normal file
172
specs/001-wordpress-plugin-para/spec.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user