FS-DAT-001: Data Integrity Functions¶
| Property | Value |
|---|---|
| ID | FS-DAT-001 |
| Version | 1.0 |
| Corresponding URS | URS-DAT-001 |
| Status | Draft |
| Author | |
| Approved By | |
| Date |
Architecture Reference¶
Functional Specifications¶
FS-DAT-001.1: ALCOA+ Record Structure¶
Covers URS: URS-DAT-001.1
Functional Description: Every entity in all 8 databases follows the common column pattern (CC-05).
Column Specification:
| Column | Type | Source | Purpose |
|---|---|---|---|
| UID | bigint(20) NOT NULL AUTO_INCREMENT | Database | Unique identifier, never manually set |
| Timestamp | datetime | Application | Creation/modification time |
| Creator | varchar(30) | Application | User or system identifier |
| CRC | bigint(20) | Application | Integrity checksum (CRC32) |
Enforcement:
- EF Core entity configurations enforce column mappings
- ValueGeneratedOnAdd() for UID
- Application code sets Timestamp and Creator before save
- CRC calculated in two-phase insert
arc42 Reference: CC-05 in arc42/02
FS-DAT-001.2: CRC Integrity Verification¶
Covers URS: URS-DAT-001.2
Functional Description: CRC32 checksum calculated via ICrcService. Runtime flow: arc42/06 s6.4.
Two-Phase Insert Sequence:
1. Create entity with UID = 0
2. SaveChangesAsync() — database assigns AUTO_INCREMENT UID
3. Read back generated UID
4. Build CRC content: {prefix}{UID}-{field1}-{field2}-...-{timestamp}-{creator}
5. Calculate CRC32 from content string
6. Update entity with CRC
7. SaveChangesAsync() — persist CRC
CRC Content Format:
Type Prefixes by Repository:
- TH: EsrtRbtx-
- (Each parameter type has its own prefix defined in the repository)
Verification: To verify integrity, recalculate CRC from stored fields and compare with stored CRC value.
arc42 Reference: arc42/08 s8.5, ADR-003
FS-DAT-001.3: Changelog Audit Trail¶
Covers URS: URS-DAT-001.3
Functional Description: 44 changelog tables in db_changelogs track all parameter modifications.
Changelog Record Structure:
| Field | Type | Description |
|---|---|---|
| UID | bigint(20) | Changelog entry UID |
| EntityType | string | What entity changed |
| EntityUid | long | Which entity changed |
| ChangeType | string | Create / Update / Delete |
| OldValue | text | Previous value (JSON) |
| NewValue | text | New value (JSON) |
| Timestamp | datetime | When changed |
| Creator | string | Who changed it |
| CRC | bigint(20) | Changelog entry integrity |
Business Rules: - Changelog records are append-only (never modified or deleted) - Stored in separate database (db_changelogs) for isolation - CRC calculated on changelog entries themselves
FS-DAT-001.4: Transaction Atomicity¶
Covers URS: URS-DAT-001.4
Functional Description: Unit of Work pattern coordinates transactions across multiple repositories and databases. See arc42/08 s8.4.
Transaction Scenarios:
| Scenario | Databases Involved | UoW Scope |
|---|---|---|
| Product + version + params | db_productparameter | Single DB transaction |
| Cascading delete (product) | db_productparameter, db_changelogs | Cross-DB UoW |
| Process + WPC update | db_process, db_wpc | Cross-DB UoW |
Rollback Behavior: - On failure, all changes across all involved databases are rolled back - No partial state is ever persisted - Error returned to caller with details
Error Handling:
| Error Condition | Response | HTTP Status |
|---|---|---|
| Transaction commit failure | All changes rolled back, error details returned | 500 |
| Partial rollback failure | Logged as critical, manual intervention may be needed | 500 |
Service Mapping¶
| FS Item | Infrastructure Service |
|---|---|
| FS-DAT-001.1 | EF Core entity configurations (all DbContexts) |
| FS-DAT-001.2 | ICrcService / CrcService |
| FS-DAT-001.3 | ChangelogsDbContext |
| FS-DAT-001.4 | IUnitOfWork / CrossDatabaseUnitOfWork |