ADR 0021: Org Admin Project Onboarding

Status

Accepted.

Context

ADR-0020 introduced Organization as the SaaS tenant root. The next product surface is not only the Feishu bot trigger path, but also the control planes around it:

platform staff need a private platform admin area to create and operate orgs;
customer org owners/admins need an org admin area for teams, roles, model provider configuration, projects, folders, sessions, and usage accounting;
ordinary teachers should be able to start work from the natural Feishu group flow without entering the web backend.

Without a crisp project onboarding model, project creation, Feishu chat binding, permissions, session history, and usage accounting would drift into separate ad-hoc rules.

Decision

Use one web app with two separate admin areas:

/admin/platform       internal platform admins only
/admin/org/:orgSlug   customer org OWNER/ADMIN only

The guards are intentionally separate:

requirePlatformAdmin for internal operators;
requireOrgRole for org owner/admin backend access;
requireProjectPermission for project-level actions.

Platform admin is not an OrganizationMembership and is not represented by project PermissionGrant. Platform admin audit remains separate from customer project audit.

Customer orgs are manually created by platform staff for the pilot. Platform admins invite/allowlist other platform admins. Customer users authenticate with the customer's Feishu app. The same customer-owned Feishu app may be used for OAuth login, bot messages, and directory sync. App secrets are org-scoped secrets and must be encrypted at rest; business code should access them through a secret/connection resolver, not raw plaintext columns.

Project management has two creation paths:

org owner/admin creates projects in the org web backend;
ordinary org members may create a project from an unbound Feishu group when membersCanCreateProjects is enabled for the org.

In both paths the creator gets project MANAGE. A Feishu-created project is immediately bound to the source chat, and that chat receives project EDIT.

Feishu chat binding is strict 1:1:

one Feishu chat binds to at most one active project;
one project binds to at most one Feishu chat;
binding an existing unbound project from Feishu requires the clicking user to have MANAGE on that project;
binding creates an active FEISHU_CHAT -> PROJECT EDIT grant;
binding mistakes are corrected by org owner/admin unbinding or archiving the binding in the backend; historical sessions stay on their original project.

Folders are transparent organization nodes for project navigation and usage aggregation:

folders belong to one organization;
projects may sit in folders;
folders can be nested;
folders are not permission resources;
folder visibility, team policies, and inherited grants are deferred.

Project permissions remain on PROJECT resources. Moving a project between folders does not change grants.

Usage accounting is org-wise and project/folder aggregatable. It is not payment collection in the pilot because customers supply their own model provider API keys and base URLs.

Consequences

OrganizationProjectSettings.membersCanCreateProjects gates Feishu group project creation for ordinary members.
Folder and Project.folderId support the file-manager-like project explorer without creating a second ACL system.
Service code should expose project creation and chat binding as reusable backend operations so Feishu cards and future web APIs call the same rules.
Org role/model/provider/billing panels can be added on top of the org tenant root without changing project authorization.

Open Questions / Deferred

True one-click Feishu app provisioning is deferred; pilot uses guided setup and readiness checks.
Folder-level permissions are deferred until there is a concrete customer need.
Self-serve org signup and payment collection are deferred beyond pilot.
The exact platform admin identity store and audit schema are separate from this ADR and should be modeled before exposing the platform admin panel.

4.1 KiB Raw Blame History