ce58cb4be4
GitHub(nextgroup2706/ken_nogi)は今後使わず自社Gitea運用に切替え。 NodeSrvは旧リポジトリの履歴を破棄しファイルのみ統合(Dokploy用サービスアカウントは 別途mygit-admin/NodeSrv.gitに履歴あり)。notepmエクスポート(12GB)とPleasanter インストーラzip(208MB)はサイズが大きいため.gitignoreで除外。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
100 lines
6.7 KiB
Markdown
100 lines
6.7 KiB
Markdown
## 開発要件書：LINE WORKS 掲示板 RAG同期管理システム
|
||
## 1. システム概要
|
||
本システムは、LINE WORKSの特定掲示板から投稿および添付ファイル（PDF/画像等）を自動取得し、AnythingLLMへRAGデータとして同期・連携するNode.js製アプリケーションです。
|
||
バックエンドの同期エンジン（既存のCLI資産を内包・拡張）と、同期状態の可視化や手動実行を行うモダンなWebフロントエンド（管理画面）で構成されます。
|
||
## 動作・運用環境
|
||
|
||
* 開発言語: Node.js (v18+) / TypeScript
|
||
* フロントエンドUI: React (Next.js App Router 又は Vite) + shadcn/ui + Tailwind CSS
|
||
* 認証基盤: 外部 Keycloak（OIDC連携、既存基盤を活用）
|
||
* インフラ: 自社設置の Dokploy サーバー（Dockerコンテナデプロイ）
|
||
|
||
------------------------------
|
||
## 2. アーキテクチャ & 技術スタック## バックエンド (Node.js 18+)
|
||
|
||
* API通信: 外部ライブラリ（axios等）に依存せず、Node.js標準の fetch、FormData、Blob、crypto（JWT自前署名用）のみで実装。
|
||
* データ永続化:
|
||
* board-list.csv: 同期対象の掲示板マスター（boardId,boardName,flag）
|
||
* board-uploaded-hashes.json: 重複アップロード防止用のハッシュ管理
|
||
|
||
## フロントエンド (Next.js / React)
|
||
|
||
* UIコンポーネント: shadcn/ui
|
||
* スタイリング: Tailwind CSS
|
||
* 認証: next-auth 又は oidc-client-ts を用いた Keycloak 認可コードフロー
|
||
|
||
------------------------------
|
||
## 3. 機能要件## 【F-1】バックエンド同期エンジン（コアロジック拡張）
|
||
既存の lineworks-anythingllm.js (v3) 処理を完全に内包し、以下の機能を持つクラスまたはモジュールとして再構築します。
|
||
|
||
1. 認証 & トークン取得: crypto モジュールを使用し、Service Account認証(JWT)でLINE WORKSのAccess Token（Scope: board）を自前署名で取得。
|
||
2. 掲示板リスト同期: GET /boards から取得し、board-list.csv を更新。
|
||
3. 投稿・添付ファイル同期 (sync 処理):
|
||
* board-list.csv で flag="1" の掲示板をループ処理。
|
||
* GET /boards/{boardId}/posts で最新投稿を取得。
|
||
* 重複チェック（投稿）: boardId + postId + 更新日時 + タイトル + 本文 からハッシュ生成。未登録または変更があれば処理続行。
|
||
* 投稿アップロード: 本文をMarkdown化し、AnythingLLMのAPI経由で指定のワークスペースへアップロード。成功後、ファイルを board_posts_md/complete/ へ退避。
|
||
* 添付ファイル処理: GET /boards/{boardId}/posts/{postId}/attachments でリスト取得。
|
||
* 重複チェック（添付）: boardId + postId + attachmentId からハッシュ生成。
|
||
* 添付アップロード: ファイルをダウンロード（GET /attachments/{attachmentId}）し、AnythingLLMへ直接個別アップロード（OCR等はAnythingLLM側で処理）。成功後、ファイルを board_attachments/complete/ へ退避。
|
||
* ファイル名競合回避: 退避先に同名ファイルがある場合は、タイムスタンプを付与。
|
||
|
||
## 【F-2】フロントエンド（管理画面 Web UI）
|
||
Keycloak認証を通過したユーザーのみがアクセス可能。
|
||
|
||
1. ダッシュボード画面:
|
||
* システム全体の同期ステータス（最終同期日時、総同期済みファイル数、直近の同期エラーログ）。
|
||
* 「今すぐ同期 (Sync)」ボタン（バックエンドの同期処理を非同期でキック）。
|
||
* チャットテストエリア：ask コマンド相当のUI（AnythingLLMのチャットAPIを叩き、RAGの応答精度を画面でテスト確認できるエリア）。
|
||
2. 掲示板設定画面 (board-list.csv の管理):
|
||
* LINE WORKSから取得した掲示板一覧を shadcn/ui の Table コンポーネントで表示。
|
||
* 各掲示板の同期 flag (ON/OFF) をSwitchまたはCheckboxコンポーネントで切り替え、CSVへ即時保存。
|
||
3. 同期ログ・ハッシュ履歴画面:
|
||
* board-uploaded-hashes.json の中身をグリッド表示、または同期された過去の投稿一覧をパジネーション付きで表示。
|
||
|
||
------------------------------
|
||
## 4. 環境変数・設定（.env）
|
||
|
||
# Keycloak設定
|
||
KEYCLOAK_CLIENT_ID=
|
||
KEYCLOAK_CLIENT_SECRET=
|
||
KEYCLOAK_ISSUER=
|
||
|
||
# LINE WORKS API設定 (getGroupList.js 共通)
|
||
LW_CLIENT_ID=
|
||
LW_CLIENT_SECRET=
|
||
LW_SERVICE_ACCOUNT=
|
||
LW_PRIVATE_KEY=
|
||
LW_PRIVATE_KEY_FILE=
|
||
LW_SCOPE=board
|
||
|
||
# AnythingLLM設定
|
||
ANYTHINGLLM_BASE_URL=http://localhost:3001
|
||
ANYTHINGLLM_API_KEY=
|
||
ANYTHINGLLM_WORKSPACE_SLUG=lineworks-board
|
||
|
||
------------------------------
|
||
## 5. Claude Code への開発指示プロンプト（タスク分割）
|
||
Claude Codeを実行する際、以下のステップ順に指示を出すとスムーズです。
|
||
## Step 1: プロジェクトの土台構築
|
||
|
||
「Next.js (App Router) + TypeScript + Tailwind CSSのプロジェクトを初期化し、shadcn/ui を導入してください。その後、指定された.envの環境変数定義ファイルを作成してください。」
|
||
|
||
## Step 2: バックエンド同期コアロジックの移植と検証
|
||
|
||
「既存の Samples\lineworks-sync\lineworks-anythingllm.js のロジック（cryptoによるJWT自前署名、標準fetch/FormDataでのLINE WORKSおよびAnythingLLM API連携、ハッシュによる重複防止、ファイル退避処理）を、TypeScriptのサービスモジュール server/services/syncEngine.ts として移植・リファクタリングしてください。外部npmライブラリは一切追加しないでください。」
|
||
|
||
## Step 3: Keycloak認証の組み込み
|
||
|
||
「next-auth (又は標準的なOIDCルーティング) を使用して、Keycloakベースの認証機能を実装してください。すべての画面へのアクセスに認証を必須としてください。」
|
||
|
||
## Step 4: Web UI (管理画面) の実装
|
||
|
||
「shadcn/uiコンポーネント（Table, Button, Switch, Card, Toast）をフル活用し、ダッシュボード画面、掲示板同期設定画面（board-list.csvの読み書き）、簡易RAGテストチャット画面を構築してください。」
|
||
|
||
## Step 5: Docker化 & Dokployデプロイ準備
|
||
|
||
「本アプリケーションをDokploy環境で安全に動かすための Dockerfile および docker-compose.yml を作成してください。board-list.csv や各種一時保存フォルダ（board_posts_md, board_attachments, board-uploaded-hashes.json）がコンテナ再起動で消えないよう、永続化ボリューム（Volume）の定義を正しく行ってください。」
|
||
|
||
------------------------------
|