feat: Update docker-compose configuration to use environment variables for sensitive data, enhance testing documentation with new LaTeX files for capacity planning, and refine README for clarity on compilation and testing processes.

docs/plan_pruebas/sections/02_arquitectura.tex

@@ -1,11 +1,48 @@
 \chapter{Arquitectura bajo prueba}
 \label{ch:arquitectura}
 
-\section{Vista de componentes}
-El host solo expone el Gateway en el puerto \textbf{8189}. El resto de APIs viven en la red Docker. El agent del bot corre en PCs externas y se comunica por HTTP + PutObject a MinIO.
+\section{C\'omo est\'a dise\~nado el sistema}
+IPSExtractor sigue una arquitectura de \textbf{microservicios} detrás de un
+\textbf{API Gateway}. El host solo expone el puerto \textbf{8189}; el resto vive
+en la red Docker. Los agents Selenium corren en PCs externas (HTTP + PutObject a MinIO).
+
+\noindent\textbf{Nombres:} \texttt{bot-descarga} = orquestador (API); \textbf{agent Selenium} = PC que descarga.
+ST-BOT-* mide el orquestador; $\sim$422 fact/h es del agent.
 
 \input{diagrams/arquitectura}
 
+\section{Patrones de dise\~no}
+\begin{description}[style=nextline,leftmargin=0.8cm,labelwidth=3.2cm]
+  \item[API Gateway]
+    \'Unica puerta p\'ublica. Proxy a extraction, cleaning, count-api y bot-descarga.
+    Centraliza CORS, health y timeouts (JSON 30\,s; uploads del orquestador 600\,s).
+    \emph{Implicaci\'on de prueba:} ST-GW-* miden el gateway, no el OCR ni el LLM.
+  \item[Bounded contexts]
+    Cada servicio tiene un dominio claro: OCR (count-api), LLM (extraction+workers),
+    orquestaci\'on de descarga (\texttt{bot-descarga}), limpieza CSV (cleaning).
+    \emph{Implicaci\'on:} fallos y capacidad se prueban por servicio, no solo E2E.
+  \item[Cola as\'incrona (ARQ)]
+    Con \texttt{ASYNC\_QUEUE=true}, el ingest encola en Redis y los workers drenan.
+    Con \texttt{false} (default), el API procesa en el mismo request (sync).
+    \emph{Implicaci\'on:} ST-EXT-01 exige async + workers; ST-EXT-02 puede correr sync.
+  \item[Claim / lease]
+    Un job \texttt{pending} solo lo toma un agent Selenium (claim at\'omico v\'ia \texttt{bot-descarga}). Heartbeat
+    mantiene al worker online; sin heartbeat, no se asignan jobs.
+    \emph{Implicaci\'on:} ST-BOT-01/02 miden el orquestador (heartbeats y contenci\'on de claim).
+\end{description}
+
+\input{diagrams/patrones}
+
+\section{Pipeline de negocio}
+\input{diagrams/pipeline_negocio}
+
+\begin{enumerate}
+  \item \textbf{Descarga:} agent Selenium obtiene PDFs $\rightarrow$ MinIO.
+  \item \textbf{Conteo:} OCR/ONNX valida el documento (filtro de calidad).
+  \item \textbf{Extracci\'on:} LLM rellena campos $\rightarrow$ PostgreSQL.
+  \item \textbf{Limpieza:} reglas/CSV sobre el lote.
+\end{enumerate}
+
 \section{Inventario de componentes}
 \begin{table}[ht]
 \centering
@@ -14,35 +51,35 @@ El host solo expone el Gateway en el puerto \textbf{8189}. El resto de APIs vive
 \textbf{Componente} & \textbf{Puerto} & \textbf{Responsabilidad} \\
 \midrule
 \texttt{api\_gateway} & Host 8189 & Proxy HTTP, health agregado, CORS \\
-\texttt{extraction} & 8001 & Jobs/tasks, LLM, ingest PDFs \\
+\texttt{extraction} & 8001 & Tasks, LLM, ingest PDFs \\
 \texttt{worker} (ARQ) & --- & Procesamiento async v\'ia Redis \\
 \texttt{cleaning} & 8002 & Limpieza CSV / reglas \\
 \texttt{count-api} & 8080 & OCR + ONNX, stateless \\
-\texttt{bot-descarga} & 8200 & Control remoto de bots \\
+\texttt{bot-descarga} & 8200 & Orquestador: jobs, claim, heartbeats, events \\
 PostgreSQL 16 & 5432 & Persistencia compartida \\
 Redis 7 & 6379 & Cola ARQ + rate limiter \\
 Desktop & local & Cliente Electron/React \\
-Agent bot & local PC & Selenium + MinIO upload \\
-MinIO/S3 & externo & Excel y PDFs del bot \\
+Agent Selenium & local PC & Descarga PDFs (Selenium/Imaging) + MinIO upload \\
+MinIO/S3 & externo & Excel y PDFs del pipeline de descarga \\
 \bottomrule
 \end{tabular}
 \caption{Componentes del sistema bajo prueba.}
 \end{table}
 
-\section{Flujo cr\'itico: bot de descarga}
+\section{Flujo cr\'itico: descarga (orquestador + agent Selenium)}
 \input{diagrams/flujo_bot}
 
 Secuencia resumida:
 \begin{enumerate}
-  \item Agent: \texttt{register} + loop \texttt{heartbeat} / \texttt{claim\_pending} ($\sim$8\,s).
+  \item Agent Selenium: \texttt{register} + loop \texttt{heartbeat} / \texttt{claim\_pending} ($\sim$8\,s).
   \item Desktop: \texttt{POST /bot-descarga/jobs} (Excel, \texttt{worker\_id}, \texttt{job\_id}).
   \item API: valida job padre y worker online; sube Excel a MinIO; estado \texttt{pending}.
-  \item Agent: claim $\rightarrow$ \texttt{RUNNING}; descarga Excel; Selenium/Imaging; PutObject PDFs.
+  \item Agent Selenium: claim $\rightarrow$ \texttt{RUNNING}; descarga Excel; Selenium/Imaging; PutObject PDFs.
   \item Eventos \texttt{POST /events}; cierre \texttt{PATCH /jobs/\{id\}} (\texttt{completed}/\texttt{failed}).
 \end{enumerate}
 
 Layout MinIO:
-\begin{lstlisting}[language={},caption={Prefijos MinIO del bot}]
+\begin{lstlisting}[language={},caption={Prefijos MinIO del pipeline de descarga}]
 uploads/{download_job_id}/input.xlsx
 downloads/{download_job_id}/{nit}/{radicado}.pdf
 downloads/{download_job_id}/_manifest.json
@@ -51,6 +88,6 @@ downloads/{download_job_id}/_manifest.json
 \section{Otros flujos de negocio}
 \begin{description}
   \item[Conteo] Desktop $\rightarrow$ \texttt{POST /count/v1/count} $\rightarrow$ \texttt{POST /count-jobs} $\rightarrow$ validaci\'on humana.
-  \item[Extracci\'on] \texttt{from-count} o ingest de PDFs $\rightarrow$ workers ARQ $\rightarrow$ filas en BD.
+  \item[Extracci\'on] \texttt{from-count} o ingest de PDFs $\rightarrow$ (ARQ) workers $\rightarrow$ filas en BD.
   \item[Limpieza] Job cleaning desde \texttt{extraction\_batch\_id} o CSV upload.
 \end{description}