zee-solution/docs/spec.md

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

  type AuthCredentials struct {
      Email    string `json:"email"`
      Password string `json:"password"`
  }
  

Output

• AuthResponse : Authentication result with token

  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

  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

  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

  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

  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