visionA/docs/autoflow/04-architecture/db-integration-plan.md

visionA Backend 接資料庫 — 工時規劃文件（Man-hours / Man-day 估算）

項目	內容
文件目的	提供 visionA-backend 各 in-memory store 接資料庫持久化的工時估算，供主管對齊資源（man-day）、PM 排程、工程師排工使用。
適用範圍	visionA-backend 6 個現有 in-memory store 的持久化規劃。不含 cluster / converter_job 兩張未 wire 的表、不含 prod 環境另建 DB（見 §8 範圍外）。
狀態	規劃，未實作。本文件為工時估算與技術規劃，非實作紀錄，無任何 production code 變更。
產出者	Architect Agent
最後更新	2026-06-16
數字基準	子任務級 man-hours，1 人天 = 6.5 有效 hrs（見 §2 估算假設）。

---

Executive Summary（給主管）

一句話結論：把 visionA-backend 接 DB 的工程已被拆到子任務級並完成保守工時估算，整體區間 22–37.7 人天（視範圍）；其中約 80% 的 Go 端工作不需要等 DB 開好就能開工，等 DB 連線資訊只卡最後 1.5–4 天的 stage 收尾驗證。

三種範圍的 man-day 區間

範圍	包含內容	Man-day	累計 Man-hours	適用情境
最小可行（只 model）	DB 基礎建設 + 模型庫接 Postgres + 精簡驗證	7.8 – 13.5	51 – 88	使用者最關心：模型庫能持久化、重啟資料還在
持久資料	上述 + device + pairing/session token	16 – 27.4	104 – 178	所有業務持久資料上 Postgres（session 暫留 in-memory）
完整	上述 + session 接 Redis + 交易/韌性	22 – 37.7	143 – 245	全部持久化 + Redis session + 交易/韌性

區間下限 = 一切順利；上限 = 含 schema 細節踩坑與測試補齊。三種範圍皆已含「DB 基礎建設」與「一次 stage 驗證」。

測試占比

接資料庫需要完整的測試保障，測試占整體工時 約 45%（41%–48%），高於一般功能開發的 25–35%——因為接 DB 涉及 integration 測試（testcontainers 真 DB）、併發/連線失敗等邊界、以及既有 e2e 的回歸驗證。測試含三層（unit / integration via testcontainers / 邊界），詳見 §5。

兩個關鍵結論

1. DB 由他人開好、Go 端不受影響：DB 機器與 visionA 專用 database 由他人在 stage host（130）開好並提供連線資訊。visionA 端不負責 provision DB，但 Go 端所有工作（連線池、config、migration 撰寫、repository 實作、testcontainers 整合測試）一小時都沒省——這些跟「DB 誰開」無關。整合測試改用 testcontainers（本機/CI 一次性 DB），不依賴 130，更可靠。

2. 「等 DB」只卡最後收尾：拿到 DB 連線資訊前，最小範圍可做到「testcontainers 全綠」的程度（約 6.5–11 個工作天的活），只差最後 stage 接上驗證（1.5–2.5 天）。換句話說，只要範圍拍板，工程師可立刻開工，不會被「等 DB」block 大部分工作。

---

1. 背景與前提

1.1 為什麼這次接 DB 估得動

6 個 store 全部已有 Repository / Store interface + in-memory 實作，main.go 裡是乾淨的 6 個 NewInMemory* 呼叫點。接 DB = 加 Postgres/Redis 實作 + 換 1 行 wiring，interface 與所有 handler 不用動。這是估算偏可控的根本原因。

1.2 從零起手的部分（誠實交代）

go.mod 目前沒有任何 DB 依賴（pgx / redis / golang-migrate 皆無），migrations/ 目錄不存在，config.go 無 DB 設定區塊。因此「DB 基礎建設」（塊 0）是真的從零建：連線池、config、migration 工具、CI Postgres。

此外，pairing / session-token 兩個 store 目前用 plaintext 當 map key，接 Postgres 要改成 token_hash 當 PK（database.md §2.4 已是此意圖，code 已有 HashToken()）。這是邏輯改動、不是純 swap，塊 3 須特別小心。

1.3 ⚡ 關鍵前提：DB 由他人在 130 另開，visionA 不負責 provision

此前提很重要，避免讀者誤解「DB 現成可省一大塊」。

• stage host 192.168.0.130 是整個 stage 的 docker host（visionA / MC / FAA / converter / minio 都在上面）。
• 130 上已存在的 DB container 都屬於其他服務 / 專案，visionA 一個都不該共用。
• 130:5432 port 雖 OPEN 但不對應任何已知 container（來源不明），不採信為 visionA 可用。
• ✅ 已確認：會有人在 130 上幫 visionA 另外開好專用 DB（Postgres + 視需要 Redis），開好後提供連線資訊。

對工時的影響：

項目	visionA 端是否要做	說明
Provision DB 機器 / 起 container	不用（他人做）	省約 6–12 hrs
建 visionA database / 角色權限	不用（他人做，含在「給連線資訊」裡）	省約 2–4 hrs
連線池 / config / migration 撰寫	照樣要做	跟 DB 誰開無關
Repository 實作 + 整合測試	照樣要做	改用 testcontainers，不依賴 130

→ 一句話：省下的是「DB provisioning + database 建置 + 130 維運邊界」（約 10–20 hrs / 1.5–3 人天）；Go 端全部照做。 整合測試改用 testcontainers（本機/CI 一次性 DB），這比連 130 測試更可靠（CI 能跑、隔離乾淨），但 testcontainers 設置成本（約 9–17 hrs）如實算進塊 0。淨效果：最小範圍總工時主要被「接 DB 必要的完整測試」佔比推高，不是被「DB 誰開」推高。

---

2. 估算單位與假設（讓數字可信）

項目	設定	理由
基本單位	man-hours（人時），子任務加總 → 塊小計 → 範圍累計	細到子任務才能排工
Man-day 換算	1 人天 = 6.5 有效 hrs（非 8）	扣掉 context switch、PR 溝通、等 CI、開會、被打斷的真實 overhead
人力假設	1 位熟 Go、熟本 codebase 的 backend 工程師	interface 已在、有現成 in-memory 測試可對照
hours 已含	實作 + 三層測試 + 一輪 code review 修正	每塊獨立列「self-review + 過 Reviewer」子任務
hours 不含	跨團隊等待（拿連線資訊、他人開 DB）、需求變更、prod 另建 DB、CI 大改造意外	這些不可控、不放進工程估算
區間語意	下限 = 一切順利；上限 = 含 schema 細節（array、unique×soft-delete、hash key 切換）踩坑與測試補齊
測試占比較高	約 45%（一般功能 25–35%）	接 DB 需 integration + 邊界 + 回歸測試，屬必要工程成本，詳見 §5

塊 0 第一次做最貴：連線池、migration 機制、testcontainers、CI Postgres 都從零。完成後塊 1–3 每塊攤平、可偏區間低值。

---

3. DB 選型分工

對齊 database.md §2.7（「Session 不落 DB、Phase 1 考慮 Redis」）的既有立場。

3.1 放 PostgreSQL（持久業務資料）

Store	package	理由
modelRepo	internal/model	模型庫要長期保存、要查詢（List by owner/chip/source）、跨重啟不能掉。使用者最關心。
deviceRepo	internal/device	裝置綁定身分長期保存、有 owner/serial unique 約束、有關聯查詢需求。
pairingStore	internal/auth	配對 token 是「可撤銷的長期憑證」，要稽核（used_at/revoked_at），重啟不能掉。
sessionTokenStore	internal/auth	session token 90 天長效、可撤銷、要查 parent token 稽核鏈。

3.2 放 Redis（揮發 session，有 TTL、高頻讀寫）

Store	package	理由
userSessionStore	internal/usersession	瀏覽器 cookie session。高頻讀、有 idle/absolute TTL、掉了重登即可。Redis TTL 原生支援。
remote-proxy session	internal/session	tunnel session。特例：handle 是 process-local 活連線物件（yamux/WS），不能序列化進 Redis。 單節點維持 in-memory；多節點才需 Redis 存 Summary（handle 仍留本地）。

3.3 為什麼不全放 Postgres / 不全放 Redis

• 不全放 Postgres：cookie session 高頻讀寫 + 自然過期，Postgres 會變熱點、還要自己寫 cleanup job；Redis TTL 天生適配。
• 不全放 Redis：model/device/token 要關聯查詢、unique 約束、稽核、長期保存，Redis 做這些彆扭。
• 結論：持久業務資料 → Postgres；揮發 session → Redis，與 database.md 既有立場一致。

---

3.5 MySQL 版本估算（並列補充，不取代 PG 版）

本節為「若改用 MySQL 取代 PostgreSQL 作為持久業務資料庫」的並列工時估算，供主管在 DB 選型上對齊。§4 各塊與 §5 三範圍的數字仍以 PostgreSQL 為基準、不受本節影響；本節只估「換 MySQL 相對 PG 額外多出的工時（delta）」，並據此推出 MySQL 版的三範圍累計。Redis 部分（塊 4）與 DB 選型無關，delta = 0。

3.5.1 為什麼會有 delta：現有 schema 用了 5 項 PG 專屬特性

現有 database.md §4 的 6 張表 schema 是針對 PostgreSQL 設計的，以下 5 項是 PG 原生、MySQL 沒有或需另解的特性，換 MySQL 每一項都要改 schema + repository code + 測試：

#	PG 特性	用在哪	MySQL 對應做法	影響面
1	gen_random_uuid() UUID 主鍵	6 張表全用（users/devices/models/pairing_tokens/clusters/converter_jobs）	BINARY(16) + app 端產 UUID（推薦，省空間），或 CHAR(36) + UUID()	migration + repository 掃描/綁定欄位邏輯
2	CITEXT（大小寫不敏感唯一）	users.email	VARCHAR + collation（如 utf8mb4_0900_ai_ci）	migration（users 為 Phase 1 stub，影響小）
3	TEXT[] array 欄位	users.roles、models.classes、models.input_shape（INT[]）	MySQL 無原生 array → JSON 欄位（MySQL 8）+ repository 序列化/反序列化	delta 最大來源，集中在塊 1
4	JSONB	clusters.devices_json、params	MySQL JSON（無 JSONB binary 索引優化，功能足夠）	本期 cluster 未 wire（§8 範圍外），實際影響小
5	partial index WHERE deleted_at IS NULL	devices/models 軟刪唯一索引	MySQL 8 不支援 partial index → functional index 或全欄索引（略低效）或調整查詢	塊 1、塊 2 的 unique×soft-delete 語意

補充：本期實際 wire 的 6 個 store 中，array 特性集中在 model（塊 1）的 classes + input_shape 與 users.roles（users 為 Phase 1 stub）；JSONB 在 cluster（範圍外）。因此 delta 重心落在塊 1，其次塊 2/3 的 UUID 與 partial unique。

3.5.2 各功能塊 PG vs MySQL 工時對照

下表以 §4/§5 各塊的 PG 區間為基準，列出 MySQL 版的額外 delta（hrs，順利–卡關）與成因。delta 已含「對應的 schema 改動 + repository code + 測試補齊」：

塊	功能	PG hrs	MySQL delta	MySQL hrs	delta 主因
0	DB 基礎建設	20–36	+4–7	24–43	Go driver 換（pgx→go-sql-driver/mysql 或 GORM）、migration 工具 MySQL dialect、testcontainers 換 MySQL image + helper 調整
1	model 接 DB	22–36	+5–9	27–45	classes/input_shape 兩個 array→JSON 欄位 + 序列化/反序列化 + round-trip 測試重打；UUID 綁定；partial index 替代（functional index / 查詢調整）
2	device 接 DB	19–32	+3–5	22–37	UUID 綁定；UNIQUE(owner,serial)×soft-delete 的 partial unique 替代（MySQL 8 無 partial index）；雙狀態欄位 round-trip
3	pairing + session token	30–49	+2–4	32–53	UUID 處理（BINARY(16)/CHAR(36)）；token_hash PK 在 MySQL 的型別/索引處理（hash 切換邏輯本身不變）
4	session 接 Redis	19–32	+0	19–32	Redis 與 DB 選型無關
5	一致性/交易/韌性	20–35	+2–4	22–39	交易隔離級別預設不同：PG 預設 Read Committed、MySQL InnoDB 預設 Repeatable Read → 一次性 token MarkUsed、cascade 撤銷等併發行為需重新驗證（含 gap lock 行為差異）
6	stage 部署 + e2e 回歸	13–25	+1–2	14–27	MySQL 版 migration 跑 + 版本特性確認（JSON 型別、collation、functional index 支援，取代 PG 的 gen_random_uuid()/CITEXT 確認）
	全部加總	143–245	+17–31	160–276

delta 區間語意同主表：下限 = array/UUID/index 替代一次到位；上限 = JSON 序列化邊界、隔離級別行為差異、functional index 效能調校踩坑。測試估算框架沿用 §2/§5 既有原則（接 DB 的客觀整合/邊界/回歸測試需要），delta 中已含對應測試補齊、未額外拉高占比。

3.5.3 MySQL 版三種範圍累計（與 PG 版並列）

沿用 §5.2 的三範圍定義（含塊組成、塊 6 計法一致），套上各塊 MySQL hrs：

範圍	包含塊	PG 累計 hrs	PG Man-day	MySQL 累計 hrs	MySQL Man-day
最小可行（只 model）	0 + 1 + 6 精簡	51–88	7.8–13.5	60–102	9.2–15.7
持久資料	0 + 1 + 2 + 3 + 6 完整	104–178	16–27.4	119–204	18.3–31.4
完整	0+1+2+3+4+5+6	143–245	22–37.7	160–276	24.6–42.5

換算同 §2：1 人天 = 6.5 有效 hrs。最小範圍塊 6 取精簡值（6.1–6.4，含 MySQL +1–2 delta）；中間範圍不重複計塊 6。

3.5.4 結論：MySQL 比 PG 多多少、值不值得

整體 delta：MySQL 版相對 PG 版多 +17–31 hrs（約 +2.6–4.8 人天），以各範圍中位推算約 +11%~13%：

• 最小範圍：+9–14 hrs（約 +18%，因基數小、塊 0+1 的 driver/array delta 占比被放大）
• 持久資料範圍：+15–26 hrs（約 +14%）
• 完整範圍：+17–31 hrs（約 +12%）

→ 比先前粗估的「+10~20%」更收斂：範圍越大、delta 百分比越低（基礎建設與 array 的一次性 delta 被攤平），落在 +11%~18% 之間，整體中位約 +13%。

主要 delta 來源排序：

1. 塊 1（model array→JSON） — 最大，+5–9 hrs，因 classes + input_shape 兩個 array 欄位都要改 JSON 序列化。
2. 塊 0（driver/工具鏈換） — +4–7 hrs，一次性。
3. 塊 2（UUID + partial unique 替代） — +3–5 hrs。
4. 塊 5（隔離級別行為驗證） — +2–4 hrs，易被低估但攸關 token 一次性正確性。

中立建議（該不該換 MySQL）：

• ✅ 若團隊已有 MySQL 維運能力、或公司技術標準就是 MySQL → 這 +13% 的開發 delta 多半值得，因為能省下 PG 的維運學習成本、監控/備份工具重建、DBA 熟悉度等長期維運成本（這部分不在本工時表內，但實務上往往大於一次性的 +2.6–4.8 人天）。
• ⚠️ 若無特殊原因（團隊對兩者都不熟、或本來就用 PG） → 對「這個 schema」而言 PostgreSQL 更自然：array（classes/input_shape）、JSONB（cluster params）、partial index（soft-delete unique）三項都是 PG 原生、零 delta，換 MySQL 等於用額外工時把這些特性「降級模擬」回來。
• 本文件立場（中立）：純就「現有 schema 的契合度」與「一次性開發成本」看，PG 略優；但 DB 選型應由維運能力與組織標準主導，本節提供的是「換 MySQL 的開發成本帳」，不是選型結論。

---

4. 各功能塊子任務拆解 + man-hours

標記：🟢 = 拿到 DB 連線資訊前就能做（testcontainers 不依賴 130）；🔵 = 必須等 DB 連線資訊 / 真 DB 才能驗。

塊 0：DB 基礎建設（所有 Postgres 塊的硬前置）

#	子任務	hrs（順利–卡關）	依賴	標記
0.1	加依賴 pgx/v5（pgxpool）+ golang-migrate/v4，go.mod/go.sum 整理	1–2	—	🟢
0.2	config.DatabaseConfig（DSN/host/port/user/password/dbname/sslmode/pool size）+ env 解析 + Enabled() 模式 + .env.example	2–3	0.1	🟢
0.3	連線池 internal/db/pool.go（pgxpool 建池 + 啟動 ping + graceful shutdown）	2–4	0.1,0.2	🟢/🔵
0.4	migration runner（migrations/ + 啟動自動 migrate up 或獨立 cmd/migrate）+ 第一份骨架 migration	3–5	0.1	🟢
0.5	main.go wire 連線池（依 config 決定是否建池，本塊只接骨架）	1–2	0.3	🟢
0.6（測試）	整合測試基礎建設：testcontainers-go 設置 + 測試 helper（setupTestDB(t) 自動 migrate + truncate）+ fixture/factory builder	4–7	0.1,0.4	🟢
0.7（測試）	CI 接 Postgres：CI workflow 讓 testcontainers 在 CI 跑（Docker-in-CI）+ migration 跑通 + cache 調校	3–6	0.6	🟢
0.8（測試）	連線池/migration 本身測試（ping、migrate up/down 冪等、池耗盡、連線失敗 fail-fast）	2–4	0.6	🔵
0.9	整塊 self-review + 過 Reviewer + 修正	2–3	全部	🟢
	塊 0 小計	20–36

一次性最貴投資。「DB 由他人開好」讓 0.3/0.8 不用煩惱在 130 上裝/起 DB，但 testcontainers（0.6）成本如實算入。

塊 1：model 接 Postgres ← 使用者最關心

#	子任務	hrs（順利–卡關）	依賴	標記
1.1	PostgresModelRepository：Get/List(by owner/chip/source)/Save(upsert ON CONFLICT)/Delete(soft)	4–6	塊0	🟢
1.2	input_shape INT[] / classes TEXT[] pgx array 映射 + Source enum + upsert 保留 CreatedAt 語意	2–4	1.1	🟢
1.3	migration create_models（含 faa_object_key TEXT nullable — database.md §4 漏此欄；index：owner/chip/source、deleted_at IS NULL partial）	2–3	塊0	🟢
1.4	main.go wiring 切換（config 決定 Postgres/in-memory，保留 in-memory 給 local dev）+ seedDemoData 改寫進 DB	2–3	1.1,塊0	🟢
1.5（測試）	unit/邏輯：對齊既有 inmemory_repository_test.go（SaveAndGet、NotFound、List 三 filter、soft delete、Save 需 ID）→ Postgres 版重打	3–5	1.1	🟢
1.6（測試）	integration/真 DB：array round-trip、upsert 保留 CreatedAt、soft-delete 後 List 不含、List filter SQL 正確性、faa_object_key nullable round-trip	4–7	1.1,0.6	🟢
1.7（測試）	邊界：空 List、重複 Save、併發 Save 同 ID、連線中斷 Get 行為、context cancel	3–5	1.1,0.6	🟢
1.8	整塊 self-review + 過 Reviewer + 修正	2–3	全部	🟢
	塊 1 小計	22–36

model 欄位最多（array + FAA 欄位 + 3 維 filter），測試子任務（1.5–1.7）合計 10–17 hrs，偏重。

塊 2：device 接 Postgres

#	子任務	hrs（順利–卡關）	依賴	標記
2.1	PostgresDeviceRepository：Get/GetBySerial/List(by owner)/Save(upsert)/Delete(soft)	3–5	塊0	🟢
2.2	migration create_devices（雙狀態欄位 remote_status/last_seen_at/last_connected_at + UNIQUE(owner_user_id, serial_number)）	2–3	塊0	🟢
2.3	UNIQUE(owner,serial) × soft-delete 語意（已刪 serial 能否重註冊 → partial unique index WHERE deleted_at IS NULL）+ 決策註記	2–4	2.2	🟢
2.4	main.go wiring 切換 + seedDemoData device	1–2	2.1,塊0	🟢
2.5（測試）	unit/邏輯：對齊既有 device test（SaveAndGet、GetBySerial 跨 owner 不串、List by owner、soft delete、再刪回 NotFound、保留 CreatedAt）	3–5	2.1	🟢
2.6（測試）	integration/真 DB：unique 衝突、partial unique 讓已刪 serial 可重註冊、雙狀態欄位 round-trip、upsert 保留 CreatedAt	4–6	2.1,0.6	🟢
2.7（測試）	邊界：空 List、併發註冊同 serial、連線中斷、context cancel	2–4	2.1,0.6	🟢
2.8	整塊 self-review + 過 Reviewer + 修正	2–3	全部	🟢
	塊 2 小計	19–32

塊 3：pairing_token + session_token 接 Postgres

#	子任務	hrs（順利–卡關）	依賴	標記
3.1	PostgresPairingStore：Create/Validate/MarkUsed/Revoke/List/CleanupExpired	4–6	塊0	🟢
3.2	PostgresSessionTokenStore：Create/Get/Revoke/CleanupExpired（含 parent_token_hash 稽核鏈）	3–5	塊0	🟢
3.3	關鍵改動：plaintext→token_hash 當 PK。Validate/Get 先 HashToken() 再查；確保所有呼叫端傳 plaintext 進、內部一致 hash	3–5	3.1,3.2	🟢
3.4	migration create_pairing_tokens（pairing + session token 是否共表 by kind — 需決策，傾向共表；含 used_at/revoked_at/expires_at/parent_token_hash + index）	2–4	塊0	🟢
3.5	main.go wiring 切換（兩個 store）+ seedDemoData pairing token	2–3	3.1,3.2,塊0	🟢
3.6（測試）	unit/邏輯（pairing）：對齊既有 test（CreateAndValidate、unknown token、MarkUsed 一次性+冪等、Revoke、CleanupExpired、List by user、Validate expired）	3–5	3.1	🟢
3.7（測試）	unit/邏輯（session token）：對齊既有 test（CreateAndGet、NotFound、expired、Revoke 冪等、Revoke NotFound、CleanupExpired、NeverExpires ttl=0）	3–5	3.2	🟢
3.8（測試）	integration/真 DB：hash 當 PK 查詢正確性、TTL 過期、一次性 used 的 DB 層 race（兩併發 MarkUsed 只一成功）、撤銷稽核欄位、共表 kind 隔離	5–8	3.1,3.2,0.6	🟢
3.9（測試）	邊界：併發 Validate 同 token、CleanupExpired 大量資料、連線中斷、context cancel	2–4	0.6	🟢
3.10	整塊 self-review + 過 Reviewer + 修正	3–4	全部	🟢
	塊 3 小計	30–49

Postgres 三塊裡最重：兩個 store + plaintext→hash 邏輯切換（漏一個呼叫端就驗不過）+ 一次性語意的 DB 層併發正確性測試。測試子任務（3.6–3.9）合計 13–22 hrs，反映「token 語意錯會出安全問題」的保守估法。

加註（不在本塊預設範圍）：remote-proxy 目前只驗 token 格式不查 store。若 Phase 1 要新增 GET /internal/session-token/:token 給 remote-proxy 拉驗證 → 另 +4–7 hrs，不含在塊 3 小計。

塊 4：session 接 Redis（userSession；tunnel session 維持 in-memory）

⚠️ 此塊需 Redis。若本期不做塊 4，可叫他人先不用開 Redis，只開 Postgres。測試用 miniredis（純 Go in-process）或 testcontainers Redis，不依賴 130。

#	子任務	hrs（順利–卡關）	依賴	標記
4.1	加依賴 redis/go-redis/v9 + config.RedisConfig（host/port/password/db index）+ env + .env.example + Enabled()	2–3	—	🟢
4.2	internal/db/redis.go 連線 + 啟動 ping + graceful close	1–3	4.1	🟢/🔵
4.3	RedisUserSessionStore：Create/Get/Update/Delete/CleanupExpired，用 Redis TTL（idle + absolute 雙 TTL）取代手動 cleanup goroutine；Extra map JSON 序列化	4–6	4.1,4.2	🟢
4.4	main.go wiring 切換 + 移除/停用 runUserSessionCleanup goroutine（改靠 Redis TTL）	1–2	4.3	🟢
4.5（測試）	unit/邏輯：對齊既有 usersession test（CreateAndGet、NotFound/EmptyID、Get 回副本、Update 移 LastSeenAt 不動 CreatedAt、Update NotFound/Nil、Delete 冪等、Extra round-trip、context cancel）	4–6	4.3	🟢
4.6（測試）	integration/真 Redis：TTL 實際過期、idle vs absolute 雙 timeout、序列化 round-trip、key 命名/隔離	3–5	4.3	🟢
4.7（測試）	邊界 + 併發：race detector、Redis 連線中斷 store 行為、TTL 邊界	2–4	4.3	🟢
4.8	整塊 self-review + 過 Reviewer + 修正	2–3	全部	🟢
	塊 4 小計	19–32

tunnel session（internal/session）value 是活的 yamux Handle 不可序列化 → 維持 in-memory（單節點），本塊不動。跨節點「Summary 放 Redis、handle 留本地」列範圍外（要的話另估 +13–26 hrs ≈ 2–4 人天）。

塊 5：一致性 / 交易 / 連線韌性 / 健康檢查

#	子任務	hrs（順利–卡關）	依賴	標記
5.1	internal/db/tx.go 交易 helper（pgx tx 包裝 + rollback on error + context）	2–4	塊0	🟢
5.2	跨 store 交易：建 Device + PairingToken 同 tx、刪 Device cascade 撤銷 token、converter job 完成→建 model transactional upsert	4–7	5.1,塊1-3	🟢
5.3	連線韌性：pool retry / context timeout / 斷線重連 / fail-fast vs degrade 策略（策略需使用者裁決）	3–6	塊0	🟢
5.4	/healthz 擴充 DB/Redis ping + 統一 pgx error → internal/api/errors.go 映射	2–4	塊0	🟢
5.5（測試）	交易測試：rollback（中途失敗整筆回滾）、cascade 撤銷 token 交易邊界、併發交易	4–6	5.2,0.6	🟢
5.6（測試）	韌性測試：連線中斷模擬、timeout、健康檢查回應（DB down 時 /healthz 行為）	3–5	5.3,5.4,0.6	🟢
5.7	整塊 self-review + 過 Reviewer + 修正	2–3	全部	🟢
	塊 5 小計	20–35

區間寬反映「做到多嚴謹」的彈性：最小只做 /healthz + 基本 tx（取下限），完整韌性策略（retry/degrade/cascade 全做）取上限。

塊 6：stage 部署接 130 + e2e 回歸驗證

#	子任務	hrs（順利–卡關）	依賴	標記
6.1	拿到他人開好的 DB 連線資訊後：.env.stage 注入 DSN/憑證（走既有 secrets 機制，不進 repo）	1–2	DB 連線資訊	🔵
6.2	在 130 的 visionA database 跑 migration + 確認 PG 版本支援 gen_random_uuid()/CITEXT（不支援則調 migration）	2–4	6.1	🔵
6.3	stage 部署設定 / compose / CI 部署步驟接上 DB env	2–3	6.1	🔵
6.4（測試）	e2e 持久化驗證：登入(OIDC)→配對→上傳 model→列 model→重啟 backend→資料還在（核心驗收）+ 空庫/seed 啟動正常	3–5	6.2,6.3	🔵
6.5（測試/回歸）	回歸測試：接 DB 後既有 e2e/integration（約 6+ 檔）重跑，修因持久化行為改變而壞的測試	4–8	6.2	🔵/🟢
6.6	部署驗證彙報 + 修 stage 特有問題	1–3	全部	🔵
	塊 6 小計	13–25

6.5 回歸測試刻意估寬（4–8 hrs）：既有 6+ 個 e2e/integration 測試檔，接 DB 後「重啟資料還在」「seed 行為」「token hash 切換」都可能讓 in-memory 假設失效，要逐一確認。這是接 DB 回歸驗證的必要成本。

---

5. 工時總表與測試占比分析

5.1 各塊 man-hours 總表

塊	功能	hrs（順利–卡關）	換算 Man-day（÷6.5）	DB	主要依賴
0	DB 基礎建設（連線池/config/migration/testcontainers/CI）	20–36	3.1–5.5	PG	—
1	model 接 Postgres（含 FAAObjectKey）	22–36	3.4–5.5	PG	塊0
2	device 接 Postgres	19–32	2.9–4.9	PG	塊0
3	pairing + session token 接 Postgres	30–49	4.6–7.5	PG	塊0
4	session 接 Redis（userSession）	19–32	2.9–4.9	Redis	—（與塊0平行）
5	一致性/交易/韌性/健康檢查	20–35	3.1–5.4	PG	塊1–3
6	stage 部署接 130 + e2e 回歸驗證	13–25	2.0–3.8	PG+Redis	想驗的塊
	全部加總	143–245	22–37.7

5.2 三種範圍累計

範圍	包含塊	累計 hrs	Man-day	說明
最小可行（只 model）	0 + 1 + 6 精簡（只跑 6.1–6.4 約 9–16 hrs）	51–88	7.8–13.5	模型庫持久化 + 驗證重啟資料還在。塊 0 是硬前置。
持久資料	0 + 1 + 2 + 3 + 6 完整	104–178	16–27.4	業務持久資料上 Postgres。session 仍 in-memory（內測可接受）。
完整	0+1+2+3+4+5+6	143–245	22–37.7	全部持久化 + Redis session + 交易/韌性。tunnel 多節點 summary 範圍外（另 +13–26 hrs）。

三種範圍皆已含塊 0 與一次塊 6 驗證；中間範圍不重複計塊 6。最小範圍的塊 6 只跑 6.1–6.4（不含完整回歸 6.5），故取精簡值。

5.3 測試占比分析

塊	測試子任務	測試 hrs	該塊總 hrs	測試占比（中位）
0	0.6+0.7+0.8	9–17	20–36	~46%
1	1.5+1.6+1.7	10–17	22–36	~47%
2	2.5+2.6+2.7	9–15	19–32	~47%
3	3.6+3.7+3.8+3.9	13–22	30–49	~44%
4	4.5+4.6+4.7	9–15	19–32	~47%
5	5.5+5.6	7–11	20–35	~33%
6	6.4+6.5	7–13	13–25	~53%

• 純測試子任務加總：64–110 hrs。
• 總工時：143–245 hrs。
• 測試占比 ≈ 45%（中位），範圍 41%–48%。

一般功能「測試占 25–35%」是常態；本估約 45%，反映接 DB 所需的三層測試（integration/邊界/回歸）+ testcontainers 一次性基礎建設。testcontainers/CI 一次性基礎建設（塊 0 的 9–17 hrs）是大頭——做一次、後續所有塊共用。若日後評估「測試估太保守」，最先可砍各塊「邊界」子任務的卡關上限，但不建議砍 integration 與回歸（那是「重啟資料還在」的核心保證）。

---

6. 可先做（不卡 DB）vs 等 DB 的劃分

6.1 拿到 DB 連線資訊前「就能先做」（🟢，約 80% 工作）

• 塊 0：加依賴、config、連線池建池邏輯、migration runner+骨架、main.go 接骨架、testcontainers 設置、CI Postgres。
• 塊 1/2/3：全部 repository 實作 + migration 撰寫 + 全部測試（unit + integration via testcontainers + 邊界）。testcontainers 自己起一次性 DB，完全不依賴 130。
• 塊 4：全部（miniredis / testcontainers Redis）。
• 塊 5：tx helper、韌性邏輯、health 擴充、交易測試（testcontainers）。

→ 拿到連線資訊前，最小範圍（塊 0+1）可做到「testcontainers 全綠」（約 6.5–11 個工作天的活），只差最後 stage 接上驗證。

6.2 必須等 DB 連線資訊 / 真 DB（🔵）

• 塊 0：0.3 連真 DB ping 確認、0.8 對真 DB 測試（可先用 testcontainers 跑、再對 stage DB 確認一次）。
• 塊 6：整塊（注入憑證、在 130 跑 migration、部署設定、e2e、stage 回歸、彙報）—— 這是唯一硬卡 DB 連線資訊的塊。

---

7. 排程建議（假設 1 個 backend 全職）

7.1 依賴關係（哪些可平行）

塊0（基礎建設）──┬──► 塊1（model）──┐
                ├──► 塊2（device）─┤
                ├──► 塊3（token）──┼──► 塊5（交易/韌性，需塊1-3）
                                   │
塊4（Redis）─────（與塊0平行，獨立）─┘

塊6（stage 驗證）◄── 拿到 DB 連線資訊 + 想驗的塊完成

• 塊 0 是所有 Postgres 塊的硬前置，必須先做。
• 塊 4（Redis）可與塊 0 平行（依賴獨立）—— 單人全職時意義不大，列為「若有第二人可平行」。
• 塊 1/2/3 在塊 0 完成後可任意順序，使用者最關心 model → 建議塊 1 優先。
• 塊 5 需塊 1–3 的 store 都在才能做跨 store 交易。
• 塊 6 卡 DB 連線資訊（唯一硬卡外部）。

7.2 最小範圍（塊 0+1）單人全職時程

階段	子任務	工作天（×6.5hr/day）
第 1 階段（拿連線資訊前可做）	塊0 全部 🟢（20–36 hrs）+ 塊1 全部 🟢（22–36 hrs，testcontainers 全綠）	6.5–11 天
第 2 階段（拿到連線資訊後）	塊6 精簡（6.1–6.4，9–16 hrs）+ 塊0 真 DB 確認	1.5–2.5 天
最小範圍合計		約 8–13.5 個工作天

第 1 階段（6.5–11 天的活）完全不卡 DB——只要拍板做最小範圍，backend 可立刻開工做到 testcontainers 全綠，等他人把 130 的 DB 開好、給連線資訊，再花 1.5–2.5 天接上 stage 驗證收尾。「等 DB」不會 block 大部分工作。

7.3 持久資料範圍單人全職時程

• 第 1 階段（拿連線資訊前）：塊 0+1+2+3 全部 🟢 ≈ 91–153 hrs ≈ 14–24 天。
• 第 2 階段（拿到後）：塊 6 完整（含回歸 6.5）≈ 13–25 hrs ≈ 2–4 天。
• 合計 約 16–28 個工作天。

---

8. 範圍外（本估算未計入）

要做再另加，不含在上述任何範圍：

項目	估算	說明
cluster / converter_job 兩張表	未估	目前 main.go 無對應 in-memory store 被 wire（converter 是 stub、cluster 只有 types）
remote-proxy /internal/session-token 驗證 endpoint	+4–7 hrs	目前 remote-proxy 只驗 token 格式不查 store
tunnel session 多節點 Redis summary	+13–26 hrs（2–4 人天）	handle 不可序列化，需「Summary 放 Redis、handle 留本地」混合實作
prod 環境另建 DB	未估	prod 是否用 130 或另一套（RDS/Cloud SQL/自建）未定，影響韌性/HA/成本

---

9. 待提供 / 待決策清單

9.1 待他人提供的 DB 連線資訊（開好後請給）

項目	為什麼需要	阻塞
Postgres：host / port / user / password / dbname	塊 6 連線（config 可先用 placeholder 寫好）	塊 6
PG 版本	影響 gen_random_uuid()（需 PG13+ 或 pgcrypto）、CITEXT extension → 影響 migration 寫法	塊 6.2
sslmode（disable/require/verify-full）	DSN 組裝	塊 6.1
visionA database 是否已建好、app role 權限	確認 migration 能跑、有無建 extension 權限	塊 6.2
Redis：有無開、host/port、有無密碼	決定塊 4 是否本期做；若不做可叫他人先不開 Redis	塊 4、塊 6

9.2 待使用者決策（影響估算/設計）

#	項目	影響
1	範圍：最小 / 持久資料 / 完整？session→Redis 本期做嗎？	決定總工時與要不要請他人開 Redis
2	session token 與 pairing token 是否共表（by kind）？	塊 3.4 schema
3	DB 掛掉降級策略：fail-fast(503) 還是 degrade？	塊 5.3 韌性
4	已 soft-delete 的 device serial 能否重註冊？	塊 2.3 partial unique index
5	remote-proxy 是否本期要 /internal/session-token 驗證 endpoint？	塊 3 加註（+4–7 hrs）

---

10. 給 Orchestrator 的後續建議（database.md 更新，本文件未動）

以下為 database.md（共享文件）應同步更新的缺口，建議另派 Architect 處理，不在本工時估算內。

1. §2.3/§4 models table 補 faa_object_key TEXT（nullable）—— code 已有（ADR-017），schema 漏。
2. §4 補 DatabaseConfig / RedisConfig env 規格（DSN/pool/sslmode/redis password）。
3. §5 補 migration 第一份清單（哪些 table 在第一個 migration）。
4. （可選）§2.7 補 tunnel session「handle 不可序列化、單節點維持 in-memory」結論。
5. 若 database.md 提及「DB 在 130 現成可用」字眼，需更正為「DB 由他人在 130 另開 visionA 專用實例並提供連線資訊；visionA 端不負責 provision，只負責跑 migration 與接上」（與 §1.3 前提一致）。