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>
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
# 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
|