# 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, provider
  mode and BYOK 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:

```text
/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.

Each Organization chooses one model-provider credential mode:

- `BYOK`: an Organization OWNER/ADMIN supplies and manages that Organization's
  provider key and base URL in the org admin area;
- `PLATFORM_MANAGED`: a platform admin supplies and manages one distinct key
  and base URL for that Organization in the platform admin area. Organization
  users cannot read the plaintext credential.

Provider connections remain Organization-scoped in both modes. Unrelated
Organizations never share a process-global provider key. Provider secrets must
be encrypted at rest and resolved at runtime through the same connection/secret
boundary as Feishu credentials.

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 for both provider
modes. It is not payment collection in the pilot: BYOK spend belongs to the
customer's provider account, while platform-managed spend is attributed to the
Organization for operational reporting; commercial billing remains deferred.

## 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-mode panels and the platform-managed connection panel
  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 platform admin identity, session, bootstrap, invitation, audit, and
  offline recovery boundary is decided by ADR-0023 and must be implemented
  before exposing the platform admin panel.