planet/docs/technical/en/docs-gatekeeper-development.md

Docs Gatekeeper Development Guide

Docs Gatekeeper moves /docs from "bundle all Markdown into the frontend" to "return catalog and content from the backend according to permissions." Its goal is to keep public manuals, user docs, developer docs, and admin/ops docs in one searchable Docs page while making every protected Markdown body pass through a server-side whitelist and authorization check.

For the user workflow, see the Docs section in Planet Manual.

Authorization Model

Docs uses two permission layers:

• users.role: preserved for console/system permissions.
• users.gatekeeper_groups: Docs content permission groups.

Groups:

Group	Purpose
docs_user	User-operation docs
docs_developer	Earth, frontend, backend, collector, and AI Provider development docs
docs_admin	Service control, operations, environment, and sensitive-operation docs

Inheritance:

• Anonymous users can only read public.
• docs_developer includes docs_user.
• docs_admin includes docs_developer and docs_user.
• admin and super_admin receive all Docs permissions by default.

Backend Entry Points

Files:

• docs.py
• docs_gatekeeper.py
• user.py
• users.py

APIs:

GET /api/v1/docs/catalog
GET /api/v1/docs/{lang}/{slug}

catalog returns only documents visible to the current user. The content endpoint validates language, slug, and file existence through the metadata whitelist before checking access:

• Anonymous protected-doc request: 401.
• Authenticated but insufficient permissions: 403.
• Unknown language, unknown slug, or missing file: 404.

Markdown bodies can only come from whitelisted files under docs/technical/{zh,en}/; arbitrary path reads are not allowed.

Metadata Source

Server-side metadata lives in docs_gatekeeper.py:

DocsMetadata(
    "manual.md",
    "manual",
    "public",
    "Manual",
    2,
    "Planet 使用手册",
    "Planet Manual",
)

When adding a public technical doc:

• Add both Chinese and English Markdown files.
• Add filename, slug, access, group, order, and titles to server DOCS_METADATA.
• Add matching metadata to frontend docs-content.ts so navigation titles and sorting stay aligned.
• Update docs/technical/zh/README.md and docs/technical/en/README.md when the document should be discoverable from the README.

User Management

The users table has gatekeeper_groups JSONB DEFAULT '[]'. Startup session.py applies ALTER TABLE ... ADD COLUMN IF NOT EXISTS for existing local databases.

The user API:

• Writes gatekeeper_groups during user creation.
• Validates group names on update: only docs_user, docs_developer, and docs_admin are accepted.
• Allows only super_admin to modify Gatekeeper groups.

Frontend Users.tsx displays group tags and provides a multi-select in the edit form. Non-super_admin users see the field disabled, and submission removes gatekeeper_groups before sending.

Frontend Docs Loading

Files:

• Docs.tsx
• docs-content.ts
• docs-search.ts

Key changes:

• Remove import.meta.glob(...?raw) as the Markdown content source.
• Load /api/v1/docs/catalog to build the visible navigation.
• Load /api/v1/docs/{lang}/{slug} for document bodies.
• Index search only across currently visible docs, loading Markdown from the backend as needed.
• Show login state for 401, permission state for 403, and unavailable-doc state for 404.

Test Coverage

Relevant tests:

• test_docs_gatekeeper.py

Tests should cover:

• Anonymous users only see public docs.
• Protected content returns 401 or 403 appropriately.
• docs_developer can read developer docs but not admin docs.
• admin and super_admin can read admin docs.
• Unknown slugs, unknown languages, and path traversal strings cannot read files.