josh
27d2ab0f0d
v1.0 Phase 1.1 — repo-wide lint/format baseline. - eslint.config.mjs (flat config) lints server, client, shared - .prettierrc.json, .prettierignore, .editorconfig, .nvmrc - Root package.json holds shared devDeps; per-package scripts keep their typecheck + test runners - Fix 7 lint issues surfaced by the baseline run: - TicketDetail.tsx: replace ternary-with-side-effects with if/else - admin/Users.tsx: escape apostrophe in JSX - errorHandler.ts: typed err as unknown with ErrorLike refinement - users.ts: Prisma.UserUpdateInput instead of Record<string, any> - seed.ts: drop unused goddard binding - Run prettier across tracked sources for a clean formatting baseline
456 lines
12 KiB
Markdown
456 lines
12 KiB
Markdown
# TicketingSystem
|
||
|
||
Internal ticketing system with CTI-based routing, severity levels, role-based access, and automation integration.
|
||
|
||
## Features
|
||
|
||
- **CTI routing** — tickets categorised by Category → Type → Item, reroutable at any time
|
||
- **Severity 1–5** — SEV 1 (critical) through SEV 5 (minimal); dashboard sorts by severity
|
||
- **Status lifecycle** — Open → In Progress → Resolved → Closed; resolved tickets auto-close after 14 days
|
||
- **Queue filter** — filter dashboard by category (queue)
|
||
- **My Tickets** — dedicated view of tickets assigned to you
|
||
- **Comments** — threaded markdown comments per ticket with author avatars
|
||
- **Roles** — Admin, Agent, User, Service (API key auth for automation)
|
||
- **Audit log** — every action tracked with actor, timestamp, and expandable detail
|
||
- **Admin panel** — manage users and the full CTI hierarchy via UI
|
||
- **n8n ready** — service accounts authenticate via `X-Api-Key` header
|
||
|
||
---
|
||
|
||
## Roles
|
||
|
||
| Role | Access |
|
||
| ----------- | ---------------------------------------------------------------------------- |
|
||
| **Admin** | Full access — manage users, CTI config, close and delete tickets |
|
||
| **Agent** | Manage tickets — create, update, assign, comment, change status (not Closed) |
|
||
| **User** | Basic access — view tickets and add comments only |
|
||
| **Service** | Automation account — authenticates via API key, no password login |
|
||
|
||
> Only **Admins** can manually set a ticket status to **Closed**.
|
||
|
||
---
|
||
|
||
## Production Deployment
|
||
|
||
### Prerequisites
|
||
|
||
- Docker + Docker Compose
|
||
- Nginx Proxy Manager pointed at the host port (default `3080`)
|
||
- Access to your Gitea container registry
|
||
|
||
### 1. Copy files to your server
|
||
|
||
```bash
|
||
scp docker-compose.yml .env.example user@your-server:~/ticketing/
|
||
```
|
||
|
||
### 2. Configure environment
|
||
|
||
```bash
|
||
cd ~/ticketing
|
||
cp .env.example .env
|
||
```
|
||
|
||
Edit `.env`:
|
||
|
||
```env
|
||
REGISTRY=gitea.thewrightserver.net
|
||
TAG=latest
|
||
POSTGRES_PASSWORD=<strong password>
|
||
JWT_SECRET=<output of: openssl rand -hex 64>
|
||
CLIENT_URL=http://tickets.thewrightserver.net
|
||
PORT=3080
|
||
```
|
||
|
||
Point NPM at `http://<host-ip>:3080` for the proxy host.
|
||
|
||
### 3. Deploy
|
||
|
||
```bash
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
### 4. Seed (first deploy only)
|
||
|
||
```bash
|
||
docker compose exec server npm run db:seed
|
||
```
|
||
|
||
This creates:
|
||
|
||
- `admin` user (password: `admin123`) — **change this immediately**
|
||
- `goddard` service account — API key is printed to the console; copy it now
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
### Requirements
|
||
|
||
- Node.js 22+
|
||
- PostgreSQL (local or via Docker)
|
||
|
||
### Start Postgres
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name ticketing-pg \
|
||
-e POSTGRES_DB=ticketing \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=postgres \
|
||
-p 5432:5432 \
|
||
postgres:16-alpine
|
||
```
|
||
|
||
### Server
|
||
|
||
```bash
|
||
cd server
|
||
cp .env.example .env # set DATABASE_URL and JWT_SECRET
|
||
npm install
|
||
npm run db:migrate # creates tables
|
||
npm run db:seed # seeds admin + Goddard + sample CTI
|
||
npm run dev # http://localhost:3000
|
||
```
|
||
|
||
### Client
|
||
|
||
```bash
|
||
cd client
|
||
npm install
|
||
npm run dev # http://localhost:5173 (proxies /api to :3000)
|
||
```
|
||
|
||
---
|
||
|
||
## API Reference
|
||
|
||
All endpoints (except `/api/auth/*`) require authentication via one of:
|
||
|
||
- **JWT**: `Authorization: Bearer <token>` (obtained from `POST /api/auth/login`)
|
||
- **API Key**: `X-Api-Key: sk_<key>` (Service accounts only)
|
||
|
||
Base URL: `https://tickets.thewrightserver.net/api`
|
||
|
||
---
|
||
|
||
### Authentication
|
||
|
||
#### `POST /api/auth/login`
|
||
|
||
Authenticate and receive a JWT.
|
||
|
||
**Body:**
|
||
|
||
```json
|
||
{ "username": "string", "password": "string" }
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"token": "eyJ...",
|
||
"user": {
|
||
"id": "...",
|
||
"username": "admin",
|
||
"displayName": "Admin",
|
||
"email": "...",
|
||
"role": "ADMIN"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `GET /api/auth/me`
|
||
|
||
Returns the currently authenticated user.
|
||
|
||
---
|
||
|
||
### Tickets
|
||
|
||
#### `GET /api/tickets`
|
||
|
||
List all tickets, sorted by severity (ASC) then created date (DESC).
|
||
|
||
**Query parameters:**
|
||
|
||
| Parameter | Type | Description |
|
||
| ------------ | ------ | ------------------------------------------------------------- |
|
||
| `status` | string | Filter by status: `OPEN`, `IN_PROGRESS`, `RESOLVED`, `CLOSED` |
|
||
| `severity` | number | Filter by severity: `1`–`5` |
|
||
| `categoryId` | string | Filter by category (queue) |
|
||
| `assigneeId` | string | Filter by assignee user ID |
|
||
| `search` | string | Full-text search on title, overview, and display ID |
|
||
|
||
**Response:** Array of ticket objects with nested `category`, `type`, `item`, `assignee`, `createdBy`, and `_count.comments`.
|
||
|
||
---
|
||
|
||
#### `GET /api/tickets/:id`
|
||
|
||
Fetch a single ticket by internal ID or display ID (e.g. `V325813929`). Includes full `comments` array.
|
||
|
||
---
|
||
|
||
#### `POST /api/tickets`
|
||
|
||
Create a new ticket. Requires **Agent**, **Admin**, or **Service** role.
|
||
|
||
**Body:**
|
||
|
||
```json
|
||
{
|
||
"title": "string",
|
||
"overview": "string (markdown)",
|
||
"severity": 1,
|
||
"categoryId": "string",
|
||
"typeId": "string",
|
||
"itemId": "string",
|
||
"assigneeId": "string (optional)"
|
||
}
|
||
```
|
||
|
||
**Response:** Created ticket object (201).
|
||
|
||
---
|
||
|
||
#### `PATCH /api/tickets/:id`
|
||
|
||
Update a ticket. Accepts any combination of fields. Requires **Agent**, **Admin**, or **Service** role.
|
||
|
||
> Setting `status` to `CLOSED` requires **Admin** role.
|
||
|
||
**Body (all fields optional):**
|
||
|
||
```json
|
||
{
|
||
"title": "string",
|
||
"overview": "string (markdown)",
|
||
"severity": 3,
|
||
"status": "IN_PROGRESS",
|
||
"assigneeId": "string | null",
|
||
"categoryId": "string",
|
||
"typeId": "string",
|
||
"itemId": "string"
|
||
}
|
||
```
|
||
|
||
All changes are recorded in the audit log automatically.
|
||
|
||
**Response:** Updated ticket object.
|
||
|
||
---
|
||
|
||
#### `DELETE /api/tickets/:id`
|
||
|
||
Delete a ticket and all associated comments and audit logs. **Admin only.**
|
||
|
||
**Response:** 204 No Content.
|
||
|
||
---
|
||
|
||
### Comments
|
||
|
||
#### `POST /api/tickets/:id/comments`
|
||
|
||
Add a comment to a ticket. Supports markdown. All authenticated roles may comment.
|
||
|
||
**Body:**
|
||
|
||
```json
|
||
{ "body": "string (markdown)" }
|
||
```
|
||
|
||
**Response:** Created comment object (201).
|
||
|
||
---
|
||
|
||
#### `DELETE /api/tickets/:id/comments/:commentId`
|
||
|
||
Delete a comment. Authors may delete their own comments; Admins may delete any.
|
||
|
||
**Response:** 204 No Content.
|
||
|
||
---
|
||
|
||
### Audit Log
|
||
|
||
#### `GET /api/tickets/:id/audit`
|
||
|
||
Retrieve the full audit log for a ticket, ordered newest first.
|
||
|
||
**Response:** Array of audit log entries:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "...",
|
||
"action": "COMMENT_ADDED",
|
||
"detail": "Comment body text here",
|
||
"createdAt": "2026-03-30T10:00:00Z",
|
||
"user": { "id": "...", "username": "admin", "displayName": "Admin" }
|
||
}
|
||
]
|
||
```
|
||
|
||
**Action types:**
|
||
|
||
| Action | Detail |
|
||
| ------------------ | -------------------------------------------------------------- |
|
||
| `CREATED` | — |
|
||
| `STATUS_CHANGED` | e.g. `Open → In Progress` |
|
||
| `SEVERITY_CHANGED` | e.g. `SEV 3 → SEV 1` |
|
||
| `ASSIGNEE_CHANGED` | e.g. `Unassigned → Josh` |
|
||
| `REROUTED` | e.g. `OldCat › OldType › OldItem → NewCat › NewType › NewItem` |
|
||
| `TITLE_CHANGED` | New title |
|
||
| `OVERVIEW_CHANGED` | — |
|
||
| `COMMENT_ADDED` | Comment body |
|
||
| `COMMENT_DELETED` | Deleted comment body |
|
||
|
||
---
|
||
|
||
### CTI (Category / Type / Item)
|
||
|
||
#### `GET /api/cti/categories`
|
||
|
||
#### `GET /api/cti/types?categoryId=<id>`
|
||
|
||
#### `GET /api/cti/items?typeId=<id>`
|
||
|
||
Read the CTI hierarchy. Used to resolve IDs when creating/rerouting tickets.
|
||
|
||
**Admin-only write operations:**
|
||
|
||
| Method | Endpoint | Body |
|
||
| -------- | ------------------------- | ---------------------------------------------- |
|
||
| `POST` | `/api/cti/categories` | `{ "name": "string" }` |
|
||
| `PUT` | `/api/cti/categories/:id` | `{ "name": "string" }` |
|
||
| `DELETE` | `/api/cti/categories/:id` | — |
|
||
| `POST` | `/api/cti/types` | `{ "name": "string", "categoryId": "string" }` |
|
||
| `PUT` | `/api/cti/types/:id` | `{ "name": "string" }` |
|
||
| `DELETE` | `/api/cti/types/:id` | — |
|
||
| `POST` | `/api/cti/items` | `{ "name": "string", "typeId": "string" }` |
|
||
| `PUT` | `/api/cti/items/:id` | `{ "name": "string" }` |
|
||
| `DELETE` | `/api/cti/items/:id` | — |
|
||
|
||
Deleting a category cascades to all child types and items.
|
||
|
||
---
|
||
|
||
### Users
|
||
|
||
#### `GET /api/users`
|
||
|
||
List all users (id, username, displayName, email, role). Used to populate assignee dropdowns.
|
||
|
||
**Admin-only operations:**
|
||
|
||
#### `POST /api/users`
|
||
|
||
Create a user.
|
||
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"email": "string",
|
||
"displayName": "string",
|
||
"password": "string (not required for SERVICE role)",
|
||
"role": "ADMIN | AGENT | USER | SERVICE"
|
||
}
|
||
```
|
||
|
||
Service accounts receive an auto-generated API key returned in the response. Copy it immediately — it is not shown again.
|
||
|
||
#### `PATCH /api/users/:id`
|
||
|
||
Update a user.
|
||
|
||
```json
|
||
{
|
||
"displayName": "string",
|
||
"email": "string",
|
||
"password": "string",
|
||
"role": "ADMIN | AGENT | USER | SERVICE",
|
||
"regenerateApiKey": true
|
||
}
|
||
```
|
||
|
||
#### `DELETE /api/users/:id`
|
||
|
||
Delete a user. Cannot delete your own account.
|
||
|
||
---
|
||
|
||
## n8n Integration (Goddard)
|
||
|
||
The `goddard` service account authenticates via API key — no login flow needed.
|
||
|
||
**Create a ticket from n8n:**
|
||
|
||
```
|
||
POST /api/tickets
|
||
X-Api-Key: sk_<goddard api key>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"title": "[Plex] Backup - 2026-03-30T02:00:00",
|
||
"overview": "Automated nightly Plex backup completed.",
|
||
"severity": 5,
|
||
"categoryId": "<TheWrightServer category ID>",
|
||
"typeId": "<Automation type ID>",
|
||
"itemId": "<Backup item ID>",
|
||
"assigneeId": "<Goddard user ID>"
|
||
}
|
||
```
|
||
|
||
CTI IDs can be fetched from:
|
||
|
||
- `GET /api/cti/categories`
|
||
- `GET /api/cti/types?categoryId=<id>`
|
||
- `GET /api/cti/items?typeId=<id>`
|
||
|
||
To regenerate the Goddard API key: Admin → Users → refresh icon next to Goddard.
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
| Variable | Required | Description |
|
||
| ------------------- | -------- | ---------------------------------------------------- |
|
||
| `DATABASE_URL` | Yes | PostgreSQL connection string |
|
||
| `JWT_SECRET` | Yes | Secret for signing JWTs — use `openssl rand -hex 64` |
|
||
| `CLIENT_URL` | Yes | Allowed CORS origin (your domain) |
|
||
| `PORT` | No | Server port (default: `3000`) |
|
||
| `REGISTRY` | Deploy | Container registry hostname |
|
||
| `POSTGRES_PASSWORD` | Deploy | Postgres password |
|
||
| `TAG` | Deploy | Image tag to deploy (default: `latest`) |
|
||
|
||
---
|
||
|
||
## Ticket Severity
|
||
|
||
| Level | Label | Meaning |
|
||
| ----- | ----- | ------------------------------------ |
|
||
| 1 | SEV 1 | Critical — immediate action required |
|
||
| 2 | SEV 2 | High — significant impact |
|
||
| 3 | SEV 3 | Medium — standard priority |
|
||
| 4 | SEV 4 | Low — minor issue |
|
||
| 5 | SEV 5 | Minimal — informational / automated |
|
||
|
||
Tickets are sorted SEV 1 → SEV 5 on the dashboard.
|
||
|
||
---
|
||
|
||
## Ticket Status Lifecycle
|
||
|
||
```
|
||
OPEN → IN_PROGRESS → RESOLVED ──(14 days)──→ CLOSED
|
||
↑
|
||
re-opens reset
|
||
the 14-day timer
|
||
```
|
||
|
||
> CLOSED status can only be set manually by an **Admin**. The auto-close job runs hourly.
|