feat: /help 슬래시 커맨드 추가 및 사용자 가이드 작성

docs/USAGE.md

@@ -0,0 +1,126 @@
+# Lang2SQL 사용 가이드
+
+Discord에서 자연어로 질문하면 SQL을 생성하고 결과를 돌려주는 분석 에이전트입니다.
+
+---
+
+## 빠른 시작
+
+봇이 서버에 있다면 바로 질문할 수 있습니다.
+
+```
+@Lang2SQL 이번 달 매출 상위 고객 10명 알려줘
+```
+
+처음 사용한다면 아래 순서대로 세팅합니다.
+
+---
+
+## 1단계: DB 연결
+
+DB가 연결되지 않으면 SQL을 실행할 수 없습니다.
+
+```
+/setup
+```
+
+DB 종류(PostgreSQL, MySQL, SQLite 등)를 선택하는 안내가 나타납니다. 접속 정보를 입력하면 연결됩니다. DSN을 직접 알고 있다면 `/connect dsn:...`으로 바로 입력할 수도 있습니다.
+
+> 관리자 권한이 필요합니다.
+
+---
+
+## 2단계: 비즈니스 용어 등록
+
+"월매출", "활성고객"처럼 회사 내부 용어를 등록해두면 LLM이 SQL을 훨씬 정확하게 만듭니다.
+
+### 방법 A — 텍스트에서 자동 추출
+
+문서나 정의집 내용을 붙여넣으면 후보를 자동으로 뽑아줍니다.
+
+```
+/ingest content:월매출은 SUM(orders.amount)이고, 활성고객은 30일 내 로그인한 users, 환불제외는 status != 'cancelled'
+```
+
+후보 목록이 표시되면 확인 후 등록합니다.
+
+```
+/confirm_ingest ref:inline:xxxx accept:all layer:channel
+```
+
+- `accept`: `all`이면 전체, `1,3`처럼 번호를 지정하면 선택 등록
+- `layer`: `channel`(이 채널 전용), `guild`(전사 공통, 관리자 전용), `member`(개인)
+
+### 방법 B — 직접 등록
+
+```
+/term_custom
+```
+
+안내에 따라 용어명, 정의, 종류(metric/rule/dimension/table)를 입력합니다.
+
+### 방법 C — DB 스캔으로 자동 추출
+
+```
+/org_setup org:회사명
+```
+
+DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니다.
+
+---
+
+## 3단계: 질문하기
+
+용어를 등록한 뒤 자연어로 질문합니다.
+
+```
+@Lang2SQL 월매출 기준 이번 달 상위 고객 10명 보여줘
+@Lang2SQL 환불제외 기준으로 채널별 주문 수 알려줘
+```
+
+봇이 SQL을 생성해 실행하고 결과를 표시합니다.
+
+---
+
+## 용어 우선순위 (Federation)
+
+같은 용어가 여러 레이어에 등록된 경우 **좁은 범위가 우선** 적용됩니다.
+
+```
+개인(member) > 채널(channel) > 전사(guild)
+```
+
+예를 들어 "활성고객"을 전사에서는 "30일 내 로그인"으로 정의했더라도, 마케팅 채널에서 "14일 내 로그인"으로 따로 등록하면 마케팅 채널 안에서만 그 정의가 우선 적용됩니다. 다른 채널에는 영향이 없습니다.
+
+---
+
+## 전체 커맨드 목록
+
+| 커맨드 | 설명 |
+|---|---|
+| `/setup` | DB 연결 마법사 (관리자) |
+| `/connect dsn:...` | DSN으로 직접 DB 연결 |
+| `/ingest content:...` | 텍스트에서 용어 후보 추출 |
+| `/ingest ref:파일명` | 서버 파일에서 용어 후보 추출 |
+| `/confirm_ingest ref:... accept:... layer:...` | 추출된 후보 검토 후 등록 |
+| `/term_custom` | 용어 직접 등록 (위저드) |
+| `/term_custom action:show` | 등록된 용어 전체 조회 |
+| `/term_custom action:remove term:용어명` | 용어 삭제 |
+| `/org_setup org:...` | 전사 조직 등록 + DB 스캔 |
+| `/org_setup team:...` | 팀(채널) 등록 |
+| `/enrich` | DB 컬럼 메타데이터 자동 보강 |
+| `/remember text:...` | 사실 기억 저장 |
+| `/audit_me` | 내 활동 이력 조회 |
+
+---
+
+## 자주 묻는 질문
+
+**Q. 질문했는데 엉뚱한 SQL이 나와요.**
+등록된 용어가 없거나 DB 메타데이터가 부족한 경우입니다. `/enrich`로 컬럼 설명을 보강하거나 `/term_custom`으로 관련 용어를 등록해보세요.
+
+**Q. "guild 용어는 관리자만 등록 가능" 오류가 나요.**
+`layer:guild`는 관리자 권한이 필요합니다. `layer:channel`로 채널 범위로 등록하거나 관리자에게 요청하세요.
+
+**Q. 이전 대화 내용을 기억하나요?**
+같은 채널(또는 DM 스레드)에서 이어지는 대화는 맥락이 유지됩니다. `/remember`로 중요한 사실을 명시적으로 저장할 수도 있습니다.

src/lang2sql/frontends/discord/bot.py

@@ -261,6 +261,10 @@ async def audit_me(interaction: discord.Interaction) -> None:
                 handlers.audit_me(to_identity(_interaction_context(interaction))),
             )
 
+        @tree.command(name="help", description="Lang2SQL 사용 방법 안내")
+        async def help(interaction: discord.Interaction) -> None:
+            await self._run(interaction, handlers.help())
+
     async def _run(self, interaction: discord.Interaction, coro) -> None:
         """Await a handler coroutine and reply with its OutboundMessage."""
         await interaction.response.defer(thinking=True)

src/lang2sql/frontends/discord/commands.py

@@ -264,6 +264,39 @@ async def confirm_ingest(
         )
         return OutboundMessage(text=result.content)
 
+    async def help(self) -> OutboundMessage:
+        """사용 방법 안내."""
+        text = """\
+**Lang2SQL 사용 가이드**
+
+**📊 질문하기**
+봇을 멘션하거나 채널에서 자연어로 질문하세요.
+> @Lang2SQL 이번 달 매출 상위 고객 10명 알려줘
+
+**🗄️ DB 연결** (관리자)
+`/setup` — 안내에 따라 DB 접속 정보 입력
+`/connect dsn:...` — DSN 직접 입력
+
+**📖 비즈니스 용어 등록**
+`/ingest content:월매출은 SUM(orders.amount), 활성고객은 30일 내 로그인`
+→ 후보 추출 후 아래 커맨드로 확정
+`/confirm_ingest ref:inline:xxxx accept:all layer:channel`
+
+`/term_custom` — 용어 직접 등록 (위저드)
+`/term_custom action:show` — 등록된 용어 조회
+`/org_setup org:회사명` — DB 스캔으로 용어 자동 추출
+
+**🏷️ 용어 우선순위**
+개인(member) > 채널(channel) > 전사(guild)
+같은 채널 안에서 등록한 정의가 전사 정의보다 우선 적용됩니다.
+
+**🔧 기타**
+`/enrich` — DB 컬럼 설명 자동 보강
+`/remember text:...` — 사실 저장
+`/audit_me` — 내 활동 이력 조회
+`/help` — 이 도움말"""
+        return OutboundMessage(text=text)
+
 
 def _fmt_ts(ts: float) -> str:
     """Format an epoch timestamp as a short UTC string for audit listings."""