Greg Claude Opus 4.7 (1M context) commited on
Commit
cf2fc7c
·
1 Parent(s): 0526771

docs(ta-01): add sprint spec and design for storage + admin attendance + gate decouple

Browse files

Three-block sprint design covering:
- Photo storage migration from Base64 in DB to Supabase Storage via PhotoStorage abstraction
- Admin attendance view for teacher-absence contingencies, with marked_by_* attribution columns
- Decoupling gate EntranceLog from classroom attendance to tolerate technical failures

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/sprints/2026-06-05_TA-01.md ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### 1. Optimización y Carga de Fotografías de Usuarios
2
+ * **Situación Actual:** Actualmente, las fotos de los usuarios se están guardando directamente en la base de datos como cadenas en Base64 (lo cual está afectando el rendimiento y el almacenamiento).
3
+
4
+ * **Nuevo Requerimiento:** * Además de capturar la foto en línea (cámara), el administrador debe poder subir archivos en formatos `png`, `jpg`, `jpeg` y `webp`.
5
+ * Antes de guardarse, la imagen debe pasar por un proceso de compresión eficiente (buscando reducir el almacenamiento en disco pero manteniendo una calidad visual óptima, "lossless" o compresión controlada).
6
+ * La imagen ya no se guardará en Base64 en la BD; ahora se subirá a un Storage y en la base de datos solo se almacenará la ruta/URL de acceso.
7
+ * *Nota de contexto:* Más adelante te proporcionaré las credenciales y accesos al bucket de Supabase Storage que utilizaremos para esto. Por ahora, diseña la lógica de forma agnóstica o preparada para Supabase.
8
+
9
+ ### 2. Módulo de Asistencia Administrativa (Casos de Contingencia)
10
+ * **Requerimiento:** Crear una nueva vista/interfaz dedicada para que los administradores del sistema puedan tomar asistencia directamente en el aula.
11
+
12
+ * **Caso de Uso:** Un profesor se enfermó o no asistió a clases, por lo que un administrador debe ir físicamente al aula a pasar lista a los alumnos de esa sección.
13
+
14
+ ### 3. Flexibilidad en las Reglas de Negocio de Asistencia (Check-in General vs. Asistencia de Aula)
15
+ * **Requerimiento:** El proceso de Check-in/Check-out del plantel (entrada/salida general) NO debe ser restrictivo para la asistencia en el aula. Un alumno puede ser marcado como "Asistente" en su clase/materia, incluso si no registra entrada en el acceso principal del plantel.
16
+
17
+ * **Caso de Uso:** Fallas tecnológicas (falla en el sistema de reconocimiento con OpenCV, corte de electricidad, o pérdida de internet en el equipo del kiosco de entrada). Los alumnos no pudieron hacer Check-in al entrar al plantel, pero el docente (o el administrador) debe poder registrar la asistencia de forma singular en su respectiva materia sin que el sistema bloquee la acción.
18
+
19
+ ---
20
+
21
+ ### Lo que espero de tu respuesta:
22
+ 1. **Diseño de Base de Datos:** Qué cambios o nuevas columnas/tablas sugieres (ej. cambiar el tipo de dato de la foto, campos para los estados de asistencia).
23
+ 2. **Estrategia de Procesamiento de Imágenes:** Qué librerías o enfoque recomiendas para la compresión en el backend antes de subir al storage.
24
+ 3. **Arquitectura del Flujo de Asistencia:** Cómo estructurar la lógica para que convivan el Check-in general (OpenCV/Kiosco) y la asistencia manual por aula sin depender estrictamente el uno del otro.
docs/superpowers/specs/2026-06-05-ta01-storage-and-attendance-design.md ADDED
@@ -0,0 +1,357 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # TA-01 — Storage de fotos + asistencia administrativa + flexibilidad gate
2
+
3
+ **Fecha:** 2026-06-05
4
+ **Sprint:** TA-01
5
+ **Estado:** Diseño aprobado, pendiente plan de implementación
6
+ **Fuente requisitos:** `docs/sprints/2026-06-05_TA-01.md`
7
+
8
+ ## Resumen
9
+
10
+ Sprint con tres bloques independientes pero entregados como una sola unidad:
11
+
12
+ - **Bloque A — Fotos:** migrar fotos de usuarios de Base64 en BD a archivos comprimidos (WebP) en un storage externo (Supabase Storage en prod, disco local en dev), detrás de una interfaz `PhotoStorage` con adapters intercambiables.
13
+ - **Bloque B — Asistencia administrativa:** nueva vista y endpoints para que los administradores pasen lista por aula cuando un docente está ausente, con trazabilidad de quién marcó cada asistencia.
14
+ - **Bloque C — Flexibilidad gate ↔ aula:** desacoplar la asistencia de aula del registro de entrada al plantel para tolerar fallas técnicas del kiosco (OpenCV, electricidad, internet).
15
+
16
+ ## Motivación
17
+
18
+ 1. Las fotos en Base64 dentro de la columna `face_encodings.photo` están afectando rendimiento y crecimiento de la BD; el patrón estándar es guardar archivos en un storage y solo la ruta en la BD.
19
+ 2. Cuando un docente falta, hoy no existe forma de que un administrador pase lista por aula desde el sistema — debe hacerse manualmente o quedar sin registrar.
20
+ 3. El acoplamiento actual (un estudiante no puede ser marcado presente en clase si no hizo check-in en el gate) era intencional como invariante de negocio, pero la operación real tiene cortes de electricidad / internet / fallas de cámara que dejan al docente sin poder marcar asistencia legítima. La contingencia técnica gana prioridad sobre la invariante.
21
+
22
+ **Reversión consciente:** este sprint revierte la guía previa de mantener acoplados `EntranceLog` y asistencia de aula. La motivación es contingencia técnica documentada arriba.
23
+
24
+ ## Decisiones de diseño tomadas
25
+
26
+ | # | Pregunta | Decisión |
27
+ |---|----------|----------|
28
+ | 1 | Alcance del sprint | Un único spec con los 3 bloques. |
29
+ | 2 | Abstracción de storage | Interfaz `PhotoStorage` con adapters `LocalDiskStorage` (dev) y `SupabaseStorage` (prod). Switch por env var. |
30
+ | 3 | Ubicación de la URL/path de foto en BD | Cambiar el tipo de `face_encodings.photo` de `Text` a `VARCHAR(500)`. No agregar columna nueva en `users`. |
31
+ | 4 | Migración de datos existentes | No automática. El admin re-sube manualmente las pocas fotos existentes. La migración Alembic solo cambia el tipo. |
32
+ | 5 | Perfil de compresión | WebP lossy q=85, máximo 800×800 px manteniendo aspect ratio. |
33
+ | 6 | Scope del admin en asistencia | Cualquier sección de su cuenta. Sin tabla de asignación admin-sección. |
34
+ | 7 | Trazabilidad de quién marcó | Agregar `attendances.marked_by_role` y `attendances.marked_by_user_id`. También se popula en marcas hechas por docente y por kiosco. |
35
+ | 8 | Grado de desacople gate | Desacople total: nunca bloquear. El chip `entrance_logged` se sigue calculando como información en la UI. |
36
+ | 9 | Ubicación de la UI admin | Página nueva `/admin/attendance` reutilizando componentes extraídos de `TeacherAttendancePage`. |
37
+
38
+ ## Cambios de base de datos
39
+
40
+ Migración Alembic: `backend/migrations/versions/028_ta01_storage_and_attendance_attribution.py`
41
+
42
+ ```sql
43
+ -- Bloque A: foto pasa de Base64 a URL/path corto + permitir encoding NULL
44
+ ALTER TABLE face_encodings
45
+ ALTER COLUMN photo TYPE VARCHAR(500) USING NULL, -- vacía las filas viejas; admin re-sube
46
+ ALTER COLUMN encoding DROP NOT NULL; -- permite foto sin rostro detectado
47
+
48
+ -- Bloque B: trazabilidad de origen de la marca
49
+ ALTER TABLE attendances
50
+ ADD COLUMN marked_by_role VARCHAR(20), -- 'teacher' | 'admin' | 'kiosco'
51
+ ADD COLUMN marked_by_user_id BIGINT NULL,
52
+ ADD CONSTRAINT fk_attendances_marked_by_user
53
+ FOREIGN KEY (marked_by_user_id) REFERENCES users(id);
54
+
55
+ CREATE INDEX ix_attendances_marked_by_user_id ON attendances(marked_by_user_id);
56
+ ```
57
+
58
+ **Justificación de `encoding NULL`:** el endpoint de upload de Bloque A intenta extraer encoding facial vía `face_utils`. Si la foto no tiene rostro detectable (ej. foto carnet con lente o ángulo), guardamos la foto igualmente con `encoding=NULL` para no perder la foto de identidad del usuario. El kiosco facial filtra `WHERE encoding IS NOT NULL` al hacer matching.
59
+
60
+ **Downgrade:**
61
+
62
+ ```sql
63
+ DROP INDEX ix_attendances_marked_by_user_id;
64
+ ALTER TABLE attendances
65
+ DROP CONSTRAINT fk_attendances_marked_by_user,
66
+ DROP COLUMN marked_by_user_id,
67
+ DROP COLUMN marked_by_role;
68
+ ALTER TABLE face_encodings
69
+ ALTER COLUMN photo TYPE TEXT;
70
+ ```
71
+
72
+ **Modelos SQLAlchemy:**
73
+
74
+ - `app/models/face_encoding.py` → `photo = Column(String(500), nullable=True)`
75
+ - `app/models/attendance.py` → agregar `marked_by_role = Column(String(20), nullable=True)` y `marked_by_user_id = Column(BigInteger, ForeignKey("users.id"), nullable=True)`
76
+
77
+ ## Bloque A — Storage de fotos
78
+
79
+ ### 1. Capa de abstracción (`backend/app/storage/`)
80
+
81
+ Estructura nueva del paquete:
82
+
83
+ ```
84
+ backend/app/storage/
85
+ __init__.py # factory: get_storage() lee env var
86
+ base.py # Protocol PhotoStorage
87
+ local_disk.py # LocalDiskStorage
88
+ supabase.py # SupabaseStorage (stub inicial)
89
+ in_memory.py # InMemoryStorage (solo tests)
90
+ ```
91
+
92
+ `base.py`:
93
+
94
+ ```python
95
+ from typing import Protocol
96
+
97
+ class PhotoStorage(Protocol):
98
+ def upload(self, account_id: int, user_id: int, content: bytes, ext: str) -> str:
99
+ """Persiste el archivo y devuelve la ruta/URL canónica que se guarda en BD."""
100
+ def delete(self, path_or_url: str) -> None:
101
+ """Borra el archivo. Best-effort, no levanta si no existe."""
102
+ def get_url(self, path_or_url: str) -> str:
103
+ """Devuelve la URL pública o firmada con la que el frontend lo consume."""
104
+ ```
105
+
106
+ `__init__.py`:
107
+
108
+ ```python
109
+ def get_storage() -> PhotoStorage:
110
+ backend = os.getenv("PHOTO_STORAGE_BACKEND", "local").lower()
111
+ if backend == "local":
112
+ return LocalDiskStorage(root=os.getenv("LOCAL_PHOTO_ROOT", "/data/photos"))
113
+ if backend == "supabase":
114
+ return SupabaseStorage(
115
+ url=os.getenv("SUPABASE_URL"),
116
+ key=os.getenv("SUPABASE_SERVICE_KEY"),
117
+ bucket=os.getenv("SUPABASE_PHOTO_BUCKET", "user-photos"),
118
+ )
119
+ raise ValueError(f"Unknown PHOTO_STORAGE_BACKEND: {backend}")
120
+ ```
121
+
122
+ `LocalDiskStorage`:
123
+
124
+ - Path en disco: `{root}/{account_id}/{user_id}/{uuid4}.{ext}`
125
+ - `get_url` devuelve `/api/v1/photos/{path}` (endpoint sirve el archivo con `FileResponse`)
126
+ - `delete` ignora `FileNotFoundError`
127
+
128
+ `SupabaseStorage` (inicial: stub que tira `NotImplementedError` con mensaje claro hasta que lleguen credenciales; las firmas y tests fakeados ya quedan listos).
129
+
130
+ ### 2. Pipeline de procesamiento de imágenes (`backend/app/services/photo_pipeline.py`)
131
+
132
+ ```python
133
+ from io import BytesIO
134
+ from PIL import Image, ImageOps
135
+ import magic
136
+
137
+ ALLOWED_MIME = {"image/png", "image/jpeg", "image/webp"}
138
+ MAX_INPUT_BYTES = 5 * 1024 * 1024 # 5 MB
139
+ TARGET_MAX_DIM = 800
140
+ WEBP_QUALITY = 85
141
+
142
+ def process_user_photo(raw: bytes) -> bytes:
143
+ if len(raw) > MAX_INPUT_BYTES:
144
+ raise ValueError("photo exceeds 5 MB")
145
+ mime = magic.from_buffer(raw, mime=True)
146
+ if mime not in ALLOWED_MIME:
147
+ raise ValueError(f"unsupported mime: {mime}")
148
+ img = Image.open(BytesIO(raw))
149
+ img = ImageOps.exif_transpose(img) # corrige rotación
150
+ img.thumbnail((TARGET_MAX_DIM, TARGET_MAX_DIM), Image.LANCZOS)
151
+ if img.mode in ("RGBA", "P"):
152
+ img = img.convert("RGB")
153
+ out = BytesIO()
154
+ img.save(out, format="WEBP", quality=WEBP_QUALITY, method=6)
155
+ return out.getvalue()
156
+ ```
157
+
158
+ Librerías nuevas en `backend/requirements.txt`: `Pillow` (verificar versión actual), `python-magic`. En Windows dev, `python-magic-bin`.
159
+
160
+ ### 3. Endpoint de upload
161
+
162
+ `POST /api/v1/users/{user_id}/photo` (admin-only):
163
+
164
+ ```
165
+ 1. multipart/form-data con campo `file` (max 5 MB; png|jpg|jpeg|webp)
166
+ 2. processed = process_user_photo(raw) # WebP 800×800 q=85
167
+ 3. Intentar extract_encoding(processed) vía face_utils:
168
+ - éxito → encoding_str
169
+ - sin rostro detectable → encoding_str = None, warning_flag = True
170
+ 4. storage = get_storage()
171
+ 5. Buscar último face_encoding del user; si existe y tiene photo:
172
+ storage.delete(old.photo) # best-effort
173
+ 6. new_path = storage.upload(account_id, user_id, processed, "webp")
174
+ 7. INSERT face_encodings (user_id, account_id, encoding=encoding_str, photo=new_path)
175
+ 8. Respuesta:
176
+ 200 { "photo_url": storage.get_url(new_path),
177
+ "encoding_extracted": bool,
178
+ "warning": "no se detectó rostro; el reconocimiento facial no
179
+ funcionará hasta resubir una foto con rostro visible"
180
+ if not encoding_extracted else None }
181
+ ```
182
+
183
+ **Mapeo en responses de usuarios:** En `users.py:72-99` (y cualquier otro lugar que devuelva `face_photo`), la columna `face_encodings.photo` ahora contiene un path/URL. Antes de devolverlo al frontend, pasa por `storage.get_url(path)` para que el frontend reciba siempre una URL servible (sea local `/api/v1/photos/...` o Supabase firmada). El campo `face_photo` en `UserResponse` schema mantiene su nombre y tipo `Optional[str]`.
184
+
185
+ ### 4. Endpoint para servir foto local
186
+
187
+ `GET /api/v1/photos/{account_id}/{user_id}/{filename}` con `FileResponse` y verificación de pertenencia a cuenta (auth + scope). Solo activo cuando `PHOTO_STORAGE_BACKEND=local`.
188
+
189
+ ## Bloque B — Asistencia administrativa
190
+
191
+ ### 1. Refactor previo (extracción de servicio)
192
+
193
+ Mover la lógica de marca de asistencia desde `app/api/v1/endpoints/teacher.py` a `app/services/attendance.py`:
194
+
195
+ ```python
196
+ def record_attendance(
197
+ db, *, account_id, user_id, section_id, subject_id, action,
198
+ marked_by_role: str, marked_by_user_id: int, when: datetime,
199
+ ) -> Attendance: ...
200
+
201
+ def list_section_roster(
202
+ db, *, account_id, section_id, on_date,
203
+ ) -> list[StudentRosterItem]: ...
204
+ ```
205
+
206
+ `teacher.py` y los nuevos endpoints admin pasan a llamar al servicio. Esto elimina duplicación y deja el cambio del Bloque C en un solo lugar.
207
+
208
+ ### 2. Endpoints admin (`app/api/v1/endpoints/admin_attendance.py`)
209
+
210
+ ```
211
+ GET /api/v1/admin/sections
212
+ GET /api/v1/admin/sections/{section_id}/subjects?on_date=YYYY-MM-DD
213
+ GET /api/v1/admin/sections/{section_id}/roster?subject_id=&on_date=YYYY-MM-DD
214
+ POST /api/v1/admin/attendance/swipe
215
+ POST /api/v1/admin/attendance/batch-toggle
216
+ ```
217
+
218
+ Schemas: mismos de `teacher` con renombre cosmético. Auth: `require_role("admin")`. Scope: filtrado por `current_user.account_id` en todas las queries.
219
+
220
+ ### 3. Frontend
221
+
222
+ Componentes nuevos / reusados:
223
+
224
+ - Extraer de `frontend/src/pages/teacher/TeacherAttendancePage.tsx` los componentes presentacionales: `AttendanceTable`, `StudentRow`, `AttendanceSummaryChips`. Mover a `frontend/src/components/attendance/`.
225
+ - Nueva página: `frontend/src/pages/admin/AdminAttendancePage.tsx`
226
+ - Header: selector `Section` → `Subject` → `Date` (default hoy).
227
+ - Body: `<AttendanceTable />` con datos del endpoint admin.
228
+ - Footer: contadores presente/ausente y botón "Guardar".
229
+ - Nuevo servicio: `frontend/src/services/adminAttendanceService.ts` espejo de `teacherService.ts`.
230
+ - Ruta: `/admin/attendance` agregada al router y al sidebar admin con el item "Asistencia por contingencia".
231
+
232
+ ## Bloque C — Desacople gate ↔ aula
233
+
234
+ ### Cambios
235
+
236
+ En `app/api/v1/endpoints/teacher.py` (y, después del refactor del Bloque B, en `app/services/attendance.py`):
237
+
238
+ - Eliminar el cálculo de `entrance_logged_ids` como **filtro** en `submit_swipe` (`teacher.py:470-496`) y en `batch-toggle` (`teacher.py:580-…`).
239
+ - Eliminar las acumulaciones de `skipped_ids` derivadas del check de gate.
240
+ - Eliminar las ramas `if rec.student_id not in entrance_logged_ids: skipped_ids.append(...)`.
241
+ - Grep adicional antes de implementar: `entrance_logged_ids` en todo el backend para asegurar que no quedó otro punto bloqueante (también revisar `services/attendance.py` post-refactor del Bloque B).
242
+
243
+ El `entrance_logged` que se devuelve en el roster (`GET /students` y similares) sigue calculándose; solo cambia su rol: ya no es bloqueante.
244
+
245
+ **Marcas desde el kiosco:** en `app/api/v1/endpoints/facial.py`, donde se inserta una `Attendance` desde reconocimiento facial, agregar `marked_by_role='kiosco'` y `marked_by_user_id=None`. Es un cambio de una línea para preservar consistencia del Bloque B.
246
+
247
+ ### Documentación de UI
248
+
249
+ En `TeacherAttendancePage` y `AdminAttendancePage`: el chip `entrance_logged` cambia de tono de "advertencia bloqueante" a "informativo" (gris). Tooltip: "Este estudiante no registró entrada en el gate hoy. Podés marcar asistencia igualmente."
250
+
251
+ ## Arquitectura de archivos (cambios)
252
+
253
+ ```
254
+ backend/
255
+ app/
256
+ models/
257
+ attendance.py [edit: +marked_by_role, +marked_by_user_id]
258
+ face_encoding.py [edit: photo = String(500)]
259
+ storage/ [NEW]
260
+ __init__.py
261
+ base.py
262
+ local_disk.py
263
+ supabase.py
264
+ in_memory.py
265
+ services/ [NEW or grow]
266
+ attendance.py [NEW: record_attendance, list_section_roster]
267
+ photo_pipeline.py [NEW]
268
+ api/v1/endpoints/
269
+ teacher.py [edit: usa services/attendance + quita gate filter]
270
+ admin_attendance.py [NEW]
271
+ users.py [edit: photo endpoint + mapea path → URL en responses]
272
+ photos.py [NEW: GET local file]
273
+ migrations/versions/
274
+ 028_ta01_storage_and_attendance_attribution.py [NEW]
275
+ tests/
276
+ storage/ [NEW: test_local_disk, test_supabase, test_in_memory]
277
+ services/ [NEW: test_photo_pipeline, test_attendance_service]
278
+ api/
279
+ test_admin_attendance.py [NEW]
280
+ test_teacher_attendance_gate_decouple.py [NEW: regresión Bloque C]
281
+ test_users_photo_upload.py [NEW]
282
+
283
+ frontend/
284
+ src/
285
+ components/attendance/ [NEW: extracción]
286
+ AttendanceTable.tsx
287
+ StudentRow.tsx
288
+ AttendanceSummaryChips.tsx
289
+ pages/
290
+ teacher/TeacherAttendancePage.tsx [edit: usa componentes extraídos]
291
+ admin/AdminAttendancePage.tsx [NEW]
292
+ services/
293
+ adminAttendanceService.ts [NEW]
294
+ routes.tsx [edit: +/admin/attendance]
295
+ ```
296
+
297
+ ## Variables de entorno nuevas
298
+
299
+ ```
300
+ PHOTO_STORAGE_BACKEND=local # local | supabase
301
+ LOCAL_PHOTO_ROOT=/data/photos # solo si backend=local
302
+ SUPABASE_URL= # solo si backend=supabase
303
+ SUPABASE_SERVICE_KEY= # solo si backend=supabase
304
+ SUPABASE_PHOTO_BUCKET=user-photos # opcional, default mostrado
305
+ ```
306
+
307
+ En `docker-compose.yml` montar volumen `/data/photos` para el backend (dev). En `.env.example` agregar las cinco variables con valores de dev.
308
+
309
+ ## Plan de testing
310
+
311
+ - **Storage**
312
+ - `LocalDiskStorage`: upload escribe archivo, delete lo borra (y es idempotente), get_url devuelve el path correcto.
313
+ - `InMemoryStorage`: smoke en memoria para tests rápidos del pipeline.
314
+ - `SupabaseStorage`: stub levanta `NotImplementedError` con mensaje claro hasta integración real.
315
+ - **Photo pipeline**
316
+ - Rechaza tamaños > 5 MB.
317
+ - Rechaza mime no permitido (probar gif).
318
+ - Acepta png, jpeg, webp.
319
+ - Output siempre es WebP de ≤ 800×800.
320
+ - EXIF rotation se aplica (foto verticalmente girada queda derecha).
321
+ - **Endpoint upload**
322
+ - Admin de otra cuenta no puede subir foto de un user.
323
+ - Sube foto, llamada GET la devuelve.
324
+ - Subir segunda foto borra la anterior del storage.
325
+ - **Servicio de asistencia**
326
+ - `record_attendance` setea `marked_by_role` y `marked_by_user_id` correctamente.
327
+ - Idempotencia: misma marca dos veces no duplica.
328
+ - **Endpoints admin**
329
+ - Admin puede listar todas las secciones de su cuenta.
330
+ - Admin de otra cuenta recibe 404 al pedir una sección ajena.
331
+ - `swipe` y `batch-toggle` se comportan como los de teacher pero con `marked_by_role='admin'`.
332
+ - **Regresión Bloque C**
333
+ - Estudiante sin `EntranceLog` del día ahora SÍ se marca presente en `teacher/attendance/swipe` y en `teacher/attendance/batch-toggle`.
334
+ - El roster sigue devolviendo `entrance_logged: false` para ese estudiante (información preservada).
335
+
336
+ ## Out of scope
337
+
338
+ - Migración automática de fotos Base64 existentes (admin re-sube manualmente).
339
+ - UI para que el admin "confirme ausencia de docente" o se asigne a una sección (admin tiene scope completo).
340
+ - Reportes diferenciados por `marked_by_role` (la columna queda lista pero los reports no la consumen en este sprint).
341
+ - Soporte para Supabase Storage real funcionando — el adapter queda con stub. La integración efectiva se hará cuando lleguen credenciales (sprint posterior).
342
+
343
+ ## Riesgos y mitigaciones
344
+
345
+ | Riesgo | Mitigación |
346
+ |--------|------------|
347
+ | Volumen local `/data/photos` en dev no persiste entre `docker compose down -v` | Documentar; el admin re-sube en dev. |
348
+ | `python-magic` requiere libmagic; en Windows usar `python-magic-bin` | Documentar en `requirements.txt` y `README` con condición de OS. |
349
+ | Reverter el filtro del gate podría permitir marcar a un estudiante que ni siquiera vino al colegio | Aceptado por requisito de contingencia. Trazabilidad retroactiva queda en `attendances.marked_by_user_id` (quién marcó) + flag `entrance_logged=false` ya almacenado, suficiente para auditar después. |
350
+ | Extraer componentes del frontend puede romper la UI de docente | Test manual de TeacherAttendancePage post-refactor antes de mergear. |
351
+
352
+ ## Convenciones del proyecto a respetar
353
+
354
+ - TZ: usar `datetime.now(timezone.utc)` para escrituras a columnas timezone-aware. El contenedor está en `America/Caracas`.
355
+ - Tests: pytest directo, **no** tocar `init.sh`.
356
+ - Commits locales OK durante el sprint, **NO** push automático a producción.
357
+ - Un mismo motor de BD en dev y prod (PostgreSQL).