This commit is contained in:
silverpro89
@@ -4,334 +4,347 @@ const vocabController = require('../controllers/vocabController');
|
||||
const { authenticateToken } = require('../middleware/auth');
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: Vocabulary
|
||||
* description: Vocabulary management system for curriculum-based language learning
|
||||
*/
|
||||
* ============================================
|
||||
* POST /api/vocabs
|
||||
* ============================================
|
||||
* Tạo một vocab entry mới
|
||||
*
|
||||
* INPUT:
|
||||
* {
|
||||
* text: String (required) - từ thực tế (wash, washes, washing, ate, eaten...)
|
||||
* ipa: String - phiên âm IPA (ví dụ: /wɒʃ/)
|
||||
* base_word: String (required) - từ gốc để nhóm lại (wash, eat...)
|
||||
* form_key: JSON - loại biến thể (V1, V2, V3, V_ing, Noun_Form...), mặc định 'base'
|
||||
* vi: String - nghĩa tiếng Việt
|
||||
* category: String - category của từ (Action Verbs, Nouns, etc.)
|
||||
* topic: String - chủ đề (Food, Travel, Education, etc.)
|
||||
* image_small: JSON Array - mảng URLs của hình ảnh nhỏ
|
||||
* image_square: JSON Array - mảng URLs của hình ảnh vuông
|
||||
* image_normal: JSON Array - mảng URLs của hình ảnh bình thường
|
||||
* audio: JSON Array - mảng URLs của audio files
|
||||
* example_sentences: JSON - các câu ví dụ
|
||||
* tags: JSON Array - các tags để phân loại
|
||||
* syntax: JSON - vai trò cú pháp
|
||||
* semantics: JSON - ràng buộc ngữ nghĩa
|
||||
* constraints: JSON - ràng buộc ngữ pháp
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Vocab object đã tạo (bao gồm vocab_id, created_at, updated_at)
|
||||
* }
|
||||
**/
|
||||
|
||||
router.post('/', vocabController.createVocab);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab:
|
||||
* post:
|
||||
* summary: Create a new vocabulary entry
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/VocabComplete'
|
||||
* example:
|
||||
* vocab_code: "vocab-001-eat"
|
||||
* base_word: "eat"
|
||||
* translation: "ăn"
|
||||
* attributes:
|
||||
* difficulty_score: 1
|
||||
* category: "Action Verbs"
|
||||
* images:
|
||||
* - "https://cdn.sena.tech/img/eat-main.png"
|
||||
* - "https://cdn.sena.tech/img/eat-context.jpg"
|
||||
* tags: ["daily-routine", "verb"]
|
||||
* mappings:
|
||||
* - book_id: "global-success-1"
|
||||
* grade: 1
|
||||
* unit: 2
|
||||
* lesson: 3
|
||||
* form_key: "v1"
|
||||
* - book_id: "global-success-2"
|
||||
* grade: 2
|
||||
* unit: 5
|
||||
* lesson: 1
|
||||
* form_key: "v_ing"
|
||||
* forms:
|
||||
* v1:
|
||||
* text: "eat"
|
||||
* phonetic: "/iːt/"
|
||||
* audio: "https://cdn.sena.tech/audio/eat_v1.mp3"
|
||||
* min_grade: 1
|
||||
* v_s_es:
|
||||
* text: "eats"
|
||||
* phonetic: "/iːts/"
|
||||
* audio: "https://cdn.sena.tech/audio/eats_s.mp3"
|
||||
* min_grade: 2
|
||||
* v_ing:
|
||||
* text: "eating"
|
||||
* phonetic: "/ˈiː.tɪŋ/"
|
||||
* audio: "https://cdn.sena.tech/audio/eating_ing.mp3"
|
||||
* min_grade: 2
|
||||
* v2:
|
||||
* text: "ate"
|
||||
* phonetic: "/et/"
|
||||
* audio: "https://cdn.sena.tech/audio/ate_v2.mp3"
|
||||
* min_grade: 3
|
||||
* relations:
|
||||
* synonyms: ["consume", "dine"]
|
||||
* antonyms: ["fast", "starve"]
|
||||
* syntax:
|
||||
* is_subject: false
|
||||
* is_verb: true
|
||||
* is_object: false
|
||||
* is_be: false
|
||||
* is_adj: false
|
||||
* verb_type: "transitive"
|
||||
* semantics:
|
||||
* can_be_subject_type: ["human", "animal"]
|
||||
* can_take_object_type: ["food", "plant"]
|
||||
* word_type: "action"
|
||||
* constraints:
|
||||
* requires_object: true
|
||||
* semantic_object_types: ["food", "plant"]
|
||||
* responses:
|
||||
* 201:
|
||||
* description: Vocabulary created successfully
|
||||
* 400:
|
||||
* description: Invalid input
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.post('/', authenticateToken, vocabController.createVocab);
|
||||
* ============================================
|
||||
* POST /api/vocabs/bulk
|
||||
* ============================================
|
||||
* Tạo nhiều vocab entries cùng lúc
|
||||
*
|
||||
* INPUT:
|
||||
* {
|
||||
* vocabs: Array of Vocab objects - mỗi object phải có text và base_word
|
||||
* [
|
||||
* {
|
||||
* text: String (required),
|
||||
* base_word: String (required),
|
||||
* ipa: String,
|
||||
* vi: String,
|
||||
* ...
|
||||
* },
|
||||
* ...
|
||||
* ]
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of created Vocab objects,
|
||||
* count: Number - số lượng vocab đã tạo
|
||||
* }
|
||||
**/
|
||||
router.post('/bulk', vocabController.bulkCreateVocabs);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab:
|
||||
* get:
|
||||
* summary: Get all vocabulary entries with pagination and filters
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: page
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 1
|
||||
* description: Page number
|
||||
* - in: query
|
||||
* name: limit
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 20
|
||||
* description: Items per page
|
||||
* - in: query
|
||||
* name: category
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Filter by category (e.g., "Action Verbs")
|
||||
* - in: query
|
||||
* name: grade
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Filter by grade level
|
||||
* - in: query
|
||||
* name: book_id
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Filter by book ID (e.g., "global-success-1")
|
||||
* - in: query
|
||||
* name: difficulty_min
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Minimum difficulty score
|
||||
* - in: query
|
||||
* name: difficulty_max
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Maximum difficulty score
|
||||
* - in: query
|
||||
* name: search
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Search in base_word, translation, or vocab_code
|
||||
* - in: query
|
||||
* name: include_relations
|
||||
* schema:
|
||||
* type: string
|
||||
* enum: ['true', 'false']
|
||||
* default: 'false'
|
||||
* description: Include synonyms/antonyms in response
|
||||
* responses:
|
||||
* 200:
|
||||
* description: List of vocabularies
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
* ============================================
|
||||
* POST /api/vocabs/search
|
||||
* ============================================
|
||||
* Tìm kiếm vocab nâng cao với nhiều filter
|
||||
*
|
||||
* INPUT:
|
||||
* {
|
||||
* topic: String (optional) - chủ đề (exact match)
|
||||
* category: String (optional) - loại từ (exact match)
|
||||
* base_word: String (optional) - từ gốc (partial match với LIKE)
|
||||
* form_key: JSON (optional) - loại biến thể (V1, V2, V3, V_ing, Noun_Form, etc.)
|
||||
* text: String (optional) - từ thực tế (partial match với LIKE)
|
||||
* vi: String (optional) - nghĩa tiếng Việt (partial match với LIKE)
|
||||
*
|
||||
* v_type: Boolean (optional) - tìm các biến thể khác của cùng một base_word
|
||||
* base_word_filter: String (optional) - base_word cụ thể (dùng khi v_type=true)
|
||||
*
|
||||
* shuffle_pos: Object (optional) - tìm từ thay thế dựa trên syntax
|
||||
* {
|
||||
* is_subject: Boolean,
|
||||
* is_verb: Boolean,
|
||||
* is_object: Boolean,
|
||||
* is_be: Boolean,
|
||||
* is_adj: Boolean,
|
||||
* is_adv: Boolean,
|
||||
* is_article: Boolean
|
||||
* }
|
||||
*
|
||||
* page: Number - trang hiện tại (mặc định: 1)
|
||||
* limit: Number - số items mỗi trang (mặc định: 100)
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of Vocab objects,
|
||||
* pagination: {
|
||||
* total: Number,
|
||||
* page: Number,
|
||||
* limit: Number,
|
||||
* totalPages: Number
|
||||
* }
|
||||
* }
|
||||
**/
|
||||
router.post('/search', vocabController.searchVocabs);
|
||||
|
||||
/**
|
||||
* ============================================
|
||||
* GET /api/vocabs
|
||||
* ============================================
|
||||
* Lấy danh sách tất cả vocab với phân trang và filter
|
||||
*
|
||||
* INPUT (Query Parameters):
|
||||
* {
|
||||
* page: Number - trang hiện tại (mặc định: 1)
|
||||
* limit: Number - số items mỗi trang (mặc định: 20)
|
||||
* category: String - lọc theo category
|
||||
* topic: String - lọc theo topic
|
||||
* base_word: String - lọc theo base_word chính xác
|
||||
* text: String - lọc theo text chính xác
|
||||
* search: String - tìm kiếm trong text, base_word và vi
|
||||
* is_active: Boolean - lọc theo trạng thái active (mặc định: true)
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of Vocab objects,
|
||||
* pagination: {
|
||||
* total: Number,
|
||||
* page: Number,
|
||||
* limit: Number,
|
||||
* totalPages: Number
|
||||
* }
|
||||
* }
|
||||
*
|
||||
**/
|
||||
router.get('/', vocabController.getAllVocabs);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/curriculum:
|
||||
* get:
|
||||
* summary: Get vocabularies by curriculum mapping
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: book_id
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Book ID (e.g., "global-success-1")
|
||||
* - in: query
|
||||
* name: grade
|
||||
* required: false
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Grade level
|
||||
* - in: query
|
||||
* name: unit
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Unit number
|
||||
* - in: query
|
||||
* name: lesson
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: Lesson number
|
||||
* responses:
|
||||
* 200:
|
||||
* description: List of vocabularies for the specified curriculum
|
||||
* 400:
|
||||
* description: Invalid parameters
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.get('/curriculum', authenticateToken, vocabController.getVocabsByCurriculum);
|
||||
* ============================================
|
||||
* GET /api/vocabs/stats/overview
|
||||
* ============================================
|
||||
* Lấy thống kê tổng quan về vocab
|
||||
*
|
||||
* INPUT: Không có
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: {
|
||||
* total: {
|
||||
* active: Number,
|
||||
* inactive: Number,
|
||||
* all: Number
|
||||
* },
|
||||
* unique_base_words: Number,
|
||||
* by_category: Array [{category: String, count: Number}],
|
||||
* by_topic: Array [{topic: String, count: Number}]
|
||||
* }
|
||||
* }
|
||||
**/
|
||||
router.get('/stats/overview', vocabController.getVocabStats);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/guide:
|
||||
* get:
|
||||
* summary: Get comprehensive guide for AI to create vocabulary entries
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Complete guide with rules, examples, and data structures
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* guide_version:
|
||||
* type: string
|
||||
* last_updated:
|
||||
* type: string
|
||||
* data_structure:
|
||||
* type: object
|
||||
* rules:
|
||||
* type: object
|
||||
* examples:
|
||||
* type: object
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.get('/guide', authenticateToken, vocabController.getVocabGuide);
|
||||
* ============================================
|
||||
* GET /api/vocabs/meta/categories
|
||||
* ============================================
|
||||
* Lấy danh sách tất cả categories
|
||||
*
|
||||
* INPUT: Không có
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of String - danh sách categories,
|
||||
* count: Number - số lượng categories
|
||||
* }
|
||||
**/
|
||||
router.get('/meta/categories', vocabController.getAllCategories);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/stats:
|
||||
* get:
|
||||
* summary: Get vocabulary statistics
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Vocabulary statistics
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.get('/stats', authenticateToken, vocabController.getVocabStats);
|
||||
* ============================================
|
||||
* GET /api/vocabs/meta/topics
|
||||
* ============================================
|
||||
* Lấy danh sách tất cả topics
|
||||
*
|
||||
* INPUT: Không có
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of String - danh sách topics,
|
||||
* count: Number - số lượng topics
|
||||
* }
|
||||
**/
|
||||
router.get('/meta/topics', vocabController.getAllTopics);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/{id}:
|
||||
* get:
|
||||
* summary: Get vocabulary by ID or code
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Vocabulary ID (numeric) or vocab_code (string)
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Vocabulary details
|
||||
* 404:
|
||||
* description: Vocabulary not found
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.get('/:id', authenticateToken, vocabController.getVocabById);
|
||||
* ============================================
|
||||
* GET /api/vocabs/missing/ipa
|
||||
* ============================================
|
||||
* Lấy tất cả các vocab chưa có IPA
|
||||
*
|
||||
* INPUT (Query Parameters):
|
||||
* {
|
||||
* page: Number - trang hiện tại (mặc định: 1),
|
||||
* limit: Number - số items mỗi trang (mặc định: 50)
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of Vocab objects - các vocab chưa có IPA,
|
||||
* pagination: {
|
||||
* total: Number,
|
||||
* page: Number,
|
||||
* limit: Number,
|
||||
* totalPages: Number
|
||||
* }
|
||||
* }
|
||||
**/
|
||||
router.get('/missing/ipa', vocabController.getVocabsWithoutIpa);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/{id}:
|
||||
* put:
|
||||
* summary: Update vocabulary entry
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Vocabulary ID (numeric) or vocab_code (string)
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/VocabComplete'
|
||||
* example:
|
||||
* translation: "ăn uống"
|
||||
* attributes:
|
||||
* difficulty_score: 2
|
||||
* tags: ["daily-routine", "verb", "food"]
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Vocabulary updated successfully
|
||||
* 404:
|
||||
* description: Vocabulary not found
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.put('/:id', authenticateToken, vocabController.updateVocab);
|
||||
* ============================================
|
||||
* GET /api/vocabs/missing/images
|
||||
* ============================================
|
||||
* Lấy tất cả các vocab chưa đủ hình ảnh
|
||||
*
|
||||
* INPUT (Query Parameters):
|
||||
* {
|
||||
* page: Number - trang hiện tại (mặc định: 1),
|
||||
* limit: Number - số items mỗi trang (mặc định: 50)
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Array of Vocab objects - các vocab chưa đủ hình ảnh,
|
||||
* pagination: {
|
||||
* total: Number,
|
||||
* page: Number,
|
||||
* limit: Number,
|
||||
* totalPages: Number
|
||||
* }
|
||||
* }
|
||||
**/
|
||||
router.get('/missing/images', vocabController.getVocabsWithoutImages);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/vocab/{id}:
|
||||
* delete:
|
||||
* summary: Delete vocabulary (soft delete)
|
||||
* tags: [Vocabulary]
|
||||
* security:
|
||||
* - bearerAuth: []
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: string
|
||||
* description: Vocabulary ID (numeric) or vocab_code (string)
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Vocabulary deleted successfully
|
||||
* 404:
|
||||
* description: Vocabulary not found
|
||||
* 500:
|
||||
* description: Server error
|
||||
*/
|
||||
router.delete('/:id', authenticateToken, vocabController.deleteVocab);
|
||||
* ============================================
|
||||
* GET /api/vocabs/:id
|
||||
* ============================================
|
||||
* Lấy chi tiết một vocab theo ID
|
||||
*
|
||||
* INPUT (URL Parameter):
|
||||
* {
|
||||
* id: UUID - vocab_id của vocab cần lấy
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Vocab object với đầy đủ thông tin
|
||||
* }
|
||||
**/
|
||||
router.get('/:id', vocabController.getVocabById);
|
||||
|
||||
/**
|
||||
* ============================================
|
||||
* PUT /api/vocabs/:id
|
||||
* ============================================
|
||||
* Cập nhật thông tin vocab
|
||||
*
|
||||
* INPUT (URL Parameter + Body):
|
||||
* {
|
||||
* id: UUID - vocab_id cần update
|
||||
* Body: Object - các trường cần update (có thể update một hoặc nhiều trường)
|
||||
* {
|
||||
* text: String,
|
||||
* ipa: String,
|
||||
* base_word: String,
|
||||
* form_key: JSON,
|
||||
* vi: String,
|
||||
* category: String,
|
||||
* topic: String,
|
||||
* image_small: JSON Array,
|
||||
* image_square: JSON Array,
|
||||
* image_normal: JSON Array,
|
||||
* audio: JSON Array,
|
||||
* example_sentences: JSON,
|
||||
* tags: JSON Array,
|
||||
* syntax: JSON,
|
||||
* semantics: JSON,
|
||||
* constraints: JSON,
|
||||
* is_active: Boolean
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String,
|
||||
* data: Updated Vocab object
|
||||
* }
|
||||
* **/
|
||||
router.put('/:id', vocabController.updateVocab);
|
||||
|
||||
/**
|
||||
* ============================================
|
||||
* DELETE /api/vocabs/:id
|
||||
* ============================================
|
||||
* Xóa mềm vocab (set is_active = false)
|
||||
*
|
||||
* INPUT (URL Parameter):
|
||||
* {
|
||||
* id: UUID - vocab_id cần xóa
|
||||
* }
|
||||
*
|
||||
* OUTPUT:
|
||||
* {
|
||||
* success: Boolean,
|
||||
* message: String
|
||||
* }
|
||||
**/
|
||||
router.delete('/:id', vocabController.deleteVocab);
|
||||
|
||||
module.exports = router;
|
||||
|
||||
Reference in New Issue
Block a user