---
title: 專案平台化決策 — project 是插座不是插頭
brand: Guidant AI · **架構手冊**
eyebrow: 架構手冊 · FR-069 第四階段 · 決策說明（2026-08-31 拍板）
h1: 專案／任務層升格平台核心
lede: 這頁解釋一個關鍵決策：**project/task 層是「被所有功能插的插座」，不是「去用所有套件的插頭」**——依賴方向決定整個平台的成敗。寫給 PM 與決策者，30 秒抓到重點、細節在圖裡。
chips: [{text: 已拍板 2026-08-31, kind: ok}, {text: 落地棒 CM-1478, kind: accent}]
---

## 30 秒版 {#tldr nav="30 秒版"}

1. **未來圖景**：本產品走向平台——「專案＋任務」是骨架，稽核、問卷、檢測……都是掛上來的功能模組。
2. **關鍵決策＝依賴方向**：project 不 import 任何功能套件；是功能套件在安裝時**向 project 申報**「我提供這種任務、狀態機長這樣、頁面在哪」。方向弄反，每加一個功能都要改 project 一次，平台就死了。
3. **直接效益**：客戶流程差異（例如問卷要不要審核）從「客製開發」變成「設定開關」。
4. **flow_control 會被複用，而且分家正是複用的前提**：現在的 flow_control 混著「流程骨架」與「稽核規則」兩種料——切開後，流程骨架那包才是任何產品裝了都乾淨能用的東西（見 §4）。
5. **業界驗證**：ServiceNow／Jira／Odoo 全是這個蓋法。

## 為什麼依賴方向是生死線 {#direction nav="依賴方向"}

::: grid2
::: {.card .crit}
#### ❌ 錯的方向：project 當插頭
project 去 import 稽核、問卷、檢測……

- 每**新增一個功能**，都要回頭改 project
- project 變成全系統最大的依賴節點，誰都不敢動它
- 功能無法單獨安裝——project 綁死了全家
- 我們已經有這個病的小樣本：AI 儀表板 525 行手工登記簿，每抽一支套件要回改一次（正由 CM-1476 拆除）
:::
::: {.card .ok}
#### ✅ 對的方向：project 當插座
稽核、問卷、檢測……在安裝時向 project **申報**自己。

- project 只定義契約：「什麼是任務、任務有狀態、任務可綁一個功能頁面」
- 新增功能＝新套件自己 register，**project 一行不改**
- 客戶買什麼裝什麼，功能可選配
- 我們已驗證過這模式：jedi-iam 就是這樣掛進主程式的（裝一行有 39 條 API、拔一行全消失）
:::
:::

```{.mermaid cap="圖 1 — 依賴方向：所有箭頭指向平台，平台不認識任何功能"}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB'}}}%%
flowchart TD
  AUDIT["稽核插件<br/>（申報 audit 任務型別＋狀態機＋頁面）"] -->|register| PLATFORM
  SURVEY["問卷插件<br/>（申報 survey 任務型別＋審核狀態機）"] -->|register| PLATFORM
  DETECT["檢測插件<br/>（申報 detection 任務型別）"] -->|register| PLATFORM
  FUTURE["未來任何新功能<br/>（新套件，project 零改動）"] -.->|register| PLATFORM
  PLATFORM["🔌 project／task 平台層<br/>任務骨架＋狀態機引擎＋指派<br/>（不認識任何功能，只認契約）"]
  PLATFORM --> ENGINE["jedi-flow-engine<br/>（BPMN 流程執行引擎，純技術）"]
```

## 現況 vs 目標：flow_control 的三層拆解 {#threelayer nav="三層拆解"}

現在的 `flow_control`（約 24,600 行）把兩種東西焊在一起：**通用的**任務狀態推進邏輯，和**稽核專屬的**業務規則。所以問卷想要審核流程就得客製——狀態機是稽核專用的，別人借不到。

```{.mermaid cap="圖 2 — 左：現況（焊死）；右：目標（三層，通用半下沉為平台）"}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB'}}}%%
flowchart LR
  subgraph NOW["現況"]
    FC["flow_control 24,600 行<br/>通用狀態邏輯＋稽核業務<br/>焊死在一起"]
  end
  subgraph TARGET["目標（三層）"]
    A2["稽核插件<br/>（第一個 task type）"] --> T2["task／狀態平台層<br/>（從 flow_control 蒸餾出的通用半）"]
    S2["問卷插件<br/>（審核狀態機）"] --> T2
    T2 --> E2["jedi-flow-engine<br/>（BPMN 引擎，已存在）"]
  end
  NOW ==>|"CM-1478 分兩步：<br/>先拆出，再依設計下沉"| TARGET
```

## flow_control 的分家＝複用的前提 {#reuse nav="分家與複用"}

「流程類的東西應該可以複用」——**完全正確，分家就是為了做到這件事**。要對齊的只有一個認知：現在叫 flow_control 的 24,600 行，**不是整包都是流程**，裡面混了兩種料：

| | 例子 | 換一個產品還會一樣嗎？ |
|---|---|---|
| **流程骨架**（可複用） | 任務有狀態機、狀態怎麼推進、推進時通知誰、任務綁人／附件／功能頁 | ✅ 一樣——這就是要拔去 reuse 的 |
| **稽核業務規則**（不可複用） | 「POA&M 全部 closed 才能結束輪次」、覆核輪 clone 指派與證據、AP 階段前置條件 | ❌ 別的產品沒有 POA&M、沒有覆核輪 |

::: {.callout .warn}
**如果不分家、整包拔去別的產品會怎樣**

新產品裝完，包裡帶著 POA&M 檢查、稽核輪次、覆核 clone——用不到又拆不掉，改流程骨架還要繞著稽核規則走。**包裡混著別人用不到的東西，複用性就被拖死了。** 分家不是限制複用，是複用的前提。
:::

## 終局的包裝形態（2026-08-31 討論定案） {#packaging nav="終局包裝"}

| 層 | 終局形態 | 內容 |
|---|---|---|
| 技術地基 | jedi-common（既有） | session／查詢底座 |
| **業務地基** | **task 平台包**（吸收 jedi-project 種子＋flow_control 流程骨架半） | 專案／任務／狀態機／指派骨架——**被所有功能套件依賴、自己不依賴任何功能**；新產品裝了它就有專案任務骨架 |
| 流程引擎 | jedi-flow-engine（既有） | BPMN 執行，平台層的下游工具 |
| 功能插件 | 稽核（flow_control 的業務半）／問卷／檢測／AI 分類… | 各自向平台申報 task type，可選配 |
| 宿主（Guidant AI 本體） | 不打包 | 接線盤＋組裝設定＋readmodel 聚合櫃檯 |

**順序刻意「先蒸餾、後打包」**：4.2 先在主專案內把通用半與稽核半切開、跑穩，打包是最後一步也是最便宜的一步（第三階段已證明：邊界切乾淨後補殼是機械工）。先打包會把「哪些算通用」的判斷錯誤鎖進套件版號，改起來貴十倍。24,600 行裡切線怎麼畫，是 CM-1478 設計稿的主題——先審再動工。

## 第一個受益案例：問卷審核 {#survey nav="問卷案例"}

::: {.callout .decided}
**「客製」變「設定」的具體走法**

問卷套件申報自己的審核狀態機（作答 → 送審 → 核可／退回），狀態推進走平台層。客戶 A 要審核、客戶 B 不要？——**那是一個設定開關**（走「設定 schema 申報制」：套件申報開關、平台存值），不再是兩套客製程式。這是本決策對商務最直接的回報：**流程差異的交付成本從「開發案」降為「勾選項」。**
:::

## 對舊決策的影響 {#impact nav="決策影響"}

| 舊狀態 | 新狀態 |
|---|---|
| D15（boundary-map）：jedi-project「疆界待決、短期凍結」——吸收回主專案或平台化，兩邊門都不關 | **路 B 確立：project 升格平台核心**。凍結解除，方向寫死 |
| 4.2（CM-1478）：flow_control「先單純拆出、切分後議」 | 「切分」目標圖景定案（本頁圖 2）；動工仍分兩步，但每步朝三層終點 |
| 終局選項「等商業決策」 | 商業方向已表態（2026-08-31）：產品走平台路線，功能模組化掛在專案／任務骨架上 |
| flow_control 定位模糊（流程？稽核？） | **分家定案**：流程骨架半→併入 task 平台包、拔去其他產品複用；稽核規則半→自成功能套件。分家是複用的前提（見 §4） |

## 誠實的邊界（避免過度承諾） {#limits nav="邊界"}

- **這不是微服務**。現在是同一個程式內的插件（register 掛載）。疆界切乾淨是微服務的**前置**——切對了，日後把某支升級成獨立服務只是換運輸層；切錯了，微服務只會把耦合變成更難查的網路耦合。哪支值得服務化，照 D7 逐支評估（第一個候選：檢測平台）。
- **不是一棒到位**。CM-1478 先出三層設計稿給決策者拍板，才動工；動工先拆出、再逐步下沉。
- 平台層契約（任務型別怎麼申報、狀態機怎麼宣告）的細節，在 CM-1478 設計稿定，本頁只定方向。