161 lines
5.0 KiB
Markdown
161 lines
5.0 KiB
Markdown
# GUIDE
|
|
This document provides detailed functional specifications for key components. It outlines the purpose, inputs, outputs, logic, and error handling for specific functions within designated files. Additionally, it visualizes and explains the overall sequence of operations for major user flows or processes using sequence diagrams. This serves as a technical reference for understanding the implementation details and interactions within the application.
|
|
# FORMAT
|
|
## Title: [Application/Website Name]
|
|
app_ver: [app_ver]
|
|
doc_ver: [doc_ver]
|
|
## Specifications
|
|
### [Numerical order].[File Name]
|
|
### [Numerical order].[Function Name]
|
|
#### Input
|
|
[Parameters] : [Description and format]
|
|
#### Output
|
|
[Return Value/Object] : [Description and format]
|
|
#### Description
|
|
[Brief description of the function's purpose within the file]
|
|
#### Logic
|
|
[Detailed description of the processing logic; consider using numbered steps or pseudocode for clarity. Description of any side effects if any (e.g., database updates, external API calls)]
|
|
#### Error Handling:
|
|
[Description of how errors are detected and handled]
|
|
|
|
---
|
|
# CONTENT
|
|
|
|
## Title: ZEE Quiz Application
|
|
app_ver: 1.0.0
|
|
doc_ver: A1
|
|
|
|
## Specifications
|
|
|
|
### 1. auth/service.go
|
|
### 1.1. AuthenticateUser
|
|
#### Input
|
|
- credentials : AuthCredentials
|
|
```go
|
|
type AuthCredentials struct {
|
|
Email string `json:"email"`
|
|
Password string `json:"password"`
|
|
}
|
|
```
|
|
#### Output
|
|
- AuthResponse : Authentication result with token
|
|
```go
|
|
type AuthResponse struct {
|
|
Token string `json:"token"`
|
|
RefreshToken string `json:"refresh_token"`
|
|
ExpiresAt time.Time `json:"expires_at"`
|
|
User UserInfo `json:"user"`
|
|
}
|
|
```
|
|
#### Description
|
|
Authenticate user credentials and generate JWT token for authorized access
|
|
#### Logic
|
|
1. Validate email format and password length
|
|
2. Hash password using bcrypt
|
|
3. Query user from database by email
|
|
4. Compare password hashes
|
|
5. Generate JWT token with user claims
|
|
6. Create refresh token and store in Redis
|
|
7. Update last login timestamp
|
|
8. Return tokens and user info
|
|
#### Error Handling
|
|
- Invalid email format: Return 400 Bad Request
|
|
- User not found: Return 401 Unauthorized
|
|
- Invalid password: Return 401 Unauthorized
|
|
- Database error: Return 500 Internal Server Error
|
|
|
|
### 2. quiz/service.go
|
|
### 2.1. CreateQuiz
|
|
#### Input
|
|
- quizData : QuizCreationRequest
|
|
```go
|
|
type QuizCreationRequest struct {
|
|
Title string `json:"title"`
|
|
Description string `json:"description"`
|
|
TimeLimit int `json:"time_limit"`
|
|
Questions []QuestionDTO `json:"questions"`
|
|
}
|
|
```
|
|
#### Output
|
|
- QuizResponse : Created quiz details
|
|
```go
|
|
type QuizResponse struct {
|
|
ID string `json:"id"`
|
|
Title string `json:"title"`
|
|
Description string `json:"description"`
|
|
CreatedAt time.Time `json:"created_at"`
|
|
Questions int `json:"question_count"`
|
|
}
|
|
```
|
|
#### Description
|
|
Create a new quiz with questions and answers in the database
|
|
#### Logic
|
|
1. Validate quiz data (title, time limit, questions)
|
|
2. Begin database transaction
|
|
3. Create quiz record
|
|
4. For each question:
|
|
- Create question record
|
|
- Create answer options
|
|
- Link correct answer
|
|
5. Commit transaction
|
|
6. Return quiz details
|
|
#### Error Handling
|
|
- Invalid quiz data: Return 400 Bad Request
|
|
- Transaction failure: Rollback and return 500
|
|
- Duplicate quiz title: Return 409 Conflict
|
|
|
|
### 3. quiz/service.go
|
|
### 3.1. SubmitQuizAttempt
|
|
#### Input
|
|
- attemptData : QuizAttemptSubmission
|
|
```go
|
|
type QuizAttemptSubmission struct {
|
|
QuizID string `json:"quiz_id"`
|
|
UserID string `json:"user_id"`
|
|
StartedAt time.Time `json:"started_at"`
|
|
Answers map[string]string `json:"answers"`
|
|
TimeSpent int `json:"time_spent"`
|
|
}
|
|
```
|
|
#### Output
|
|
- AttemptResult : Quiz attempt results
|
|
```go
|
|
type AttemptResult struct {
|
|
Score float64 `json:"score"`
|
|
CorrectCount int `json:"correct_count"`
|
|
TotalCount int `json:"total_count"`
|
|
TimeTaken int `json:"time_taken"`
|
|
CompletedAt time.Time `json:"completed_at"`
|
|
Feedback []Answer `json:"feedback"`
|
|
}
|
|
```
|
|
#### Description
|
|
Process a quiz attempt submission and calculate results
|
|
#### Logic
|
|
1. Validate attempt data
|
|
2. Check time limit compliance
|
|
3. Load correct answers from database
|
|
4. Calculate score:
|
|
- Compare submitted answers with correct ones
|
|
- Apply scoring rules
|
|
- Calculate percentage
|
|
5. Store attempt results
|
|
6. Generate detailed feedback
|
|
7. Update user statistics
|
|
#### Error Handling
|
|
- Invalid quiz/user ID: Return 400 Bad Request
|
|
- Time limit exceeded: Return 400 Bad Request
|
|
- Quiz not found: Return 404 Not Found
|
|
- Database error: Return 500 Internal Server Error
|
|
|
|
---
|
|
*Last Updated: 2025-06-06*
|
|
*Next Review: 2025-07-01*## Overall Flow:
|
|
### [Numerical order].[Flow Name (e.g., Goal Creation Flow)]
|
|
```
|
|
[mermaid sequenceDiagram]
|
|
```
|
|
[Explanation of the diagram]
|
|
|
|
---
|
|
# CONTENT |