smart-org/docs/plan/reports/agent-1-phase-1.md

Agent 1 — Phase 1 report: platform invites, roles and org sharing

Date: 2026-10-14 · Branch: dev

What was done

1.1 platform_invites (db/models_org.py, migration a1b2c3d4e5f1)

The door into the product (D12). Unlike an org invite — which joins someone to an org that already exists — this one mints the platform account, so it is a capability: the token is stored only as a hash, it is single-use, it expires after PLATFORM_INVITE_TTL_HOURS, and the owner can revoke it. The email is optional; when pinned, the account it creates is bound to it.

1.2 PlatformInviteService

issue / list_pending / revoke / redeem. Two rules carry over from the org-invite flow unchanged, deliberately:

• A link can never reset the password of an existing account. A redeemed link whose email already belongs to somebody is refused; they sign in first.
• Every rejection gives the same answer. "No such link", "already used" and "revoked" are indistinguishable to a caller, so a probe cannot enumerate.

revoke refuses to un-redeem, and redeem is atomic (mark_used rejects a second caller rather than silently overwriting), so two workers redeeming the same link cannot both win.

1.2 Endpoints (admin_users.py, owner-only via the router's dependency)

POST /admin/platform-invites (returns invite_url once), GET /admin/platform-invites, POST /admin/platform-invites/{id}/revoke. All audited. owner is refused as a platform role — the seat moves only via a deliberate transfer.

1.3 invites.py — one lookup path, two kinds

_load_any_invite resolves a token to whichever kind it is, and the preview and accept routes both branch on it. A platform invite carries kind: "platform" and no organization. Redemption either mints a manager (anonymous, with the password — and the email the holder types when the owner pinned none) or raises an existing account to the invited role.

1.4 GET /auth/me gains needs_onboarding

True for a manager with zero organizations and not the owner. The client reads it through fetchNeedsOnboarding() rather than recomputing the rule locally, so it cannot drift from the server's.

1.5 Org sharing (organizations.py)

• POST /transfer-ownership — the current org owner only, to an existing admin member, with the org slug typed back, both role changes and the assignment in one transaction so there is never a moment with no owner. Audited.
• POST /leave — the last owner cannot leave: an organization with no owner is invisible to everyone, because its owner_user_id points at a non-member.
• GET/DELETE /invites — list and revoke. Revoking is expressed as expiry rather than a revoked_at column, because adding one would mean editing the locked db/models.py; a revoked link and an expired link are both simply unusable, and it cannot un-accept somebody who already joined.

Frontend

/accept-invite titles a platform invite ساخت حساب مدیر, shows the pinned email when there is one, and asks for an address when there is none. /admin/users gains a "دعوت مدیر جدید" button → modal → the link shown once, plus a pending-links card with revoke. /onboarding redirects anyone who already has an organization. lib/api-org.ts is no longer a stub; contracts gained PlatformInvite, IssuedPlatformInvite, needs_onboarding and the kind discriminator.

Files changed

Backend: db/models_org.py, alembic/versions/a1b2c3d4e5f1_org_platform.py, domain/identity/models.py (PlatformInvite), domain/audit/models.py (MEMBER_INVITE_REVOKE), application/services/platform_users.py (PlatformInviteService), infrastructure/repositories/identity.py (PlatformInviteRepository; InviteRepository.get/revoke), interfaces/http/routers/{invites,auth,organizations,admin_users}.py.

Frontend: packages/contracts/src/index.ts, apps/web/src/lib/{api.ts,api-org.ts}, apps/web/src/app/accept-invite/page.tsx, onboarding/page.tsx, (app)/admin/users/page.tsx, src/test/org-sharing.test.tsx, src/test/accept-invite.test.tsx (one assertion widened for the new argument).

Test output

apps/api:  520 passed, 1 skipped (was 502; +18)
           ruff check .  -> All checks passed!
           mypy app      -> Success: no issues found in 136 source files
alembic:   single head; upgrade / downgrade -1 / upgrade / check all clean
apps/web:  83 passed (was 78; +5)
           tsc --noEmit  -> clean · next lint -> no warnings

Deviations from the TODO

1. Org-invite revocation is expiry, not a flag. db/models.py is locked for this workstream and invites has no revoked_at. Semantically honest and strictly safer: it cannot un-accept a member.
2. The migration chains after the delivery workstream's head (a3b4c5d6e7f4) rather than the foundation. The two workstreams are being built sequentially here, so this keeps one head rather than introducing a merge revision that §8.3 only asks for when genuinely parallel branches exist.
3. admin_users.py holds the platform-invite endpoints. The TODO names that file for them, and it already carries the router-level require_platform_owner dependency — adding a second owner-gated router would duplicate the guarantee rather than strengthen it.

Open questions / CHANGE REQUESTs

• deploy_target.py / repo_workspace.py field additions (from Phase 5) remain open: DeployTargetSpec would benefit from post_deploy_command and the org/project ids. Nothing is broken; they are passed as explicit arguments.
• MeResponse should carry the org role so the web can gate the production buttons client-side. Noted in the Phase 6 report as well.

Known limitations — 1.10 NOT DONE

(app)/settings has no "اشتراک‌گذاری سازمان" section. Phase 1's frontend is otherwise complete (1.7–1.9, 1.11); the settings section — members with a role selector, invite form, pending invites with revoke, transfer-ownership modal that requires typing the org slug, leave org — is not built. The endpoints it needs (transfer-ownership, leave, GET/DELETE /invites) are done and tested, so the remaining work is presentational. The same is true of the /tasks/[id]-style extra test named in 1.11 — src/test/org-sharing.test.tsx covers the invite screen instead, which is where the phase's risk actually is.