Commit initial
This commit is contained in:
@@ -0,0 +1,313 @@
|
||||
---
|
||||
phase: 03-printer-configuration
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- tests/test_printer_crud.py
|
||||
- imptune/api/printers.py
|
||||
- imptune/api/clients.py
|
||||
- imptune/api/pages.py
|
||||
- imptune/main.py
|
||||
- imptune/templates/printers.html
|
||||
- imptune/templates/clients.html
|
||||
- imptune/templates/partials/printer_list.html
|
||||
- imptune/templates/partials/printer_form.html
|
||||
autonomous: false
|
||||
requirements:
|
||||
- PRNT-01
|
||||
- PRNT-02
|
||||
- PRNT-03
|
||||
- PRNT-04
|
||||
- PRNT-05
|
||||
- PRNT-06
|
||||
- PRNT-07
|
||||
- PRNT-08
|
||||
- PRNT-09
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can fill in a printer form with name, IP, port, duplex, color, paper size, collate and save it"
|
||||
- "Port name auto-populates from IP address (user can still edit it)"
|
||||
- "User can assign a printer to a client/tenant label"
|
||||
- "Saved printer appears in a grouped list after page refresh"
|
||||
- "User can create a new client from the clients page"
|
||||
artifacts:
|
||||
- path: "imptune/api/printers.py"
|
||||
provides: "POST /printers endpoint with Form parsing and validation"
|
||||
exports: ["router"]
|
||||
- path: "imptune/api/clients.py"
|
||||
provides: "POST /clients and GET /clients endpoints"
|
||||
exports: ["router"]
|
||||
- path: "imptune/templates/printers.html"
|
||||
provides: "Printer list page grouped by client"
|
||||
- path: "imptune/templates/partials/printer_form.html"
|
||||
provides: "Printer create form with all fields, Alpine.js port derivation"
|
||||
- path: "imptune/templates/partials/printer_list.html"
|
||||
provides: "Grouped printer list fragment for HTMX swap"
|
||||
- path: "tests/test_printer_crud.py"
|
||||
provides: "Integration tests for PRNT-01 through PRNT-09"
|
||||
key_links:
|
||||
- from: "imptune/templates/partials/printer_form.html"
|
||||
to: "/printers"
|
||||
via: "hx-post form submission"
|
||||
pattern: "hx-post.*printers"
|
||||
- from: "imptune/api/printers.py"
|
||||
to: "imptune/db/models.py"
|
||||
via: "Printer.create() and Client.select()"
|
||||
pattern: "Printer\\.create|Client\\.select"
|
||||
- from: "imptune/main.py"
|
||||
to: "imptune/api/printers.py"
|
||||
via: "app.include_router(printers.router)"
|
||||
pattern: "include_router.*printers"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Implement printer and client CRUD with full form, grouped list display, and persistence.
|
||||
|
||||
Purpose: This is the core of Phase 3 — technicians need to configure printer parameters, assign to clients, and see saved configs persist across sessions. All form fields (PRNT-01 through PRNT-07), client assignment (PRNT-08), and persistence (PRNT-09) are covered.
|
||||
|
||||
Output: Working /printers and /clients pages with HTMX-powered form submission, Alpine.js port auto-derivation, and grouped printer list.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/03-printer-configuration/03-RESEARCH.md
|
||||
|
||||
<interfaces>
|
||||
<!-- Key types and contracts from existing codebase. Use directly. -->
|
||||
|
||||
From imptune/db/models.py:
|
||||
```python
|
||||
class Client(BaseModel):
|
||||
name = CharField(unique=True)
|
||||
created_at = DateTimeField(default=datetime.utcnow)
|
||||
|
||||
class Driver(BaseModel):
|
||||
sha256 = CharField(unique=True, index=True)
|
||||
original_filename = CharField()
|
||||
size_bytes = IntegerField()
|
||||
uploaded_at = DateTimeField(default=datetime.utcnow)
|
||||
driver_desc = CharField(null=True) # JSON list of driver names
|
||||
inf_filename = CharField(null=True)
|
||||
architecture = CharField(null=True)
|
||||
has_cat_file = BooleanField(default=False)
|
||||
|
||||
class Printer(BaseModel):
|
||||
name = CharField()
|
||||
ip_address = CharField()
|
||||
port_name = CharField()
|
||||
client = ForeignKeyField(Client, null=True, backref="printers")
|
||||
driver = ForeignKeyField(Driver, null=True, backref="printers")
|
||||
duplex_mode = CharField(default="OneSided")
|
||||
color_mode = BooleanField(default=True)
|
||||
paper_size = CharField(default="A4")
|
||||
collate = BooleanField(default=True)
|
||||
created_at = DateTimeField(default=datetime.utcnow)
|
||||
updated_at = DateTimeField(default=datetime.utcnow)
|
||||
```
|
||||
|
||||
From imptune/api/drivers.py (established error pattern):
|
||||
```python
|
||||
def _error_response(message: str, status_code: int = 400) -> HTMLResponse:
|
||||
return HTMLResponse(
|
||||
content=f"<div id='driver-list' class='error'><p>{message}</p></div>",
|
||||
status_code=status_code,
|
||||
)
|
||||
```
|
||||
|
||||
From tests/conftest.py (test fixtures):
|
||||
```python
|
||||
@pytest.fixture
|
||||
def client(tmp_data_dir):
|
||||
from imptune.main import app
|
||||
with TestClient(app) as c:
|
||||
yield c
|
||||
|
||||
@pytest.fixture
|
||||
def tmp_data_dir(tmp_path, monkeypatch):
|
||||
data_dir = tmp_path / "data"
|
||||
data_dir.mkdir()
|
||||
monkeypatch.setenv("DATA_DIR", str(data_dir))
|
||||
import imptune.config as cfg
|
||||
cfg.DATA_DIR = str(data_dir)
|
||||
cfg.DB_PATH = str(data_dir / "imptune.db")
|
||||
cfg.DRIVERS_DIR = str(data_dir / "drivers")
|
||||
return data_dir
|
||||
```
|
||||
|
||||
From imptune/main.py (router registration pattern):
|
||||
```python
|
||||
app.include_router(health.router)
|
||||
app.include_router(pages.router)
|
||||
app.include_router(drivers.router)
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Write failing integration tests for printer and client CRUD</name>
|
||||
<files>tests/test_printer_crud.py</files>
|
||||
<behavior>
|
||||
- test_create_printer_persisted: POST /printers with name="Test Printer", ip_address="192.168.1.100", port_name="IP_192_168_1_100" returns 200; GET /printers contains "Test Printer" (covers PRNT-01, PRNT-02, PRNT-09)
|
||||
- test_create_printer_duplex: POST /printers with duplex_mode="LongEdge"; verify Printer record has duplex_mode="LongEdge" (covers PRNT-04)
|
||||
- test_create_printer_color_mode: POST /printers with color_mode=false; verify Printer record has color_mode=False (covers PRNT-05)
|
||||
- test_create_printer_paper_size: POST /printers with paper_size="Letter"; verify Printer record has paper_size="Letter" (covers PRNT-06)
|
||||
- test_create_printer_collate: POST /printers with collate=false; verify Printer record has collate=False (covers PRNT-07)
|
||||
- test_create_client: POST /clients with name="Contoso" returns 200; GET /clients contains "Contoso"
|
||||
- test_printer_grouped_by_client: Create client "Contoso", POST /printers with client_id=contoso.id; GET /printers HTML contains "Contoso" as group header (covers PRNT-08)
|
||||
- test_create_printer_missing_name: POST /printers with empty name returns 400 (validation)
|
||||
- test_create_printer_invalid_ip: POST /printers with ip_address="" returns 400 (validation)
|
||||
- test_delete_printer: POST /printers to create, then DELETE /printers/{id} returns 200; printer no longer in GET /printers
|
||||
</behavior>
|
||||
<action>
|
||||
Create `tests/test_printer_crud.py` with all tests listed above. Use the existing `client` fixture from conftest.py (which provides TestClient with lifespan-triggered init_db). Follow the same pattern as `test_driver_upload.py`:
|
||||
- Import `pytest` and use `client` fixture
|
||||
- POST form data via `client.post("/printers", data={...})` (not JSON, form-encoded)
|
||||
- POST client creation via `client.post("/clients", data={"name": "Contoso"})`
|
||||
- For verifying DB state, import `Printer` and `Client` from `imptune.db.models` inside each test
|
||||
- For grouped list test, check that GET /printers response HTML contains the client name in an `<h3>` or `<section>` header
|
||||
- For boolean fields (color_mode, collate): HTML checkboxes send "on" when checked, nothing when unchecked. Use `data={"color_mode": ""}` for false and `data={"color_mode": "on"}` for true. Design tests accordingly.
|
||||
- All tests should FAIL initially (routes don't exist yet). Run them to confirm RED state.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd C:/Users/SebastienQUEROL/Documents/projets/ImpTune && python -m pytest tests/test_printer_crud.py -x -q 2>&1 | head -30</automated>
|
||||
</verify>
|
||||
<done>All tests exist and fail with connection/404 errors (RED state). No test passes yet.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Implement printer and client CRUD routes, templates, and wire routers</name>
|
||||
<files>imptune/api/printers.py, imptune/api/clients.py, imptune/api/pages.py, imptune/main.py, imptune/templates/printers.html, imptune/templates/clients.html, imptune/templates/partials/printer_form.html, imptune/templates/partials/printer_list.html</files>
|
||||
<action>
|
||||
**1. Create `imptune/api/clients.py`:**
|
||||
- `router = APIRouter(prefix="/clients")`
|
||||
- `POST /clients`: Accept `name: str = Form(...)`. Validate non-empty. Create `Client.create(name=name)`. Handle IntegrityError (duplicate name) with 400 error. Return redirect or HTMX partial.
|
||||
- Follow established pattern: sync `def` handlers, Jinja2Templates from same path as drivers.py.
|
||||
|
||||
**2. Create `imptune/api/printers.py`:**
|
||||
- `router = APIRouter(prefix="/printers")`
|
||||
- `POST /printers`: Accept all form fields via `Form(...)`:
|
||||
- `name: str = Form(...)` (required)
|
||||
- `ip_address: str = Form(...)` (required)
|
||||
- `port_name: str = Form(...)` (required)
|
||||
- `duplex_mode: str = Form("OneSided")` — validate value in ("OneSided", "LongEdge", "ShortEdge")
|
||||
- `color_mode: str = Form("")` — checkbox: "on" = True, "" = False. Convert: `bool(color_mode)`
|
||||
- `paper_size: str = Form("A4")` — validate value in ("A4", "Letter", "Legal")
|
||||
- `collate: str = Form("")` — same checkbox pattern as color_mode
|
||||
- `client_id: str = Form("")` — empty string = None, otherwise int FK
|
||||
- `driver_id: str = Form("")` — empty string = None, otherwise int FK
|
||||
- Validate: name not empty, ip_address not empty. On failure return `_error_response(msg)` with `<div id="printer-list">` wrapper (same HTMX pattern as drivers.py).
|
||||
- On success: `Printer.create(...)` with all fields. Return the updated printer list partial via `_render_printer_list(request)`.
|
||||
- `DELETE /printers/{printer_id}`: Delete printer by ID. Return updated printer list partial.
|
||||
- Helper `_render_printer_list(request)`: Query `Printer.select(Printer, Client).join(Client, JOIN.LEFT_OUTER).order_by(Client.name, Printer.name)`, group into `defaultdict(list)` by client name ("Unassigned" for null client_id), pass `grouped` to `partials/printer_list.html`.
|
||||
- Helper `_error_response(message, status_code=400)`: Return `HTMLResponse(content=f"<div id='printer-list' class='error'><p>{message}</p></div>", status_code=status_code)`.
|
||||
|
||||
**3. Update `imptune/api/pages.py`:**
|
||||
Add two new page routes (import Client, Printer, Driver, json, JOIN from peewee):
|
||||
- `GET /printers`: Render `printers.html` with `grouped` printers (same query as `_render_printer_list`), plus `clients` list and `driver_data` list for form dropdowns.
|
||||
- `GET /clients`: Render `clients.html` with `clients = list(Client.select().order_by(Client.name))`.
|
||||
|
||||
**4. Create `imptune/templates/printers.html`:**
|
||||
- Extends `base.html`. Contains:
|
||||
- `<h1>Printers</h1>`
|
||||
- Section with `<h2>Add Printer</h2>` containing `{% include "partials/printer_form.html" %}`
|
||||
- Section with `<h2>Printer Library</h2>` containing `{% include "partials/printer_list.html" %}`
|
||||
|
||||
**5. Create `imptune/templates/partials/printer_form.html`:**
|
||||
- Wrap in `<div x-data="{ ip: '{{ printer.ip_address if printer else '' }}', port: '{{ printer.port_name if printer else '' }}', portEdited: {{ 'true' if printer else 'false' }} }">` for Alpine.js reactivity.
|
||||
- Form with `hx-post="/printers"`, `hx-target="#printer-list"`, `hx-swap="outerHTML"`.
|
||||
- Fields:
|
||||
- Printer Name: `<input type="text" name="name" required>`
|
||||
- IP Address: `<input type="text" name="ip_address" x-model="ip" @input="if (!portEdited) port = 'IP_' + ip.replaceAll('.', '_')" required>`
|
||||
- Port Name: `<input type="text" name="port_name" x-model="port" @change="portEdited = true" @keydown="portEdited = true">` (PRNT-03)
|
||||
- Driver: `<select name="driver_id"><option value="">-- No driver --</option>{% for item in driver_data %}<option value="{{ item.driver.id }}">{{ item.driver.original_filename }} ({{ item.names | join(', ') }})</option>{% endfor %}</select>`
|
||||
- Duplex Mode: `<select name="duplex_mode"><option value="OneSided">One-Sided</option><option value="LongEdge">Long Edge</option><option value="ShortEdge">Short Edge</option></select>`
|
||||
- Color Mode: `<input type="checkbox" name="color_mode" value="on" checked>` (default checked = True)
|
||||
- Paper Size: `<select name="paper_size"><option value="A4">A4</option><option value="Letter">Letter</option><option value="Legal">Legal</option></select>`
|
||||
- Collate: `<input type="checkbox" name="collate" value="on" checked>` (default checked = True)
|
||||
- Client: `<select name="client_id"><option value="">-- Unassigned --</option>{% for c in clients %}<option value="{{ c.id }}">{{ c.name }}</option>{% endfor %}</select>`
|
||||
- Submit button: `<button type="submit">Save Printer</button>`
|
||||
|
||||
**6. Create `imptune/templates/partials/printer_list.html`:**
|
||||
- `<div id="printer-list">`
|
||||
- If grouped is empty: `<p>No printers configured yet.</p>`
|
||||
- Else: for each `(client_name, printers)` in grouped.items(): `<h3>{{ client_name }}</h3>` then a `<table>` with columns: Name, IP, Driver, Duplex, Paper, Actions. Each row has a Delete button with `hx-delete="/printers/{{ p.id }}" hx-target="#printer-list" hx-swap="outerHTML" hx-confirm="Delete '{{ p.name }}'?"`.
|
||||
|
||||
**7. Create `imptune/templates/clients.html`:**
|
||||
- Extends `base.html`. `<h1>Clients</h1>`.
|
||||
- Form: `<form hx-post="/clients" hx-target="#client-list" hx-swap="outerHTML">` with name input and submit button.
|
||||
- `<div id="client-list">`: Table of clients (Name, Created, Printer Count). Printer count via `Client.printers` backref — pass pre-computed count from route.
|
||||
|
||||
**8. Update `imptune/main.py`:**
|
||||
- Add imports: `from imptune.api import clients, printers`
|
||||
- Add: `app.include_router(printers.router)` and `app.include_router(clients.router)`
|
||||
|
||||
After all files are created, run the full test suite to confirm GREEN state.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd C:/Users/SebastienQUEROL/Documents/projets/ImpTune && python -m pytest tests/test_printer_crud.py -x -q && python -m pytest tests/ -v</automated>
|
||||
</verify>
|
||||
<done>All test_printer_crud.py tests pass (GREEN). Full test suite passes. GET /printers shows form with all fields. POST /printers creates and persists printer. Printers grouped by client name in list. GET /clients shows client list with creation form.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 3: Verify printer form and Alpine.js port auto-derivation in browser</name>
|
||||
<files>imptune/templates/partials/printer_form.html</files>
|
||||
<action>
|
||||
Human verifies the complete printer configuration flow in a browser, especially the Alpine.js port auto-derivation (PRNT-03) which cannot be tested via pytest.
|
||||
|
||||
What was built: Complete printer configuration form with Alpine.js port auto-derivation (PRNT-03), all form fields (PRNT-01 through PRNT-07), client assignment (PRNT-08), and persistence (PRNT-09). Also a /clients page for client management.
|
||||
|
||||
Steps to verify:
|
||||
1. Start app: `docker compose up` (or `uvicorn imptune.main:app --reload`)
|
||||
2. Navigate to /clients — create a client "Contoso"
|
||||
3. Navigate to /printers — verify empty state message
|
||||
4. Fill in printer form:
|
||||
- Name: "HP LaserJet 4050"
|
||||
- IP: "192.168.1.100" — verify port name auto-fills to "IP_192_168_1_100"
|
||||
- Manually edit port name to "CUSTOM_PORT" — change IP to "10.0.0.1" — verify port stays "CUSTOM_PORT" (not overwritten)
|
||||
- Select duplex "Long Edge", uncheck Color, paper "Letter", check Collate
|
||||
- Select client "Contoso"
|
||||
- Click Save
|
||||
5. Verify printer appears under "Contoso" group heading
|
||||
6. Refresh page — verify printer still appears (persistence)
|
||||
7. Click Delete on the printer — confirm deletion dialog — verify it disappears
|
||||
</action>
|
||||
<verify>Human confirms all 7 steps pass in browser</verify>
|
||||
<done>Alpine.js port auto-derivation works correctly: auto-fills from IP, preserves manual edits. Full CRUD flow verified visually.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- `pytest tests/test_printer_crud.py -x -q` — all printer CRUD tests pass
|
||||
- `pytest tests/ -v` — full suite green (no regressions)
|
||||
- GET /printers renders form with all required fields
|
||||
- POST /printers persists to SQLite and returns updated list
|
||||
- Printers are grouped by client name in the list display
|
||||
- Alpine.js port derivation works in browser (manual checkpoint)
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All PRNT-01 through PRNT-09 requirements verified by tests or manual check
|
||||
- Printer form has: name, IP, port (auto-derived), duplex select, color checkbox, paper select, collate checkbox, client select, driver select
|
||||
- Printer list groups by client with "Unassigned" fallback
|
||||
- Client CRUD works on /clients page
|
||||
- No N+1 queries (LEFT_OUTER JOIN used)
|
||||
- Full test suite green
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/03-printer-configuration/03-01-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user