forked from EduCraft/curriculum-project-hub
103 lines
4.1 KiB
Markdown
103 lines
4.1 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, 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:
|
|
|
|
```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.
|
|
|
|
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.
|