diff --git a/docs/MOC_AUTO_GENERATION.md b/docs/MOC_AUTO_GENERATION.md index a195557..74e9a92 100644 --- a/docs/MOC_AUTO_GENERATION.md +++ b/docs/MOC_AUTO_GENERATION.md @@ -4,13 +4,16 @@ The LEGO Instructions Manager now includes automatic MOC (My Own Creation) set number generation, making it easier to track and organize your custom LEGO builds without manually managing set numbers. +**Default Behavior: Global Numbering** - All users share the same MOC number sequence, ensuring system-wide unique MOC numbers. + ## Features ### 🤖 Automatic Number Generation - **Sequential Numbering**: Automatically generates MOC numbers in sequence (MOC-10000, MOC-10001, MOC-10002, etc.) -- **Conflict-Free**: Ensures no duplicate MOC numbers +- **Global by Default**: All users share the same sequence for system-wide uniqueness +- **Conflict-Free**: Ensures no duplicate MOC numbers across the entire system - **Customizable Prefix**: Default is "MOC" but can be changed -- **User-Scoped Option**: Can scope MOC numbers per user or globally +- **Optional User-Scoping**: Can scope to individual users if needed ### 🔌 API Endpoints @@ -21,7 +24,7 @@ GET /api/moc/generate **Query Parameters:** - `prefix` (optional): MOC prefix, default is 'MOC' -- `user_scoped` (optional): Scope to current user, default is 'true' +- `user_scoped` (optional): Scope to current user, default is **'false'** (GLOBAL) **Response:** ```json @@ -29,17 +32,25 @@ GET /api/moc/generate "success": true, "moc_number": "MOC-10001", "prefix": "MOC", - "user_scoped": true + "user_scoped": false } ``` **Example Usage:** ```javascript +// Get next global MOC number (default) fetch('/api/moc/generate') .then(response => response.json()) .then(data => { console.log('Next MOC number:', data.moc_number); }); + +// Get next user-scoped MOC number (optional) +fetch('/api/moc/generate?user_scoped=true') + .then(response => response.json()) + .then(data => { + console.log('Next user MOC number:', data.moc_number); + }); ``` #### 2. Validate MOC Number @@ -51,7 +62,7 @@ POST /api/moc/validate ```json { "set_number": "MOC-12345", - "user_scoped": true + "user_scoped": false } ``` @@ -131,7 +142,7 @@ document.getElementById('is_moc').addEventListener('change', function() { officialSection.style.display = 'none'; setNumberInput.removeAttribute('required'); - // Fetch next MOC number + // Fetch next MOC number (global by default) fetchNextMocNumber(); } else { // Show official section, hide MOC section @@ -168,16 +179,22 @@ The `MOCNumberGenerator` service handles all MOC number logic: ```python from app.services.moc_generator import MOCNumberGenerator -# Generate next MOC number +# Generate next GLOBAL MOC number (default) moc_number = MOCNumberGenerator.generate_next_number( prefix='MOC', - user_id=current_user.id # Optional: scope to user + user_id=None # None = global numbering ) -# Validate MOC number availability +# Generate next USER-SCOPED MOC number (optional) +moc_number = MOCNumberGenerator.generate_next_number( + prefix='MOC', + user_id=current_user.id # Scope to specific user +) + +# Validate MOC number availability (global) is_available = MOCNumberGenerator.validate_moc_number( 'MOC-12345', - user_id=current_user.id + user_id=None # Check globally ) # Check if number follows MOC format @@ -198,8 +215,12 @@ bp = Blueprint('moc', __name__, url_prefix='/api/moc') @bp.route('/generate', methods=['GET']) @login_required def generate_moc_number(): + # Default: user_scoped=false (global numbering) + user_scoped = request.args.get('user_scoped', 'false').lower() == 'true' + user_id = current_user.id if user_scoped else None + moc_number = MOCNumberGenerator.generate_next_number( - user_id=current_user.id + user_id=user_id ) return jsonify({ 'success': True, @@ -219,17 +240,20 @@ class MOCNumberGenerator: DEFAULT_START = 10000 # Starting number for MOCs ``` -### Per-User vs Global Numbering +### Numbering Modes -**Per-User Numbering** (default): +**Global Numbering** (Default - **RECOMMENDED**): +- All users share the same MOC number sequence +- Ensures system-wide unique MOC numbers +- MOC-10000 is unique across the entire system +- **API**: `user_scoped=false` or omit parameter +- **Use Case**: Single household, organization, or when you want guaranteed unique IDs + +**Per-User Numbering** (Optional): - Each user has their own MOC number sequence - MOC-10000 can exist for multiple users -- API: `user_scoped=true` - -**Global Numbering**: -- All users share the same MOC number sequence -- Ensures unique MOC numbers across the entire system -- API: `user_scoped=false` +- **API**: `user_scoped=true` +- **Use Case**: Multi-tenant systems where users want isolated numbering ## Use Cases @@ -237,7 +261,7 @@ class MOCNumberGenerator: 1. User clicks "Add New Set" 2. User toggles "This is a MOC" checkbox -3. System automatically generates MOC-10000 (or next available) +3. System automatically generates next global MOC number (e.g., MOC-10000) 4. User fills in MOC designer, description, and other details 5. System saves set with is_moc=True @@ -247,6 +271,7 @@ class MOCNumberGenerator: from app.services.moc_generator import MOCNumberGenerator for moc_data in moc_import_list: + # Global numbering - user_id=None moc_number = MOCNumberGenerator.generate_next_number() new_set = Set( set_number=moc_number, @@ -297,8 +322,8 @@ mocs_range = Set.query.filter( **Issue**: Same MOC number assigned to multiple sets **Solutions**: -1. Check database constraints on `set_number` field -2. Verify `user_scoped` parameter matches your use case +1. Verify you're using global numbering (default `user_scoped=false`) +2. Check database constraints on `set_number` field (should be unique) 3. Run database migration to add unique constraint if missing ### MOC Toggle Not Working @@ -325,8 +350,7 @@ Potential improvements for the MOC feature: - [Main README](../README.md) - General application documentation - [Setup Guide](../SETUP_GUIDE.md) - Installation and configuration -- [API Documentation](../docs/api.md) - Complete API reference (if exists) -- [Database Schema](../docs/database.md) - Database structure (if exists) +- [Feature Update Summary](../FEATURE_UPDATE_SUMMARY.md) - Recent changes ## Support @@ -344,5 +368,5 @@ For issues or questions about MOC auto-generation: --- **Last Updated**: December 2024 -**Feature Version**: 1.0 +**Feature Version**: 1.1 (Global Numbering Default) **Compatibility**: LEGO Instructions Manager v1.3.0+