1196de6e88
Flask backend with Vue 3 frontend for shop floor machine management. Includes database schema export for MySQL shopdb_flask database. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
107 lines
2.9 KiB
Markdown
107 lines
2.9 KiB
Markdown
# Contributing to ShopDB Flask
|
|
|
|
## Coding Standards
|
|
|
|
### Database Naming Convention
|
|
|
|
**IMPORTANT: No underscores in database identifiers**
|
|
|
|
All database table names and column names must use lowercase concatenated words (no underscores).
|
|
|
|
| Pattern | Good | Bad |
|
|
|---------|------|-----|
|
|
| Table names | `printerdata` | `printer_data` |
|
|
| Column names | `passwordhash` | `password_hash` |
|
|
| Foreign keys | `machinetypeid` | `machine_type_id` |
|
|
| Index names | `idx_printer_zabbix` | Allowed for indexes |
|
|
|
|
### Intuitive Naming for Non-Technical Users
|
|
|
|
Database tables and columns should use **simple, intuitive names** that non-technical users can understand when viewing data or reports.
|
|
|
|
| Avoid | Prefer | Why |
|
|
|-------|--------|-----|
|
|
| `printerextensions` | `printerdata` | "data" is clearer than "extensions" |
|
|
| `machinerelationships` | `machinelinks` | "links" is simpler (consider) |
|
|
| `comtypeid` | `connectiontypeid` | Spell it out when unclear |
|
|
|
|
**Guiding principle:** If someone unfamiliar with the system looked at a table name, would they understand what's in it?
|
|
|
|
Examples:
|
|
|
|
```python
|
|
# Good
|
|
class PrinterExtension(db.Model):
|
|
__tablename__ = 'printerextensions'
|
|
|
|
machineid = db.Column(db.Integer, db.ForeignKey('machines.machineid'))
|
|
lastzabbixsync = db.Column(db.DateTime)
|
|
isnetworkprinter = db.Column(db.Boolean)
|
|
|
|
# Bad
|
|
class PrinterExtension(db.Model):
|
|
__tablename__ = 'printer_extensions'
|
|
|
|
machine_id = db.Column(db.Integer, db.ForeignKey('machines.machine_id'))
|
|
last_zabbix_sync = db.Column(db.DateTime)
|
|
is_network_printer = db.Column(db.Boolean)
|
|
```
|
|
|
|
### API Response Keys
|
|
|
|
API JSON responses should also use lowercase concatenated keys to match database columns:
|
|
|
|
```json
|
|
{
|
|
"machineid": 1,
|
|
"machinenumber": "M001",
|
|
"lastzabbixsync": "2026-01-12T10:00:00Z",
|
|
"isnetworkprinter": true
|
|
}
|
|
```
|
|
|
|
### Python Code
|
|
|
|
Python variable and function names follow standard Python conventions (snake_case for variables/functions, PascalCase for classes):
|
|
|
|
```python
|
|
# Variables and functions use snake_case
|
|
machine_type = get_machine_type()
|
|
is_valid = validate_input(data)
|
|
|
|
# Classes use PascalCase
|
|
class PrinterExtension:
|
|
pass
|
|
```
|
|
|
|
### File Structure
|
|
|
|
- Models: `shopdb/core/models/` or `plugins/<plugin>/models/`
|
|
- API routes: `shopdb/core/api/` or `plugins/<plugin>/api/`
|
|
- Services: `shopdb/core/services/` or `plugins/<plugin>/services/`
|
|
|
|
### Plugin Development
|
|
|
|
When creating a new plugin:
|
|
|
|
1. Create directory structure in `plugins/<name>/`
|
|
2. Include `manifest.json` with metadata
|
|
3. Extend `BasePlugin` class
|
|
4. Follow naming conventions above
|
|
5. Run `flask plugin install <name>` to install
|
|
|
|
## Testing
|
|
|
|
Run tests with:
|
|
|
|
```bash
|
|
pytest tests/
|
|
```
|
|
|
|
## Code Review Checklist
|
|
|
|
- [ ] No underscores in table/column names
|
|
- [ ] API responses use consistent key naming
|
|
- [ ] Plugin follows BasePlugin interface
|
|
- [ ] Tests included for new functionality
|