mygit-admin/ken_nogi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
ken_nogi/NodeSrv/apps/lineworks-board-sync/SPEC.md
Kenichiro NOGI ce58cb4be4 初回コミット: dev配下(NodeSrv/Pleasanter等)をGitea管理下に統合 
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>
2026-09-04 15:37:06 +09:00

4.7 KiB
Raw Permalink Blame History

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

ローカル開発手順

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