Add admin user management

README.md

@@ -8,9 +8,9 @@ This repository is in bootstrap phase.
 
 - FastAPI application entrypoint is available.
 - Token-based authentication and role checks are implemented.
-- Portfolio API contracts are defined.
+- Portfolio and user management API contracts are implemented.
 - Core portfolio domain services are ported from `jsbot-kis`.
-- Postgres repository scaffolding is implemented and gated behind `PORTFOLIOHUB_DB_ENABLED=true`.
+- Postgres-backed portfolio and user persistence is implemented and gated behind `PORTFOLIOHUB_DB_ENABLED=true`.
 
 ## Configuration
 
@@ -60,6 +60,11 @@ The repository now includes a `portfoliohub` CLI that mirrors the main portfolio
 
 ```bash
 portfoliohub --help
+portfoliohub user list
+portfoliohub user create --username alice --email alice@example.com --force
+portfoliohub user get <user-id>
+portfoliohub user update <user-id> --username alice-updated --force
+portfoliohub user delete <user-id> --force
 portfoliohub portfolio list
 portfoliohub portfolio status 005930:tv --recent 10
 portfoliohub portfolio create 005930:tv --symbol 005930 --cash-balance 10000000 --force
@@ -75,6 +80,11 @@ Supported commands:
 
 - `init-db`
 - `migrate-db`
+- `user list`
+- `user get`
+- `user create`
+- `user update`
+- `user delete`
 - `portfolio list`
 - `portfolio status`
 - `portfolio create`
@@ -148,12 +158,32 @@ PortfolioHub currently supports bearer tokens with three permission levels.
 
 - `read`: list and status endpoints
 - `trade-write`: mutation endpoints such as buy, sell, invest, transfer, reset
-- `admin`: delete and future operational actions
+- `admin`: delete, user management, and future operational actions
+
+## User management
+
+User management is exposed through both HTTP API and CLI.
+
+- API base route: `/users`
+- Permission: `admin` only
+- Supported operations: list, get, create, update, delete
+
+Example API calls:
+
+```bash
+curl -X GET "http://localhost:8000/users" \
+	-H "Authorization: Bearer <ADMIN_TOKEN>"
+
+curl -X POST "http://localhost:8000/users" \
+	-H "Authorization: Bearer <ADMIN_TOKEN>" \
+	-H "Content-Type: application/json" \
+	-d '{"username": "alice", "email": "alice@example.com"}'
+```
 
 The default `.env.example` includes example tokens for development.
 
 ## Planned next steps
 
-1. Implement Postgres/Timescale repository.
-2. Port domain logic from `jsbot-kis` services.
-3. Add integration tests for full portfolio flows.
+1. Apply and verify Alembic migrations against a real PostgreSQL/Timescale instance.
+2. Add integration tests for DB-backed portfolio and user flows.
+3. Design token-to-user mapping if ownership or user-scoped authorization is needed later.