genome2025/backend/src/help/help.controller.ts

import { Controller, Get, Post, Put, Delete, Body, Param, Query, Req } from '@nestjs/common';
import { HelpService } from './help.service';
import { CreateHelpDto } from './dto/create-help.dto';
import { UpdateHelpDto } from './dto/update-help.dto';
import { FilterHelpDto } from './dto/filter-help.dto';
import { Request } from 'express';

/**
 * Help Controller
 *
 * @description
 * 도움말/툴팁 시스템 API 엔드포인트를 제공합니다.
 *
 * 주요 기능:
 * - 도움말 CRUD (생성, 조회, 수정, 삭제)
 * - 카테고리별 조회 (SNP/GENOME/MPT)
 * - 대상명별 조회 (PLAG1, 도체중 등)
 * - 툴팁 데이터 제공
 *
 * @export
 * @class HelpController
 */
@Controller('help')
export class HelpController {
  constructor(private readonly helpService: HelpService) {}

  /**
   * POST /help - 도움말 생성 (관리자)
   *
   * @description
   * 새로운 도움말을 생성합니다.
   *
   * @example
   * // POST /help
   * {
   *   "helpCtgry": "SNP",
   *   "targetNm": "PLAG1",
   *   "helpTitle": "PLAG1 유전자란?",
   *   "helpShort": "체고 및 성장 관련 유전자",
   *   "helpFull": "PLAG1은 소의 체고와 성장에 영향을 미치는 주요 유전자입니다...",
   *   "displayOrder": 1,
   *   "useYn": "Y"
   * }
   *
   * @param {CreateHelpDto} createHelpDto - 생성할 도움말 데이터
   * @param {Request} req - Express Request 객체
   * @returns {Promise<HelpModel>}
   */
  @Post()
  async create(@Body() createHelpDto: CreateHelpDto, @Req() req: Request) {
    const userId = (req as any).user?.userId || 'system';
    const ip = req.ip || req.socket.remoteAddress || 'unknown';
    return await this.helpService.create(createHelpDto, userId, ip);
  }

  /**
   * GET /help - 전체 도움말 목록 조회
   *
   * @description
   * 전체 도움말 목록을 조회합니다. 필터 조건을 통해 검색 가능합니다.
   *
   * @example
   * // GET /help
   * // GET /help?helpCtgry=SNP
   * // GET /help?useYn=Y
   * // GET /help?targetNm=PLAG1
   *
   * @param {FilterHelpDto} filterDto - 필터 조건 (선택)
   * @returns {Promise<HelpModel[]>}
   */
  @Get()
  async findAll(@Query() filterDto: FilterHelpDto) {
    return await this.helpService.findAll(filterDto);
  }

  /**
   * GET /help/category/:category - 카테고리별 도움말 조회
   *
   * @description
   * 특정 카테고리(SNP/GENOME/MPT)의 모든 도움말을 조회합니다.
   *
   * @example
   * // GET /help/category/SNP
   * // GET /help/category/GENOME
   * // GET /help/category/MPT
   *
   * @param {string} category - 카테고리 (SNP/GENOME/MPT)
   * @returns {Promise<HelpModel[]>}
   */
  @Get('category/:category')
  async findByCategory(@Param('category') category: string) {
    return await this.helpService.findByCategory(category);
  }

  /**
   * GET /help/:category/:targetNm - 특정 대상의 도움말 조회
   *
   * @description
   * 특정 카테고리와 대상명에 해당하는 도움말을 조회합니다.
   * 툴팁이나 사이드패널에서 사용됩니다.
   *
   * @example
   * // GET /help/SNP/PLAG1
   * // GET /help/GENOME/도체중
   * // GET /help/MPT/혈당
   *
   * @param {string} category - 카테고리 (SNP/GENOME/MPT)
   * @param {string} targetNm - 대상명 (PLAG1, 도체중 등)
   * @returns {Promise<HelpModel>}
   */
  @Get(':category/:targetNm')
  async findByTarget(
    @Param('category') category: string,
    @Param('targetNm') targetNm: string,
  ) {
    return await this.helpService.findByTarget(category, targetNm);
  }

  /**
   * GET /help/id/:id - 도움말 단건 조회
   *
   * @description
   * 도움말 번호로 단건을 조회합니다.
   *
   * @example
   * // GET /help/id/1
   *
   * @param {number} id - 도움말 번호
   * @returns {Promise<HelpModel>}
   */
  @Get('id/:id')
  async findOne(@Param('id') id: number) {
    return await this.helpService.findOne(id);
  }

  /**
   * PUT /help/:id - 도움말 수정 (관리자)
   *
   * @description
   * 기존 도움말을 수정합니다.
   *
   * @example
   * // PUT /help/1
   * {
   *   "helpTitle": "수정된 제목",
   *   "helpShort": "수정된 짧은 설명",
   *   "displayOrder": 2
   * }
   *
   * @param {number} id - 도움말 번호
   * @param {UpdateHelpDto} updateHelpDto - 수정할 데이터
   * @param {Request} req - Express Request 객체
   * @returns {Promise<HelpModel>}
   */
  @Put(':id')
  async update(
    @Param('id') id: number,
    @Body() updateHelpDto: UpdateHelpDto,
    @Req() req: Request,
  ) {
    const userId = (req as any).user?.userId || 'system';
    const ip = req.ip || req.socket.remoteAddress || 'unknown';
    return await this.helpService.update(id, updateHelpDto, userId, ip);
  }

  /**
   * DELETE /help/:id - 도움말 삭제 (관리자)
   *
   * @description
   * 도움말을 삭제합니다 (soft delete - useYn = 'N').
   *
   * @example
   * // DELETE /help/1
   *
   * @param {number} id - 도움말 번호
   * @param {Request} req - Express Request 객체
   * @returns {Promise<void>}
   */
  @Delete(':id')
  async remove(@Param('id') id: number, @Req() req: Request) {
    const userId = (req as any).user?.userId || 'system';
    const ip = req.ip || req.socket.remoteAddress || 'unknown';
    return await this.helpService.remove(id, userId, ip);
  }
}