Skip to Content

Quy tắc check

Tool check kiểm lỗi project qua bốn lớp (cú pháp, luật cấm, luật hợp đồng, kiểm kiểu): chạy khi nào, chặn deploy lúc nào, và các luật chính theo nhóm.

Mỗi luật ứng với một kiểu lỗi từng làm app hỏng khi chạy hoặc deploy thất bại. Lỗi chặn deploy; cảnh báo thì không.

Các lớp

check chạy lớp rẻ trước, lớp đắt sau.

1. Cú pháp phân tích mọi file .ts / .tsx → lỗi cú pháp, có số dòng 2. Luật cấm mẫu code làm app hỏng hoặc ra ngoài stack → rule code.* (lỗi) + cảnh báo chất lượng 3. Hợp đồng cây route, giao diện ↔ API, ranh giới .ts/.tsx, schema handler 4. Kiểm kiểu TypeScript đầy đủ — chỉ khi gọi check({ typecheck: true }), ~5–15 giây

Mỗi dòng kết quả có lớp, rule id (nếu có), file, dòng và cách sửa:

✗ 2 error(s) Errors: - [gate:code.antd-v6-no-visible-prop] app/orders/page.tsx:42 <Modal visible={…}> — antd v6 Modal ignores `visible`, so it never opens. Use `open={…}` … - [contract] app/orders/page.tsx FE calls GET /orders/stats but no matching BE route found Warnings: - [gate:perf.order-unindexed] app/orders/repository.ts:18 orders.createdAt is used in orderBy but …

Khi nào check chạy

  • Mỗi lần write_files — ba lớp đầu chạy ngay trong lần gọi, kết quả trả kèm. Agent sửa ở lần gọi sau.
  • Gọi check — ba lớp đầu; thêm typecheck: true để chạy cả lớp kiểm kiểu. Nên chạy kiểm kiểu một lần cuối mỗi giai đoạn, không phải sau từng file.
  • deploy — chạy cả bốn lớp (gồm kiểm kiểu) và từ chối khi còn lỗi. Lỗi kiểu là lớp duy nhất bỏ qua được, bằng deploy({ force: true, reason }) khi chắc app vẫn chạy; lỗi ở ba lớp đầu không bỏ qua được. Ngoại lệ: một cây file đã từng deploy thành công luôn deploy lại được, để quay lại bản cũ.

Giao diện và stack

RuleNghĩa
code.no-mui, code.no-shadcnImport MUI hoặc shadcn/ui — dùng antd và pro-components.
code.no-tailwind-importImport package Tailwind hoặc UI kit dựa trên Tailwind — viết class tiện ích thẳng trong className.
code.no-css-importImport file .css — app không có file CSS; dùng token antd.
code.undefined-componentDùng <Tên /> chưa import hay khai báo — trang sẽ hỏng với ”… is not defined”.
code.antd-v6-no-visible-propvisible trên Modal, Drawer, Dropdown, Tooltip, Popover, Popconfirm của antd v6 bị bỏ qua — lớp phủ không bao giờ mở; dùng open. Component tự viết và ModalForm / DrawerForm không bị báo.
code.no-pagecontainer-onbackonBack trên PageContainer/PageHeader làm hỏng trang — tự vẽ nút quay lại.

Gọi API từ giao diện

RuleNghĩa
code.invalid-api-methodGọi api.<tài nguyên>.<hàm>() không có trong client sinh sẵn; thông báo liệt kê các hàm hợp lệ. Lúc deploy, bước build kiểm lại trên chính client nó vừa sinh và từ chối deploy nếu còn lời gọi sai.
(hợp đồng)Giao diện gọi một đường dẫn mà không có handler nào phục vụ.

Cây file

RuleNghĩa
code.no-app-api-folderFile nằm trong app/api/ — cây là phẳng: app/<tài nguyên>/<method>.ts.
code.no-framework-file-emitViết tay app/db.ts, app/api.ts, app/hooks.ts — các file này do manh.run sinh.
code.reserved-std-pathFile nằm trong manh/ — thư mục dành cho dịch vụ có sẵn.
config.wrong-extensionapp/auth.tsx hay app/upstream.tsx — file cấu hình phải là .ts; manh.run không đọc bản .tsx.
shared.impure-importFile trong app/shared import thứ khác app/shared/*, manh/enum, manh/flow và manh/vn (ví dụ app/db, react, manh/env) hoặc dùng window, document, localStorage.
shared.not-tsxFile .tsx hay JSX trong app/shared — thư mục này chỉ chứa .ts thuần.
(hợp đồng)File .tsx import module chỉ chạy trên server, hoặc file .ts import React. app/shared/* là thư mục duy nhất cả hai bên cùng import.

Server và database

RuleNghĩa
code.runtime-importImport runtime khác import { env } from "manh/env" — đó là import runtime duy nhất được phép.
code.backend-package-not-allowedPackage không có trong danh sách server của manh.run; thông báo liệt kê package được phép.
code.no-remote-importImport bằng URL (https://…, esm.sh, URL esm.town/v/std/* cũ) — không hỗ trợ; dịch vụ có sẵn nằm ở manh/*.
code.unknown-std-importImport manh/<tên> không có (ví dụ manh/oauth) — đăng nhập khai báo trong app/auth.ts (email/mật khẩu, thêm providers: ["google"] cho Google).
code.no-dayjs-in-backendDùng dayjs trong file .ts — chỉ có ở giao diện; server dùng Date.
code.no-async-transactiondb.transaction(async …) — callback async không được chờ, lỗi không huỷ được các lệnh đã ghi; dùng callback đồng bộ.
(hợp đồng)Handler đọc body hay trường nào đó mà schema không khai báo.

Quên import eq, and, desc… từ app/db không phải lỗi: build tự thêm.

Bảo mật và đăng nhập

RuleNghĩa
code.hardcoded-secretChuỗi trông giống API key thật trong code — đặt secret trong dashboard, đọc qua env.NAME.
code.no-reserved-envĐọc tên dành riêng (OPENAI_*, FT_*…) — khoá của manh.run không có trong app; dùng manh/*.
auth.config-invalidapp/auth.ts sai dạng: thiếu roles, defaultRole không nằm trong roles, signup hay providers có giá trị lạ, hoặc không phải giá trị cố định.
access.invalidexport const access không phải "public", "user" hay một mảng tên vai viết cố định.
access.unknown-roleaccess nêu một vai không có trong roles của app/auth.ts.
auth.signed-in-redirect-loopCảnh báo: trang đăng nhập chuyển về trang chủ hễ thấy có người dùng (useEffect(() => { if (user) nav("/") }, [user])). Nếu trang chủ vẫn coi là chưa đăng nhập, hai trang chuyển qua lại mãi. Chuyển trang ngay sau signIn(…) trong hàm gửi form, hoặc chỉ khi phiên vừa bắt đầu lúc trang đang mở.
code.jwt-verify-algverify(token, secret) thiếu "HS256" — mọi request bị từ chối đăng nhập.
tenant.removedApp có app/tenant.ts. manh.run không còn chế độ nhiều tenant: mỗi app một database. Xoá file đó; khách cần dữ liệu riêng thì nhân bản app cho từng khách, hoặc lọc dòng theo cột tổ chức (orgId).

Cron

RuleNghĩa
code.cron-missing-scheduleFile .cron.ts không có export const schedule — việc không bao giờ chạy.
code.cron-invalid-scheduleLịch không đủ đúng 5 trường (phút giờ ngày tháng thứ, giờ UTC).

Dữ liệu mẫu

RuleNghĩa
sample.template-unchangedProject tạo từ template, app đã được sửa cho chủ mới nhưng spec/sample-data.json vẫn y nguyên của template (khách, sản phẩm, địa chỉ của một doanh nghiệp khác). Viết file mới cho đúng việc kinh doanh của chủ trong một lần write_files: giữ các bảng và cột thông báo liệt kê, tối đa 80 KB. Deploy sẽ nạp file mới vào các bảng còn trống; app đã deploy thì xoá dòng mẫu cũ bằng db_exec trước.

Cảnh báo thường gặp

Cảnh báo không chặn deploy, nhưng chỉ ra chỗ nên sửa.

RuleNghĩa
code.missing-frontendChưa có file .tsx — bình thường khi đang làm phần dữ liệu và API.
code.no-inline-drizzle-in-handlerHandler gọi db.select/insert… trực tiếp — nên chuyển vào repository.ts.
perf.order-unindexedDanh sách sắp xếp theo cột không có index — chậm dần khi bảng lớn. Không báo khi có index (kể cả index ghép) bắt đầu bằng cột sắp xếp hoặc cột mà truy vấn lọc bằng eq, khi lọc theo khoá ngoại có index kèm .limit(n) với n ≤ 50, và với bảng users sinh từ app/auth.ts.
list.unboundedSchema pageSize viết tay không có .max(…) — một request đọc được cả bảng. Dùng listSchema() từ app/db (giới hạn 100) hoặc thêm .max(100).
code.hardcoded-colorMàu viết cứng trong style — lấy từ theme.useToken() (token.colorTextLightSolid cho chữ trắng trên nền màu, token.colorBgMask cho lớp tối), chữ đỏ/xanh dùng Typography.Text type, nhãn trạng thái dùng Tag color. Lớp phủ trắng / đen / rgba trên ảnh nền không bị báo.
seo.missing-metaTrang công khai thiếu title / description trong meta. Khi app có đăng nhập, chỉ trang nằm trong danh sách kiểu PUBLIC_PAGES của layout mới bị báo; trang đăng nhập, đăng ký, người dùng không bao giờ bị báo; meta = { noindex: true } ở app/layout.tsx phủ mọi trang bên dưới.
code.no-raw-useapi-on-own-backendDùng useApi() gọi API của chính app — chạy được, nhưng nên dùng useApiClient() từ app/api (có kiểu).
code.no-direct-sqlite-core-importImport từ drizzle-orm/sqlite-core — build tự đổi sang app/db, nhưng nên import từ app/db.
code.antd-v6-no-bodystyle-prop, code.antd-v6-no-headstyle-prop, code.antd-v6-no-dropdownclassname-prop, code.antd-v6-no-tabpane-jsx, code.antd-v6-no-menu-item-jsxCách viết cũ của antd v6, vẫn chạy — nên dùng styles={{ body, header }}, classNames={{ popup: { root } }}, items={[…]}.
code.antd-responsive-xs-onlyCột bảng đặt responsive: ["xs"] một mình — antd chỉ hiện cột này trên điện thoại (dưới 576 px), máy tính không thấy. Muốn hiện ở mọi màn hình thì viết responsive: ["xs", "sm"].
access.public-writeHandler ghi dữ liệu (POST, PUT, PATCH, DELETE) để access = "public" — ai cũng gọi được.
sample.qualityspec/sample-data.json có dòng tự mâu thuẫn hoặc trông giả: id trỏ tới dòng không có trong file (classes[3].teacher_id = 9 but teachers has no id 9), dòng con khác dòng cha (điểm danh ghi lớp khác lớp của buổi), bé điểm danh ở lớp không ghi danh, chữ \n viết thành hai ký tự (trang hiện nguyên “\n”), số điện thoại kiểu 0900000001, email @example.com, “Lorem ipsum”, một tên lặp ở nhiều dòng, hoặc bảng có màn danh sách mà 0 dòng (màn đó trống lúc bàn giao). Nêu bảng, dòng, cột; tối đa 8 dòng. Sửa file mẫu cho các dòng khớp nhau, dùng tên và số thật, đa dạng.
sample.runtime-rewriteCode server cập nhật dữ liệu và trích ít nhất 3 giá trị của spec/sample-data.json (kiểu nút “chuẩn hoá dữ liệu mẫu”) — đổi dòng mẫu lúc chạy dễ hỏng giữa chừng. Xoá code đó, viết lại file mẫu.

Cần biết

  • Khi còn lỗi cú pháp, phần lớn luật cấm tạm dừng — sửa lỗi cú pháp trước rồi chạy lại.
  • deploy chạy cả lớp kiểm kiểu, nên lỗi kiểu sẽ chặn deploy. Chạy check({ typecheck: true }) trước khi bàn giao để thấy lỗi kiểu sớm, không đợi tới lúc deploy.
  • Danh sách trên là các luật chính, không phải tất cả. Thông báo lỗi luôn kèm cách sửa.

Gợi ý tính năng có sẵn

Cảnh báo hint.* chỉ ra tính năng của framework đã làm sẵn việc mà một file đang tự viết. Không bao giờ chặn. Mỗi loại một lần cho cả project:

  • hint.useAction — try / message.error(e.response.data.message) lặp lại quanh lời gọi API → useAction trong app/hooks.
  • hint.std-vn — tự cộng giờ Việt Nam (+7h) hoặc tự định dạng tiền → manh/vn.
  • hint.mail-html — tự viết hàm escape HTML trong code gửi mail → html và mailFrame trong manh/email.
  • hint.csv-export — tự làm nút tải CSV → block export-excel.
  • hint.numbering — tự ghép mã chứng từ bằng padStart → block numbering.
  • hint.flow-history — bảng lịch sử trạng thái từ/đến → Flow.move trả dòng cần lưu, hiện trên trang bản ghi bằng <ActivityLog> từ manh/shell.
  • hint.row-scope — cùng một bộ lọc dòng theo vai lặp ở nhiều truy vấn → scopeBy trong app/db.

Bước tiếp theo

Cập nhật