Dùng checklist bàn giao mã nguồn này để xuất mã, ghi chép, xoay vòng secrets, chạy migrations, xác minh build và đảm bảo quyền triển khai cho khách hàng.

Bàn giao mã nguồn là thời điểm dự án chuyển từ “việc mà agency quản lý” sang “việc khách hàng sở hữu.” Nếu không có bàn giao rõ ràng, các vấn đề thường xuất hiện nhanh: app chỉ build trên một máy, production phụ thuộc vào một secret không ai tìm thấy, hoặc một cập nhật nhỏ biến thành nhiều ngày dò lỗi.
Mục tiêu của checklist bàn giao mã nguồn rất đơn giản: sau khi chuyển, khách hàng có thể build, chạy và triển khai sản phẩm mà không cần agency túc trực. Điều này không có nghĩa là “không bao giờ hỗ trợ.” Nó có nghĩa là những bước cơ bản phải lặp lại được và được ghi chép rõ ràng, để người tiếp theo có thể tiếp quản với sự tự tin.
Những gì được coi là deliverable nên được làm rõ. Tối thiểu, một bàn giao hoàn chỉnh thường bao gồm:
Phạm vi quan trọng không kém nội dung. Một số bàn giao chỉ bao gồm một môi trường (ví dụ production). Những bàn giao khác bao gồm dev, staging và production với cài đặt và quy trình riêng. Nếu bạn không nêu rõ môi trường nào được bao gồm, người ta sẽ hiểu khác nhau — và đó là nguồn gốc của sự cố.
Một cách thực tế để định nghĩa thành công là kiểm tra xác minh: một người không tham gia build app có thể xuất mã (ví dụ từ một nền tảng như Koder.ai), theo docs, thiết lập biến môi trường, chạy migrations, build và triển khai tới môi trường đã thỏa thuận.
Checklist này tập trung vào sẵn sàng về mặt kỹ thuật: biến môi trường, xoay vòng secrets, migration cơ sở dữ liệu, script triển khai và xác minh build. Nó không bao gồm điều khoản pháp lý, hợp đồng, điều khoản IP hay tranh chấp thanh toán. Những mục đó cũng quan trọng, nhưng thuộc một thỏa thuận riêng.
Một bàn giao sạch bắt đầu trước khi bất kỳ việc xuất mã nào diễn ra. Nếu bạn thống nhất ai sở hữu gì và khi nào, bạn tránh được những bất ngờ phút chót như deployment hỏng, hosting chưa trả, hoặc thiếu quyền truy cập.
Chọn một ngày bàn giao và định nghĩa một cửa sổ đóng băng (thường 24–72 giờ) chỉ cho phép sửa lỗi khẩn cấp. Điều này giữ cho mã xuất và hệ thống đang chạy đồng bộ. Nếu cần hotfix trong thời gian đóng băng, hãy ghi rõ chính xác gì đã thay đổi và đảm bảo nó được bao gồm trong bản xuất cuối cùng.
Quyết định ai sẽ sở hữu DNS, cloud hosting và các dịch vụ trả phí sau bàn giao. Đây không chỉ là thủ tục. Nếu thanh toán vẫn nằm trên thẻ agency, dịch vụ có thể bị tạm dừng sau đó mà không báo trước.
Một cách nhanh để cụ thể hóa:
Ghi những điều này bằng ngôn ngữ dễ hiểu để cả hai bên theo dõi.
Thống nhất các môi trường tồn tại (local, staging, production) và nơi mỗi môi trường chạy. Ghi rõ staging có phải là server riêng, database riêng hay chỉ là feature flag. Nếu bạn dùng nền tảng như Koder.ai, cũng xác nhận thứ gì được host ở đó so với thứ gì dự kiến chạy trên hạ tầng của khách hàng sau khi xuất.
Đừng chờ đến phút cuối mới yêu cầu quyền truy cập. Đảm bảo những người phù hợp có thể tiếp cận: repo, CI, hosting, database và nhà cung cấp email.
Cũng thống nhất bài kiểm tra chấp nhận cuối cùng và quy trình ký duyệt. Ví dụ: “Khách hàng có thể build từ máy sạch, chạy migrations, triển khai lên staging và vượt qua smoke test. Sau đó cả hai bên ký chấp nhận bằng văn bản.”
Một checklist bàn giao mã nguồn tốt bắt đầu bằng một repo mà đội mới có thể mở và hiểu trong vài phút. Xác nhận những gì được bao gồm (mã ứng dụng, mẫu cấu hình, script) và những gì được loại trừ cố ý (secrets thực, private keys, file lớn sinh ra). Nếu có thứ bị loại trừ, chỉ nơi nó nằm và ai sở hữu nó.
Giữ cấu trúc dễ đoán. Hướng tới các thư mục top-level rõ ràng như frontend/, backend/, mobile/, infra/, scripts/ và docs/. Nếu dự án là monorepo, giải thích cách các phần liên kết và cách chạy từng phần.
README nên dùng được cho người không xây dựng dự án. Nó nên bao gồm prerequisites và đường dẫn nhanh nhất để chạy dev mà không phải đoán mò.
Bao gồm một phần README ngắn, bằng ngôn ngữ con người, trả lời:
Thêm ghi chú kiến trúc đơn giản bằng ngôn ngữ thường: thành phần nào gọi thành phần nào và vì sao. Một biểu đồ nhỏ là tùy chọn, nhưng vài câu thường đủ. Ví dụ: “Frontend React gọi API Go. API đọc/ghi PostgreSQL. Jobs nền chạy như worker riêng.”
Cuối cùng, bao gồm changelog hoặc release notes có phiên bản cho bản bàn giao. Có thể là CHANGELOG.md hoặc một file “handoff release notes” ngắn ghi commit/tag chính xác, những gì đã được shipped và các vấn đề đã biết.
Nếu mã được xuất từ nền tảng như Koder.ai, ghi lại loại project được tạo (web, server, mobile), toolchain dự kiến (ví dụ React, Go, PostgreSQL, Flutter) và phiên bản OS/công cụ hỗ trợ mà khách hàng nên dùng để tái tạo build.
Biến môi trường thường là lý do một app “chạy tốt” nhưng thất bại ngay sau bàn giao. Một checklist bàn giao tốt coi biến môi trường là một phần của sản phẩm, không phải chi tiết phụ.
Bắt đầu bằng việc viết một inventory mà đội mới có thể theo mà không đoán mò. Giữ bằng ngôn ngữ dễ hiểu, và bao gồm ví dụ về định dạng giá trị (không phải secrets thật). Nếu một biến là tuỳ chọn, nói rõ điều gì xảy ra khi nó bị thiếu và giá trị mặc định là gì.
Cách trình bày inventory đơn giản:
.env cục bộ)Ghi rõ khác biệt theo môi trường. Ví dụ, staging có thể trỏ tới DB test và provider thanh toán sandbox, trong khi production dùng dịch vụ live. Ghi cả các giá trị phải khớp giữa hệ thống, như callback URL, allowed origins hoặc bundle identifier app mobile.
Tài liệu hoá nơi từng giá trị đang nằm hôm nay. Nhiều đội phân chia giá trị qua các nơi: file .env cục bộ cho dev, biến CI cho build, và cài đặt hosting cho runtime. Nếu bạn dùng Koder.ai để xuất app, bao gồm một file .env.example và ghi ngắn biến nào phải được điền trước build đầu tiên.
Cuối cùng, chứng minh không có secrets ẩn trong repo. Đừng chỉ kiểm tra file hiện có. Xem lại lịch sử commit để tìm key vô tình, file .env cũ, hoặc credentials sao chép trong config mẫu.
Ví dụ cụ thể: một frontend React + API Go có thể cần API_BASE_URL cho web app, và DATABASE_URL cùng JWT_SIGNING_KEY cho backend. Nếu staging dùng domain khác, ghi cả hai giá trị và nơi thay đổi chúng, để đội mới không đưa setting staging vào production.
Một bàn giao chưa hoàn tất cho tới khi khách hàng điều khiển mọi credential mà app cần. Điều đó có nghĩa là xoay vòng secrets, không chỉ chia sẻ. Nếu agency (hoặc contractor trước) vẫn có key hoạt động, đó là cửa hậu không thể kiểm toán.
Bắt đầu bằng việc lập đầy đủ inventory. Đừng chỉ dừng ở mật khẩu database. Bao gồm API key bên thứ ba, OAuth client secret, webhook signing secret, JWT signing key, thông tin SMTP, access key lưu trữ, và bất kỳ token tạm thời nào nằm trong CI.
Đây là checklist xoay vòng đơn giản cho ngày rotation:
Sau khi xoay, chứng minh không có gì hỏng. Chạy các test “người dùng thực” thay vì chỉ kiểm tra log.
Tập trung vào luồng phụ thuộc vào secrets:
Ví dụ: nếu bạn xuất dự án từ Koder.ai và app dùng nhà cung cấp thanh toán và gửi email, xoay cả hai key, redeploy, rồi thực hiện một giao dịch thử nhỏ và gửi email thử. Chỉ sau khi chúng thành công mới thu hồi key của agency.
Cuối cùng, ghi rõ nơi secrets sẽ được lưu tiếp theo (vault, biến CI hoặc cài đặt hosting), ai có quyền thay đổi và cách rollback an toàn nếu xoay gây lỗi.
Bàn giao có thể trông “xong” trong khi database là phần hỏng đầu tiên. Đối xử với migrations và dữ liệu như một sản phẩm riêng: có phiên bản, lặp lại được và đã kiểm thử.
Bắt đầu bằng việc ghi phiên bản DB hiện tại và nơi migration nằm trong repo. Cụ thể: đường dẫn thư mục, mô hình đặt tên và ID migration mới nhất (hoặc timestamp). Nếu dùng PostgreSQL (phổ biến với backend Go), cũng ghi các extension cần thiết.
Bao gồm một runbook ngắn trả lời các câu hỏi:
Rollback cần trung thực. Một số thay đổi chỉ phục hồi được bằng restore backup. Ghi rõ điều đó bằng ngôn ngữ thường, và kèm bước backup (snapshot trước deploy, xác minh quy trình restore).
Trước khi bàn giao hoàn tất, chạy migrations trên bản copy dữ liệu production nếu có thể. Điều này phát hiện truy vấn chậm, index thiếu và các lỗi “chỉ chạy trên dữ liệu rỗng.” Một bài test thực tế là xuất mã, thiết lập env, phục hồi dump đã ẩn danh, rồi apply migrations từ đầu. Bài kiểm tra này xác nhận phần lớn checklist bàn giao.
Nếu app được xây dựng trên nền tảng như Koder.ai rồi xuất, kiểm tra lại rằng file migration và seed script được bao gồm trong export và vẫn được backend gọi đúng khi khởi động.
Bàn giao chỉ hoàn tất khi người khác có thể rebuild app từ đầu trên máy sạch. Checklist nên bao gồm lệnh build chính xác, phiên bản cần thiết và đầu ra mong đợi (ví dụ: “web bundle trong /dist”, “tên binary API”, “vị trí APK Flutter”).
Ghi lại công cụ và package manager bạn thực sự dùng, không phải bạn nghĩ mình dùng gì. Với stack tiêu chuẩn có thể là Node.js (và npm hay pnpm) cho React web, toolchain Go cho server, công cụ client PostgreSQL cho setup cục bộ và Flutter SDK cho mobile.
Làm cho việc cài phụ thuộc có thể dự đoán. Xác nhận các lockfile đã được commit (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) và thực hiện cài mới trên máy mới hoặc container sạch để chứng minh hoạt động.
Ghi lại CI làm gì, từng bước, để có thể sao chép sang CI provider khác nếu cần:
Tách cấu hình thời gian build khỏi cấu hình runtime. Cấu hình build ảnh hưởng tới thứ được biên dịch (ví dụ API base URL được nhúng vào web bundle). Cấu hình runtime được chèn khi app khởi động (ví dụ database URL, API key và feature flag). Trộn hai loại này là lý do phổ biến khiến “chạy được trên CI” nhưng thất bại sau deploy.
Cung cấp công thức xác minh cục bộ đơn giản. Ngay cả một vài lệnh ngắn cũng đủ:
# Web
pnpm install
pnpm test
pnpm build
# API
go test ./...
go build ./cmd/server
# Mobile
flutter pub get
flutter test
flutter build apk
Nếu bạn xuất từ nền tảng như Koder.ai, bao gồm bất kỳ file CI được sinh hoặc preset build đã dùng khi triển khai để khách hàng có thể tái tạo build ngoài nền tảng.
Checklist bàn giao tốt không dừng ở “đây là repo.” Nó còn giải thích cách app đi từ source tới dịch vụ chạy, và ai là người nhấn nút.
Bắt đầu bằng việc ghi cách deployments diễn ra hiện tại: hoàn toàn thủ công (ai đó chạy lệnh trên server), CI-driven (pipeline build và deploy), hoặc qua nền tảng host. Bao gồm nơi cấu hình nằm, và môi trường tồn tại (dev, staging, production).
Làm cho bước phát hành lặp lại được. Nếu quy trình phụ thuộc vào ai đó nhớ 12 lệnh, hãy chuyển thành script và ghi quyền cần thiết.
Cung cấp cho khách hàng đủ để triển khai ngày đầu:
Thống nhất mong đợi downtime. Nếu yêu cầu “không downtime”, nói rõ nghĩa thực tế (blue-green, rolling deploy, cửa sổ read-only cho migration). Nếu chấp nhận downtime, định nghĩa khung thời gian rõ ràng.
Tài nguyên tĩnh và cache là điểm thường gặp lỗi. Ghi cách assets được build và phục vụ, khi nào cần bust cache, và có dùng CDN hay không.
Rollback nên là công thức ngắn, đã test và gắn với tag hoặc release ID. Ví dụ: deploy tag trước đó, restore snapshot DB nếu cần, và invalidate cache.
Nếu app được tạo trên Koder.ai rồi xuất, đề cập snapshot đã biết là tốt cuối cùng và phiên bản export chính xác để khách hàng đối chiếu mã với release hoạt động nhanh.
Xác minh là lúc bạn biết liệu bàn giao có thật sự hoàn tất không. Mục tiêu đơn giản: người mới có thể lấy mã xuất, thiết lập và chạy app cùng một cách không đoán mò.
Trước khi bắt đầu, ghi cái gì là “đúng”: phiên bản app đang chạy, commit/tag hiện tại (nếu có), và một hai màn hình hoặc API response chính để so sánh. Nếu export từ nền tảng như Koder.ai, ghi snapshot hoặc timestamp export để chứng minh bạn đã test trạng thái mới nhất.
Với smoke test, giữ ngắn và liên quan tới rủi ro:
Nếu có lỗi, ghi lại lệnh chính xác, output lỗi và env vars đã dùng. Chi tiết đó tiết kiệm hàng giờ khi chuyển giao quyền sở hữu.
Nhanh nhất để biến một bàn giao thành cuộc chạy chữa là cho rằng “chỉ cần mã là đủ.” Checklist bàn giao tốt tập trung vào những chi tiết nhỏ, nhàm chán quyết định khách hàng có thể chạy và thay đổi app không cần bạn hay không.
Hầu hết vấn đề rơi vào vài dạng lặp:
Làm cho xoay vòng và dọn dẹp quyền là việc có lịch, không phải mục “khi nào rảnh.” Đặt ngày khi tài khoản agency bị xóa, key dịch vụ được tạo lại, và khách hàng xác nhận họ có thể deploy chỉ với credential của mình.
Với env vars, làm inventory từ ba nơi: repo, hệ thống CI và UI hosting. Sau đó xác minh bằng cách chạy build sạch trên máy mới hoặc container.
Với migrations, test bằng cùng role database mà production deploy sẽ dùng. Nếu production cần bước nâng quyền (như bật extension), ghi những bước đó và làm rõ ai chịu trách nhiệm.
Ví dụ thực tế: sau khi xuất dự án từ Koder.ai, khách hàng deploy thành công nhưng jobs nền fail vì một URL queue chỉ được đặt trong dashboard hosting. Một kiểm toán env var đơn giản sẽ phát hiện. Kết hợp điều đó với release có tag và rollback đã ghi (ví dụ “redeploy tag v1.8.2 và restore snapshot gần nhất”) giúp đội tránh downtime.
Nếu bạn chỉ giữ một trang từ checklist bàn giao mã nguồn này, hãy giữ trang này. Mục tiêu đơn giản: một clone sạch nên chạy trên máy mới, với secrets mới, và cơ sở dữ liệu có thể tiến lên an toàn.
Chạy những kiểm tra này trên laptop chưa từng thấy dự án (hoặc container/VM sạch). Đây là cách nhanh nhất để bắt lỗi file thiếu, giả định ẩn và credentials cũ.
Một agency bàn giao frontend React, API Go và DB PostgreSQL. Đội khách hàng clone repo, copy .env.example thành env thật, tạo credential mới cho database, nhà cung cấp email và API bên thứ ba. Họ chạy go test (hoặc lệnh test đã thỏa thuận), build React app, apply migrations lên Postgres mới, và khởi động cả hai dịch vụ. Cuối cùng họ deploy bằng script đã doc và xác nhận commit đó có thể build lại sau này.
Giữ việc bàn giao ngắn và có chủ. Một buổi walkthrough 30–60 phút thường hiệu quả hơn một tài liệu dài.