PostERG/xamxam
1
0
Fork 0
mirror of https://codeberg.org/PostERG/xamxam.git synced 2026-09-25 01:53:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: verify and refactor documentation to match current codebase

Browse Source
This commit is contained in:
Pontoporeia
2026-08-24 11:31:38 +02:00
parent b2cdbd0174
commit e9747edce0
17 changed files with 1006 additions and 1442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/import.md
+89 -134
View File
@@ -1,153 +1,108 @@
# CSV Import Format Specification
# CSV Import
## File Format
Import of theses from the admin panel, plus the CSV structure and behaviour.
- **Encoding**: UTF-8
- **Delimiter**: Comma (`,`)
- **Header Rows**: First 4 rows are skipped during import
- Row 1: Empty
- Row 2: Headers (French labels)
- Row 3: Description row
- Row 4: Column names
- **Data Rows**: Start from row 5 onwards
> **Where it lives:** the CSV import is handled **inline** in
> `app/public/admin/index.php` — there is no separate `import.php` action. The
> `/admin/import.php` file only redirects to `/admin/`.
## Column Structure
---
The CSV must contain exactly 21 columns in this order:
## File format
| Index | Field Name | Required | Type | Description |
|-------|------------|----------|------|-------------|
| 0 | identifier | No | String | Unique identifier for the thesis |
| 1 | title | **Yes** | String | Thesis title |
| 2 | subtitle | No | String | Thesis subtitle |
| 3 | authors | No | String | Author(s), comma-separated for multiple |
| 4 | contact | No | String | Contact email (associated with first author) |
| 5 | supervisors | No | String | Supervisor(s), comma-separated for multiple |
| 6 | formats | No | String | Format(s), comma-separated for multiple |
| 7 | year | **Yes** | Integer | Year of thesis (e.g., 2024) |
| 8 | ap | No | String | AP program code (see AP Codes section) |
| 9 | orientation | No | String | Orientation code (see Orientation Codes section) |
| 10 | finality | No | String | Finality name |
| 11 | keywords | No | String | Keywords, comma-separated (max 10) |
| 12 | synopsis | No | Text | Synopsis/abstract of the thesis |
| 13 | context | No | Text | Context note |
| 14 | remarks | No | Text | Additional remarks |
| 15 | language | No | String | Language (e.g., Français, English, Nederlands) |
| 16 | access | No | String | Access authorization |
| 17 | license | No | String | License information |
| 18 | size_info | No | String | File size information |
| 19 | jury_points | No | Float | Jury score (out of 20) |
| 20 | baiu_link | No | String | Link to BAIU (institutional archive) |
- **Encoding:** UTF-8
- **Delimiter:** comma (`,`), quoting with double quotes (`""` escapes a quote)
- **Header detection:** the importer scans up to **8 rows** looking for a header
row containing at least **11 recognised column names**. Matching is flexible:
prefix/substring/variant matching (e.g. `contact.visible` matches `contact`,
`Licence` ↔ `License`, `Promoteur·ice(s) université` matches `ulb`).
- **No header fallback:** if no header row is found, the importer falls back to
**positional** interpretation, skipping the first **4 rows** (the legacy
template layout with label/description rows).
## Field Details
So import files are robust to column reordering as long as meaningful headers
are present; legacy fixed-position files (skip-4) also still work.
### Required Fields
- **title**: Must not be empty
- **year**: Must not be empty and must be a valid integer
---
### Multi-Value Fields
These fields accept multiple values separated by commas:
- **authors**: e.g., `"John Doe, Jane Smith"`
- **supervisors**: e.g., `"Prof. A, Prof. B"`
- **keywords**: Maximum 10 keywords, e.g., `"art, design, digital"`
- **formats**: e.g., `"PDF, Video, Installation"`
## Recognised columns
### Orientation Codes
Valid orientation codes and their full names:
Headings are matched by the keywords below (case-insensitive). They mirror the
**export** header names in `ExportController::CSV_HEADERS`.
| Export header (order in export) | Imported as | Notes |
|---|---|---|
| `Identifiant` | identifier | Optional; if it already exists, the row is skipped |
| `Titre` | title | **Required** |
| `Sous-titre` | subtitle | |
| `Auteur·ice(s)` | authors | comma-separated; first author gets `Contact` |
| `Contact` | contact | email; `OUI`/`NON` artefacts emptied |
| `Promoteur·ice(s) interne` | promoteur (interne) | role `promoteur`, `is_ulb=0` |
| `Lecteur·ice(s) interne` | lecteur (interne) | role `lecteur`, `is_external=0` |
| `Lecteur·ice(s) externe` | lecteur (externe) | role `lecteur`, `is_external=1` |
| `Promoteur·ice(s) université` | promoteur (ulb) | role `promoteur`, `is_ulb=1` |
| `Format(s)` | formats | comma-separated; matched to `format_types` |
| `Année` | année | **Required** unless derivable from `Identifiant` (`2024-003` → 2024) |
| `AP` | ap | AP program code or name |
| `Orientation` | orientation | code or full name (see below) |
| `Finalité` | finalité | matched to `finality_types` |
| `Mots-clés` | mots-clés | comma-separated; lowercase-normalised; max 10 |
| `Synopsis` | synopsis | |
| `Contexte` | contexte | context note |
| `Remarques` | remarques | |
| `Langue` | langue | comma-separated; stored lowercase; created if missing |
| `Autorisation` | autorisation | access type name → `access_types`; default `Libre` if unknown |
| `Licence` / `License` | license | licence name |
| `Points sur 20` | points | float (jury points) |
| `Lien BAIU` | lien baiu | institutional link |
| `CC2r`, `Exemplaire BAIU`, `Exemplaire ERG` | *(export only)* | written by export; ignored on import |
> Positional-fallback indices (0-based): `0` Identifier, `1` Titre, `2`
> Sous-titre, `3` Auteur, `4` Contact, `5` Promoteurs, `6` Lecteurs internes,
> `7` Lecteurs externes, `8` Promoteurs ULB, `9` Formats, `10` Année, `11` AP,
> `12` Orientation, `13` Finalité, `14` Mots-clés, `15` Synopsis, `16` Contexte,
> `17` Remarques, `18` Langue, `19` Autorisation, `20` Licence, `21` Points,
> `22` Lien BAIU.
The three trailing **export-only** columns (CC2r / Exemplaire BAIU / Exemplaire
ERG) are not currently read back on import.
---
## Orientation & AP values
Orientation codes (legacy short form) and aliases are normalised to canonical
DB names. Recognised codes:
```
SC = Sculpture
VI = Vidéographie
CA = Cinéma d'animation
IP = Installation-Performance
PE = Peinture
PH = Photographie
DE = Dessin
AN = Arts Numériques
GR = Graphisme
TY = Typographie
DN = Design Numérique
IL = Illustration
BD = Bande-Dessinée
SE = Sérigraphie
GV = Gravure
AN=Arts Numériques, DE=Dessin, CA=Cinéma d'animation, IP=Installation-Performance,
PE=Peinture, PH=Photographie, SC=Sculpture, VI=Vidéographie, GR=Graphisme,
TY=Typographie, DN=Design Numérique, IL=Illustration, BD=Bande-Dessinée,
SE=Sérigraphie, GV=Gravure
```
### AP Codes
Valid AP program codes:
- `DPM`
- `LIENS`
- `APS`
AP programs (by code or name): `NS` Narration Spéculative, `DPM` Design et
Politique du Multiple, `APS` Atelier Pratiques Situées, `LIENS`, `PACS`.
(These codes must match exactly what exists in the `ap_programs` table)
---
### Language Values
Languages should be provided with capital first letter:
- `Français`
- `English`
- `Nederlands`
- etc.
## Import behaviour
### Format Values
Common format values (case-insensitive, will be normalized):
- `PDF`
- `Video`
- `Audio`
- `Installation`
- `Web`
- etc.
- **Transaction per row** — a failed row is rolled back and logged; import
continues.
- **Required:** `Titre` and `Année` (year may be derived from the identifier).
- Empty rows (no title and no identifier) are skipped.
- Authors, supervisors, languages and tags are auto-created if missing.
- **Tag normalisation:** `strtolower`, collapse multiple spaces, de-duplicate,
cap at 10.
- Duplicate `Identifiant` → row skipped (not re-inserted).
- Results summary reports: imported count, skipped count, and per-row
`✓`/`✗` messages.
## Import Behavior
---
### Row Processing
1. Empty rows (no title and no identifier) are skipped
2. Each row is processed in a transaction
3. If a row fails, it is skipped and logged, but processing continues
## Restore procedure
### Data Validation
- If title or year is missing, the row is rejected
- Invalid orientation codes result in no orientation being set (null)
- Invalid AP codes result in no AP program being set (null)
- Keywords are limited to first 10 if more are provided
### Data Normalization
- All string fields are trimmed of whitespace
- Language and format values are normalized (first letter capitalized, rest lowercase)
- Empty strings are converted to NULL in the database
### Entity Creation
- Authors, supervisors, and keywords are automatically created if they don't exist
- Existing authors are matched by name
- Contact email is only associated with the first author
## Example CSV Structure
```csv
Identifiant,Titre,Sous-titre,Auteur·ice(s),Contact,Promoteur·ice(s),Format,Année,AP,Orientation,Finalité,Mots-clés,Synopsis,Contexte,Remarques,Langue,Autorisation,License,taille,Points sur 20,lien BAIU
TFE-2024-001,Mon projet artistique,Exploration du numérique,"Alice Dupont, Bob Martin",alice@example.com,Prof. Smith,PDF,2024,DPM,AN,Création,art numérique,digital art,interactive installation,Un projet explorant l'intersection de l'art et de la technologie,Réalisé dans le cadre du master,Très bon projet,Français,Public,CC-BY,250MB,16.5,https://baiu.example.org/12345
TFE-2024-002,Design graphique moderne,,Charlie Brown,charlie@example.com,"Prof. A, Prof. B","PDF, Print",2024,LIENS,GR,Design,typographie,graphisme,design,Une exploration de la typographie contemporaine,,,English,Restricted,All rights reserved,50MB,15,
```
## Troubleshooting
### Common Issues
1. **Encoding problems**: Ensure file is saved as UTF-8
2. **Missing columns**: All 21 columns must be present, even if empty
3. **Line breaks in fields**: Ensure fields containing newlines are properly quoted
4. **Quote escaping**: Use double quotes (`""`) to escape quotes within fields
### Import Results
After import, the system will display:
- Number of theses successfully imported
- Number of rows skipped due to errors
- Detailed line-by-line results with success (✓) or error (✗) indicators
## Notes
- The import process preserves the order of authors, supervisors, and keywords
- The first author gets the contact email if provided
- Duplicate detection is not performed - each import creates new entries
- Failed rows do not stop the import process
- All errors are logged to the server error log
Full restore combines the three exports (CSV + DB + files). See
[export.md](export.md) for the step-by-step restore of the database and files;
the CSV is re-importable as described above when rebuilding from scratch.