From 0c2cf263b6978437c82b1c10964c503f0dec56b5 Mon Sep 17 00:00:00 2001 From: Anya Tokugawa Date: Sun, 8 Nov 2026 02:48:14 +0900 Subject: [PATCH] docs: define embedded and FreshRSS source authority [skip ci] --- docs/design/ja/decisions.md | 4 +- docs/design/ja/feeds.md | 48 ++++++++++++++++-------- docs/design/ja/implementation-backlog.md | 7 ++-- 3 files changed, 38 insertions(+), 21 deletions(-) diff --git a/docs/design/ja/decisions.md b/docs/design/ja/decisions.md index f59ebed..6002b77 100644 --- a/docs/design/ja/decisions.md +++ b/docs/design/ja/decisions.md @@ -27,7 +27,7 @@ | ADR-O1 | organizerはtyped metadataと任意Page参照 | タスク初版は専用表+既存CAS Document Store(2026-09-24)。通常のObject閲覧・リンク・削除の権限境界を拡大せず、個人所有を確実に分離する。DBは捨てられる索引ではない。[実装契約](tasks-implementation.md) | | ADR-O2 | task共通部+ticket workflow | 提案。番号・外部依頼者・遷移権限の要件確認 | | ADR-O3 | ICS/vCard入出力→read-only DAV→双方向 | 推奨順。対象サーバー/clientを選んで互換表を作る | -| ADR-O4 | FreshRSS正本+PagesWiki connector+newsboat | 第一候補。利用環境・追加運用負荷を確認。内蔵readerは代案 | +| ADR-O4 | 簡易利用は内蔵正本、本格運用はFreshRSS正本+PagesWiki connector+newsboat | 2026-11-08利用者指定で採用。source単位で正本を分離し、自動fallbackや二重管理はしない。実環境の接続先・版・資格情報は別途指定 | | ADR-O5 | IMAP read-only、Wikiコピーは明示操作 | 初期設計方針。providerとsampleが実装前提 | | ADR-O6 | HTMLパーツを先行し全面WYSIWYGは保留 | 提案。round-tripと操作改善の評価でgo/no-go | | ADR-O7 | Wiki Pathと外部UID/hrefを分離 | 共通の設計制約。rename fixtureを全connectorで実施 | @@ -35,7 +35,7 @@ ## 未決事項 -利用するFreshRSSの有無と版、対象CalDAV/CardDAV client、IMAP provider、taskの共有単位、ticketの依頼者公開範囲、保持期限、外部接続を許可するhost、RPO/RTO、WYSIWYG採用基準です。これらが未決でもlocal fixtureと設計は進められますが、外部サービスを勝手に立ち上げたり資格情報を流用したりしません。 +利用するFreshRSSの接続先・版・資格情報、対象CalDAV/CardDAV client、IMAP provider、taskの共有単位、ticketの依頼者公開範囲、保持期限、外部接続を許可するhost、RPO/RTO、WYSIWYG採用基準です。これらが未決でもlocal fixtureと設計は進められますが、外部サービスを勝手に立ち上げたり資格情報を流用したりしません。 ## 文書運用 diff --git a/docs/design/ja/feeds.md b/docs/design/ja/feeds.md index bafbcb6..de24a1a 100644 --- a/docs/design/ja/feeds.md +++ b/docs/design/ja/feeds.md @@ -1,21 +1,32 @@ # 15. RSSビューア・FreshRSS・newsboat -状態:設計案。既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。 +状態:正本の役割分担は決定、実装は未着手。既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。 -2026-11-08:利用者指定のサブプロジェクト順で最初に実施する。FreshRSS/内蔵readerの -正本選定と実環境への接続は別の判断であり、RSSを優先することだけでは確定しない。 +2026-11-08:利用者指定のサブプロジェクト順で最初に実施する。内蔵readerは簡易利用の +正本、本格運用はFreshRSSを正本とする。実環境の接続先・版・資格情報は別途指定する。 -## 選択肢と推奨する試作順 +## 正本と責務 -| 案 | 正本 | 利点 | 追加する責任 | +| モード | 正本 | PagesWikiの役割 | 範囲 | | --- | --- | --- | --- | -| PagesWiki内蔵reader | ローカルの購読と状態 | Wiki保存と一体のUI | 取得・既読・同期・client対応を全て持つ | -| FreshRSS connector | FreshRSSの購読・既読 | 既存reader資産を利用 | API互換性、権限、cacheと失効 | -| newsboat単独の橋渡し | newsboat側の購読・状態 | CLI利用に合わせやすい | ローカル連携経路・export/importの設計 | +| 内蔵簡易reader | PagesWikiの購読・フォルダ・既読・star | feed取得、保持上限内の記事保存、閲覧とWiki保存 | 個人の簡易利用。外部reader向け同期サーバーや高度なルール機能は初期範囲外 | +| FreshRSS連携 | FreshRSSの購読・フォルダ・記事・既読・star | 表示用cache、連携UI、Wiki保存・タスク化 | 本格運用。PagesWikiは独立した購読・既読の正本を重ねない | +| newsboat等のclient | 接続先FreshRSS | PagesWikiと同じ正本を使う別clientとして扱う | PagesWiki経由の代理同期やnewsboatのDB共有は行わない | FreshRSSにはGoogle Reader互換APIがあり、APIの有効化と専用passwordを使います。newsboatにはFreshRSS連携が用意され、カテゴリのtag化やstar操作を扱えます。[FreshRSS公式API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)、[newsboat公式マニュアル](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)。 -このため最初の候補は **FreshRSSを正本、PagesWikiを読取connector、newsboatを同じFreshRSSのclient** とする構成です。これは設計上の提案で、ユーザー環境のFreshRSS導入・採用決定ではありません。PagesWikiがnewsboatをサーバー上で起動したり、そのSQLiteを共有したりする必要はありません。 +本格運用は **FreshRSSを正本、PagesWikiとnewsboatをそのclient** とする構成を採用します。 +内蔵簡易readerも別providerとして提供し、共通の一覧・保存UIを使用します。FreshRSSを +PagesWiki全体の必須依存にはせず、外部サービスの新設・接続は設定時の明示操作とします。 + +sourceは一つのproviderに束縛し、記事キーはDomain/所有者/source UUID/remote IDで +区別します。同じURLの記事でも別sourceの既読を自動統合しません。FreshRSSのcacheは +再取得可能な派生データですが、内蔵の購読・状態は正本として保全対象にします。 + +FreshRSS停止時は取得済みcacheと鮮度・接続状態を示し、内蔵正本へ自動切替しません。 +外部操作の未送信状態は正本と区別し、成功していない既読・starを同期済みと表示しません。 +内蔵からFreshRSSへの移行はOPML等による明示的なexport/importとし、初期版では既読・star・ +記事IDの完全移行を保証しません。移行完了の確認前に内蔵データを削除しません。 ## 読取MVP @@ -29,7 +40,12 @@ server-authoritative stateと未送信の操作を分けます。操作ごとの FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。 -## 内蔵fetcherを選ぶ場合 +## 内蔵簡易reader + +購読追加/削除、フォルダ、記事一覧、既読/未読、star、更新間隔と保持上限を初期範囲に +します。取得は背景ジョブで行い、更新失敗で購読や状態を消しません。記事本文cacheと +既読・starの保持期間を分離し、古い記事を再取得しただけで未読へ戻る挙動を防ぎます。 +高度な自動分類、全文収集、reader向け互換APIはFreshRSSとの機能競争として追加しません。 定期event、条件付きGET、host別同時数、timeout、応答サイズ、展開サイズ、backoffを設けます。XML外部entityを無効にし、feed HTMLを安全化します。redirect/DNSを含むSSRF対策、外部画像の同意、個人購読URLや認証情報の秘匿が必要です。 @@ -41,22 +57,22 @@ OPMLは購読の入出力として扱い、既読・star・全本文のバック ## TODOと受け入れ -RSS-1:read-only FreshRSS fixture。RSS-2:安全な一覧と出典付きWiki保存。RSS-3:必要なら既読/star送信。RSS-4:内蔵reader採用判断とOPML。オフライン、欠落ID、巨大feed、未知HTML、同期再送、他user情報、feed削除後の保存Page維持を試験します。 +RSS-1:read-only FreshRSS fixture。RSS-2:安全な共通一覧と出典付きWiki保存。RSS-3:FreshRSSへの明示的な既読/star操作。RSS-4:内蔵簡易readerとOPML。オフライン、欠落ID、巨大feed、未知HTML、同期再送、他user情報、feed削除後の保存Page維持を試験します。内蔵とFreshRSSの正本を混ぜないこと、停止時の自動切替がないこと、移行後も保存済みWiki/タスクが残ることを両provider共通の受入条件とします。 ## 実施段階 1. **共通契約とfixture**:Domain/本人のsource所有、provider ID、remote ID、cursor、取得予算、 - 最終成功/失敗と無効化を定義する。合成記事を返すfixtureから開始し、FreshRSSを必須の - 稼働依存として固定しない。sourceの資格情報をブラウザ・ログへ出さない。 + 最終成功/失敗と無効化を定義する。FreshRSS読取connectorを合成fixtureで先に検証し、 + 内蔵providerも同じ表示契約へ接続する。sourceの資格情報をブラウザ・ログへ出さない。 2. **読取UIと背景取得**:購読/フォルダ、記事の一行一覧、本文表示、出典リンクを用意する。 デスクトップでは一覧を見渡せる配置、スマホでは一覧と本文を切り替える。画面表示で外部fetchを 待たず、schedulerで有界に更新し、取得済みcacheと鮮度を表示する。source停止・失効も検証する。 3. **Wiki保存とタスク化**:タイトル・URL・出典・短いメモをpreviewし、保存先Pathを選ぶ。 既存captureと権限確認を再利用し、二重送信・保存先競合・自動公開範囲を検査する。全文保存は 独立した明示操作。タスク作成が失敗しても保存済みWikiを消さず、部分成功と再試行方法を示す。 -4. **ダッシュボードと実環境受入**:読める記事だけのwidgetを追加。providerと正本を選定後、 - 同意した接続先でread-only受入を行う。既読/star書込、OPML、内蔵fetcherはそれぞれ後続の - 明示範囲とし、read-only連携を有効化しただけで外部状態を変更しない。 +4. **ダッシュボードとprovider完成**:読める記事だけのwidget、内蔵簡易readerとOPML、 + FreshRSSの明示的な既読/star操作を段階的に追加する。接続先・対象版の指定後に実環境で + read-only→書込の順に受入し、read-only連携を有効化しただけで外部状態を変更しない。 各段階で無効化、件数・時間・容量上限、移行の再実行、ユーザー/Domain間の分離を試験する。 source解除時のcache清掃と、利用者が明示保存したWiki/タスクの保持は別操作とする。 diff --git a/docs/design/ja/implementation-backlog.md b/docs/design/ja/implementation-backlog.md index b0aa4a4..a1a49bb 100644 --- a/docs/design/ja/implementation-backlog.md +++ b/docs/design/ja/implementation-backlog.md @@ -57,8 +57,9 @@ P0は認可・整合性・復旧の安全条件、P1は日常利用の回復性 範囲を各段階へ組み込む。必須の認可・DB整合性・再送防止は省略せず、無関係な基盤改修を すべて完了させるまで機能開発を止める構成にも戻さない。 -最初のRSSは[着手単位](feeds.md#実施段階)に従う。FreshRSS採用や外部環境の新設は未決定のまま、 -まずprovider契約と合成fixtureで一覧・保存フローを検証する。各サブプロジェクトはUI・API・ +最初のRSSは[着手単位](feeds.md#実施段階)に従う。内蔵は簡易正本、本格運用はFreshRSS正本と +する方針を採用。接続先・版・資格情報は別途指定し、まずprovider契約と合成fixtureで一覧・ +保存フローを検証する。各サブプロジェクトはUI・API・ 保存・試験が揃った単位でコミットし、本番反映は別ゲートとする。 別セッションとの保存層の競合がある場合は、該当ファイルの作業境界を合意してから進める。 @@ -109,7 +110,7 @@ P0は認可・整合性・復旧の安全条件、P1は日常利用の回復性 | ID / 優先 | 状態・次の作業 | 着手ゲート・最初の検証 | 詳細 | | --- | --- | --- | --- | -| RSS-01 / P2 | 未実装・選定待ち:FreshRSS読取connector/newsboat橋渡し | 正本・対象版・接続先を選定。合成fixture→明示Wiki保存。表示だけで既読を書かない。ブログRSS配信とは別 | [RSS](feeds.md) | +| RSS-01 / P2 | 未実装・役割決定済み:内蔵簡易正本+本格運用のFreshRSS正本 | 共通UI、合成fixture→Wiki保存・タスク化。FreshRSSの接続先・版を指定して受入。newsboatは同じFreshRSSへ接続。二重正本・停止時の自動切替なし | [RSS](feeds.md) | | IMAP-01 / P3 | 未実装・選定待ち:IMAP読取同期 | provider/認証/保持を決める。UIDVALIDITY/UID、添付量、外部画像、失効をfixture化。neomutt captureは実装済みで別 | [メール](mail.md) | | TICKET-01 / P3 | 未実装:queue/番号/workflow/外部依頼者 | 共有範囲と状態遷移を定義、同時採番・失効・監査。既存個人タスクをticketと呼び替えない | [タスクとticket](tasks-tickets.md) | | EXT-01 / P3 | built-inのみ:第三者manifest/署名/隔離runtime、停止・rollback・観測 | capability・secret・host・予算・export契約。任意コードをGoプロセス内へ直接ロードしない | [拡張](extensions.md) |