Update documentation for API, configuration, and model
API.md: - Add export formats (JSON, XML, EGF, FFG, CSV) - Document /explain endpoint for pairing analysis - Add PUT /standings for freezing - Improve parameter documentation - Fix typos (regitration -> registration, #tip -> #tid) configuration.md: - Add property loading hierarchy - Document SSL/TLS configuration - Add OAuth provider configuration - Add ratings.path property - Include example configurations model.md: - Complete entity diagram with Team, external IDs - Document all tournament types (PAIRGO, RENGO, TEAM) - Add TimeSystem types and parameters - Document all pairing parameters - List all 39 tiebreak criteria - Add external database (AGA, EGF, FFG) documentation
This commit is contained in:
Claude Brisson
312
doc/model.md
312
doc/model.md
@@ -1,9 +1,7 @@
|
||||
# PairGoth model
|
||||
# Pairgoth Model
|
||||
|
||||
## Entity Relationship Diagram
|
||||
|
||||
For simplicity, teams (pairgo, rengo) and teams of individuals (clubs championships) are not included.
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
|
||||
@@ -11,22 +9,23 @@ erDiagram
|
||||
|
||||
Tournament {
|
||||
int id
|
||||
string type
|
||||
Type type
|
||||
string name
|
||||
string shortName
|
||||
date startDate
|
||||
date endDate
|
||||
string director
|
||||
string country
|
||||
string location
|
||||
bool isOnline
|
||||
bool online
|
||||
int rounds
|
||||
int gobanSize
|
||||
string rules
|
||||
int komi
|
||||
Rules rules
|
||||
double komi
|
||||
}
|
||||
|
||||
TimeSystem {
|
||||
string type
|
||||
TimeSystemType type
|
||||
int mainTime
|
||||
int increment
|
||||
int maxTime
|
||||
@@ -37,18 +36,17 @@ erDiagram
|
||||
|
||||
Pairing {
|
||||
PairingType type
|
||||
BaseParams base
|
||||
MainParams main
|
||||
SecondaryParams secondary
|
||||
GeographicalParams geo
|
||||
HandicapParams handicap
|
||||
PlacementParams place
|
||||
PairingParams pairingParams
|
||||
PlacementParams placementParams
|
||||
}
|
||||
|
||||
|
||||
Game {
|
||||
int id
|
||||
int table
|
||||
int handicap
|
||||
string result
|
||||
Result result
|
||||
int drawnUpDown
|
||||
bool forcedTable
|
||||
}
|
||||
|
||||
Player {
|
||||
@@ -58,13 +56,26 @@ erDiagram
|
||||
string country
|
||||
string club
|
||||
int rating
|
||||
string rank
|
||||
int rank
|
||||
bool final
|
||||
array skip
|
||||
int mmsCorrection
|
||||
set skip
|
||||
map externalIds
|
||||
}
|
||||
|
||||
|
||||
Team {
|
||||
int id
|
||||
string name
|
||||
set playerIds
|
||||
int rating
|
||||
int rank
|
||||
bool final
|
||||
int mmsCorrection
|
||||
set skip
|
||||
}
|
||||
|
||||
Standings {
|
||||
array criteria
|
||||
list criteria
|
||||
}
|
||||
|
||||
%% relationships
|
||||
@@ -72,9 +83,266 @@ erDiagram
|
||||
Tournament ||--|{ TimeSystem: "time system"
|
||||
Tournament ||--|{ Pairing: "pairing"
|
||||
Tournament ||--|{ Game: "round"
|
||||
Tournament }o--|{ Player: "participate(round)"
|
||||
Tournament }o--|{ Player: "players"
|
||||
Tournament }o--|{ Team: "teams"
|
||||
Team }o--|{ Player: "members"
|
||||
Game ||--|| Player: "black"
|
||||
Game ||--|| Player: "white"
|
||||
Player }|--|| Standings: "position"
|
||||
|
||||
|
||||
```
|
||||
|
||||
## Tournament
|
||||
|
||||
Sealed class hierarchy for different tournament formats.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | int | Tournament identifier |
|
||||
| type | Type | Tournament format |
|
||||
| name | string | Full tournament name |
|
||||
| shortName | string | Abbreviated name |
|
||||
| startDate | date | Start date |
|
||||
| endDate | date | End date |
|
||||
| director | string | Tournament director |
|
||||
| country | string | Country code (default: "fr") |
|
||||
| location | string | Venue location |
|
||||
| online | bool | Is online tournament |
|
||||
| rounds | int | Total number of rounds |
|
||||
| gobanSize | int | Board size (default: 19) |
|
||||
| rules | Rules | Scoring rules |
|
||||
| komi | double | Komi value (default: 7.5) |
|
||||
| timeSystem | TimeSystem | Time control |
|
||||
| pairing | Pairing | Pairing system |
|
||||
| tablesExclusion | list | Table exclusion rules per round |
|
||||
|
||||
### Tournament Types
|
||||
|
||||
| Type | Players/Team | Description |
|
||||
|------|--------------|-------------|
|
||||
| INDIVIDUAL | 1 | Individual players |
|
||||
| PAIRGO | 2 | Pair Go (alternating) |
|
||||
| RENGO2 | 2 | Rengo with 2 players |
|
||||
| RENGO3 | 3 | Rengo with 3 players |
|
||||
| TEAM2 | 2 | Team with 2 boards |
|
||||
| TEAM3 | 3 | Team with 3 boards |
|
||||
| TEAM4 | 4 | Team with 4 boards |
|
||||
| TEAM5 | 5 | Team with 5 boards |
|
||||
|
||||
### Rules
|
||||
|
||||
- `AGA` - American Go Association
|
||||
- `FRENCH` - French Go Association
|
||||
- `JAPANESE` - Japanese rules
|
||||
- `CHINESE` - Chinese rules
|
||||
|
||||
## Player
|
||||
|
||||
Individual tournament participant.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | int | Player identifier |
|
||||
| name | string | Last name |
|
||||
| firstname | string | First name |
|
||||
| country | string | Country code |
|
||||
| club | string | Club affiliation |
|
||||
| rating | int | EGF-style rating |
|
||||
| rank | int | Rank (-30=30k to 8=9D) |
|
||||
| final | bool | Is registration confirmed |
|
||||
| mmsCorrection | int | MacMahon score correction |
|
||||
| skip | set | Skipped round numbers |
|
||||
| externalIds | map | External IDs (AGA, EGF, FFG) |
|
||||
|
||||
## Team
|
||||
|
||||
Team participant (for team tournaments).
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | int | Team identifier |
|
||||
| name | string | Team name |
|
||||
| playerIds | set | Member player IDs |
|
||||
| rating | int | Computed from members |
|
||||
| rank | int | Computed from members |
|
||||
| final | bool | Is registration confirmed |
|
||||
| mmsCorrection | int | MacMahon score correction |
|
||||
| skip | set | Skipped round numbers |
|
||||
|
||||
## Game
|
||||
|
||||
Single game in a round.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | int | Game identifier |
|
||||
| table | int | Table number (0 = unpaired) |
|
||||
| white | int | White player ID (0 = bye) |
|
||||
| black | int | Black player ID (0 = bye) |
|
||||
| handicap | int | Handicap stones |
|
||||
| result | Result | Game outcome |
|
||||
| drawnUpDown | int | DUDD value |
|
||||
| forcedTable | bool | Is table manually assigned |
|
||||
|
||||
### Result
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| ? | Unknown (not yet played) |
|
||||
| w | White won |
|
||||
| b | Black won |
|
||||
| = | Jigo (draw) |
|
||||
| X | Cancelled |
|
||||
| # | Both win (unusual) |
|
||||
| 0 | Both lose (unusual) |
|
||||
|
||||
## TimeSystem
|
||||
|
||||
Time control configuration.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| type | TimeSystemType | System type |
|
||||
| mainTime | int | Main time in seconds |
|
||||
| increment | int | Fischer increment |
|
||||
| maxTime | int | Fischer max time |
|
||||
| byoyomi | int | Byoyomi time per period |
|
||||
| periods | int | Number of byoyomi periods |
|
||||
| stones | int | Stones per period (Canadian) |
|
||||
|
||||
### TimeSystemType
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| CANADIAN | Canadian byoyomi |
|
||||
| JAPANESE | Japanese byoyomi |
|
||||
| FISCHER | Fischer increment |
|
||||
| SUDDEN_DEATH | No overtime |
|
||||
|
||||
## Pairing
|
||||
|
||||
Pairing system configuration.
|
||||
|
||||
### Pairing Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| SWISS | Swiss system |
|
||||
| MAC_MAHON | MacMahon system |
|
||||
| ROUND_ROBIN | Round robin (not implemented) |
|
||||
|
||||
### MacMahon-specific
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| mmFloor | int | MacMahon floor (default: -20 = 20k) |
|
||||
| mmBar | int | MacMahon bar (default: 0 = 1D) |
|
||||
|
||||
### Base Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| nx1 | Concavity curve factor (0.0-1.0) |
|
||||
| dupWeight | Duplicate game avoidance weight |
|
||||
| random | Randomization factor |
|
||||
| deterministic | Deterministic pairing |
|
||||
| colorBalanceWeight | Color balance importance |
|
||||
| byeWeight | Bye assignment weight |
|
||||
|
||||
### Main Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| categoriesWeight | Avoid mixing categories |
|
||||
| scoreWeight | Minimize score differences |
|
||||
| drawUpDownWeight | Draw-up/draw-down weighting |
|
||||
| compensateDrawUpDown | Enable DUDD compensation |
|
||||
| drawUpDownUpperMode | TOP, MIDDLE, or BOTTOM |
|
||||
| drawUpDownLowerMode | TOP, MIDDLE, or BOTTOM |
|
||||
| seedingWeight | Seeding importance |
|
||||
| lastRoundForSeedSystem1 | Round cutoff for system 1 |
|
||||
| seedSystem1 | First seeding method |
|
||||
| seedSystem2 | Second seeding method |
|
||||
| mmsValueAbsent | MMS for absent players |
|
||||
| roundDownScore | Floor vs round scores |
|
||||
|
||||
### Seed Methods
|
||||
|
||||
- `SPLIT_AND_FOLD`
|
||||
- `SPLIT_AND_RANDOM`
|
||||
- `SPLIT_AND_SLIP`
|
||||
|
||||
### Secondary Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| barThresholdActive | Don't apply below bar |
|
||||
| rankSecThreshold | Rank limit for criteria |
|
||||
| nbWinsThresholdActive | Score threshold |
|
||||
| defSecCrit | Secondary criteria weight |
|
||||
|
||||
### Geographical Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| avoidSameGeo | Avoid same region |
|
||||
| preferMMSDiffRatherThanSameCountry | Country preference |
|
||||
| preferMMSDiffRatherThanSameClubsGroup | Club group preference |
|
||||
| preferMMSDiffRatherThanSameClub | Club preference |
|
||||
|
||||
### Handicap Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| weight | Handicap minimization weight |
|
||||
| useMMS | Use MMS vs rank |
|
||||
| rankThreshold | Rank threshold |
|
||||
| correction | Handicap reduction |
|
||||
| ceiling | Max handicap stones |
|
||||
|
||||
## Placement Criteria
|
||||
|
||||
Tiebreak criteria for standings, in order of priority.
|
||||
|
||||
### Score-based
|
||||
|
||||
| Criterion | Description |
|
||||
|-----------|-------------|
|
||||
| NBW | Number of wins |
|
||||
| MMS | MacMahon score |
|
||||
| STS | Strasbourg score |
|
||||
| CPS | Cup score |
|
||||
| SCOREX | Congress score |
|
||||
|
||||
### Opponent-based (W = wins, M = MMS)
|
||||
|
||||
| Criterion | Description |
|
||||
|-----------|-------------|
|
||||
| SOSW / SOSM | Sum of opponent scores |
|
||||
| SOSWM1 / SOSMM1 | SOS minus worst |
|
||||
| SOSWM2 / SOSMM2 | SOS minus two worst |
|
||||
| SODOSW / SODOSM | Sum of defeated opponent scores |
|
||||
| SOSOSW / SOSOSM | Sum of opponent SOS |
|
||||
| CUSSW / CUSSM | Cumulative score sum |
|
||||
|
||||
### Other
|
||||
|
||||
| Criterion | Description |
|
||||
|-----------|-------------|
|
||||
| CATEGORY | Player category |
|
||||
| RANK | Player rank |
|
||||
| RATING | Player rating |
|
||||
| DC | Direct confrontation |
|
||||
| SDC | Simplified direct confrontation |
|
||||
| EXT | Exploits attempted |
|
||||
| EXR | Exploits successful |
|
||||
|
||||
## External Databases
|
||||
|
||||
Player IDs can be linked to external rating databases:
|
||||
|
||||
| Database | Description |
|
||||
|----------|-------------|
|
||||
| AGA | American Go Association |
|
||||
| EGF | European Go Federation |
|
||||
| FFG | French Go Association |
|
||||
|
||||
Reference in New Issue
Block a user