"""FAQ 조회 + 승인(검증 상태 전이). COPY 잡이 faqs 를 UNVERIFIED 로 쌓아두지만, 절대규칙 1 때문에 확인 전에는 사이트에 나가지 못한다 (snapshot 이 PUBLISHABLE 만 싣는다). 즉 **승인 창구가 없으면 FAQPage JSON-LD 는 영영 안 나간다** — 이 서비스가 그 창구다. fact 와 같은 규칙을 따른다(다른 표를 쓰면 두 도메인의 승인 의미가 갈라진다): 1. 회사 스코프는 사업장 조회로 강제 — 남의 회사 place 의 FAQ 는 보이지도 만져지지도 않는다 2. 상태 전이는 FACT_STATUS_TRANSITIONS 에 있는 것만 (FACT_INVALID_TRANSITION) 3. CORRECTED 는 잠긴 종착 상태(LOCKED_FACT_STATUSES) — 재생성이 사장님 문구를 덮어쓰지 못한다 4. 사람이 직접 쓴 FAQ 는 바로 노출값이다 — 사람이 곧 출처이자 책임 주체다 """ import uuid from fastapi import Depends from common.database.db_session_manager import DB_SESSION_MNG from common.database.model.models import faqs, places from common.enums import ( CANDIDATE_FACT_STATUSES, FACT_STATUS_TRANSITIONS, PUBLISHABLE_FACT_STATUSES, DBWRType, ErrorType, FactStatus, SourceType, ) from common.logger import LOG from common.models.gmodel import UserInfo from common.utils.gtime import GTime from crud.faq_crud import FaqCRUD, IFaqCRUD from crud.place_crud import PlaceCRUD from router.v1.faq.protocol import FaqData, Req_CreateFaq, Req_TransitionFaq, Res_Faq, Res_FaqList class FaqService: def __init__(self, crud: IFaqCRUD = Depends(FaqCRUD), place_crud: PlaceCRUD = Depends(PlaceCRUD)): self.crud = crud self.place_crud = place_crud # ---- 사업장 로드(회사 스코프) ---- async def _load_place(self, user_info: UserInfo, place_id: str): """company_id 를 WHERE 에 걸어 조회한다 — 남의 회사 place_id 를 넣으면 PLACE_NOT_FOUND. '없다'와 '권한 없다'를 구분해 주지 않는 것도 의도다(존재 여부를 흘리지 않는다).""" err_type, place = await DB_SESSION_MNG.execute_lambda( places.DBType(), DBWRType.DB_READ.value, lambda s: self.place_crud.get_place(s, uuid.UUID(user_info.company_id), uuid.UUID(place_id)), ) if err_type != ErrorType.SUCCESS: return ErrorType.PLACE_NOT_FOUND, None return ErrorType.SUCCESS, place async def _mark_content_updated(self, place_id: str, ts): """★ 사이트에 나가는 내용이 바뀌었다 — 이 사업장만 다시 빌드하면 된다는 표시. FAQ 도 페이지에 렌더되고 FAQPage JSON-LD 로 나가므로 fact 와 같은 취급이다. 부가 효과라 실패해도 본 흐름을 막지 않는다(다음 변경 때 다시 찍힌다).""" err = await DB_SESSION_MNG.execute_lambda_run([places.DBType()], [lambda s: self._touch(s, place_id, ts)]) if err != ErrorType.SUCCESS: LOG.e_no_callstack(f"[faq] content_updated_at 갱신 실패 place={place_id}") async def _touch(self, s, place_id: str, ts): from sqlalchemy import update query = update(places).where(places.place_id == uuid.UUID(place_id)).values(content_updated_at=ts, updated_at=ts) return await DB_SESSION_MNG.add(s, query) async def _reload(self, res: Res_Faq, pid, faq_id) -> Res_Faq: _e, row = await DB_SESSION_MNG.execute_lambda( faqs.DBType(), DBWRType.DB_READ.value, lambda s: self.crud.get_faq(s, pid, faq_id), ) res.faq = FaqData.model_validate(row) if row is not None else None return res # ---- 조회 ---- async def list_faqs(self, user_info: UserInfo, place_id: str, publishable_only: bool = False) -> Res_FaqList: """publishable_only=True → ★ 사이트에 나갈 수 있는 것만(빌드가 보는 것과 같은 집합). 기본(False)은 승인 대기까지 함께 준다 — 관리 화면이 승인할 대상을 봐야 하기 때문이다.""" res = Res_FaqList() err_type, _place = await self._load_place(user_info, place_id) if err_type != ErrorType.SUCCESS: res.result.SetResult(err_type) return res pid = uuid.UUID(place_id) list_err, rows = await DB_SESSION_MNG.execute_lambda( faqs.DBType(), DBWRType.DB_READ.value, lambda s: self.crud.list_faqs(s, pid, publishable_only), ) if list_err != ErrorType.SUCCESS: res.result.SetResult(list_err) return res res.faqs = [FaqData.model_validate(r) for r in rows] res.publishable = sum(1 for r in rows if FactStatus(r.status) in PUBLISHABLE_FACT_STATUSES) res.pending_review = sum(1 for r in rows if FactStatus(r.status) in CANDIDATE_FACT_STATUSES) return res # ---- 직접 추가 ---- async def create_faq(self, user_info: UserInfo, place_id: str, req: Req_CreateFaq) -> Res_Faq: """사장님이 직접 쓴 FAQ 를 넣는다 — fact 의 owner 입력과 같은 철학으로 바로 노출값(VERIFIED)이 된다. 근거 fact(source_fact_ids)를 요구하지 않는 것도 그래서다. 근거를 요구하는 이유는 LLM 이 지어냈는지 확인하기 위해서인데, 여기서는 사람 본인이 출처다.""" res = Res_Faq() err_type, _place = await self._load_place(user_info, place_id) if err_type != ErrorType.SUCCESS: res.result.SetResult(err_type) return res question = (req.question or "").strip() answer = (req.answer or "").strip() if not question or not answer: # 빈 문답은 사이트에 렌더도 안 되고 고유 콘텐츠로도 안 세진다 — 애초에 받지 않는다. res.result.SetResult(ErrorType.INVALID_REQUEST_DATA) return res pid = uuid.UUID(place_id) sort_order = req.sort_order if sort_order is None: # 순서를 안 주면 맨 뒤에 붙인다 — 기존 FAQ 사이에 끼어들어 순서를 흔들지 않게. _e, rows = await DB_SESSION_MNG.execute_lambda( faqs.DBType(), DBWRType.DB_READ.value, lambda s: self.crud.list_faqs(s, pid, False), ) sort_order = max((r.sort_order for r in rows), default=-1) + 1 row = faqs( place_id=pid, question=question, answer=answer, generated_by=SourceType.OWNER.value, status=FactStatus.VERIFIED.value, sort_order=sort_order, ) run_err = await DB_SESSION_MNG.execute_lambda_run([faqs.DBType()], [lambda s: self.crud.add_faq(s, row)]) if run_err != ErrorType.SUCCESS: res.result.SetResult(run_err) return res # 바로 노출 대상이 늘었다 → 재빌드 대상 표시. await self._mark_content_updated(place_id, GTime.UTC()) return await self._reload(res, pid, row.faq_id) # ---- 검증 상태 전이(승인 · 정정 · 반려) ---- async def transition(self, user_info: UserInfo, place_id: str, faq_id: str, req: Req_TransitionFaq) -> Res_Faq: """생성된 FAQ 를 승인하거나, 문구를 고쳐 승인하거나, 반려한다. 고쳐서 승인하면 CORRECTED — ★ 잠긴 상태다. 이후 재생성(expire_generated)은 미확인 FAQ 만 건드리므로 사장님이 고친 문구는 살아남는다. generated_by 도 OWNER 로 바꿔 둔다: 문장의 책임 주체가 LLM 에서 사람으로 넘어왔다는 기록이다.""" res = Res_Faq() err_type, _place = await self._load_place(user_info, place_id) if err_type != ErrorType.SUCCESS: res.result.SetResult(err_type) return res pid = uuid.UUID(place_id) fid = uuid.UUID(faq_id) get_err, faq = await DB_SESSION_MNG.execute_lambda( faqs.DBType(), DBWRType.DB_READ.value, lambda s: self.crud.get_faq(s, pid, fid), ) if get_err != ErrorType.SUCCESS: res.result.SetResult(ErrorType.FAQ_NOT_FOUND) return res current = FactStatus(faq.status) target = req.status if target not in FACT_STATUS_TRANSITIONS.get(current, set()): res.result.SetResult(ErrorType.FACT_INVALID_TRANSITION) return res data: dict = {} if target == FactStatus.CORRECTED: question = (req.question or "").strip() answer = (req.answer or "").strip() if not question and not answer: # '정정'인데 고친 문구가 없으면 그냥 승인(VERIFIED)이어야 한다 — 잠금만 얻는 길을 막는다. res.result.SetResult(ErrorType.INVALID_REQUEST_DATA) return res if question: data["question"] = question if answer: data["answer"] = answer data["generated_by"] = SourceType.OWNER.value now = GTime.UTC() run_err = await DB_SESSION_MNG.execute_lambda_run( [faqs.DBType()], [lambda s: self._transition_ok(s, fid, current, target, data)], ) if run_err != ErrorType.SUCCESS: # 적용행수 0 = 그 사이 다른 사람이 상태를 바꿨다 — 요청한 전이는 더 이상 유효하지 않다. res.result.SetResult(ErrorType.FACT_INVALID_TRANSITION if run_err == ErrorType.DB_EMPTY_DATA else run_err) return res # 노출 집합이 바뀌는 전이(승격 / 정정 / 노출값 내림)면 재빌드 대상으로 표시한다. if target in PUBLISHABLE_FACT_STATUSES or current in PUBLISHABLE_FACT_STATUSES: await self._mark_content_updated(place_id, now) return await self._reload(res, pid, fid) async def _transition_ok(self, s, fid, current: FactStatus, target: FactStatus, data: dict): """출발 상태를 WHERE 에 걸어 조건부로만 바꾼다(동시 처리 가드). execute_lambda_run 은 ErrorType 만 받으므로 적용행수 0 을 DB_EMPTY_DATA 로 바꿔 트랜잭션을 중단시킨다.""" err_type, rowcount = await self.crud.transition(s, fid, (current.value,), target.value, data) if err_type != ErrorType.SUCCESS: return err_type return ErrorType.SUCCESS if rowcount else ErrorType.DB_EMPTY_DATA