Extract Knowledge Base into a plugin (reference non-asset plugin)

First feature extracted from core into a plugin per "plugin is the product",
mirroring the notifications plugin. KB is a NON-asset plugin: it contributes a
model + blueprint + nav item but registers no AssetType.

- plugins/knowledgebase/: manifest.json (api_prefix /api/knowledgebase, no deps),
  models/ (KnowledgeBase, contract-pure imports via shopdb.api), api/ (the
  blueprint, same routes/prefix so the frontend is unchanged), plugin.py
  (get_blueprint + get_models + get_navigation_items).
- De-cored: removed shopdb/core/models/knowledgebase.py + api/knowledgebase.py,
  their __init__ exports, and 'knowledgebase' from CORE_BLUEPRINT_NAMES; dropped
  the hardcoded KB nav item from dashboard.py (now via the plugin nav hook).
- search.py and reports.py lazy-import KnowledgeBase from the plugin and degrade
  gracefully (search skips via _require_enabled when disabled; kb-popularity
  report returns 503 if the plugin is absent).
- Registered in instance/plugins.json (enabled).

The knowledgebase table stays in the core Alembic chain (bundled-plugin schema
folded into core, ADR-004); the model just maps it. KB was never in the
shopdb.api contract surface, so no __contract_version__ bump.

Pinned with characterization tests first (test_knowledgebase.py); they pass
unchanged against the plugin blueprint. 163 tests pass, naming green, app boots
7 bundled plugins, KB endpoint/nav/search verified live.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

plugins/knowledgebase/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin package."""
+
+from .plugin import KnowledgeBasePlugin
+
+__all__ = ['KnowledgeBasePlugin']

plugins/knowledgebase/api/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin API."""
+
+from .routes import knowledgebase_bp
+
+__all__ = ['knowledgebase_bp']

plugins/knowledgebase/api/routes.py

@@ -0,0 +1,210 @@
+"""Knowledge Base API endpoints."""
+
+from flask import Blueprint, request
+from flask_jwt_extended import jwt_required
+
+from shopdb.api import (
+    db,
+    Application,
+    success_response,
+    error_response,
+    paginated_response,
+    ErrorCodes,
+    get_pagination_params,
+    paginate_query,
+)
+
+from ..models import KnowledgeBase
+
+knowledgebase_bp = Blueprint('knowledgebase', __name__)
+
+
+@knowledgebase_bp.route('', methods=['GET'])
+@jwt_required(optional=True)
+def list_articles():
+    """List all knowledge base articles."""
+    page, per_page = get_pagination_params(request)
+
+    query = KnowledgeBase.query.filter_by(isactive=True)
+
+    # Search
+    if search := request.args.get('search'):
+        query = query.filter(
+            db.or_(
+                KnowledgeBase.shortdescription.ilike(f'%{search}%'),
+                KnowledgeBase.keywords.ilike(f'%{search}%')
+            )
+        )
+
+    # Filter by topic/application
+    if appid := request.args.get('appid'):
+        query = query.filter(KnowledgeBase.appid == int(appid))
+
+    # Sort options
+    sort = request.args.get('sort', 'clicks')
+    order = request.args.get('order', 'desc')
+
+    if sort == 'clicks':
+        query = query.order_by(
+            KnowledgeBase.clicks.desc() if order == 'desc' else KnowledgeBase.clicks.asc(),
+            KnowledgeBase.lastupdated.desc()
+        )
+    elif sort == 'topic':
+        query = query.join(Application).order_by(
+            Application.appname.desc() if order == 'desc' else Application.appname.asc()
+        )
+    elif sort == 'description':
+        query = query.order_by(
+            KnowledgeBase.shortdescription.desc() if order == 'desc' else KnowledgeBase.shortdescription.asc()
+        )
+    elif sort == 'lastupdated':
+        query = query.order_by(
+            KnowledgeBase.lastupdated.desc() if order == 'desc' else KnowledgeBase.lastupdated.asc()
+        )
+    else:
+        query = query.order_by(KnowledgeBase.clicks.desc())
+
+    items, total = paginate_query(query, page, per_page)
+    data = []
+    for article in items:
+        article_dict = article.to_dict()
+        if article.application:
+            article_dict['application'] = {
+                'appid': article.application.appid,
+                'appname': article.application.appname
+            }
+        else:
+            article_dict['application'] = None
+        data.append(article_dict)
+
+    return paginated_response(data, page, per_page, total)
+
+
+@knowledgebase_bp.route('/stats', methods=['GET'])
+@jwt_required(optional=True)
+def get_stats():
+    """Get knowledge base statistics."""
+    total_clicks = db.session.query(
+        db.func.coalesce(db.func.sum(KnowledgeBase.clicks), 0)
+    ).filter(KnowledgeBase.isactive == True).scalar()
+
+    total_articles = KnowledgeBase.query.filter_by(isactive=True).count()
+
+    return success_response({
+        'totalclicks': int(total_clicks),
+        'totalarticles': total_articles
+    })
+
+
+@knowledgebase_bp.route('/<int:link_id>', methods=['GET'])
+@jwt_required(optional=True)
+def get_article(link_id: int):
+    """Get a single knowledge base article."""
+    article = KnowledgeBase.query.get(link_id)
+
+    if not article or not article.isactive:
+        return error_response(ErrorCodes.NOT_FOUND, 'Article not found', http_code=404)
+
+    data = article.to_dict()
+    if article.application:
+        data['application'] = {
+            'appid': article.application.appid,
+            'appname': article.application.appname
+        }
+    else:
+        data['application'] = None
+
+    return success_response(data)
+
+
+@knowledgebase_bp.route('/<int:link_id>/click', methods=['POST'])
+@jwt_required(optional=True)
+def track_click(link_id: int):
+    """Increment click counter and return the URL to redirect to."""
+    article = KnowledgeBase.query.get(link_id)
+
+    if not article or not article.isactive:
+        return error_response(ErrorCodes.NOT_FOUND, 'Article not found', http_code=404)
+
+    article.increment_clicks()
+    db.session.commit()
+
+    return success_response({
+        'linkurl': article.linkurl,
+        'clicks': article.clicks
+    })
+
+
+@knowledgebase_bp.route('', methods=['POST'])
+@jwt_required()
+def create_article():
+    """Create a new knowledge base article."""
+    data = request.get_json()
+
+    if not data or not data.get('shortdescription'):
+        return error_response(ErrorCodes.VALIDATION_ERROR, 'shortdescription is required')
+
+    if not data.get('linkurl'):
+        return error_response(ErrorCodes.VALIDATION_ERROR, 'linkurl is required')
+
+    # Validate application if provided
+    if data.get('appid'):
+        app = Application.query.get(data['appid'])
+        if not app:
+            return error_response(ErrorCodes.NOT_FOUND, 'Application not found', http_code=404)
+
+    article = KnowledgeBase(
+        shortdescription=data['shortdescription'],
+        linkurl=data['linkurl'],
+        appid=data.get('appid'),
+        keywords=data.get('keywords'),
+        clicks=0
+    )
+
+    db.session.add(article)
+    db.session.commit()
+
+    return success_response(article.to_dict(), message='Article created', http_code=201)
+
+
+@knowledgebase_bp.route('/<int:link_id>', methods=['PUT'])
+@jwt_required()
+def update_article(link_id: int):
+    """Update a knowledge base article."""
+    article = KnowledgeBase.query.get(link_id)
+
+    if not article:
+        return error_response(ErrorCodes.NOT_FOUND, 'Article not found', http_code=404)
+
+    data = request.get_json()
+    if not data:
+        return error_response(ErrorCodes.VALIDATION_ERROR, 'No data provided')
+
+    # Validate application if being changed
+    if 'appid' in data and data['appid']:
+        app = Application.query.get(data['appid'])
+        if not app:
+            return error_response(ErrorCodes.NOT_FOUND, 'Application not found', http_code=404)
+
+    fields = ['shortdescription', 'linkurl', 'appid', 'keywords', 'isactive']
+    for key in fields:
+        if key in data:
+            setattr(article, key, data[key])
+
+    db.session.commit()
+    return success_response(article.to_dict(), message='Article updated')
+
+
+@knowledgebase_bp.route('/<int:link_id>', methods=['DELETE'])
+@jwt_required()
+def delete_article(link_id: int):
+    """Delete (deactivate) a knowledge base article."""
+    article = KnowledgeBase.query.get(link_id)
+
+    if not article:
+        return error_response(ErrorCodes.NOT_FOUND, 'Article not found', http_code=404)
+
+    article.isactive = False
+    db.session.commit()
+
+    return success_response(message='Article deleted')

plugins/knowledgebase/manifest.json

@@ -0,0 +1,12 @@
+{
+  "name": "knowledgebase",
+  "version": "1.0.0",
+  "description": "Knowledge Base articles linking to external resources",
+  "author": "ShopDB Team",
+  "dependencies": [],
+  "core_version": ">=0.1.0,<1.0.0",
+  "api_prefix": "/api/knowledgebase",
+  "provides": {
+    "features": ["knowledgebase"]
+  }
+}

plugins/knowledgebase/models/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin models."""
+
+from .knowledgebase import KnowledgeBase
+
+__all__ = ['KnowledgeBase']

plugins/knowledgebase/models/knowledgebase.py

@@ -0,0 +1,33 @@
+"""Knowledge Base model.
+
+Non-asset plugin model. The `knowledgebase` table lives in the core Alembic
+chain (bundled-plugin schema is folded into core, ADR-004); this class just
+maps it and is registered via the plugin's get_models hook. The appid FK
+references the core applications table by name, which resolves at mapper config
+time without importing the core model.
+"""
+
+from shopdb.api import db, BaseModel
+
+
+class KnowledgeBase(BaseModel):
+    """Knowledge Base article linking to external resources."""
+    __tablename__ = 'knowledgebase'
+
+    linkid = db.Column(db.Integer, primary_key=True)
+    appid = db.Column(db.Integer, db.ForeignKey('applications.appid'))
+    shortdescription = db.Column(db.String(500), nullable=False)
+    linkurl = db.Column(db.String(2000))
+    keywords = db.Column(db.String(500))
+    clicks = db.Column(db.Integer, default=0)
+    lastupdated = db.Column(db.DateTime, default=db.func.now(), onupdate=db.func.now())
+
+    # Relationship to the core Application model (resolved by class name).
+    application = db.relationship('Application', backref=db.backref('knowledgebase_articles', lazy='dynamic'))
+
+    def __repr__(self):
+        return f"<KnowledgeBase {self.linkid}: {self.shortdescription[:50] if self.shortdescription else 'No desc'}>"
+
+    def increment_clicks(self):
+        """Increment click counter."""
+        self.clicks = (self.clicks or 0) + 1

plugins/knowledgebase/plugin.py

@@ -0,0 +1,74 @@
+"""Knowledge Base plugin main class.
+
+Reference NON-asset plugin: contributes a model + blueprint + nav item but no
+AssetType (it is not an asset). Mirrors the notifications plugin.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import List, Dict, Optional, Type
+
+from flask import Flask, Blueprint
+
+from shopdb.plugins.base import BasePlugin, PluginMeta
+
+from .models import KnowledgeBase
+from .api import knowledgebase_bp
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeBasePlugin(BasePlugin):
+    """Knowledge Base plugin - articles linking to external resources."""
+
+    def __init__(self):
+        self._manifest = self._load_manifest()
+
+    def _load_manifest(self) -> Dict:
+        """Load plugin manifest from JSON file."""
+        manifest_path = Path(__file__).parent / 'manifest.json'
+        if manifest_path.exists():
+            with open(manifest_path, 'r') as f:
+                return json.load(f)
+        return {}
+
+    @property
+    def meta(self) -> PluginMeta:
+        """Return plugin metadata."""
+        return PluginMeta(
+            name=self._manifest.get('name', 'knowledgebase'),
+            version=self._manifest.get('version', '1.0.0'),
+            description=self._manifest.get(
+                'description',
+                'Knowledge Base articles linking to external resources'
+            ),
+            author=self._manifest.get('author', 'ShopDB Team'),
+            dependencies=self._manifest.get('dependencies', []),
+            core_version=self._manifest.get('core_version', '>=0.1.0,<1.0.0'),
+            api_prefix=self._manifest.get('api_prefix', '/api/knowledgebase'),
+        )
+
+    def get_blueprint(self) -> Optional[Blueprint]:
+        """Return Flask Blueprint with API routes."""
+        return knowledgebase_bp
+
+    def get_models(self) -> List[Type]:
+        """Return list of SQLAlchemy model classes."""
+        return [KnowledgeBase]
+
+    def init_app(self, app: Flask, db_instance) -> None:
+        """Initialize plugin with Flask app."""
+        logger.info(f"Knowledge Base plugin initialized (v{self.meta.version})")
+
+    def get_navigation_items(self) -> List[Dict]:
+        """Return navigation menu items."""
+        return [
+            {
+                'name': 'Knowledge Base',
+                'icon': 'book-open',
+                'route': '/knowledgebase',
+                'position': 35,
+                'section': 'information',
+            },
+        ]