讓應用回報統計數字

適用：使用者說「我想讓主任看到這個工具的數字」「每個月要交報表」「想知道這個工具到底省了多少事」。

科室主管不會為了五個工具點進五個頁面。做法是：應用自己把算好的數字送給平台，

平台負責把它們擺在一起、依設定決定誰看得到，並在樣本太少時擋下來。

平台不做統計，只收數字。 怎麼算是應用的事——它才知道自己的資料長什麼樣。

一個指標長什麼樣

平台收的每一筆都是同樣的形狀，這個形狀來自團隊實際在用的 KPI：

欄位	是什麼	例子
`key`	這個數字的代號，固定不變（小寫英數與底線）	`specimen_rejection_rate`
`label`	人看的名字	`檢體退件率`
`unit`	`percent`／`count`／`rate`／`score`	`percent`
`period_kind`	`week`／`month`／`quarter`	`month`
`period_start`	那一段期間的第一天 `YYYY-MM-DD`	`2026-08-01`
`value`	數字本身	`2.4`
`sample_size`	分母：這個數字是從幾筆算出來的	`1840`
`visibility`	`owner`（只有負責人）／`unit`（採用這個工具的科室主管）／`public`（目錄上公開）	`unit`
`note`	一句話說明（選填）	`溶血佔六成`

鐵律：分母一定要送

sample_size 小於 5 的時候，平台一律不顯示數值，只顯示「資料太少」。

理由：三個人的小組裡「本月交換班次 2 次」等於指名道姓。

不送 sample_size 不會被擋，但那表示平台無法保護那筆數字——只要數字牽涉到人，就一定要送分母。

怎麼送

await fetch(`${PLATFORM}/api/v1/apps/${slug}/metrics`, {
  method: 'POST',
  headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
  body: JSON.stringify({
    metrics: [
      {
        key: 'specimen_rejection_rate',
        label: '檢體退件率',
        unit: 'percent',
        period_kind: 'month',
        period_start: '2026-08-01',
        value: 2.4,
        sample_size: 1840,
        visibility: 'unit',
        note: '溶血佔六成',
      },
    ],
  }),
});

只有應用的負責人或代理人送得出去（平台金鑰或在網頁上登入都可以）。
一次最多 100 筆，補過去幾個月的歷史可以一次送。
同一個 `key` 加同一個期間再送一次＝更正，不會變成兩筆。算錯了就重送。

數字從哪裡來

看應用的資料放在哪裡：

資料在平台的資料服務（UberTeach.data.*）：讀出來自己算。這是最單純的一種，

可以做一個「更新統計」按鈕，讓負責人自己按，或在應用載入時順手算上個月的。

資料在 Google 試算表或院內系統：應用怎麼讀資料，就怎麼算，算完再送。平台看不到那些資料。
純靜態、沒有資料的工具：那就沒有數字可送，不要為了送而送。

命名：先用這些，不夠再自己取

同一件事在不同工具裡叫不同名字，主管的頁面會變成一團亂。先看這裡有沒有：

`key`	`label`	`unit`
`uses`	使用次數	`count`
`users`	使用人數	`count`
`completion_rate`	完成率	`percent`
`on_time_rate`	及時率	`percent`
`rejection_rate`	退件率	`percent`
`error_rate`	錯誤率	`percent`
`pending`	待處理件數	`count`
`satisfaction`	滿意度	`score`

自己取的時候：小寫英數與底線、看名字就知道是什麼、取了就不要改（改了等於換一個指標，

舊的數字會留在原地變成孤兒）。

選 `visibility` 的判斷

owner：自己看的品管數字、還在試的指標。
unit：大部分的情況。採用這個工具的科室，它的主管看得到。
public：任何看得到這個應用的人都看得到。放在目錄上會讓工具更有說服力，但想清楚再開。

不要做的事

不要送個人層級的數字（某某人用了幾次、某某人的錯誤率）。平台的設計是工具層級的統計；

要看個人表現是另一回事，而且牽涉個資與人事，不是應用該自己決定的。

不要把病人資料放進 `label` 或 `note`（病歷號、診斷、姓名）。這兩欄會顯示在別人的畫面上。
不要每次使用者操作就送一次。指標是「一段期間的一個數字」，每天或每月送一次就夠了。

送完之後在哪裡看

負責人：應用管理頁的「這個應用回報的數字」。
科室主管：本科工具頁的「這些工具回報的數字」（只看得到採用中的工具、且 visibility 是 unit 或 public 的）。
每張卡片會顯示最新一期的數字、期間、分母，以及前幾期的走勢。

app-metrics

怎麼用