talos-access / progress /advisor_assessment.md
Greg
Claude Opus 4.7 (1M context)
Preparar despliegue en fly.io: monolito dockerizado + seeder demo
6aa6081
|
Raw History Blame Contribute Delete
9.76 kB
# Advisor Assessment β€” Post-MVP Sprint (F006β€”F009) & MVP Demo Readiness
**Date:** 2026-05-28
**Advisor:** Principal SME β€” Educational Software & Attendance Systems
**Scope:** Domain audit of post-MVP sprint (F006-F009) and MVP demo readiness assessment
---
## Executive Summary
The post-MVP sprint added 5 significant feature areas to the system. From a domain perspective, the system has evolved from "functional but rough" to **"demo-ready with minor caveats"**. The critical path coverage is strong; remaining gaps are primarily in reporting depth and edge-case polish, not core attendance workflow.
**Provisional Verdict:** DOMAIN_VALIDATED β€” MVP demo is viable with the caveats documented below.
---
## Sprint Audit: New Features (F006β€”F009)
### F006a β€” Hide Sat/Sun in Schedule Grid βœ…
**Domain verdict:** Correct. Venezuelan school weeks run Monday–Friday. Showing Saturday/Sunday in the default schedule view added visual noise. The configurable toggle ("Mostrar fin de semana") is appropriate since some schools have Saturday extracurricular activities.
### F006b β€” Holiday Calendar βœ…
**Model:** `Holiday(id, account_id, name, date, type)` with `national/school/vacation` enum
**Blocking logic:** `is_holiday()` utility blocks attendance creation at endpoint level
**Domain verdict:** CORRECT with a nuance:
- **Endpoint-level blocking** is pragmatic and verifiable. Each attendance-creation path explicitly calls `is_holiday()`.
- **Coverage is thorough** β€” checkin, self-checkin, teacher swipe, batch-toggle, toggle, facial recognize, facial checkout, facial self β€” all blocked.
- **Account isolation** via `account_id` ensures schools don't see each other's holidays.
- **⚠️ Caveat:** Holiday blocking only prevents *new* attendance creation. If a holiday is added retroactively, existing attendance records for that date remain. This is acceptable for MVP since admins would typically configure holidays before the school year starts.
### F006.1 β€” Section Capacity Enforcement βœ…
**Domain verdict:** Correct. The `_section_at_capacity()` helper is clean: `COUNT(enrollments) >= Section.max_students`. Returns 409 for single enrollment, skips with message for bulk. This is the expected real-world behavior β€” a teacher cannot have 45 students in a classroom designed for 40.
### F007a β€” Password Reset (Admin-Generated Token) βœ…
**Flow:** Admin clicks "Reset Password" β†’ system generates `secrets.token_urlsafe(32)` β†’ token shown in modal with copy button β†’ user visits `/reset-password` β†’ enters token + new password β†’ `must_change_password` flag cleared on success
**Domain verdict:** HIGHLY CORRECT for Venezuelan schools:
- **No email dependency** is the right call β€” many public schools lack institutional email or reliable internet for password reset emails.
- **Admin-generated token** shown in UI is practical: the admin can tell the user the token verbally, write it on a note, or print it.
- **`must_change_password` flag** ensures first login after reset forces a password change.
- **Token expiry (24h)** prevents stale tokens from being exploited.
- **Minimum 6-char validation** is reasonable for a school system (avoids forcing complex passwords that students will forget).
### F007b β€” Audit Log Viewer βœ…
**Domain verdict:** Correct. Paginated, filterable audit trail is essential for school compliance. Schools in regulated environments (e.g., Fe y AlegrΓ­a network, state-funded schools) often require audit logs for attendance record-keeping. The expandable JSON detail view is particularly useful for investigating specific actions.
### F008 β€” Role Workflows & Late Analytics βœ…
**Domain verdict:** CORRECT with observation:
- **Late arrival analytics** (`RETRASO:` / `SALIDA TEMPRANA:` in `note` column) is pragmatic β€” uses existing data without schema changes. The `LIKE` pattern is straightforward.
- **⚠️ Caveat:** Late/early data quality depends on teachers actually writing the note prefix correctly. No enforcement mechanism exists for the `RETRASO:` / `SALIDA TEMPRANA:` prefix convention. This is acceptable for MVP but should be documented in training materials.
- **Administrativo role** gaining student/section/report access is correct β€” this matches the "school secretary" role in Venezuelan schools who manages enrollment records.
- **Obrero role** (gate/general staff) getting check-in access is correct.
### F009a β€” Documentation βœ…
**Domain verdict:** Correct. `CHECKPOINTS.md`, `docs/architecture.md`, and `docs/conventions.md` provide the minimum viable documentation for handover and maintenance.
### F009b β€” Core Business Logic Tests βœ…
**Coverage:** 12 tests in `tests/test_business.py` covering holiday isolation, section capacity, attendance counting, password validation
**Domain verdict:** Acceptable for MVP. Tests cover the critical business invariants:
- Holiday dates block attendance (account-scoped)
- Section capacity prevents over-enrollment
- Present/absent counting is correct
- Password minimum length validation
---
## MVP Demo Readiness Assessment
### Scoring
| Criteria | Score | Notes |
|----------|-------|-------|
| Core attendance flow | βœ… | Check-in, check-out, teacher swipe, facial all work |
| Role-based access | βœ… | Admin, teacher, representative, administrativo, obrero |
| Student management | βœ… | CRUD, import, card assignment |
| Section/class management | βœ… | With capacity enforcement |
| Enrollment | βœ… | Multi-section, duplicate-protected, capacity-enforced |
| Schedule | βœ… | Weekly grid with weekday toggle |
| Holiday calendar | βœ… | Blocking attendance on holidays |
| Password reset | βœ… | Admin-generated token flow complete |
| Late analytics | βœ… | Data + visual report page |
| Audit log | βœ… | Viewable and filterable |
| Representative portal | βœ… | "Mis Hijos" page with attendance and schedule |
| Facial recognition | βœ… | Enrollment, recognition, checkout |
| Spanish UI | βœ… | All labels in Spanish |
| Documentation | βœ… | CHECKPOINTS, architecture, conventions |
### Gap Analysis (What a Client Would Notice)
#### Moderate Gaps (should address before serious demo)
1. **No academic year separation** β€” Data from different school years is mixed. A client might ask "how do I start a new school year?" β€” we don't have a clean answer beyond manual section management.
2. **No student attendance report by section** β€” The late arrivals report is useful, but there's no "attendance rate by section" or "daily attendance summary" report that a school director would expect.
#### Minor Gaps (acceptable for initial demo)
3. **No email/SMS notifications** β€” Schools will eventually want automated parent notifications for absences. Acceptable to defer.
4. **No mobile app** β€” The web app is mobile-responsive but not a dedicated mobile experience. Acceptable for MVP.
5. **No QR code check-in** β€” Some schools use QR codes at entrances. Not a blocker.
6. **No bulk holiday import** β€” Holidays must be added one by one. Minor UI inconvenience.
#### Strengths for Demo
1. **Password reset flow** β€” This was the #1 question schools asked. Now solved without email.
2. **Holiday blocking** β€” "See, if it's a national holiday, the system simply won't let anyone check in."
3. **Late arrival tracking** β€” "We can tell which students are habitually late, by section."
4. **Multi-section enrollment** β€” "Ana can be in both 5to A English and 5to B Math."
5. **Representative access** β€” "Parents can see their children's attendance from home."
---
## Recommended Demo Script (Domain-Focused)
1. **Login as admin** β†’ show dashboard β†’ show users by role
2. **Create a student** β†’ assign card β†’ enroll in section
3. **Show schedule** β†’ toggle weekend β†’ show holiday
4. **Create a holiday** (e.g., "24 de Diciembre") β†’ try to check in β†’ see 409 block
5. **Teacher check-in flow** β†’ swipe student β†’ show attendance record
6. **Late arrival** β†’ check in with "RETRASO: 15 min" β†’ show late arrivals report
7. **Password reset** β†’ admin generates token β†’ show copy β†’ user resets password
8. **Login as representative** β†’ show "Mis Hijos" β†’ attendance cards, schedule
9. **Audit log** β†’ show all actions tracked, filter by user
10. **Capacity enforcement** β†’ try to enroll 41st student β†’ see error
---
## Risks & Remediation
| Risk | Impact | Mitigation | Timeline |
|------|--------|------------|----------|
| Client asks about school year separation | Medium | Prepare verbal answer: "currently sections can be archived, academic year field is a future enhancement" | Pre-demo prep |
| Client asks about attendance reports by section | Medium | Point to late arrivals + student reports; explain reporting dashboard is in roadmap | Pre-demo prep |
| Facial recognition accuracy in poor lighting | Low | Configure camera settings; have manual check-in as fallback | Already handled |
| Client wants bulk holiday import | Low | Show single-create, mention CSV import can be added | Pre-demo Q&A prep |
---
## Final Verdict
**DOMAIN_VALIDATED** β€” The post-MVP sprint (F006β€”F009) correctly implements the business requirements. The system is **ready for an MVP demo with a potential client** given the documented caveats. The core attendance workflow is complete, role-based access covers all defined roles, and the new features (password reset, holiday calendar, capacity enforcement, late analytics, audit log) address the most common client demo questions.
**Recommended focus for demo day:** Prepare verbal answers for the two moderate gaps (academic year separation, section-level attendance reports) and lead with the password reset flow and holiday blocking as key differentiators.