# 建立業務指標定義知識庫

這是三個檔案的虛構指標練習：判斷 C-104 是否計入，檢查儀表板草稿，保留退款規則的未知狀態。

## 任務

只根據三個來源檔，定義每週活躍客戶數，判斷 C-104，並審查儀表板草稿。保留所有未知資訊，每個結論都用 [[filename]] 引用。

## 預期推理

依第 1 版定義，C-104 在週二行動時已付費且尚未取消，因此應計入；週四取消不會移除該週活動。草稿在週末篩選取消日期而錯誤排除，退款處理仍未知。

## 完整來源資料包

### Weekly active customer — revision 1 — weekly-active-customer-contract.md

```markdown
# Weekly active customer — revision 1
Owner: Growth Analytics
Window: Monday 00:00 through Sunday 23:59 UTC.

Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when cancellation is effective before the action timestamp; a cancellation after the action does not remove that week's activity. Exclude test accounts.

The contract does not specify how refund state changes this metric. Leave refund handling unknown.
```

### Qualifying customer actions — qualifying-actions.md

```markdown
# Qualifying customer actions

Count an event only when it has a customer_id and an event_at timestamp in UTC. The qualifying actions are: publish a reviewed knowledge page, complete a source review, or approve a revision for reuse.

Do not count a login, a page view, a failed import, or an event without customer_id. The action list does not define revenue, retention, or customer health.
```

### Existing dashboard query — draft — dashboard-query-draft.md

```markdown
# Existing dashboard query — draft
Status: owner approval pending
Window example: 2026-04-06 through 2026-04-12 UTC.

The draft counts distinct customer_id values with a qualifying action and a paid subscription, then filters out any customer whose cancellation_date is before the end of the week.

Example row: customer C-104 was paid and completed a qualifying action on Tuesday, then canceled on Thursday. The draft excludes C-104 because cancellation_date is inside the week. This query is a draft and is not an approved metric definition.
```

## Reference answer: count the action-time state, then flag the draft query

Under revision 1, C-104 counts because the customer was paid and not canceled at the Tuesday action; a Thursday cancellation does not remove that week's activity. The draft query incorrectly excludes any cancellation before week end and still needs owner approval. Refund handling is unspecified.

# Weekly active customer — reference

## Definition

Count distinct customer_id values with at least one qualifying action in the Monday-through-Sunday UTC window. A qualifying action is publishing a reviewed knowledge page, completing a source review, or approving a revision for reuse. Login, page view, failed import, and events without customer_id do not count. [[weekly-active-customer-contract.md]] [[qualifying-actions.md]]

At the action timestamp, the subscription must be paid and not canceled. A customer whose cancellation becomes effective after the action still counts for this revision of the metric. [[weekly-active-customer-contract.md]]

## C-104 and the draft query

C-104 counts in the example: the customer was paid and not canceled at the Tuesday qualifying action, while the Thursday cancellation happened afterward. The dashboard draft incorrectly removes C-104 by filtering cancellation_date at the end of the week. It is not an approved definition and needs the metric owner to reconcile its filter with the contract. [[weekly-active-customer-contract.md]] [[dashboard-query-draft.md]]

Refund handling is not specified by these sources. Keep it unknown rather than deciding whether a refund changes activity. [[weekly-active-customer-contract.md]]

## 變更後來源

### weekly-active-customer-contract.md

```markdown
# Weekly active customer — revision 2
Owner: Growth Analytics
Window: Monday 00:00 through Sunday 23:59 UTC.

Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when a cancellation becomes effective at any time during the window, even when the qualifying action happened before the cancellation. Exclude test accounts.

The contract does not specify how refund state changes this metric. Leave refund handling unknown.
```

## 變更預期

The revision changes the cancelled-but-paid case: C-104 no longer counts because the cancellation became effective on Thursday inside the measurement window, even though the qualifying action was on Tuesday. The reference must replace its action-time-only conclusion and the draft query's end-of-week exclusion is now consistent with this revised contract, subject to owner approval. Qualifying actions and unknown refund handling are unchanged.

## 審查邊界

分別核對行動時的付費與未取消規則、C-104 與週末篩選；保留退款處理未知，讓指標負責人確認草稿。

## 比較

單一指標契約可以用普通檔案檢查。當定義、排除條件、查詢草稿與後續修訂需要一起保持可檢視，又不能假裝公式已核准時，來源連結的指標 wiki 才有幫助。

## 閱讀本地化頁面

https://wenlan.app/zh-TW/learn/build-business-metric-definition-knowledge-base