Add comprehensive documentation for IPN generation and synonym system

Co-authored-by: jbtronics <[email protected]>

Author: Copilot

docs/concepts.md

@@ -50,7 +50,10 @@ A part entity has many fields, which can be used to describe it better. Most of
 * **Mass**: The mass of a single piece of this part (so of a single transistor). Given in grams.
 * **Internal Part Number** (IPN): Each part is automatically assigned a numerical ID that identifies a part in the
   database. This ID depends on when a part was created and cannot be changed. If you want to assign your own unique
-  identifiers, or sync parts identifiers with the identifiers of another database, you can use this field.
+  identifiers, or sync parts identifiers with the identifiers of another database, you can use this field. Part-DB 
+  can automatically suggest IPNs based on category prefixes and sequential numbering. See the 
+  [IPN Generation documentation]({% link usage/ipn_generation.md %}) for detailed information on how to set up and use 
+  this feature.
 
 ### Stock / Part lot
 

docs/index.md

@@ -27,6 +27,8 @@ It is installed on a web server and so can be accessed with any browser without
 * Inventory management of your electronic parts. Each part can be assigned to a category, footprint, manufacturer,
   and multiple store locations and price information. Parts can be grouped using tags. You can associate various files
   like datasheets or pictures with the parts.
+* Automatic Internal Part Number (IPN) generation with customizable prefixes and numbering schemes (see [IPN documentation]({% link usage/ipn_generation.md %}))
+* Synonym system to customize terminology throughout the application (see [Synonyms documentation]({% link usage/synonyms.md %}))
 * Multi-language support (currently German, English, Russian, Japanese, French, Czech, Danish, and Chinese)
 * Barcodes/Labels generator for parts and storage locations, scan barcodes via webcam using the built-in barcode scanner
 * User system with groups and detailed (fine-grained) permissions.

docs/usage/ipn_generation.md

@@ -0,0 +1,306 @@
+---
+title: Internal Part Number (IPN) Generation
+layout: default
+parent: Usage
+nav_order: 12
+---
+
+# Internal Part Number (IPN) Generation
+
+Part-DB supports automatic generation and management of Internal Part Numbers (IPNs) for your parts. IPNs are unique identifiers that help you organize and track your inventory in a structured way.
+
+1. TOC
+{:toc}
+
+## What is an IPN?
+
+An Internal Part Number (IPN) is a unique identifier assigned to each part in your inventory. Unlike manufacturer part numbers (MPNs), IPNs are defined and controlled by you, following your own naming conventions and organizational structure.
+
+IPNs are useful for:
+- Creating a consistent numbering scheme across your entire inventory
+- Organizing parts hierarchically based on categories
+- Quickly identifying and locating parts
+- Generating barcodes for parts
+- Integrating with external systems (like EDA tools)
+
+## Basic Concepts
+
+### IPN Structure
+
+An IPN typically consists of several components:
+- **Prefix**: Identifies the category or type of part (e.g., "RES" for resistors, "CAP" for capacitors)
+- **Separator**: Divides different parts of the IPN (default is `-`)
+- **Number**: A sequential number that makes the IPN unique
+
+Example: `RES-0001`, `CAP-IC-0042`, `MCU-ARM-1234`
+
+### Category-Based IPN Prefixes
+
+Categories in Part-DB can have their own IPN prefix. When creating a new part in a category, Part-DB can automatically suggest IPNs based on the category's prefix.
+
+To set an IPN prefix for a category:
+1. Navigate to the category edit page
+2. Find the "Part IPN Prefix" field
+3. Enter your desired prefix (e.g., "RES", "CAP", "IC")
+
+### Hierarchical Prefixes
+
+Part-DB supports hierarchical IPN generation based on parent categories. For example:
+- Parent category "IC" with prefix "IC"
+- Child category "Microcontrollers" with prefix "MCU"
+- Generated IPN could be: `IC-MCU-0001`
+
+This allows you to create deeply nested categorization schemes while maintaining clear IPNs.
+
+## Configuring IPN Generation
+
+You can configure IPN generation in the system settings under `Tools -> System -> Settings -> Miscellaneous -> IPN Suggest Settings`.
+
+### Available Settings
+
+#### Regex Pattern
+Define a regular expression pattern that valid IPNs must match. This helps enforce consistency across your inventory.
+
+Example: `^[A-Za-z0-9]{3,4}(?:-[A-Za-z0-9]{3,4})*-\d{4}$`
+
+This pattern requires:
+- 3-4 alphanumeric characters for prefixes
+- Optional additional prefix groups separated by `-`
+- Ending with a 4-digit number
+
+#### Regex Help Text
+Provide custom help text that explains your IPN format to users. This text is shown when users are creating or editing parts.
+
+#### Auto-Append Suffix
+When enabled, Part-DB automatically appends a suffix (`_1`, `_2`, etc.) to IPNs that would otherwise be duplicates. This prevents IPN collisions when multiple parts might generate the same IPN.
+
+**Example:**
+- First part: `RES-0001`
+- Duplicate attempt: automatically becomes `RES-0001_1`
+- Next duplicate: automatically becomes `RES-0001_2`
+
+#### Suggest Part Digits
+Defines how many digits should be used for the sequential part number (default: 4).
+- 4 digits: `0001` to `9999`
+- 6 digits: `000001` to `999999`
+
+#### Use Duplicate Description
+When enabled, Part-DB will suggest the same IPN for parts with identical descriptions. This is useful when you want to track variants of the same component with the same IPN scheme.
+
+#### Fallback Prefix
+The prefix to use when a category has no IPN prefix defined (default: `N.A.`). This ensures all parts can get an IPN suggestion even without category-specific prefixes.
+
+#### Number Separator
+The character that separates the prefix from the number (default: `-`).
+
+Example: With separator `-`, you get `RES-0001`. With separator `.`, you get `RES.0001`.
+
+#### Category Separator
+The character that separates hierarchical category prefixes (default: `-`).
+
+Example: With separator `-`, you get `IC-MCU-0001`. With separator `.`, you get `IC.MCU.0001`.
+
+#### Global Prefix
+An optional prefix that is prepended to all IPNs in your system. Useful if you want to distinguish your inventory from other systems.
+
+Example: With global prefix `ACME`, IPNs become `ACME-RES-0001`, `ACME-CAP-0042`, etc.
+
+## Using IPN Suggestions
+
+### When Creating a New Part
+
+When you create a new part, Part-DB provides IPN suggestions based on:
+
+1. **Global Prefix** (if configured): Suggestions using your global prefix
+2. **Description Matching** (if enabled): If another part has the same description, its IPN is suggested
+3. **Direct Category Prefix**: The IPN prefix of the part's assigned category
+4. **Hierarchical Prefixes**: IPNs combining parent category prefixes with the current category
+
+Each suggestion includes:
+- The suggested IPN
+- A description of how it was generated
+- An auto-incremented version (ending with the next available number)
+
+### IPN Suggestion Types
+
+#### Common Prefixes
+These show just the prefix part without a number. Use these as a starting point to manually add your own number.
+
+Example: `RES-` (you then type `RES-1234`)
+
+#### Prefixes with Part Increment
+These show complete IPNs with automatically incremented numbers. The system finds the highest existing number with that prefix and suggests the next one.
+
+Example: If `RES-0001` through `RES-0005` exist, the system suggests `RES-0006`.
+
+### Manual IPN Entry
+
+You can always manually enter any IPN you want. If you've configured a regex pattern, Part-DB will validate your IPN against it and show an error if it doesn't match.
+
+## IPN Uniqueness
+
+IPNs must be unique across your entire Part-DB instance. Part-DB enforces this constraint:
+
+- When manually entering an IPN, you'll see an error if it already exists
+- When auto-append suffix is enabled, duplicate IPNs are automatically made unique
+- Existing parts retain their IPNs even if you change their category
+
+## IPNs in Labels and Barcodes
+
+IPNs can be used in label templates through placeholders:
+
+- `[[IPN]]` - The IPN as text
+- `[[IPN_BARCODE_C39]]` - IPN as Code 39 barcode
+- `[[IPN_BARCODE_C128]]` - IPN as Code 128 barcode
+- `[[IPN_BARCODE_QR]]` - IPN as QR code
+
+See the [Labels documentation]({% link usage/labels.md %}) for more information.
+
+## IPNs in Barcode Scanning
+
+Part-DB can scan barcodes containing IPNs to quickly find parts. When a barcode is scanned, Part-DB:
+1. Attempts to parse it as an IPN
+2. Searches for the part with that IPN
+3. Displays the part information
+
+This enables quick inventory operations using barcode scanners.
+
+## IPNs in EDA Integration
+
+When using Part-DB with EDA tools like KiCad, the IPN is automatically added to the component fields as "Part-DB IPN". This creates a direct link between your schematic components and your Part-DB inventory.
+
+See the [EDA Integration documentation]({% link usage/eda_integration.md %}) for more information.
+
+## Best Practices
+
+### Choosing Prefixes
+
+- **Keep them short**: 2-4 characters work well (e.g., "RES", "CAP", "IC")
+- **Make them memorable**: Use abbreviations that are obvious (avoid "XYZ" or "ABC")
+- **Be consistent**: Use the same style across all categories (all caps or all lowercase)
+- **Avoid ambiguity**: Don't use similar prefixes like "IC" and "1C"
+
+### Numbering Schemes
+
+- **Pad with zeros**: Use leading zeros for cleaner sorting (0001, 0042 instead of 1, 42)
+- **Leave room for growth**: If you have 50 parts now, use 4 digits (up to 9999) instead of 2
+- **Don't encode information**: Let the prefix and category do the work, not the number
+- **Sequential is fine**: You don't need gaps - 0001, 0002, 0003 is perfectly valid
+
+### Hierarchical Categories
+
+- **Limit depth**: 2-3 levels is usually sufficient (IC-MCU vs IC-MCU-ARM-STM32)
+- **Balance specificity**: More levels = longer IPNs but more precise categorization
+- **Consider searching**: Very specific categories are harder to search across
+
+### Changing Your Scheme
+
+- **Plan ahead**: Changing IPN schemes later is difficult
+- **Document your convention**: Add your IPN format to your regex help text
+- **Existing parts**: Don't feel obligated to renumber existing parts if you change schemes
+- **Migration**: Use import/export to batch-update IPNs if needed
+
+## Common Issues and Solutions
+
+### "IPN already exists"
+
+**Problem**: You're trying to use an IPN that's already assigned to another part.
+
+**Solutions**:
+- Choose a different number
+- Enable "Auto-Append Suffix" to automatically handle duplicates
+- Search for the existing part to see if it's a duplicate you should merge
+
+### "IPN doesn't match regex pattern"
+
+**Problem**: Your IPN doesn't follow the configured format.
+
+**Solutions**:
+- Check the regex help text to understand the expected format
+- Contact your administrator if the regex is too restrictive
+- Use the suggested IPNs which are guaranteed to match
+
+### Suggestions not showing
+
+**Problem**: IPN suggestions are empty or not appearing.
+
+**Solutions**:
+- Ensure the part has a category assigned
+- Check that the category has an IPN prefix defined
+- Verify that a fallback prefix is configured in settings
+- Save the part first before getting suggestions (for new parts)
+
+### Wrong prefix being suggested
+
+**Problem**: Part-DB suggests an IPN with the wrong prefix.
+
+**Solutions**:
+- Check the part's category - suggestions are based on the assigned category
+- Verify parent categories and their prefixes if using hierarchical structure
+- Set the correct IPN prefix in the category settings
+- Use manual entry with your desired prefix
+
+## Example Scenarios
+
+### Simple Electronic Components Inventory
+
+**Setup**:
+- Categories: Resistors, Capacitors, ICs, etc.
+- Prefixes: RES, CAP, IC
+- 4-digit numbering
+
+**Results**:
+- `RES-0001` - 10kΩ resistor
+- `CAP-0001` - 100nF capacitor
+- `IC-0001` - ATmega328
+
+### Professional Lab with Detailed Categories
+
+**Setup**:
+- Hierarchical categories: Components > Passive > Resistors > Surface Mount
+- Prefixes: COMP, PAS, RES, SMD
+- Global prefix: LAB
+- 6-digit numbering
+
+**Results**:
+- `LAB-COMP-PAS-RES-SMD-000001` - 0805 10kΩ resistor
+- `LAB-COMP-PAS-CAP-SMD-000001` - 0805 100nF capacitor
+
+### Makerspace with Mixed Inventory
+
+**Setup**:
+- Categories for electronics, mechanical parts, tools
+- Simple prefixes: ELEC, MECH, TOOL
+- Fallback prefix for miscellaneous: MISC
+- 4-digit numbering
+
+**Results**:
+- `ELEC-0001` - Arduino Uno
+- `MECH-0001` - M3 screw set
+- `TOOL-0001` - Soldering iron
+- `MISC-0001` - Cable ties
+
+## Environment Variables
+
+IPN settings can be configured via environment variables (useful for Docker deployments):
+
+- `IPN_SUGGEST_REGEX` - Override the regex pattern
+- `IPN_SUGGEST_REGEX_HELP` - Override the regex help text
+- `IPN_AUTO_APPEND_SUFFIX` - Enable/disable auto-append suffix (boolean)
+- `IPN_SUGGEST_PART_DIGITS` - Number of digits for part numbers (integer)
+- `IPN_USE_DUPLICATE_DESCRIPTION` - Enable/disable duplicate description matching (boolean)
+
+Example in docker-compose.yaml:
+```yaml
+environment:
+  IPN_SUGGEST_REGEX: "^[A-Z]{3}-\d{4}$"
+  IPN_AUTO_APPEND_SUFFIX: "true"
+  IPN_SUGGEST_PART_DIGITS: "4"
+```
+
+## Related Documentation
+
+- [Getting Started]({% link usage/getting_started.md %}) - Initial setup guide
+- [Concepts]({% link concepts.md %}) - Understanding Part-DB concepts
+- [Labels]({% link usage/labels.md %}) - Using IPNs in labels
+- [EDA Integration]({% link usage/eda_integration.md %}) - IPNs in electronic design tools