Đọc file này TRƯỚC KHI viết bất kỳ dòng code nào.
EconSim phục vụ cả Kinh tế Vi mô và Kinh tế Vĩ mô tại FSPPM (MPP28). Kiến thức vi mô và vĩ mô được lưu ở 2 notebook NotebookLM riêng biệt, nhưng dùng chung một nền tảng mô phỏng và bổ trợ lẫn nhau.
src/
engine/
shared/ ← Glossary, types chung, math utils (tìm nghiệm, đạo hàm số)
micro/ ← Toán vi mô: preferences, constraints, solver, market, firm
macro/ ← Toán vĩ mô: is_lm, ad_as, mundell_fleming, solow, phillips
graph/ ← Khối vẽ SVG dùng chung. Chỉ nhận tọa độ + style, không biết micro hay macro.
ui/ ← Shell giao diện React dùng chung. Đọc khai báo scenario, dựng layout.
scenarios/
micro/ ← Các module tình huống vi mô (consumer, market, firm, failure)
macro/ ← Các module tình huống vĩ mô (short_run, open_econ, long_run)
registry.ts ← Danh mục toàn bộ module, phân nhánh Micro / Macro
• scenarios/ → import engine/, graph/, ui/ (OK)
• engine/micro/ và engine/macro/ → chỉ import engine/shared/ (OK)
• engine/ → KHÔNG import graph/, ui/, scenarios/, React, DOM
• graph/ → KHÔNG import engine/, ui/, scenarios/
Mỗi module là một thư mục trong src/scenarios/<domain>/<category>/<module_name>/:
src/scenarios/micro/consumer/rationing/
index.ts # defineScenario({...}): khai báo thông số, gọi engine
explain.tsx # React component giải thích, dùng biến từ kết quả engine
defineScenario({
meta: {
id: string, // ví dụ "micro.consumer.rationing" hoặc "macro.short_run.is_lm"
domain: "micro" | "macro" | "bridge", // "bridge" khi kết nối vi mô sang vĩ mô
category: string, // "consumer", "market", "short_run", "open_econ"...
chapter: string, // "PR Ch.3" hoặc "Mankiw Macro Ch.11"
title: string,
source: string, // Trích dẫn APA 7
notebook_id: string, // ID notebook NotebookLM nguồn
tags: string[],
},
params: Record<string, ParamDef>, // {min, max, step, default, unit, label, symbol}
presets?: Record<string, PresetDef>, // Kịch bản mẫu: gán sẵn một bộ params
model: (params) => ModelResult, // GỌI engine, trả kết quả số hoàn chỉnh
graph: (result) => GraphSpec, // Khai báo trục, đường cong, điểm, vùng tô màu
explain: React.FC<{result: ModelResult}>
})
• Cấm viết lệnh vẽ thủ công (ctx.lineTo, hoặc tự tính tọa độ pixel) trong scenario. Dùng graph/.
• Cấm ghi cứng con số trong văn bản giải thích. Mọi con số phải lấy từ result.
• Cấm đặt tên biến mơ hồ. Dùng đúng thuật ngữ kinh tế trong engine/shared/glossary.ts.
src/engine/micro/)• preferences.ts: CobbDouglas, ShiftedCobbDouglas, PerfectSubstitutes, PerfectComplements, QuasiLinear
ts
interface Preference {
type: string;
utility: (x: number, y: number) => number;
mrs: (x: number, y: number) => number;
indifferenceY: (u: number, x: number) => number | null;
indirectUtility?: (Px: number, Py: number, I: number) => number;
expenditure?: (Px: number, Py: number, u: number) => number;
label: string;
}
• constraints.ts: LinearBudget, RationedBudget, PriceCeilingBudget, InKindTransferBudget
• solver.ts: nhận Preference + BudgetConstraint, trả OptimalChoice (tọa độ, mức thỏa dụng, loại nghiệm interior / corner_axis / corner_kink, giá trị MRS, ràng buộc đang có hiệu lực)
• market.ts (giai đoạn tiếp theo): cung cầu, độ co giãn, thuế, giá trần/sàn, CS, PS, DWL
src/engine/macro/ — sẵn sàng mở rộng)• is_lm.ts: hàm tiêu dùng $C(Y-T)$, đầu tư $I(r)$, cầu tiền $L(Y, r)$, giải cân bằng $(Y^, r^)$, số nhân tài khóa và tiền tệ
• mundell_fleming.ts: IS, LM, đường $BP$ ($r = r^$), cơ chế tỷ giá cố định vs thả nổi, bộ ba bất khả thi
• ad_as.ts: tổng cầu $AD$, tổng cung ngắn hạn $SRAS$ và dài hạn $LRAS$, cú sốc cung/cầu
• solow.ts: hàm sản xuất $f(k)$, tích lũy vốn $\Delta k = s f(k) - (\delta + n + g)k$, trạng thái dừng $k^$, quy tắc vàng
Nhiều khái niệm vĩ mô có nền tảng vi mô trực tiếp (ví dụ: quyết định tiêu dùng liên thời gian nối sang hàm tiêu dùng trong IS LM; độc quyền và định giá nối sang độ cứng giá trong SRAS; kiểm soát giá vi mô nối sang lạm phát bị kìm nén ở vĩ mô). Các module có thể gắn related_scenarios: string[] trong meta để người học bấm chuyển qua lại giữa góc nhìn vi mô và vĩ mô.
tests/)Mỗi module PHẢI có file test kiểm tra bất biến kinh tế:
• Nghiệm bên trong: $|MRS - P_X/P_Y| < 10^{-4}$ • Nghiệm góc trên trục: $MRS \ge P_X/P_Y$ tại $(X_{\max}, 0)$ hoặc $MRS \le P_X/P_Y$ tại $(0, Y_{\max})$ • Rổ hàng tối ưu dùng hết ngân sách khả dụng • Trợ cấp tiền mặt luôn đạt mức thỏa dụng lớn hơn hoặc bằng trợ cấp hiện vật cùng mệnh giá ($U_{\text{cash}} \ge U_{\text{inkind}}$) • Khi mệnh giá trợ cấp hiện vật nhỏ hơn hoặc bằng mức chi tự nguyện ($T \le T^*$): $U_{\text{cash}} = U_{\text{inkind}}$ và hai điểm chọn trùng nhau
• Thị trường hàng hóa và tiền tệ đồng thời cân bằng tại giao điểm IS LM: $Y = C + I + G + NX$ và $M/P = L(Y, r)$ • Trong Mundell Fleming với vốn lưu chuyển hoàn hảo: $r = r^$ ở trạng thái cân bằng • Trong mô hình Solow tại trạng thái dừng: $s f(k^) = (\delta + n + g)k^*$
src/engine/shared/glossary.ts)Bảng từ điển chuẩn hóa ký hiệu cho cả hai môn:
• Vi mô: I (Thu nhập), Px, Py, MRS (Tỷ lệ thay thế biên), U (Mức thỏa dụng), CS, PS, DWL, MC, MR
• Vĩ mô: Y (Sản lượng / GDP thực), r (Lãi suất thực), i (Lãi suất danh nghĩa), P (Mức giá chung), pi (Tỷ lệ lạm phát), u (Tỷ lệ thất nghiệp), e (Tỷ giá hối đoái), k (Vốn trên mỗi lao động hiệu quả)
• TypeScript strict mode, cấm dùng any
• Không dùng ký tự gạch nối hoặc gạch ngang trong văn bản tiếng Việt hiển thị cho người dùng (dùng dấu chấm tròn • và dấu hai chấm :)
• Trích dẫn học thuật chuẩn APA 7
• Công thức toán hiển thị bằng KaTeX
Khi nhận một module hoặc file HTML từ Gemini hay nguồn khác:
1. TÁCH: mô hình kinh tế (hàm, tham số), lời giải thích, ý tưởng hiển thị
2. KIỂM CHỨNG: cho engine giải lại, đối chiếu từng con số với bản gốc, lập bảng chỉ rõ các chỗ sai
3. ÁNH XẠ: bỏ toàn bộ lệnh vẽ thủ công, thay bằng các khối trong src/graph/ và src/ui/
4. GỘP: nếu trùng cấu trúc toán học với module đã có, đưa vào làm một preset thay vì tạo module mới