# lineworks-board-sync 仕様書

## 概要
- アプリ名: lineworks-board-sync
- 目的: LINE WORKS の掲示板（Board）から投稿および添付ファイルを取得し、ローカルに保存、必要に応じて外部サービスへアップロード／インデックス化する同期バッチ／APIサービス。

## 主要機能
- 指定掲示板の投稿一覧取得・投稿詳細取得
- 添付ファイル（PDF/画像等）のダウンロード
- 投稿をMarkdown化してローカルに保存（`board_posts_md/`）
- 添付ファイルをローカルに保存（`board_attachments/`）
- アップロード済みハッシュ管理による重複排除（`board-uploaded-hashes.json`）
- Rate Limit対策（スロットリング、429時のRetry）
- 長文の分割（条文形式の分割 / AI補助分割）
- 完了ファイルを `complete/` に退避して再処理を防止
- AnythingLLM 等へのアップロード（オプション）とワークスペースへの埋め込み

## 動作フロー
1. 認証トークンを取得（JWT assertion を用いた OAuth2.0）
2. 対象掲示板を取得（`board-list.csv` の flag=1 を優先、それ以外は利用可能全掲示板を取得）
3. 各掲示板について投稿一覧をページネーションで取得
4. 各投稿について詳細を取得し、本文をHTML除去してテキスト化
5. 重複チェック（投稿ハッシュ） → 未登録なら処理継続
6. 添付一覧取得・添付ダウンロード → ローカル保存
7. 投稿本文の分割ルールに従いMarkdownファイルに出力
8. 必要に応じて外部APIへアップロード、埋め込み処理
9. 成功したファイルは `complete/` へ移動、ハッシュを保存

## API / エンドポイント
- `/` : 簡易応答（JSON: { app: 'lineworks-board-sync', status: 'ok' }）
- `/health` : ヘルスチェック用（200 OK）

（主処理はCLI/バッチで動作。`node lineworks-board-sync.js sync` のようなコマンド実行を想定）

## 環境変数
- LW_CLIENT_ID
- LW_CLIENT_SECRET
- LW_SERVICE_ACCOUNT
- LW_PRIVATE_KEY または LW_PRIVATE_KEY_FILE
- LW_SCOPE (デフォルト: "board board.read")
- LW_REQUEST_DELAY_MS (ミリ秒、既定250)
- LW_MAX_RETRIES (429時の最大リトライ回数)
- ANYTHINGLLM_BASE_URL （任意）
- ANYTHINGLLM_API_KEY （任意）
- ANYTHINGLLM_WORKSPACE_SLUG （任意）
- EMBEDDING_BATCH_SIZE （任意）
- LMSTUDIO_CHAT_URL / LMSTUDIO_MODEL_NAME（AI分割を使う場合）

## ディレクトリ構成（主要）
- apps/lineworks-board-sync/
  - src/index.js
  - package.json
  - .env.example
  - board-list.csv
  - board_posts_md/
    - complete/
  - board_attachments/
    - complete/
  - board-uploaded-hashes.json
  - SPEC.md

## ローカル開発手順
```bash
cd apps/lineworks-board-sync
npm install
cp .env.example .env
# 必要な環境変数を .env に設定
npm run dev
# またはバッチ実行
node src/index.js     # サーバ起動
# CLI（別スクリプト）
node lineworks-sync.js sync
```

## Docker / 本番デプロイ
- `Dockerfile` によるビルドを想定。Dokployでは Build Path を `NodeSrv/apps/lineworks-board-sync` に指定し、Port 3000 を合わせる。
- 本番環境では `.env` を管理画面で設定し、秘密鍵は `LW_PRIVATE_KEY` に直接入れず `LW_PRIVATE_KEY_FILE` を使うことを推奨。

## レート制御とリトライ
- リクエスト間隔は `LW_REQUEST_DELAY_MS` で制御
- 429レスポンス時は Retry-After ヘッダ優先、無ければ指数バックオフで再試行（上限 `LW_MAX_RETRIES`）

## 重複制御 / idempotency
- 投稿: `boardId + postId + 更新日時 + タイトル + 本文` をSHA256ハッシュ化して `board-uploaded-hashes.json` に保存
- 添付: `boardId + postId + attachmentId` をハッシュ化して管理

## ロギング・監視
- コンソール出力で処理状況を表示。Dokploy環境ではログを集約する仕組みを利用すること。
- 重要な警告・例外は WARN/ERROR レベルで出力

## セキュリティ
- 秘密鍵はリポジトリに直書きしない。`LW_PRIVATE_KEY_FILE` または deploy 環境のシークレット管理を利用。
- 出力ファイルやハッシュファイルは適切なファイルパーミッションを設定すること。

## テスト
- 単体: mock を使った API 呼び出しのスタブ化（fetch をモック）
- 結合: 少量の掲示板を対象にしたエンドツーエンドの同期検証

## 備考 / 今後の拡張
- スケジューラ（cron）連携により定期実行化
- Web UI で同期状況の可視化
- AnythingLLM 以外のアップロード先プラグイン化

---
作成日時: 2026-07-21