Add admin user management

docs/portfoliohub-spec.md

@@ -22,6 +22,7 @@ Primary goals:
 In scope:
 
 - Authenticated portfolio read and write operations
+- Admin-managed user CRUD operations
 - Role-based access control (read, trade-write, admin)
 - Optional PostgreSQL/Timescale-backed repository via feature flag
 - Operational commands for DB bootstrap and migration
@@ -121,6 +122,7 @@ Base routes:
 
 - Health: `/health`
 - Portfolio: `/portfolios`
+- Users: `/users`
 
 ### 7.1 Health Endpoint
 
@@ -245,6 +247,47 @@ Note: Since strategy sets are identified by (name, config) uniqueness, updating
 
 - See `docs/api-examples.md` for maintained request/response examples.
 
+### 7.5 User Endpoints
+
+All user management endpoints are admin-only.
+
+#### List Users
+
+- `GET /users`
+- Auth: `admin`
+- Response `200`: array of `UserResponse`
+
+#### Get User
+
+- `GET /users/{user_id}`
+- Auth: `admin`
+- Response `200`: `UserResponse`
+- Response `404`: user not found
+
+#### Create User
+
+- `POST /users`
+- Auth: `admin`
+- Body: `CreateUserRequest`
+- Response `201`: `UserResponse`
+- Response `409`: duplicate username or email
+
+#### Update User
+
+- `PATCH /users/{user_id}`
+- Auth: `admin`
+- Body: `UpdateUserRequest`
+- Response `200`: `UserResponse`
+- Response `404`: user not found
+- Response `409`: duplicate username or email
+
+#### Delete User
+
+- `DELETE /users/{user_id}`
+- Auth: `admin`
+- Response `204`: no content
+- Response `404`: user not found
+
 ## 8. Schema Specification
 
 ### 8.1 Request Models
@@ -278,6 +321,16 @@ Note: Since strategy sets are identified by (name, config) uniqueness, updating
 `BuyRequest` / `SellRequest`
 
 - `quantity: float > 0`
+
+`CreateUserRequest`
+
+- `username: str`
+- `email: str | null`
+
+`UpdateUserRequest`
+
+- `username: str | null`
+- `email: str | null`
 - `price: float > 0`
 - `fee: float >= 0`
 - `tax: float >= 0`