Update documentation: Global numbering is now the default standard

2025-12-15 00:41:57 +11:00
parent fdb9211dd2
commit d09732cf78
1 changed files with 49 additions and 25 deletions
--- 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+