Manual del técnico (producto)

Manual operativo para el equipo técnico (producto, devs senior) en EMA Vault. Tu rol enfoca producto module, infra, audit, wiki.

Tu día típico

Tu vista al loguearte:

1. Producto — los 11+ productos EMA con KPIs.
2. Issues GitHub — sync horario + webhook real-time.
3. Infra — inventory de Workers, dominios, secrets.
4. Notifications — releases pendientes, infra alerts.

Producto module

Vista cross-product

1. Producto → selector con todos los productos EMA.
2. Sub-pages cross:
   • Cross issues: issues GitHub abiertos en todos los repos.
   • Cross recent: actividad reciente cross-product.
3. Click en un producto → ver dashboard del producto.

Sub-pages por producto

Cuando entras a /producto/:slug/*:

Sub-page	Para qué
Dashboard	KPIs producto, releases recientes, issues open
Issues	GitHub issues sync (cache local)
Backlog	Features pendientes, agrupadas por module
Journeys	User journeys editables (steps, outcomes)
Modulos	Estructura del producto: layers → modules → features
Tech	Tech stack (6 categorías) + architecture_md
Releases	Versiones publicadas con changelog_md
Roadmap	Capas con target_dates editables inline

Crear release

1. Producto → <slug> → Releases → + Nueva release.
2. Llenar:
   • Version (semver: 0.3.0).
   • Title.
   • Changelog markdown (renderizado via simpleMarkdown).
   • Released_at.
3. Asociar features cerradas + issues GitHub.
4. Click Publish → release visible en docs públicos.
5. Audit_trigger registra la creación.

Roadmap editable

1. Producto → <slug> → Roadmap.
2. Ver layers (frontend, backend, db, integrations, etc.) con target_date + status + estimated_sessions.
3. Click inline para editar campos.
4. Save → audit log.

Tech stack

1. Producto → <slug> → Tech.
2. Ver tech stack en 6 categorías:
   • language, framework, database, infra, library, tool.
3. Editar + agregar items.
4. Editar architecture_md (renderizado markdown).

GitHub sync

Webhook real-time

Cuando alguien cierra un issue en GitHub:

1. GitHub envía webhook a /api/github/webhook.
2. Sistema verifica HMAC sig.
3. UPDATE github_issues_cache.
4. Match con product_features.linked_issues → auto-close feature.

Cron horario

Cron 0 * * * *:

1. Paginated fetch GitHub REST API issues.
2. UPSERT a github_issues_cache.
3. Enrich from labels (module:, layer:, priority:).

Si el cron falla, ver Worker logs.

Infra

Infraestructura:

• Workers: lista de CF Workers deployados.
• Domains: dominios en CF + DNS.
• Secrets: inventario de secrets per-Worker (sin valores).
• Status: health checks per-Worker.

Agregar Worker nuevo

1. Infra → Workers → + Nuevo.
2. Llenar:
   • Name (igual a wrangler.toml).
   • URL.
   • Repo.
   • Owner (technical/admin).
3. Sistema empieza health check periódico.

Audit log (read)

Tu rol technical puede leer audit log (no admin only):

1. Audit log → filters.
2. Útil para:
   • Diagnostico bugs (“¿qué cambió antes del incidente?”).
   • Verificar deploys (audit_trigger registra cambios releases).
   • Tracking provisioning (¿quién provisionó qué tenant cuándo?).

Wiki

Wiki:

• Docs internos EMA (procedimientos, runbooks, decisions).
• CRUD para technical/admin.
• Markdown rendering.

Convención de páginas

• Runbooks: RUNBOOK_<topic>.md (ej: incident response).
• Decisions: cross-product (lo que NO está en docs/decisions.md por repo).
• Onboarding: para nuevos staff.

Documentos

Documentos:

• Repository ops (contratos, propuestas, decks, brand assets).
• File upload + tags.
• Compartir cross-team.

Análisis

Análisis:

• Reportes ad-hoc sobre data del Vault.
• Custom queries (admin/technical pueden ejecutar).
• Útil para responder “¿cuántos clientes activos hay con producto X?”.

Quality module

Quality dashboard:

• 3 tablas: product_quality, product_security, product_metrics.
• 10 endpoints con KPIs.
• Pages: ProductQuality + ProductSecurity per-producto.

Lo que NO puedes hacer

Tu rol es technical. NO tienes acceso a:

• Provisioning de tenants (admin only).
• Equipo Vault / users (admin).
• Settings system (admin).
• Cancelar contratos (commercial/finance).
• Anular documentos fiscales (es de finance).
• EMI access admin (admin only — pero lees analytics).

Atajos útiles

Atajo	Acción
g luego p	Producto
g luego i	Infra
g luego a	Audit
g luego w	Wiki

Buenas prácticas

• Releases con changelog útil — los developers que vienen después agradecerán el contexto.
• Tech stack actualizado — versiones reales del repo, no hipotéticas.
• Roadmap honesto — target_dates realistas, no marketing.
• GitHub sync verificado — chequear que cron + webhook funcionan.
• Wiki es source of truth para procesos internos no en repos.
• Audit log es tu amigo — antes de blame, query.
• Quality module mensual — review KPIs producto + plan acción.