From d20682fd0620e12dfb801cb5f9e2754ee2746b97 Mon Sep 17 00:00:00 2001 From: cproudlock Date: Fri, 26 Jun 2026 21:13:15 -0400 Subject: [PATCH] Extract employee directory into a plugin Third core feature pulled into a plugin (blueprint-only, like slides). The employee directory is a read-only lookup over a separate HR database. - plugins/employees/: manifest (api_prefix /api/employees, no deps), api/ (moved blueprint, contract-pure: success/error/ErrorCodes + employee_connection all from shopdb.api), plugin.py (get_blueprint, get_models -> []). - employee_connection STAYS core infrastructure in shopdb.api (config-driven external DB connector, shared by search + the notifications shopfloor feed). So no get_services needed and no contract change - the plugin owns the directory FEATURE, core owns the shared connector. - Fixed a latent bug in the move: error paths used ErrorCodes.DATABASE_ERROR which does not exist -> ErrorCodes.INTERNAL_ERROR (so a directory outage now returns a clean 500 envelope instead of an AttributeError crash). - De-cored: deleted shopdb/core/api/employees.py, removed from CORE_BLUEPRINT_NAMES + core/api/__init__ import/__all__. Registered in instance/plugins.json. Pinned first: validation (400) + graceful-degrade (500) characterization tests; the degrade test caught the DATABASE_ERROR bug and goes green with the fix. 184 tests pass, naming green, app boots 9 bundled plugins, endpoint verified live. Plugin extractions complete: knowledgebase, slides, employees. Co-Authored-By: Claude Opus 4.8 --- plugins/employees/__init__.py | 5 ++ plugins/employees/api/__init__.py | 5 ++ .../employees/api/routes.py | 24 ++++--- plugins/employees/manifest.json | 12 ++++ plugins/employees/plugin.py | 63 +++++++++++++++++++ shopdb/__init__.py | 1 - shopdb/core/api/__init__.py | 2 - tests/test_core/test_employees.py | 26 ++++++++ tests/test_plugin_contract.py | 2 +- tests/test_smoke.py | 1 + 10 files changed, 128 insertions(+), 13 deletions(-) create mode 100644 plugins/employees/__init__.py create mode 100644 plugins/employees/api/__init__.py rename shopdb/core/api/employees.py => plugins/employees/api/routes.py (86%) create mode 100644 plugins/employees/manifest.json create mode 100644 plugins/employees/plugin.py create mode 100644 tests/test_core/test_employees.py diff --git a/plugins/employees/__init__.py b/plugins/employees/__init__.py new file mode 100644 index 0000000..b2ff675 --- /dev/null +++ b/plugins/employees/__init__.py @@ -0,0 +1,5 @@ +"""Employees plugin package.""" + +from .plugin import EmployeesPlugin + +__all__ = ['EmployeesPlugin'] diff --git a/plugins/employees/api/__init__.py b/plugins/employees/api/__init__.py new file mode 100644 index 0000000..50aefcc --- /dev/null +++ b/plugins/employees/api/__init__.py @@ -0,0 +1,5 @@ +"""Employees plugin API.""" + +from .routes import employees_bp + +__all__ = ['employees_bp'] diff --git a/shopdb/core/api/employees.py b/plugins/employees/api/routes.py similarity index 86% rename from shopdb/core/api/employees.py rename to plugins/employees/api/routes.py index 5624655..d013c0c 100644 --- a/shopdb/core/api/employees.py +++ b/plugins/employees/api/routes.py @@ -1,16 +1,22 @@ """Employee lookup API endpoints. -These read from the separate employee directory DB (see shopdb.utils.employee_db). -They are intentionally reachable by the unauthenticated shopfloor kiosk displays -(recognition wall), so they are not JWT-gated; keep them read-only and never -return more than the directory fields below. +These read from the separate employee directory DB (employee_connection is core +infrastructure exposed via shopdb.api, shared with search + notifications). The +endpoints are intentionally reachable by the unauthenticated shopfloor kiosk +displays (recognition wall), so they are not JWT-gated; keep them read-only and +never return more than the directory fields below. """ import logging from flask import Blueprint, request -from shopdb.utils.responses import success_response, error_response, ErrorCodes -from shopdb.utils.employee_db import employee_connection + +from shopdb.api import ( + success_response, + error_response, + ErrorCodes, + employee_connection, +) logger = logging.getLogger(__name__) @@ -56,7 +62,7 @@ def search_employees(): except Exception: logger.exception('Employee search failed') return error_response( - ErrorCodes.DATABASE_ERROR, + ErrorCodes.INTERNAL_ERROR, 'Employee lookup failed', http_code=500 ) @@ -92,7 +98,7 @@ def lookup_employee(sso): except Exception: logger.exception('Employee lookup failed for SSO %s', sso) return error_response( - ErrorCodes.DATABASE_ERROR, + ErrorCodes.INTERNAL_ERROR, 'Employee lookup failed', http_code=500 ) @@ -138,7 +144,7 @@ def lookup_employees(): except Exception: logger.exception('Employee multi-lookup failed') return error_response( - ErrorCodes.DATABASE_ERROR, + ErrorCodes.INTERNAL_ERROR, 'Employee lookup failed', http_code=500 ) diff --git a/plugins/employees/manifest.json b/plugins/employees/manifest.json new file mode 100644 index 0000000..ea0fda2 --- /dev/null +++ b/plugins/employees/manifest.json @@ -0,0 +1,12 @@ +{ + "name": "employees", + "version": "1.0.0", + "description": "Read-only employee directory lookup (separate HR database)", + "author": "ShopDB Team", + "dependencies": [], + "core_version": ">=0.1.0,<1.0.0", + "api_prefix": "/api/employees", + "provides": { + "features": ["employee_directory"] + } +} diff --git a/plugins/employees/plugin.py b/plugins/employees/plugin.py new file mode 100644 index 0000000..4e9e689 --- /dev/null +++ b/plugins/employees/plugin.py @@ -0,0 +1,63 @@ +"""Employees plugin main class. + +Blueprint-only plugin: a read-only employee directory lookup over a separate HR +database. No model (the directory is an external DB) and no AssetType. The +connection helper (employee_connection) stays core infrastructure in shopdb.api, +shared with search and the notifications shopfloor feed. +""" + +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 .api import employees_bp + +logger = logging.getLogger(__name__) + + +class EmployeesPlugin(BasePlugin): + """Employees plugin - read-only HR directory lookup.""" + + 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', 'employees'), + version=self._manifest.get('version', '1.0.0'), + description=self._manifest.get( + 'description', + 'Read-only employee directory lookup' + ), + 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/employees'), + ) + + def get_blueprint(self) -> Optional[Blueprint]: + """Return Flask Blueprint with API routes.""" + return employees_bp + + def get_models(self) -> List[Type]: + """No models - the directory is an external database.""" + return [] + + def init_app(self, app: Flask, db_instance) -> None: + """Initialize plugin with Flask app.""" + logger.info(f"Employees plugin initialized (v{self.meta.version})") diff --git a/shopdb/__init__.py b/shopdb/__init__.py index cd4a803..5ba5399 100644 --- a/shopdb/__init__.py +++ b/shopdb/__init__.py @@ -105,7 +105,6 @@ CORE_BLUEPRINT_NAMES = ( 'search', 'reports', 'collector', - 'employees', 'settings', 'auditlogs', 'users', diff --git a/shopdb/core/api/__init__.py b/shopdb/core/api/__init__.py index 97b049d..53a7b00 100644 --- a/shopdb/core/api/__init__.py +++ b/shopdb/core/api/__init__.py @@ -14,7 +14,6 @@ from .applications import applications_bp from .search import search_bp from .reports import reports_bp from .collector import collector_bp -from .employees import employees_bp from .settings import settings_bp from .auditlogs import auditlogs_bp from .users import users_bp @@ -34,7 +33,6 @@ __all__ = [ 'search_bp', 'reports_bp', 'collector_bp', - 'employees_bp', 'settings_bp', 'auditlogs_bp', 'users_bp', diff --git a/tests/test_core/test_employees.py b/tests/test_core/test_employees.py new file mode 100644 index 0000000..aacb64a --- /dev/null +++ b/tests/test_core/test_employees.py @@ -0,0 +1,26 @@ +"""Characterization tests for the employee directory endpoints. + +Written before extracting employees into a plugin. The wjf_employees DB is not +available under test, so these assert the DB-independent behaviors: validation +(400) and graceful failure (500 envelope, not an unhandled crash) when the +directory is unreachable. Behavior must be identical as a plugin blueprint. +""" + + +def test_search_requires_min_query(client, db): + """A too-short query is rejected before touching the directory DB.""" + resp = client.get('/api/employees/search?q=a') + assert resp.status_code == 400 + + +def test_lookup_requires_numeric_sso(client, db): + """Non-numeric SSO is rejected without touching the directory DB.""" + resp = client.get('/api/employees/lookup/abc') + assert resp.status_code == 400 + + +def test_search_degrades_when_directory_unreachable(client, db): + """With the directory DB unavailable, search returns a clean 500 envelope.""" + resp = client.get('/api/employees/search?q=smith') + assert resp.status_code == 500 + assert resp.get_json()['status'] == 'error' diff --git a/tests/test_plugin_contract.py b/tests/test_plugin_contract.py index 3b39101..2f6a2cf 100644 --- a/tests/test_plugin_contract.py +++ b/tests/test_plugin_contract.py @@ -17,7 +17,7 @@ from shopdb.plugins import plugin_manager from shopdb.plugins.base import BasePlugin, PluginMeta -BUNDLED_PLUGINS = ('computers', 'equipment', 'knowledgebase', 'network', 'notifications', 'printers', 'slides', 'usb') +BUNDLED_PLUGINS = ('computers', 'employees', 'equipment', 'knowledgebase', 'network', 'notifications', 'printers', 'slides', 'usb') @pytest.fixture diff --git a/tests/test_smoke.py b/tests/test_smoke.py index 6477f42..2ebb5c8 100644 --- a/tests/test_smoke.py +++ b/tests/test_smoke.py @@ -94,6 +94,7 @@ def test_plugin_loader_discovers_bundled_plugins(app): expected_plugins = { 'computers', + 'employees', 'equipment', 'knowledgebase', 'network',