Fix and complete the administrator roles documentation

[christophdb]

Problem

The list of standard administrator roles named custom admin as the fourth preconfigured role. That role does not exist.

The fourth role is system_admin, displayed as "System admin" in the role dropdown of the Users' section. custom_admin is neither a constant in seahub/constants.py nor a key in DEFAULT_ENABLED_ADMIN_ROLE_PERMISSIONS. The only occurrence of that string anywhere in dtable-web is the local variable custom_admin_role_permissions, which holds the custom roles from dtable_web_settings.py — the opposite of a preconfigured role. The sentence "They can be used […] without prior configuration" therefore contradicted itself.

While verifying this against seahub/role_permissions/settings.py, several further deviations turned up.

Changes

Standard roles. All four are now named by their configuration key (default_admin, system_admin, daily_admin, audit_admin), with their actual definitions as a copy-and-paste codeblock — the same treatment the standard user roles already get.

Permissions table, 10 → 19 rows.

• can_manage_user_log and can_manage_audit_log never existed (code search: 0 hits). They are can_view_user_log and can_view_audit_log.
• Added: can_update_user, can_manage_library, can_manage_base, can_manage_app, can_manage_form, can_update_organization, can_manage_sys_notification, can_manage_plugin, other_permission.
• can_manage_organization was listed as 1.0; it arrived with seafileltd/dtable-web#1681 (2021-03-23) → 2.0.

Three behaviours that were undocumented and regularly cause confusion:

1. Administrator permissions default to False — the exact opposite of user permissions. Every admin role is merged onto the hidden dummy_admin role in which everything is False, so each wanted permission must be listed explicitly.
2. can_manage_base, can_manage_form, can_manage_sys_notification, can_manage_plugin and can_manage_library only guard API endpoints. The matching sidebar entries are gated by isDefaultAdmin, so "Bases", "Forms" etc. cannot be granted to any other role.
3. Only an administrator with the role default_admin may assign administrator roles (admin_role.py:178).

Display names. An info box explains that only the six standard roles have a translated label in role-status-utils.js; everything else falls through to return role. A custom role new_admin_role therefore appears verbatim — underscores included — in the dropdown. Since role keys are not validated beyond a membership check, picking Support as the key gives a clean label.

Enterprise flag. <!-- md:flag enterprise --> on both custom-role sections, where the is_pro check in settings.py silently discards ENABLED_ROLE_PERMISSIONS / ENABLED_ADMIN_ROLE_PERMISSIONS without a Pro license. Also noted that a custom user role inherits from default.

Note on the version numbers

The older permissions could not be dated from a release list — changelog pages below 3.5 are no longer public. They were interpolated from the commit dates against the calibration points already present in the table (2021-03-25 → 2.0, 2021-06-18 → 2.2) and the published release dates:

Permission	Commit	→ Version
can_update_user	2020-12-16, immediately before "1.6.0 sql" (#1485)	1.6
can_manage_base / _form / _organization / _sys_notification / _plugin	2021-03-23 (#1681)	2.0
can_update_organization	2021-06-29 (#1943)	2.2
can_view_audit_log	2024-08-19 (#4992), between 5.0.7 and 5.1.9	5.1
other_permission	2024-11-21 (#5066), between 5.1.9 and 5.2.7	5.2
can_manage_app	2025-04-08 (#5381), between 5.2.7 and 5.3.10	5.3

1.6 and the 2.0 group are inferred, not sourced. Worth a second look if an internal version/date list for 1.x and 2.x exists.

Testing

• python3 tests/validate_docs.py --strict → 0 errors (3 warnings, all in unrelated files)
• mkdocs build --strict → builds clean; both admonitions and the Enterprise badges render

🤖 Generated with Claude Code

https://claude.ai/code/session_01DSukUw96UPeEwjXPAEQbzJ