diff --git a/CHANGELOG.md b/CHANGELOG.md index f57947eb..d62b3e2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,20 @@ see the notices in the README. ### Added +- **Check out several parts of an assembly at once** (#415): `POST /api/v1/checkouts` + takes a list of revisions (by id, or item and code) and checks them out in one + transaction with a result per revision – the ones that can be taken are checked + out, the rest are reported with a reason (`not_found`, `released`, `in_review`, + `locked`, `forbidden`), so one released or locked part does not stop the others. + The rows are locked in a fixed order, so overlapping batches cannot deadlock and + every revision has one winner; each changed revision gets its own + `revision.checkout` audit record. A server batch rather than one call per part: + one round trip and one consistent moment for the whole set, with the rules of + the single check-out in one place. TeamCraft Desktop: *Check out parts…* on an + assembly (revision toolbar and *Structure* tab) shows the structure as a tree + with check boxes, state and lock holder (parts that cannot be checked out are + disabled with the reason), checks out the ticked ones in one step, makes their + files in the working folder writable and lists what was refused. - **BOM components picked by search** (#419, UX B5 of #408): *Add component* on the web BOM card lists matching items as you type part of their number, name or file name – with the preview image from the CAD file, latest diff --git a/README.md b/README.md index 472a3dc6..a1e5cd48 100755 --- a/README.md +++ b/README.md @@ -197,7 +197,9 @@ end-to-end tests against a real PostgreSQL. **Files and versions** - **Check-out / check-in** – exclusive locks per revision; a check-in based on - an outdated version is refused instead of overwriting it. + an outdated version is refused instead of overwriting it. Several parts of an + assembly can be checked out in one step to edit them in its context + (`POST /api/v1/checkouts`, a result per part). - **Versions and rollback** – every upload is a new version; download or restore any of them, history is never rewritten. - **Vault explorer** – project groups as folders with lock owners, files and diff --git a/desktop/README.md b/desktop/README.md index 28487899..2e186695 100755 --- a/desktop/README.md +++ b/desktop/README.md @@ -40,6 +40,7 @@ TeamCraft server – it is a client, not an offline copy. | SolidCraft design properties | The Files tab shows the `properties_line` the server sends with a design's file record under its name and the server's `property_mismatches` as the notice *Design properties differ from this revision* (`ui/js/revision.js` `propertyMismatchNotice`); *New item* from local files (`ui/js/dialogs.js` `createItemFromFiles`) and *Import a CAD folder* fill an empty description from the uploaded design's `properties.description` while the item is still checked out (`ui/js/folder-import.js` `describeFromDesign`, best effort) – #367 | | SolidCraft plugin bridge | The TeamCraft plugin inside SolidCraft has no network, so the app shares `/.teamcraft/solidcraft` with it (`src/scbridge.rs`, `ui/js/solidcraft-bridge.js`): every 30 s a heartbeat (`desktop.json`: the app runs, the server answers), on every Workspace refresh the state of the revision (`state-.json`: checked out by, local changes, released), every 5 s the plugin's requests (`request-..json`, one per revision and action) are picked up, checked (a revision of this working folder, a known action, fresh, small, a regular file) and removed: *open* shows the revision, *check out* asks first, *check in* opens the check-in dialog. Only for a working folder that exists; no secrets in the folder | | Check out and open | *Check out and open* on the revision toolbar (*Open in CAD* for one's own check-out) takes the lock, gets the files and opens the main CAD file; the chip next to it names the program (e.g. *Inventor 2026*). The program: the project group's default CAD program (`default_cad`, `default_cad_version` of `GET /api/v1/projects`) in its version, else its newest installed version; without a default, or for a file of another program, the newest installed version of the program that fits the file (`format_info.family`); else the system's default application. Installed programs are found by their install folders (Windows *Program Files*, SOLIDWORKS via `reg query`; macOS `/Applications`; FreeCAD on the Linux `PATH`), once per start – `src/cadlaunch.rs`, `ui/js/cad-open.js`; *Open* in the Files tab uses the same choice. On Windows an Inventor that already runs – the chosen installation, with the working folder's Inventor project active (the `.ipj` in the nearest folder up to the working folder root) – opens the file as a new window instead of a second instance (#350; asked through COM by a Windows PowerShell script: `GetActiveObject`, `InstallPath`, `ActiveDesignProject`, `Documents.Open`); otherwise a new instance starts and the message says why. After *Cancel* during the download, or with files that could not be copied, nothing is opened (#348, `ui/js/get-rules.js`). *Import CAD folder* detects the folder's program (Inventor with the release year read from the files, `folderimport::inventor_year`) and offers to set it as the group's default | +| Check out parts | *Check out parts…* on an assembly (revision toolbar, group **Lock**, and the *Structure* tab, #415): the structure as a tree with check boxes (`GET …/bom?expand=true&rule=latest` for the tree, `GET …/workset?rule=latest` for state, group and lock holder; parts the CAD files reference follow at the end); parts that are released, in review or held by someone else are disabled with the reason (`checkoutBlocker` in `ui/js/workspace.js`). The command `workspace_checkout_many` sends the ticked revisions in one `POST /api/v1/checkouts` (one transaction, a result per revision), then fetches the files of every revision now checked out – writable, an unchanged copy only loses its read-only flag, local changes are kept (`workspace::checkout_many`, summary `workspace::checkout_many_summary`); the refused ones are listed with the server's reason | | Preferred CAD program | The account setting of the web UI (`preferred_cad` of `GET /api/v1/me`, read at sign-in): when a revision has files of that program, the Files tab lists the native files of other CAD programs (`format_info.family`) in a collapsed *N files in other CAD formats (…)* group; neutral files (STEP, JT, STL, PDF, …) stay visible. Grouped in `ui/js/revision.js` (`groupByFamily`) with the same rule as the server's `cadformat::group_by_family`; display only | | Whole project groups locally | the download icon in the navigator (*Tools → Get Project Groups…*): copies the files of every item of the chosen groups – latest revision (also in work, the default since #355) or latest released – into the working folder with their folder structure; unchanged files are skipped, locally modified files kept, name clashes reported. For new team members or a fresh computer | | Import a CAD folder | the folder icon in the navigator (*Tools → Import CAD Folder…*): scans an existing folder (dry run: items, duplicate file names, skipped lock/backup files), then creates one item per part or assembly with the drawings and exports of the same name, project files in one document item, optional BOM lines from the assembly references, and checks every item in right after its files (assemblies once more after their BOM lines), so an interrupted import never leaves items checked out – a new run of the same folder also releases the check-outs an earlier, interrupted run left behind; a final report lists the new items and files, BOM lines, check-ins and problems (with *Open* for the top assembly); interrupted imports continue where they stopped (remembered per project group, so the same folder can also be imported into another group). Tutorial: *Help → How to Import a CAD Folder* | diff --git a/desktop/src/commands.rs b/desktop/src/commands.rs index b1364743..145d0447 100755 --- a/desktop/src/commands.rs +++ b/desktop/src/commands.rs @@ -749,6 +749,22 @@ pub async fn workspace_checkout( .await } +/// *Check out parts…* (issue #415): checks out the ticked revisions of an +/// assembly in one server call and makes their files in the working folder +/// writable; the result lists what the server refused and why. +#[tauri::command] +pub async fn workspace_checkout_many( + app: AppHandle, + state: State<'_, AppState>, + revisions: Vec, +) -> CmdResult { + usage(&state, |u| u.count("checkout")); + let api = signed_in_api(&state)?; + let (cancel, mut progress) = progress_events(&app, &state); + let root = workspace_root(&app, &state); + workspace::checkout_many(&api, &root, &revisions, &cancel, &mut progress).await +} + /// Copies the current files of a revision into the working folder without /// taking the lock (read-only on disk). #[tauri::command] diff --git a/desktop/src/main.rs b/desktop/src/main.rs index fd121692..ebd6d79b 100755 --- a/desktop/src/main.rs +++ b/desktop/src/main.rs @@ -264,6 +264,7 @@ fn main() { commands::assistant_cancel, commands::file_bytes, commands::workspace_checkout, + commands::workspace_checkout_many, commands::workspace_download, commands::workspace_get, commands::workspace_cancel, diff --git a/desktop/src/workspace.rs b/desktop/src/workspace.rs index 8329d65c..ca63336e 100755 --- a/desktop/src/workspace.rs +++ b/desktop/src/workspace.rs @@ -647,6 +647,152 @@ pub fn checkout_summary(r: &Downloaded, item: &str, code: &str) -> String { } } +/// A revision the user ticked in *Check out parts…* (issue #415). +#[derive(Clone, Debug, Deserialize)] +pub struct CheckoutPick { + pub project: Option, + pub item: String, + pub code: String, +} + +/// One server answer of `POST /checkouts` for one revision. +#[derive(Clone, Debug, Default, Deserialize, Serialize)] +pub struct CheckoutResult { + #[serde(default)] + pub revision_id: Option, + #[serde(default)] + pub item: String, + #[serde(default)] + pub code: String, + #[serde(default)] + pub ok: bool, + #[serde(default)] + pub already: bool, + #[serde(default)] + pub reason: Option, + #[serde(default)] + pub message: Option, + #[serde(default)] + pub checked_out_by_name: Option, +} + +/// The result of checking out several revisions: the server's answer per +/// revision and the files brought into the working folder. +#[derive(Debug, Default, Serialize)] +pub struct CheckedOutMany { + pub results: Vec, + pub refused: Vec, + pub files: Downloaded, + pub summary: String, +} + +/// Checks out several revisions in one server call (`POST /checkouts`, +/// one transaction, a result per revision) and copies the files of every +/// revision now checked out into the working folder – writable, because +/// the user holds their lock now (`layout::read_only_wanted`). A file that +/// was already here unchanged only loses its read-only flag; a changed one +/// is kept. The refused revisions are listed with the server's reason. +pub async fn checkout_many( + api: &Api, + root: &Path, + picks: &[CheckoutPick], + cancel: &AtomicBool, + progress: &mut (dyn FnMut(&Progress) + Send), +) -> Result { + let body = serde_json::json!({ + "revisions": picks + .iter() + .map(|p| serde_json::json!({ "item": p.item, "code": p.code })) + .collect::>(), + }); + let answer = api.json(Method::POST, "/checkouts", Some(&body)).await?; + // The server has committed the check-outs by now: an answer we cannot + // read is an error (refresh), never "nothing was checked out". + let results: Vec = serde_json::from_value(answer["revisions"].clone()) + .map_err(|e| { + ApiError::local(format!( + "Unexpected answer of POST /checkouts: {e}. Some parts may be checked out – refresh to see them." + )) + })?; + let mut files = Vec::new(); + let mut dirs = Vec::new(); + let mut failed = Vec::new(); + for r in results.iter().filter(|r| r.ok) { + let project = picks + .iter() + .find(|p| p.item.eq_ignore_ascii_case(&r.item) && p.code.eq_ignore_ascii_case(&r.code)) + .and_then(|p| p.project.clone()); + match revision_files(api, project.as_deref(), &r.item, &r.code).await { + Ok(rev) => { + dirs.push(main_dir( + root, + project.as_deref(), + &rev.files, + &rev.item_folder, + )); + files.extend(rev.files); + } + Err(e) => failed.push(format!("{}/{}: {e}", r.item, r.code)), + } + } + let mut report = fetch(api, root, &files, cancel, progress).await?; + report.failed.extend(failed); + report.revisions = results.iter().filter(|r| r.ok).count(); + report.dir = dirs + .into_iter() + .next() + .unwrap_or_else(|| root.to_path_buf()); + let refused: Vec = results.iter().filter(|r| !r.ok).cloned().collect(); + let summary = checkout_many_summary(report.revisions, &refused, &report); + Ok(CheckedOutMany { + results, + refused, + files: report, + summary, + }) +} + +/// The sentence after *Check out parts…*: how many revisions were checked +/// out, how many were refused, and what happened to their files. +pub fn checkout_many_summary( + checked_out: usize, + refused: &[CheckoutResult], + r: &Downloaded, +) -> String { + let mut head = match checked_out { + 0 => "Nothing was checked out".to_string(), + 1 => "Checked out 1 revision".to_string(), + n => format!("Checked out {n} revisions"), + }; + if !refused.is_empty() { + head.push_str(&format!("; {} refused", refused.len())); + } + let mut parts = Vec::new(); + if !r.downloaded.is_empty() { + parts.push(format!("{} file(s) downloaded", r.downloaded.len())); + } + if r.up_to_date > 0 { + parts.push(format!("{} up to date and writable now", r.up_to_date)); + } + if !r.kept.is_empty() { + parts.push(format!("{} kept (your local changes)", r.kept.len())); + } + if !r.clashes.is_empty() { + parts.push(format!( + "{} name clash(es), not overwritten", + r.clashes.len() + )); + } + if !r.failed.is_empty() { + parts.push(format!("{} failed", r.failed.len())); + } + if parts.is_empty() { + format!("{head}.") + } else { + format!("{head}. {}.", parts.join(", ")) + } +} + /// The files of a `workset` answer: all, those of the root revision, the /// root's project group and the number of revisions. fn workset_files(set: &Value) -> (Vec, Vec, Option, usize) { @@ -2170,6 +2316,40 @@ mod tests { ); } + #[test] + fn checkout_many_summaries() { + let refused = CheckoutResult { + item: "PRT-000003".into(), + code: "A".into(), + reason: Some("released".into()), + message: Some("PRT-000003/A is Released: revise it first.".into()), + ..CheckoutResult::default() + }; + assert_eq!( + checkout_many_summary(0, &[], &Downloaded::default()), + "Nothing was checked out." + ); + let files = Downloaded { + downloaded: vec!["ROVER/hub.prt".into()], + up_to_date: 2, + kept: vec!["ROVER/axle.prt".into()], + ..Downloaded::default() + }; + assert_eq!( + checkout_many_summary(3, std::slice::from_ref(&refused), &files), + "Checked out 3 revisions; 1 refused. 1 file(s) downloaded, \ + 2 up to date and writable now, 1 kept (your local changes)." + ); + assert_eq!( + checkout_many_summary(0, &[refused], &Downloaded::default()), + "Nothing was checked out; 1 refused." + ); + // the server answer is read leniently (missing fields = defaults) + let r: CheckoutResult = + serde_json::from_value(json!({ "item": "PRT-1", "code": "A", "ok": true })).unwrap(); + assert!(r.ok && !r.already && r.reason.is_none()); + } + #[test] fn decomposed_files_get_the_composed_name() { let dir = tempfile::tempdir().unwrap(); diff --git a/desktop/ui/js/revision.js b/desktop/ui/js/revision.js index 2ca76fd0..8aa54ecd 100755 --- a/desktop/ui/js/revision.js +++ b/desktop/ui/js/revision.js @@ -13,7 +13,7 @@ import { openTab, reloadActive, renderActive, renderTabs, table } from "./tabs.j import { agentButton } from "./agent.js"; import { groupImpacts, impactGroup, revChanges, revHistory, revReferences } from "./references.js"; import { graphBackControl, revGraph } from "./graph.js"; -import { addFilesDialog, checkinDialog, doCancelCheckout, doCheckout, doObsolete, doRevise, editDialog, filesHint, getStructureDialog, openFile, openWorkspaceFolder, releaseDialog, revViewer, revWorkspace } from "./workspace.js"; +import { addFilesDialog, checkinDialog, checkoutPartsDialog, doCancelCheckout, doCheckout, doObsolete, doRevise, editDialog, filesHint, getStructureDialog, openFile, openWorkspaceFolder, releaseDialog, revViewer, revWorkspace } from "./workspace.js"; import { openChange } from "./change.js"; import { openRequest, requestChangeDialog } from "./requests.js"; import { bomFromCadDialog, importBomDialog } from "./bom-import.js"; @@ -190,6 +190,12 @@ export function renderRevision(tab, body, toolbar) { ] : [ act("checkout", "Check out", "checkout", function () { doCheckout(tab); }, "Take the lock and copy the files into your workspace") ]; + // an assembly: check out several of its parts in one step (#415) + var isAssembly = rev.item_type === "assembly" || d.bom.length > 0; + if (isAssembly && canEdit()) { + lock.push(tool("Check out parts…", "checkout", function () { checkoutPartsDialog(tab); }, + { title: "Pick parts of this assembly and check them out together – their files become writable, so you can change them in the context of the assembly" })); + } var releaseButton = act("release", "Release…", "release", function () { releaseDialog(tab); }, "Create a change order with reviewers and submit it"); // The working copy changes while the tab stays open (the CAD program saves // into it): look again when the tab is shown from its cache or the window @@ -630,6 +636,10 @@ export function revStructure(tab, el) { type: "button", title: "Save the structure with this revision rule and all its files as ZIP", on: { click: function () { savePackage(rev, rule); } } }, "Pack and Go…"), + canEdit() && d.bom.length ? h("button.small", { + type: "button", title: "Pick parts of this structure and check them out together – their files become writable", + on: { click: function () { checkoutPartsDialog(tab); } } + }, "Check out parts…") : null, canEdit() ? h("button.small", { type: "button", disabled: !mine, title: mine ? "Add a component – search by number, name or file name" diff --git a/desktop/ui/js/workspace.js b/desktop/ui/js/workspace.js index 0cc8eb2b..ac0db3b3 100755 --- a/desktop/ui/js/workspace.js +++ b/desktop/ui/js/workspace.js @@ -4,7 +4,7 @@ import { $, api, badge, call, clear, confirmDialog, dialog, enc, errorText, field, h, invoke, lockBadge, materialField, run, setStatus, state, toast, tool } from "./core.js"; import { fmtDate, fmtSize, label } from "/static/shared/js/format.js"; -import { isCancelled, refreshWorklistCount, uploadLine } from "./shell.js"; +import { canEdit, canEditProject, isCancelled, refreshWorklistCount, uploadLine } from "./shell.js"; import { reloadActive, renderActive, table } from "./tabs.js"; import { PROGRAM_LABEL, cadPrograms, dd, exportProgram, exportStep, openRevision, previewFormat, revisionAbilities } from "./revision.js"; import { openChange } from "./change.js"; @@ -442,6 +442,125 @@ export function doCheckout(tab, then) { }, function () {}); } +/** Why a part of the structure cannot be ticked in *Check out parts…*, or + * null; `info` is its revision in the working set (state, lock, group). */ +export function checkoutBlocker(info) { + if (!info) return "Not in the working set"; + if (info.locked_by_me) return "Already checked out by you"; + if (!canEdit()) return "Viewers cannot check out"; + // the group by its code; one the app does not know is left to the server + var group = info.project_code ? state.projects.filter(function (p) { return p.code === info.project_code; })[0] : null; + if (group && !canEditProject(group.id)) return "Not a member of project group " + info.project_code; + if (info.state === "released") return "Released – revise it first"; + if (info.state === "in_review") return "In review"; + if (info.state !== "in_work") return label(info.state) + " – cannot be checked out"; + if (info.locked_by) return "Checked out by " + (info.locked_by_name || "another user"); + return null; +} + +/** "Check out parts…" (#415): the parts of an assembly as a tree with + * check boxes – state and lock holder per part, the ones that cannot be + * checked out disabled with the reason. One step checks out the ticked + * revisions (`POST /checkouts`, one transaction), makes their files in the + * working folder writable and lists what the server refused. */ +export function checkoutPartsDialog(tab) { + var rev = tab.data.rev; + var path = "/items/" + enc(rev.item_number) + "/revisions/" + enc(rev.code); + run("Loading the structure of " + rev.item_number + "/" + rev.code, function () { + return Promise.all([api("GET", path + "/bom?expand=true&rule=latest"), api("GET", path + "/workset?rule=latest")]); + }).then(function (r) { showCheckoutParts(tab, r[0], r[1]); }, function () {}); +} + +function showCheckoutParts(tab, tree, set) { + var rev = tab.data.rev; + var byId = {}; + (set.revisions || []).forEach(function (w) { byId[w.revision_id] = w; }); + var seen = {}, rows = [], boxes = []; + function row(depth, itemNumber, revision, name, note) { + var info = revision ? byId[revision.id] : null; + var blocker = revision ? checkoutBlocker(info) : note; + var box = h("input", { type: "checkbox", disabled: !!blocker, checked: !!(info && info.locked_by_me), + "aria-label": "Check out " + itemNumber + (revision ? "/" + revision.code : "") }); + if (!blocker) boxes.push({ input: box, pick: { project: info.project_code || null, item: itemNumber, code: revision.code } }); + var indent = h("span.indent"); + indent.style.width = (depth * 1.2) + "rem"; + rows.push({ + cells: [ + h("span", null, [indent, box, " ", h("span.mono", { text: itemNumber + (revision ? "/" + revision.code : "") })]), + name, + revision ? badge(revision.state) : "", + h("span" + (blocker ? ".muted" : ""), { text: blocker || (info && info.via === "reference" ? "Referenced by a CAD file" : "Can be checked out") }) + ] + }); + } + row(0, tree.root_item_number, tree.root, tree.root.name, null); + seen[tree.root.id] = true; + function walk(nodes, depth) { + (nodes || []).forEach(function (n) { + var r = n.revision; + if (n.restricted) { row(depth, "—", null, h("span.muted", { text: "Restricted item" }), "In a project group you are not a member of"); return; } + if (!r) { row(depth, n.item_number, null, "", "No revision"); return; } + // a part used more than once is offered at its first place only + if (seen[r.id]) return; + seen[r.id] = true; + row(depth, n.item_number, r, r.name, null); + walk(n.children, depth + 1); + }); + } + walk(tree.children, 1); + // parts the CAD files reference without a BOM line + (set.revisions || []).forEach(function (w) { + if (seen[w.revision_id]) return; + seen[w.revision_id] = true; + row(1, w.item_number, { id: w.revision_id, code: w.code, state: w.state }, w.name, null); + }); + function tickAll(on) { boxes.forEach(function (b) { b.input.checked = on; }); } + var body = h("div.stack", null, [ + h("p", { text: "Tick the parts you want to change in the context of the assembly. They are checked out in one step and their files in your working folder become writable; " + + "the others stay read-only. Parts that are released, in review or checked out by someone else cannot be ticked." }), + boxes.length ? h("div.row", null, [ + h("button.small", { type: "button", on: { click: function () { tickAll(true); } } }, "Tick all"), + h("button.small", { type: "button", on: { click: function () { tickAll(false); } } }, "Tick none") + ]) : h("p.notice", { text: "Nothing in this structure can be checked out by you right now." }), + table(["Item", "Name", "State", "Check-out"], rows) + ]); + dialog("Check out parts of " + rev.item_number + "/" + rev.code, body, [ + { label: "Cancel", onClick: function (d) { d.close(); } }, + { label: "Check out", primary: true, submit: true, onClick: function (d) { + var picks = boxes.filter(function (b) { return b.input.checked; }).map(function (b) { return b.pick; }); + if (!picks.length) { d.fail("Tick at least one part."); return; } + d.close(); + doCheckoutMany(picks); + } } + ], { wide: true }); +} + +/** Checks out `picks` ({project, item, code}) in one step and reports the + * result: a toast, and the refused revisions with the server's reason. */ +export function doCheckoutMany(picks) { + run("Checking out " + picks.length + (picks.length === 1 ? " revision" : " revisions"), function () { + return getting(call("workspace_checkout_many", { revisions: picks })); + }).then(function (r) { + toast(r.summary, r.refused.length ? "info" : null); + var f = r.files; + if (r.refused.length) { + dialog("Some parts were not checked out", h("div.stack", null, [ + h("p", { text: r.summary }), + h("ul.small", null, r.refused.map(function (o) { + return h("li", null, [h("span.mono", { text: o.item ? o.item + "/" + o.code : (o.revision_id || "?") }), " – " + (o.message || o.reason || "refused")]); + })), + f.kept.length || f.clashes.length || f.failed.length + ? h("p.small.muted", { text: "Files: " + f.kept.length + " kept (your local changes), " + f.clashes.length + " name clash(es), " + f.failed.length + " failed." }) : null + ]), [{ label: "Close", primary: true, submit: true, onClick: function (d) { d.close(); } }], { wide: true }); + } else if (f.kept.length || f.clashes.length || f.failed.length) { + reportDownload(f); + } + refreshStructure(); + reloadActive(); + refreshWorklistCount(); + }, function () {}); +} + // Cancelling one's own check-out takes effect at once (the local files stay // in the workspace); releasing someone else's lock is confirmed first. export function doCancelCheckout(tab) { diff --git a/docs/OPEN_WORK.md b/docs/OPEN_WORK.md index de6e8767..b7c2acbc 100755 --- a/docs/OPEN_WORK.md +++ b/docs/OPEN_WORK.md @@ -768,6 +768,10 @@ needs an issue with a reason first (see *Direction*). - [ ] Modern, quieter UI: fewer clicks, modal dialogs and legacy patterns on the common paths – the CAD-user review is #408: quick wins done (#409 check-in icon, #410 one vocabulary + glossary, #411 web check-out wording and *Get TeamCraft Desktop*, #412 preview at the top of the revision page, #413 no hash column, #414 revision vs + version explained), #421 section nav of the revision page, #417 right-click menus in the desktop app; left: the + daily CAD loop (#416, #418–#420) and onboarding (#422–#424); done: #415 check out several parts of an assembly at + once (`POST /api/v1/checkouts`, desktop *Check out parts…*) – open follow-up: *Revise and check out* for released + parts version explained), #421 section nav of the revision page, #417 right-click menus in the desktop app, #423 empty states that name the next step (web and desktop, by role, i18n catalogs), #420 thumbnails in the item list, search, vault explorer and the desktop Home views (left from #420: a revision with only STEP or mesh files gets diff --git a/docs/src/dev/threat-model.md b/docs/src/dev/threat-model.md index 4b4f51ef..2e751acf 100755 --- a/docs/src/dev/threat-model.md +++ b/docs/src/dev/threat-model.md @@ -102,6 +102,7 @@ enial of service, **E**levation of privilege. | A mutation leaves no trace | R | `audit::record` in the transaction of every service mutation; exceptions listed with a reason | `tests/architecture_guards.rs` `every_service_mutation_writes_an_audit_entry` (#96) | mitigated | | One request makes the server resolve an unbounded list (A2) | D | list lengths are checked before the list is resolved: the affected items of a change request at most `requests::MAX_ITEMS` (100) in the REST API, the MCP tool and again in `requests::create` (distinct items; repeated references are dropped before any lookup – before the CodeQL triage each repeat was looked up and inserted, ~150 000 times for a 2 MB body of one item); simulation results at most `MAX_RESULTS` (2000) per import; JSON bodies are capped by axum's default limit (2 MB) | `tests/change_requests.rs` `too_many_items_are_rejected_before_any_is_resolved` | mitigated for the lists found by CodeQL; no general audit of list fields | | The duplicate check of new files tells what a group holds (#359) | I, D | `POST /projects/{code}/file-check` reads only the requested group, after `projects::get_by_code` and `access::ensure_visible` (a hidden group answers like an unknown code, before the entries are validated); it compares only that group's current files under `access::item_visible`, so a caller learns nothing the file browser of that group would not show; at most 200 files per request and 20 matches per file and kind. The upload guard (`refuse_clash`, `refuse_same_name`) only refuses, inside the group of a revision the caller has checked out (`services::file_check`) | `tests/file_check.rs` `a_restricted_group_is_not_found_and_viewers_may_check`, `bad_requests_are_refused`; `tests/read_permissions.rs` `outsiders_see_nothing_of_a_restricted_group` (every route) | mitigated | +| The batch check-out tells what a hidden revision is, or deadlocks (#415) | I, D | `POST /checkouts` (`checkouts::checkout_many`) checks every revision like the single check-out; a revision the caller may not read answers `not_found` with the same message as a missing one, echoing only what the caller sent (never the item, name or holder; by code, not even the id) – a `200` that repeats the caller's own identifiers for `not_found`, by design; hidden revisions are resolved, deduplicated and left unlocked exactly like missing ones (the visibility guard runs before the lookup), so neither the number of results nor a row lock tells them apart. At most 500 entries; all visible rows are locked in one statement ordered by id, so overlapping batches wait instead of deadlocking, and every revision has one winner | `tests/checkout_batch.rs` `hidden_revisions_answer_like_missing_ones`, `overlapping_batches_give_every_revision_one_winner`, `bad_requests` (the route sweep of `tests/read_permissions.rs` does not reach it: its probe body has no `revisions` list) | mitigated | | The component picker suggests items of a restricted group (#419) | I | `GET /items/suggest` (web session only, no bearer token) and `GET /api/v1/items/suggest` call `items::suggest`, which is the item search (`items::search`) with the caller's actor and `access::item_visible`, so a name, file name or number of a hidden item never matches; at most 10 rows, nothing below 2 characters, the text cut at 200; preview images come from files of the readable latest revision (`/files/{id}/thumbnail` checks again). Adding the chosen line still needs the caller's own check-out (`bom::add`) | `tests/component_picker.rs` `items_of_a_restricted_group_never_appear_for_outsiders`, `suggestions_need_a_signed_in_user`, `a_line_needs_my_check_out_through_the_web_form_and_the_api` | mitigated | ## Single sign-on (OIDC) diff --git a/docs/src/guide/desktop.md b/docs/src/guide/desktop.md index 91588657..5e8accdf 100755 --- a/docs/src/guide/desktop.md +++ b/docs/src/guide/desktop.md @@ -34,6 +34,10 @@ check-outs and reviews, and a **local working folder**: locked; parts you changed locally, or whose place is taken by another file, are never overwritten and are listed in the report (*Settings → Workspace* switches this off); +* *Check out parts…* on an assembly (revision toolbar, group **Lock**, and + the *Structure* tab) checks out several of its parts at once, to change + them in the context of the assembly – see + [Check out parts of an assembly](#check-out-parts-of-an-assembly); * *Files / All items / Structure* in the navigator head: *Files* shows the folders and files of the project group as in its working folder (see below); *Structure* shows, per project @@ -342,7 +346,7 @@ shown or the app window gets the focus back – save in the CAD program, switch back, and *Check in…* is highlighted. * revision tab: **Lock** (*Check out*, or *Check in…* and *Cancel check-out* - / *Force unlock* while checked out) · **Open** (*Check out and open*, or *Open in CAD* for your own + / *Force unlock* while checked out; *Check out parts…* on an assembly) · **Open** (*Check out and open*, or *Open in CAD* for your own check-out, with the CAD program that will open the file next to it – see [Check out and open](#check-out-and-open)) · **Work** (*Edit attributes*, *Get…*, *Open folder*) · **Lifecycle** (*Release…*, *Revise*) · **Collaborate** @@ -476,6 +480,28 @@ Keyboard: `Ctrl/Cmd+N` new item, `Ctrl/Cmd+F` search, `F5` refresh, `Ctrl/Cmd+1/2/3/4/5` Home, Worklist, Changes, Agent, Projects, `Ctrl/Cmd+W` close the tab, `Ctrl/Cmd` + `+` / `-` / `0` (or `Ctrl` + mouse wheel) zoom. +## Check out parts of an assembly + +CAD users change parts **in the context of the assembly**. *Check out +parts…* (revision toolbar, group **Lock**, on an assembly, and the +*Structure* tab) shows the assembly's structure as a tree with check boxes: +every part with its state and who holds it. Parts that cannot be checked +out are greyed out with the reason – *Not a member of project group …*, +*Released – revise it first*, *In review*, *Checked out by …*, or +*Already checked out by you* (ticked). A +part used several times is offered once; parts the CAD files reference +without a BOM line follow at the end. *Tick all* / *Tick none* help with +large assemblies. + +*Check out* takes the locks of all ticked parts in **one step** on the +server (`POST /api/v1/checkouts`) and makes their files in the working +folder writable – missing or outdated files are downloaded, an unchanged +copy only loses its read-only flag, a copy you changed is kept – so the CAD +program can save them. What the server refused (someone took a part a +moment earlier, a part was released meanwhile, you are not a member of its +project group) is listed with the reason; the rest is checked out anyway. +The other parts stay read-only. + ## Check out and open *Check out and open* (revision toolbar, group **Open**) takes the lock, diff --git a/docs/src/reference/api.md b/docs/src/reference/api.md index 03832a96..3cd3d520 100755 --- a/docs/src/reference/api.md +++ b/docs/src/reference/api.md @@ -153,6 +153,45 @@ curl -s -X POST -H "$H" -H "Content-Type: application/json" \ $API/items/PRT-000001/revisions/A/cancel-checkout ``` +### Checking out several revisions at once + +`POST /checkouts` checks out several revisions in one step – the parts of +an assembly a CAD user wants to change in the assembly's context (#415). +Each entry names a revision by `id`, or by `item` and `code` (`latest` = the +newest revision); at most 500 entries, duplicates are answered once. + +```sh +curl -s -X POST -H "$H" -H "Content-Type: application/json" \ + -d '{"revisions": [{"item": "PRT-000011", "code": "A"}, {"item": "PRT-000012", "code": "B"}]}' \ + $API/checkouts +``` + +The answer has **a result per revision**, not all-or-nothing: the revisions +that can be taken are checked out, the others are reported, so one released +part or a part somebody else holds does not stop the rest. It is `200` with +`checked_out`, `refused`, a `summary` sentence and `revisions`, each with +`revision_id`, `item`, `code`, `name`, `ok`, `already` (you held it before: +no change, no audit record), `reason`, `message` and `checked_out_by_name` +(you when `ok`, the holder when `locked`). The reasons: + +| `reason` | Meaning | +|-------------|-------------------------------------------------------------------------------| +| `not_found` | Missing, or in a group you may not read – the same answer, without its name; only what you sent (`item` and `code`, or `revision_id` when you sent an id) comes back | +| `released` | Released or obsolete: revise it first | +| `in_review` | In review: it can be checked out again once the change returns it to in work | +| `locked` | Checked out by someone else (`checked_out_by_name`) | +| `forbidden` | You are not a member of the item's project group | + +The whole batch is one transaction: the rows are locked in a fixed order +(by id), so two batches over overlapping parts cannot deadlock – the second +waits, then reports what the first took as `locked`; every revision has one +winner. Each revision whose lock changed gets its own `revision.checkout` +audit record. Viewers get `403` for the whole request, more than 500 entries +or an entry without an id or an item and a code `400`. The choice of a server +batch over one `checkout` call per revision: one round trip, one consistent +moment for the whole set, and the per-revision rules stay those of +`revisions::checkout` in one place. + ### Concurrency: base versions and file status A check-in or upload can name the version each file is **based on** in the @@ -492,6 +531,7 @@ the caller cannot read are left out; a successor there is a placeholder with |-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Items | `GET/POST /items` (`class=`, `attr=` + `value=`, `result=` + `result_name=` filters), `GET /items/duplicates?name=&type=` (likely duplicates by name, before creating), `GET /items/suggest?q=&limit=` (component picker of the BOM, #419: readable items whose number, name, description, attributes or file name match – at most 10, nothing for fewer than 2 characters – as `{"items": [{id, number, item_type, unit, name, latest_code, latest_state, project_code, matched_file, thumbnail_file_id}]}`; `thumbnail_file_id` is a file for `GET /files/{id}/thumbnail`; the web UI has the same list at `/items/suggest` for its session), `POST /items/bulk` (`{"action": "revise"\|"obsolete", "items": [number]}`: the latest revision of up to 200 items, each in its own transaction, outcome per item), `GET/PATCH /items/{number}` (classification, unit, project, folder), `where-used` (`levels=1…25` for parents of parents), `interchange`, `alternates`, `supersession`, `replace`, history, impacts, watch | | Attributes | `GET /attributes` (`all=true`: also inactive), `POST /attributes`, `PATCH /attributes/{key}` (admins); values in `attributes` of a revision | +| Revisions | `GET/PATCH /items/{number}/revisions/{code\|latest}`, `checkout`, `checkin`, `cancel-checkout`, `file-status`, `revise`, `obsolete`; `POST /checkouts` (several at once, a result per revision) | | Revisions | `GET/PATCH /items/{number}/revisions/{code\|latest}`, `checkout`, `checkin`, `cancel-checkout`, `file-status`, `revise`, `obsolete`; `GET /revisions/{id}/thumbnail` – the picture of the main model (see below) | | Worklist | `GET /worklist` (check-outs, reviews, impacts and `impact_groups`, statistics), `POST /worklist/checkin-all` | | Users | `GET /users/{id}/holdings` – what a user still holds (check-outs, open change orders, pending reviews, change requests, owned items, memberships, tokens), as the caller may see it: administrators, and group managers for the groups they manage; `POST /users/{id}/offboard` `{hand_over_to?: username, release_checkouts?, revoke_tokens?, confirm_no_manager?}` – administrators deactivate a leaver in one step (see [When someone leaves](../admin/users.md#when-someone-leaves)) | diff --git a/src/api/concurrency_api.rs b/src/api/concurrency_api.rs index d606ea7d..01625e86 100755 --- a/src/api/concurrency_api.rs +++ b/src/api/concurrency_api.rs @@ -62,3 +62,28 @@ pub(super) async fn checkin_all( "revisions": outcomes, }))) } + +#[derive(Deserialize)] +pub(super) struct CheckoutManyBody { + /// `[{id}]` or `[{item, code}]` (code `latest` = the newest revision). + revisions: Vec, +} + +/// Checks out several revisions at once (issue #415, the parts of an +/// assembly). One transaction with a result per revision: the ones that can +/// be taken are checked out, the rest come back with `ok = false`, a +/// `reason` (`not_found`, `released`, `in_review`, `locked`, `forbidden`) +/// and a `message` – a refused part does not stop the others. +pub(super) async fn checkout_many( + State(st): State, + ApiUser(me): ApiUser, + ApiJson(body): ApiJson, +) -> AppResult> { + let outcomes = checkouts::checkout_many(&st.db, &me, &body.revisions).await?; + Ok(Json(json!({ + "checked_out": outcomes.iter().filter(|o| o.ok).count(), + "refused": outcomes.iter().filter(|o| !o.ok).count(), + "summary": checkouts::checkout_summary(&outcomes), + "revisions": outcomes, + }))) +} diff --git a/src/api/mod.rs b/src/api/mod.rs index 604ccd8d..14678593 100755 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -83,6 +83,7 @@ pub fn router(state: &AppState) -> Router { .route("/users/{id}/offboard", post(user_offboard)) .route("/worklist", get(worklist)) .route("/worklist/checkin-all", post(checkin_all)) + .route("/checkouts", post(checkout_many)) .route("/mcp", post(crate::mcp::http).get(crate::mcp::http_get)) .route("/assistant", get(assistant_info).post(assistant_ask)) .route( @@ -574,6 +575,7 @@ async fn index() -> Json { "GET /api/v1/items/{number}/revisions/{code|latest}", "PATCH /api/v1/items/{number}/revisions/{code} {name?, description?, material?, mass_kg?, unit_cost?, attributes?: {key: value|null}}", "POST /api/v1/items/{number}/revisions/{code}/checkout", + "POST /api/v1/checkouts {revisions: [{id} | {item, code}]} – check out several revisions in one transaction; a result per revision (ok, reason: not_found | released | in_review | locked | forbidden, message, checked_out_by_name)", "POST /api/v1/items/{number}/revisions/{code}/checkin optional multipart: 'file' (new versions), 'comment', 'bases' = {\"name\": version | sha256} → 409 if a file moved on, 'folder' or 'folders' = {\"name\": \"folder\"}, 'uploads' = [upload id] (chunked uploads)", "POST /api/v1/uploads {item, revision, filename, size, sha256?, content_type?, base?, folder?, refuse_clash?, refuse_same_name?} – start a chunked, resumable upload (checked-out revision); the refuse flags are the duplicate guard of the multipart upload, applied when the file is stored", "GET /api/v1/uploads/{id} state and offset to resume from (also HEAD: Upload-Offset, Upload-Length)", diff --git a/src/services/checkouts.rs b/src/services/checkouts.rs index e4c59ebf..f0a78d86 100755 --- a/src/services/checkouts.rs +++ b/src/services/checkouts.rs @@ -6,10 +6,11 @@ //! optimistic base-version guard of uploads (`files::store_uploads`) live in //! their own services; this module combines them for the workspace views. -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; +use serde_json::json; use sqlx::PgPool; use uuid::Uuid; @@ -18,7 +19,7 @@ use crate::{ domain::{self, BaseVersion, FileSyncState, ServerFile}, error::{AppError, AppResult}, models::Revision, - services::{access, files, projects, revisions}, + services::{access, audit, files, projects, revisions}, }; /// A file of the client's workspace, as the client reports it. @@ -366,6 +367,351 @@ pub async fn check_in_all( Ok(outcomes) } +/// Most revisions one [`checkout_many`] call takes (400 above it). +pub const MAX_CHECKOUT_BATCH: usize = 500; + +/// One revision a client asks [`checkout_many`] to check out: by its id, or +/// by item number and revision code (`latest` = the newest revision). +#[derive(Clone, Debug, Default, Deserialize)] +pub struct CheckoutTarget { + #[serde(default)] + pub id: Option, + #[serde(default)] + pub item: Option, + #[serde(default)] + pub code: Option, +} + +/// Why [`checkout_many`] did not check out one revision. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum CheckoutRefusal { + /// Missing, or hidden from the actor (answered alike, nothing leaks). + NotFound, + /// Released or obsolete: revise it first. + Released, + /// In review: the change has to come back to *in work* first. + InReview, + /// Checked out by somebody else (`checked_out_by_name`). + Locked, + /// Not a member of the item's project group. + Forbidden, +} + +/// The result of [`checkout_many`] for one requested revision. +#[derive(Clone, Debug, Serialize)] +pub struct CheckoutOutcome { + /// The requested id, or the revision found by item and code (never for + /// a revision the actor may not read). + pub revision_id: Option, + /// Item number (as requested when the revision was not found). + pub item: String, + pub code: String, + pub name: Option, + pub ok: bool, + /// The actor already held the check-out (no change, no audit record). + pub already: bool, + pub reason: Option, + /// The sentence to show for a refusal. + pub message: Option, + /// Who holds the check-out now: the actor when `ok`, the other user + /// when `reason` = `locked`. + pub checked_out_by_name: Option, +} + +impl CheckoutOutcome { + fn not_found(slot: &BatchSlot) -> CheckoutOutcome { + CheckoutOutcome { + revision_id: slot.requested_id, + item: slot.item.clone(), + code: slot.code.clone(), + name: None, + ok: false, + already: false, + reason: Some(CheckoutRefusal::NotFound), + message: Some(access::not_found_revision().to_string()), + checked_out_by_name: None, + } + } + + fn of(rev: &Revision) -> CheckoutOutcome { + CheckoutOutcome { + revision_id: Some(rev.id), + item: rev.item_number.clone(), + code: rev.code.clone(), + name: Some(rev.name.clone()), + ok: false, + already: false, + reason: None, + message: None, + checked_out_by_name: rev.checked_out_by_name.clone(), + } + } +} + +/// One entry of the request after resolving item and code. +struct BatchSlot { + requested_id: Option, + item: String, + code: String, + id: Option, +} + +/// Why `actor` may not check out `rev` – the rules of +/// `revisions::ensure_checkout_possible`, sorted into a [`CheckoutRefusal`] +/// instead of an error, so one refusal does not end the batch. +fn refusal(rev: &Revision, actor: &Actor) -> Option<(CheckoutRefusal, String)> { + let err = revisions::ensure_checkout_possible(rev, actor).err()?; + let state = revisions::state_of(rev); + Some(match err { + AppError::NotFound(m) => (CheckoutRefusal::NotFound, m), + AppError::Conflict(_) if state == domain::LifecycleState::InReview => ( + CheckoutRefusal::InReview, + format!( + "{} is in review; it can be checked out again once the change returns it to in work.", + revisions::label(rev) + ), + ), + AppError::Conflict(_) if !state.is_editable() => ( + CheckoutRefusal::Released, + format!( + "{} is {}: revise it first.", + revisions::label(rev), + state.label() + ), + ), + AppError::Conflict(m) => (CheckoutRefusal::Locked, m), + other => (CheckoutRefusal::Forbidden, other.to_string()), + }) +} + +/// Looks up the id of a revision the actor may read, by item number and +/// code (`latest` = the newest revision). Read-only; a hidden revision is +/// `None`, exactly like a missing one, so the caller deduplicates and locks +/// only visible rows (nothing about a hidden revision reaches the answer or +/// its timing). +async fn visible_revision_id_by_code( + pool: &PgPool, + actor: &Actor, + item: &str, + code: &str, +) -> AppResult> { + Ok(sqlx::query_scalar(&format!( + "SELECT r.id FROM revisions r JOIN items i ON i.id = r.item_id + WHERE i.number = $1 AND ($2 = 'LATEST' OR r.code = $2) AND {} + ORDER BY r.seq DESC + LIMIT 1", + access::item_visible("i", 3) + )) + .bind(item) + .bind(code) + .bind(&actor.hidden_projects) + .fetch_optional(pool) + .await?) +} + +/// `id` if it names a revision the actor may read, else `None` (missing and +/// hidden alike). +async fn visible_revision_id(pool: &PgPool, actor: &Actor, id: Uuid) -> AppResult> { + Ok(sqlx::query_scalar(&format!( + "SELECT r.id FROM revisions r JOIN items i ON i.id = r.item_id + WHERE r.id = $1 AND {}", + access::item_visible("i", 2) + )) + .bind(id) + .bind(&actor.hidden_projects) + .fetch_optional(pool) + .await?) +} + +/// Checks out several revisions in one step – the parts of an assembly a +/// CAD user wants to edit in its context (issue #415). The result has one +/// entry per requested revision (duplicates once, in request order): the +/// ones the actor may take are checked out, the rest are reported with a +/// [`CheckoutRefusal`] instead of failing the whole request, so a released +/// part or a part somebody else holds does not stop the others. +/// +/// # Invariants +/// +/// * **Permission:** CAD editor (403 for the whole request otherwise). Per +/// revision the rules of `revisions::checkout`: visible ("not found" +/// otherwise, the same answer as a missing revision, without its item or +/// name), in a group the actor may edit (`forbidden`), in work +/// (`released`, `in_review`) and not checked out by someone else +/// (`locked`, with the holder's name). +/// * **Bounds:** at most [`MAX_CHECKOUT_BATCH`] entries (400); every entry +/// names an id or an item and a code (400). +/// * **Locks:** the requested revisions the actor may read (resolved and +/// deduplicated under the visibility guard, so a hidden row is neither +/// locked nor collapsed with another entry) in one `SELECT … FOR UPDATE` +/// ordered by id, so two batches over overlapping sets cannot deadlock: +/// the second waits, then reports the revisions the first took as +/// `locked` – each revision has one winner. +/// * **Audit:** `revision.checkout` for every revision whose lock changed; +/// nothing for one the actor already held. +/// * **Notifications / webhooks:** none. +/// * **Atomic:** one transaction for the whole batch. +pub async fn checkout_many( + pool: &PgPool, + actor: &Actor, + targets: &[CheckoutTarget], +) -> AppResult> { + actor.require(domain::Role::Editor)?; + if targets.len() > MAX_CHECKOUT_BATCH { + return Err(AppError::BadRequest(format!( + "At most {MAX_CHECKOUT_BATCH} revisions can be checked out at once." + ))); + } + let mut slots: Vec = Vec::with_capacity(targets.len()); + let mut seen: HashSet = HashSet::new(); + for t in targets { + let slot = if let Some(id) = t.id { + BatchSlot { + requested_id: Some(id), + item: String::new(), + code: String::new(), + id: visible_revision_id(pool, actor, id).await?, + } + } else { + let item = t.item.as_deref().unwrap_or("").trim().to_ascii_uppercase(); + let code = t.code.as_deref().unwrap_or("").trim().to_ascii_uppercase(); + if item.is_empty() || code.is_empty() { + return Err(AppError::BadRequest( + "Every revision needs an id or an item and a code.".into(), + )); + } + let id = visible_revision_id_by_code(pool, actor, &item, &code).await?; + BatchSlot { + requested_id: None, + item, + code, + id, + } + }; + // Only visible revisions are deduplicated by their id; a missing or + // hidden one by what was sent, so both collapse (or not) alike. + let key = match (slot.id, slot.requested_id) { + (Some(id), _) | (None, Some(id)) => id.to_string(), + (None, None) => format!("{}/{}", slot.item, slot.code), + }; + if seen.insert(key) { + slots.push(slot); + } + } + let mut ids: Vec = slots.iter().filter_map(|s| s.id).collect(); + ids.sort(); + if ids.is_empty() { + return Ok(slots.iter().map(CheckoutOutcome::not_found).collect()); + } + + let mut tx = pool.begin().await?; + // Lock first, in a fixed order, then read: the read is a new statement + // and sees what a batch we waited for committed, including the joined + // holder name (a locking read with joins could return a stale one). + sqlx::query("SELECT id FROM revisions WHERE id = ANY($1) ORDER BY id FOR UPDATE") + .bind(&ids) + .execute(&mut *tx) + .await?; + let rows: Vec = sqlx::query_as::<_, Revision>(&format!( + "{} WHERE r.id = ANY($1)", + revisions::REVISION_SELECT + )) + .bind(&ids) + .fetch_all(&mut *tx) + .await?; + let by_id: HashMap = rows.iter().map(|r| (r.id, r)).collect(); + + let mut outcomes = Vec::with_capacity(slots.len()); + let mut take: Vec<&Revision> = Vec::new(); + for slot in &slots { + let Some(rev) = slot.id.and_then(|id| by_id.get(&id).copied()) else { + outcomes.push(CheckoutOutcome::not_found(slot)); + continue; + }; + if !actor.can_see_project(rev.project_id) { + outcomes.push(CheckoutOutcome::not_found(slot)); + continue; + } + let mut outcome = CheckoutOutcome::of(rev); + match refusal(rev, actor) { + Some((CheckoutRefusal::NotFound, _)) => { + outcomes.push(CheckoutOutcome::not_found(slot)); + continue; + } + Some((reason, message)) => { + outcome.reason = Some(reason); + outcome.message = Some(message); + if reason != CheckoutRefusal::Locked { + outcome.checked_out_by_name = None; + } + } + None => { + outcome.ok = true; + outcome.already = rev.checked_out_by == Some(actor.id); + outcome.checked_out_by_name = Some(actor.display_name.clone()); + if !outcome.already { + take.push(rev); + } + } + } + outcomes.push(outcome); + } + + if !take.is_empty() { + let take_ids: Vec = take.iter().map(|r| r.id).collect(); + sqlx::query( + "UPDATE revisions SET checked_out_by = $2, checked_out_at = now() + WHERE id = ANY($1)", + ) + .bind(&take_ids) + .bind(actor.id) + .execute(&mut *tx) + .await?; + for rev in &take { + audit::record( + &mut tx, + Some(actor), + "revision.checkout", + "revision", + Some(rev.id), + format!("Checked out {}", revisions::label(rev)), + json!({ "item_id": rev.item_id, "batch": true }), + ) + .await?; + } + } + tx.commit().await?; + Ok(outcomes) +} + +/// One line about a [`checkout_many`] result: how many were checked out and +/// which were refused, with the reason. +pub fn checkout_summary(outcomes: &[CheckoutOutcome]) -> String { + let ok = outcomes.iter().filter(|o| o.ok).count(); + let refused: Vec = outcomes + .iter() + .filter(|o| !o.ok) + .map(|o| { + let what = if o.item.is_empty() { + o.revision_id.map(|id| id.to_string()).unwrap_or_default() + } else { + format!("{}/{}", o.item, o.code) + }; + format!("{what} ({})", o.message.as_deref().unwrap_or("refused")) + }) + .collect(); + let head = match ok { + 0 if refused.is_empty() => return "Nothing to check out.".into(), + 1 => "Checked out 1 revision".to_string(), + n => format!("Checked out {n} revisions"), + }; + if refused.is_empty() { + format!("{head}.") + } else { + format!("{head}; {} refused: {}", refused.len(), refused.join(", ")) + } +} + /// Most check-outs one [`release_held`] run releases. pub const MAX_RELEASE: i64 = 1000; @@ -575,6 +921,59 @@ mod tests { ); } + fn taken(number: &str, refusal: Option<(CheckoutRefusal, &str)>) -> CheckoutOutcome { + CheckoutOutcome { + revision_id: None, + item: number.into(), + code: "A".into(), + name: None, + ok: refusal.is_none(), + already: false, + reason: refusal.map(|r| r.0), + message: refusal.map(|r| r.1.to_string()), + checked_out_by_name: None, + } + } + + #[test] + fn checkout_summaries() { + assert_eq!(checkout_summary(&[]), "Nothing to check out."); + assert_eq!( + checkout_summary(&[taken("PRT-1", None)]), + "Checked out 1 revision." + ); + assert_eq!( + checkout_summary(&[ + taken("PRT-1", None), + taken("PRT-2", None), + taken( + "PRT-3", + Some(( + CheckoutRefusal::Released, + "PRT-3/A is Released: revise it first." + )) + ), + ]), + "Checked out 2 revisions; 1 refused: PRT-3/A (PRT-3/A is Released: revise it first.)" + ); + let hidden = CheckoutOutcome { + revision_id: Some(Uuid::nil()), + item: String::new(), + ..taken("", Some((CheckoutRefusal::NotFound, "Revision not found."))) + }; + assert_eq!( + checkout_summary(&[hidden]), + format!( + "Checked out 0 revisions; 1 refused: {} (Revision not found.)", + Uuid::nil() + ) + ); + assert_eq!( + serde_json::to_value(CheckoutRefusal::InReview).unwrap(), + "in_review" + ); + } + #[test] fn client_bases() { let c = ClientFile { diff --git a/tests/checkout_batch.rs b/tests/checkout_batch.rs new file mode 100755 index 00000000..0c0510cb --- /dev/null +++ b/tests/checkout_batch.rs @@ -0,0 +1,326 @@ +//! Checking out several revisions at once (`POST /api/v1/checkouts`, issue +//! #415): a result per revision, refusals do not stop the others, hidden +//! revisions answer like missing ones, overlapping batches give every +//! revision one winner, and only changed revisions are audited. + +mod common; + +use axum::http::{Method, StatusCode}; +use serde_json::{json, Value}; +use teamcraft::domain::Role; +use uuid::Uuid; + +macro_rules! app_or_skip { + () => { + match common::setup().await { + Some(app) => app, + None => return, + } + }; +} + +/// Creates a part in `project` and checks it in again, so nobody holds it. +async fn free_part(app: &common::TestApp, token: &str, name: &str, project: &str) -> String { + let number = app + .create_item( + token, + json!({ "item_type": "part", "name": name, "project": project }), + ) + .await; + let r = app + .api( + Method::POST, + &format!("/api/v1/items/{number}/revisions/A/checkin"), + token, + None, + ) + .await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + number +} + +async fn revision_id(app: &common::TestApp, number: &str) -> Uuid { + sqlx::query_scalar( + "SELECT r.id FROM revisions r JOIN items i ON i.id = r.item_id + WHERE i.number = $1 AND r.code = 'A'", + ) + .bind(number) + .fetch_one(&app.pool) + .await + .expect("revision exists") +} + +async fn holder(app: &common::TestApp, number: &str) -> Option { + sqlx::query_scalar( + "SELECT u.username FROM revisions r JOIN items i ON i.id = r.item_id + LEFT JOIN users u ON u.id = r.checked_out_by + WHERE i.number = $1 AND r.code = 'A'", + ) + .bind(number) + .fetch_one(&app.pool) + .await + .expect("revision exists") +} + +async fn checkout_audits(app: &common::TestApp, number: &str) -> usize { + let id = revision_id(app, number).await; + app.audit_actions(id) + .await + .iter() + .filter(|a| *a == "revision.checkout") + .count() +} + +async fn batch(app: &common::TestApp, token: &str, revisions: Value) -> common::Response { + app.api( + Method::POST, + "/api/v1/checkouts", + token, + Some(json!({ "revisions": revisions })), + ) + .await +} + +fn by_item<'a>(body: &'a Value, item: &str) -> &'a Value { + body["revisions"] + .as_array() + .unwrap() + .iter() + .find(|o| o["item"] == item) + .unwrap_or_else(|| panic!("no outcome for {item}: {body}")) +} + +fn refs>(numbers: &[S]) -> Value { + Value::Array( + numbers + .iter() + .map(|n| json!({ "item": n.as_ref(), "code": "A" })) + .collect(), + ) +} + +#[tokio::test] +async fn checks_out_the_free_parts_and_reports_the_rest() { + let app = app_or_skip!(); + let (_, max) = app.user_in("max", Role::Editor, &["ROVER"]).await; + let (_, erika) = app.user_in("erika", Role::Editor, &["ROVER"]).await; + let (_, eva) = app.user_in("eva", Role::Editor, &["ROVER"]).await; + + let free = free_part(&app, &max, "Wheel hub", "ROVER").await; + let mine = free_part(&app, &max, "Axle", "ROVER").await; + let held = free_part(&app, &max, "Bracket", "ROVER").await; + let released = free_part(&app, &max, "Cover", "ROVER").await; + let in_review = free_part(&app, &max, "Spacer", "ROVER").await; + app.release(&max, ("eva", &eva), &[released.as_str()]).await; + app.submit_change(&max, "Review", &[in_review.as_str()], &["eva"]) + .await; + for (number, token) in [(&mine, &max), (&held, &erika)] { + let r = app + .api( + Method::POST, + &format!("/api/v1/items/{number}/revisions/A/checkout"), + token, + None, + ) + .await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + } + let audits_mine = checkout_audits(&app, &mine).await; + let audits_free = checkout_audits(&app, &free).await; + + let mut list = refs(&[&free, &mine, &held, &released, &in_review]); + // a duplicate (once by code, once by id) is answered once + let free_id = revision_id(&app, &free).await; + list.as_array_mut().unwrap().push(json!({ "id": free_id })); + let r = batch(&app, &max, list).await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + let body = r.json(); + assert_eq!(body["revisions"].as_array().unwrap().len(), 5, "{body}"); + assert_eq!(body["checked_out"], 2, "{body}"); + assert_eq!(body["refused"], 3, "{body}"); + + let o = by_item(&body, &free); + assert_eq!(o["ok"], true); + assert_eq!(o["already"], false); + assert_eq!(o["revision_id"], json!(free_id)); + assert_eq!(o["checked_out_by_name"], "max (test)"); + let o = by_item(&body, &mine); + assert_eq!(o["ok"], true); + assert_eq!(o["already"], true, "held by the actor before: {o}"); + let o = by_item(&body, &held); + assert_eq!(o["ok"], false); + assert_eq!(o["reason"], "locked"); + assert_eq!(o["checked_out_by_name"], "erika (test)"); + let o = by_item(&body, &released); + assert_eq!(o["reason"], "released"); + assert!( + o["message"].as_str().unwrap().contains("revise it first"), + "{o}" + ); + assert!(o["checked_out_by_name"].is_null()); + let o = by_item(&body, &in_review); + assert_eq!(o["reason"], "in_review"); + let summary = body["summary"].as_str().unwrap(); + assert!( + summary.starts_with("Checked out 2 revisions; 3 refused"), + "{summary}" + ); + + // the database follows the result + assert_eq!(holder(&app, &free).await.as_deref(), Some("max")); + assert_eq!(holder(&app, &mine).await.as_deref(), Some("max")); + assert_eq!(holder(&app, &held).await.as_deref(), Some("erika")); + assert_eq!(holder(&app, &released).await, None); + assert_eq!(holder(&app, &in_review).await, None); + + // audit: one record for the revision that changed, none for the one max already held + assert_eq!(checkout_audits(&app, &free).await, audits_free + 1); + assert_eq!(checkout_audits(&app, &mine).await, audits_mine); + + // running the same batch again changes nothing and audits nothing + let r = batch(&app, &max, refs(&[&free, &mine])).await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + assert_eq!(by_item(&r.json(), &free)["already"], true); + assert_eq!(checkout_audits(&app, &free).await, audits_free + 1); +} + +#[tokio::test] +async fn permissions_viewers_and_other_groups() { + let app = app_or_skip!(); + let (_, max) = app.user_in("max", Role::Editor, &["ROVER"]).await; + let (_, vic) = app.user_in("vic", Role::Viewer, &["ROVER"]).await; + let (_, olga) = app.user_in("olga", Role::Editor, &["ARM"]).await; + let rover = free_part(&app, &max, "Wheel hub", "ROVER").await; + let arm = free_part(&app, &olga, "Gripper", "ARM").await; + + // a viewer may not check out anything: the whole request is refused + let r = batch(&app, &vic, refs(&[&rover])).await; + assert_eq!(r.status, StatusCode::FORBIDDEN, "{}", r.text()); + assert_eq!(holder(&app, &rover).await, None); + + // an editor of another group: forbidden for that part, the own part goes through + let r = batch(&app, &olga, refs(&[&rover, &arm])).await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + let body = r.json(); + assert_eq!(by_item(&body, &rover)["reason"], "forbidden"); + assert!(by_item(&body, &rover)["message"] + .as_str() + .unwrap() + .contains("ROVER")); + assert_eq!(by_item(&body, &arm)["ok"], true); + assert_eq!(holder(&app, &rover).await, None); + assert_eq!(holder(&app, &arm).await.as_deref(), Some("olga")); +} + +#[tokio::test] +async fn bad_requests() { + let app = app_or_skip!(); + let (_, max) = app.user_in("max", Role::Editor, &["ROVER"]).await; + let r = batch(&app, &max, json!([{ "item": "PRT-000001" }])).await; + assert_eq!(r.status, StatusCode::BAD_REQUEST, "{}", r.text()); + let too_many: Vec = (0..501).map(|_| json!({ "id": Uuid::new_v4() })).collect(); + let r = batch(&app, &max, Value::Array(too_many)).await; + assert_eq!(r.status, StatusCode::BAD_REQUEST, "{}", r.text()); + let r = batch(&app, &max, json!([])).await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + assert_eq!(r.json()["summary"], "Nothing to check out."); +} + +#[tokio::test] +async fn hidden_revisions_answer_like_missing_ones() { + let app = app_or_skip!(); + let (_, max) = app.user_in("max", Role::Editor, &["ROVER"]).await; + let (_, erika) = app.user("erika", Role::Editor).await; + let r = app + .api( + Method::POST, + "/api/v1/projects", + &erika, + Some(json!({ "code": "NTK", "name": "Need to know", "visibility": "restricted" })), + ) + .await; + assert_eq!(r.status, StatusCode::CREATED, "{}", r.text()); + let secret = free_part(&app, &erika, "Secret part", "NTK").await; + let secret_id = revision_id(&app, &secret).await; + let missing_id = Uuid::new_v4(); + + let r = batch( + &app, + &max, + json!([ + { "item": secret, "code": "A" }, + { "item": "PRT-999999", "code": "A" }, + { "id": secret_id }, + { "id": missing_id }, + ]), + ) + .await; + assert_eq!(r.status, StatusCode::OK, "{}", r.text()); + let body = r.json(); + let list = body["revisions"].as_array().unwrap(); + assert_eq!(list.len(), 4, "{body}"); + for o in list { + assert_eq!(o["ok"], false, "{o}"); + assert_eq!(o["reason"], "not_found", "{o}"); + assert_eq!(o["message"], "Revision not found.", "{o}"); + assert!(o["name"].is_null(), "no name of a hidden revision: {o}"); + assert!(o["checked_out_by_name"].is_null(), "{o}"); + } + // by code: only what was asked comes back, never the hidden revision's id + assert_eq!(list[0]["item"], json!(secret)); + assert!(list[0]["revision_id"].is_null(), "{}", list[0]); + assert!(list[1]["revision_id"].is_null(), "{}", list[1]); + // by id: the id as asked, nothing more – the same shape as a missing one + assert_eq!(list[2]["revision_id"], json!(secret_id)); + assert_eq!(list[2]["item"], ""); + assert_eq!(list[3]["revision_id"], json!(missing_id)); + assert_eq!(list[3]["item"], ""); + assert_eq!(holder(&app, &secret).await, None); +} + +#[tokio::test] +async fn overlapping_batches_give_every_revision_one_winner() { + let app = app_or_skip!(); + let (_, max) = app.user_in("max", Role::Editor, &["ROVER"]).await; + let (_, erika) = app.user_in("erika", Role::Editor, &["ROVER"]).await; + let mut parts = Vec::new(); + for name in ["A", "B", "C", "D", "E", "F"] { + parts.push(free_part(&app, &max, &format!("Part {name}"), "ROVER").await); + } + let p: Vec<&str> = parts.iter().map(String::as_str).collect(); + let mut before = std::collections::HashMap::new(); + for n in &p { + before.insert(n.to_string(), checkout_audits(&app, n).await); + } + // max: A B C D, erika: D C B E F – in a different order on purpose + let max_set = refs(&[p[0], p[1], p[2], p[3]]); + let erika_set = refs(&[p[3], p[2], p[1], p[4], p[5]]); + let (rm, re) = tokio::join!(batch(&app, &max, max_set), batch(&app, &erika, erika_set)); + assert_eq!(rm.status, StatusCode::OK, "{}", rm.text()); + assert_eq!(re.status, StatusCode::OK, "{}", re.text()); + let (bm, be) = (rm.json(), re.json()); + + // the parts only one of them asked for go to that one + assert_eq!(by_item(&bm, p[0])["ok"], true); + assert_eq!(by_item(&be, p[4])["ok"], true); + assert_eq!(by_item(&be, p[5])["ok"], true); + // the overlap: exactly one winner per part, the other side sees it locked + for n in [p[1], p[2], p[3]] { + let (om, oe) = (by_item(&bm, n), by_item(&be, n)); + let max_won = om["ok"] == true; + assert_ne!(max_won, oe["ok"] == true, "one winner for {n}: {om} {oe}"); + let (loser, winner) = if max_won { (oe, "max") } else { (om, "erika") }; + assert_eq!(loser["reason"], "locked", "{loser}"); + assert_eq!( + loser["checked_out_by_name"], + format!("{winner} (test)"), + "{loser}" + ); + assert_eq!(holder(&app, n).await.as_deref(), Some(winner)); + assert_eq!( + checkout_audits(&app, n).await, + before[n] + 1, + "one audit record for {n}" + ); + } +}