# 調査・検証記録

## 調査基準

| 項目 | 記録 |
|---|---|
| リポジトリルート | `/mnt/hdd8tb/kk/works/bluem/CommunityAI/OKR/mock_okr_cai` |
| ブランチ | `main` |
| 対象コミット | `30b101f70ea31c11706ea148f7272fbc29053a69` |
| 履歴比較基準 | tag `v2026.09.29`、commit `eba90cd721d3905ae2d09ae05d2e8db94606259f` |
| 調査日時 | 2026-10-01 16:33 JSTから開始 |
| 重点再確認 | 9月29日時点と現在の業務PostgreSQL read・write・AI Worker処理、対象範囲、lock、CAS、pool admission |
| 開始時git status | `## main...origin/main`、変更なし |
| 既存の未コミット変更 | なし |
| 本成果物に含む未コミット変更 | `docs/architecture/`の資料一式と、デモ一覧の資料リンク定義 |
| 実環境へのアクセス | なし。外部照会、deploy、migration、メール送信、課金API、DB接続を実施していない |
| 秘密値・実データ | 読み込んでいない。実 `.env.local`、Git管理外env、credential、dump、利用者データを対象外にした |

ルート以下に追加の `AGENTS.md` / `AGENTS.override.md` は見つかりませんでした。submodule entryも確認されませんでした。

## 調査範囲

「精読」は該当ファイルの構成判断に必要な範囲を行単位で追跡、「検索確認」は全ファイル名の棚卸しとキーワード/import/entrypoint追跡、「除外」は生成物等を精読対象外にしたことを表します。

| 対象ディレクトリ／主なファイル | 方法 | 確認内容または除外理由 |
|---|---|---|
| ルート `README.md`、`package.json`、`package-lock.json`、`Dockerfile`、Compose群 | 精読・検索確認 | 4 workspace、build/run target、通常SaaS/demo/ops、production DBとruntime設定 |
| `.github/workflows/`、`.github/release/` | 精読・検索確認 | CI、immutable image、staging evidence、production approval、監視契約。production deploy本体は外部実行 |
| `config/` | 精読 | production/staging blue/green、PC deploy入力例、秘密値ではなく設定名と役割だけを利用 |
| `deploy/local-bluegreen/` | 精読 | systemd、HAProxy生成、cloudflared起動、Web/Worker container、drain/reaper |
| `deploy/production/`、`scripts/production/` | 検索確認・関連箇所精読 | 既存の単一runtime、PostgreSQL構築、isolated restore試験。blue/greenとの併存を記録 |
| `docker/` | 精読 | runtime secret file loadingとentrypoint。値は読まず契約だけ確認 |
| `okr-cai-saas/src/app/`（188 files、82 `route.ts`、48 `page.tsx`） | 全ファイル名棚卸し・route検索・主要route精読 | 公開/保護画面、auth、artifact、workflow、AI job、admin APIの入口からservice/storeまで追跡 |
| `okr-cai-saas/src/lib/` | import/通信/永続化を横断検索・主要実装精読 | proxy、session、Access、認可、PostgreSQL、AI job、OpenAI、最小化、diagnostics |
| `v2026.09.29`の`postgres-request-store.ts`、`db/postgres/repository.ts`、`reader.ts`、AI job実装 | `git show`で履歴精読 | revision別snapshot cache、組織共通advisory lock、全量read/clone、変更aggregate書込、AI文脈・結果反映のsnapshot依存 |
| 現在の`dashboard-reader.ts`、`profile.ts`、`workflow-collaboration.ts`、`ai-workflow.ts`、`ai-generation-jobs.ts`、`pool-admission.ts` | 精読 | 対象別read、entity transaction、row lock/CAS、対象AI graph、provider I/O分離、bounded admission |
| `okr-cai-saas/db/postgres/migrations/`（50 files） | 全migration名確認・主要schema精読 | 業務、session、artifact、workflow、AI、command/lease、file URL、auth floor、runtime制御 |
| `okr-cai-saas/deploy/`、`.env.local.example`、`package.json`、`next.config.ts` | 精読 | public host、Tunnel例、production/dev flags、PostgreSQL-only境界、依存関係 |
| `okr-cai-auth-worker/src/` と `migrations/`（16 files） | 全ファイル確認・entry/auth/storage/email精読 | Hono routes、password/OTP/reset、JWT/JWKS、D1、Email、Cron、rate limit |
| `okr-cai-auth-worker/wrangler.jsonc` | 精読（値を成果物へ転載せず） | env別Worker、D1/Email binding、Cron、observability。実resourceは未照会 |
| `okr-cai-saas-demo/` | manifest/entrypoint/flag検索 | 別workspace・build・sample runtimeであることを確認し、production主図から分離 |
| `docs/`（2085 files） | 全ファイル名・構成語検索、関連資料精読 | deployment、data inventory、backup試算、security、auth、規約/プライバシー、課題記録、旧構成資料を照合 |
| `scripts/` | 全ファイル名・deploy/backup/restore/CI語を検索、関連script精読 | production準備、promotion evidence、restore trial。定常backup jobは発見できず |
| `reference/` | 除外（名称と目的だけ確認） | 過去mock/design referenceで現行runtime根拠にしない |
| `.staging-rollbacks/`、ルート`tmp/`、各種`.next*`、coverage、storybook-static、test-results、e2e-results | 除外 | 過去作業退避、build/cache、生成物、試験結果。現行構成の一次ソースではない |
| `node_modules/`、各workspaceの`node_modules/` | 除外 | vendor codeは精読しない。manifest/lockfileで宣言を確認し、ローカル描画用の既存`sharp`だけ実行 |
| `.git/` | 内部除外、履歴を限定確認 | branch/SHA/statusと直近履歴だけ確認。最新commitだけを採用理由にはせず実装・設定も照合 |
| 実 `.env.local`、`config/*.inputs.env`、`.dev.vars`、credential、DB dump/volume | アクセスしない | 秘密値・実環境識別子・個人情報を取得しないため。example/schemaだけを使用 |

## 資料と実装の不整合

### C01: Cloudflareの取扱範囲

- 資料: `docs/legal/terms/02_かけあい_プライバシーポリシー_v1.6.md:103-113` は、Cloudflare利用を認証関連に限定し、相談内容・成果物の通信はCloudflareを経由しないと記載します。
- 実装・設定: `okr-cai-saas/deploy/cloudflared-config.example.yml:6-15` はapp/admin両hostを同じlocal Next.js originへ中継し、`docs/operations/bluegreen/local-bluegreen-deployment.md:3-21` は既存TunnelをHAProxyへ接続します。
- 図での扱い: 通常のWeb/API本文もCloudflare Edge/Tunnelを通るものとして描きました。Accessによる認証はadmin hostだけと分けています。
- 未解決: 法務文書を実装に合わせるか、ネットワーク経路を文書に合わせるかの判断が必要です。

### C02: backup保持

- 資料: プライバシーポリシー `:147-157` は復旧backupを3暦月保持とします。
- 設定例: `config/pc-deploy.inputs.example.env:62-73` は30日です。
- 実装確認: isolated restore trialとbackup要件/evidence contractはありますが、定常 `pg_dump`、base backup、WAL archive、schedulerに相当するproduction jobは見つかりませんでした。
- 図での扱い: backup storeを確定ノードにせず、データ表で「方針の不一致・実装/稼働未確認」としました。

### C03: production runtime方式の併存

- 既存経路: `compose.yaml:1-121` は単一の通常SaaS containerを定義します。
- 新経路: `deploy/local-bluegreen/` と `docs/operations/bluegreen/local-bluegreen-deployment.md:3-56` はWeb/Workerをblue/green分離し、HAProxyを固定originにします。
- 図での扱い: 直近追加のproduction用blue/greenを、実装とsystemd/configが揃った主対象として採用しました。ただし実配備は未確認で、単一runtimeを削除済みとは扱いません。

### C04: policy上の地域・provider保持とrepository証明範囲

- policyは国内自社server、D1 APAC、OpenAIの米国を含む処理、Access log 24時間、OpenAI abuse log最長30日等を説明します。
- repositoryから確認できるのは、接続先種別、`store:false`、D1 binding、minimization、設定名までです。実ホスト所在地、D1 jurisdiction、Access plan/log retention、OpenAI project data controls/DPAは管理画面・契約でしか確認できません。
- 図での扱い: 自社管理hostの国内所在やprovider保持を確定ラベルにせず、注記とデータ表で未確認にしました。

## 未確認事項と確認に必要な証跡

| 未確認事項 | 断定できない理由 | 確認に必要な資料・管理画面項目 |
|---|---|---|
| productionがblue/greenか単一runtimeか、active slot/台数 | 両方式の設定がrepoに併存し、hostへ接続していない | systemd status、稼働container一覧、承認済みplatform/release JSON（秘密値除外）、HAProxy state |
| production hostの所在地・所有責任 | policy記述だけで物理/VM配置を証明できない | hosting/asset台帳、契約、datacenter所在地、責任分界 |
| Cloudflare Tunnel route、Access application/policy | config例と検証コードだけでdashboard実値を証明できない | Tunnel public hostname→origin、Access app hostname/AUD、IdP/OTP、allowlist、MFA、session duration、plan |
| Auth Worker/D1/Emailのdeployed versionとresource分離 | `wrangler.jsonc` はdeploy結果ではない | Worker version/route、D1 binding/migration list/location、Cron、Email verified sender、secret namesの存在（値不要） |
| OpenAI project設定・契約・保持・学習利用 | `store:false` はAPI request設定で、provider account/contract全体ではない | project data controls、data sharing off、retention/ZDR/MAM status、DPA、subprocessor/region、key scope |
| PostgreSQL backup/PITR/offsite/復元実績 | 入力例・容量試算・trial scriptは定常運用を証明しない | backup scheduler、repository、暗号化、retention、WAL/PITR、直近成功記録、restore test、RPO/RTO |
| 集中log/alert/pagerの実運用 | contractとoptional operations profileはあるが外部manifestがない | log sink、retention、redaction sample、alert state、pager/on-call manifest、稼働agent |
| 外部ファイルのprovider/保持/権限 | アプリは任意HTTPS URLしか保持しない | 導入機関の保管サービス、ACL、保持/削除、リンク共有方針 |
| 実トラフィックでブラウザが行う外部通信 | sourceではsame-origin fetchと任意リンクを確認したが、実ブラウザ/CSP/拡張/外部設定は未観測 | production HAR/CSP report（個人情報除去）、DNS/Tunnel/edge log sample |

## 生成・機械検証

以下は成果物完成後に実行した結果です。

| 検査 | コマンド | 結果 |
|---|---|---|
| SVG/PNG・Markdown HTML再生成 | `node docs/architecture/tools/generate.mjs` | 成功。SVG 7枚、PNG 7枚、Markdown由来HTML 7ページを生成 |
| モデル・根拠・layout・安全性 | `node docs/architecture/tools/verify.mjs` | 成功。主図14 node/15 edge、8 stakeholder connection、補助図5 runtime view、62 evidenceのID・集約・endpoint、根拠path/line、node overlap、SVG metadata、PNG寸法、必須file、全ローカルlink/image、credential-like patternを検査 |
| PNG寸法 | verifier内の`sharp.metadata()` | stakeholder 2560×1440、engineer 2560×1600、5枚の補足図は各2560×1440 |
| JSON構文 | `node -e` / verifierのJSON parse | 成功 |
| ローカルHTML | Google Chrome 153.0.8010.36で`index.html`、データフローHTML、DB方式比較HTMLを開き、console/page error、画像、表、横overflow、見出しを検査 | 1440×1000、390×844でconsole/page error 0、root overflow 0、画像欠落0。mobileでは広幅の図と表だけを各枠内で横スクロール |
| 文書ナビゲーション | `index.html`の「データフロー」「DB方式比較」リンクから各説明ページへ移動 | 各ページのtitleとH1が「データの流れと保存先｜構成資料」「DB操作・処理の新旧比較｜構成資料」で一致することを確認 |
| ブラウザ実行制約 | 最初のsandbox内Chrome起動と、承認後のローカル限定再実行 | 初回はCrashpadの`setsockopt`制約でSIGTRAP。承認済みの昇格実行で、外部通信を行わず成功 |
| 視覚確認 | engineer、Blue-Green Deployment、データフロー、DB新旧図の生成PNGとHTML screenshotを実際に開いて確認 | 成功。文字化け、箱・文字の重なり、切れた矢印、曖昧な終点がないことを確認 |
| デモ資料同期・回帰試験 | `npm --prefix okr-cai-saas run sync:architecture-documents`、`npm --prefix okr-cai-saas-demo test` | 同期成功。demo構造検査とVitest 4 files／44 testsが全て成功 |
| 変更範囲 | `git diff --check`、`git status --short` | `docs/architecture/`、デモ資料一覧、デモ設計資料だけを変更 |

初版の主図トップページの目視記録は `verification-assets/index-desktop.png` と `verification-assets/index-mobile.png` です。今回のトップ／データフロー／DB方式比較ページのデスクトップ・モバイル確認画像は、リポジトリ外の `/home/tb/codex-tmp/architecture-data-flow-2026-10-01/` と `/home/tb/codex-tmp/architecture-db-comparison-2026-10-01/` に保存しました。

2026-09-29のデモ統合時には、build済みstandaloneでデモ一覧と構成資料トップを確認済みです。2026-10-01の更新では、資料同期とデモ回帰試験を実行し、生成HTMLはfile URLで再確認しました。検証scriptは文字の実レンダリング幅を完全には証明できないため、機械検査だけで完了とはせず、SVG/PNGとHTMLの視覚確認を別に実施しました。

## 再生成

```bash
node docs/architecture/tools/generate.mjs
node docs/architecture/tools/verify.mjs
```

外部ネットワークは不要です。共通内容は `architecture-model.json`、配置は `sources/layouts.mjs`、描画規則は `tools/generate.mjs`、Markdown HTML変換規則は `tools/render-markdown.mjs` にあります。