Einrichtung und Prüfstand
GCC mit C++20, CMake ab 3.25, CTest und Python 3. Qt 6.8 mit Core, Widgets und Test. Setze CMAKE_PREFIX_PATH auf deinen Qt-Installationsordner, falls Qt nicht automatisch gefunden wird. Lokal geprüft mit Qt 6.8.3. Entpacke das ZIP in einen neuen Ordner. python3 run_checks.py prüft Beispiel und Lösung in einer temporären Kopie und erhält deine Dateien. Für einen eigenen Build führe python3 verify.py aus. Danach liegt das Demo unter build/order_lab. Die Qt-Demos verwenden englische Beschriftungen. Automatische Widgettests nutzen standardmäßig offscreen. Starte die sichtbare Demo in einer Desktop-Sitzung ohne QT_QPA_PLATFORM=offscreen. Native Windows-Ausführung ist nicht verifiziert.
Geprüft am 21.10.2026 unter Linux x86_64. V1-zu-V2-Migration, JSON-Roundtrip, ungültige Struktur und Versionen, Größenlimit, Dateifehler und Erhalt einer gültigen Datei bei abgewiesenen Daten. Die Übung prüft einen gefilterten Export. Kein Crash-Durability-Nachweis.
Gespeicherte Dateien überleben oft die Programmversion, mit der sie erstellt wurden. Das Order-Lab-Format beginnt mit ID und Titel. Version 2 ergänzt Priorität und Status. Der Decoder übersetzt beide Versionen in dasselbe aktuelle Domänenmodell. Der Encoder schreibt ausschließlich Version 2. Dieses eigenständige Lernformat ist nicht das Projektformat der FactoryForge-Anwendung.
Paketinhalt und einzelne Dateien
01Das alte Format verstehen
Jede Datei nennt format und version ausdrücklich. appfabrik-order-lab unterscheidet diese Auftragslisten von anderen JSON-Dateien. Version 1 kennt nur id und title. Fehlende neue Eigenschaften werden nicht beliebig geraten, sondern durch die dokumentierte Migration ergänzt.
{
"format": "appfabrik-order-lab",
"version": 1,
"orders": [
{
"id": 7,
"title": "Legacy delivery"
}
]
}
Der Altauftrag hat nach dem Laden Priorität 0 und Status open.
02Das aktuelle Format festlegen
Version 2 verlangt zusätzlich priority zwischen 0 und 2 und status als open oder done. Eine Versionsnummer wie 1.5 ist kein gültiger Ersatz für Version 1. Unbekannte zukünftige Versionen werden abgelehnt. Der Decoder ignoriert zusätzliche Felder innerhalb einer bekannten Version, verlangt aber alle Pflichtfelder.
{
"format": "appfabrik-order-lab",
"version": 2,
"orders": [
{
"id": 10,
"title": "Deliver motors",
"priority": 2,
"status": "open"
}
]
}
Das Format lässt sich ohne Zugriff auf eine bestimmte App-Installation prüfen.
03Struktur und Grenzen prüfen
decode begrenzt Dokumente auf 256 KiB und Listen auf 1000 Einträge. Es kontrolliert Ganzzahlen, Typen, Statuswerte und eindeutige IDs. Erst nach vollständiger Validierung entsteht ein erfolgreiches Ergebnis. saveFile verwendet QSaveFile mit deaktiviertem direkten Schreibfallback. Ungültige Daten werden vor dem Öffnen der Zieldatei abgelehnt.
#pragma once
#include "order.hpp"
#include <QFile>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QSaveFile>
#include <cmath>
namespace orders {
inline constexpr int maximumDocumentBytes = 262144;
inline bool integer(const QJsonValue &value, int minimum, int maximum) {
if (!value.isDouble())
return false;
double number = value.toDouble();
return std::isfinite(number) && std::floor(number) == number &&
number >= minimum && number <= maximum;
}
inline Result<std::vector<Order>> decode(const QByteArray &bytes) {
if (bytes.size() > maximumDocumentBytes)
return Error{ErrorCode::invalid, "Document exceeds 256 KiB"};
QJsonParseError parse;
auto document = QJsonDocument::fromJson(bytes, &parse);
if (parse.error != QJsonParseError::NoError || !document.isObject())
return Error{ErrorCode::invalid, "Expected a JSON object"};
auto root = document.object();
if (root.value("format") != "appfabrik-order-lab" ||
!integer(root.value("version"), 1, 2))
return Error{ErrorCode::unsupported,
"Expected order-lab format version 1 or 2"};
if (!root.value("orders").isArray() ||
root.value("orders").toArray().size() > 1000)
return Error{ErrorCode::invalid,
"Expected an array of at most 1000 orders"};
std::vector<Order> result;
for (const auto &value : root.value("orders").toArray()) {
if (!value.isObject())
return Error{ErrorCode::invalid, "Order must be an object"};
auto object = value.toObject();
if (!integer(object.value("id"), 1, 1000000) ||
!object.value("title").isString())
return Error{ErrorCode::invalid, "Invalid ID or title"};
Order order{object.value("id").toInt(),
object.value("title").toString().toStdString()};
if (root.value("version").toInt() == 2) {
if (!integer(object.value("priority"), 0, 2) ||
(object.value("status") != "open" &&
object.value("status") != "done"))
return Error{ErrorCode::invalid, "Invalid priority or status"};
order.priority = object.value("priority").toInt();
order.status =
object.value("status") == "done" ? Status::done : Status::open;
}
result.push_back(std::move(order));
}
auto valid = validateBatch(result);
if (!succeeded(valid))
return std::get<Error>(valid);
return result;
}
inline Result<QByteArray> encode(std::span<const Order> batch) {
auto valid = validateBatch(batch);
if (!succeeded(valid))
return std::get<Error>(valid);
QJsonArray items;
for (const auto &order : batch)
items.append(QJsonObject{
{"id", order.id},
{"title", QString::fromStdString(order.title)},
{"priority", order.priority},
{"status", order.status == Status::open ? "open" : "done"}});
auto bytes = QJsonDocument(QJsonObject{{"format", "appfabrik-order-lab"},
{"version", 2},
{"orders", items}})
.toJson(QJsonDocument::Compact);
if (bytes.size() > maximumDocumentBytes)
return Error{ErrorCode::invalid, "Encoded document exceeds 256 KiB"};
return bytes;
}
inline Result<std::vector<Order>> loadFile(const QString &path) {
QFile file(path);
if (!file.open(QIODevice::ReadOnly))
return Error{ErrorCode::storage, file.errorString().toStdString()};
auto bytes = file.read(maximumDocumentBytes + 1);
if (file.error() != QFileDevice::NoError)
return Error{ErrorCode::storage, file.errorString().toStdString()};
return decode(bytes);
}
inline Result<Done> saveFile(const QString &path,
std::span<const Order> batch) {
auto encoded = encode(batch);
if (!succeeded(encoded))
return std::get<Error>(encoded);
const auto &bytes = std::get<QByteArray>(encoded);
QSaveFile file(path);
file.setDirectWriteFallback(false);
if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() ||
!file.commit())
return Error{ErrorCode::storage, file.errorString().toStdString()};
return Done{};
}
} // namespace orders
Eine abgewiesene Speicherung ersetzt keine vorhandene gültige Datei.
04Migration sichtbar ausführen
Starte ./build/order_lab nach python3 verify.py. Das Programm lädt einen eingebetteten V1-Auftrag und schreibt ihn über den aktuellen Encoder zurück. Es verändert keine Originaldatei. Vergleiche die Ausgabe mit orders-v2.json und identifiziere die beiden ergänzten Eigenschaften.
#include "json_orders.hpp"
#include <iostream>
int main() {
auto migrated = orders::decode(
R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"Legacy order"}]})");
if (!orders::succeeded(migrated))
return 1;
auto encoded = orders::encode(std::get<std::vector<orders::Order>>(migrated));
if (!orders::succeeded(encoded))
return 1;
std::cout << std::get<QByteArray>(encoded).toStdString() << '\n';
}
Die Ausgabe enthält version 2, priority 0 und status open.
05Kompatibilität und Abweisung nachweisen
Die Tests prüfen V1-Migration, V2-Roundtrip und die vorhandene Datei nach einem ungültigen Speicherauftrag. Eine Tabelle negativer Fälle enthält beschädigtes JSON, falsches Wurzelformat, unbekannte oder gebrochene Versionsnummern, doppelte IDs, fehlende V2-Felder und zu große Daten. Ein Test für Stromausfallsicherheit wird damit nicht behauptet.
#include "json_orders.hpp"
#include "test_support.hpp"
#include <QTemporaryDir>
#include <QtTest>
using namespace orders;
class FileTests : public QObject {
Q_OBJECT
private slots:
void migrationAndRoundTrip() {
auto migrated = decode(
R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":7,"title":"Legacy"}]})");
QVERIFY(succeeded(migrated));
auto batch = std::get<std::vector<Order>>(migrated);
QCOMPARE(batch[0].priority, 0);
QCOMPARE(batch[0].status, Status::open);
auto encoded = encode(batch);
QVERIFY(succeeded(encoded));
QVERIFY(std::get<QByteArray>(encoded).contains("\"version\":2"));
QVERIFY(std::get<std::vector<Order>>(
decode(std::get<QByteArray>(encoded))) == batch);
QTemporaryDir directory;
auto path = directory.filePath("orders.json");
QVERIFY(succeeded(saveFile(path, samples())));
QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
auto invalid = samples();
invalid[0].title.clear();
QVERIFY(!succeeded(saveFile(path, invalid)));
QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
QVERIFY(
!succeeded(saveFile(directory.filePath("missing/file.json"), batch)));
QVERIFY(!succeeded(loadFile(directory.filePath("absent.json"))));
}
void malformed_data() {
QTest::addColumn<QByteArray>("input");
QTest::newRow("syntax") << QByteArray("{");
QTest::newRow("root") << QByteArray("[]");
QTest::newRow("unknown") << QByteArray(
R"({"format":"appfabrik-order-lab","version":3,"orders":[]})");
QTest::newRow("fraction") << QByteArray(
R"({"format":"appfabrik-order-lab","version":1.5,"orders":[]})");
QTest::newRow("wrong-format")
<< QByteArray(R"({"format":"factory-forge","version":1,"orders":[]})");
QTest::newRow("duplicate") << QByteArray(
R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"A"},{"id":1,"title":"B"}]})");
QTest::newRow("missing-fields") << QByteArray(
R"({"format":"appfabrik-order-lab","version":2,"orders":[{"id":1,"title":"A"}]})");
QTest::newRow("oversized") << QByteArray(maximumDocumentBytes + 1, ' ');
}
void malformed() {
QFETCH(QByteArray, input);
QVERIFY(!succeeded(decode(input)));
}
};
QTEST_GUILESS_MAIN(FileTests)
#include "tests.moc"
Gültige Altdateien werden übernommen. Jeder negative Fall liefert einen Fehler.
06Einen gefilterten Export ergänzen
encodeOpen erzeugt eine neue Liste ausschließlich offener Aufträge und verwendet anschließend den normalen Encoder. Dadurch gelten dieselben Format- und Validierungsregeln. Der ursprüngliche Bestand bleibt unangetastet. Die Lösung liest den Export wieder ein, statt nur nach einem Textstück in der Ausgabe zu suchen.
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
std::vector<orders::Order> open;
std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
return order.status == orders::Status::open;
});
return orders::encode(open);
}
int main() {
const auto original = samples();
auto result = encodeOpen(original);
require(orders::succeeded(result), "encode");
auto decoded = orders::decode(std::get<QByteArray>(result));
require(orders::succeeded(decoded), "decode exported file");
require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
"only open exported");
require(original == samples(), "source unchanged");
require(std::get<QByteArray>(result).contains("\"version\":2"),
"current version");
require(orders::succeeded(encodeOpen({})), "empty export");
}
Der Export enthält zwei offene Aufträge im aktuellen Format.
Deine Übung
Schreibe encodeOpen. Exportiere nur offene Aufträge als Version 2, ohne die Ausgangsliste zu verändern. Prüfe den erneut eingelesenen Inhalt und einen leeren Export.
Lösung mit Erklärung anzeigen
Die Lösung filtert in einen eigenen vector und ruft encode auf. Die Tests kontrollieren zwei offene Aufträge, Version 2, unveränderte Originaldaten und einen zulässigen leeren Export.
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
std::vector<orders::Order> open;
std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
return order.status == orders::Status::open;
});
return orders::encode(open);
}
int main() {
const auto original = samples();
auto result = encodeOpen(original);
require(orders::succeeded(result), "encode");
auto decoded = orders::decode(std::get<QByteArray>(result));
require(orders::succeeded(decoded), "decode exported file");
require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
"only open exported");
require(original == samples(), "source unchanged");
require(std::get<QByteArray>(result).contains("\"version\":2"),
"current version");
require(orders::succeeded(encodeOpen({})), "empty export");
}
Projektbezug und Quellen
Eigenständiges Lernprojekt im Logistikthema von FactoryForge. Der bestehende FactoryForge-Quellstand dient als Architekturkontext. Die hier eingeführten SQLite-, Netzwerk- und Importfunktionen sind Funktionen des Lernprojekts. Das Order-Lab-JSON ist ein eigenes Format.