curriculum-project-hub/docs/architecture/adr/0004-feishu-docs-like-permissions.md

ADR 0004: Use Feishu Docs-like Permission Grants

Status

Proposed.

Context

Project collaboration needs more nuance than a hard-coded owner / teacher / admin model. Teachers may need to view a project, discuss it, trigger Claude, edit artifacts, manage members, or handle exceptional cancellation. These are related but not identical privileges.

Feishu cloud docs separates collaborators from operation settings:

• collaborators can be users, groups, departments, user groups, apps, or wiki members;
• collaborator roles are read, edit, or manage;
• settings separately control sharing outside the organization, copying/downloading, commenting, and collaborator management.

That split maps well to Curriculum Project Hub.

Decision

Model project permissions as:

PermissionGrant
- resource_type: project | artifact | project_group
- resource_id
- principal_type: user | feishu_chat | department | user_group | app
- principal_id
- role: read | edit | manage

PermissionSettings
- resource_type
- resource_id
- external_share_policy
- comment_policy
- copy_download_policy
- collaborator_management_policy
- agent_trigger_policy
- agent_cancel_policy

Use role-derived capabilities for ordinary actions, and settings for policy knobs:

• read: view project, artifacts, run history and project group metadata.
• edit: read plus discuss, comment, edit artifacts, trigger Claude runs and answer Claude choice cards.
• manage: edit plus manage collaborators, project settings, group binding and normal run cancellation policy.
• admin-only override: force release stuck locks and perform exceptional audit operations.

Consequences

• We can grant access to a teacher, a whole Feishu project group, a department, or a custom user group using the same model.
• Claude invocation is explicit policy, not just "anyone in the group can run it" forever.
• "Who can cancel current processing" can be different from "who can force release a stuck lock".
• The model stays close to Feishu users' expectations without copying every Feishu-specific API detail.