294 lines
4.8 KiB
Markdown
294 lines
4.8 KiB
Markdown
# Copilot Instructions – Artworks Module (SkinBase)
|
||
|
||
> **This file defines HOW Copilot must generate code.**
|
||
> It is a strict instruction set.
|
||
> If there is a conflict between generated code and these rules,
|
||
> **these rules override everything.**
|
||
|
||
---
|
||
|
||
## 1. Global Rules (MANDATORY)
|
||
|
||
Copilot MUST:
|
||
|
||
* Target **Laravel 12**
|
||
* Use **PHP 8.3+ syntax**
|
||
* Follow **Eloquent best practices**
|
||
* Respect **SoftDeletes**
|
||
* Respect **FK relationships**
|
||
* Generate **clean, readable, maintainable code**
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Reference legacy tables (`wallz`, old categories, old views)
|
||
* Generate MyISAM tables
|
||
* Generate hard deletes for user content
|
||
* Put counters on hot tables
|
||
* Use IDs in URLs
|
||
* Mix responsibilities across models
|
||
|
||
---
|
||
|
||
## 2. Authoritative Schema Reference
|
||
|
||
The canonical schema for artworks is defined in:
|
||
|
||
```
|
||
.copilot/artworks.md
|
||
```
|
||
|
||
Copilot MUST:
|
||
|
||
* Read this file before generating any code
|
||
* Match table names, columns, relations exactly
|
||
* Never invent fields or tables unless explicitly allowed
|
||
|
||
---
|
||
|
||
## 3. Models Generation Rules
|
||
|
||
When generating Eloquent models:
|
||
|
||
### Required models
|
||
|
||
Copilot MUST generate:
|
||
|
||
* `App\Models\Artwork`
|
||
* `App\Models\ArtworkTranslation`
|
||
* `App\Models\ArtworkStats`
|
||
* `App\Models\ArtworkComment`
|
||
* `App\Models\ArtworkDownload`
|
||
|
||
### Model requirements
|
||
|
||
Each model MUST:
|
||
|
||
* Declare `$fillable`
|
||
* Define all relationships
|
||
* Use `SoftDeletes` **only when allowed**
|
||
* Include PHPDoc blocks for relations
|
||
* Use type-hinted return values
|
||
|
||
### Forbidden
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Add business logic into models
|
||
* Perform stat mutations in models
|
||
* Use observers unless explicitly requested
|
||
|
||
---
|
||
|
||
## 4. Relationships (STRICT)
|
||
|
||
Copilot MUST implement these exact relations:
|
||
|
||
### Artwork
|
||
|
||
```php
|
||
belongsTo(User::class)
|
||
hasMany(ArtworkTranslation::class)
|
||
hasOne(ArtworkStats::class)
|
||
belongsToMany(Category::class)
|
||
hasMany(ArtworkComment::class)
|
||
hasMany(ArtworkDownload::class)
|
||
```
|
||
|
||
### ArtworkTranslation
|
||
|
||
```php
|
||
belongsTo(Artwork::class)
|
||
```
|
||
|
||
### ArtworkStats
|
||
|
||
```php
|
||
belongsTo(Artwork::class)
|
||
```
|
||
|
||
### ArtworkComment
|
||
|
||
```php
|
||
belongsTo(Artwork::class)
|
||
belongsTo(User::class)
|
||
```
|
||
|
||
### ArtworkDownload
|
||
|
||
```php
|
||
belongsTo(Artwork::class)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Query & Scope Rules
|
||
|
||
Copilot MUST define these scopes on `Artwork`:
|
||
|
||
```php
|
||
scopePublic($query)
|
||
scopeApproved($query)
|
||
scopePublished($query)
|
||
```
|
||
|
||
Public queries MUST always include:
|
||
|
||
```php
|
||
deleted_at IS NULL
|
||
is_public = true
|
||
is_approved = true
|
||
```
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Eager-load stats in list views
|
||
* Use `offset` pagination for feeds
|
||
* Load unnecessary relations by default
|
||
|
||
---
|
||
|
||
## 6. Controller Generation Rules
|
||
|
||
When generating controllers:
|
||
|
||
Copilot MUST:
|
||
|
||
* Use **thin controllers**
|
||
* Delegate logic to services/actions if needed
|
||
* Validate input using Form Requests
|
||
* Use route-model binding with `slug`
|
||
* Handle soft-deleted content properly
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Query raw DB tables directly
|
||
* Bypass scopes
|
||
* Return unfiltered content
|
||
|
||
---
|
||
|
||
## 7. Routing Rules
|
||
|
||
Routes MUST:
|
||
|
||
* Use **slug-based routing**
|
||
* Never expose numeric IDs
|
||
* Respect category hierarchy
|
||
* Be SEO-friendly
|
||
|
||
Example (valid):
|
||
|
||
```
|
||
/photography/abstract/dark/night-city
|
||
```
|
||
|
||
Invalid:
|
||
|
||
```
|
||
/artwork/123
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Soft Delete Rules
|
||
|
||
Copilot MUST:
|
||
|
||
* Use `delete()` (soft delete) for user content
|
||
* Use `restore()` for recovery
|
||
* Use `forceDelete()` **only** when explicitly requested
|
||
|
||
When content is soft-deleted:
|
||
|
||
* It must disappear from public browsing
|
||
* It must remain accessible to admins
|
||
|
||
---
|
||
|
||
## 9. Stats & High-Load Rules
|
||
|
||
Copilot MUST:
|
||
|
||
* Treat stats as **derived data**
|
||
* Update stats via jobs / services
|
||
* Never increment counters inline in controllers
|
||
* Assume Redis may be present
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Store counters on `artworks`
|
||
* Use `increment()` directly on hot rows
|
||
|
||
---
|
||
|
||
## 10. Search Rules
|
||
|
||
Copilot MAY:
|
||
|
||
* Use MySQL FULLTEXT
|
||
* Use external search engines (if requested)
|
||
|
||
Copilot MUST NOT:
|
||
|
||
* Search file paths
|
||
* Search binary metadata
|
||
* Assume Elasticsearch exists unless specified
|
||
|
||
---
|
||
|
||
## 11. Forbidden Patterns (NEVER GENERATE)
|
||
|
||
❌ Hard deletes on artworks
|
||
❌ Legacy column names
|
||
❌ Polymorphic abuse
|
||
❌ Fat controllers
|
||
❌ Magic numbers
|
||
❌ Inline SQL in controllers
|
||
❌ Business logic in migrations
|
||
|
||
---
|
||
|
||
## 12. Extension Rules
|
||
|
||
Copilot MAY generate new features ONLY if:
|
||
|
||
* They do not modify core tables
|
||
* They follow the same architectural principles
|
||
* They are isolated in new tables/services
|
||
|
||
Allowed examples:
|
||
|
||
* tags
|
||
* EXIF metadata
|
||
* versioning
|
||
* reporting/flagging
|
||
* API resources
|
||
|
||
---
|
||
|
||
## 13. Error Handling
|
||
|
||
Copilot MUST:
|
||
|
||
* Throw meaningful exceptions
|
||
* Return proper HTTP codes
|
||
* Use 404 for missing public content
|
||
* Use 410 or 301 for deleted content (if requested)
|
||
|
||
---
|
||
|
||
## 14. Final Instruction (ABSOLUTE)
|
||
|
||
> **Copilot must treat this file and `artworks.md`
|
||
> as non-negotiable contracts.**
|
||
|
||
If unsure:
|
||
|
||
* ask for clarification
|
||
* do NOT guess
|
||
* do NOT invent schema
|
||
|
||
---
|
||
|
||
### ✅ End of Copilot Instructions
|