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âyMỗ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êmtypecheck: 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ằngdeploy({ 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
| Rule | Nghĩa |
|---|---|
code.no-mui, code.no-shadcn | Import MUI hoặc shadcn/ui — dùng antd và pro-components. |
code.no-tailwind-import | Import package Tailwind hoặc UI kit dựa trên Tailwind — viết class tiện ích thẳng trong className. |
code.no-css-import | Import file .css — app không có file CSS; dùng token antd. |
code.undefined-component | Dùng <Tên /> chưa import hay khai báo — trang sẽ hỏng với ”… is not defined”. |
code.antd-v6-no-visible-prop | visible 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-onback | onBack trên PageContainer/PageHeader làm hỏng trang — tự vẽ nút quay lại. |
Gọi API từ giao diện
| Rule | Nghĩa |
|---|---|
code.invalid-api-method | Gọ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
| Rule | Nghĩa |
|---|---|
code.no-app-api-folder | File nằm trong app/api/ — cây là phẳng: app/<tài nguyên>/<method>.ts. |
code.no-framework-file-emit | Viết tay app/db.ts, app/api.ts, app/hooks.ts — các file này do manh.run sinh. |
code.reserved-std-path | File nằm trong manh/ — thư mục dành cho dịch vụ có sẵn. |
config.wrong-extension | app/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-import | File 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-tsx | File .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
| Rule | Nghĩa |
|---|---|
code.runtime-import | Import runtime khác import { env } from "manh/env" — đó là import runtime duy nhất được phép. |
code.backend-package-not-allowed | Package 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-import | Import 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-import | Import 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-backend | Dùng dayjs trong file .ts — chỉ có ở giao diện; server dùng Date. |
code.no-async-transaction | db.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
| Rule | Nghĩa |
|---|---|
code.hardcoded-secret | Chuỗ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-invalid | app/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.invalid | export const access không phải "public", "user" hay một mảng tên vai viết cố định. |
access.unknown-role | access nêu một vai không có trong roles của app/auth.ts. |
auth.signed-in-redirect-loop | Cả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-alg | verify(token, secret) thiếu "HS256" — mọi request bị từ chối đăng nhập. |
tenant.removed | App 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
| Rule | Nghĩa |
|---|---|
code.cron-missing-schedule | File .cron.ts không có export const schedule — việc không bao giờ chạy. |
code.cron-invalid-schedule | Lịch không đủ đúng 5 trường (phút giờ ngày tháng thứ, giờ UTC). |
Dữ liệu mẫu
| Rule | Nghĩa |
|---|---|
sample.template-unchanged | Project 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.
| Rule | Nghĩa |
|---|---|
code.missing-frontend | Chưa có file .tsx — bình thường khi đang làm phần dữ liệu và API. |
code.no-inline-drizzle-in-handler | Handler gọi db.select/insert… trực tiếp — nên chuyển vào repository.ts. |
perf.order-unindexed | Danh 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.unbounded | Schema 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-color | Mà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-meta | Trang 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-backend | Dù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-import | Import 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-jsx | Cá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-only | Cộ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-write | Handler ghi dữ liệu (POST, PUT, PATCH, DELETE) để access = "public" — ai cũng gọi được. |
sample.quality | spec/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-rewrite | Code 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.
deploychạy cả lớp kiểm kiểu, nên lỗi kiểu sẽ chặn deploy. Chạycheck({ 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 →useActiontrongapp/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 →htmlvàmailFrametrongmanh/email.hint.csv-export— tự làm nút tải CSV → blockexport-excel.hint.numbering— tự ghép mã chứng từ bằngpadStart→ blocknumbering.hint.flow-history— bảng lịch sử trạng thái từ/đến →Flow.movetrả 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 →scopeBytrongapp/db.
Bước tiếp theo
- manh.run hoạt động thế nào —
checknằm ở đâu trong luồng từ code đến app. - Vì sao stack cố định — lý do có các luật về stack.
- Cây thư mục app/ — loại file và đường dẫn hợp lệ.
Cập nhật