SDD
Powered by

AGENTS.md — CocinaME

Resumen del proyecto

CocinaME es una plataforma móvil de intermediación de comida casera basada en geolocalización: los Consumidores publican Solicitudes y los Emprendedores cercanos responden con Ofertas. Incluye advertencias de alérgenos, adjudicación de Pedidos basada en créditos y coordinación en tiempo real.

Estructura del repositorio

  • academic/si525-assignments/: tesis, SRS, casos de uso, UML y roadmap de V1. Es un submódulo de Git (rama dev). No se edita a la ligera desde este repositorio: los cambios se hacen en el propio submódulo y luego se actualiza el puntero.

  • .specify/: configuración, plantillas y scripts de Spec Kit, y memory/constitution.md.

  • specs/: una carpeta por funcionalidad (index.yml, spec.md, plan.md, tasks.md y artefactos auxiliares cuando correspondan). specs/README.md registra el estado del producto.

  • docs/: documentación técnica del proyecto, por ejemplo COLOR_THEME.md.

  • mobile/ (futuro): cliente Flutter para Android e iOS.

  • backend/ (futuro): API en Spring Boot.

  • supabase/ (futuro): configuración de Supabase y migraciones SQL versionadas.

Stack técnico

Flutter (móvil) · Spring Boot (backend) · PostgreSQL/PostGIS en Supabase · Supabase Auth · Supabase Storage (imágenes) · Supabase Realtime (solo donde se requieran eventos en tiempo real) · Google Maps Platform (mapas, geocodificación, lugares) · LiteRT (inferencia en el dispositivo) · Gemini API (multimodal remoto, invocado desde el backend) · Firebase Cloud Messaging (notificaciones donde se requieran).

Reglas de arquitectura

  • Flutter no tiene autoridad sobre las reglas críticas de negocio.
  • Spring Boot es responsable de la lógica de negocio, la autorización y las operaciones transaccionales.
  • Flutter nunca escribe directamente en tablas críticas de negocio.
  • Gemini se invoca solo a través de Spring Boot, nunca desde Flutter.
  • LiteRT se ejecuta localmente en el cliente móvil.
  • Los servicios gestionados por Supabase (Auth, Storage, Realtime) son infraestructura, no entidades de dominio.
  • Todo cambio en la base de datos se hace mediante migraciones versionadas.

Autoridad de las fuentes académicas

Las rutas son relativas a academic/si525-assignments/degree-project/.

  • Los Typst del capítulo IV (chapters/ch-4-segments/) contienen requisitos y restricciones.
  • Los casos de uso Typst del capítulo V (chapters/ch-5-segments/use-cases/) contienen comportamiento y flujos.
  • Los PlantUML (assets/uml/puml/) contienen las interacciones y el diseño UML vigentes.
  • academic/si525-assignments/ROADMAP-V1.md es la línea base aprobada para el desarrollo de V1.
  • Antes de implementar una funcionalidad, leer solo los artefactos académicos pertinentes y su spec.
  • Si una fuente es ambigua, no inventar reglas de negocio, operaciones de dominio, relaciones ni políticas.
  • Si la implementación contradice un artefacto académico, informar el conflicto. No conciliarlo en silencio.

Flujo SDD

  • spec.md: qué debe hacer la funcionalidad.
  • plan.md: cómo se implementará.
  • tasks.md: el trabajo de implementación.
  • constitution.md: principios estables de producto y proceso.
  • AGENTS.md: memoria técnica y del proyecto persistente (este archivo).
  • Las decisiones propias de una funcionalidad van en su spec o su plan, no aquí.

Convenciones de navegación y publicación de specs

La documentación SDD se publica con Retype. Al crear o modificar una funcionalidad bajo specs/, mantener la metadata de navegación junto con los artefactos fuente; no editar .docs/ ni .retype/ directamente porque son salidas generadas.

  • Cada funcionalidad vive en specs/NNN-slug/ y debe incluir index.yml para definir el nombre visible y el orden de la carpeta sin renombrar su ruta física.
  • El index.yml de una funcionalidad usa un label legible, por ejemplo 001 — Núcleo de agenda, y un order coherente con la secuencia de funcionalidades.
  • Cada Markdown principal de una funcionalidad debe comenzar con front matter YAML de Retype. Mantener estos labels y órdenes salvo que la estructura de la spec requiera algo distinto:
    • spec.md → label: Especificación, order: 100
    • plan.md → label: Plan de implementación, order: 90
    • tasks.md → label: Tareas, order: 80
    • research.md → label: Investigación, order: 70
    • data-model.md → label: Modelo de datos, order: 60
    • quickstart.md → label: Validación / Quickstart, order: 50
  • Si existen contracts/ o checklists/, pueden incluir su propio index.yml para mostrar nombres legibles como Contratos o Listas de verificación.
  • Los Markdown dentro de contracts/ y checklists/ también deben llevar front matter con un label descriptivo y un order coherente con la navegación.
  • El front matter es metadata de presentación: no debe alterar el significado, alcance ni autoridad del contenido SDD.
  • specs/README.md sigue siendo el mapa global y estado del producto; no duplicar allí requisitos detallados que pertenezcan a una spec concreta.

Idioma

  • Toda la documentación relevante se redacta en español latinoamericano: constitución, specs, planes, tareas, docs/ y este archivo. Se publicará en Retype y la leerán revisores académicos.

  • Los nombres de herramientas, términos técnicos establecidos (por ejemplo, "spec"), rutas e identificadores de código se mantienen en su forma original.

  • Los términos de dominio siguen las fuentes académicas (Consumidor, Emprendedor, Solicitud, Oferta, Pedido, Publicación).

Desarrollo local

  • Móvil: TODO tras el bootstrap de Flutter.
  • Backend: TODO tras el bootstrap de Spring Boot.
  • Base de datos/migraciones: TODO tras el bootstrap de Supabase. Actualizar cada entrada cuando se inicialice el proyecto correspondiente. No inventar comandos antes.

Convenciones

  • Nunca versionar secretos, llaves de API ni credenciales de servicios.
  • Mantener la configuración específica de cada entorno fuera del control de versiones.
  • Preferir commits pequeños y trazables.
  • Mantener los cambios de implementación alineados con su spec.
  • No editar directamente los SVG generados a partir de PlantUML; regenerarlos.
  • No tratar los artefactos UML o de prototipo históricos como autoridad vigente: domain-model.puml, el class-diagram.puml monolítico, tecnoupsa/, notes*/ y plan/.

Las reglas del producto viven en .specify/memory/constitution.md y el estado del producto vive en specs/README.md.