Home Esplora Aiuto
Accedi
mxl_citu
/
DataOps-platform
1
0
Forka 0
File Problemi 0 Pull Requests 0 Wiki
Albero (Tree): 10e42a080d
Rami (Branch) Tag
DataOps-plat...
/
docs
/
superpowers
/
plans
/
2026-07-29-wp10-device-search-knowledge-qa.md

2026-07-29-wp10-device-search-knowledge-qa.md 10 KB
Cronologia Originale

WP10 Device Search and Knowledge Q&A Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Deliver authorized device search and evidence-grounded device Q&A by extending the existing canonical governance knowledge pipeline.

Architecture: PostgreSQL device assets, authorized source mappings, and operational events remain authoritative. A bounded device retriever joins the existing knowledge retrieval pipeline before fusion, filters source business-domain scope in SQL, and emits the same stable evidence contract used by lexical/vector retrieval. The existing answer synthesizer remains the only generative path; it must refuse or report model unavailability instead of fabricating. LightRAG remains shadow-only and is not activated by WP10.

Tech Stack: Flask, SQLAlchemy/PostgreSQL, existing knowledge retrieval and Q&A services, Vue 2/Vuetify, pytest, Node test runner.

Scope and constraints

  • Search platform UID, device name, authorized source ID, location, organization, responsible person, and related alarm/fault/maintenance/downtime records.
  • Derive device data range from each ingestion_sources.permission_scope.business_domains. An empty scope is admin-only; non-admin access is default-deny.
  • Apply authorization inside SQL before device candidates are returned, then retain the pipeline's post-fusion authorization check.
  • Return stable object UID, asset version, source time, point key/revision, source IDs, and related event evidence.
  • For Q&A, return only model-selected canonical citations. When the model is unavailable or evidence is insufficient, return no answer and still expose the authorized retrieval evidence for inspection.
  • Persist query audit evidence without storing raw questions, generated answers, secrets, or full retrieved content.
  • Provide an admin-only source-scope configuration path and query-audit view.
  • Do not add NL2SQL, online analysis, BI development, predictive maintenance, automatic repair, generic web search, or direct LightRAG answers.
  • Do not claim enterprise acceptance until a real source scope, device corpus, answer model, and golden set have been validated.

Task 1: Device evidence contract and deterministic query behavior

Files:

  • Create: app/core/knowledge/retrieval/device.py
  • Create: tests/knowledge/test_device_retrieval.py
  • Modify: app/core/knowledge/retrieval/pipeline.py

  • Modify: tests/knowledge/test_retrieval.py

  • [x] Write failing tests that define query normalization, maximum length, deterministic device scoring, stable point keys, safe readable content, and source/event evidence boundaries.

  • [x] Write a failing pipeline test proving device evidence participates in fusion and is still removed when its business domain is outside the access context.

  • [x] Run only the two tests and confirm failure is caused by the absent device retriever integration.

  • [x] Implement SqlDeviceKnowledgeRetriever with a 300-character query boundary, a maximum 100 results, SQL-pre-filtered business-domain authorization, and deterministic ranking.

  • [x] Aggregate only authorized source codes and authorized alarm/fault/maintenance/downtime titles; do not include event evidence JSON or source configuration.

  • [x] Emit KnowledgeEvidence with object_type="DeviceAsset", object_version=current_version, one stable summary point, source time, and the authorized business-domain UID.

  • [x] Add the optional device retriever to KnowledgeRetrievalPipeline; include it in standard search modes without changing LightRAG routing.

  • [x] Re-run only device retrieval and pipeline tests until green.

Task 2: Source scope management and real PostgreSQL authorization

Files:

  • Create: app/core/knowledge/device_scope.py
  • Create: tests/knowledge/test_device_scope.py

  • Create: tests/integration/test_device_knowledge_postgres.py

  • [x] Write failing service tests for sorted unique UUID scopes, the 100-domain boundary, invalid UUID rejection, missing source rejection, empty-scope admin-only semantics, and preservation of non-domain scope keys.

  • [x] Write a failing PostgreSQL test with two device sources in different business domains plus one unscoped source.

  • [x] Prove an admin can retrieve all three, a domain-A viewer can retrieve only source-A assets/events, source-B IDs do not match, and an unscoped asset does not leak.

  • [x] Implement DeviceSourceScopeService and its SQLAlchemy repository against the existing IngestionSource.permission_scope.

  • [x] Implement the device retriever query using an authorized_sources CTE so filtering occurs before text matching and aggregation.

  • [x] Add a source-detail lookup that applies the same authorization and returns only safe device/source/event fields.

  • [x] Run only the source-scope and PostgreSQL device-knowledge tests until green.

Task 3: Knowledge API integration, citations, and query audit

Files:

  • Create: app/core/knowledge/query_audit.py
  • Create: tests/knowledge/test_query_audit.py
  • Modify: app/api/knowledge_base/routes.py
  • Modify: tests/knowledge/test_api.py
  • Modify: app/core/system/permissions.py

  • Modify: tests/test_permission_matrix.py

  • [x] Write failing API tests for device search evidence, grounded device answers with citation content, model-unavailable answers with authorized retrieval evidence, device source detail, admin source-scope list/update, and admin query-audit list.

  • [x] Write failing audit tests proving only a normalized SHA-256 query hash, subject, roles, authorized domains, mode, retriever counts, cited point identities, degraded components, correlation ID, and latency are stored.

  • [x] Assert that raw query text, answer text, evidence content, credentials, and source configuration never enter the audit payload.

  • [x] Instantiate SqlDeviceKnowledgeRetriever in the default canonical pipeline and add safe device fallback to /api/knowledge/sources/<uid>.

  • [x] Add evidence to /api/knowledge/ask responses and enrich selected citations with their retrieved content and source metadata.

  • [x] Persist a query audit for every executed search/ask; fail the request if mandatory audit persistence fails.

  • [x] Add admin-only GET/PUT /api/knowledge/admin/device-sources[/<uid>/scope] and GET /api/knowledge/admin/query-audits.

  • [x] Keep public search/ask under governance:read and all scope/audit operations under knowledge:manage.

  • [x] Run only knowledge API, audit, and permission tests until green.

Task 4: Device-focused knowledge workbench

Files:

  • Create: frontend/src/views/knowledgeBaseProduct/deviceKnowledgeModel.js
  • Create: frontend/tests/device-knowledge-model.test.mjs
  • Modify: frontend/src/views/knowledgeBaseProduct/index.vue
  • Modify: frontend/src/api/governanceKnowledge.js

  • Create: tests/knowledge/test_device_knowledge_frontend_contract.py

  • [x] Write failing model tests for device object labels, answer-status presentation, citation/evidence fallback, source-scope display, and admin-only controls.

  • [x] Write a failing frontend contract test for device search prompts, source ID/location/responsible/fault coverage, explicit no-answer language, source-scope management, and audit visibility.

  • [x] Add device prompt examples and render readable DeviceAsset evidence without parsing or exposing private source configuration.

  • [x] For ask responses, display selected citations when grounded; otherwise display authorized retrieval evidence beneath the explicit refusal/model-unavailable state.

  • [x] Add an admin source-scope dialog accepting newline-separated business-domain UUIDs and show that an empty scope is admin-only.

  • [x] Add an admin query-audit list that displays time, mode, retriever counts, cited-point count, degraded components, and correlation ID but never raw questions.

  • [x] Use the existing $snackbar interface for success and failure feedback.

  • [x] Run only the Node model test, frontend contract test, and ESLint on changed frontend files.

Task 5: Acceptance set, documentation, and release-copy parity

Files:

  • Create: docs/acceptance/WP10_DEVICE_KNOWLEDGE_GOLDEN_SET.json
  • Modify: docs/FUNCTION_MODULE_CENSUS_20260726.md
  • Modify: docs/DATAOPS_PHASE1_3_MONTH_WORK_PLAN_20260729.md
  • Modify: docs/architecture/DATA_MODEL.md
  • Modify: docs/architecture/OPENAPI.yaml
  • Modify: tests/test_architecture_artifacts.py

  • Mirror changed backend files under: deployment/app/

  • [x] Add a versioned ten-case acceptance set covering name, platform UID, source ID, location, responsible person, fault, grounded owner/fault questions, unauthorized-domain refusal, and insufficient-evidence refusal.

  • [x] Document source-scope semantics, SQL pre-filtering, post-fusion authorization, audit data minimization, citation behavior, and model-unavailable behavior.

  • [x] Mark WP10 engineering maturity separately from enterprise source-scope, real-model, and golden-set acceptance.

  • [x] Update CAT-11, CAT-12, KAI-03, KAI-04, KAI-05, KAI-06, KAI-08, KAI-09, KAI-20, and KAI-22 without claiming NL2SQL or production K6 completion.

  • [x] Regenerate OpenAPI and assert all new admin endpoints plus ask evidence fields are represented.

  • [x] Copy every changed app/ backend file to deployment/app/ and verify byte parity.

Task 6: Targeted validation and local branch commit

Files:

  • Test only WP10-related files and directly affected permission/architecture contracts.

  • [x] Run WP10 device retrieval, scope, query audit, API, frontend contract, PostgreSQL integration, permission, and architecture tests only.

  • [x] Run Ruff only on changed Python files.

  • [x] Run ESLint only on changed frontend files and run the device knowledge Node model test.

  • [x] Build the frontend production bundle because the existing knowledge workbench changes.

  • [x] Rebuild only local backend/frontend services needed for WP10 browser validation.

  • [x] In the browser, verify authorized device search by source ID and fault, model-unavailable/insufficient evidence does not fabricate an answer, source detail is safe, source-scope management works, query audits contain no raw question, and a clean knowledge page has zero console errors.

  • [x] Confirm the existing device asset and observability pages still load through unchanged navigation.

  • [x] Commit the verified WP10 change on codex/dataops-phase1-equipment-governance; do not push or deploy production.