Phase 6 Complete by Claude Code

backend/equipment/models.py

@@ -1 +1,42 @@
-# TODO: Equipment Pydantic schemas
+from pydantic import BaseModel
+from typing import List, Optional
+
+
+# --- Request / Response schemas ---
+
+class NoteCreate(BaseModel):
+    """Create a new equipment note/log entry."""
+    title: str
+    content: str
+    category: str = "general"  # general, maintenance, installation, issue, other
+    device_id: Optional[str] = None  # Firestore doc ID of linked device
+    user_id: Optional[str] = None  # Firestore doc ID of linked user
+
+
+class NoteUpdate(BaseModel):
+    """Update an existing note. Only provided fields are updated."""
+    title: Optional[str] = None
+    content: Optional[str] = None
+    category: Optional[str] = None
+    device_id: Optional[str] = None
+    user_id: Optional[str] = None
+
+
+class NoteInDB(BaseModel):
+    """Note as stored in Firestore."""
+    id: str
+    title: str = ""
+    content: str = ""
+    category: str = "general"
+    device_id: str = ""
+    user_id: str = ""
+    device_name: str = ""
+    user_name: str = ""
+    created_by: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+
+
+class NoteListResponse(BaseModel):
+    notes: List[NoteInDB]
+    total: int

backend/equipment/router.py

@@ -1 +1,58 @@
-# TODO: Complementary devices / notes endpoints
+from fastapi import APIRouter, Depends, Query
+from typing import Optional
+from auth.models import TokenPayload
+from auth.dependencies import require_device_access, require_viewer
+from equipment.models import (
+    NoteCreate, NoteUpdate, NoteInDB, NoteListResponse,
+)
+from equipment import service
+
+router = APIRouter(prefix="/api/equipment/notes", tags=["equipment"])
+
+
+@router.get("", response_model=NoteListResponse)
+async def list_notes(
+    search: Optional[str] = Query(None),
+    category: Optional[str] = Query(None),
+    device_id: Optional[str] = Query(None),
+    user_id: Optional[str] = Query(None),
+    _user: TokenPayload = Depends(require_viewer),
+):
+    notes = service.list_notes(
+        search=search, category=category,
+        device_id=device_id, user_id=user_id,
+    )
+    return NoteListResponse(notes=notes, total=len(notes))
+
+
+@router.get("/{note_id}", response_model=NoteInDB)
+async def get_note(
+    note_id: str,
+    _user: TokenPayload = Depends(require_viewer),
+):
+    return service.get_note(note_id)
+
+
+@router.post("", response_model=NoteInDB, status_code=201)
+async def create_note(
+    body: NoteCreate,
+    _user: TokenPayload = Depends(require_device_access),
+):
+    return service.create_note(body, created_by=_user.name or _user.email)
+
+
+@router.put("/{note_id}", response_model=NoteInDB)
+async def update_note(
+    note_id: str,
+    body: NoteUpdate,
+    _user: TokenPayload = Depends(require_device_access),
+):
+    return service.update_note(note_id, body)
+
+
+@router.delete("/{note_id}", status_code=204)
+async def delete_note(
+    note_id: str,
+    _user: TokenPayload = Depends(require_device_access),
+):
+    service.delete_note(note_id)

backend/equipment/service.py

@@ -1 +1,168 @@
-# TODO: Equipment Firestore operations
+from datetime import datetime, timezone
+
+from shared.firebase import get_db
+from shared.exceptions import NotFoundError
+from equipment.models import NoteCreate, NoteUpdate, NoteInDB
+
+COLLECTION = "equipment_notes"
+
+VALID_CATEGORIES = {"general", "maintenance", "installation", "issue", "other"}
+
+
+def _convert_firestore_value(val):
+    """Convert Firestore-specific types to strings."""
+    if isinstance(val, datetime):
+        return val.strftime("%d %B %Y at %H:%M:%S UTC%z")
+    return val
+
+
+def _sanitize_dict(d: dict) -> dict:
+    """Recursively convert Firestore-native types in a dict to plain strings."""
+    result = {}
+    for k, v in d.items():
+        if isinstance(v, dict):
+            result[k] = _sanitize_dict(v)
+        elif isinstance(v, list):
+            result[k] = [
+                _sanitize_dict(item) if isinstance(item, dict)
+                else _convert_firestore_value(item)
+                for item in v
+            ]
+        else:
+            result[k] = _convert_firestore_value(v)
+    return result
+
+
+def _doc_to_note(doc) -> NoteInDB:
+    """Convert a Firestore document snapshot to a NoteInDB model."""
+    data = _sanitize_dict(doc.to_dict())
+    return NoteInDB(id=doc.id, **data)
+
+
+def _resolve_names(db, device_id: str | None, user_id: str | None) -> tuple[str, str]:
+    """Look up device_name and user_name from their IDs."""
+    device_name = ""
+    user_name = ""
+
+    if device_id:
+        device_doc = db.collection("devices").document(device_id).get()
+        if device_doc.exists:
+            device_name = device_doc.to_dict().get("device_name", "")
+
+    if user_id:
+        user_doc = db.collection("users").document(user_id).get()
+        if user_doc.exists:
+            user_doc_data = user_doc.to_dict()
+            user_name = user_doc_data.get("display_name", "") or user_doc_data.get("email", "")
+
+    return device_name, user_name
+
+
+def list_notes(
+    search: str | None = None,
+    category: str | None = None,
+    device_id: str | None = None,
+    user_id: str | None = None,
+) -> list[NoteInDB]:
+    """List notes with optional filters."""
+    db = get_db()
+    ref = db.collection(COLLECTION)
+    query = ref
+
+    if category and category in VALID_CATEGORIES:
+        query = query.where("category", "==", category)
+
+    if device_id:
+        query = query.where("device_id", "==", device_id)
+
+    if user_id:
+        query = query.where("user_id", "==", user_id)
+
+    query = query.order_by("created_at", direction="DESCENDING")
+
+    docs = query.stream()
+    results = []
+
+    for doc in docs:
+        note = _doc_to_note(doc)
+
+        if search:
+            search_lower = search.lower()
+            title_match = search_lower in (note.title or "").lower()
+            content_match = search_lower in (note.content or "").lower()
+            if not (title_match or content_match):
+                continue
+
+        results.append(note)
+
+    return results
+
+
+def get_note(note_id: str) -> NoteInDB:
+    """Get a single note by Firestore document ID."""
+    db = get_db()
+    doc = db.collection(COLLECTION).document(note_id).get()
+    if not doc.exists:
+        raise NotFoundError("Note")
+    return _doc_to_note(doc)
+
+
+def create_note(data: NoteCreate, created_by: str = "") -> NoteInDB:
+    """Create a new note document in Firestore."""
+    db = get_db()
+    now = datetime.now(timezone.utc).strftime("%d %B %Y at %H:%M:%S UTC")
+
+    device_name, user_name = _resolve_names(db, data.device_id, data.user_id)
+
+    doc_data = data.model_dump()
+    doc_data["device_id"] = data.device_id or ""
+    doc_data["user_id"] = data.user_id or ""
+    doc_data["device_name"] = device_name
+    doc_data["user_name"] = user_name
+    doc_data["created_by"] = created_by
+    doc_data["created_at"] = now
+    doc_data["updated_at"] = now
+
+    _, doc_ref = db.collection(COLLECTION).add(doc_data)
+
+    return NoteInDB(id=doc_ref.id, **doc_data)
+
+
+def update_note(note_id: str, data: NoteUpdate) -> NoteInDB:
+    """Update an existing note. Only provided fields are updated."""
+    db = get_db()
+    doc_ref = db.collection(COLLECTION).document(note_id)
+    doc = doc_ref.get()
+    if not doc.exists:
+        raise NotFoundError("Note")
+
+    update_data = data.model_dump(exclude_none=True)
+
+    # Re-resolve names if device_id or user_id changed
+    existing = doc.to_dict()
+    new_device_id = update_data.get("device_id", existing.get("device_id", ""))
+    new_user_id = update_data.get("user_id", existing.get("user_id", ""))
+
+    if "device_id" in update_data or "user_id" in update_data:
+        device_name, user_name = _resolve_names(db, new_device_id, new_user_id)
+        if "device_id" in update_data:
+            update_data["device_name"] = device_name
+        if "user_id" in update_data:
+            update_data["user_name"] = user_name
+
+    update_data["updated_at"] = datetime.now(timezone.utc).strftime("%d %B %Y at %H:%M:%S UTC")
+    doc_ref.update(update_data)
+
+    updated_doc = doc_ref.get()
+    return _doc_to_note(updated_doc)
+
+
+def delete_note(note_id: str) -> None:
+    """Delete a note document from Firestore."""
+    db = get_db()
+    doc_ref = db.collection(COLLECTION).document(note_id)
+    doc = doc_ref.get()
+    if not doc.exists:
+        raise NotFoundError("Note")
+
+    doc_ref.delete()

backend/main.py

@@ -9,6 +9,7 @@ from devices.router import router as devices_router
 from settings.router import router as settings_router
 from users.router import router as users_router
 from mqtt.router import router as mqtt_router
+from equipment.router import router as equipment_router
 from mqtt.client import mqtt_manager
 from mqtt import database as mqtt_db
 
@@ -33,6 +34,7 @@ app.include_router(devices_router)
 app.include_router(settings_router)
 app.include_router(users_router)
 app.include_router(mqtt_router)
+app.include_router(equipment_router)
 
 
 @app.on_event("startup")

frontend/src/App.jsx

@@ -15,6 +15,9 @@ import UserForm from "./users/UserForm";
 import MqttDashboard from "./mqtt/MqttDashboard";
 import CommandPanel from "./mqtt/CommandPanel";
 import LogViewer from "./mqtt/LogViewer";
+import NoteList from "./equipment/NoteList";
+import NoteDetail from "./equipment/NoteDetail";
+import NoteForm from "./equipment/NoteForm";
 
 function ProtectedRoute({ children }) {
   const { user, loading } = useAuth();
@@ -75,6 +78,10 @@ export default function App() {
         <Route path="mqtt" element={<MqttDashboard />} />
         <Route path="mqtt/commands" element={<CommandPanel />} />
         <Route path="mqtt/logs" element={<LogViewer />} />
+        <Route path="equipment/notes" element={<NoteList />} />
+        <Route path="equipment/notes/new" element={<NoteForm />} />
+        <Route path="equipment/notes/:id" element={<NoteDetail />} />
+        <Route path="equipment/notes/:id/edit" element={<NoteForm />} />
         <Route path="*" element={<Navigate to="/" replace />} />
       </Route>
     </Routes>

frontend/src/devices/DeviceDetail.jsx

@@ -3,6 +3,7 @@ import { useParams, useNavigate } from "react-router-dom";
 import api from "../api/client";
 import { useAuth } from "../auth/AuthContext";
 import ConfirmDialog from "../components/ConfirmDialog";
+import NotesPanel from "../equipment/NotesPanel";
 
 function Field({ label, children }) {
   return (
@@ -379,6 +380,9 @@ export default function DeviceDetail() {
               </Field>
             </dl>
           </section>
+
+          {/* Equipment Notes */}
+          <NotesPanel deviceId={id} />
         </div>
       </div>
 

frontend/src/equipment/NoteDetail.jsx

@@ -0,0 +1,296 @@
+import { useState, useEffect } from "react";
+import { useParams, useNavigate } from "react-router-dom";
+import api from "../api/client";
+import { useAuth } from "../auth/AuthContext";
+import ConfirmDialog from "../components/ConfirmDialog";
+
+const categoryStyle = (cat) => {
+  switch (cat) {
+    case "issue":
+      return { backgroundColor: "var(--danger-bg)", color: "var(--danger-text)" };
+    case "maintenance":
+      return { backgroundColor: "var(--warning-bg, rgba(245,158,11,0.15))", color: "var(--warning-text, #f59e0b)" };
+    case "installation":
+      return { backgroundColor: "var(--success-bg)", color: "var(--success-text)" };
+    default:
+      return { backgroundColor: "var(--bg-card-hover)", color: "var(--text-muted)" };
+  }
+};
+
+function Field({ label, children }) {
+  return (
+    <div>
+      <dt
+        className="text-xs font-medium uppercase tracking-wide"
+        style={{ color: "var(--text-muted)" }}
+      >
+        {label}
+      </dt>
+      <dd className="mt-1 text-sm" style={{ color: "var(--text-primary)" }}>
+        {children || "-"}
+      </dd>
+    </div>
+  );
+}
+
+export default function NoteDetail() {
+  const { id } = useParams();
+  const navigate = useNavigate();
+  const { hasRole } = useAuth();
+  const canEdit = hasRole("superadmin", "device_manager");
+
+  const [note, setNote] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [showDelete, setShowDelete] = useState(false);
+
+  useEffect(() => {
+    loadNote();
+  }, [id]);
+
+  const loadNote = async () => {
+    setLoading(true);
+    try {
+      const data = await api.get(`/equipment/notes/${id}`);
+      setNote(data);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleDelete = async () => {
+    try {
+      await api.delete(`/equipment/notes/${id}`);
+      navigate("/equipment/notes");
+    } catch (err) {
+      setError(err.message);
+      setShowDelete(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="text-center py-8" style={{ color: "var(--text-muted)" }}>
+        Loading...
+      </div>
+    );
+  }
+
+  if (error && !note) {
+    return (
+      <div
+        className="text-sm rounded-md p-3 border"
+        style={{
+          backgroundColor: "var(--danger-bg)",
+          borderColor: "var(--danger)",
+          color: "var(--danger-text)",
+        }}
+      >
+        {error}
+      </div>
+    );
+  }
+
+  if (!note) return null;
+
+  return (
+    <div>
+      <div className="flex items-center justify-between mb-6">
+        <div>
+          <button
+            onClick={() => navigate("/equipment/notes")}
+            className="text-sm hover:underline mb-2 inline-block"
+            style={{ color: "var(--accent)" }}
+          >
+            &larr; Back to Notes
+          </button>
+          <div className="flex items-center gap-3">
+            <h1
+              className="text-2xl font-bold"
+              style={{ color: "var(--text-heading)" }}
+            >
+              {note.title || "Untitled Note"}
+            </h1>
+            <span
+              className="px-2 py-0.5 text-xs rounded-full"
+              style={categoryStyle(note.category)}
+            >
+              {note.category || "general"}
+            </span>
+          </div>
+        </div>
+        {canEdit && (
+          <div className="flex gap-2">
+            <button
+              onClick={() => navigate(`/equipment/notes/${id}/edit`)}
+              className="px-4 py-2 text-sm rounded-md transition-colors"
+              style={{ backgroundColor: "var(--text-link)", color: "var(--text-white)" }}
+            >
+              Edit
+            </button>
+            <button
+              onClick={() => setShowDelete(true)}
+              className="px-4 py-2 text-sm rounded-md transition-colors"
+              style={{ backgroundColor: "var(--danger)", color: "var(--text-white)" }}
+            >
+              Delete
+            </button>
+          </div>
+        )}
+      </div>
+
+      {error && (
+        <div
+          className="text-sm rounded-md p-3 mb-4 border"
+          style={{
+            backgroundColor: "var(--danger-bg)",
+            borderColor: "var(--danger)",
+            color: "var(--danger-text)",
+          }}
+        >
+          {error}
+        </div>
+      )}
+
+      <div className="grid grid-cols-1 xl:grid-cols-2 gap-6">
+        {/* Left Column */}
+        <div className="space-y-6">
+          {/* Note Content */}
+          <section
+            className="rounded-lg border p-6"
+            style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+          >
+            <h2
+              className="text-lg font-semibold mb-4"
+              style={{ color: "var(--text-heading)" }}
+            >
+              Content
+            </h2>
+            <div
+              className="text-sm whitespace-pre-wrap"
+              style={{ color: "var(--text-primary)" }}
+            >
+              {note.content || "No content."}
+            </div>
+          </section>
+
+          {/* Timestamps */}
+          <section
+            className="rounded-lg border p-6"
+            style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+          >
+            <h2
+              className="text-lg font-semibold mb-4"
+              style={{ color: "var(--text-heading)" }}
+            >
+              Details
+            </h2>
+            <dl className="grid grid-cols-2 md:grid-cols-3 gap-4">
+              <Field label="Category">
+                <span
+                  className="px-2 py-0.5 text-xs rounded-full"
+                  style={categoryStyle(note.category)}
+                >
+                  {note.category || "general"}
+                </span>
+              </Field>
+              <Field label="Created By">{note.created_by}</Field>
+              <Field label="Document ID">
+                <span className="font-mono text-xs" style={{ color: "var(--text-muted)" }}>
+                  {note.id}
+                </span>
+              </Field>
+              <Field label="Created At">{note.created_at}</Field>
+              <Field label="Updated At">{note.updated_at}</Field>
+            </dl>
+          </section>
+        </div>
+
+        {/* Right Column */}
+        <div className="space-y-6">
+          {/* Linked Device */}
+          <section
+            className="rounded-lg border p-6"
+            style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+          >
+            <h2
+              className="text-lg font-semibold mb-4"
+              style={{ color: "var(--text-heading)" }}
+            >
+              Linked Device
+            </h2>
+            {note.device_id ? (
+              <div className="flex items-center justify-between">
+                <div>
+                  <p className="text-sm font-medium" style={{ color: "var(--text-heading)" }}>
+                    {note.device_name || "Unnamed Device"}
+                  </p>
+                  <p className="text-xs font-mono" style={{ color: "var(--text-muted)" }}>
+                    {note.device_id}
+                  </p>
+                </div>
+                <button
+                  onClick={() => navigate(`/devices/${note.device_id}`)}
+                  className="text-xs hover:underline"
+                  style={{ color: "var(--text-link)" }}
+                >
+                  View Device
+                </button>
+              </div>
+            ) : (
+              <p className="text-sm" style={{ color: "var(--text-muted)" }}>
+                No device linked.
+              </p>
+            )}
+          </section>
+
+          {/* Linked User */}
+          <section
+            className="rounded-lg border p-6"
+            style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+          >
+            <h2
+              className="text-lg font-semibold mb-4"
+              style={{ color: "var(--text-heading)" }}
+            >
+              Linked User
+            </h2>
+            {note.user_id ? (
+              <div className="flex items-center justify-between">
+                <div>
+                  <p className="text-sm font-medium" style={{ color: "var(--text-heading)" }}>
+                    {note.user_name || "Unnamed User"}
+                  </p>
+                  <p className="text-xs font-mono" style={{ color: "var(--text-muted)" }}>
+                    {note.user_id}
+                  </p>
+                </div>
+                <button
+                  onClick={() => navigate(`/users/${note.user_id}`)}
+                  className="text-xs hover:underline"
+                  style={{ color: "var(--text-link)" }}
+                >
+                  View User
+                </button>
+              </div>
+            ) : (
+              <p className="text-sm" style={{ color: "var(--text-muted)" }}>
+                No user linked.
+              </p>
+            )}
+          </section>
+        </div>
+      </div>
+
+      <ConfirmDialog
+        open={showDelete}
+        title="Delete Note"
+        message={`Are you sure you want to delete "${note.title || "this note"}"? This action cannot be undone.`}
+        onConfirm={handleDelete}
+        onCancel={() => setShowDelete(false)}
+      />
+    </div>
+  );
+}

frontend/src/equipment/NoteForm.jsx

@@ -0,0 +1,266 @@
+import { useState, useEffect } from "react";
+import { useNavigate, useParams, useSearchParams } from "react-router-dom";
+import api from "../api/client";
+
+const CATEGORIES = ["general", "maintenance", "installation", "issue", "other"];
+
+export default function NoteForm() {
+  const { id } = useParams();
+  const isEdit = Boolean(id);
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  const [title, setTitle] = useState("");
+  const [content, setContent] = useState("");
+  const [category, setCategory] = useState("general");
+  const [deviceId, setDeviceId] = useState(searchParams.get("device_id") || "");
+  const [userId, setUserId] = useState(searchParams.get("user_id") || "");
+
+  const [devices, setDevices] = useState([]);
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    loadOptions();
+    if (isEdit) loadNote();
+  }, [id]);
+
+  const loadOptions = async () => {
+    try {
+      const [devData, usrData] = await Promise.all([
+        api.get("/devices"),
+        api.get("/users"),
+      ]);
+      setDevices(devData.devices || []);
+      setUsers(usrData.users || []);
+    } catch {
+      // Non-critical — dropdowns will just be empty
+    }
+  };
+
+  const loadNote = async () => {
+    setLoading(true);
+    try {
+      const note = await api.get(`/equipment/notes/${id}`);
+      setTitle(note.title || "");
+      setContent(note.content || "");
+      setCategory(note.category || "general");
+      setDeviceId(note.device_id || "");
+      setUserId(note.user_id || "");
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    setSaving(true);
+    setError("");
+
+    try {
+      const body = {
+        title,
+        content,
+        category,
+        device_id: deviceId || null,
+        user_id: userId || null,
+      };
+
+      let noteId = id;
+      if (isEdit) {
+        await api.put(`/equipment/notes/${id}`, body);
+      } else {
+        const created = await api.post("/equipment/notes", body);
+        noteId = created.id;
+      }
+
+      navigate(`/equipment/notes/${noteId}`);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (loading) {
+    return <div className="text-center py-8" style={{ color: "var(--text-muted)" }}>Loading...</div>;
+  }
+
+  const inputClass = "w-full px-3 py-2 rounded-md text-sm border";
+
+  return (
+    <div>
+      <div className="flex items-center justify-between mb-6">
+        <h1 className="text-2xl font-bold" style={{ color: "var(--text-heading)" }}>
+          {isEdit ? "Edit Note" : "Add Note"}
+        </h1>
+        <div className="flex gap-3">
+          <button
+            type="button"
+            onClick={() => navigate(isEdit ? `/equipment/notes/${id}` : "/equipment/notes")}
+            className="px-4 py-2 text-sm rounded-md hover:opacity-80 transition-colors"
+            style={{ backgroundColor: "var(--bg-card-hover)", color: "var(--text-primary)" }}
+          >
+            Cancel
+          </button>
+          <button
+            type="submit"
+            form="note-form"
+            disabled={saving}
+            className="px-4 py-2 text-sm rounded-md hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+            style={{ backgroundColor: "var(--btn-primary)", color: "var(--text-white)" }}
+          >
+            {saving ? "Saving..." : isEdit ? "Update Note" : "Create Note"}
+          </button>
+        </div>
+      </div>
+
+      {error && (
+        <div
+          className="text-sm rounded-md p-3 mb-4 border"
+          style={{ backgroundColor: "var(--danger-bg)", borderColor: "var(--danger)", color: "var(--danger-text)" }}
+        >
+          {error}
+        </div>
+      )}
+
+      <form id="note-form" onSubmit={handleSubmit}>
+        <div className="grid grid-cols-1 xl:grid-cols-2 gap-6">
+          {/* Left Column — Note Content */}
+          <div className="space-y-6">
+            <section
+              className="rounded-lg border p-6"
+              style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+            >
+              <h2 className="text-lg font-semibold mb-4" style={{ color: "var(--text-heading)" }}>
+                Note Details
+              </h2>
+              <div className="space-y-4">
+                <div>
+                  <label className="block text-sm font-medium mb-1" style={{ color: "var(--text-secondary)" }}>
+                    Title *
+                  </label>
+                  <input
+                    type="text"
+                    required
+                    value={title}
+                    onChange={(e) => setTitle(e.target.value)}
+                    placeholder="Brief description of the note"
+                    className={inputClass}
+                    style={{
+                      backgroundColor: "var(--bg-primary)",
+                      color: "var(--text-primary)",
+                      borderColor: "var(--border-primary)",
+                    }}
+                  />
+                </div>
+                <div>
+                  <label className="block text-sm font-medium mb-1" style={{ color: "var(--text-secondary)" }}>
+                    Content *
+                  </label>
+                  <textarea
+                    required
+                    value={content}
+                    onChange={(e) => setContent(e.target.value)}
+                    rows={8}
+                    placeholder="Detailed note content..."
+                    className={inputClass}
+                    style={{
+                      backgroundColor: "var(--bg-primary)",
+                      color: "var(--text-primary)",
+                      borderColor: "var(--border-primary)",
+                      resize: "vertical",
+                    }}
+                  />
+                </div>
+                <div>
+                  <label className="block text-sm font-medium mb-1" style={{ color: "var(--text-secondary)" }}>
+                    Category
+                  </label>
+                  <select
+                    value={category}
+                    onChange={(e) => setCategory(e.target.value)}
+                    className={inputClass}
+                    style={{
+                      backgroundColor: "var(--bg-primary)",
+                      color: "var(--text-primary)",
+                      borderColor: "var(--border-primary)",
+                    }}
+                  >
+                    {CATEGORIES.map((c) => (
+                      <option key={c} value={c}>
+                        {c.charAt(0).toUpperCase() + c.slice(1)}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              </div>
+            </section>
+          </div>
+
+          {/* Right Column — Associations */}
+          <div className="space-y-6">
+            <section
+              className="rounded-lg border p-6"
+              style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+            >
+              <h2 className="text-lg font-semibold mb-4" style={{ color: "var(--text-heading)" }}>
+                Link To
+              </h2>
+              <div className="space-y-4">
+                <div>
+                  <label className="block text-sm font-medium mb-1" style={{ color: "var(--text-secondary)" }}>
+                    Device (optional)
+                  </label>
+                  <select
+                    value={deviceId}
+                    onChange={(e) => setDeviceId(e.target.value)}
+                    className={inputClass}
+                    style={{
+                      backgroundColor: "var(--bg-primary)",
+                      color: "var(--text-primary)",
+                      borderColor: "var(--border-primary)",
+                    }}
+                  >
+                    <option value="">No device linked</option>
+                    {devices.map((d) => (
+                      <option key={d.id} value={d.id}>
+                        {d.device_name || "Unnamed"} ({d.device_id || d.id})
+                      </option>
+                    ))}
+                  </select>
+                </div>
+                <div>
+                  <label className="block text-sm font-medium mb-1" style={{ color: "var(--text-secondary)" }}>
+                    User (optional)
+                  </label>
+                  <select
+                    value={userId}
+                    onChange={(e) => setUserId(e.target.value)}
+                    className={inputClass}
+                    style={{
+                      backgroundColor: "var(--bg-primary)",
+                      color: "var(--text-primary)",
+                      borderColor: "var(--border-primary)",
+                    }}
+                  >
+                    <option value="">No user linked</option>
+                    {users.map((u) => (
+                      <option key={u.id} value={u.id}>
+                        {u.display_name || "Unnamed"} ({u.email || u.id})
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              </div>
+            </section>
+          </div>
+        </div>
+      </form>
+    </div>
+  );
+}

frontend/src/equipment/NoteList.jsx

@@ -0,0 +1,241 @@
+import { useState, useEffect } from "react";
+import { useNavigate, useSearchParams } from "react-router-dom";
+import api from "../api/client";
+import { useAuth } from "../auth/AuthContext";
+import SearchBar from "../components/SearchBar";
+import ConfirmDialog from "../components/ConfirmDialog";
+
+const CATEGORY_OPTIONS = ["", "general", "maintenance", "installation", "issue", "other"];
+
+const categoryStyle = (cat) => {
+  switch (cat) {
+    case "issue":
+      return { backgroundColor: "var(--danger-bg)", color: "var(--danger-text)" };
+    case "maintenance":
+      return { backgroundColor: "var(--warning-bg, rgba(245,158,11,0.15))", color: "var(--warning-text, #f59e0b)" };
+    case "installation":
+      return { backgroundColor: "var(--success-bg)", color: "var(--success-text)" };
+    default:
+      return { backgroundColor: "var(--bg-card-hover)", color: "var(--text-muted)" };
+  }
+};
+
+export default function NoteList() {
+  const [notes, setNotes] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [search, setSearch] = useState("");
+  const [categoryFilter, setCategoryFilter] = useState("");
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [hoveredRow, setHoveredRow] = useState(null);
+  const navigate = useNavigate();
+  const { hasRole } = useAuth();
+  const canEdit = hasRole("superadmin", "device_manager");
+  const [searchParams] = useSearchParams();
+
+  const deviceIdFilter = searchParams.get("device_id") || "";
+  const userIdFilter = searchParams.get("user_id") || "";
+
+  const fetchNotes = async () => {
+    setLoading(true);
+    setError("");
+    try {
+      const params = new URLSearchParams();
+      if (search) params.set("search", search);
+      if (categoryFilter) params.set("category", categoryFilter);
+      if (deviceIdFilter) params.set("device_id", deviceIdFilter);
+      if (userIdFilter) params.set("user_id", userIdFilter);
+      const qs = params.toString();
+      const data = await api.get(`/equipment/notes${qs ? `?${qs}` : ""}`);
+      setNotes(data.notes);
+      setTotal(data.total);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchNotes();
+  }, [search, categoryFilter, deviceIdFilter, userIdFilter]);
+
+  const handleDelete = async () => {
+    if (!deleteTarget) return;
+    try {
+      await api.delete(`/equipment/notes/${deleteTarget.id}`);
+      setDeleteTarget(null);
+      fetchNotes();
+    } catch (err) {
+      setError(err.message);
+      setDeleteTarget(null);
+    }
+  };
+
+  return (
+    <div>
+      <div className="flex items-center justify-between mb-6">
+        <h1 className="text-2xl font-bold" style={{ color: "var(--text-heading)" }}>Equipment Notes</h1>
+        {canEdit && (
+          <button
+            onClick={() => {
+              const params = new URLSearchParams();
+              if (deviceIdFilter) params.set("device_id", deviceIdFilter);
+              if (userIdFilter) params.set("user_id", userIdFilter);
+              const qs = params.toString();
+              navigate(`/equipment/notes/new${qs ? `?${qs}` : ""}`);
+            }}
+            className="px-4 py-2 text-sm rounded-md hover:opacity-90 transition-colors cursor-pointer"
+            style={{ backgroundColor: "var(--btn-primary)", color: "var(--text-white)" }}
+          >
+            Add Note
+          </button>
+        )}
+      </div>
+
+      <div className="mb-4 space-y-3">
+        <SearchBar onSearch={setSearch} placeholder="Search by title or content..." />
+        <div className="flex flex-wrap gap-3 items-center">
+          <select
+            value={categoryFilter}
+            onChange={(e) => setCategoryFilter(e.target.value)}
+            className="px-3 py-2 rounded-md text-sm cursor-pointer border"
+            style={{
+              backgroundColor: "var(--bg-card)",
+              color: "var(--text-primary)",
+              borderColor: "var(--border-primary)",
+            }}
+          >
+            <option value="">All Categories</option>
+            {CATEGORY_OPTIONS.filter(Boolean).map((c) => (
+              <option key={c} value={c}>
+                {c.charAt(0).toUpperCase() + c.slice(1)}
+              </option>
+            ))}
+          </select>
+          <span className="flex items-center text-sm" style={{ color: "var(--text-muted)" }}>
+            {total} {total === 1 ? "note" : "notes"}
+          </span>
+        </div>
+      </div>
+
+      {error && (
+        <div
+          className="text-sm rounded-md p-3 mb-4 border"
+          style={{
+            backgroundColor: "var(--danger-bg)",
+            borderColor: "var(--danger)",
+            color: "var(--danger-text)",
+          }}
+        >
+          {error}
+        </div>
+      )}
+
+      {loading ? (
+        <div className="text-center py-8" style={{ color: "var(--text-muted)" }}>Loading...</div>
+      ) : notes.length === 0 ? (
+        <div
+          className="rounded-lg p-8 text-center text-sm border"
+          style={{
+            backgroundColor: "var(--bg-card)",
+            borderColor: "var(--border-primary)",
+            color: "var(--text-muted)",
+          }}
+        >
+          No notes found.
+        </div>
+      ) : (
+        <div
+          className="rounded-lg overflow-hidden border"
+          style={{
+            backgroundColor: "var(--bg-card)",
+            borderColor: "var(--border-primary)",
+          }}
+        >
+          <div className="overflow-x-auto">
+            <table className="w-full text-sm">
+              <thead>
+                <tr style={{ backgroundColor: "var(--bg-primary)", borderBottom: "1px solid var(--border-primary)" }}>
+                  <th className="px-4 py-3 text-left font-medium w-28" style={{ color: "var(--text-secondary)" }}>Category</th>
+                  <th className="px-4 py-3 text-left font-medium" style={{ color: "var(--text-secondary)" }}>Title</th>
+                  <th className="px-4 py-3 text-left font-medium" style={{ color: "var(--text-secondary)" }}>Device</th>
+                  <th className="px-4 py-3 text-left font-medium" style={{ color: "var(--text-secondary)" }}>User</th>
+                  <th className="px-4 py-3 text-left font-medium" style={{ color: "var(--text-secondary)" }}>Created</th>
+                  {canEdit && (
+                    <th className="px-4 py-3 text-left font-medium w-24" style={{ color: "var(--text-secondary)" }} />
+                  )}
+                </tr>
+              </thead>
+              <tbody>
+                {notes.map((note, index) => (
+                  <tr
+                    key={note.id}
+                    onClick={() => navigate(`/equipment/notes/${note.id}`)}
+                    className="cursor-pointer"
+                    style={{
+                      borderBottom: index < notes.length - 1 ? "1px solid var(--border-primary)" : "none",
+                      backgroundColor: hoveredRow === note.id ? "var(--bg-card-hover)" : "transparent",
+                    }}
+                    onMouseEnter={() => setHoveredRow(note.id)}
+                    onMouseLeave={() => setHoveredRow(null)}
+                  >
+                    <td className="px-4 py-3">
+                      <span
+                        className="px-2 py-0.5 text-xs rounded-full"
+                        style={categoryStyle(note.category)}
+                      >
+                        {note.category || "general"}
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 font-medium" style={{ color: "var(--text-heading)" }}>
+                      {note.title || "Untitled"}
+                    </td>
+                    <td className="px-4 py-3" style={{ color: "var(--text-primary)" }}>
+                      {note.device_name || "-"}
+                    </td>
+                    <td className="px-4 py-3" style={{ color: "var(--text-primary)" }}>
+                      {note.user_name || "-"}
+                    </td>
+                    <td className="px-4 py-3 text-xs" style={{ color: "var(--text-muted)" }}>
+                      {note.created_at || "-"}
+                    </td>
+                    {canEdit && (
+                      <td className="px-4 py-3">
+                        <div className="flex gap-2" onClick={(e) => e.stopPropagation()}>
+                          <button
+                            onClick={() => navigate(`/equipment/notes/${note.id}/edit`)}
+                            className="hover:opacity-80 text-xs cursor-pointer"
+                            style={{ color: "var(--text-link)" }}
+                          >
+                            Edit
+                          </button>
+                          <button
+                            onClick={() => setDeleteTarget(note)}
+                            className="hover:opacity-80 text-xs cursor-pointer"
+                            style={{ color: "var(--danger)" }}
+                          >
+                            Delete
+                          </button>
+                        </div>
+                      </td>
+                    )}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      )}
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title="Delete Note"
+        message={`Are you sure you want to delete "${deleteTarget?.title || "this note"}"? This action cannot be undone.`}
+        onConfirm={handleDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </div>
+  );
+}

frontend/src/equipment/NotesPanel.jsx

@@ -0,0 +1,271 @@
+import { useState, useEffect } from "react";
+import { useNavigate } from "react-router-dom";
+import api from "../api/client";
+import { useAuth } from "../auth/AuthContext";
+import ConfirmDialog from "../components/ConfirmDialog";
+
+const categoryStyle = (cat) => {
+  switch (cat) {
+    case "issue":
+      return { backgroundColor: "var(--danger-bg)", color: "var(--danger-text)" };
+    case "maintenance":
+      return { backgroundColor: "var(--warning-bg, rgba(245,158,11,0.15))", color: "var(--warning-text, #f59e0b)" };
+    case "installation":
+      return { backgroundColor: "var(--success-bg)", color: "var(--success-text)" };
+    default:
+      return { backgroundColor: "var(--bg-card-hover)", color: "var(--text-muted)" };
+  }
+};
+
+const CATEGORIES = ["general", "maintenance", "installation", "issue", "other"];
+
+export default function NotesPanel({ deviceId, userId }) {
+  const [notes, setNotes] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [showForm, setShowForm] = useState(false);
+  const [title, setTitle] = useState("");
+  const [content, setContent] = useState("");
+  const [category, setCategory] = useState("general");
+  const [saving, setSaving] = useState(false);
+  const navigate = useNavigate();
+  const { hasRole } = useAuth();
+  const canEdit = hasRole("superadmin", "device_manager");
+
+  const fetchNotes = async () => {
+    setLoading(true);
+    setError("");
+    try {
+      const params = new URLSearchParams();
+      if (deviceId) params.set("device_id", deviceId);
+      if (userId) params.set("user_id", userId);
+      const qs = params.toString();
+      const data = await api.get(`/equipment/notes${qs ? `?${qs}` : ""}`);
+      setNotes(data.notes);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchNotes();
+  }, [deviceId, userId]);
+
+  const handleCreate = async (e) => {
+    e.preventDefault();
+    setSaving(true);
+    setError("");
+    try {
+      await api.post("/equipment/notes", {
+        title,
+        content,
+        category,
+        device_id: deviceId || null,
+        user_id: userId || null,
+      });
+      setTitle("");
+      setContent("");
+      setCategory("general");
+      setShowForm(false);
+      fetchNotes();
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleDelete = async () => {
+    if (!deleteTarget) return;
+    try {
+      await api.delete(`/equipment/notes/${deleteTarget.id}`);
+      setDeleteTarget(null);
+      fetchNotes();
+    } catch (err) {
+      setError(err.message);
+      setDeleteTarget(null);
+    }
+  };
+
+  const inputClass = "w-full px-3 py-2 rounded-md text-sm border";
+
+  return (
+    <section
+      className="rounded-lg border p-6"
+      style={{ backgroundColor: "var(--bg-card)", borderColor: "var(--border-primary)" }}
+    >
+      <div className="flex items-center justify-between mb-4">
+        <h2
+          className="text-lg font-semibold"
+          style={{ color: "var(--text-heading)" }}
+        >
+          Notes ({notes.length})
+        </h2>
+        <div className="flex gap-2">
+          {canEdit && (
+            <button
+              onClick={() => setShowForm(!showForm)}
+              className="px-3 py-1.5 text-xs rounded-md hover:opacity-90 transition-colors cursor-pointer"
+              style={{ backgroundColor: "var(--btn-primary)", color: "var(--text-white)" }}
+            >
+              {showForm ? "Cancel" : "Add Note"}
+            </button>
+          )}
+          <button
+            onClick={() => {
+              const params = new URLSearchParams();
+              if (deviceId) params.set("device_id", deviceId);
+              if (userId) params.set("user_id", userId);
+              navigate(`/equipment/notes?${params}`);
+            }}
+            className="px-3 py-1.5 text-xs rounded-md hover:opacity-80 transition-colors cursor-pointer"
+            style={{ backgroundColor: "var(--bg-card-hover)", color: "var(--text-primary)" }}
+          >
+            View All
+          </button>
+        </div>
+      </div>
+
+      {error && (
+        <div
+          className="text-sm rounded-md p-3 mb-4 border"
+          style={{
+            backgroundColor: "var(--danger-bg)",
+            borderColor: "var(--danger)",
+            color: "var(--danger-text)",
+          }}
+        >
+          {error}
+        </div>
+      )}
+
+      {showForm && (
+        <form onSubmit={handleCreate} className="mb-4 p-4 rounded-md border" style={{ backgroundColor: "var(--bg-primary)", borderColor: "var(--border-primary)" }}>
+          <div className="space-y-3">
+            <div className="flex gap-3">
+              <div className="flex-1">
+                <input
+                  type="text"
+                  required
+                  value={title}
+                  onChange={(e) => setTitle(e.target.value)}
+                  placeholder="Note title"
+                  className={inputClass}
+                  style={{
+                    backgroundColor: "var(--bg-card)",
+                    color: "var(--text-primary)",
+                    borderColor: "var(--border-primary)",
+                  }}
+                />
+              </div>
+              <select
+                value={category}
+                onChange={(e) => setCategory(e.target.value)}
+                className="px-3 py-2 rounded-md text-sm border"
+                style={{
+                  backgroundColor: "var(--bg-card)",
+                  color: "var(--text-primary)",
+                  borderColor: "var(--border-primary)",
+                }}
+              >
+                {CATEGORIES.map((c) => (
+                  <option key={c} value={c}>
+                    {c.charAt(0).toUpperCase() + c.slice(1)}
+                  </option>
+                ))}
+              </select>
+            </div>
+            <textarea
+              required
+              value={content}
+              onChange={(e) => setContent(e.target.value)}
+              rows={3}
+              placeholder="Note content..."
+              className={inputClass}
+              style={{
+                backgroundColor: "var(--bg-card)",
+                color: "var(--text-primary)",
+                borderColor: "var(--border-primary)",
+                resize: "vertical",
+              }}
+            />
+            <div className="flex justify-end">
+              <button
+                type="submit"
+                disabled={saving}
+                className="px-4 py-2 text-sm rounded-md hover:opacity-90 disabled:opacity-50 transition-colors"
+                style={{ backgroundColor: "var(--btn-primary)", color: "var(--text-white)" }}
+              >
+                {saving ? "Saving..." : "Save Note"}
+              </button>
+            </div>
+          </div>
+        </form>
+      )}
+
+      {loading ? (
+        <p className="text-sm py-4 text-center" style={{ color: "var(--text-muted)" }}>Loading...</p>
+      ) : notes.length === 0 ? (
+        <p className="text-sm" style={{ color: "var(--text-muted)" }}>
+          No notes yet.
+        </p>
+      ) : (
+        <div className="space-y-2">
+          {notes.map((note) => (
+            <div
+              key={note.id}
+              className="p-3 rounded-md border cursor-pointer hover:opacity-90 transition-colors"
+              style={{ backgroundColor: "var(--bg-primary)", borderColor: "var(--border-primary)" }}
+              onClick={() => navigate(`/equipment/notes/${note.id}`)}
+            >
+              <div className="flex items-start justify-between gap-2">
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-2 mb-1">
+                    <span
+                      className="px-2 py-0.5 text-xs rounded-full shrink-0"
+                      style={categoryStyle(note.category)}
+                    >
+                      {note.category}
+                    </span>
+                    <span className="text-sm font-medium truncate" style={{ color: "var(--text-heading)" }}>
+                      {note.title}
+                    </span>
+                  </div>
+                  <p className="text-xs truncate" style={{ color: "var(--text-muted)" }}>
+                    {note.content}
+                  </p>
+                  <p className="text-xs mt-1" style={{ color: "var(--text-muted)" }}>
+                    {note.created_by && `${note.created_by} · `}{note.created_at}
+                  </p>
+                </div>
+                {canEdit && (
+                  <button
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      setDeleteTarget(note);
+                    }}
+                    className="text-xs hover:opacity-80 shrink-0 cursor-pointer"
+                    style={{ color: "var(--danger)" }}
+                  >
+                    Delete
+                  </button>
+                )}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title="Delete Note"
+        message={`Are you sure you want to delete "${deleteTarget?.title || "this note"}"? This action cannot be undone.`}
+        onConfirm={handleDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </section>
+  );
+}

frontend/src/layout/Sidebar.jsx

@@ -23,6 +23,7 @@ const navItems = [
       { to: "/mqtt/logs", label: "Logs" },
     ],
   },
+  { to: "/equipment/notes", label: "Equipment Notes", roles: ["superadmin", "device_manager", "viewer"] },
 ];
 
 const linkClass = (isActive) =>

frontend/src/users/UserDetail.jsx

@@ -3,6 +3,7 @@ import { useParams, useNavigate } from "react-router-dom";
 import api from "../api/client";
 import { useAuth } from "../auth/AuthContext";
 import ConfirmDialog from "../components/ConfirmDialog";
+import NotesPanel from "../equipment/NotesPanel";
 
 function Field({ label, children }) {
   return (
@@ -473,6 +474,9 @@ export default function UserDetail() {
               </div>
             )}
           </section>
+
+          {/* Equipment Notes */}
+          <NotesPanel userId={id} />
         </div>
       </div>