[People] Roadmap: People, Soci and census across auth, backend and admin #146

This is the root of the People work across auth, backend and admin. Until now People was built without a clear direction. This issue sets the direction, records what happens to the existing code and PRs, and links every piece of work. Reviews of People PRs are paused until the sub-issues below say otherwise.

Phases

Progress shows in the sub-issue tree below. Each issue's order is set with GitHub "blocked by" links.

Decisions (29 October 2026)

1. Three separate concerns, little overlap. Phase 1 is People ↔ Auth accounts ↔ RBAC roles. Soci and fees (Phase 2) and the census (Phase 3) are separate, and are built after it.
2. People without a linked account live only in the backend, never as placeholder users in Auth. We often don't know which account someone will sign in with (Entra ID if they're a socio, otherwise any Google account), and the email and name we have may not match it.
3. Linking: an email invite the person accepts by signing in with any account, or a manual link by someone with the new people:link permission. No automatic matching.
4. Only predetermined roles: roles bound in Auth to admin, capo, team:<key>:member or team:<key>:lead, never with idp:* permissions. Clearance comes from RBAC, and Auth checks it on every change.
5. Capo Admin is part of Phase 1 (the capo-admin role already exists). Capo Admins may later manage the admins under them. That's not built now, but it's designed for.
6. Soci in People is removed outright, to be rebuilt from scratch on Entra ID users in Phase 2.
7. Nothing is migrated. Every People table holds only test data.
8. Administrative capabilities are RBAC permissions, not hard-coded Master Admin checks (e.g. binding a role to People).

Decisions (8 November 2026)

9. No bulk import. [People · Phase 1] Bulk import people from CSV backend#103 and [People · Phase 1] Bulk import wizard #141 are not planned. The 2026 admin census spreadsheets are imported once, outside the roadmap: an agent prepares a seed file that a person reviews, and a one-off script (scripts/people-seed/ in the admin repo) writes it through people.* as the signed-in person. From Phase 3 the census happens in the dashboard. Phase 1 is complete, and Phases 2 and 3 can start.

Decisions (9 November 2026)

Phase 2's design: docs/people/soci.md (#154).

10. The dashboard is the Libro Soci. Microsoft 365 still says who is a socio now (the Soci group). A backend register keyed on the account and the member number holds what Microsoft 365 doesn't:

    • legal name and optional alias;
    • codice fiscale, place and date of birth, residence;
    • admission and end dates;
    • fees and history.

    It starts empty, keeps history forever and never reuses a member number. Admitting a socio moves from Microsoft 365 › Members to People › Soci, with the same account workflow.

11. Fees: the Regolamento's rules are hard-coded (€5, fee year 1 Sep – 31 Aug, renewals until 31 Dec, the summer exemption). The socio uploads the transfer receipt, and the Direttivo confirms it or marks the fee as paid by hand. The association issues no receipts in this phase.

12. Lapse is automatic: an unpaid fee after 31 December removes the account from Soci, so Auth drops the Socio role. The account waits in Deletion pending until someone deletes it by hand.

13. Soci get people:self: My area is the one place for one's own association life. The Direttivo holds soci:read, soci:write and soci:delete.

14. Soci stay under People, in their own panel group next to Volunteers.

15. Automatic emails go to the PoliNetwork mailbox: fee-year opening, reminders, lapse, birthdays.

What's in production

• admin: a People area with Overview, Admins, Teams, Census, Linking, Capo Admin, My area, the Soci register, fees and receipts: feat(people): add people records, roles and census workflows #97, feat(people): add fee renewal and signed receipts #100, fix(people): accept unknown Telegram group admins in the Capo area #134. It's empty and not connected to RBAC.
• backend: the people.* API (feat(people): add the people api for the admin dashboard backend#83, fix(people): classify pending telegram admin removals backend#94). It holds all of that, plus creating Microsoft 365 accounts and the eSign receipt bridge.
• auth: no People code on main.
  • people:* permissions exist, granted to direttivo and it-lead.
  • Team roles (hr-*, design-*, intl-*, events-*) and capo-admin exist, but nothing binds them to People yet.

What happens to the open PRs

Older issues covering parts of this: #23, #24, #25.

How to follow along

• Every issue has the people label, and its title starts with [People], [People · Cleanup] or [People · Phase N].
• Each repo issue is a sub-issue of its phase, and each phase is a sub-issue of this one.
• PRs should say Closes <issue> so progress rolls up here.