update docs

README.md

@@ -55,6 +55,74 @@ X-API-Key: <your API_KEY>
 
 Missing/wrong key → `401`. `/`, `/health`, and `/docs` are open.
 
+## UI integration guide
+
+For a management portal the two primary resources are **Devices** (`/device`) and
+**VLANs** (`/vlan`). Everything else is lower-level raw-table access.
+
+**Base URL (staging):** `http://10.0.1.235:8000`
+**Every request:** header `X-API-Key: <API_KEY>` (except `/health`).
+**All bodies:** JSON with `Content-Type: application/json`.
+
+### Response shapes
+
+`GET /device/` — **paginated** envelope:
+
+```json
+{
+  "total": 4,
+  "limit": 50,
+  "offset": 0,
+  "items": [
+    { "mac_address": "AA-BB-CC-DD-EE-11", "group": "residents", "status": "paid",
+      "name": "Sara Ib", "phone": "9998887", "alias": "Living Room TV" }
+  ]
+}
+```
+
+`GET /device/{mac}`, `POST /device/add`, `POST /device/edit` — a single device object:
+
+```json
+{ "mac_address": "AA-BB-CC-DD-EE-11", "group": "residents", "status": "paid",
+  "name": "Sara Ib", "phone": "9998887", "alias": "Living Room TV" }
+```
+
+`GET /vlan/` — **plain array** (not paginated):
+
+```json
+[ { "alias": "residents", "vlanid": 51 }, { "alias": "staff", "vlanid": 55 } ]
+```
+
+- `status` is always one of `"new"`, `"paid"`, `"unpaid"`.
+- `group`, `name`, `phone`, `alias` may be `null` on older rows.
+- `DELETE` returns **`204` with an empty body** (nothing to parse).
+
+### Error shapes
+
+Application errors (`400`, `401`, `404`, `409`) return a **string** detail:
+
+```json
+{ "detail": "Device 'AA-BB-CC-DD-EE-11' already exists" }
+```
+
+Validation errors (`422`, bad/missing fields) return a FastAPI **array** detail:
+
+```json
+{ "detail": [ { "type": "missing", "loc": ["body","phone"], "msg": "Field required" } ] }
+```
+
+So in the UI: read `detail` directly when it's a string; when it's an array, join
+each entry's `msg` (and `loc`) for field-level messages.
+
+### Typical portal flows
+
+- **Provision a device:** `POST /device/add` with `mac_address`, `group` (an
+  existing VLAN alias), `name`, `phone`, optional `alias`. Handle `400` (group
+  missing), `409` (MAC exists), `422` (bad MAC / missing name·phone).
+- **Change plan state:** `POST /device/edit` `{mac_address, status}`.
+- **Move to another VLAN:** `POST /device/edit` `{mac_address, group}`.
+- **Populate a VLAN dropdown:** `GET /vlan/` → map `alias` (value sent as `group`).
+
 ## Endpoints
 
 All list endpoints return a paginated envelope and accept `?limit=&offset=` plus
@@ -173,11 +241,11 @@ curl http://10.0.1.235:8000/device/add \
  -H "Content-Type: application/json" \
  -d '{"mac_address":"14-99-3E-74-CB-7F","group":"staff","name":"Ali Hassan","phone":"7712345","alias":"Living Room TV"}' -s | jq
 
-# Edit a device (any one field: groupname and/or status)
+# Edit a device (any subset of group/status/name/phone/alias)
 curl http://10.0.1.235:8000/device/edit \
  -H "X-API-Key: staging-dev-key-change-me-7f3a9c1e5b" \
  -H "Content-Type: application/json" \
- -d '{"mac_address":"14-99-3E-74-CB-7F","status":"unpaid"}' -s | jq
+ -d '{"mac_address":"14-99-3E-74-CB-7F","status":"unpaid","alias":"Living Room TV"}' -s | jq
 
 # Delete a device
 curl http://10.0.1.235:8000/device/14-99-3E-74-CB-7F \
@@ -212,8 +280,9 @@ curl http://10.0.1.235:8000/health -s | jq
 | 200  | OK                                          |
 | 201  | Created                                     |
 | 204  | Deleted (no content)                        |
+| 400  | Bad request (e.g. referenced group/VLAN doesn't exist) |
 | 401  | Missing/invalid `X-API-Key`                 |
-| 404  | Row not found                               |
+| 404  | Row / device / VLAN not found               |
 | 409  | Duplicate / integrity conflict              |
 | 422  | Request body failed validation              |
 

docs.txt.save

@@ -0,0 +1,71 @@
+
+adding a new device
+example post /device/new
+macaddress,group
+removing an existing device
+
+listing vlans
+GET /vlan/
+SELECT * FROM `radgroupreply`
+this will return 3 duplicate "groupnames" with different attribute and vlaue
+only need to return group name and value for Tunnel-Private-Group-Id
+
+adding new vlan
+need to add 3 items with different attribute and value, 
+for example to add staff vlan with vlan ID 55
+api call should be like POST vlan/add and json data vlanid:55, alias staff
+
+'INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`)
+VALUES ('staff', 'Tunnel-Type', '=', 'VLAN');
+
+INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`)
+VALUES ('staff', 'Tunnel-Medium-Type', '=', 'IEEE-802');
+
+INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`)
+VALUES ('staff', 'Tunnel-Private-Group-Id', '=', '55');
+'
+deleting existing vlan
+you get api call to delete vlan 
+DELETE vlan/55
+and the sqlcommands should you looking for Tunnel-Private-Group-Id=55 and then deleting all the maching group names
+
+edit existing vlan (alias)
+post request, and allow to edit alias 
+
+disallow to add duplicate vlans or alias
+
+listing existing devices
+get /device/
+SELECT * FROM `radusergroup`
+and then 
+SELECT * FROM `customers`
+return mac address, groupname and status
+
+adding new device
+this input feils are 
+'
+POST /device/add with mac address and group and it involves few Commands
+`
+SELECT * FROM `radgroupreply` 
+# and see if the group in the device add command exists
+# respond 4xx (whatever needed with reason group not found)
+# else continue
+
+INSERT INTO `radcheck` (`username`, `attribute`, `op`, `value`)
+VALUES ('14-99-3E-74-CB-7F', 'Cleartext-Password', ':=', '14-99-3E-74-CB-7F');
+
+INSERT INTO `radusergroup` (`username`, `groupname`, `priority`)
+VALUES ('14-99-3E-74-CB-7F', 'staff', '1');
+
+INSERT INTO `customers` (`username`, `mac_address`, `status`, `created_at`)
+VALUES ('14-99-3E-74-CB-7F', '14-99-3E-74-CB-7F', 'paid', now());
+`
+
+deleting existing deivce
+edit existing device (input macaddress, edit groupname, edit status. do allow to edit just 1 feild) 
+use sesnible commands based on add devices
+
+i would also like a device alias, added to customers table like 
+"Customer name, device name, phone number"
+these are to be ignored by radius server, but helpful for human review 
+and add input fields during adding device and also listing devices