diff --git a/docs/concepts.md b/docs/concepts.md index 8a3551bdb..efce9880e 100644 --- a/docs/concepts.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index c2128946d..449401431 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/usage/ipn_generation.md b/docs/usage/ipn_generation.md new file mode 100644 index 000000000..a2142fa1d --- /dev/null +++ b/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 diff --git a/docs/usage/synonyms.md b/docs/usage/synonyms.md new file mode 100644 index 000000000..1f54d06f6 --- /dev/null +++ b/docs/usage/synonyms.md @@ -0,0 +1,346 @@ +--- +title: Synonym System +layout: default +parent: Usage +nav_order: 13 +--- + +# Synonym System + +Part-DB includes a powerful synonym system that allows you to customize the terminology used throughout the application. This is especially useful when using Part-DB in contexts other than electronics, or when you want to adapt the interface to your organization's specific vocabulary. + +1. TOC +{:toc} + +## What is the Synonym System? + +The synonym system allows you to replace Part-DB's standard terminology with your own preferred terms. For example: +- Change "Part" to "Product", "Component", or "Item" +- Change "Category" to "Group", "Type", or "Class" +- Change "Manufacturer" to "Supplier", "Vendor", or "Brand" + +These custom terms (synonyms) are applied throughout the user interface, making Part-DB feel more natural for your specific use case. + +## Important Notes + +{: .warning-title } +> Experimental Feature +> +> The synonym system is currently **experimental**. While it works in most places throughout Part-DB, there may be some locations where the default terms still appear. The synonym system is being continuously improved. + +## Configuring Synonyms + +To configure synonyms, you need administrator permissions: + +1. Navigate to `Tools -> System -> Settings` +2. Find and click on "Synonyms" in the settings menu +3. You'll see the synonym configuration interface + +### Adding a Synonym + +To add a new synonym: + +1. Click the "Add Entry" button in the synonym settings +2. Select the **Type** (element type) you want to create a synonym for +3. Select the **Language** for which the synonym applies +4. Enter the **Singular** form of your synonym +5. Enter the **Plural** form of your synonym +6. Click "Save" to apply the changes + +### Available Element Types + +You can create synonyms for the following element types: + +| Element Type | Default Term (EN) | Example Use Cases | +|--------------------|-----------------------|-----------------------------------------------| +| **attachment** | Attachment | Document, File, Asset | +| **attachment_type**| Attachment Type | Document Type, File Category | +| **category** | Category | Group, Class, Type, Collection | +| **currency** | Currency | Monetary Unit, Money Type | +| **footprint** | Footprint | Package, Form Factor, Physical Type | +| **group** | Group | Team, Department, Role | +| **label_profile** | Label Profile | Label Template, Print Template | +| **manufacturer** | Manufacturer | Brand, Vendor, Supplier, Maker | +| **measurement_unit**| Measurement Unit | Unit of Measure, Unit, Measurement | +| **parameter** | Parameter | Specification, Property, Attribute | +| **part** | Part | Component, Item, Product, Article, SKU | +| **part_lot** | Part Lot | Stock Item, Inventory Item, Batch | +| **project** | Project | Assembly, Build, Work Order | +| **storage_location**| Storage Location | Warehouse, Bin, Location, Place | +| **supplier** | Supplier | Vendor, Distributor, Reseller | +| **user** | User | Member, Account, Person | + +## How Synonyms Work + +### Translation Mechanism + +The synonym system works by integrating with Part-DB's translation system. When you define a synonym: + +1. Part-DB creates translation placeholders for the element type +2. These placeholders are available in both capitalized and lowercase forms +3. The placeholders are used throughout the application where these terms appear + +### Placeholder Format + +Synonyms use special placeholders in translations: + +- `[elementtype]` - Singular, lowercase (e.g., "part" → "item") +- `[Elementtype]` - Singular, capitalized (e.g., "Part" → "Item") +- `[[elementtype]]` - Plural, lowercase (e.g., "parts" → "items") +- `[[Elementtype]]` - Plural, capitalized (e.g., "Parts" → "Items") + +### Language-Specific Synonyms + +Synonyms are language-specific, meaning you can define different terms for different languages: + +- English users see: "Component" and "Components" +- German users see: "Bauteil" and "Bauteile" +- French users see: "Composant" and "Composants" + +This allows Part-DB to maintain proper multilingual support even with custom terminology. + +## Use Cases and Examples + +### Non-Electronics Inventory + +**Scenario**: Using Part-DB for a library + +**Synonyms**: +- Part → Book +- Category → Genre +- Manufacturer → Publisher +- Supplier → Distributor +- Storage Location → Shelf + +**Result**: The interface now speaks library language: "Add a new Book", "Select a Genre", etc. + +### Manufacturing Environment + +**Scenario**: Managing production inventory + +**Synonyms**: +- Part → Material +- Category → Material Type +- Part Lot → Batch +- Storage Location → Warehouse Zone +- Project → Assembly + +**Result**: The interface uses manufacturing terminology: "Materials", "Batches", "Warehouse Zones", "Assemblies" + +### Small Business Retail + +**Scenario**: Managing store inventory + +**Synonyms**: +- Part → Product +- Category → Department +- Manufacturer → Brand +- Supplier → Vendor +- Part Lot → Stock Item +- Storage Location → Store Location + +**Result**: The interface matches retail terminology: "Products", "Departments", "Brands" + +### Laboratory Setting + +**Scenario**: Managing lab supplies and chemicals + +**Synonyms**: +- Part → Reagent +- Category → Substance Type +- Manufacturer → Chemical Supplier +- Storage Location → Cabinet +- Part Lot → Bottle + +**Result**: Lab-appropriate language: "Reagents", "Substance Types", "Cabinets" + +### Educational Makerspace + +**Scenario**: Managing shared tools and components + +**Synonyms**: +- Part → Resource +- Category → Resource Type +- Storage Location → Area +- Project → Activity +- Part Lot → Available Unit + +**Result**: Educational context: "Resources", "Resource Types", "Areas", "Activities" + +## Managing Synonyms + +### Editing Synonyms + +To edit an existing synonym: +1. Find the synonym entry in the list +2. Modify the singular or plural form as needed +3. Click "Save" to apply changes + +### Removing Synonyms + +To remove a synonym: +1. Find the synonym entry in the list +2. Click the "Remove Entry" button (usually a trash icon) +3. Click "Save" to apply changes + +After removal, Part-DB will revert to using the default term for that element type and language. + +### Bulk Configuration + +If you need to set up many synonyms at once (e.g., for a complete custom terminology set): + +1. Define all your synonyms in the settings page +2. Each element type can have synonyms in multiple languages +3. Save once when all entries are configured + +### Duplicate Prevention + +The system prevents duplicate entries: +- You cannot have multiple synonyms for the same element type and language combination +- If you try to add a duplicate, you'll see a validation error +- Edit the existing entry instead of creating a new one + +## Best Practices + +### Consistency + +- **Use consistent terminology**: If you change "Part" to "Product", consider changing "Part Lot" to "Product Item" or similar +- **Think holistically**: Consider how terms relate to each other in your domain +- **Test thoroughly**: Check various pages to ensure your terms make sense in context + +### Singular and Plural Forms + +- **Provide both forms**: Always define both singular and plural forms +- **Use proper grammar**: Ensure plurals are grammatically correct +- **Consider irregular plurals**: Some terms have non-standard plurals (e.g., "Box" → "Boxes", not "Boxs") + +### Language Considerations + +- **Match user expectations**: Use terms your users are familiar with in their language +- **Be culturally appropriate**: Some terms may have different connotations in different languages +- **Maintain professionalism**: Choose terms appropriate for your organizational context + +### Planning Your Terminology + +Before implementing synonyms: + +1. **List all terms**: Identify which Part-DB terms don't fit your context +2. **Define replacements**: Decide on appropriate alternatives +3. **Check relationships**: Ensure related terms work together logically +4. **Get feedback**: Consult with users about proposed terminology +5. **Document decisions**: Keep a record of your synonym choices for future reference + +## Limitations + +### Not All Locations Covered + +As an experimental feature, synonyms may not appear in: +- Some error messages +- Technical logs +- Email templates (depending on configuration) +- API responses +- Some administrative interfaces + +The development team is working to expand synonym coverage. + +### No Automatic Propagation + +Synonyms only affect the user interface: +- Database values remain unchanged +- Export files use original terms +- API endpoints keep original names +- URLs and routes remain the same + +### Performance Considerations + +The synonym system: +- Caches translations for performance +- Minimal performance impact in normal usage +- Cache is automatically updated when synonyms change + +## Technical Details + +### Cache Management + +Synonyms are cached for performance: +- Cache is automatically cleared when synonyms are saved +- No manual cache clearing needed +- Changes appear immediately after saving + +### Translation Priority + +When displaying text, Part-DB checks in this order: +1. Synonym (if defined for current language and element type) +2. Standard translation (from translation files) +3. Fallback to English default + +### Environment Variables + +Currently, synonyms can only be configured through the web interface. Future versions may support environment variable configuration. + +## Troubleshooting + +### Synonyms Not Appearing + +**Problem**: You've configured synonyms but still see original terms. + +**Solutions**: +- Clear your browser cache and reload the page +- Check that you've configured the synonym for the correct language +- Verify that you saved the settings after adding the synonym +- Remember this is an experimental feature - some locations may not be covered yet + +### Inconsistent Terminology + +**Problem**: Some pages show your synonym, others show the original term. + +**Solutions**: +- This is expected behavior for the experimental feature +- Check if you've defined both singular and plural forms +- Report inconsistencies to help improve the system + +### Wrong Language Displaying + +**Problem**: Seeing synonyms from the wrong language. + +**Solutions**: +- Check your user language preference in user settings +- Verify you've configured synonyms for the correct language code +- Ensure the language code matches exactly (e.g., "en" not "en_US") + +### Synonyms Lost After Update + +**Problem**: Synonyms disappeared after updating Part-DB. + +**Solutions**: +- Check the settings page - they should still be there +- Database migrations preserve synonym settings +- If truly lost, restore from backup or reconfigure + +## Future Enhancements + +The synonym system is under active development. Planned improvements include: +- Coverage of more interface elements +- Synonym suggestions based on common use cases +- Import/export of synonym configurations +- Synonym templates for different industries +- More granular control over term usage + +## Related Documentation + +- [Getting Started]({% link usage/getting_started.md %}) - Initial Part-DB setup +- [Configuration]({% link configuration.md %}) - System configuration options +- [Concepts]({% link concepts.md %}) - Understanding Part-DB terminology + +## Feedback + +Since the synonym system is experimental, feedback is valuable: +- Report locations where synonyms don't appear +- Suggest new element types that should support synonyms +- Share your use cases to help improve the system +- Report bugs or unexpected behavior + +You can provide feedback through: +- GitHub issues on the Part-DB repository +- Community forums and discussions +- Direct contact with the development team