Skip to content

docs: align docs site and demo script with the 2:00 demo narration #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KCL1104 merged 1 commit into from
Sep 5, 2026
Merged

docs: align docs site and demo script with the 2:00 demo narration #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Mello 是企業 AI 採購的 orchestration（流程協調）平台，協助 AI A

## 核心功能

- **採購申請與服務探索**：輸入目標企業、預算與補充需求，選擇是否需要發票、是否需要 Mello Registry 認證；建立申請後，按「開始探索」比較服務。
- **採購申請與服務探索**：描述需求、設定預算並可附上文件，選擇是否需要發票、是否需要 Mello Registry 認證；建立申請後自動比對服務，不需再按探索。
- **人工選用與條件篩選**：勾選必要條件時，只顯示符合條件的服務；不限制時，列出服務並標示有無發票與有效認證。由使用者選用一個服務，再送出採購並開始付款。
- **企業付款控制**：檢查單筆／每日額度、供應商、網路與代幣限制，支援人工核准門檻、指定收款地址與凍結新付款。
- **付款、發票與對帳**：支援本機 Mock 與 Base Sepolia x402 測試網付款；串接交付結果、Demo 發票、對帳與稽核紀錄，發票失敗可獨立重試。
Expand Down Expand Up @@ -146,7 +146,7 @@ JS
npm run db:prepare --workspace @mello/api
```

此指令會套用 migrations、在空資料庫建立 Demo 公司／政策與 Seller A/B，並補上服務 C/D。既有公司與政策不會被初始化流程覆寫。四個服務共用兩個 Demo Seller，其中 B/C 支援 Demo 發票，A/D 不支援；初始化不會自動核發 Mello Registry 認證。
此指令會套用 migrations、在空資料庫建立 Demo 公司／政策與兩個 Demo Seller，並登錄個股分析、總經分析、加密市場資訊與期貨分析四項服務。既有公司與政策不會被初始化流程覆寫。四個服務共用兩個 Demo Seller，其中總經分析與加密市場資訊支援 Demo 發票，個股分析與期貨分析不支援；初始化不會自動核發 Mello Registry 認證。

**5. 分別啟動後端與前端**

Expand All @@ -169,7 +169,7 @@ npm run dev:docs

**6. 體驗與驗證**

登入後新增申請，例如目標企業填「範例企業」、預算填 `0.10 USDC`。本機首次操作請保留「需要發票」，取消「需要 Mello Registry 認證」，再依序操作「建立申請 → 開始探索 → 選擇 B 或 C → 送出採購並開始付款」。預設會模擬第一次發票失敗，可在案件頁重試發票並查看對帳結果。若要驗證認證篩選，請依 [認證管理流程](docs/BAZAAR_IMPLEMENTATION.md)另行建立服務審查紀錄。
登入後新增申請，例如需求說明填「我需要總經分析，關注亞洲市場利率與通膨」、預算填 `0.10 USDC`。本機首次操作請保留「需要發票」，取消「需要 Mello Registry 認證」，再依序操作「建立申請 → 等待服務比對 → 選擇總經分析 → 送出採購並開始付款」。預設會模擬第一次發票失敗，可在案件頁重試發票並查看對帳結果。若要驗證認證篩選，請依 [認證管理流程](docs/BAZAAR_IMPLEMENTATION.md)另行建立服務審查紀錄。

```bash
# 後端與 Sellers 啟動後，在另一個終端機檢查本機服務。
Expand Down Expand Up @@ -200,7 +200,7 @@ Base Sepolia 付款、鏈上存證、Bazaar 公開服務發現與 Railway 部署

## 限制與未來工作

- **服務與資料範圍**：目前支援 `credit_report`；報告由 Demo 程式產生，沒有串接真實徵信資料。後續擴充服務類型、供應商與真實資料來源。
- **服務與資料範圍**：目前提供個股分析、總經分析、加密市場資訊與期貨分析四項 Demo 服務；報告由 Demo 程式產生，沒有串接真實市場資料。後續擴充服務類型、供應商與真實資料來源。
- **發票尚為 Demo**：目前使用 Mock adapter，未完成正式台灣電子發票介接；ECPay Stage 僅預留設定。後續串接開立、作廢與正式財務對帳流程。
- **認證需人工管理**：加入目錄與取得有效認證是不同狀態。認證包含審查範圍、服務綁定與期限，並非自動 KYB，也不保證正式發票能力；後續完善審查、續期與撤銷工具。
- **付款與權限範圍**：目前提供 Mock／Base Sepolia Test USDC，尚未提供主網付款；採單公司共用工作區權限，尚無多租戶、SSO 或完整職務分權。
Expand Down
Binary file added apps/docs/public/diagrams/procurement-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions apps/docs/src/app/globals.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,22 @@ code {
padding: 5px;
font-weight: 400;
}
.doc-figure {
margin: 22px 0;
}
.doc-figure img {
display: block;
width: 100%;
height: auto;
border: 1px solid #dbe2d3;
background: #fff;
}
.doc-figure figcaption {
margin-top: 10px;
font-size: 12px;
line-height: 1.7;
color: #7e897d;
}
.mobile-doc-nav,
.mobile-toc {
display: none;
Expand Down
125 changes: 113 additions & 12 deletions apps/docs/src/content/documents.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import Image from "next/image";
import type { ReactNode } from "react";

export type Document = {
Expand All @@ -22,16 +23,77 @@ export const documents: Document[] = [
content: (
<>
<p>
付款成功，不代表企業完成了一筆採購。財務仍需要知道買了什麼、為何選用這家供應商、誰的預算被使用，以及收到的服務與發票是否和付款一致。
x402 讓服務可以直接透過 HTTP 收款，技術越來越完整，但企業仍然沒有入口：它解決了付款的程序，卻進不了現有的採購流程。付款成功不代表企業完成了一筆採購，財務仍需要知道買了什麼、為何選用這家供應商、誰的預算被使用，以及收到的服務與發票是否和付款一致。
</p>
<p>
Mello 是企業的 Agent Purchase-to-Pay
控制層：接收採購需求，以確定性政策約束執行，再把付款、交付、測試發票及對帳結果保存在同一個案件。
Mello 讓企業的 AI Agent 只選擇驗證過的供應商，並把從找標的、確認報價、付款到產出發票與對帳的每一步留在同一個案件。它是企業的 Agent Purchase-to-Pay
控制層：接收採購需求，以確定性政策約束執行，再把付款、交付、測試發票及對帳結果保存在一起。
</p>
<figure className="doc-figure">
<Image
src="/diagrams/procurement-flow.png"
alt="Mello 採購流程圖：需求、選供應商、付款、發票、對帳五個階段。x402 只涵蓋付款；Mello 補上供應商驗證、企業政策與額度、ERC-3009 授權憑證、統編發票與三方對帳稽核。"
width={1280}
height={720}
unoptimized
/>
<figcaption>
x402 解決付款那一段，Mello 讓它進得了整條採購流程。本次展示使用模擬結算與測試發票，未向財政部開立有效憑證。
</figcaption>
</figure>
<blockquote>x402 解決付款。Mello 把帳做完。</blockquote>
</>
),
},
{
id: "flow",
title: "五個階段，Mello 補上什麼",
content: (
<>
<p>
一筆企業採購會經過需求、選供應商、付款、發票與對帳五個階段。x402 涵蓋的是付款；其餘階段由 Mello 以工作區與後端政策接起來。
</p>
<div className="doc-table">
<table>
<thead>
<tr>
<th>階段</th>
<th>企業在意的事</th>
<th>Mello 提供</th>
</tr>
</thead>
<tbody>
<tr>
<td>需求</td>
<td>要發票、要認證、預算多少</td>
<td>需求說明與文件附加；統編、抬頭與成本中心沿用公司設定</td>
</tr>
<tr>
<td>選供應商</td>
<td>比價與資格</td>
<td>Mello Registry 認證、政策白名單與額度檢核，由人選用</td>
</tr>
<tr>
<td>付款</td>
<td>跨境、小額、按次</td>
<td>x402 付款；保存 EIP-3009（ERC-3009）授權憑證：限額、限收款地址、限時間</td>
</tr>
<tr>
<td>發票</td>
<td>統編、台幣金額</td>
<td>帶公司抬頭與統編的測試發票，保存示範匯率與台幣等值</td>
</tr>
<tr>
<td>對帳</td>
<td>入帳與稽核</td>
<td>付款、交付、發票三方比對，結果寫入稽核紀錄</td>
</tr>
</tbody>
</table>
</div>
</>
),
},
{
id: "roles",
title: "誰會使用",
Expand Down Expand Up @@ -92,7 +154,7 @@ export const documents: Document[] = [
content: (
<>
<p>
先從「採購操作」了解一筆案件的生命週期，再閱讀「政策與授權」及「付款、發票與對帳」。工程整合請看「系統架構」，能力邊界以「實作範圍」為準。
先從「採購操作」了解從公司設定到憑證的一筆案件生命週期，再閱讀「政策與授權」及「付款、發票與對帳」。工程整合請看「系統架構」，能力邊界以「實作範圍」為準。
</p>
<p>
本文件站是獨立的靜態說明，不讀取案件或付款資料，也不提供交易操作。
Expand All @@ -106,18 +168,32 @@ export const documents: Document[] = [
slug: "purchase-guide",
group: "使用指南",
title: "採購操作",
description: "從建立需求到查看憑證，每一筆申請都保留獨立案件編號。",
description: "從公司設定、建立需求到查看憑證，每一筆申請都保留獨立案件編號。",
sections: [
{
id: "setup",
title: "事前設定：公司、統編與政策",
content: (
<>
<p>
在「設定」填寫公司法定名稱、統一編號、預設成本中心、財務 Email 與發票收件資訊。新採購會保存這份資料的快照，供開立測試發票與對帳使用；頁面同時顯示 Base Sepolia 測試網的 USDC 餘額。
</p>
<p>
額度與供應商白名單屬於採購政策。「採購政策」頁顯示單筆與每日金額上限、發票要求與允許網路；「供應商」頁列出每項服務是否在政策白名單、是否有有效 Mello 認證與登錄的收款地址。這兩頁在工作區為唯讀，修改需透過後端受保護的管理操作；可操作的只有凍結或解除新付款。
</p>
</>
),
},
{
id: "create",
title: "建立採購申請",
content: (
<>
<p>
在「採購申請」選擇「新增採購申請」。在同一個需求區描述想找的服務，並可附上相關文件；不必指定企業。可搜尋個股分析、總經分析、加密市場資訊或期貨分析，每筆申請選用一項服務。
在「採購申請」選擇「新增採購申請」。在同一個需求區描述想找的服務，並可上傳相關文件（PDF、DOCX、TXT、MD）；不必指定企業。可搜尋個股分析、總經分析、加密市場資訊或期貨分析，每筆申請選用一項服務。
</p>
<p>
預算、發票與認證條件分別設定，公司抬頭、統一編號與成本中心沿用公司設定。建立後會自動尋找服務，但不會立即付款。附件先隨案件保存，目前搜尋依據是文字需求。
預算上限、是否需要發票、是否需要 Mello Registry 認證分別設定，公司抬頭、統一編號與成本中心沿用公司設定。按「建立申請」後 Agent 會自動比對服務並列出建議，但不會付款。附件隨案件保存供下載；目前搜尋依據是文字需求說明，系統不解析文件內容。
</p>
<div className="doc-example">
<span>需求範例</span>
Expand All @@ -134,18 +210,28 @@ export const documents: Document[] = [
},
{
id: "submit",
title: "確認並送出",
title: "人工審核候選清單並送出",
content: (
<>
<p>
建立申請後，案件會自動顯示服務比對結果。先選用服務，再按「送出採購並開始付款」；系統會重新核對報價、發票、認證與公司政策，通過後才執行付款。
建立申請後，案件會自動列出候選服務：服務與供應商名稱、報價、是否支援台灣發票（測試發票）、是否具有效 Mello Registry 認證，以及依公司政策的評估結果；來自 CDP Bazaar 公開目錄的候選也會標示認證狀態。由人確認供應商與報價後選用其中一項，再按「送出採購並開始付款」；系統會重新核對報價、發票、認證與公司政策，通過後才執行付款。
</p>
<p>
處理狀態由後端更新。可以離開頁面，之後由清單或同一案件網址繼續查看；重新整理不會建立新申請。
</p>
</>
),
},
{
id: "execute",
title: "執行採購與付款",
content: (
<p>
送出後，付款依 x402 協議進行：Agent 只在鏈下以 EIP-3009 簽署限定金額、收款地址與有效期間的授權，Seller 交由
Facilitator 驗證並結算，Agent 不需持有 gas，也無法超出授權範圍支出。案件會依序顯示付款授權、結算、服務交付、測試發票與三方對帳的進度；憑證欄位說明見「付款、發票與對帳」。
</p>
),
},
{
id: "review",
title: "查看處理依據",
Expand Down Expand Up @@ -303,6 +389,11 @@ export const documents: Document[] = [
授權與結算因此是兩份可以分別查核的證據：前者說明這筆支出當初被授權的範圍，
後者說明資金實際如何移轉。
</p>
<p>
對 Agent 而言，這份授權只限定一筆金額、一個收款地址與一段有效期間，並且只在鏈下簽署；Seller 將它交給
Facilitator 驗證與結算，Agent 不需持有 gas，也不可能超出授權範圍支出。流程圖與影片講稿稱它為
ERC-3009，與文件中的 EIP-3009 是同一份規格。
</p>
<p>
<code>SETTLED</code> 代表 Provider 已確認結算；若模式為
mock，它只是模擬結算，不是鏈上資金移轉。
Expand Down Expand Up @@ -339,6 +430,10 @@ export const documents: Document[] = [
產生測試發票。不得宣稱已向財政部開立有效發票，也不能當作正式報稅憑證。
</p>
</div>
<p>
測試發票帶入建立採購當時的公司抬頭與統一編號快照，並以結算的 USDC 金額換算新台幣等值。匯率取自後端設定的示範匯率（
<code>DEMO_TWD_PER_USDC</code>，預設 32.0），不是即時牌告匯率；匯率與台幣金額保存在發票紀錄，目前工作區畫面只顯示 USDC 金額。
</p>
<p>
發票號碼及狀態保存於採購。若狀態為可重試，使用「重試取得發票」只重跑發票工作，不重新發動採購付款。
</p>
Expand All @@ -350,6 +445,9 @@ export const documents: Document[] = [
title: "對帳與歸檔",
content: (
<>
<p>
對帳把付款結算、服務交付與發票視為三份獨立證據，比對付款識別碼、金額、收款方、代幣、網路與結算交易。比對項目與結果保存於對帳紀錄；對帳完成或不一致都會寫入稽核紀錄，可在「稽核紀錄」頁查閱。
</p>
<p>
<code>MATCHED</code> 表示付款、服務與發票經核對一致；
<code>MISMATCH</code> 表示存在差異，需要查看原始證據。
Expand Down Expand Up @@ -507,8 +605,9 @@ export const documents: Document[] = [
title: "已接通的產品流程",
content: (
<ul>
<li>採購清單、需求表單、保存後送出、案件詳情與狀態查詢。</li>
<li>供應商候選評估、後端政策執行、歷史政策快照。</li>
<li>採購清單、需求表單與文件附加、自動比對候選服務、保存後送出、案件詳情與狀態查詢。</li>
<li>候選評估並列報價、台灣發票能力與 Mello Registry 認證；後端政策執行、歷史政策快照。</li>
<li>公司與發票設定頁（法定名稱、統一編號、成本中心、發票收件資訊、測試網 USDC 餘額）；新採購保存抬頭與統編快照。</li>
<li>付款、服務交付、測試發票、對帳及稽核紀錄查閱。</li>
<li>依後端狀態提供發票／歸檔重試。</li>
<li>重新整理恢復同一案件，同一 task 的冪等重跑。</li>
Expand Down Expand Up @@ -541,7 +640,9 @@ export const documents: Document[] = [
title: "不在目前範圍",
content: (
<ul>
<li>正式電子發票及財政部有效開立。</li>
<li>正式電子發票及財政部有效開立；發票台幣等值使用設定的示範匯率，尚未接即時匯率。</li>
<li>附件內容解析：文件只隨案件保存與下載，搜尋依據是文字需求說明。</li>
<li>在工作區內編輯額度與供應商白名單：採購政策與供應商頁唯讀，僅付款凍結可操作。</li>
<li>跨 Agent、跨 task 同服務同標的的業務去重。</li>
<li>正式信用資料與徵信評等；現有信用報告仍為 Demo。</li>
<li>SSO、多租戶及正式財務職務分權管理。</li>
Expand Down
Loading
Loading