# ToolsShow API Reference

Base URL: `/api/v1`

All JSON responses (except binary download stream) use the wrapper:

```json
{
  "code": 0,
  "message": "ok",
  "data": {},
  "traceId": "uuid",
  "timestamp": "2026-03-26T10:10:00.000Z"
}
```

## Public APIs

| Method | Path | Description |
|---|---|---|
| GET | `/health` | Liveness/readiness check |
| GET | `/tools` | Query tools list (query/category/sort/page/pageSize) |
| GET | `/tools/:id` | Tool detail |
| POST | `/tools/:id/launch` | Unified launch (web/download) |
| GET | `/downloads/:ticket` | Consume ticket and stream artifact |
| GET | `/categories` | Category list with tool count |
| GET | `/keywords/hot` | Hot keyword list |
| GET | `/overview` | KPI overview |

### `GET /tools` query params

| Param | Type | Required | Default |
|---|---|---|---|
| `query` | string | No | - |
| `category` | string | No | `all` |
| `sortBy` | `popular \| latest \| rating \| name` | No | `latest` |
| `page` | number | No | `1` |
| `pageSize` | number (1-50) | No | `6` |

### `POST /tools/:id/launch` body

```json
{
  "channel": "official",
  "clientVersion": "web-1.0.0"
}
```

Web mode response:

```json
{
  "mode": "web",
  "actionUrl": "https://example.com",
  "openIn": "new_tab"
}
```

Download mode response:

```json
{
  "mode": "download",
  "ticket": "dl_tk_xxx",
  "expiresInSec": 120,
  "actionUrl": "/api/v1/downloads/dl_tk_xxx"
}
```

## Admin Auth APIs

Auth header for protected admin APIs:

```text
Authorization: Bearer <accessToken>
```

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | `/admin/auth/login` | No | Admin login |
| POST | `/admin/auth/refresh` | No | Refresh tokens |
| POST | `/admin/auth/logout` | Yes | Admin logout |
| GET | `/admin/auth/me` | Yes | Current admin profile |

Default seeded admin account:

```text
username: admin
password: admin123456
```

## Admin Tool APIs

| Method | Path | Description |
|---|---|---|
| GET | `/admin/tools` | Query tools |
| POST | `/admin/tools` | Create tool |
| GET | `/admin/tools/:id` | Tool detail |
| PATCH | `/admin/tools/:id` | Update tool |
| PATCH | `/admin/tools/:id/status` | Update tool status |
| PATCH | `/admin/tools/:id/access-mode` | Switch access mode |
| DELETE | `/admin/tools/:id` | Soft delete tool |

### Create/Update tool payload core fields

```json
{
  "name": "Tool Name",
  "categoryId": "cat_dev",
  "description": "Tool description",
  "rating": 4.5,
  "tags": ["tag_hot", "tag_free"],
  "features": ["Feature A", "Feature B"],
  "accessMode": "web",
  "openUrl": "https://example.com",
  "openInNewTab": true,
  "status": "draft"
}
```

## Admin Artifact APIs

| Method | Path | Description |
|---|---|---|
| POST | `/admin/tools/:id/artifacts` | Upload artifact (`multipart/form-data`) |
| GET | `/admin/tools/:id/artifacts` | List artifacts |
| PATCH | `/admin/tools/:id/artifacts/:artifactId/latest` | Set latest artifact |
| PATCH | `/admin/tools/:id/artifacts/:artifactId/status` | Update artifact status |
| DELETE | `/admin/tools/:id/artifacts/:artifactId` | Soft delete artifact metadata |

### Upload form fields

| Field | Type | Required |
|---|---|---|
| `file` | binary | Yes |
| `version` | string | Yes |
| `releaseNotes` | string | No |
| `isLatest` | boolean | No (default `true`) |

## Admin Audit APIs

| Method | Path | Description |
|---|---|---|
| GET | `/admin/audit-logs` | Query admin audit logs |

Query params:

| Param | Type | Required |
|---|---|---|
| `action` | string | No |
| `resourceType` | string | No |
| `adminUserId` | string | No |
| `page` | number | No |
| `pageSize` | number | No |

## Error Codes

| Code | Meaning |
|---|---|
| `1001` | validation failed |
| `1002` | unauthorized |
| `1003` | forbidden |
| `1004` | resource not found |
| `1005` | conflict |
| `1010` | invalid credentials |
| `1011` | token invalid/expired |
| `1201` | GitLab upload failed |
| `1202` | GitLab download failed |
| `1203` | artifact not available |
| `1204` | download ticket invalid/expired |
| `1210` | tool access mode mismatch |
| `1211` | web open URL not configured |
| `1500` | internal server error |