# Date Format Codes Guide

## Overview

The module supports dynamic date format codes in lot/serial number sequences. These codes are automatically replaced with current date/time values when generating lot numbers.

## Available Format Codes

| Code | Description | Example Output | Notes |
|------|-------------|----------------|-------|
| `%(year)s` | Full year (4 digits) | 2024 | Current year |
| `%(y)s` | Short year (2 digits) | 24 | Last 2 digits of year |
| `%(month)s` | Month (2 digits) | 11 | 01-12, zero-padded |
| `%(day)s` | Day of month (2 digits) | 20 | 01-31, zero-padded |
| `%(doy)s` | Day of year (3 digits) | 325 | 001-366, zero-padded |
| `%(woy)s` | Week of year (2 digits) | 47 | 00-53, zero-padded |
| `%(weekday)s` | Day of week | 4 | 0=Sunday, 6=Saturday |
| `%(h24)s` | Hour (24-hour format) | 14 | 00-23, zero-padded |
| `%(h12)s` | Hour (12-hour format) | 02 | 01-12, zero-padded |
| `%(min)s` | Minute | 30 | 00-59, zero-padded |
| `%(sec)s` | Second | 45 | 00-59, zero-padded |

## Common Usage Examples

### Example 1: Year-Month-Day Format
**Configuration**: `%(y)s%(month)s%(day)s`

**Generated Lot Numbers**:
- On 2024-11-20: `2411200000001`, `2411200000002`, ...
- On 2024-12-01: `2412010000001`, `2412010000002`, ...

**Use Case**: Daily batch tracking with compact format

### Example 2: Full Date with Separators
**Configuration**: `LOT-%(year)s-%(month)s-%(day)s-`

**Generated Lot Numbers**:
- `LOT-2024-11-20-0000001`
- `LOT-2024-11-20-0000002`
- ...

**Use Case**: Human-readable lot numbers with full date

### Example 3: Year and Week
**Configuration**: `WK%(y)s%(woy)s-`

**Generated Lot Numbers**:
- Week 47 of 2024: `WK2447-0000001`, `WK2447-0000002`, ...

**Use Case**: Weekly production batches

### Example 4: Month and Day Only
**Configuration**: `BATCH-%(month)s%(day)s-`

**Generated Lot Numbers**:
- On Nov 20: `BATCH-1120-0000001`, `BATCH-1120-0000002`, ...

**Use Case**: Daily batches within same year

### Example 5: Day of Year
**Configuration**: `%(year)s-%(doy)s-`

**Generated Lot Numbers**:
- Day 325 of 2024: `2024-325-0000001`, `2024-325-0000002`, ...

**Use Case**: Sequential day tracking

### Example 6: Timestamp Format
**Configuration**: `SN-%(y)s%(month)s%(day)s%(h24)s-`

**Generated Lot Numbers**:
- At 14:30 on Nov 20, 2024: `SN-24112014-0000001`, `SN-24112014-0000002`, ...

**Use Case**: Hour-based batch tracking

## Configuration Steps

### Method 1: Via Product Form (Recommended)

1. Go to **Inventory > Products**
2. Open a product
3. Go to **Inventory** tab
4. In **Custom Lot/Serial** field, enter your format (e.g., `%(y)s%(month)s%(day)s`)
5. The system automatically creates a sequence
6. Check **Next Number** field to preview the format

### Method 2: Via Sequence Configuration

1. Go to **Settings > Technical > Sequences & Identifiers > Sequences**
2. Find or create a sequence with code `stock.lot.serial`
3. Set **Prefix** to your format (e.g., `LOT-%(year)s-%(month)s-%(day)s-`)
4. Set **Padding** (e.g., 7 for 7-digit numbers)
5. Assign this sequence to your product's `lot_sequence_id` field

## How It Works

### Date Interpolation Process

```
1. User configures: %(y)s%(month)s%(day)s
                    ↓
2. System reads current date: 2024-11-20
                    ↓
3. Interpolation:
   %(y)s      → 24
   %(month)s  → 11
   %(day)s    → 20
                    ↓
4. Result prefix: 241120
                    ↓
5. Add sequence number: 241120 + 0000001
                    ↓
6. Final lot number: 2411200000001
```

### Batch Generation

When generating multiple lots (e.g., 500 units):
- Date codes are interpolated **once** at the start
- All lots in the batch use the **same date values**
- Ensures consistency within a batch
- Extremely fast (single interpolation for all lots)

## Best Practices

### 1. Choose Appropriate Granularity

**Daily Batches**: Use `%(y)s%(month)s%(day)s`
- New sequence each day
- Good for daily production runs

**Monthly Batches**: Use `%(year)s-%(month)s-`
- New sequence each month
- Good for monthly inventory cycles

**Yearly Batches**: Use `%(year)s-`
- New sequence each year
- Good for annual product lines

### 2. Consider Sequence Exhaustion

**Problem**: If you use daily format and generate 10,000 lots per day, you might exhaust the sequence.

**Solution**: Use appropriate padding
```
%(y)s%(month)s%(day)s with padding=7
→ 2411200000001 to 2411209999999 (10 million lots per day)
```

### 3. Human Readability vs Compactness

**Compact** (machine-friendly):
```
%(y)s%(month)s%(day)s → 2411200000001
```

**Readable** (human-friendly):
```
LOT-%(year)s-%(month)s-%(day)s- → LOT-2024-11-20-0000001
```

### 4. Avoid Time-Based Codes for Large Batches

**Not Recommended**:
```
%(y)s%(month)s%(day)s%(h24)s%(min)s
```

**Why**: If batch generation takes > 1 minute, lots might have different timestamps, causing confusion.

**Better**: Use date-only codes for consistency within batches.

## Testing Date Formats

### Quick Test

1. Configure format on product
2. Check **Next Number** field
3. Create a single lot manually
4. Verify the format is correct

### Batch Test

```python
# Create test product
product = env['product.product'].create({
    'name': 'Test Product',
    'tracking': 'serial',
})

# Set date format
product.product_tmpl_id.serial_prefix_format = '%(y)s%(month)s%(day)s'

# Generate 10 lots
picking = env['stock.picking'].create({...})
move = env['stock.move'].create({
    'product_id': product.id,
    'product_uom_qty': 10,
    ...
})

# Check generated lot names
# All should start with current date (e.g., 241120)
```

### Run Test Suite

```bash
# Test date format functionality
odoo-bin -c odoo.conf -d test_db --test-tags product_lot_sequence_per_product.test_date_format
```

## Troubleshooting

### Issue: Date codes not being replaced

**Symptoms**: Lot names show literal `%(y)s` instead of `24`

**Causes**:
1. Using old version of module (< 1.1.1)
2. Incorrect format syntax

**Solutions**:
1. Upgrade to version 1.1.1 or later
2. Check format syntax (must be exactly `%(code)s`)
3. Restart Odoo after upgrade

### Issue: Wrong date values

**Symptoms**: Date shows yesterday or tomorrow

**Causes**:
1. Server timezone misconfiguration
2. Database timezone issues

**Solutions**:
1. Check server timezone: `date` command
2. Check Odoo timezone configuration
3. Verify PostgreSQL timezone settings

### Issue: Inconsistent dates in batch

**Symptoms**: Some lots have different dates in same batch

**Causes**:
1. Batch generation crossed midnight
2. Using time-based codes (hour/minute)

**Solutions**:
1. Generate batches earlier in the day
2. Use date-only codes (avoid hour/minute)
3. Accept minor inconsistency for midnight batches

## Performance Impact

### Date Interpolation Performance

**Single Lot**:
- Date interpolation: ~0.001 seconds
- Negligible impact

**Batch of 1000 Lots**:
- Date interpolation: ~0.001 seconds (once)
- Sequence allocation: ~0.5 seconds
- Lot creation: ~5 seconds
- **Total**: ~5.5 seconds

**Conclusion**: Date format codes have **no measurable performance impact** on batch generation.

## Advanced Examples

### Example: Product Code + Date
```
PROD-A-%(year)s%(month)s-
→ PROD-A-202411-0000001
```

### Example: Facility + Date
```
NYC-%(y)s%(doy)s-
→ NYC-24325-0000001 (Day 325 of 2024)
```

### Example: Shift-Based
```
SHIFT-%(y)s%(month)s%(day)s-%(h24)s-
→ SHIFT-241120-14-0000001 (2 PM shift)
```

### Example: Week-Based Production
```
WK%(woy)s-%(year)s-
→ WK47-2024-0000001
```

## Migration from Fixed Prefixes

### Before (Fixed Prefix)
```
Prefix: LOT-2024-
Generated: LOT-2024-0000001, LOT-2024-0000002, ...
Problem: Need to manually update prefix each year
```

### After (Dynamic Date)
```
Prefix: LOT-%(year)s-
Generated: LOT-2024-0000001, LOT-2024-0000002, ...
Benefit: Automatically updates to LOT-2025- next year
```

### Migration Steps
1. Note current sequence number
2. Update prefix to use date codes
3. Verify next number is correct
4. Test with single lot
5. Deploy to production

## Summary

Date format codes provide:
- ✓ Dynamic lot numbering based on current date/time
- ✓ Automatic date updates (no manual changes needed)
- ✓ Flexible formatting options
- ✓ No performance impact
- ✓ Batch generation support
- ✓ Full compatibility with all module features

Use date format codes to create intelligent, self-updating lot numbering schemes that adapt to your production schedule automatically.