Phiên bản: 1.0

Tạo Space & quản thành viên — dành cho Space Owner

Đối tượng: chủ dự án — người mở Space, gắn repo, mời team, cấp cứu khi mất quyền admin. Role kỹ thuật: Board owner (rank cao nhất). Người tạo Space tự thành owner. Nguyên tắc gán quyền: cấp tối thiểu đủ dùng — viewer (xem) · member (làm) · admin (duyệt) · owner (chỉ chủ dự án).

Công cụ bạn dùng

Công cụ	Bạn làm gì
Trang Projects → New Project / Edit / Delete	Tạo Space, sửa cấu hình, xoá Space
`GET /api/spaces/<spaceId>/members` + `POST/DELETE`	Xem, thêm/đổi role, xoá thành viên
Biến `AGENTBOARD_BOOTSTRAP_OWNERS` trên server + restart	Khởi tạo lần đầu và break-glass khi mất hết admin
Board / Tree / Review View	Giám sát chung (đọc như viewer, duyệt như admin khi cần)

Lần đầu khởi tạo quyền quản trị

Áp dụng ngay sau deploy đầu tiên, khi DB mới hoàn toàn và phân quyền fail-closed (chưa ai có quyền gì). Chi tiết từng bước: Bài 1 — Lần đầu đăng nhập.

Mở URL production, qua SSO. Danh sách Space trống, mọi hành động 403 — đúng thiết kế.
Trên server (/opt/agentjira/.env): AGENTBOARD_BOOTSTRAP_OWNERS=lead@yourcompany.com → restart agentjira_server → xác nhận log [rbac] applied 1 bootstrap owner grant(s).
Refresh UI → bạn là owner mọi Space hiện có.

Lệnh grant idempotent — vừa là đường khởi tạo lần đầu, vừa là đường break-glass khi mất hết admin.

Môi trường dev

DEV-LITE không cần bước này (AGENTBOARD_DEV_IDENTITY=1 cho mọi request làm owner). DEV FULL-STACK chạy y production (DEV_USER_EMAIL đưa vào bootstrap).

Tạo Space mới — provisioning nguyên tử 2-phase

New Project, điền:
- name; repoPath (đường dẫn tuyệt đối tới repo git) hoặc repoUrl (server tự clone vào cloneRoot);
- defaultAgentType, defaultBaseBranch (thường main);
- defaultUseWorktree — bật (khuyến nghị mạnh);
- requireHumanGate — bật để cưỡng chế chốt người;
- mergeStrategy — xem 3 tab dưới.
Submit → server provisioning nguyên tử: transaction DB → tạo Department bên Arkon → sinh Wiki Home → tạo đúng 5 persona (@architect/@coder/@reviewer/@qa/@devops) + mint MCP token (mã hoá at-rest) → cấp bạn làm owner → commit.
Nếu Arkon lỗi giữa đường: transaction rollback sạch + xoá Department dở dang — không rác. Nếu Arkon không cấu hình: Space vẫn tạo thành công, chỉ ghi Activity cảnh báo, tab Wiki trống (suy biến mềm).
Xác minh: Board mới có 2 tab Board + Wiki; bên Arkon :3119 → Departments thấy tên Space với trang Home.

Ba chiến lược hợp nhất (`mergeStrategy`)

merge-local
create-pr
manual

Chiếm mutex withRepoLock → git merge --no-ff nhánh agent vào baseBranch → task done. Mặc định — dùng khi repo và server cùng host.

Push nhánh lên origin, tạo Pull Request → task done. Repo local không bị chạm. Dùng khi quy trình PR bắt buộc, cần review thêm bên GitHub.

Chỉ đánh dấu done. Bạn tự merge. Dùng cho repo đặc biệt, cần kiểm soát tay hoàn toàn.

Quyết định lúc tạo, đổi sau cần cân nhắc — ghi lại mergeStrategy + requireHumanGate

của từng Space và lý do chọn.

Mời thành viên & phân quyền

Người	Role	Vì sao
PO, Stakeholder	`viewer`	Xem tiến độ, không tạo/sửa
Developer	`member`	Tạo task, chạy agent, apply plan — nhưng không approve
Tech Lead, Reviewer	`admin`	Được approve & merge (Human Gate)
Chủ dự án	`owner`	Sửa cấu hình Space, quản lý thành viên

# Xem danh sách
curl http://<host>/api/spaces/<spaceId>/members

# Thêm / đổi role
curl -X POST http://<host>/api/spaces/<spaceId>/members \
  -H 'Content-Type: application/json' \
  -d '{"email":"dev1@corp.com","role":"member"}'

# Xoá
curl -X DELETE http://<host>/api/spaces/<spaceId>/members/dev1@corp.com

Người được cấp refresh trang là thấy Space. Không xoá được owner cuối cùng (409) — chống tự khoá mình: cấp owner cho người khác trước rồi mới xoá.

Việc bạn phải nhờ sysadmin

Việc	Vì sao
Deploy, secret, Cloudflare JWT, backup/restore, incident infra	ngoài phạm vi Space — xem Vận hành
Cấp API key LLM/Embedding, đổi model embedding, re-index	Arkon admin — xem Model Catalog
Bypass Human Gate cho 1 task gấp	không ai làm được — hoặc tắt `requireHumanGate` ở cấp Space (quyết định của bạn, ghi nhận rủi ro), hoặc chờ admin human approve
Kiểm thử RBAC trên DEV-LITE	không thể — DEV-LITE bypass mọi request thành `owner`; dùng DEV FULL-STACK

Checklist tự xác minh

Bootstrap owner hoạt động, log [rbac] applied xuất hiện sau restart.
Tạo 1 Space mẫu: provisioning thành công, 5 persona đầy đủ, Wiki Home tồn tại bên Arkon.
Mời 1 viewer + 1 member + 1 admin: viewer Approve 403; member tạo/chạy được nhưng approve 403; admin approve được.
Xoá owner cuối cùng → 409 đúng kỳ vọng.

Công cụ bạn dùng​

Lần đầu khởi tạo quyền quản trị​

Tạo Space mới — provisioning nguyên tử 2-phase​

Ba chiến lược hợp nhất (mergeStrategy)​

Mời thành viên & phân quyền​

Việc bạn phải nhờ sysadmin​

Checklist tự xác minh​