forked from EduCraft/curriculum-project-hub
118 lines
5.0 KiB
Markdown
118 lines
5.0 KiB
Markdown
# 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.
|