leocrm/.a0/briefings/T11_briefing.md

T11 Briefing — Tags Plugin + Permissions Plugin + Entity Links Backend

Project Root

/a0/usr/workdir/dev-projects/leocrm

Task

Implement 3 builtin plugins: Tags, Permissions, Entity Links.

Plugin Framework (existing — read these files first)

• app/plugins/base.py — BasePlugin abstract class with lifecycle hooks
• app/plugins/manifest.py — PluginManifest, PluginRouteDef schemas
• app/plugins/registry.py — PluginRegistry (discovers builtins, manages lifecycle)
• app/plugins/builtins/test_sample.py — Example plugin (reference pattern)
• app/plugins/builtins/migrations/ — Migration SQL files go here
• app/core/event_bus.py — EventBus for pub/sub
• app/core/service_container.py — DI container
• app/core/db.py — Base, TenantMixin, TimestampMixin
• app/models/company.py — Company model (reference for model patterns)
• app/models/plugin.py — Plugin + PluginMigration models

Architecture Rules

• Plugins live in app/plugins/builtins/ as subdirectories (e.g. app/plugins/builtins/tags/)
• Each plugin has: __init__.py (exports plugin class), plugin.py (BasePlugin subclass), routes.py (APIRouter), models.py (SQLAlchemy models), schemas.py (Pydantic schemas), migrations/ (SQL files)
• Migrations are plain SQL files in app/plugins/builtins/<plugin>/migrations/
• Models use SQLAlchemy 2.0 style (Mapped, mapped_column) with PGUUID, TenantMixin
• Routes use FastAPI APIRouter, registered via manifest routes list
• Events: subscribe in on_activate, handlers named on_<event_name>

1. Tags Plugin (app/plugins/builtins/tags/)

Requirements (F-TAG-01 through F-TAG-04)

• Tags can be applied to files, folders, companies, contacts
• Tags are global (not per-user), centrally managed
• Multiple tags per entity (N:M)
• Tag CRUD with color support
• Tag filtering in lists (AND/OR combination)
• Tag cloud/sidebar with entity counts

Endpoints

GET    /api/v1/tags              → 200, list tags with entity counts
POST   /api/v1/tags              → 201, create tag (name, color)
PATCH  /api/v1/tags/{id}          → 200, update tag
DELETE /api/v1/tags/{id}          → 204, cascade delete assignments
POST   /api/v1/tags/assign        → 200, assign tag to entity (tag_id, entity_type, entity_id)
DELETE /api/v1/tags/assign        → 204, remove tag assignment
POST   /api/v1/tags/bulk-assign   → 200, assign multiple tags to entity
GET    /api/v1/tags/{id}/entities → 200, list entities with this tag

Models

• Tag: id (UUID), name (str, unique per tenant), color (str, hex), tenant_id
• TagAssignment: id, tag_id (FK), entity_type (str: company/contact/file/folder), entity_id (UUID), tenant_id

Migration

• 0001_initial.sql: Create tags and tag_assignments tables with tenant_id columns

2. Permissions Plugin (app/plugins/builtins/permissions/)

Requirements (F-PERM-01 through F-PERM-06)

• Personal root folder per user ("Mein Bereich")
• Shared root folders for teams/departments
• Share files/folders with individual users (read/write)
• Share files/folders with user groups (read/write)
• Public share links (with password, expiry, download-only or preview+download)
• Permission display (who has access?)

Endpoints

GET    /api/v1/dms/files/{id}/permissions          → 200, permission list
POST   /api/v1/dms/files/{id}/permissions          → 201, grant permission
DELETE /api/v1/dms/files/{id}/permissions/{user_id} → 204, revoke
POST   /api/v1/dms/files/{id}/share-link           → 200, create share link (returns public token URL)
GET    /api/public/share/{token}                   → 200 (file) or 410 (expired)
DELETE /api/v1/dms/share-links/{id}                → 204, revoke share link

Models

• Permission: id, file_id (UUID), user_id (UUID), group_id (UUID nullable), access_level (read/write), tenant_id
• ShareLink: id, file_id (UUID), token (str, unique), password_hash (nullable), expires_at (nullable), access_level (download/preview), tenant_id

Migration

• 0001_initial.sql: Create permissions and share_links tables

Special

• Public share endpoint /api/public/share/{token} must NOT require auth
• Expired links return 410 Gone
• Password-protected links verify password before serving

3. Entity Links Backend (app/plugins/builtins/entity_links/)

Requirements (F-LINK-01 through F-LINK-06)

• Link files/folders to companies (N:M)
• Link files/folders to contacts (N:M)
• Reverse links (file shows linked entities)
• Multi-links (one file → many entities)
• Event cleanup: on company.deleted/contact.deleted → remove links

Endpoints

POST   /api/v1/dms/files/{id}/link    → 200, link file to entity (entity_type, entity_id)
DELETE /api/v1/dms/files/{id}/link    → 204, remove link (entity_type, entity_id in body)
GET    /api/v1/dms/files/{id}/links    → 200, list all linked entities for file
GET    /api/v1/companies/{id}/files   → 200, list linked files for company
GET    /api/v1/contacts/{id}/files    → 200, list linked files for contact

Models

• EntityLink: id, file_id (UUID), entity_type (str: company/contact), entity_id (UUID), tenant_id, created_by (UUID)

Migration

• 0001_initial.sql: Create entity_links table

Event Handling

• Subscribe to company.deleted → delete all EntityLink rows where entity_type='company' AND entity_id=deleted_id
• Subscribe to contact.deleted → delete all EntityLink rows where entity_type='contact' AND entity_id=deleted_id

Acceptance Criteria (14 total — ALL must pass)

1. GET /api/v1/dms/files/{id}/permissions → 200 + permission list
2. POST /api/v1/dms/files/{id}/link → 200, file linked to entity
3. DELETE /api/v1/dms/files/{id}/link → 204, link removed
4. POST /api/v1/dms/files/{id}/share-link → 200 + public token URL
5. GET /api/public/share/{token} with expired link → 410
6. GET /api/v1/tags → 200 + tags with counts
7. POST /api/v1/tags → 201, tag created
8. PATCH /api/v1/tags/{id} → 200
9. DELETE /api/v1/tags/{id} → 204, cascade delete assignments
10. POST /api/v1/tags/assign → 200, tag assigned to entity
11. DELETE /api/v1/tags/assign → 204, tag removed
12. POST /api/v1/tags/bulk-assign → 200, multiple tags assigned
13. DMS plugin listens to company.deleted event → linked files cleanup
14. Folder permissions enforced: user without read → 403

Test Files (create in tests/)

• tests/test_tags.py — Tag CRUD, assignment, bulk assign, cascade delete, counts
• tests/test_permissions.py — Personal root, shared root, share with users/groups, share links (password, expiry), permission display, 403 enforcement
• tests/test_entity_links.py — Link file to company, link to contact, reverse links, multi-links, event cleanup on deletion

Verification Commands

cd /a0/usr/workdir/dev-projects/leocrm
python -m pytest tests/test_tags.py tests/test_permissions.py tests/test_entity_links.py -v --tb=short
python -m pytest tests/test_tags.py tests/test_permissions.py tests/test_entity_links.py --cov=app/plugins/builtins --cov-report=term-missing

Rules

• Use text_editor:write for new files, text_editor:patch for updates
• Read existing files before modifying
• No Lorem Ipsum, no placeholder code
• Follow existing patterns (SQLAlchemy 2.0, Pydantic v2, FastAPI APIRouter)
• Each plugin must have manifest, plugin class, routes, models, schemas, migrations
• Register plugins in app/plugins/builtins/__init__.py
• Keep response under 50 lines
• Report: files created, test count + pass/fail, coverage %