Skip to content

Commit f68bd57

Browse files
h7mlh7ml
committed
feat: 完善用户列表 API 文档
- 添加 status 和 role 筛选参数说明（支持 all 跳过筛选） - 更新响应示例添加 username, department, position, updatedAt 字段 - 同步更新中英文文档
1 parent 111a24b commit f68bd57

2 files changed

Lines changed: 241 additions & 39 deletions

File tree

‎en/guide/api-nestjs.md‎

Lines changed: 120 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -97,22 +97,22 @@ halolight-api-nestjs/
9797

9898
## API Modules
9999

100-
The project includes **12 core business modules** providing **60+ RESTful API endpoints**:
100+
The project includes **12 core business modules** providing **90+ RESTful API endpoints**:
101101

102102
| Module | Endpoints | Description |
103103
|--------|-----------|-------------|
104-
| **Auth** | 5 | User authentication (login, register, refresh token, current user, logout) |
105-
| **Users** | 5 | User management (CRUD, pagination, search, filtering) |
104+
| **Auth** | 7 | User authentication (login, register, refresh token, current user, logout, forgot/reset password) |
105+
| **Users** | 7 | User management (CRUD, pagination, search, filtering, status update, batch delete) |
106106
| **Roles** | 6 | Role management (CRUD + permission assignment) |
107107
| **Permissions** | 4 | Permission management (wildcard support: `users:*`, `*`) |
108-
| **Teams** | 5 | Team management |
109-
| **Documents** | 5 | Document management (tags, folders support) |
110-
| **Files** | 5 | File management |
111-
| **Folders** | 5 | Folder management (tree structure) |
112-
| **Calendar** | 5 | Calendar event management |
113-
| **Notifications** | 5 | Notification management |
114-
| **Messages** | 5 | Message conversations |
115-
| **Dashboard** | 5 | Dashboard statistics |
108+
| **Teams** | 7 | Team management (CRUD, member management) |
109+
| **Documents** | 11 | Document management (CRUD, sharing, moving, tagging, renaming, batch delete) |
110+
| **Files** | 14 | File management (upload, download, storage info, move/copy, favorite, batch delete, etc.) |
111+
| **Folders** | 5 | Folder management (CRUD, tree structure) |
112+
| **Calendar** | 9 | Calendar event management (CRUD, attendee management, reschedule, batch delete, etc.) |
113+
| **Notifications** | 5 | Notification management (list, unread count, mark read, batch read, delete) |
114+
| **Messages** | 5 | Message conversations (conversation list, send message, mark read, delete) |
115+
| **Dashboard** | 9 | Dashboard statistics (overview, visit/sales trends, product/order/activity stats, pie chart, tasks, etc.) |
116116

117117
### Authentication Endpoints
118118

@@ -121,19 +121,112 @@ The project includes **12 core business modules** providing **60+ RESTful API en
121121
| POST | `/api/auth/login` | User login | Public |
122122
| POST | `/api/auth/register` | User registration | Public |
123123
| POST | `/api/auth/refresh` | Refresh token | Public |
124+
| POST | `/api/auth/forgot-password` | Send password reset email | Public |
125+
| POST | `/api/auth/reset-password` | Reset password | Public |
124126
| GET | `/api/auth/me` | Get current user | JWT Required |
125127
| POST | `/api/auth/logout` | User logout | JWT Required |
126128

127129
### User Management Endpoints
128130

129131
| Method | Path | Description | Permission |
130132
|--------|------|-------------|------------|
131-
| GET | `/api/users` | Get user list (pagination, search) | JWT Required |
133+
| GET | `/api/users` | Get user list (pagination, search, status/role filtering) | JWT Required |
132134
| GET | `/api/users/:id` | Get user details | JWT Required |
133135
| POST | `/api/users` | Create user | JWT Required |
134136
| PATCH | `/api/users/:id` | Update user | JWT Required |
137+
| PATCH | `/api/users/:id/status` | Update user status (ACTIVE/INACTIVE/SUSPENDED) | JWT Required |
138+
| POST | `/api/users/batch-delete` | Batch delete users | JWT Required |
135139
| DELETE | `/api/users/:id` | Delete user | JWT Required |
136140

141+
### Complete Endpoint List
142+
143+
> The table below lists all API endpoints for business modules, aligned with actual implementation and Swagger documentation.
144+
145+
#### Document Management (Documents) - 11 Endpoints
146+
147+
| Method | Path | Description | Permission |
148+
|--------|------|-------------|------------|
149+
| GET | `/api/documents` | Document list (pagination, search, filtering) | JWT Required |
150+
| GET | `/api/documents/:id` | Get document details | JWT Required |
151+
| POST | `/api/documents` | Create document | JWT Required |
152+
| PUT | `/api/documents/:id` | Update document content | JWT Required |
153+
| PATCH | `/api/documents/:id/rename` | Rename document | JWT Required |
154+
| POST | `/api/documents/:id/move` | Move to target folder | JWT Required |
155+
| POST | `/api/documents/:id/tags` | Update tags | JWT Required |
156+
| POST | `/api/documents/:id/share` | Share document with users | JWT Required |
157+
| POST | `/api/documents/:id/unshare` | Unshare document | JWT Required |
158+
| POST | `/api/documents/batch-delete` | Batch delete documents | JWT Required |
159+
| DELETE | `/api/documents/:id` | Delete document | JWT Required |
160+
161+
#### File Management (Files) - 14 Endpoints
162+
163+
| Method | Path | Description | Permission |
164+
|--------|------|-------------|------------|
165+
| POST | `/api/files/upload` | Upload file | JWT Required |
166+
| POST | `/api/files/folder` | Create folder | JWT Required |
167+
| GET | `/api/files` | File list (filter by folder/type) | JWT Required |
168+
| GET | `/api/files/storage` | Get storage quota and usage | JWT Required |
169+
| GET | `/api/files/storage-info` | Get storage info (alias) | JWT Required |
170+
| GET | `/api/files/:id` | Get file details | JWT Required |
171+
| GET | `/api/files/:id/download-url` | Generate file download link | JWT Required |
172+
| PATCH | `/api/files/:id/rename` | Rename file | JWT Required |
173+
| POST | `/api/files/:id/move` | Move file to other directory | JWT Required |
174+
| POST | `/api/files/:id/copy` | Copy file | JWT Required |
175+
| PATCH | `/api/files/:id/favorite` | Toggle favorite status | JWT Required |
176+
| POST | `/api/files/:id/share` | Share file | JWT Required |
177+
| POST | `/api/files/batch-delete` | Batch delete files | JWT Required |
178+
| DELETE | `/api/files/:id` | Delete file | JWT Required |
179+
180+
#### Calendar Events (Calendar) - 9 Endpoints
181+
182+
| Method | Path | Description | Permission |
183+
|--------|------|-------------|------------|
184+
| GET | `/api/calendar/events` | Event list (supports date range query) | JWT Required |
185+
| GET | `/api/calendar/events/:id` | Get event details | JWT Required |
186+
| POST | `/api/calendar/events` | Create calendar event | JWT Required |
187+
| PUT | `/api/calendar/events/:id` | Update event information | JWT Required |
188+
| PATCH | `/api/calendar/events/:id/reschedule` | Reschedule event time | JWT Required |
189+
| POST | `/api/calendar/events/:id/attendees` | Add attendees | JWT Required |
190+
| DELETE | `/api/calendar/events/:id/attendees/:attendeeId` | Remove attendee | JWT Required |
191+
| POST | `/api/calendar/events/batch-delete` | Batch delete events | JWT Required |
192+
| DELETE | `/api/calendar/events/:id` | Delete event | JWT Required |
193+
194+
#### Notification Management (Notifications) - 5 Endpoints
195+
196+
| Method | Path | Description | Permission |
197+
|--------|------|-------------|------------|
198+
| GET | `/api/notifications` | Notification list | JWT Required |
199+
| GET | `/api/notifications/unread-count` | Get unread notification count | JWT Required |
200+
| PUT | `/api/notifications/:id/read` | Mark single notification as read | JWT Required |
201+
| PUT | `/api/notifications/read-all` | Mark all as read | JWT Required |
202+
| DELETE | `/api/notifications/:id` | Delete notification | JWT Required |
203+
204+
#### Team Management (Teams) - 7 Endpoints
205+
206+
| Method | Path | Description | Permission |
207+
|--------|------|-------------|------------|
208+
| GET | `/api/teams` | Team list (pagination, search) | JWT Required |
209+
| GET | `/api/teams/:id` | Get team details and members | JWT Required |
210+
| POST | `/api/teams` | Create team | JWT Required |
211+
| PATCH | `/api/teams/:id` | Update team information | JWT Required |
212+
| POST | `/api/teams/:id/members` | Add member to team | JWT Required |
213+
| DELETE | `/api/teams/:id/members/:userId` | Remove member from team | JWT Required |
214+
| DELETE | `/api/teams/:id` | Delete team | JWT Required |
215+
216+
#### Dashboard Statistics (Dashboard) - 9 Endpoints
217+
218+
| Method | Path | Description | Permission |
219+
|--------|------|-------------|------------|
220+
| GET | `/api/dashboard/stats` | Get statistics (users, revenue, orders, etc.) | JWT Required |
221+
| GET | `/api/dashboard/visits` | Get visit trends (7-day data) | JWT Required |
222+
| GET | `/api/dashboard/sales` | Get sales trends (6-month data) | JWT Required |
223+
| GET | `/api/dashboard/products` | Get popular product rankings | JWT Required |
224+
| GET | `/api/dashboard/orders` | Get recent order list | JWT Required |
225+
| GET | `/api/dashboard/activities` | Get recent activity logs | JWT Required |
226+
| GET | `/api/dashboard/pie` | Get pie chart data (category statistics) | JWT Required |
227+
| GET | `/api/dashboard/tasks` | Get task list and statistics | JWT Required |
228+
| GET | `/api/dashboard/overview` | Get system overview (CPU, memory, disk, etc.) | JWT Required |
229+
137230
## Complete API Reference
138231

139232
### 1. Authentication Module (Auth)
@@ -348,9 +441,10 @@ curl -X POST http://localhost:3000/api/auth/logout \
348441

349442
**Query Parameters**:
350443
- `page` (number, optional): Page number, default 1
351-
- `limit` (number, optional): Items per page, default 10
352-
- `search` (string, optional): Search keyword (searches name or email)
353-
- `status` (string, optional): User status filter (ACTIVE | INACTIVE | SUSPENDED)
444+
- `limit` (number, optional): Items per page, default 10, max 100
445+
- `search` (string, optional): Search keyword (searches name, username, or email)
446+
- `status` (string, optional): User status filter (all | ACTIVE | INACTIVE | SUSPENDED), pass `all` or omit for all
447+
- `role` (string, optional): Filter by role name (all | admin | user | ...), pass `all` or omit for all
354448

355449
**Success Response** (200):
356450
```json
@@ -359,11 +453,14 @@ curl -X POST http://localhost:3000/api/auth/logout \
359453
{
360454
"id": "clx1234567890",
361455
"email": "admin@halolight.h7ml.cn",
456+
"username": "admin",
362457
"name": "Admin User",
363458
"avatar": "https://avatar.example.com/admin.jpg",
364-
"phone": "+86 138****8888",
365459
"status": "ACTIVE",
366-
"createdAt": "2024-01-01T00:00:00.000Z"
460+
"department": "Development",
461+
"position": "Senior Engineer",
462+
"createdAt": "2024-01-01T00:00:00.000Z",
463+
"updatedAt": "2024-12-04T12:00:00.000Z"
367464
}
368465
],
369466
"meta": {
@@ -381,8 +478,12 @@ curl -X POST http://localhost:3000/api/auth/logout \
381478
curl -X GET "http://localhost:3000/api/users?page=1&limit=10" \
382479
-H "Authorization: Bearer YOUR_TOKEN"
383480

384-
# Search users
385-
curl -X GET "http://localhost:3000/api/users?search=admin&status=ACTIVE" \
481+
# Search users with status and role filtering
482+
curl -X GET "http://localhost:3000/api/users?search=admin&status=ACTIVE&role=admin" \
483+
-H "Authorization: Bearer YOUR_TOKEN"
484+
485+
# Use all to skip filtering
486+
curl -X GET "http://localhost:3000/api/users?status=all&role=all" \
386487
-H "Authorization: Bearer YOUR_TOKEN"
387488
```
388489

0 commit comments

Comments
 (0)