Feature assemblies base

[webdevinition]

Hello @jbtronics,

In relation to #1051 the feature for adding the base of assembly as an new data source.
Also mentioned in the discussion under #1041, section 1.

The changes are the remaining delta to the other extracted feature pull requests related to the mentioned discussion.

Configuration opportunity of Bills of Materials (BOMs) with referencing of other assemblies, cycle prevention included

Simplified import overview with template description for filling the parts lists (BOM) of an assembly

Human-readable export in CSV and PDF format for simplified viewing of basic information

Human-readable export in PDF format to simplify understanding of which parts are actually required for a multiply nested assembly, for example, completely independent of a build function as is the case with projects.

Thanks for everything so far! I am grateful for integration!

Best regards,
Marcel

[webdevinition]

@jbtronics, I've rebased the branch to the master branch.

It would be great if you could take a look at the pull request and give me some feedback on what else needs to be done for you to integrate it.

I wish you even now a nice and fulfilling holiday season!

Best regards,
Marcel

[codecov]

Codecov Report

❌ Patch coverage is 27.12100% with 1572 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.52%. Comparing base (05a9e4d) to head (e4cd243).

Files with missing lines	Patch %	Lines
src/Services/ImportExportSystem/BOMImporter.php	14.98%	312 Missing ⚠️
src/Services/ImportExportSystem/EntityExporter.php	3.96%	242 Missing ⚠️
src/Helpers/Assemblies/AssemblyPartAggregator.php	0.74%	133 Missing ⚠️
src/DataTables/AssemblyDataTable.php	0.00%	115 Missing ⚠️
src/Controller/AssemblyController.php	60.13%	61 Missing ⚠️
src/Controller/TypeaheadController.php	1.63%	60 Missing ⚠️
src/Controller/StatisticsController.php	0.00%	58 Missing ⚠️
src/DataTables/AssemblyBomEntriesDataTable.php	62.16%	56 Missing ⚠️
src/DataTables/Filters/AssemblySearchFilter.php	0.00%	56 Missing ⚠️
src/Form/Filters/AssemblyFilterType.php	0.00%	48 Missing ⚠️
... and 35 more

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1082      +/-   ##
============================================
- Coverage     54.77%   52.52%   -2.25%     
- Complexity     8012     8580     +568     
============================================
  Files           601      629      +28     
  Lines         25691    27807    +2116     
============================================
+ Hits          14073    14607     +534     
- Misses        11618    13200    +1582     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jbtronics]

I do not quite understand what the semantic difference between an assembly and the existing projects should be?

[webdevinition]

Hello @jbtronics,

I hope you had a wonderful holiday season.
First of all, Happy New Year, best of luck, and above all, good health! :)

Here's the explanation:

1. Logical vs. Physical Entity
   Project (Operational): A project is a concrete work order. It uses the "Build Part" function to retrieve physical parts from inventory at the end of the process and book the finished product/device. It represents the manufacturing process for users in a way.
   Assembly (Structural): An assembly is a purely logical definition (similar to a "virtual component"). It serves to define the bill of materials (BOM) for a complex part without having to go through a virtual part or even a build process in our every day life working with Part-DB.

2. The Problem of "Flat" Projects
   Without assemblies, a user building a complex machine would have to create a huge project with many of individual parts.

With assemblies: The user defines the "Motor" assembly once and the "Control" assembly once with all the depending structure.
In another assembly where this is needed, the user simply adds these example assemblies to the bill of materials with the necessary quantity.
The key advantage: Since assemblies don't have their own build part/stock inventory in the pull request, they serve as transparent containers.

The difference lies in the level of abstraction:
Projects are designed mainly for the physical build process of specific users. They have a 'build part' because they actively modify the inventory (components removed, finished product added).
Assemblies are designed for structural organization in our every day life. They don't have their own inventory but serve as reusable templates for bills of materials in other assembly entries.

Assemblies thus specifically solve the problem of reusing blueprints, while projects solve the problem of inventory changes during manufacturing.
This adds another useful feature to the part database for all users who wish to utilize it.

[jbtronics]

Im still not really convinced that introducing a new kind of entity is the best approach there. Especially as this PR is very big and complex (136 file changes) and a lot of logic seems to be duplicated from projects.

Maybe the goal could also be reached by adding some new functionality to the existing projects (like adding a flag, that makes them non-buildable and only work as generic placeholder, or assembly if you wanna call it that way).

I am not sure how many people would actually profit from that feature anyway, and if it is worth to the additional complexity/maintenance effort of the PR in the current form.

[webdevinition]

Hello @jbtronics,

thank you for your reply. I don't currently see this being represented in the projects via a flag or similar.

Benefits for the community:
Hierarchical BOMs: complex hardware cannot really do without nested parts lists (multi-level BOMs) and cannot really be represented. This should be separated from the projects to avoid unwanted sideeffects- because it is a new type of datasource.
Basically, anyone who not only soldered circuit boards but also defined housings, motors, or cable harnesses as subgroups needed this structure to maintain an overview. That's why I see a certain benefit for the community.
It is also a feature that can be activated. Those who don't need it don't have to activate it.

In addition, a separate assembly entity is certainly more intuitive for such users, as assemblies often serve as reusable blueprints (templates), while projects are one-time instances (actually real orders in a way).

I would greatly appreciate it if you could take on this task as well and would also be happy to contribute further to any future inquiries that may arise, because I enjoy doing so.

I will also modify the Custom Part State feature to include multiple selection in the near future and prepare it as a pull request—unfortunately, I haven't had time to do so yet ;)

Best regards,
Marcel

[deberman]

I would like this functionalty. I’m about to try out part-db in the near future as a part manager. Having the ability to create unit level assemblies in the same tool would be super useful for a company like ours.

[lukas-runge]

I'd also love to have a feature like this. Doesn't need to be a new thing entirely - I can totally see this work on the current projects structure, but it would be great if I'd be able to define an "assembly of projects" in defined quantities so I can see (when pressing "Build") if I have all the parts in stock to build all of the projects at their desired quantities or not. The usecase is basically any project with more than one PCB inside. My current Project has 11 different designs contained within. The only current workaround for something like this is to merge all boms, respecting quantities of every bom and creating an additional new project with all of it inside. Ofc I can understand the hesitation towards this obviously vibe-coded prototype. But still think the goal behind this is worth pursuing. Imo the MVP of this would just allow to add projects as parts to other projects bom. This way a product could e.g. have 20 of the same board projects inside and 5 of another kind and then when pressing "Build" on the product project which nests all other component projects inside this would then recursively get all parts and calculate a sum to tell me what I am missing to build the entire thing. What do you think @jbtronics? Would this be viable to build without a headache? 🙌

[webdevinition]

@lukas-runge,
Thank you for bringing this up. I definitely agree that the underlying use case is worth solving.

Just to clarify one point: based on my explanations above, I do not fully understand why the current implementation is being considered a prototype or not yet ready to be merged, and I am absolutely open to feedback on the architecture and implementation details. However, calling it “vibe-coded” feels somewhat unfair to me. This was neither AI-generated nor a randomly thrown-together implementation, including the hierarchical export functionality. I did think about the underlying model and tried to explain the reasoning behind it earlier in the PR.

The most important distinction I wanted to make is between operational builds and structural BOM definitions:

• Projects represent an actual build or work order. They are tied to the build process and can affect stock levels by consuming parts and optionally adding the completed build part.
• Assemblies, as proposed here, are intended to be reusable, transparent BOM structures. They do not represent stock themselves and do not require their own build part. They are more like structural templates or virtual components that can be referenced in other BOMs.

“Projects inside projects” would solve a similar use case, but in my view it mixes two different concepts: a Project as something that is actively being built, and an Assembly as something that describes a structure. That was also the main idea behind solving this with a dedicated entity.

For my use case — and probably also for many more complex products — nesting alone is not the key point. What is needed is a reusable structural entity that does not itself imply any stock transaction. For example, one could define an Assembly such as “Motor”, “Control board”, or “Front panel” once and then reuse it multiple times, with different quantities, in higher-level Assemblies.

Apart from that, I do not understand why the current implementation cannot be the path toward a future integration of the aforementioned function.
It is a usable feature that has already been in productive use for many months and is used for many assembly configurations. I am happy to discuss a cleaner approach and try to explain the reasoning behind it. I just wanted to make sure that the intended concept is not reduced to “nested projects”, because the separation between Project/build process and Assembly/BOM structure was the main reason for this proposal.

Kind regards,
Marcel

[lukas-runge]

@webdevinition Fair point, that came across harsher than intended - sorry for that. "Vibe-coded" wasn't meant as a dig at you or the thinking behind it (your explanations in this thread clearly show there's a real concept here). My concern is a purely practical one: with 183 changed files, a full parallel entity stack and a lot of logic mirrored from projects, this PR is just very hard to review and maintain - which is pretty much what @jbtronics named as his main hesitation too. So imo the question isn't "is this useful" (it clearly is, I want it myself 🙂), it's "what's the smallest version of this that actually gets merged".

On the conceptual separation: I get the distinction you're making (operational build vs. structural bom definition) and I think it's real. But imo it doesn't need a new entity type, because it already exists as a property of projects: a project without a build part is exactly your "transparent container". It just describes a structure and doesn't hold any stock. Your "Motor", "Control board" or "Front panel" would simply be projects without a build part (plus an IPN, see below) and could be reused in as many higher-level boms as you like, in whatever quantities. The bom references would also be completely independent from the organizational project tree, so reuse works exactly like with your assemblies. Whether something is an actual build or just structure is then simply decided by whether it has a build part, so the separation you're after is already built in.

So here's what I'd propose as the MVP:

1. Projects get an optional IPN (like parts already have).
2. A bom entry can also reference another project instead of a part. The referenced project doesn't have to have a build part.
3. The Build tab recursively accumulates all part quantities from nested project references. By default the recursion stops at sub-projects that have a build part (their built stock gets consumed), and an extra toggle lets you continue the recursion through those as well, down to the raw parts.

Data-model-wise that's two columns and a FK plus a cycle check on the bom reference graph, the real work is in the build logic. Compared to this PR that's maybe a dozen files instead of 183, and it saves us the whole extra permission tree, the additional API endpoints and the huge translation diff that come with a separate entity.

Everything else from this PR could then become independent follow-up PRs on top of that base. And most of it is actually generic product improvement that would benefit all projects, not just this feature: hierarchical bom display, human-readable CSV/PDF export, bom import that can reference sub-boms by IPN, project search via quicksearch/IPN, statistics. So none of that would be lost, it just doesn't have to land in step one.

Honest question to you Marcel: does this cover your use cases, or is there something in your daily use of your assembly implementation that a no-build-part project with IPN + bom references + recursive build genuinely can't represent? And would you see this as a solid base to build the remaining usability features on? You've been running your implementation productively for months, so you know the real-world corner cases better than anyone - that input would be super valuable before anyone writes code. And @jbtronics: would a staged approach like this be something you'd be open to merging? 🙌

[jbtronics]

And @jbtronics: would a staged approach like this be something you'd be open to merging? 🙌

Yes, splitting it up into multiple smaller PRs would be an option. Ideally they should be independent from each other and not coupled so much into these assemblies functionality...

There still remains the conceptual and architectural issues with that this seems to be very close projects, and that it doesnt really seem worth it to introduce a completly new concept to Part-DB, especially when it duplicates a whole subsystem bascially. And i think i still dont really get the point of why you think this new concept is really necessary and not possible to do with projects. For end users it will just be very very confusing to have these two similar entity types.

I think the way to go would be either to generalize or change the concept of projects, or introduce some special case of projects that makes some minor behavior changes.

But in both cases some deep architectural changes to this PR will be necessary.