roi-theme/_planeacion/REORGANIZACION-TEMA.md

# PROPUESTA: REORGANIZACIÓN Y LIMPIEZA DEL TEMA APUS

**Fecha**: 2025-11-04
**Problema**: Archivos .md innecesarios en el tema + mala organización de archivos en raíz

---

## ❌ PROBLEMA 1: ARCHIVOS .MD EN EL TEMA (MALA PRÁCTICA)

### Archivos encontrados que NO deberían estar:

```
wp-content/themes/apus-theme/
├── CHANGELOG.md                        ❌ ELIMINAR
├── CREDITS.md                          ❌ ELIMINAR
├── ISSUE-14-COMPLETION-REPORT.md       ❌ ELIMINAR
├── ISSUE-19-COMPLETION-REPORT.md       ❌ ELIMINAR
├── ISSUES-6-7-COMPLETED.md             ❌ ELIMINAR
├── QUICK-START-OPTIONS-PANEL.md        ❌ ELIMINAR
├── README.md                           ❌ ELIMINAR
├── README-THEME-OPTIONS.md             ❌ ELIMINAR
├── SEO-COMPATIBILITY.md                ❌ ELIMINAR
├── TEMPLATES.md                        ❌ ELIMINAR
└── THEME-OPTIONS-STRUCTURE.txt         ❌ ELIMINAR
```

**Total**: 11 archivos de documentación que deben eliminarse

### ¿Por qué es mala práctica?

1. **La documentación debe estar en GitHub Issues**, no en archivos del tema
2. Aumenta el tamaño del tema innecesariamente
3. Dificulta el mantenimiento (documentación duplicada)
4. No es estándar de WordPress (temas profesionales no incluyen .md)

### ✅ Acción:

**MOVER contenido a issues de GitHub y ELIMINAR archivos**:

| Archivo | Acción |
|---------|--------|
| `CHANGELOG.md` | Documentar en releases de GitHub |
| `CREDITS.md` | Agregar en `style.css` header |
| `ISSUE-14-COMPLETION-REPORT.md` | Ya está en issue #14 (cerrado) → ELIMINAR |
| `ISSUE-19-COMPLETION-REPORT.md` | Ya está en issue #19 (cerrado) → ELIMINAR |
| `ISSUES-6-7-COMPLETED.md` | Ya está en issues #6 y #7 → ELIMINAR |
| `QUICK-START-OPTIONS-PANEL.md` | Agregar en issue #14 (ya cerrado) → ELIMINAR |
| `README.md` | Crear README.md en RAÍZ del repo (no en tema) |
| `README-THEME-OPTIONS.md` | Fusionar con issue #14 → ELIMINAR |
| `SEO-COMPATIBILITY.md` | Fusionar con issue #19 → ELIMINAR |
| `TEMPLATES.md` | Fusionar con issue #9 → ELIMINAR |
| `THEME-OPTIONS-STRUCTURE.txt` | Fusionar con issue #14 → ELIMINAR |

---

## ❌ PROBLEMA 2: DESORGANIZACIÓN EN LA RAÍZ DEL TEMA

### Estructura ACTUAL (desordenada):

```
wp-content/themes/apus-theme/
├── 404.php                    ← Template
├── archive.php                ← Template
├── comments.php               ← Template
├── footer.php                 ← Template part
├── front-page.php             ← Template
├── functions.php              ✓ OK en raíz
├── header.php                 ← Template part
├── index.php                  ✓ OK en raíz (requerido)
├── page.php                   ← Template
├── search.php                 ← Template
├── sidebar.php                ← Template part
├── single.php                 ← Template
├── style.css                  ✓ OK en raíz (requerido)
├── LICENSE                    ✓ OK en raíz
├── .htaccess                  ❓ Verificar si es necesario
├── assets/                    ✓ OK
├── docs/                      ❓ ¿Qué contiene?
├── inc/                       ✓ OK
└── template-parts/            ✓ OK
```

### ✅ Estructura PROPUESTA (organizada):

```
wp-content/themes/apus-theme/
├── functions.php              ✓ REQUERIDO en raíz
├── style.css                  ✓ REQUERIDO en raíz
├── screenshot.png             ✓ REQUERIDO en raíz
├── index.php                  ✓ REQUERIDO en raíz (fallback)
├── LICENSE                    ✓ Opcional en raíz
│
├── templates/                 🆕 NUEVA CARPETA
│   ├── 404.php
│   ├── archive.php
│   ├── front-page.php
│   ├── page.php
│   ├── search.php
│   └── single.php
│
├── template-parts/            ✓ Ya existe
│   ├── header.php             ← MOVER aquí
│   ├── footer.php             ← MOVER aquí
│   ├── sidebar.php            ← MOVER aquí
│   ├── comments.php           ← MOVER aquí
│   ├── content.php
│   ├── content-none.php
│   ├── content-hero.php       🆕 Del template
│   ├── content-toc.php        🆕 Del template
│   ├── content-share.php      🆕 Del template
│   ├── content-cta.php        🆕 Del template
│   └── content-related.php    🆕 Del template
│
├── inc/                       ✓ Ya existe - bien organizado
│   ├── admin/
│   ├── adsense-delay.php
│   ├── category-badge.php
│   ├── critical-css.php
│   ├── customizer-fonts.php
│   ├── enqueue-scripts.php
│   ├── featured-image.php
│   ├── image-optimization.php
│   ├── performance.php
│   ├── related-posts.php
│   ├── sanitize-functions.php
│   ├── schema-markup.php      🆕 Del template
│   ├── seo.php
│   ├── template-functions.php
│   ├── template-tags.php
│   ├── theme-options-helpers.php
│   └── toc.php
│
└── assets/                    ✓ Ya existe - bien organizado
    ├── css/
    ├── js/
    ├── images/
    └── vendor/                🆕 Para Bootstrap local
        └── bootstrap/
```

---

## 🔄 PROBLEMA 3: NOMBRES DE ARCHIVOS INCONSISTENTES

### ❌ Problema: Inconsistencia en ubicación de template parts

**Actual**:
- `header.php` → Está en RAÍZ (debería estar en `template-parts/`)
- `footer.php` → Está en RAÍZ (debería estar en `template-parts/`)
- `sidebar.php` → Está en RAÍZ (debería estar en `template-parts/`)
- `comments.php` → Está en RAÍZ (debería estar en `template-parts/`)

**WordPress permite template parts en raíz**, pero es **mala práctica** por:
1. Desorganización visual
2. Dificulta encontrar archivos
3. No sigue estándares modernos de temas

### ✅ Solución:

**MOVER a `template-parts/`** y actualizar referencias:

```php
// ANTES:
get_header();
get_footer();
get_sidebar();

// DESPUÉS:
get_template_part('template-parts/header');
get_template_part('template-parts/footer');
get_template_part('template-parts/sidebar');
```

**NOTA**: `get_header()` y `get_footer()` buscan por defecto en raíz, pero podemos usar `get_template_part()` para mejor organización.

---

## 📋 PLAN DE ACCIÓN

### Fase 1: Limpiar archivos .md

- [ ] Revisar contenido de cada .md
- [ ] Agregar información relevante a issues de GitHub correspondientes
- [ ] Eliminar los 11 archivos .md del tema
- [ ] Commit: "docs: eliminar archivos .md del tema (mover a GitHub issues)"

### Fase 2: Reorganizar templates

- [ ] Crear carpeta `templates/`
- [ ] Mover `404.php`, `archive.php`, `front-page.php`, `page.php`, `search.php`, `single.php`
- [ ] Actualizar `functions.php` si es necesario para que WordPress reconozca templates
- [ ] Commit: "refactor: reorganizar templates en carpeta templates/"

### Fase 3: Reorganizar template parts

- [ ] Mover `header.php` a `template-parts/header.php`
- [ ] Mover `footer.php` a `template-parts/footer.php`
- [ ] Mover `sidebar.php` a `template-parts/sidebar.php`
- [ ] Mover `comments.php` a `template-parts/comments.php`
- [ ] Actualizar todas las referencias en templates que usen `get_header()`, `get_footer()`, etc.
- [ ] Commit: "refactor: mover template parts a carpeta template-parts/"

### Fase 4: Crear estructura para nuevo template

- [ ] Crear `template-parts/content-hero.php` (vacío, para issue #11)
- [ ] Crear `template-parts/content-toc.php` (vacío, para issue #12)
- [ ] Crear `template-parts/content-share.php` (vacío, para nuevo issue)
- [ ] Crear `template-parts/content-cta.php` (vacío, para nuevo issue)
- [ ] Crear `template-parts/content-related.php` (vacío, para issue #13)
- [ ] Commit: "feat: agregar estructura de template parts para nuevo diseño"

### Fase 5: Preparar assets para Bootstrap local

- [ ] Crear `assets/vendor/bootstrap/`
- [ ] Descargar Bootstrap 5.3.2
- [ ] Colocar en `assets/vendor/bootstrap/css/` y `assets/vendor/bootstrap/js/`
- [ ] Actualizar `inc/enqueue-scripts.php` para cargar local (issue #5)
- [ ] Commit: "feat: agregar Bootstrap 5.3.2 local"

### Fase 6: Testing

- [ ] Verificar que todos los templates siguen funcionando
- [ ] Verificar que header/footer/sidebar siguen cargando
- [ ] Verificar que no hay errores 404 en assets
- [ ] Commit: "test: verificar reorganización completa"

---

## 🎯 BENEFICIOS DE ESTA REORGANIZACIÓN

1. ✅ **Cumple estándares de WordPress** modernos
2. ✅ **Más fácil de mantener** (archivos agrupados por función)
3. ✅ **Elimina redundancia** (documentación solo en GitHub)
4. ✅ **Reduce tamaño del tema** (sin .md innecesarios)
5. ✅ **Prepara estructura** para implementar nuevo template
6. ✅ **Facilita onboarding** de nuevos desarrolladores

---

## ⚠️ CONSIDERACIONES

### ¿Afecta a WordPress?

**NO** - WordPress es flexible con la ubicación de archivos:
- Templates pueden estar en subcarpetas (con ajuste en `functions.php`)
- Template parts pueden estar en cualquier ubicación (usando `get_template_part()`)

### ¿Rompe algo?

**NO** - Siempre que actualicemos las referencias correctamente:
- `get_header()` → `get_template_part('template-parts/header')`
- `get_footer()` → `get_template_part('template-parts/footer')`
- O configurar custom locations en `functions.php`

### ¿Es reversible?

**SÍ** - Todo está en Git, podemos revertir si hay problemas.

---

## 📌 ISSUE DE GITHUB SUGERIDO

**Título**: Reorganizar estructura de archivos del tema y eliminar documentación .md

**Labels**: `enhancement`, `refactoring`, `cleanup`, `priority-medium`

**Milestone**: Sprint 2025-12

**Estimación**: 2-3 horas

---

## ✅ CRITERIO DE DONE

- [ ] Todos los archivos .md eliminados del tema
- [ ] Contenido relevante de .md migrado a issues de GitHub
- [ ] Templates organizados en carpeta `templates/`
- [ ] Template parts organizados en carpeta `template-parts/`
- [ ] Bootstrap 5.3.2 descargado y en `assets/vendor/bootstrap/`
- [ ] Todas las referencias actualizadas
- [ ] Testing completo sin errores
- [ ] Commits con mensajes descriptivos
- [ ] Documentación en issue de GitHub actualizada