Richard/Deploymentcenter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(2.7.0): Roadmap im DC, Testinstanz mit Testtor, Supervisor und MCP

Browse Source 
Sammelcommit fuer den ueber mehrere Sitzungen gewachsenen, bisher nicht
eingecheckten Stand. Getrennte Commits waeren ehrlicher gewesen, sind es
nachtraeglich aber nicht mehr: BugRepo, changelog.json und die Doku tragen
Aenderungen aus allen Straengen gleichzeitig, und keine Zwischenstufe waere
lauffaehig.

ROADMAP IM DEPLOYMENTCENTER (2.7.0)

Planungsstand, Reihenfolge und Zustaendigkeit lagen in handgepflegten
Markdown-Dateien neben einem Bugtracker, der genau diese drei Dinge bereits
fuehrt. Zwei Pfleger fuer dasselbe Feld - Drift war eine Frage der Zeit.

Ab jetzt: Zustand im DC, Begruendung in der Datei. Kein Feld hat zwei Pfleger.

  - Migration 016: epic, roadmap_rank, target_build, defer_trigger,
    doc_anchor, Status "deferred", Tabelle roadmap_epics.
    KEINE Roadmap-Tabelle - ein Eintrag ist ein bugtracker_item.
  - Zugehoerigkeit ist ein Feld: Ein Item steht auf der Roadmap, wenn es ein
    epic hat. Ein zweites Kennzeichen daneben koennte auseinanderlaufen.
  - Kennung ist die Item-ID. Handvergebene Kuerzel ("A12") erzeugen die
    schlimmste Fehlerart: Beide Seiten stimmig, Verschiedenes gemeint, weil
    die Kennung nach einer Loeschung neu vergeben wurde.
  - Zurueckstellen verlangt defer_trigger. Ohne benannten Anlass ist ein
    Vorhaben nicht zurueckgestellt, sondern vergessen. Die Regel sitzt im
    Repository, damit sie auf allen drei Schreibwegen gleich greift.
  - Modules/Bugtracker/Roadmap.php, /api/bugtracker/v1/roadmap.php,
    WebUI-Modul mit Filtern, cli/roadmap.php --write/--check,
    dc_roadmap und dc_roadmap_set im MCP-Adapter.
  - cli/roadmap.php --write ERZEUGT den Zustandsteil der Markdown-Datei;
    --check prueft nur die Prosa. Was erzeugt wird, kann nicht driften.
  - docs/ROADMAP_MIGRATION.md: Uebernahme fuer die anderen Projekte.

TESTINSTANZ UND TESTTOR

  - dc-dev.mhdf.de: zweite Installation, eigene DB, eigene Schluessel,
    Basic-Auth davor, Rocket.Chat aus.
  - 124 Testfaelle in tests/e2e gegen API, Rechte, Migrationen, Sperre.
  - scripts/deploy.py bringt vor jedem Upload erst den anstehenden Stand auf
    die Testinstanz und laesst dann den Testlauf laufen. Erst bei
    Rueckgabewert 0 geht etwas auf die Produktion (--ohne-test als Notausgang).
    Andersherum prueft der Lauf aelteren Code als den, der gleich hochgeht.
  - tests/ ist aus dem Produktiv-Deploy ausgeschlossen; testctl.php kann
    nicht versehentlich auf dc.mhdf.de landen.
  - Ein Lauf mit mehr uebersprungenen als geprueften Faellen endet mit
    Rueckgabewert 2 statt 0. Nichts ist kaputt, geprueft wurde es aber auch
    nicht - der Unterschied darf nicht am Rueckgabewert verschwinden.

SUPERVISOR, PROJEKTLANDSCHAFT, NACHPRUEFUNG (2.6.0/2.6.1)

  - Migration 013: projektuebergreifend melden (dev_agent, evidence,
    triage_external, affects).
  - Migration 014: supervisor_findings, Katalog, fuenf serverseitige
    Detektoren im Tick.
  - Migration 015: Nachpruefung als Arbeitsschlange statt Benachrichtigung.
  - DEV-Lizenzschluessel zur Selbstbedienung, dc-testkit fuer die Test-VM.
  - MCP-Adapter: 15 Werkzeuge, ohne Fremdabhaengigkeiten, mit Abgrenzung
    von Fremddaten gegen Prompt-Injektion.

BEHOBEN

  - observe und status im Supervisor legten den Zustand des Befundes als
    "status" in die Antwort. Http::ok() merged ['status' => 'success']
    darunter, also gewann der Befundzustand - eine angenommene Meldung kam
    als status="open" an. Heisst jetzt finding_status. War Item #59.

Migrationen 013-016 sind auf dem Produktivserver noch NICHT ausgefuehrt.
Ohne sie bricht das WebUI, weil die Roadmap-Ansicht bei jedem Seitenaufruf
gegen bugtracker_items.epic abfragt.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Deploymentcenter Bot
2026-08-29 21:59:20 +02:00
co-authored by Claude Opus 5
parent 9d0261306c
commit 1d5ac92051
52 changed files with 15261 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public/api/bugtracker/v1/manage/index.php
+92 -13
View File
@@ -60,7 +60,19 @@ if ($isWrite && $method !== 'POST') {
$context = ApiAuth::requireScope($db, $isWrite ? 'bugtracker:manage' : 'bugtracker:read');
$author = $context['actor'];
// Zwei Einschraenkungen, weil Lesen und Schreiben hier verschieden weit reichen.
//
// $boundProject gilt beim Schreiben und kennt keine Ausnahme: auch ein
// Werkbank-Token uebernimmt und schliesst nur Items im eigenen Projekt. Sonst
// zoege ein Agent, der in Projekt X arbeitet, ueber ?action=next Arbeit aus
// einem fremden Backlog an sich.
//
// $readProject gilt beim Lesen und laesst Werkbank-Token durch: ein Agent, der
// entscheiden soll, ob ein Fehler ins eigene oder ins fremde Projekt gehoert,
// muss die Landschaft sehen.
$boundProject = ApiAuth::projectFilter($context);
$readProject = ApiAuth::projectFilter($context, true);
$itemId = resolveItemId();
@@ -72,7 +84,11 @@ switch ($action) {
// no break - Http::ok beendet die Anfrage
case 'stats':
$slug = Http::str('project_slug') ?? $boundProject;
// Die Bindung geht der Anfrage vor. Vorher stand hier
// "Http::str('project_slug') ?? $boundProject" - damit konnte ein an
// Projekt X gebundenes Token die Zahlen jedes anderen Projekts abrufen,
// indem es den Slug einfach mitschickte.
$slug = $readProject ?? Http::str('project_slug');
Http::ok(['stats' => $repo->getStats($slug)]);
case 'get':
@@ -81,11 +97,11 @@ switch ($action) {
if ($item === null) {
Http::fail(404, 'not_found', sprintf('Item #%d existiert nicht.', $itemId));
}
ApiAuth::enforceProject($context, (string)$item['project_slug']);
ApiAuth::enforceProject($context, (string)$item['project_slug'], true);
Http::ok(['item' => $item]);
case 'list':
$filters = collectFilters($boundProject);
$filters = collectFilters($readProject);
$result = $repo->getItems($filters);
Http::ok([
'count' => count($result['items']),
@@ -113,6 +129,14 @@ switch ($action) {
case 'next':
$filters = collectFilters($boundProject);
// Der Rueckkanal: zusaetzlich zu den eigenen Items auch fremde, die auf
// Nachpruefung warten und bei denen dieses Projekt als betroffen
// vermerkt ist. Nur dort - siehe assertProject().
if ($boundProject !== null) {
$filters['include_affected_verification'] = $boundProject;
}
$limit = Http::int('limit', 1);
$claimedItems = $repo->claimNext($author, $filters, $limit);
Http::ok([
@@ -125,7 +149,8 @@ switch ($action) {
case 'release':
requireItemId($itemId);
assertProject($repo, $context, $itemId);
// Zurueckgeben duerfen heisst: was man haelt, auch loslassen koennen.
assertProject($repo, $context, $itemId, false, true);
if (!$repo->releaseItem($itemId, $author, Http::str('note'))) {
Http::fail(409, 'not_claimed', sprintf(
@@ -138,7 +163,7 @@ switch ($action) {
case 'comment':
requireItemId($itemId);
assertProject($repo, $context, $itemId);
assertProject($repo, $context, $itemId, true, true);
$comment = Http::str('comment');
if ($comment === null) {
@@ -157,7 +182,9 @@ switch ($action) {
case 'status':
requireItemId($itemId);
assertProject($repo, $context, $itemId);
// Der Pruefende schliesst mit dem Status ab - auch bei einem fremden
// Item, das er zur Nachpruefung haelt.
assertProject($repo, $context, $itemId, false, true);
$status = Http::str('status');
if ($status === null) {
@@ -166,7 +193,16 @@ switch ($action) {
]);
}
if (!$repo->updateStatus($itemId, $status, Http::str('notes'), $author)) {
try {
$changed = $repo->updateStatus($itemId, $status, Http::str('notes'), $author);
} catch (\InvalidArgumentException $e) {
// Etwa: zurueckstellen ohne Ausloeser. Das ist eine verletzte
// Regel, kein unbekannter Status - und verdient deshalb eine
// Meldung, die sagt, was fehlt.
Http::fail(400, 'invalid_transition', $e->getMessage());
}
if (!$changed) {
Http::fail(400, 'invalid_status', sprintf(
'Status "%s" ist unbekannt oder Item #%d existiert nicht.',
$status,
@@ -180,7 +216,13 @@ switch ($action) {
requireItemId($itemId);
assertProject($repo, $context, $itemId);
if (!$repo->updateItemDetails($itemId, Http::body(), $author)) {
try {
$updated = $repo->updateItemDetails($itemId, Http::body(), $author);
} catch (\InvalidArgumentException $e) {
Http::fail(400, 'invalid_update', $e->getMessage());
}
if (!$updated) {
Http::fail(404, 'not_found', sprintf('Item #%d existiert nicht.', $itemId));
}
Http::ok(['message' => sprintf('Item #%d aktualisiert.', $itemId)]);
@@ -283,10 +325,39 @@ function requireItemId(int $itemId): void
}
}
/** Stellt sicher, dass ein projektgebundenes Token das Item anfassen darf. */
function assertProject(BugRepo $repo, array $context, int $itemId): void
{
if (ApiAuth::projectFilter($context) === null) {
/**
* Stellt sicher, dass ein projektgebundenes Token das Item anfassen darf.
*
* $allowWorkbench laesst Werkbank-Token auch an fremde Items. Das ist nur fuer
* Kommentare gesetzt: wer aus einem anderen Projekt heraus melden darf, muss
* auch nachreichen koennen, was er inzwischen herausgefunden hat. Uebernehmen,
* abschliessen oder den Status aendern bleibt dem besitzenden Projekt
* vorbehalten - dort weiss man, was ein "resolved" bedeutet.
*/
/**
* Projektschranke fuer Schreibzugriffe auf ein einzelnes Item.
*
* $allowLeaseHolder oeffnet sie fuer den, der das Item gerade haelt. Das ist
* kein Schlupfloch, sondern die Kehrseite der Nachpruefung: Ein Agent kann ein
* FREMDES Item nur ueber ?action=next in die Hand bekommen, und dort gibt
* BugRepo nur Items heraus, die auf Nachpruefung warten und bei denen sein
* Projekt als betroffen vermerkt ist (siehe include_affected_verification).
* Wer auf diesem Weg etwas haelt, muss es auch kommentieren, im Status setzen
* und zurueckgeben duerfen - sonst haette er eine Aufgabe, die er nicht
* abschliessen kann.
*
* Bewusst NICHT geoeffnet: resolve und update. Was in einem fremden Projekt
* als "behoben in Build X" gilt, entscheidet dieses Projekt. Der Pruefende
* bestaetigt (status) oder meldet erneut - mehr braucht er nicht.
*/
function assertProject(
BugRepo $repo,
array $context,
int $itemId,
bool $allowWorkbench = false,
bool $allowLeaseHolder = false
): void {
if (ApiAuth::projectFilter($context, $allowWorkbench) === null) {
return;
}
@@ -295,7 +366,15 @@ function assertProject(BugRepo $repo, array $context, int $itemId): void
Http::fail(404, 'not_found', sprintf('Item #%d existiert nicht.', $itemId));
}
ApiAuth::enforceProject($context, (string)$item['project_slug']);
if ($allowLeaseHolder
&& ($item['claimed_by'] ?? null) === ($context['actor'] ?? null)
&& $item['lease_until'] !== null
&& strtotime((string)$item['lease_until']) > time()
) {
return;
}
ApiAuth::enforceProject($context, (string)$item['project_slug'], $allowWorkbench);
}
/**
public/api/bugtracker/v1/projects.php
+84 -9
View File
@@ -17,22 +17,85 @@ require_once __DIR__ . '/../../../../src/bootstrap.php';
use Deploymentcenter\Core\ApiAuth;
use Deploymentcenter\Core\Db;
use Deploymentcenter\Core\Http;
use Deploymentcenter\Core\ProjectLinks;
use Deploymentcenter\Modules\Bugtracker\BugRepo;
Http::beginJson(['GET', 'OPTIONS'], true);
Http::beginJson(['GET', 'POST', 'OPTIONS'], true);
if (Http::method() !== 'GET') {
Http::fail(405, 'method_not_allowed', 'Dieser Endpunkt erwartet GET.');
if (!in_array(Http::method(), ['GET', 'POST'], true)) {
Http::fail(405, 'method_not_allowed', 'Dieser Endpunkt erwartet GET oder POST.');
}
$db = Db::init();
$context = ApiAuth::requireScope($db, 'bugtracker:read');
$context = ApiAuth::requireScope($db, Http::method() === 'POST' ? 'bugtracker:report' : 'bugtracker:read');
// ---------------------------------------------------------------------------
// POST: Beziehung des eigenen Projekts zu einem anderen festhalten.
// ---------------------------------------------------------------------------
// Ersetzt die von Hand gepflegte Zeile "Deploymentcenter-Anbindung: SDK 2.5.1"
// in jeder Projekt-CLAUDE.md. Eine Angabe, die an N Stellen nachgezogen werden
// muss, ist nach dem ersten Vergessen falsch - und zwar schweigend.
//
// from_slug kommt wie reported_from aus der Token-Bindung, nicht aus dem Body:
// ein Projekt traegt seine eigene Anbindung ein, nicht die eines anderen.
if (Http::method() === 'POST') {
$home = ApiAuth::homeProject($context);
if ($home === null) {
Http::fail(
400,
'no_home_project',
'Dieses Token ist an kein Projekt gebunden. Eine Beziehung braucht aber ein Projekt, '
. 'von dem aus sie gilt.'
);
}
$target = is_string(Http::input('to_slug')) ? trim((string)Http::input('to_slug')) : null;
if ($target === null || $target === '' || $target === $home) {
Http::fail(
400,
'invalid_target',
'Das Feld "to_slug" muss ein anderes Projekt als das eigene bezeichnen.'
);
}
$kind = is_string(Http::input('kind')) ? (string)Http::input('kind') : 'uses_sdk';
if (!in_array($kind, ProjectLinks::KINDS, true)) {
Http::fail(400, 'invalid_kind', 'Unbekannte Art der Beziehung.', null, [
'allowed' => ProjectLinks::KINDS,
]);
}
$version = is_string(Http::input('integrated_version'))
? trim((string)Http::input('integrated_version'))
: null;
$links = new ProjectLinks($db);
if (!$links->record($home, $target, $kind, $version !== '' ? $version : null)) {
Http::fail(500, 'link_failed', 'Die Beziehung konnte nicht gespeichert werden.');
}
Http::ok([
'from_slug' => $home,
'to_slug' => $target,
'kind' => $kind,
'integrated_version' => $version,
'message' => $version !== null
? sprintf('"%s" nutzt "%s" in Fassung %s.', $home, $target, $version)
: sprintf('Beziehung "%s" -> "%s" festgehalten.', $home, $target),
]);
}
$repo = new BugRepo($db);
$projects = $repo->getProjects();
// Ein projektgebundenes Token sieht nur sein eigenes Projekt.
$bound = ApiAuth::projectFilter($context);
// Ein Laufzeit-Token sieht nur sein eigenes Projekt. Ein Werkbank-Token sieht
// alle: es soll ja gerade entscheiden koennen, wohin ein Fehler gehoert - und
// dafuer muss es die Nachbarn kennen.
$bound = ApiAuth::projectFilter($context, true);
if ($bound !== null) {
$projects = array_values(array_filter(
$projects,
@@ -40,18 +103,30 @@ if ($bound !== null) {
));
}
// Das Heimatprojekt bleibt auch beim Werkbank-Token bekannt. Es ist der
// Bezugspunkt, gegen den die Beziehungen ausgewiesen werden.
$home = ApiAuth::homeProject($context);
$links = new ProjectLinks($db);
Http::ok([
'count' => count($projects),
'projects' => array_map(static function (array $p): array {
'count' => count($projects),
'home_project' => $home,
'projects' => array_map(static function (array $p) use ($links, $home): array {
$slug = (string)$p['slug'];
return [
'id' => (int)$p['id'],
'slug' => (string)$p['slug'],
'slug' => $slug,
'name' => (string)$p['name'],
'notes' => $p['notes'] ?? null,
'repo_url' => $p['repo_url'] ?? null,
'default_agent' => $p['default_agent'] ?? null,
'open_items' => (int)($p['open_items'] ?? 0),
'critical_items' => (int)($p['critical_items'] ?? 0),
// Wie haengt dieses Projekt mit dem eigenen zusammen? null heisst
// schlicht "gar nicht" und ist der Normalfall.
'relation' => $home !== null ? $links->between($home, $slug) : null,
];
}, $projects),
]);
public/api/bugtracker/v1/report.php
+105 -10
View File
@@ -23,6 +23,14 @@ use Deploymentcenter\Core\Http;
use Deploymentcenter\Modules\Bugtracker\BugRepo;
use Deploymentcenter\Modules\License\RateLimiter;
/**
* Mindestlaenge der Begruendung bei einer Meldung gegen ein fremdes Projekt.
*
* Kurz genug, dass ein Satz reicht - lang genug, dass "Bug" oder "kaputt"
* nicht durchgeht.
*/
const MIN_EVIDENCE_LENGTH = 40;
Http::beginJson(['POST', 'OPTIONS'], true);
if (Http::method() !== 'POST') {
@@ -49,12 +57,58 @@ $environment = is_string($data['environment'] ?? null) ? $data['environment'] :
$context = ApiAuth::requireScope($db, 'bugtracker:report', $environment, false);
$projectSlug = is_string($data['project_slug'] ?? null) ? trim($data['project_slug']) : null;
ApiAuth::enforceProject($context, $projectSlug);
// Ein projektgebundenes Token schreibt immer in sein eigenes Projekt.
$boundProject = ApiAuth::projectFilter($context);
if ($boundProject !== null) {
$data['project_slug'] = $boundProject;
// Werkbank-Token duerfen in ein fremdes Projekt melden - ein Agent, der das SDK
// in Projekt X integriert und dabei einen Fehler im Deploymentcenter findet,
// muss ihn dort ablegen koennen. Laufzeit-Token duerfen das nicht: sie stecken
// im ausgelieferten Client und sind extrahierbar.
ApiAuth::enforceProject($context, $projectSlug, true);
$homeProject = ApiAuth::homeProject($context);
// Ein Laufzeit-Token schreibt immer in sein eigenes Projekt.
if ($homeProject !== null && !ApiAuth::isWorkbench($context)) {
$data['project_slug'] = $homeProject;
}
// --- Fremdmeldung? ----------------------------------------------------------
$target = is_string($data['project_slug'] ?? null) ? trim($data['project_slug']) : null;
$isForeign = $homeProject !== null
&& $target !== null && $target !== ''
&& $target !== $homeProject;
// Die Herkunft wird aus der Token-Bindung abgeleitet und niemals aus dem Body
// uebernommen. Nur so ist sie bezeugt statt behauptet - und nur dann traegt das
// Signal "drei Projekte melden dasselbe" ueberhaupt etwas.
$rawEvidence = $data['evidence'] ?? null;
unset($data['reported_from'], $data['evidence']);
if ($isForeign) {
$evidence = is_string($rawEvidence) ? trim($rawEvidence) : null;
// Begruendungspflicht. Ein Agent in Projekt X kann kaum unterscheiden, ob
// das fremde Projekt kaputt ist oder ob X es falsch benutzt; die
// Voreinstellung eines hilfsbereiten Modells ist im Zweifel "melde es".
// Etwas ausformulieren zu muessen kostet einen Reflex fast immer den Kopf.
if ($evidence === null || mb_strlen($evidence) < MIN_EVIDENCE_LENGTH) {
Http::fail(
400,
'missing_evidence',
sprintf(
'Eine Meldung gegen das fremde Projekt "%s" verlangt das Feld "evidence" '
. '(mindestens %d Zeichen): was wurde beobachtet, und warum liegt die '
. 'Ursache dort und nicht in "%s"?',
$target,
MIN_EVIDENCE_LENGTH,
$homeProject
),
null,
['home_project' => $homeProject, 'target_project' => $target]
);
}
$data['reported_from'] = $homeProject;
$data['evidence'] = $evidence;
}
// Der Absender wird aus dem Token abgeleitet und kann nicht frei gewaehlt
@@ -72,11 +126,41 @@ if (empty($data['client_ref'])) {
$repo = new BugRepo($db);
$result = $repo->reportItem($data);
$message = $result['idempotent_hit']
? 'Bereits erfasst (identische client_ref) - kein Duplikat angelegt.'
: ($result['is_new']
? ($result['type'] === 'bug' ? 'Bug erfasst.' : 'Feature Request erfasst.')
: 'Wiederkehrendes Vorkommnis - Zaehler erhoeht.');
// Bekannt und in einer spaeteren Fassung behoben. Diese Antwort geht jeder
// anderen vor: Sie beendet die Frage, statt sie einzusortieren. Der Melder
// prueft eine Fassung, in der der Fix noch nicht steckt - er soll aufhoeren zu
// suchen und aktualisieren, nicht ein weiteres Item anlegen.
// Der Fix hat nicht getragen. Kein neues Item - das bestehende ist zurueck in
// der Arbeitsschlange, und der Beleg haengt daran.
if (!empty($result['fix_insufficient'])) {
$message = sprintf(
'Der Fix traegt nicht. Item #%d steht wieder auf "fix_insufficient" und liegt in der '
. 'Arbeitsschlange - kein neues Item angelegt, der Beleg haengt am bestehenden.',
$result['id']
);
} elseif (isset($result['known_fixed_in'])) {
$message = sprintf(
'Bekannt und behoben in Build "%s" - du hast "%s" geprueft. Kein neues Item angelegt. '
. 'Aktualisiere und pruefe erneut; tritt es dann immer noch auf, ist es eine Regression '
. 'und gehoert gemeldet.',
$result['known_fixed_in'],
$result['reported_build']
);
} elseif ($isForeign) {
$message = $result['is_new']
? sprintf(
'Im Eingang von "%s" hinterlegt. Wird dort gesichtet und zaehlt erst nach '
. 'Bestaetigung in die Statistik.',
$target
)
: sprintf('Bereits bekannt - "%s" ist als betroffen vermerkt.', $homeProject);
} else {
$message = $result['idempotent_hit']
? 'Bereits erfasst (identische client_ref) - kein Duplikat angelegt.'
: ($result['is_new']
? ($result['type'] === 'bug' ? 'Bug erfasst.' : 'Feature Request erfasst.')
: 'Wiederkehrendes Vorkommnis - Zaehler erhoeht.');
}
Http::ok([
'item_id' => $result['id'],
@@ -90,6 +174,17 @@ Http::ok([
'environment' => $result['environment'],
'push_id' => $result['push_id'] ?? null,
'regression_of' => $result['regression_of'] ?? null,
// Gesetzt, wenn der Fehler bereits in einer spaeteren Fassung behoben ist
// als der, die gemeldet wurde. Dann wurde NICHTS angelegt und nichts
// hochgezaehlt - die Antwort ist eine Auskunft.
'known_fixed_in' => $result['known_fixed_in'] ?? null,
'reported_build' => $result['reported_build'] ?? null,
// Gesetzt, wenn der gemeldete Fehler ein Item betrifft, dessen Fix noch
// nicht bestaetigt war. Dann wurde kein neues Item angelegt - das
// bestehende wechselte auf fix_insufficient.
'fix_insufficient' => !empty($result['fix_insufficient']),
'reported_from' => $result['reported_from'] ?? null,
'affects' => $result['affects'] ?? [],
'url' => Http::baseUrl() . '/index.php#tab-bugtracker',
'message' => $message,
], $result['is_new'] ? 201 : 200);
public/api/bugtracker/v1/roadmap.php
+317
View File
@@ -0,0 +1,317 @@
<?php
/**
* /api/bugtracker/v1/roadmap.php
*
* Die Roadmap - Vorhaben mit Themenbereich, Reihenfolge und Zielfassung.
*
* GET ?action=list Eintraege, gefiltert (bugtracker:read)
* GET ?action=epics Themenbereiche samt Zaehlung (bugtracker:read)
* GET ?action=next "Als Naechstes" (bugtracker:read)
* GET ?action=active Wer arbeitet gerade woran (bugtracker:read)
* GET ?action=render Der erzeugte Markdown-Block (bugtracker:read)
* POST ?action=set Bereich/Rang/Ziel/Anker setzen (bugtracker:manage)
* POST ?action=move Eintrag eine Position schieben (bugtracker:manage)
* POST ?action=reorder Reihenfolge eines Bereichs neu (bugtracker:manage)
* POST ?action=epic Themenbereich anlegen/aendern (bugtracker:manage)
*
* KEINE eigene Datenhaltung. Ein Roadmap-Eintrag ist ein bugtracker_item mit
* gesetztem `epic`; dieser Endpunkt ist die Sicht darauf. Anlegen laeuft
* weiterhin ueber /report, Abschliessen ueber /manage - sonst gaebe es zwei
* Wege zu denselben Daten und damit zwei Stellen, an denen Regeln gelten
* muessten.
*/
declare(strict_types=1);
require_once __DIR__ . '/../../../../src/bootstrap.php';
use Deploymentcenter\Core\ApiAuth;
use Deploymentcenter\Core\Db;
use Deploymentcenter\Core\Http;
use Deploymentcenter\Modules\Bugtracker\BugRepo;
use Deploymentcenter\Modules\Bugtracker\Roadmap;
Http::beginJson(['GET', 'POST', 'OPTIONS'], true);
const READ_ACTIONS = ['list', 'epics', 'next', 'active', 'render', 'check'];
const WRITE_ACTIONS = ['set', 'move', 'reorder', 'epic'];
$action = strtolower(Http::str('action') ?? 'list');
if (!in_array($action, READ_ACTIONS, true) && !in_array($action, WRITE_ACTIONS, true)) {
Http::fail(404, 'unknown_action', sprintf('Unbekannte Aktion "%s".', $action), null, [
'available' => array_merge(READ_ACTIONS, WRITE_ACTIONS),
]);
}
$isWrite = in_array($action, WRITE_ACTIONS, true);
if ($isWrite && Http::method() !== 'POST') {
Http::fail(405, 'method_not_allowed', sprintf('Die Aktion "%s" erwartet POST.', $action));
}
$db = Db::init();
$repo = new BugRepo($db);
$roadmap = new Roadmap($db);
$context = ApiAuth::requireScope($db, $isWrite ? 'bugtracker:manage' : 'bugtracker:read');
$author = $context['actor'];
// Lesen darf die Landschaft sehen, Schreiben nur das eigene Projekt.
//
// Dieselbe Trennung wie in /manage, und aus demselben Grund: Ein Agent soll
// erkennen koennen, wo sein Projekt in der Gesamtplanung steht - aber die
// Reihenfolge fremder Vorhaben legt er nicht fest.
$readProject = ApiAuth::projectFilter($context, true);
$writeProject = ApiAuth::projectFilter($context);
$requested = Http::str('project_slug') ?? Http::str('project') ?? 'all';
$scope = $readProject ?? $requested;
switch ($action) {
case 'epics':
Http::ok([
'epics' => $roadmap->epics($scope),
'orphans' => $roadmap->orphanEpics($scope),
'stats' => $roadmap->stats($scope),
]);
case 'next':
Http::ok([
'items' => $roadmap->nextUp($scope, Http::int('limit', 5) ?: 5),
]);
case 'active':
Http::ok([
'items' => $roadmap->activeWork($scope),
]);
case 'render': {
$project = requireProject($scope);
Http::ok([
'project_slug' => $project,
'markdown' => $roadmap->renderBlock($project),
]);
}
case 'check': {
// Der Abgleich braucht den Dateiinhalt. Er kommt mitgeschickt, statt
// dass der Server ihn liest: Die Datei liegt im Repository des
// Projekts, oft auf einer anderen Maschine. Der Server kennt sie nicht
// und soll auch nicht anfangen, in Verzeichnissen zu suchen.
$project = requireProject($scope);
$content = Http::str('content');
if ($content === null) {
Http::fail(400, 'missing_content', 'Das Feld "content" mit dem Dateiinhalt fehlt.');
}
$tmp = tempnam(sys_get_temp_dir(), 'dcrm');
if ($tmp === false) {
Http::fail(500, 'tmp_failed', 'Konnte den Inhalt nicht zwischenspeichern.');
}
file_put_contents($tmp, $content);
$result = $roadmap->check($project, $tmp);
@unlink($tmp);
Http::ok($result);
}
case 'list': {
$filters = [
'project_slug' => $scope,
'on_roadmap' => true,
'epic' => Http::str('epic') ?? 'all',
'status' => resolveStatusFilter(Http::str('status')),
'type' => Http::str('type') ?? 'all',
'severity' => Http::str('severity') ?? 'all',
'target_build' => Http::str('target_build') ?? 'all',
'claimed_by' => Http::str('claimed_by') ?? '',
'search' => Http::str('q') ?? '',
'order' => 'roadmap',
'limit' => Http::int('limit', 200) ?: 200,
'offset' => Http::int('offset', 0) ?: 0,
];
$result = $repo->getItems($filters);
$result['stats'] = $roadmap->stats($scope);
Http::ok($result);
}
case 'set': {
$itemId = Http::int('id', 0) ?: 0;
if ($itemId < 1) {
Http::fail(400, 'missing_id', 'Das Feld "id" fehlt.');
}
assertOwnProject($repo, $writeProject, $itemId);
// Nur die Roadmap-Felder. Titel, Schweregrad und Status laufen
// weiterhin ueber /manage - ein zweiter Schreibweg auf dieselben
// Spalten waere eine zweite Stelle, an der Regeln gelten muessten.
$updates = [];
foreach (['epic', 'target_build', 'defer_trigger', 'doc_anchor'] as $field) {
if (Http::input($field) !== null) {
$updates[$field] = Http::str($field);
}
}
// Ein leerer Wert loescht die Reihenfolge, statt sie auf 0 zu setzen.
// Sonst waere "keine Meinung" nicht mehr ausdrueckbar - und Rang 0
// sortierte den Eintrag ausgerechnet an die Spitze.
if (Http::input('roadmap_rank') !== null) {
$raw = Http::str('roadmap_rank');
$updates['roadmap_rank'] = ($raw !== null && is_numeric($raw)) ? (int)$raw : null;
}
// Zurueckstellen laeuft ueber diesen Weg mit, weil Status und
// Ausloeser zusammen ankommen muessen - getrennt gesetzt entstuende
// genau der Eintrag ohne Ausloeser, den die Regel verhindern soll.
$status = Http::str('status');
if ($status !== null) {
$updates['status'] = $status;
}
if ($updates === []) {
Http::fail(400, 'nothing_to_do', 'Keines der Roadmap-Felder wurde mitgeschickt.', null, [
'fields' => ['epic', 'roadmap_rank', 'target_build', 'defer_trigger', 'doc_anchor', 'status'],
]);
}
try {
if (!$repo->updateItemDetails($itemId, $updates, $author)) {
Http::fail(404, 'not_found', sprintf('Item #%d existiert nicht.', $itemId));
}
} catch (\InvalidArgumentException $e) {
Http::fail(400, 'invalid_update', $e->getMessage());
}
Http::ok(['message' => sprintf('Roadmap-Angaben zu #%d gesetzt.', $itemId)]);
}
case 'move': {
$itemId = Http::int('id', 0) ?: 0;
if ($itemId < 1) {
Http::fail(400, 'missing_id', 'Das Feld "id" fehlt.');
}
assertOwnProject($repo, $writeProject, $itemId);
$direction = strtolower(Http::str('direction') ?? 'up');
if (!in_array($direction, ['up', 'down'], true)) {
Http::fail(400, 'invalid_direction', 'Erlaubt sind "up" und "down".');
}
if (!$roadmap->move($itemId, $direction)) {
Http::fail(409, 'cannot_move', sprintf(
'#%d laesst sich nicht weiter nach %s schieben - '
. 'schon am Rand des Bereichs, oder ohne Bereich.',
$itemId,
$direction === 'up' ? 'oben' : 'unten'
));
}
Http::ok(['message' => sprintf('#%d verschoben.', $itemId)]);
}
case 'reorder': {
$project = requireProject($writeProject ?? $requested);
$epic = Http::str('epic');
$ids = Http::input('ids');
if ($epic === null || !is_array($ids) || $ids === []) {
Http::fail(400, 'missing_fields', 'Es werden "epic" und "ids" (Liste) erwartet.');
}
$touched = $roadmap->reorder($project, $epic, array_map('intval', $ids));
Http::ok([
'message' => sprintf('%d Eintrag/Eintraege neu gereiht.', $touched),
'touched' => $touched,
]);
}
case 'epic': {
$project = requireProject($writeProject ?? $requested);
$epic = Http::str('epic');
$title = Http::str('title');
if ($epic === null || $title === null) {
Http::fail(400, 'missing_fields', 'Es werden "epic" und "title" erwartet.');
}
$roadmap->saveEpic(
$project,
$epic,
$title,
Http::str('summary'),
Http::int('sort_order', 100) ?: 100
);
Http::ok(['message' => sprintf('Themenbereich "%s" gespeichert.', $epic)]);
}
}
/**
* Verlangt ein konkretes Projekt.
*
* "all" ist beim Lesen sinnvoll und beim Schreiben oder Erzeugen nicht - eine
* Datei gehoert zu genau einem Repository.
*/
function requireProject(?string $slug): string
{
if ($slug === null || $slug === '' || $slug === 'all') {
Http::fail(400, 'missing_project', 'Diese Aktion braucht ein konkretes "project_slug".');
}
return $slug;
}
/**
* Ein Roadmap-Eintrag wird nur im eigenen Projekt umsortiert.
*
* Dieselbe Schranke wie beim Uebernehmen von Arbeit: Wer in Projekt X
* arbeitet, ordnet nicht die Planung von Projekt Y.
*/
function assertOwnProject(BugRepo $repo, ?string $bound, int $itemId): void
{
if ($bound === null) {
return; // Master-Token oder Oberflaeche
}
$item = $repo->getItemDetails($itemId);
if ($item === null) {
Http::fail(404, 'not_found', sprintf('Item #%d existiert nicht.', $itemId));
}
if ((string)$item['project_slug'] !== $bound) {
Http::fail(403, 'foreign_project', sprintf(
'Item #%d gehoert zu "%s". Fremde Roadmaps werden nicht umsortiert.',
$itemId,
(string)$item['project_slug']
));
}
}
/**
* Uebersetzt eine Lage-Auswahl in die zugehoerigen Status.
*
* Elf Status sind fuer die Ablage richtig und fuer einen Filter zu viele. Wer
* "offen" waehlt, meint keine ENUM-Konstante, sondern eine Lage - deshalb hier
* die Gruppen aus Roadmap::STATUS_GROUPS, mit den Einzelstatus als Rueckfall.
*/
function resolveStatusFilter(?string $value): string
{
if ($value === null || $value === '' || $value === 'all') {
return 'all';
}
if (isset(Roadmap::STATUS_GROUPS[$value])) {
return implode(',', Roadmap::STATUS_GROUPS[$value]);
}
return $value;
}