docs: update documentation for normalized config and improve command

- Add improve command to all command tables and usage sections
- Add normalized_config field to BestCarRecord struct documentation
- Update CarCounts.by_rid type from String to (String, String)
- Update CarCounts.guid_to_rid type to HashMap<String, HashSet<(String, String)>>
- Add owned_configs field to MyCarsData and CarCounts docs
- Add normalize_to_final_build() to API docs
- Update CSV format examples to include FinalBuild column
- Update my_cars.json structure with engineMajor/weightMajor/chassisMajor
- Update timing file example with v2c_ version prefix
- Add version prefix stripping to data transformation docs
- Update CHANGELOG.md with Unreleased section
- Fix compare_records description to include normalized config sorting
This commit is contained in:
Jan-Peter von Hunnius 2026-05-11 16:58:01 +02:00
parent bf21d3d1f6
commit 2b0602d564
6 changed files with 204 additions and 84 deletions

View file

@ -86,18 +86,18 @@ cargo run --bin records -- best --min-count 5
`best.csv`:
```csv
RQ,Brand,Model,Year,Count
85,McLaren,F1,1993,15
82,Ferrari,250 GTO,1962,12
80,Lamborghini,Countach,1974,8
75,Porsche,911 Turbo,1975,6
RQ,Brand,Model,Year,FinalBuild,Count
85,McLaren,F1,1993,323,15
82,Ferrari,250 GTO,1962,332,12
80,Lamborghini,Countach,1974,233,8
75,Porsche,911 Turbo,1975,332,6
```
`very_best.csv`:
```csv
RQ,Brand,Model,Year,Count
85,McLaren,F1,1993,15
82,Ferrari,250 GTO,1962,12
RQ,Brand,Model,Year,FinalBuild,Count
85,McLaren,F1,1993,323,15
82,Ferrari,250 GTO,1962,332,12
```
**Understanding the output:**
@ -105,6 +105,7 @@ RQ,Brand,Model,Year,Count
- **Brand**: Car manufacturer
- **Model**: Car model name
- **Year**: Model year
- **FinalBuild**: Normalized tune configuration (323, 233, or 332)
- **Count**: How many times this car was the fastest across different tracks
**Interpretation:**
@ -164,24 +165,24 @@ cargo run --bin records -- wishlist --min-count 5 --max-wishlist 500
`wishlist.csv`:
```csv
RQ,Brand,Model,Year,Count
90,Pagani,Zonda R,2010,18
88,Ferrari,F40,1987,15
87,McLaren,Senna,2018,12
RQ,Brand,Model,Year,FinalBuild,Count
90,Pagani,Zonda R,2010,323,18
88,Ferrari,F40,1987,332,15
87,McLaren,Senna,2018,233,12
```
`add.csv`:
```csv
RQ,Brand,Model,Year,Count
90,Pagani,Zonda R,2010,18
88,Ferrari,F40,1987,15
RQ,Brand,Model,Year,FinalBuild,Count
90,Pagani,Zonda R,2010,323,18
88,Ferrari,F40,1987,332,15
```
`remove.csv`:
```csv
RQ,Brand,Model,Year,Count
75,BMW,M3,2003,3
72,Audi,RS6,2002,2
RQ,Brand,Model,Year,FinalBuild,Count
75,BMW,M3,2003,332,3
72,Audi,RS6,2002,233,2
```
**Action items:**
@ -196,7 +197,7 @@ RQ,Brand,Model,Year,Count
cargo run --bin records -- all
```
**Purpose:** Generates all 6 CSV files in a single parse pass. Equivalent to running `best`, `trash`, and `wishlist` together, but more efficient since data is only parsed once.
**Purpose:** Generates all 7 CSV files in a single parse pass. Equivalent to running `best`, `trash`, `wishlist`, and `improve` together, but more efficient since data is only parsed once.
**Flags:**
- `--min-count N` — Minimum number of tracks for "very best" qualification (default: 10)
@ -214,6 +215,38 @@ cargo run --bin records -- all --min-count 5 --max-wishlist 500
- `wishlist.csv` — Ideal wishlist (very_best unowned, capped)
- `add.csv` — Cars to add to wishlist
- `remove.csv` — Cars to remove from wishlist
- `improve.csv` — Owned cars not yet at final build config
#### Improve Analysis
**Command:**
```bash
cargo run --bin records -- improve
```
**Purpose:** Generates `improve.csv` — owned cars whose actual tune configuration is not yet a final build (323, 233, or 332). Sorted by number of best tracks descending, so the most impactful upgrades appear first.
**Output File:**
`improve.csv`:
```csv
RQ,Brand,Model,Year,Target,Count
90,Pagani,Zonda R,2010,323,18
85,McLaren,F1,1993,332,15
```
**Understanding the output:**
- **RQ**: Car's rarity level
- **Brand**: Car manufacturer
- **Model**: Car model name
- **Year**: Model year
- **Target**: The final build config the player should upgrade to
- **Count**: How many tracks this car is best on (across all its configs)
**Interpretation:**
- Focus on cars with the highest Count first — upgrading them benefits the most tracks
- The Target column shows which of the three final builds (323, 233, 332) to aim for
- Cars already at a final build or maxed config are automatically excluded
#### Detailed Performance Data
@ -285,19 +318,20 @@ cargo run --bin records -- fetch && cargo run --bin records -- all
### What `all` Does
1. **Parses** all timing data in a single pass
2. **Generates** all 6 output CSV files
3. **Sorts** all files by car RQ
2. **Generates** all 7 output CSV files
3. **Sorts** all files by car RQ (and FinalBuild where applicable)
### Output Files
| File | Format | Description |
|------|--------|-------------|
| `best.csv` | `RQ,Brand,Model,Year,Count` | All cars best on at least one track |
| `very_best.csv` | `RQ,Brand,Model,Year,Count` | Cars best on ≥ min_count tracks |
| `best.csv` | `RQ,Brand,Model,Year,FinalBuild,Count` | All cars best on at least one track |
| `very_best.csv` | `RQ,Brand,Model,Year,FinalBuild,Count` | Cars best on ≥ min_count tracks |
| `trash.csv` | `RQ,Brand,Model,Year` | Owned cars not best on any track (RQ<80, not prize) |
| `wishlist.csv` | `RQ,Brand,Model,Year,Count` | Ideal wishlist (very_best unowned, capped) |
| `add.csv` | `RQ,Brand,Model,Year,Count` | Cars to add to wishlist |
| `remove.csv` | `RQ,Brand,Model,Year,Count` | Cars to remove from wishlist |
| `wishlist.csv` | `RQ,Brand,Model,Year,FinalBuild,Count` | Ideal wishlist (very_best unowned, capped) |
| `add.csv` | `RQ,Brand,Model,Year,FinalBuild,Count` | Cars to add to wishlist |
| `remove.csv` | `RQ,Brand,Model,Year,FinalBuild,Count` | Cars to remove from wishlist |
| `improve.csv` | `RQ,Brand,Model,Year,Target,Count` | Owned cars not yet at final build config |
### Typical Daily Routine
@ -421,7 +455,7 @@ The tool generates CSV files for external analysis. All files are sorted by car
#### "Please provide a command"
**Problem:** No arguments provided
**Solution:** Use `best`, `trash`, `wishlist`, `all`, `details`, `track`, or `fetch`
**Solution:** Use `best`, `trash`, `wishlist`, `all`, `details`, `track`, `improve`, or `fetch`
#### "Could not read my cars file" / "Missing data file"
**Problem:** `my_cars.json` (or another data file) not found or not readable