為什麼要一個 App

人在外面，手上一張剛拿到的名片，要當場用手機拍、當場入庫。

說明：因為 Apple 建置 app 要花錢，所以只弄 andriod app. (不過很快，Andriod 也要認證才可以了)

先弄一台 andriod 建置機

Flutter 與 Android 的工具鏈很大，不適合裝在主控制那台上。另外準備一台 Ubuntu 建置機，裝 Flutter 3.44.8、Dart 3.12.2、Android SDK 36、JDK 17，還有 adb。一台 Android 實機，平板或手機，用 USB 接在這台上andriod 建置機，讓 adb 可以看得到它，裝 APK、看 log 都走這條線。做法是寫完 rsync 到建置機，在建置機上跑 flutter analyze 與 flutter build apk，測試過了才算。這個迴圈一開始就要通：第一天先做一個空殼 App，build 出 debug APK，裝到實機上打開，確定工具鏈是活的，再開始寫功能。

告訴 claude：

準備一台 Android 建置機：Ubuntu，裝 Flutter、Dart、Android SDK、JDK 17、adb。
一台 Android 實機用 USB 接上去，adb devices 要看得到它。
控制台這台⛔ 不裝 Flutter：程式在這裡寫，rsync 到建置機，在那邊跑 flutter analyze 與 flutter build apk。
第一件事：建一個空殼 App，build 出 debug APK，adb install 到實機上打開。
⛔ 這一步沒通之前不要寫任何功能。

注意：一把不能弄丟的鑰匙

release 版的 APK 要簽章，簽章用一把 keystore 金鑰。這把金鑰在建置機上，不進 git。Android 的規矩是：已經裝在手機上的 App，只認同一把金鑰簽出來的更新。金鑰弄丟了，這個 App 永遠不能再更新，只能請每一個使用者解除安裝重裝。為了這把金鑰，建置機一定要備份。這台機器單獨保護一份映像備份檔，不跟著日常的備份輪替。規則：金鑰生出來的那一天就決定它的備份放哪裡。它是整個 App 裡唯一不能重建的東西。

App 要做的事

名片 App 不需要自己的後端，它連接是昨天那一套 名片系統，跟網頁版同一套。要做的事情就這幾件：登入，token 存在手機的安全儲存區，過期了自動續期，使用者不會被踢出去；名片列表、詳情、編輯；拍照、裁切、送 OCR、確認、入庫；用講的搜尋；把一張名片匯出到手機聯絡人。API 的網址做成可以改的設定，預設指到 namecard.iron30.com。App 要跟手機要四個權限：網路、相機、讀聯絡人、寫聯絡人。

告訴 claude：

名片系統的 Android App，打昨天那套 API（https://namecard.iron30.com/api/v1），⛔ 不要另外寫後端。
- 登入：token 存 secure storage；401 就自動 refresh 再重試一次，使用者不會被踢出去
- 名片：我的名片 / 公司名片庫、搜尋、排序、詳情、編輯，權限規則與網頁版完全一樣
- 拍照：正面必填、反面選填、人頭照選填；拍照或從相簿選；拍完可裁切旋轉；
  送 OCR → 確認頁（OCR 結果只是草稿，人改完才存）→ 入庫
- 搜尋：一個聊天框，打同一個 chat API
- 匯出到聯絡人：單筆、單向；寫入前用姓名 + 電話或 email 查重，命中要問「新增或略過」；拒絕權限就停用並說明
- API 網址做成可改的設定，預設 namecard.iron30.com
權限只要四個：網路、相機、讀聯絡人、寫聯絡人，⛔ 一個都不准多要。
🔴 release 簽章的 keystore 放建置機，⛔ 不進 git，⛔ 不貼回對話。
驗收：release APK 在乾淨實機裝得起來、登得進正式站。

裝到手機上

裝好之後的桌面：名片 App 的圖示還是 Flutter 預設的那一個，先能用再說

build 出來的 release APK 是 56MB。用 adb 裝，或者把檔案傳到手機上點開裝。第一次裝要允許來自未知來源的 App，因為它不是從商店來的。裝好之後桌面上多一個名片 App，圖示還是 Flutter 預設的那一個，沒換。這件事不重要，先讓它能用。規則：先能用，再好看。圖示、動畫、啟動畫面都放到最後。

首頁：四件事

App 首頁：帳號與角色在上面，名片、搜尋、拍照、上傳四件事；右上角是外觀、深色模式、登出

打開 App 是首頁：上面是自己的帳號與角色，下面四個：名片、搜尋、拍照、上傳。右上角三個東西：外觀、深色模式、登出。拍照被放在首頁第一層。一開始它藏在名片列表的右上角，實際拿去用一次就發現：現場掏出手機要按三下才能開相機，太慢。改成首頁一格。規則：最常做的那件事，放在打開 App 之後的第一下。

外觀：這支手機自己的

外觀：六個顏色跟網頁版一樣，但只套用在這支手機；淺色、深色、跟隨系統三選一

外觀頁可以選主題色，六個顏色跟網頁版一樣，但這裡選的只套用在這支手機上。網頁版是管理員定全站，手機是自己定自己的。也可以按一下跟隨全域設定，回到管理員定的那個顏色。淺色、深色、跟隨系統三選一。規則：全站的設定在 server，個人的偏好在裝置。手機上的外觀是個人的，不該回寫到 server。

名片列表

我的名片：搜尋、排序、每頁幾筆；右上角的相機是拍照捷徑，右下角新增名片

名片頁兩個分頁：我的名片、公司名片庫，跟網頁版一樣。搜尋欄、排序、每頁幾筆都有。右上角一顆相機，是拍照的捷徑；右下角一顆新增名片。在手機上看清單，一列一列比方塊好，一眼看到姓名與公司就夠了。規則：手機上的列表只放兩行資訊。細節留給詳情頁。

公司名片庫：跟網頁版同一份資料，一列兩行，姓名與公司

名片詳情

名片詳情：圖在最上面，正面與人頭照，再往下才是中文資訊、英文資訊、聯絡方式；右上角有共享鈕與選單

點進一張名片：姓名、由誰建立、右上角一個共享鈕，下面是正面圖、人頭照、中文資訊、英文資訊、聯絡方式。右上角的選單裡有編輯，也有匯出到聯絡人。這一頁的順序是刻意的：圖在最上面。手機上看名片，最快的方式是看那張圖。規則：手機的詳情頁先放圖，再放欄位。

用講的找

搜尋頁就是一個聊天框：問「在台中印名片的」，回一張位於台中的名片，附卡片連結

搜尋頁就是一個聊天框。試了一句「在台中印名片的」，它回：找到一張位於台中的名片，底下附卡片，點進去就是詳情頁。它跟網頁版走同一條後端：模型把話翻成查詢，server 跑資料庫，權限在 server 管。App 這邊只是一個輸入框。規則：聰明的部分留在 server。App 越笨越好改。

三個框

新增名片：正面必填、反面選填、人頭照選填，拍照後可裁切、旋轉

新增名片的頁面三個框：正面必填，反面選填，人頭照選填。點任何一個框，跳出兩個選項：拍照，或從相簿選。從相簿選是給「剛剛已經拍過了」的情況用的，不用再拍一次。規則：每一個要照片的地方都給兩條路：現拍，或已經拍好的。

點任何一個框都是兩條路：拍照，或從相簿選

拍，然後裁

相機拍到的原圖：整張桌面，名片只在中間一小塊，不用刻意對準

拍照的時候不用對準，相機拍到的是整張桌面，名片在中間一小塊。拍完進裁切頁：框拉到名片的邊，比例有原始比例、正方形、4x3、3x2 四種，可以旋轉。裁完放回框裡。反面同樣再做一次。裁切在手機上做，是為了送出去的圖小一點、正一點。server 收到之後還會再自動裁一次，所以手機這邊裁得不準沒關係。規則：裁切做兩層。手機那層是給人看的，server 那層是給 OCR 的。

裁切名片正面：框拉到名片的邊，比例四選一，可以旋轉

正面放回框裡了，反面與人頭照還空著

裁切名片反面：這一面是門診時間表與一張地圖，等一下它會惹事

OCR 回來的草稿：三個地方錯掉：

OCR 回來的確認頁：「建興」變「建典」、職稱空著、反面的中文填進了英文公司欄；先不改，往下按

按下一步，兩張圖送上去，OCR 回來一張確認頁，最上面寫著：以下為 OCR 辨識結果，請確認或修改。這次拿一張真的名片試，一家中醫診所的。結果三個地方要改：診所名字「建興」被認成「建典」；名片上的「醫師」兩個字沒有進職稱；反面明明是中文，卻被填進英文公司那一欄，因為系統的規矩是正面填中文、反面填英文。這頁存在的理由就是這三個。我故意一個都沒改，直接按存檔，看它會變成什麼樣。規則：OCR 的結果永遠是草稿。確認頁不是形式，是唯一的關卡。

入庫之後：模型多給的那一行

入庫之後的詳情頁：「建典」原封不動；英文地址那行「建國路與文化路交叉口附近，青年國中旁」名片上沒有，是模型看反面地圖推出來的

存檔之後的詳情頁：中文公司還是「建典」，因為我沒改，系統不會替我改。英文地址那一欄出現一行字：建國路與文化路交叉口附近，青年國中旁。名片上沒有這一行。那是模型看著反面那張地圖，自己推出來的。看起來很聰明，但這是編的。真正的地址在中文那一欄，是名片正面印的。電話對，國別台灣對。規則：模型會補你沒給它的東西，而且補得像真的。看到不在原圖上的資料，先當它是編的。

匯出到聯絡人

詳情頁的選單裡按匯出到聯絡人，App 先問手機要聯絡人權限，拒絕的話這個功能就停用並說明原因。匯出是單筆、單向：從 App 寫進手機聯絡人，不回寫、不自動同步。寫進去之前先比對：同一個姓名加任何一支電話或 email 在手機裡已經有了，就跳出來問：新增一筆，還是略過。規則：往別人的資料庫寫東西，先查重，再問人，最後才寫。

安裝：

網站本身就有 /download 頁：登入頁的「下載 Android App」連過去,頁上有 QR code、直接下載按鈕、三步安裝說明。掃 QR 在手機瀏覽器下載、點開檔案、第一次要允許該瀏覽器安裝未知應用程式、裝好登入。

做完了

從拍一張名片到手機聯絡人裡多一筆，這條線通了。名片有了，聯絡人有了，明天開始弄 ERP。