mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-09-25 01:53:03 +02:00
docs: verify and refactor documentation to match current codebase
This commit is contained in:
Pontoporeia
+68
-142
@@ -1,172 +1,98 @@
|
||||
# Search Feature Documentation
|
||||
# Search & Répertoire — Documentation
|
||||
|
||||
## Overview
|
||||
The search feature allows users to search across theses using multiple criteria including full-text search and advanced filters.
|
||||
Two public browsing surfaces, both handled by `app/src/Controllers/SearchController.php`
|
||||
and routed by `app/src/Dispatcher.php`:
|
||||
|
||||
## Files Created/Modified
|
||||
| Route | Handler | Purpose |
|
||||
|-------|---------|---------|
|
||||
| `/search`, `/search.php` | `handleSearch()` | Full-text query + classic single filters |
|
||||
| `/repertoire`, `/repertoire.php` | `handleRepertoire()` | Browseable directory with multi-select filters |
|
||||
|
||||
### New Files
|
||||
1. **search.php** - Main search interface page
|
||||
2. **create_test_db.php** - Script to generate test database with sample data
|
||||
3. **search.md** - This documentation file
|
||||
Both only ever expose **published** theses (`is_published = 1`).
|
||||
|
||||
### Modified Files
|
||||
1. **Database.php** - Added search methods:
|
||||
- `searchTheses()` - Search with multiple filters
|
||||
- `countSearchResults()` - Count matching results
|
||||
- `getAvailableYears()` - Get all years from published theses
|
||||
- `getOrientations()` - Get all orientations
|
||||
- `getApPrograms()` - Get all AP programs
|
||||
- `getFinalityTypes()` - Get all finality types
|
||||
- `getUsedKeywords()` - Get keywords used in published theses
|
||||
- `getFormatTypes()` - Get all format types
|
||||
- `getLanguages()` - Get all languages
|
||||
---
|
||||
|
||||
2. **inc/header.php** - Added "Rechercher" link to navigation
|
||||
## HandleSearch (`/search`)
|
||||
|
||||
## Searchable Fields
|
||||
`handleSearch()` reads from `$_GET` and renders `app/templates/public/search.php`
|
||||
with the results fragment (`app/templates/partials/search-results.php`).
|
||||
|
||||
The search feature allows filtering by:
|
||||
Searchable text fields (via `Database::searchTheses()`):
|
||||
- Title, subtitle, synopsis, author names, supervisor names, tags/keywords.
|
||||
|
||||
1. **Full-text query** - Searches across:
|
||||
- Title
|
||||
- Subtitle
|
||||
- Synopsis
|
||||
- Author names
|
||||
- Supervisor names
|
||||
- Keywords
|
||||
Single-value filters (`collectSearchParams()`):
|
||||
- `query` — free text
|
||||
- `year` — exact year
|
||||
- `orientation` — artistic orientation
|
||||
- `ap_program` — AP program
|
||||
- `finality` — finality type
|
||||
- `format` — format
|
||||
- `keyword` — tag/keyword
|
||||
|
||||
2. **Year** - Filter by specific year
|
||||
Results are paginated (`limit = 20` default); the **search bar**
|
||||
(`app/templates/partials/search-bar.php`) submits a GET form to `/search`.
|
||||
|
||||
3. **Orientation** - Filter by artistic orientation:
|
||||
- Arts Numériques, Dessin, Cinéma d'animation, Installation-Performance
|
||||
- Peinture, Photographie, Sculpture, Vidéographie
|
||||
- Graphisme, Typographie, Design Numérique, Illustration
|
||||
- Bande-Dessinée, Sérigraphie, Gravure
|
||||
---
|
||||
|
||||
4. **AP Program** - Filter by atelier pratique:
|
||||
- Narration Spéculative
|
||||
- Design et Politique du Multiple (DPM)
|
||||
- Atelier Pratiques Situées (APS)
|
||||
- Lieux, Interdisciplinarités, Écologie, Nécessité, Systèmes (LIENS)
|
||||
## HandleRepertoire (`/repertoire`)
|
||||
|
||||
5. **Finality** - Filter by master finality:
|
||||
- Approfondi
|
||||
- Enseignement
|
||||
- Spécialisé
|
||||
`handleRepertoire()` reads multi-select filter arrays from `$_GET` and renders
|
||||
`app/templates/public/repertoire.php`, which uses the shared results partial
|
||||
and `app/templates/partials/repertoire-index.php`.
|
||||
|
||||
6. **Format** - Filter by work format:
|
||||
- Site web, Audio, Vidéo, Performance
|
||||
- Objet éditorial, Installation, Autre
|
||||
Multi-select filters (`collectFilterParams()`, each an array, `_GET` keys):
|
||||
- `fy[]` — years (validated to 1900–2100)
|
||||
- `ap[]` — AP program names
|
||||
- `or[]` — orientations
|
||||
- `fi[]` — finalities
|
||||
- `kw[]` — keywords/tags
|
||||
|
||||
7. **Language** - Filter by language (Français, Anglais)
|
||||
Each value is trimmed, length-capped (≤ 100), de-duplicated, and passed through
|
||||
as sanitised strings — no direct user input reaches SQL.
|
||||
|
||||
8. **Keyword** - Filter by specific keyword
|
||||
There is also an HTMX **student preview** popover at
|
||||
`/repertoire/student-preview` (`handleStudentPreview()` → `student-preview.php`).
|
||||
|
||||
9. **Type** - Filter by thesis type:
|
||||
- TFE (final thesis projects)
|
||||
- Doctoral theses
|
||||
---
|
||||
|
||||
## Testing the Search Feature
|
||||
## Rate limiting
|
||||
|
||||
### 1. Create Test Database
|
||||
Run the script to generate sample data:
|
||||
```bash
|
||||
cd /home/padlock/dev/posterg-website/front-backend
|
||||
php create_test_db.php
|
||||
```
|
||||
Search is rate-limited via `app/src/RateLimit.php`. See the nginx config
|
||||
(`nginx/xamxam.conf`) for the matching server-side limits.
|
||||
|
||||
This will create `test.db` in the `formulaire/` directory with:
|
||||
- 6 sample theses (various years, orientations, and programs)
|
||||
- 5 sample authors
|
||||
- 3 sample supervisors
|
||||
- 20 keywords
|
||||
- Complete relationships (authors, supervisors, keywords, formats, languages)
|
||||
---
|
||||
|
||||
### 2. Access the Search Page
|
||||
Navigate to: `search.php`
|
||||
## Database access
|
||||
|
||||
### 3. Test Search Scenarios
|
||||
- **Full-text + single filters:** `Database::searchTheses(array $params, $limit, $offset)`
|
||||
and `Database::countSearchResults(array $params)`.
|
||||
- **Keyword/tag autocomplete:** `Database::searchTags(string $query)`.
|
||||
- **Supervisor autocomplete:** `Database::searchSupervisors($query, $role)`.
|
||||
- **Language autocomplete:** `Database::searchLanguages(string $query)`.
|
||||
|
||||
#### Scenario 1: Full-text Search
|
||||
- Enter "urbain" in the search field
|
||||
- Should find: "Espaces Urbains et Narration Collective"
|
||||
Queries operate on `v_theses_public`; keyword matching joins the `thesis_tags` /
|
||||
`tags` tables (keywords are stored as lowercase-normalised **tags**, not a
|
||||
`keywords`/`thesis_keywords` set — see [database.md](database.md)).
|
||||
|
||||
#### Scenario 2: Filter by Year
|
||||
- Select year: 2024
|
||||
- Should find: 3 theses from 2024
|
||||
All queries use PDO prepared statements and escape `%`/`_` for `LIKE`
|
||||
(`Database::escapeLikeString`) to prevent wildcard injection.
|
||||
|
||||
#### Scenario 3: Filter by Orientation
|
||||
- Select orientation: "Installation-Performance"
|
||||
- Should find: 2 theses
|
||||
---
|
||||
|
||||
#### Scenario 4: Filter by AP Program
|
||||
- Select AP: "Narration Spéculative"
|
||||
- Should find: 2 theses
|
||||
## Performance notes
|
||||
|
||||
#### Scenario 5: Combined Filters
|
||||
- Enter "performance" in search field
|
||||
- Select year: 2024
|
||||
- Should find: 1 thesis ("Corps et Technologies")
|
||||
- Critical text/filter columns and the junction tables are indexed
|
||||
(`idx_theses_pub_year`, `idx_theses_*`, `idx_thesis_tags_*`, …).
|
||||
- `v_theses_public` pre-computes the joins for the common read path.
|
||||
- The repertoire filters operate on indexed lookup columns.
|
||||
|
||||
#### Scenario 6: Keyword Search
|
||||
- Select keyword: "écologie"
|
||||
- Should find: "Écologies Affectives"
|
||||
---
|
||||
|
||||
## Database Schema Reference
|
||||
## Future enhancements (not yet implemented)
|
||||
|
||||
The search uses the `v_theses_public` view which combines:
|
||||
- Main thesis data from `theses` table
|
||||
- Related authors via `thesis_authors` junction table
|
||||
- Related supervisors via `thesis_supervisors` junction table
|
||||
- Related keywords via `thesis_keywords` junction table
|
||||
- Related formats via `thesis_formats` junction table
|
||||
- Related languages via `thesis_languages` junction table
|
||||
- Predefined values from lookup tables (orientations, ap_programs, finality_types, etc.)
|
||||
The historical `search.md` listed potential automplete/faceted-search/export
|
||||
ideas. Status:
|
||||
|
||||
## Features
|
||||
|
||||
### Pagination
|
||||
- Results are paginated (20 items per page)
|
||||
- Previous/Next navigation
|
||||
- Numbered page links
|
||||
|
||||
### Result Display
|
||||
- Shows total number of results
|
||||
- Card-based layout matching the main index page
|
||||
- Displays: title, author, year, synopsis excerpt
|
||||
- Links to full thesis detail page
|
||||
|
||||
### User Experience
|
||||
- All filters are optional
|
||||
- Filters can be combined
|
||||
- "Réinitialiser" button to clear all filters
|
||||
- Maintains filter state during pagination
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- All user inputs are sanitized using `htmlspecialchars()`
|
||||
- SQL queries use prepared statements with parameter binding
|
||||
- No direct SQL injection risk
|
||||
- Only published theses are searchable (`is_published = 1`)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
1. **Auto-complete** - Suggest keywords/authors as user types
|
||||
2. **Faceted search** - Show filter counts (e.g., "Peinture (12)")
|
||||
3. **Sort options** - Sort by year, title, relevance
|
||||
4. **Save searches** - Allow users to bookmark search queries
|
||||
5. **Export results** - Export search results as CSV/JSON
|
||||
6. **Advanced boolean search** - Support AND/OR/NOT operators
|
||||
7. **Search highlights** - Highlight matching terms in results
|
||||
8. **Related theses** - Show similar works based on keywords
|
||||
9. **Statistics** - Show search analytics and popular queries
|
||||
10. **AJAX search** - Live search without page reload
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- Uses SQLite LIKE operator for text matching (case-insensitive)
|
||||
- Searches across GROUP_CONCAT fields in the view for many-to-many relationships
|
||||
- Efficient use of indexes defined in schema.sql
|
||||
- Compatible with existing Database.php singleton pattern
|
||||
- Auto-complete for tags exists at the form level (`searchTags`)
|
||||
- Faceted counts, saved searches, result export, and advanced boolean operators
|
||||
are **not** implemented
|
||||
|
||||
Reference in New Issue
Block a user