Guía de Desarrollo Completa¶
Proyecto: {{PROJECT_NAME}} · Clase SaMD: {{SAMD_CLASS}} · Versión: v0.1 · Fecha: 2026-01-01
Plantilla del SaMD Starter Kit. Reemplazá los comandos placeholder por los reales de tu stack.
1. Setup del entorno¶
| Requisito | Valor |
|---|---|
| Frontend | {{FRONTEND_STACK}} |
| Backend | {{BACKEND_STACK}} |
| Base de datos | {{DB_STACK}} |
| Cloud | {{CLOUD_STACK}} |
| Gestor de secretos |
# 1. Clonar e instalar dependencias
git clone <repo> && cd {{PROJECT_NAME}}
# Frontend
<comando-instalar-deps-frontend> # ej. npm ci
# Backend (entorno aislado obligatorio)
<crear-entorno-virtual> && <activar> # ej. python -m venv venv && source venv/bin/activate
<comando-instalar-deps-backend> # ej. pip install -r requirements.txt
# 2. Variables de entorno (NUNCA commitear secretos reales)
cp .env.example .env # completar valores locales
# 3. Servicios locales (BD, emuladores, etc.)
<comando-levantar-servicios-locales>
2. Comandos core¶
# Desarrollo
<dev-frontend> # ej. npm run dev
<dev-backend> # ej. uvicorn app.main:app --reload
# Tests
<test-frontend> # ej. npm run test
<test-backend> # ej. pytest
<cobertura> # ej. pytest --cov (umbral según política)
<tipos> # ej. mypy . / tsc --noEmit
# Migraciones
<crear-migracion> # ej. alembic revision --autogenerate
<aplicar-migracion> # ej. alembic upgrade head (MANUAL solo para recuperación)
# CI local pre-push
<ci-local> # ej. bash scripts/run_local_ci.sh
# Stack de calidad SaMD (lentos — correr cuando aplique, piden OK por costo)
<mutation> # mutation testing (frontend/backend)
<sast> # análisis estático de seguridad
<dast> # análisis dinámico
<deps-cve> # escaneo de CVEs en dependencias
3. Estándares de backend¶
- Identidad solo desde token verificado. Nunca aceptar
idde sujeto desde body o query. - Asincronía máxima: prohibido I/O bloqueante; usar primitivas async.
- Tipado estricto: prohibido el tipo dinámico/
any; validación de esquemas en frontera. - Errores empáticos: nunca devolver tracebacks, SQL, metadatos internos o logs técnicos al cliente; solo mensaje claro + código HTTP correcto.
- Cifrado en reposo de campos sensibles; clave gestionada por el gestor de secretos, nunca hardcodeada ni reutilizada.
- Auditoría: persistir mutaciones (POST/PUT/PATCH/DELETE) para trazabilidad; lecturas a logs estructurados.
.env.examplecubre todo el código vivo: variable nueva en config → agregarla con comentario.
4. Estándares de frontend¶
- Offline-first: toda mutación pasa por el almacén local → outbox → sync. Nunca saltearlo.
- Cache/fetch vía la librería de data-fetching estándar del proyecto.
- Accesibilidad WCAG 2.1 AA: etiquetas semánticas + ARIA correctas; contraste verificado; respetar
prefers-reduced-motionincondicionalmente. - Componentes canónicos: reusar el modal/diálogo base; prohibido crear overlays nuevos.
- Mensajes al usuario claros y empáticos, sin jerga técnica; toasts con
idúnico anti-flood.
5. Definition of Done¶
Una tarea está "lista" solo si cumple TODO:
- [ ] Código tipado, sin warnings nuevos respecto al techo del repo.
- [ ] Tests vinculados escritos (con aserciones reales, no de humo) y verdes; números reportados.
- [ ] Análisis de impacto hecho: todos los consumidores del símbolo revisados/actualizados.
- [ ] Fail-safe verificado para los modos de fallo del cambio.
- [ ] Sin tracebacks ni PII/PHI expuestos al cliente ni a logs.
- [ ] Accesibilidad verificada (si tocó UI).
- [ ] Trazabilidad: REQ/Risk +
ruta/archivo.py::símbolo+ nombre de test. - [ ] Documentación actualizada junto con el cambio (Master Map / deuda / RFC según aplique).
- [ ] Boy Scout: al menos un pedazo de deuda del archivo tocado quedó más limpio.
6. Flujo de Pull Request¶
- Rama desde la rama principal; nunca commitear directo a la principal.
- Commits atómicos; mensaje describe el qué y el porqué.
- CI local verde antes de abrir PR.
- PR describe: cambio, impacto, tests corridos (números), trazabilidad, riesgos.
- Revisión: al menos un revisor; cambios clínicos/seguridad requieren revisión adversarial.
- Auditoría del changeset según
AUDIT_PROTOCOL.mdsi toca capa regulada. - Merge tras aprobación; deploy y push a remoto solo con OK explícito del propietario.
7. Versionado de este documento¶
| Versión | Fecha | Autor | Cambio |
|---|---|---|---|
| v0.1 | 2026-01-01 | {{OWNER}} | Plantilla inicial |
Navegación: Índice del DHF · Master Map