chore: add c4 spec

2026-06-06 19:22:58 +08:00
commit ca9f1242f8
11 changed files with 2490 additions and 0 deletions
@@ -0,0 +1,54 @@
+# 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:
+
+```text
+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.