Setup and verification
GCC with C++20, CMake 3.25 or later, CTest and Python 3. Qt 6.8 with Core, Widgets and Test. Set CMAKE_PREFIX_PATH to your Qt installation if it is not discovered automatically. Locally checked with Qt 6.8.3. Extract the ZIP into a new folder. python3 run_checks.py checks example and solution in a temporary copy and preserves your files. Run python3 verify.py for your own build. The demo is then available at build/order_lab. Qt demos use English labels. Automated widget tests default to offscreen. Run the visible demo in a desktop session without QT_QPA_PLATFORM=offscreen. Native Windows execution is not verified.
Verified on 2026-10-21 on Linux x86_64. V1-to-v2 migration, JSON round trips, invalid structure and versions, size limits, file errors and preservation of a valid file when data is rejected. The exercise checks filtered export. No crash-durability claim.
Saved files often outlive the program version that created them. The Order Lab format starts with ID and title. Version 2 adds priority and status. The decoder translates both versions into the current domain model, while the encoder only writes version 2. This independent teaching format is not the FactoryForge application's project format.
Package contents and individual files
01Understand the old format
Each file explicitly names its format and version. appfabrik-order-lab distinguishes these order lists from other JSON documents. Version 1 only knows id and title. Missing new properties are supplied by a documented migration rather than guessed arbitrarily.
{
"format": "appfabrik-order-lab",
"version": 1,
"orders": [
{
"id": 7,
"title": "Legacy delivery"
}
]
}
The legacy order loads with priority 0 and status open.
02Define the current format
Version 2 additionally requires priority from 0 to 2 and status as open or done. A version number such as 1.5 is not a valid substitute for version 1. Unknown future versions are rejected. The decoder ignores extra fields within a known version but requires every mandatory field.
{
"format": "appfabrik-order-lab",
"version": 2,
"orders": [
{
"id": 10,
"title": "Deliver motors",
"priority": 2,
"status": "open"
}
]
}
The format can be checked without access to a particular app installation.
03Validate structure and limits
decode limits documents to 256 KiB and lists to 1000 entries. It checks integers, types, statuses and unique IDs. A successful result is returned only after full validation. saveFile uses QSaveFile with direct-write fallback disabled. Invalid data is rejected before opening the destination file.
#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
A rejected save does not replace an existing valid file.
04Run a visible migration
Run ./build/order_lab after python3 verify.py. The program loads an embedded v1 order and writes it through the current encoder. It changes no original file. Compare the output with orders-v2.json and identify the two added properties.
#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';
}
The output contains version 2, priority 0 and status open.
05Prove compatibility and rejection
Tests cover v1 migration, a v2 round trip and the existing file after an invalid save request. Negative cases include malformed JSON, the wrong root type, unknown or fractional versions, duplicate IDs, missing v2 fields and oversized input. These checks do not claim power-loss safety.
#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"
Valid legacy files migrate successfully. Every negative case returns an error.
06Add a filtered export
encodeOpen constructs a new list containing only open orders and then uses the regular encoder. The same format and validation rules apply. The original batch remains untouched. The solution decodes the export again rather than merely searching for a text fragment in its output.
#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");
}
The export contains two open orders in the current format.
Your exercise
Write encodeOpen. Export only open orders as version 2 without changing the source list. Check decoded output and an empty export.
Show the solution and explanation
The solution filters into an owning vector and calls encode. Tests check two open orders, version 2, unchanged original data and a valid empty 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");
}
Project context and sources
Independent teaching project using FactoryForge's logistics theme. The existing FactoryForge source revision provides architectural context. SQLite, networking and import features introduced here belong to the teaching project. Order Lab JSON is a separate format.