Document 02 — User Requirements Specification (URS)
Document ID: URS-GXPHISTORIAN-2026-002 | Generated (UTC): 2026-10-17T20:21:45Z | Total Requirements: 15
1. Formal User Requirements Catalog (URS-001 to URS-015)
| URS ID | Requirement Title & Operational Statement | GxP Risk | ALCOA+ Attributes | Regulation Ref | Acceptance Criteria (FRS) |
|---|---|---|---|---|---|
| URS-001 | Multi-Service Container Infrastructure & Non-Default GxP Security Credentials The system shall deploy isolated PostgreSQL Control Plane, ClickHouse Telemetry Archive, Edge Collector, FastAPI Control Plane, and Grafana HMI services using non-default authenticated credentials. | Medium | Attributable, Contemporaneous | 21 CFR §11.10(d), EU GMP Annex 11 §12 | FRS-INFRA-001: All database, API, and HMI endpoints enforce non-default credentials configured via environment variables and pass readiness health checks. |
| URS-002 | PostgreSQL 16 Control Plane Extensions & Core GxP Schema Qualification The PostgreSQL Control Plane shall enable ltree, btree_gist, and pgcrypto extensions and provision tables for asset_templates, assets, tags, event_frames, users, and part11_audit_log. | Medium | Legible, Enduring | 21 CFR §11.10(a), GAMP 5 Appendix M4 | FRS-PG-002: PostgreSQL 16 initializes ltree, btree_gist, and pgcrypto extensions, GiST hierarchy indexes, and all 6 required GxP tables. |
| URS-003 | ClickHouse Lossless Time-Series Compression Codecs Verification The ClickHouse Telemetry Archive shall store high-frequency sensor data using lossless Delta, DoubleDelta, Gorilla, and T64 codecs layered with ZSTD(1). | Low | Original, Accurate, Enduring | 21 CFR §11.10(b), EU GMP Annex 11 §7.1 | FRS-CH-003: Table pi_historian.sensor_data enforces CODEC(Delta, ZSTD(1)) on tag_id, CODEC(DoubleDelta, ZSTD(1)) on ts, CODEC(Gorilla, ZSTD(1)) on val, and CODEC(T64, ZSTD(1)) on quality and status_code. |
| URS-004 | ISA-95 ltree Asset Hierarchy & ClickHouse In-Memory Dictionary Synchronization The system shall synchronize ISA-95 hierarchical asset paths and tag metadata from PostgreSQL into ClickHouse via an in-memory FLAT dictionary. | Medium | Legible, Consistent | ISA-95, 21 CFR §11.10(a) | FRS-DICT-004: ClickHouse dictionary pi_historian.pg_asset_tags resolves all seeded GxP tags and their ISA-95 asset_path strings from PostgreSQL v_clickhouse_tag_dict. |
| URS-005 | Stage 1 Edge Exception/Deadband Filtering & Disk WAL Store-and-Forward Buffer The Edge Collector shall perform Stage 1 Exception/Deadband filtering (ExcDev and ExcMax) and persist outbound batches in a disk-backed Write-Ahead Log (WAL) buffer. | High | Complete, Original, Available | ALCOA+ (Complete, Original), EU GMP Annex 11 §7 | FRS-EDGE-005: Telegraf edge-collector configures buffer_strategy=‘disk’ at /var/lib/telegraf/buffer and applies ExcDev/ExcMax deadband filtering accurately. |
| URS-006 | 21 CFR Part 11 Mandatory Attribution Context Enforcement All INSERT, UPDATE, and DELETE operations on GxP configuration and batch Event Frame tables shall require authenticated actor_id and change_reason context or be rejected. | High | Attributable, Contemporaneous | 21 CFR §11.10(e), ALCOA+ (Attributable) | FRS-P11-006: PL/pgSQL trigger fn_enforce_part11_audit() raises ‘21 CFR Part 11 Violation: app.actor_id and app.change_reason are mandatory’ when session context is missing. |
| URS-007 | 21 CFR Part 11 §11.10(e) WORM Audit Trail Immutability The computer-generated, time-stamped audit trail (part11_audit_log) shall be strictly append-only (Write-Once-Read-Many) and block UPDATE, DELETE, and TRUNCATE operations. | High | Original, Enduring, Complete | 21 CFR §11.10(e), EU GMP Annex 11 §9 | FRS-P11-007: PL/pgSQL trigger fn_prevent_audit_tampering() unconditionally raises ‘21 CFR Part 11 WORM Violation: Audit trail records are immutable’ on UPDATE, DELETE, or TRUNCATE. |
| URS-008 | 21 CFR Part 11 §11.200 Electronic Signature Rejection of Unauthorized Credentials The system shall reject electronic signature attempts with invalid user IDs, wrong passwords, or missing change reasons. | High | Attributable, Accurate | 21 CFR §11.10(d), §11.200(a) | FRS-P11-008: POST /api/v1/event-frames/{event_id}/sign verifies password against pgcrypto bcrypt hash and returns HTTP 401 on invalid credentials without altering the record. |
| URS-009 | 21 CFR Part 11 §11.50 & §11.70 Electronic Signature Manifestation & HMAC Binding Signed Event Frames shall record the signer’s user ID, timestamp, signature meaning, and cryptographic HMAC-SHA256 signature hash linked to the audit trail. | High | Attributable, Legible, Enduring | 21 CFR §11.50, §11.70, §11.200 | FRS-P11-009: POST /api/v1/event-frames/{event_id}/sign authenticates qa_approver_01, binds HMAC-SHA256 over (event_id, user_id, signature_meaning, signed_at), and logs to part11_audit_log. |
| URS-010 | 21 CFR Part 11 Cryptographic SHA-256 Audit Hash-Chain Verification Every audit trail entry shall chain the previous record’s SHA-256 hash from GENESIS_0000000000000000, and the API shall verify end-to-end cryptographic integrity. | High | Original, Accurate, Enduring | 21 CFR §11.10(e), ALCOA+ (Enduring, Accurate) | FRS-P11-010: GET /api/v1/audit-trail/verify recomputes the SHA-256 hash chain across all part11_audit_log records and confirms chain_valid == true. |
| URS-011 | Multi-Protocol Telemetry Ingestion (OPC UA, BACnet/IP, Siemens S7, Legacy OPC DA) The historian shall ingest and normalize real-time telemetry across OPC UA, BACnet/IP, Siemens S7, and legacy Windows OPC DA bridges into ClickHouse. | Medium | Contemporaneous, Original | 21 CFR §211.68, ALCOA+ (Contemporaneous) | FRS-HIST-011: All 5 multi-protocol tags (101, 102, 103, 301, 401) plus HTTP /ingest batches are archived in pi_historian.sensor_data with UTC millisecond timestamps. |
| URS-012 | Bad OPC Signal Quality (quality < 192) Exclusion from GMP Rollups Telemetry points flagged with Bad (0) or Uncertain (64) OPC quality codes shall be stored in raw history for diagnostics but strictly excluded from 1-minute GMP rollups. | High | Accurate, Consistent | 21 CFR §211.188, ALCOA+ (Accurate) | FRS-HIST-012: Materialized view pi_historian.mv_sensor_rollup_1m filters WHERE quality >= 192, excluding injected quality=0 fault spikes (e.g., val=9999.0) from min/max/avg rollups. |
| URS-013 | PI DataLink Parity: Linear Interpolation vs. Discrete Step (LOCF) Sampling The sampled data endpoint shall linearly interpolate continuous analog tags (is_step_tag=False) and apply Last Observation Carried Forward (LOCF) to discrete step tags (is_step_tag=True). | High | Accurate, Complete | 21 CFR §11.10(b), GAMP 5 | FRS-DL-013: GET /api/v1/datalink/sampled computes exact linear midpoints for continuous tags and strict integer LOCF states for step tags without fractional artifacts. |
| URS-014 | PI Vision PlotValues Parity: LTTB Visual Downsampling Peak Preservation Visual trend downsampling shall use ClickHouse largestTriangleThreeBuckets (LTTB) to preserve exact local excursion peaks and valleys. | Medium | Accurate, Legible | 21 CFR §11.10(b) | FRS-LTTB-014: GET /api/v1/trends/plot-values preserves the exact timestamp and magnitude of a synthetic spike when downsampling high-density telemetry. |
| URS-015 | ISA-88 Event Frame Excursion Capture & Zero-ETL Apache Parquet Lakehouse Export The system shall automatically detect parameter excursions into Event Frames with summary KPIs and export enriched telemetry to Apache Parquet files with 100% fidelity. | High | Available, Enduring, Complete | 21 CFR §11.10(b), ISA-88 | FRS-LAKE-015: POST /api/v1/event-frames/evaluate captures excursion metrics in PostgreSQL and POST /api/v1/lakehouse/export-parquet writes a valid Snappy-compressed Parquet file verified via pyarrow. |