refs #732: separate report data and rendering requests

docs/design/hmm-html-report-mcp/README.md

@@ -15,6 +15,7 @@ DB를 다시 조회하거나 자연어를 해석하지 않는다.
 - 승인된 HTML 템플릿은 DB CLOB으로 버전 관리하고, 생성 HTML은 MCP 응답의 `html` 속성으로만 반환한다.
 - 제목은 질문 전체 문장을 복사하지 않는다. 포털의 제목 생성 지침이 요청 대상과 업무 범위만 남긴 짧은 보고서 제목을 만들고 renderer에 전달한다.
 - HTML artifact가 반환되면 일반 답변은 HTML 표나 코드를 반복하지 않고 생성 완료와 조회 건수만 안내한다. 실제 표현은 `생성된 리포트` 영역 하나에서 담당한다.
+- 포털은 사용자 질문을 그대로 두 Tool에 재사용하지 않는다. 첫 조회에는 데이터 조건만 남긴 질문을 전달하고, `HTML로 보여줘` 같은 표현 요청은 renderer 선택과 제목 생성에만 사용한다.
 
 ## 전체 흐름
 

docs/design/hmm-html-report-mcp/architecture.md

@@ -72,6 +72,22 @@ renderer 응답에 유효한 `html` 또는 `rendered_html`이 있으면 HTML art
 조회 건수, 아래 리포트 확인 안내만 반환한다. 포털은 같은 조건을 출력 후에도 검사해 모델이
 HTML을 반환하더라도 안전한 짧은 안내문으로 정규화한다.
 
+## 조회 질문과 표현 요청 분리
+
+사용자의 한 문장에는 데이터 요구와 표현 요구가 함께 있을 수 있다. 포털은 Agent instruction으로
+두 의도를 분리한다.
+
+```text
+원문: E1001 팀 선사 KPI를 HTML로 보여줘
+조회 단계: E1001 팀 선사 KPI를 보여줘
+표현 단계: 조회된 구조화 행을 HTML 리포트로 렌더링
+```
+
+조회 단계 재작성은 직원·팀·기간·지표·필터를 모두 유지하고 `HTML`, `리포트`, `차트`, `대시보드`
+같은 출력 형식과 생성 행동만 제거한다. 원문은 `report.question`에 보존한다. Select AI가 만든
+`htmlRow`, HTML 태그 또는 Markdown 표는 구조화 업무 행으로 간주하지 않으며 renderer 입력으로
+전달하지 않는다.
+
 서버는 JSON 크기, 행 수, 문자열 길이, 숫자 형식을 제한하고, 템플릿에 주입할 JSON에서
 `</script>`를 이스케이프한다. payload는 저장하지 않는다.
 

docs/design/hmm-html-report-mcp/cookbook.md

@@ -32,11 +32,14 @@
    허용 목록에 조회 도구와 리포트 렌더링 도구를 모두 넣는다.
 2. 포털에서 예를 들어 `E1001 팀의 선사 최신 실적을 HMM 리포트로 만들어줘`라고 요청한다.
 3. 실행 상세에서 첫 단계가 데이터 조회이고 두 번째 단계가 HTML 렌더링인지 확인한다.
+   첫 단계 MCP argument에는 `HTML로 보여줘`, `리포트로 만들어줘` 같은 표현 요청이 없어야 한다.
 4. 결과 영역에 `생성된 리포트` iframe이 표시되고, 막대·상세 표가 첫 단계 `items`와 일치하는지
    확인한다.
 5. 일반 답변에는 `<table>`, `<div>` 또는 Markdown 표가 반복되지 않고, 생성 완료·제목·조회 건수만
    표시되는지 확인한다.
 6. 리포트 머리글이 질문 전체 문장이 아니라 출력 형식 문구를 제거한 짧은 업무 제목인지 확인한다.
+7. `reportJson.rows`의 각 행이 `employeeCode`, `carrierCode`, KPI처럼 업무 필드를 가지며,
+   `htmlRow`나 `<tr>` 문자열을 포함하지 않는지 확인한다.
 
 대표 E1001 팀장 질의의 운영 회귀 기준은 현재 8건이다. 이 숫자는 검증 기준일 뿐 코드나 Tool
 인수에 고정하지 않는다. 첫 단계 원본에 행이 있는데 `reportJson.rows`가 0건이면 순차 실행 성공이

docs/design/hmm-html-report-mcp/troubleshooting.md

@@ -60,6 +60,20 @@
 
 **재발 방지**: 제목과 원문 질문이 역할상 분리되고 제목 길이 제한이 적용되는지 검증한다.
 
+## `reportJson.rows`가 `htmlRow`와 `<tr>`만 포함함
+
+**원인**: 포털이 `HTML로 보여줘`가 포함된 원문을 첫 Select AI 데이터 조회에 그대로 전달해,
+조회 Tool이 컬럼별 구조화 행 대신 HTML 조각을 반환했다.
+
+**확인**: 첫 Agent 단계의 MCP argument와 원본 결과를 확인한다. 조회 질문에 표현 형식이 남아 있고
+행 key가 `htmlRow`뿐이면 이 문제다.
+
+**해결**: 포털의 데이터 질문 재작성 instruction이 업무 대상·필터·지표는 유지하면서 HTML·리포트·
+차트 생성 요청만 제거하도록 한다. renderer나 DB 조회 Tool을 변경하지 않는다.
+
+**재발 방지**: `HTML로 보여줘`가 포함된 통합 질문으로 실제 연속 호출하고, 조회 결과와
+`reportJson.rows` 모두 업무 필드를 가지며 HTML 태그가 없는지 검증한다.
+
 ## 리포트는 생성됐지만 행이 0건임
 
 **원인**: 다음 둘 중 하나다.