init

server/docs/API_REFERENCE.md

@@ -0,0 +1,173 @@
+# 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 |