Từ ebook tới hộp thư khách

1. Tổng quan

Đây là một cái máy nhỏ chạy tự động, làm đúng 1 việc: ai vào trang web điền tên/số điện thoại/email để xin một cuốn ebook, thì trong vòng ~2 phút họ nhận được email có link tải ebook đó — không cần ai ngồi bấm gửi tay. Đồng thời, thông tin của người điền (tên, SĐT, email) được lưu lại vào một cái bảng dữ liệu (Lark Base) để sau này liên hệ/bán hàng tiếp.

Máy này gồm 3 mảnh ghép chạy nối tiếp nhau:

1. Một trang web ("leadpage") — nơi khách điền form.
2. Một cái bảng lưu dữ liệu (Lark Base) — nơi thông tin khách rơi vào.
3. Một chương trình nhỏ chạy nền trên máy tính — cứ vài phút lại nhìn vào bảng dữ liệu, thấy ai chưa được gửi mail thì tự gửi.

2. Chuẩn bị trước khi bắt đầu

2.1 Tài khoản cần có sẵn (tạo trước, không cần làm ngay hôm nay)

2.2 Thông tin nội dung cần chuẩn bị (không phải tài khoản, mà là thông tin thật)

Trước khi viết trang, phải có sẵn — không được bịa, thiếu thì phải hỏi người sở hữu thương hiệu:

• Tên thương hiệu hiển thị ở chân trang
• Địa chỉ / hotline / email liên hệ (có thể để trống nếu chưa muốn công khai)
• File ebook thật (PDF, hoặc link ebook đã xuất bản sẵn) để đọc nội dung thật, viết đúng lời hứa — không được đoán nội dung ebook qua tên file.

2.3 Phần mềm cần cài trên máy tính chạy hệ thống này

Máy này là máy chạy Claude Code (hoặc máy chạy chương trình gửi mail nền — xem mục 5.3), không phải máy của khách. Cần cài:

wrangler (công cụ deploy web lên Cloudflare) không cần cài riêng — dùng qua npx mỗi lần cần, tự tải bản mới nhất.

3. Các bước BẮT BUỘC làm thủ công

Đây là những bước không thể và không nên viết thành code — lý do chung: mỗi bước đều dính tới bảo mật (chống robot giả làm người, hoặc cần một con người thật chịu trách nhiệm bấm nút xác nhận), hoặc là một quyết định nội dung/thương hiệu mà máy không tự biết đúng sai. Người làm lại hệ thống này (kể cả AI) phải tự tay đi qua từng bước, không được viết script giả lập thay thế. (Lý do riêng của từng bước không nhắc lại nữa — chỉ ghi khi nào có cách bỏ bớt bước tay đó.)

3.1 Tạo & xác thực tài khoản Cloudflare

1. Vào dash.cloudflare.com, đăng ký tài khoản bằng email thật.
2. Mở hộp thư, tìm email xác thực Cloudflare gửi, bấm link xác nhận trong đó.
3. Kết quả cần lưu: không cần lưu gì đặc biệt — chỉ cần nhớ email + mật khẩu đăng nhập Cloudflare (lưu trong trình quản lý mật khẩu cá nhân, không lưu trong dự án).

Dấu hiệu chưa xong: tạo Pages project mà báo lỗi Your user email must been verified (mã lỗi 8000077) → quay lại bước 2, chưa bấm xác thực.

3.2 Đăng nhập Cloudflare cho công cụ deploy (wrangler login)

1. Chạy lệnh: npx wrangler login
2. Trình duyệt tự bật ra, hiện câu hỏi "Cho phép Wrangler truy cập tài khoản của bạn?"
3. Bấm Allow.
4. Kết quả cần lưu: không cần lưu tay — wrangler tự lưu phiên đăng nhập vào %APPDATA%\xdg.config\.wrangler\config\default.toml, dùng lại cho mọi lệnh sau. Phiên này có thể hết hạn sau thời gian dài không dùng — hết hạn thì chạy lại đúng lệnh ở bước 1.

3.3 Thêm bản ghi DNS cho tên miền con của trang web (CNAME)

1. Vào dash.cloudflare.com, chọn đúng tên miền gốc trong danh sách.
2. Menu bên trái, bấm DNS.
3. Bấm nút Add record.
4. Điền đúng 4 ô: - Type: CNAME - Name: chỉ phần tên miền con thôi, ví dụ hocnholau — không gõ thêm .tenmien.com phía sau - Target: <tên-project-cloudflare-pages>.pages.dev - Proxy status: bấm cho nó chuyển sang đám mây màu cam (chữ "Proxied") — để màu xám thì không cấp được SSL
5. Bấm Save.

Cách bỏ hẳn bước tay này cho các lần sau (tuỳ chọn): 1. Vào dash.cloudflare.com → góc trên phải → My Profile → API Tokens. 2. Bấm Create Token → Custom Token. 3. Cấp đúng quyền Zone → DNS → Edit, giới hạn chỉ 1 tên miền cụ thể. 4. Lưu chuỗi token hiện ra như một bí mật (xem mục 4) — Cloudflare chỉ hiện 1 lần duy nhất. 5. Có token này thì bước 3.3 chuyển được sang gọi API tự động (mục 5), không cần vào Dashboard nữa.

3.4 Đăng nhập Lark cho lark-cli (lark-cli auth login)

1. Chạy lệnh: lark-cli auth login --domain mail --no-wait --json
2. Lệnh trả về 1 verification_url — mở link đó (hoặc quét QR bằng lark-cli auth qrcode <url> trên điện thoại).
3. Bấm xác nhận đăng nhập & đồng ý cấp quyền trên trang/app Lark.
4. Quay lại terminal, chạy: lark-cli auth login --device-code <device_code-đã-nhận-ở-bước-1>
5. Kết quả cần lưu: không cần lưu tay — lark-cli tự giữ phiên đăng nhập an toàn trên máy. Kiểm tra còn hiệu lực bằng lark-cli auth status.

Khi nào phải lặp lại: đổi máy tính, hoặc phiên đăng nhập bị thu hồi/hết hạn.

3.5 Lấy App Secret của app Lark đã có sẵn (Lark Developer Console)

1. Vào open.larksuite.com, đăng nhập tài khoản quản trị app.
2. Bấm Developer Console (góc trên phải).
3. Dùng icon kính lúp 🔍 cạnh nút đó, gõ tên app cần tìm → bấm vào đúng app.
4. Menu dọc bên trái, bấm Credentials & Basic Info.
5. Mục App Secret bị che dấu *** — bấm icon con mắt 👁 bên cạnh để hiện chuỗi thật.
6. Copy chuỗi đó (~32 ký tự).
7. Kết quả cần lưu: dán App Secret trực tiếp vào bước nạp secret Cloudflare (mục 5) — không lưu vào bất kỳ file text/code nào trong dự án.

3.5b Tạo MỘT APP LARK MỚI từ đầu (khi chưa có app nào, hoặc muốn tách riêng app cho từng dự án)

1. Vào open.larksuite.com, bấm Developer Console (góc trên phải).
2. ⚠️ Điểm hay lạc: màn hình mặc định hiện ra là "Start from scratch" / "Create Custom App" — đây là màn tạo app mới, KHÔNG phải danh sách app đã có. Đang tìm app cũ thì đừng bấm gì ở đây — quay lại mục 3.5 (dùng kính lúp 🔍 cạnh nút Developer Console để tìm theo tên).
3. Thật sự cần tạo mới thì bấm "Create Custom App".
4. Điền App Name (gõ gì cũng được).
5. Điền Description (gõ gì cũng được).
6. Bấm Create.
7. Lark tự chuyển vào trang quản lý app đó — menu trái hiện ra, bấm Credentials & Basic Info.
8. Thấy ngay App ID (không bị che) — copy lại.
9. Bấm icon con mắt 👁 cạnh App Secret để hiện, copy lại.

Kết quả cần lưu: App ID mới (cli_...) + App Secret mới — dùng thay cho App ID/Secret cũ trong functions/api/lead.js và mọi script gọi Lark API cho dự án này.

⚠️ App vừa tạo CHƯA có quyền đọc/ghi Bitable — làm ngay mục 3.5c dưới đây trước khi dùng, không thì gọi API ghi lead sẽ bị từ chối mã lỗi 99991672.

3.5c Cấp quyền Bitable cho app mới (bitable:app + base:record:create)

1. Gọi thử 1 API bất kỳ tới app đó (ví dụ ghi 1 bản ghi test) — nếu thiếu quyền, Lark trả lỗi kèm sẵn 1 link tắt trong trường helps[0].url, dạng: https://open.larksuite.com/app/<APP_ID>/auth?q=bitable:app,base:record:create&op_from=openapi&token_type=tenant
2. Mở link đó bằng trình duyệt.
3. Trang hiện sẵn đúng các quyền còn thiếu — bấm Add (hoặc Enable) từng quyền một.
4. Bấm Save / Create version / Publish để lưu (app nội bộ dùng riêng thì có hiệu lực ngay, không cần chờ duyệt).

Dấu hiệu app đang thiếu quyền: gọi API trả về {"code":99991672,"msg":"Access denied. One of the following scopes is required: [...]"} — mở lại đúng link trong helps[0].url của lỗi đó rồi lặp lại bước 2-4.

3.5d Copy một Base có sẵn làm bảng riêng cho dự án/thương hiệu mới

Khi nào cần: bảng "17.1 Lead Magnet" mẫu đang nằm chung 1 Base lớn với nhiều việc khác (nhân sự, kho, kế toán...), muốn có bản riêng sạch chỉ cho 1 thương hiệu/dự án.

1. Mở Base mẫu.
2. Bấm menu "..." ở góc trên Base.
3. Chọn Copy (hoặc Duplicate base).
4. Lark tạo ra 1 Base hoàn toàn mới, tên có thêm chữ "Sao chép".

⚠️ Base mới có app_token (base token) và toàn bộ table_id bên trong đổi khác 100% so với bản gốc — kể cả bảng "17.1 Lead Magnet" copy sang cũng có table_id mới tinh. Không được giả định giống bản gốc — phải làm lại từ đầu: 1. Lấy app_token mới = chuỗi ngay sau /base/ trong URL của Base mới. 2. Liệt kê lại table_id các bảng (mục 5.3). 3. Kiểm tra lại tên cột (có thể khác thứ tự). 4. Thử ghi 1 bản ghi test lại từ đầu (mục 5.3) — đừng bỏ qua bước này.

Kết quả cần lưu: app_token + table_id mới, ghi đè vào hằng số BASE_TOKEN_MAC_DINH / TABLE_ID_MAC_DINH trong functions/api/lead.js và mọi script nền đọc/ghi Base này.

3.6 Bật dịch vụ Lark Mail cho tổ chức (chỉ làm 1 lần cho cả tổ chức)

1. Vào admin.larksuite.com, đăng nhập tài khoản admin.
2. Gõ "Mail" vào ô tìm kiếm trên cùng (hoặc bấm Product Settings) → chọn mục Email/Mail.
3. Bấm Configure Now.
4. Nhập tên miền muốn dùng để gửi mail — dùng tên miền riêng, ví dụ hoctapsuotdoi.com. Không dùng kiểu ...@xxx.larksuite.com — địa chỉ đó lộ chữ "larksuite", kém chuyên nghiệp.
5. Lark trả về 5 bản ghi DNS cần thêm (thường 2 TXT + 3 MX) — thêm đúng nguyên văn vào Cloudflare DNS của tên miền đó (mục 3.3), Name = @ cho cả 5 bản ghi.
6. Đợi vài phút cho DNS lan truyền, bấm Verify Now trên trang Lark.
7. Vào Quản lý tổ chức → Thành viên và Bộ phận.
8. Chọn đúng tài khoản người dùng cần gửi mail.
9. Cột Email doanh nghiệp đang ghi "Chưa thiết đặt" → bấm chữ "Thêm".
10. Gõ phần tên trước dấu @ (local-part), ví dụ ebook.
11. Bấm Lưu.

Kết quả cần lưu: địa chỉ mailbox vừa tạo (vd ebook@hoctapsuotdoi.com) — dùng lại ở bước gửi mail (mục 5). Bước này không cần lặp lại cho các leadpage sau, miễn dùng lại cùng domain.

Kiểm tra đã xong chưa: chạy lệnh lark-cli mail user_mailboxes profile --as user --params '{"user_mailbox_id":"me"}' → phải trả về đúng địa chỉ mail, không phải chuỗi rỗng.

3.7 Duyệt nội dung/giao diện trang trước khi đưa lên mạng

1. Mở ảnh chụp thử trang (preview.png).
2. Đọc lại toàn bộ copy (câu chữ) trên trang.
3. Nói 1 câu "duyệt" hoặc "sửa lại chỗ X" — chỉ khi có câu "duyệt" mới được deploy lên tên miền thật.

4. Nơi lưu thông tin nhạy cảm

Hệ thống này hiện KHÔNG dùng file .env (chưa gom lại thành 1 chỗ) — các giá trị đang nằm rải rác trực tiếp trong code, ngoại trừ đúng 1 giá trị được cách ly làm bí mật thật sự. Bảng dưới liệt kê từng giá trị và nơi nó thực sự đang nằm, để biết chỗ nào cần thận trọng khi chia sẻ file:

Khuyến nghị cải thiện (chưa làm): gom hết các hằng số trên vào 1 file .env thật (không đưa vào git), rồi cho 2 file code đọc từ đó — hiện tại vì chỉ có 1 giá trị thật sự bí mật (LARK_APP_SECRET, đã cách ly đúng cách) nên rủi ro thấp, nhưng gom lại vẫn gọn hơn khi cần đổi.

5. Phần có thể tự động hoá

Từ đây trở xuống là phần có sẵn credentials từ mục 3 rồi thì chạy được hết bằng lệnh, không cần thao tác chuột nữa (trừ khi làm thêm mục 3.3 tuỳ chọn thì DNS cũng tự động luôn).

5.1 Dựng nội dung + ảnh bìa + trang web tĩnh

• Input: file ebook thật (đọc nội dung), thông tin thương hiệu (mục 2.2), 1 file cấu hình config-ebook.json (chứa toàn bộ copy: tiêu đề, nỗi đau, tên gói quà, thông tin liên hệ...).
• Output: site/index.html (trang web hoàn chỉnh) + ảnh xem thử preview.png.
• Lệnh chạy: ```powershell # 1. Vẽ ảnh bìa bằng Python + Pillow (script tự viết riêng cho từng ebook) python make_cover.py

# 2. Nới đáy ảnh (chừa chỗ cho nút bấm đè lên) + nén sang WebP cho nhẹ powershell -File "\scripts\render-bia-hero.ps1" ` -Nguon ".\bia\anh-bia-goc.png" -Ra ".\bia\bia-hero.webp"

# 3. Build trang từ file cấu hình python "\scripts\build_ebook_leadpage.py" ` --config ".\config-ebook.json" --out ".\site"

# 4. Chụp ảnh xem thử bằng Chrome (để duyệt ở bước 3.7) & "C:\Program Files\Google\Chrome\Application\chrome.exe" --headless=new --disable-gpu --hide-scrollbars --window-size=460,2300 --virtual-time-budget=6000 --screenshot=".\preview.png" "file:///<đường dẫn tuyệt đối>/site/index.html" ```

5.2 Đưa trang lên mạng (Cloudflare Pages) + gắn tên miền

• Input: thư mục site/ (từ bước 5.1) + thư mục functions/ (mã xử lý form, xem 5.3) đặt ngang hàng nhau, phiên đăng nhập từ mục 3.2.
• Output: trang web chạy thật ở địa chỉ https://<tên-miền-con>/.
• Lệnh chạy: ```powershell npx wrangler pages project create --production-branch main

npx wrangler pages deploy site --cwd "" ` --project-name --branch main --commit-dirty=true # Phải thấy dòng "✨ Compiled Worker successfully"

# Gắn tên miền con (wrangler không có lệnh này, gọi thẳng API): $tok = [regex]::Match([IO.File]::ReadAllText("$env:APPDATA\xdg.config.wrangler\config\default.toml"), 'oauth_token\s*=\s*"([^"]+)"').Groups[1].Value Invoke-RestMethod -Method Post -Uri "https://api.cloudflare.com/client/v4/accounts//pages/projects//domains" -Headers @{ Authorization = "Bearer $tok" } -ContentType "application/json" -Body '{"name":""}' ``` → sau lệnh cuối vẫn cần bước tay 3.3 (thêm CNAME) trừ khi đã có Cloudflare API Token riêng.

5.2b Dựng nhanh 1 "trang chuyển hướng" — rút gọn 1 link dài, xấu thành tên miền dễ nhớ

Bước 1 — Tạo đúng 1 thư mục + 1 file, không cần gì khác:

Tạo thư mục mới, ví dụ C:\Chip brain\production\redirect-<ten-ngan>\site\, rồi tạo file index.html bên trong với đúng nội dung này (chỉ sửa dòng có chữ ĐỔI:):

<!doctype html>
<html lang="vi">
<head>
<meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=ĐỔI: DÁN LINK ĐÍCH DÀI VÀO ĐÂY">
<link rel="canonical" href="ĐỔI: DÁN LINK ĐÍCH DÀI VÀO ĐÂY">
<title>ĐỔI: tên trang</title>
</head>
<body>
  <p>Đang chuyển tới trang đích...
     Nếu không tự chuyển, <a href="ĐỔI: DÁN LINK ĐÍCH DÀI VÀO ĐÂY">bấm vào đây</a>.</p>
</body>
</html>

Bước 2 — Mở PowerShell, chạy đúng 2 lệnh này (thay <ten-du-an> bằng 1 cái tên ngắn, chỉ chữ thường/số/gạch ngang, ví dụ redirect-casestudy-business):

cd "C:\Chip brain\production\redirect-<ten-ngan>"

npx wrangler pages project create <ten-du-an> --production-branch main

npx wrangler pages deploy site --project-name <ten-du-an> --branch main --commit-dirty=true

Chạy xong lệnh thứ 2, màn hình in ra 1 dòng dạng ✨ Deployment complete! ... https://xxxx.<ten-du-an>.pages.dev — vậy là trang đã sống, nhưng còn ở địa chỉ xấu .pages.dev, cần làm tiếp bước 3-4 để có tên miền đẹp.

Bước 3 — Gắn tên miền con đẹp (chạy lệnh, không cần vào Cloudflare Dashboard ở bước này):

$tok = [regex]::Match([IO.File]::ReadAllText("$env:APPDATA\xdg.config\.wrangler\config\default.toml"), `
  'oauth_token\s*=\s*"([^"]+)"').Groups[1].Value
Invoke-RestMethod -Method Post `
  -Uri "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/pages/projects/<ten-du-an>/domains" `
  -Headers @{ Authorization = "Bearer $tok" } -ContentType "application/json" `
  -Body '{"name":"<ten-mien-con-day-du-vd-casestudybusiness.hoctapsuotdoi.com>"}'

(<ACCOUNT_ID> lấy trong Phụ lục ở cuối file này.) Lệnh này chỉ báo cho Cloudflare biết sắp có tên miền đó — CHƯA làm tên miền chạy được, phải làm tiếp bước 4.

Bước 4 — Bước tay DUY NHẤT: thêm 1 bản ghi DNS trên Cloudflare Dashboard

1. Mở trình duyệt, vào dash.cloudflare.com, đăng nhập.
2. Bấm chọn đúng tên miền gốc (ví dụ hoctapsuotdoi.com) trong danh sách.
3. Menu bên trái, bấm DNS → bấm nút Add record (thường ở góc phải).
4. Điền đúng 4 ô: - Type: chọn CNAME - Name: chỉ gõ phần tên miền con thôi (ví dụ casestudybusiness) — KHÔNG gõ thêm .hoctapsuotdoi.com phía sau, gõ dư là bị nối đuôi 2 lần thành sai. - Target: gõ đúng <ten-du-an>.pages.dev (tên dự án đặt ở Bước 2, thêm .pages.dev phía sau) - Proxy status: bấm vào để nó chuyển thành đám mây màu CAM (chữ "Proxied") — nếu đang màu xám (chữ "DNS only") thì bấm 1 lần để đổi sang cam.
5. Bấm nút Save.

Bước 5 — Kiểm tra đã chạy chưa: chờ khoảng 30-60 giây, rồi mở đúng link tên miền con vừa gắn (ví dụ https://casestudybusiness.hoctapsuotdoi.com) bằng trình duyệt — phải tự động nhảy sang đúng trang đích dài. Nếu báo lỗi/không nhảy, chờ thêm 1-2 phút rồi thử lại (DNS cần chút thời gian lan truyền), hoặc kiểm tra lại đúng 4 ô ở Bước 4 có gõ sai chỗ nào không.

5.3 Nối form vào Lark Base (lưu lead)

• Input: LARK_APP_ID, LARK_APP_SECRET, LARK_BASE_TOKEN, LARK_TABLE_ID, tên các cột trong bảng (lấy bằng lệnh liệt kê field).
• Output: functions/api/lead.js — mã chạy trên chính Cloudflare (gọi "Cloudflare Pages Function"), nhận dữ liệu form rồi ghi thẳng vào Lark Base.
• Lệnh kiểm tra & thiết lập: ```bash # Liệt kê bảng trong Base, tìm đúng bảng cần dùng lark-cli api GET /open-apis/bitable/v1/apps//tables --as bot

# Xem tên các cột thật trong bảng đó lark-cli api GET /open-apis/bitable/v1/apps//tables//fields --as bot

# Thử ghi 1 bản ghi test TRƯỚC khi viết mã — chạy được thì xoá đi rồi mới yên tâm lark-cli base +record-upsert --as bot --base-token --table-id --json '{"Họ và Tên":"TEST"}' ``` Sau khi test ghi thành công: sửafunctions/api/lead.js(điền đúngLARK_APP_ID,LARK_BASE_TOKEN,LARK_TABLE_ID`, tên cột), rồi nạp secret và deploy lại: ```powershell # Dán App Secret (lấy từ bước 3.5) qua PowerShell, KHÔNG in ra lại: $secret = "" $secret | npx wrangler pages secret put LARK_APP_SECRET --project-name $secret = $null

npx wrangler pages deploy site --cwd "" ` --project-name --branch main --commit-dirty=true ```

5.4 Chương trình chạy nền: tự gửi email qua Lark Mail

• Input: mailbox đã tạo ở mục 3.6, LARK_BASE_TOKEN/LARK_TABLE_ID (giống 5.3), 1 cột checkbox riêng trong bảng để đánh dấu "đã gửi" (tự tạo bằng lệnh bên dưới nếu chưa có).
• Output: file scripts/send-ebook-emails.py (quét bảng → gửi mail → đánh dấu đã gửi) + 1 tác vụ Windows Task Scheduler chạy file đó lặp lại mỗi 2 phút.
• Lệnh tạo cột đánh dấu (chỉ chạy 1 lần): bash lark-cli base +field-create --as bot --base-token <app_token> --table-id <table_id> ` --json '{"name":"Email Ebook Đã Gửi","type":"checkbox"}'
• Lệnh đăng ký chạy nền (chỉ chạy 1 lần mỗi máy): powershell $pythonwPath = (Get-Command python).Source -replace 'python\.exe$','pythonw.exe' $action = New-ScheduledTaskAction -Execute $pythonwPath -Argument '"<đường dẫn>\send-ebook-emails.py"' $trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) ` -RepetitionInterval (New-TimeSpan -Minutes 2) -RepetitionDuration (New-TimeSpan -Days 3650) $settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries ` -StartWhenAvailable -MultipleInstances IgnoreNew Register-ScheduledTask -TaskName "<ten-task>" -Action $action -Trigger $trigger ` -Settings $settings -RunLevel Limited -Force
• Bên trong script làm 3 việc, lặp mỗi lần chạy: 1. Hỏi Lark Base: "cho tôi các bản ghi có SourceID = tên chiến dịch này VÀ cột Email Ebook Đã Gửi = chưa tick". 2. Với mỗi bản ghi tìm được: gửi email qua lark-cli mail +send --as user --to <email> ... --confirm-send. 3. Đánh dấu bản ghi đó đã gửi (+record-upsert set checkbox = true), để lần quét sau bỏ qua.
• Quan trọng khi viết code gọi lark-cli từ Python trên Windows: gọi thẳng node.exe <đường-dẫn>\node_modules\@larksuite\cli\scripts\run.js <tham số>, không gọi lark-cli.cmd — xem lý do chi tiết ở mục 7.

6. Cách chạy lại từ đầu trên máy hoàn toàn mới

Giả sử đã có sẵn: tài khoản Cloudflare (đã xác thực), tên miền đã trỏ Cloudflare, app Lark đã đăng ký (có App ID, App Secret, đã bật đủ quyền bitable + mail:user_mailbox.message:send), và 1 Lark Base đã có bảng lưu lead. Nếu chưa có bất kỳ thứ nào ở trên, phải làm xong toàn bộ mục 3 trước.

1. Cài phần mềm nền (mục 2.3): Node.js, Python + Pillow, lark-cli, Chrome.
2. Đăng nhập lark-cli trên máy mới: lark-cli auth login --domain mail --no-wait --json rồi hoàn tất theo hướng dẫn (mục 3.4). Nếu chỉ cần đọc/ghi Base (chưa cần gửi mail ngay) thì --domain base là đủ, thêm --domain mail khi cần gửi mail.
3. Đăng nhập wrangler trên máy mới: npx wrangler login (mục 3.2).
4. Nếu domain gửi mail chưa từng bật Lark Mail trước đó: làm trọn mục 3.6 (bật dịch vụ, thêm DNS, gán mailbox). Nếu domain này đã bật rồi (dùng lại cho ebook mới cùng thương hiệu) thì bỏ qua bước này hoàn toàn, mailbox vẫn còn nguyên.
5. Đọc ebook thật, hỏi đủ thông tin thương hiệu (mục 2.2), viết config-ebook.json.
6. Chạy trọn mục 5.1 (vẽ bìa → build trang → chụp ảnh xem thử).
7. Đưa preview.png cho người có quyền duyệt — có gật đầu mới sang bước 8 (mục 3.7).
8. Chạy mục 5.2 (deploy Cloudflare Pages + gọi API gắn tên miền con).
9. Thêm bản ghi CNAME bằng tay trên Cloudflare Dashboard (mục 3.3) — trừ khi đã có sẵn API Token DNS riêng, thì tự động luôn trong bước 8.
10. Lấy app_token thật + tên cột của Base, thử ghi test, sửa functions/api/lead.js, lấy App Secret (mục 3.5) dán vào, nạp secret, deploy lại (mục 5.3).
11. Bắn 1 lead thật qua form, mở Base nhìn tận mắt xác nhận có ghi vào — nếu sai thì sửa lại functions/api/lead.js rồi deploy lại, đừng bỏ qua bước nhìn tận mắt này.
12. Tạo cột checkbox đánh dấu đã gửi, viết scripts/send-ebook-emails.py (mục 5.4), đăng ký Task Scheduler chạy mỗi 2 phút.
13. Bắn 1 lead test khác, đợi ≤2 phút, mở hộp thư thật kiểm tra: tiêu đề đúng, tên không vỡ dấu, nút bấm mở đúng ebook.
14. Xoá sạch mọi bản ghi test khỏi Lark Base trước khi chạy quảng cáo thật.

7. Lỗi thường gặp đã xử lý

Phụ lục — tham số của dự án mẫu "Học Nhớ Lâu" (đối chiếu nhanh)

Phụ lục 2 — tham số dự án "Case Study Business" (2026-09-06, Base RIÊNG không dùng chung)