Tài liệu này là bản thiết kế kỹ thuật và kế hoạch thực thi chi tiết (Handover Spec) để bàn giao cho agent thực thi (ví dụ it-ai worker hoặc phiên làm việc kế tiếp của Khôi). Agent nhận bàn giao chỉ cần đọc file này cùng AGENTS.md và docs/MODULE_MIGRATION.md là có thể code tuần tự hoặc chia task chạy song song mà không cần đọc lại toàn bộ lịch sử trò chuyện.
Xây dựng nền tảng EconSim dùng chung cho cả Kinh tế học Vi mô và Kinh tế học Vĩ mô, và hoàn thành Giai đoạn 1 gồm:
1. Khung ứng dụng Vite + TypeScript + React + Tailwind CSS + KaTeX + Vitest.
2. Lớp Engine chuẩn hóa (gồm phần dùng chung engine/shared/, nhánh vi mô engine/micro/, và khung chờ sẵn cho nhánh vĩ mô engine/macro/).
3. Lớp SVG Graph Primitives (src/graph/) thay thế hoàn toàn việc vẽ Canvas thủ công.
4. Lớp UI Shell (src/ui/) tái tạo toàn bộ trải nghiệm trực quan tốt nhất từ file mẫu (reference/micro_macro_animation_legacy.html), đồng thời hỗ trợ chuyển nhánh Vi mô / Vĩ mô / Cầu nối (Microfoundations).
5. Hoàn thiện 3 cụm mô phỏng Vi mô đầu tiên (tách từ file mẫu, đã fix triệt để lỗi toán học và lỗi chết đồ thị):
• Module 1 (micro.consumer.rationing): Phân phối định lượng hàng hóa (Rationing).
• Module 2 (micro.consumer.price_ceiling): Kiểm soát giá trần và thiếu hụt nguồn cung (Price Ceiling & Shortage).
• Module 3A (micro.consumer.corner_solution): Giải pháp góc trên trục tọa độ (Kem vs Sữa chua, Hình 3.15 PR).
• Module 3B (micro.consumer.inkind_vs_cash): Giải pháp góc tại đỉnh gãy khúc: Trợ cấp hiện vật vs Tiền mặt (gồm 2 preset: Quỹ ủy thác giáo dục Hình 3.17 PR và Tem phiếu thực phẩm Food Stamps).
6. Cấu hình Nginx và mở đường dẫn truy cập trên Tailscale Funnel.
/opt/ai-os/products/ceo/projects/fsppm/econ_sim/
AGENTS.md
README.md
package.json
tsconfig.json
vite.config.ts
index.html
docs/
APP_CONTEXT.md
IMPLEMENTATION_PLAN.md # File này
MODULE_MIGRATION.md
WORKFLOW.md
reference/
micro_macro_animation_legacy.html
src/
main.tsx
App.tsx
index.css
engine/
shared/
types.ts # Kiểu dữ liệu dùng chung cho cả Micro & Macro
glossary.ts # Từ điển ngữ nghĩa kinh tế (I, Px, MRS, U, Y, r, P, e, k...)
math.ts # Hàm tìm nghiệm (bisection/secant), đạo hàm số, nội suy
micro/
preferences.ts # CobbDouglas, ShiftedCobbDouglas, PerfectSubstitutes, Complements
constraints.ts # LinearBudget, RationedBudget, PriceCeilingBudget, InKindBudget
solver.ts # Bộ giải tối ưu tiêu dùng & phân loại nghiệm (interior/axis/kink)
welfare.ts # Cash Equivalent, Compensating/Equivalent Variation, Breakeven
macro/
index.ts # Khung interface chờ sẵn cho IS LM, AD AS, Mundell Fleming, Solow
graph/
types.ts # GraphSpec, LayerSpec, ViewportTransform
useViewport.ts # Quy đổi tọa độ kinh tế <-> tọa độ SVG
EconGraph.tsx # Khung SVG chính: lưới, trục, mũi tên, vạch chia, sự kiện chuột
CurveLayer.tsx # Vẽ đường cong liên tục từ hàm y = f(x) hoặc x = g(y)
PolylineLayer.tsx # Vẽ đường thẳng / đường ngân sách gãy khúc (kinked line)
RegionLayer.tsx # Tô màu tập khả thi, vùng thặng dư, vùng DWL
PointLayer.tsx # Chấm điểm cân bằng (A, B, C, E) kèm nhãn tự tránh đè chữ
GuideLayer.tsx # Đường gióng nét đứt xuống hai trục và vạch mốc (quota, breakeven)
ArrowLayer.tsx # Mũi tên chỉ hướng dịch chuyển trạng thái cân bằng
GraphTooltip.tsx # Tooltip nổi khi rê chuột trên đồ thị
ui/
AppHeader.tsx # Thanh điều hướng: Chọn nhánh (Vi mô / Vĩ mô) + Chọn Module
InputBanner.tsx # Thanh tóm tắt dữ kiện đầu vào và trạng thái cân bằng gốc
ScenarioLayout.tsx # Bố cục 2 cột chuẩn (trái 7/12 đồ thị + điều khiển, phải 5/12 lý thuyết)
ParamControls.tsx # Thanh trượt thông số động + nút Đặt lại mặc định
PresetBar.tsx # Các nút chọn nhanh kịch bản mẫu
StatCards.tsx # 4 ô chỉ số đồng bộ theo thời gian thực
StepBreakdown.tsx # Khung "Các bước tính toán chi tiết"
ComparisonTable.tsx # Bảng đối sánh các trạng thái cân bằng (A vs B vs C)
MathFormula.tsx # Component render công thức KaTeX sạch đẹp
CrossCourseBridge.tsx # Thẻ liên kết sang mô hình Vi mô / Vĩ mô bổ trợ (nếu có)
scenarios/
types.ts # Hợp đồng defineScenario()
registry.ts # Danh mục toàn bộ module (phân nhánh Micro / Macro)
micro/
consumer/
rationing/
index.ts # Module 1: Định lượng hàng hóa
explain.tsx
price_ceiling/
index.ts # Module 2: Giá trần & thiếu hụt
explain.tsx
corner_solution/
index.ts # Module 3A: Giải pháp góc trên trục (Hình 3.15)
explain.tsx
inkind_vs_cash/
index.ts # Module 3B: Hiện vật vs Tiền mặt (Hình 3.17 & Food Stamps)
explain.tsx
macro/
index.ts # Danh sách chờ cho các module Vĩ mô
tests/
engine/
consumer_solver.test.ts # Kiểm tra bộ giải và các hàm thỏa dụng
scenarios/
rationing.test.ts # Bất biến Module 1
price_ceiling.test.ts # Bất biến Module 2
corner_solution.test.ts # Bất biến Module 3A
inkind_vs_cash.test.ts # Bất biến Module 3B
Khi triển khai, có thể giao tuần tự hoặc tách thành các Atomic Tasks theo đúng quy chuẩn điều phối:
base: "/econ-sim/")• Mục tiêu: Khởi tạo bộ khung Vite + React + TypeScript + Tailwind CSS + KaTeX + Vitest tại /opt/ai-os/products/ceo/projects/fsppm/econ_sim/.
• Các file cần tạo:
• package.json: dependencies gồm react, react-dom, katex; devDependencies gồm typescript, vite, @vitejs/plugin-react, tailwindcss, @tailwindcss/vite, vitest, @types/react, @types/react-dom, @types/katex.
• vite.config.ts: cấu hình base: './' (dùng đường dẫn tương đối ./ để bản build tĩnh chạy được ở cả /econ-sim/, /micro-sim/ hoặc mở preview trực tiếp mà không lỗi đường dẫn file JS/CSS).
• tsconfig.json: bật "strict": true, "noImplicitAny": true.
• index.html và src/index.css: nạp stylesheet của Tailwind và katex/dist/katex.min.css.
• Tiêu chí nghiệm thu (Acceptance Criteria):
• Chạy npm install và npm run build thành công, sinh ra thư mục dist/.
• Chạy npm test -- --run hoạt động bình thường.
src/engine/shared/ & src/engine/micro/)• Mục tiêu: Viết toàn bộ lõi tính toán kinh tế thuần túy, không phụ thuộc React hay DOM, giải quyết triệt để các lỗi toán học của bản Gemini cũ.
• Chi tiết từng file:
1. src/engine/shared/glossary.ts:
• Khai báo từ điển thuật ngữ cho cả Vi mô (I, Px, Py, X, Y, U, MRS, CS, PS, DWL) và Vĩ mô (Y, C, I_macro, G, NX, r, i, P, pi, u, e, k), gồm: symbol (LaTeX), name_vi, name_en, unit, description.
2. src/engine/shared/math.ts:
• Hàm clamp(val, min, max), approxEqual(a, b, eps = 1e-4), solveRootBisection(fn, low, high, tol = 1e-6), sampleCurve(fn, xMin, xMax, steps, yMaxClip).
3. src/engine/micro/preferences.ts:
• createCobbDouglas(alpha: number, scale?: number):
• Mặc định chuẩn hóa hoặc chế độ nhân U(x,y) = x^alpha * y^(1-alpha) (kèm tuỳ chọn productForm: true cho U(x,y) = x * y ở Module 1 và 2 để giữ số nguyên đẹp $U_A = 100, U_B = 84, 102, 72$).
• mrs(x, y) = (alpha / (1 - alpha)) * (y / x).
• indifferenceY(u, x): giải chính xác $Y$ theo $U$ và $X$.
• indirectUtility(Px, Py, I) và expenditure(Px, Py, u): dùng để tính Giá trị tiền mặt tương đương (Cash Equivalent) ở Module 3B.
• createShiftedCobbDouglas(alpha: number, shift: number):
• Hàm $U(X, Y) = (X + s)^\alpha (Y + s)^{1 - \alpha}$ (dùng cho Module 3A với $s = 10$).
• mrs(x, y) = (alpha / (1 - alpha)) * ((y + s) / (x + s)).
• indifferenceY(u, x) = (u / (x + s)^alpha)^(1 / (1 - alpha)) - s.
4. src/engine/micro/constraints.ts:
• createLinearBudget({ I, Px, Py }): đường thẳng từ $(0, I/P_Y)$ đến $(I/P_X, 0)$.
• createRationedBudget({ I, Px, Py, maxX }): đường ngân sách bị chặt đứng tại $X = \min(\text{maxX}, I/P_X)$, tạo đỉnh gãy tại $(\text{maxX}, (I - P_X \cdot \text{maxX})/P_Y)$.
• createPriceCeilingBudget({ I, Px_ceiling, Py, maxX }): đường ngân sách xoay ra ngoài theo giá trần $P_{X,\text{trần}}$, nhưng bị chặn đứng tại lượng cung thực tế $\text{maxX}$.
• createInKindBudget({ I0, transferX, Px, Py }): bắt đầu từ $(0, I_0/P_Y)$, đi ngang sang đỉnh gãy $B(T/P_X, I_0/P_Y)$, rồi dốc xuống $((I_0 + T)/P_X, 0)$.
5. src/engine/micro/solver.ts:
• Hàm solveConsumerOptimum(pref, budget):
• Tìm điểm tối đa hóa $U(X, Y)$ trên các đoạn của budget.
• Tự động phân loại nghiệm:
• "interior": nằm bên trong đoạn nghiêng và $|MRS - P_X/P_Y| < 10^{-3}$.
• "corner_axis": chạm trục tọa độ ($Y = 0$ với $MRS \ge P_X/P_Y$, hoặc $X = 0$ với $MRS \le P_X/P_Y$).
• "corner_kink": nằm ngay tại đỉnh gãy khúc (do hạn mức định lượng, thiếu hụt giá trần, hoặc trợ cấp hiện vật).
6. src/engine/micro/welfare.ts:
• findPriceCeilingBreakevenX({ pref, I, Px_ceiling, Py, targetUtility }): giải nghiệm $X_{\text{hòa vốn}}$ sao cho $U(X, (I - P_{X,\text{trần}} X)/P_Y) = U_0$. Với $I=200, P_{X,\text{trần}}=5, P_Y=10, U_0=100$, trả về chính xác $20 - \sqrt{200} \approx 5.8579$.
• computeInKindWelfare({ alpha, I0, transfer }): trả về điểm gốc $A$, điểm hiện vật $B$, điểm tiền mặt $C$, ngưỡng bắt đầu bị kẹt $T^ = \frac{\alpha}{1-\alpha} I_0$, giá trị tiền mặt tương đương (Cash Equivalent) và phần tổn thất phúc lợi.
• Tiêu chí nghiệm thu:*
• Toàn bộ unit tests trong tests/engine/consumer_solver.test.ts pass 100%.
src/graph/)• Mục tiêu: Thay thế 600 dòng code Canvas rối rắm trong file cũ bằng bộ component SVG rõ nghĩa, tự co giãn độ phân giải cao và dùng lại được cho cả đồ thị Vi mô $(X, Y)$, Cung Cầu $(Q, P)$ và Vĩ mô $(Y, r), (Y, P)$.
• Chi tiết các component:
1. useViewport.ts: nhận { maxX, maxY, width, height, padding }, trả về toScreenX(x), toScreenY(y), toModelX(sx), toModelY(sy).
2. EconGraph.tsx: vẽ khung <svg viewBox="0 0 640 480">, lưới tọa độ nhạt, hai trục có mũi tên, vạch chia số tự động, nhãn tên trục (nằm ngang cho trục hoành, xoay dọc cho trục tung), và bắt sự kiện onMouseMove để hiển thị GraphTooltip.
3. RegionLayer.tsx: vẽ <polygon> tô màu bán trong suốt cho tập ngân sách khả thi hoặc vùng tổn thất/thặng dư.
4. PolylineLayer.tsx: vẽ các đường thẳng hoặc đường ngân sách gãy khúc (hỗ trợ nét liền, nét đứt, độ dày, màu sắc, nhãn).
5. CurveLayer.tsx: nhận hàm toán học fn(x) (ví dụ indifferenceY(u, x)), lấy mẫu mượt theo maxX/maxY, cắt tự động khi vượt khung trục và đặt nhãn ở đầu đường cong.
6. GuideLayer.tsx: vẽ đường gióng nét chấm từ điểm $(X, Y)$ xuống hai trục kèm nhãn tọa độ trên trục, và vẽ đường thẳng đứng/ngang đánh dấu ngưỡng (như hạn mức $\bar{X}$, mức cung $X_{\text{thực}}$, hoặc vạch hòa vốn $X_{\text{hòa vốn}}$).
7. PointLayer.tsx & ArrowLayer.tsx: vẽ các điểm tròn có viền trắng nổi bật kèm nhãn (có offset tuỳ chỉnh để không đè lên nhau khi $B$ tiến gần $A$ hoặc $C$) và mũi tên chỉ hướng dịch chuyển từ $A \to B$.
• Tiêu chí nghiệm thu:
• Không có bất kỳ công thức kinh tế nào nằm trong src/graph/. Lớp này chỉ nhận dữ liệu hình học từ GraphSpec và vẽ ra SVG.
src/ui/)• Mục tiêu: Tái tạo giao diện 2 cột sạch sẽ từ file mẫu, bổ sung thanh chọn nhánh Kinh tế Vi mô / Kinh tế Vĩ mô và tự động dựng toàn bộ bảng điều khiển từ khai báo của module.
• Chi tiết các component:
1. AppHeader.tsx:
• Bộ lọc nhánh: Tất cả | Kinh tế Vi mô | Kinh tế Vĩ mô.
• Thanh chọn Module hiện tại và badge chương giáo trình (ví dụ Pindyck & Rubinfeld • Chương 3).
2. InputBanner.tsx:
• Hiển thị dải thông số chuẩn đầu vào của mô hình đang mở và trạng thái cân bằng gốc, kèm nút mở nhanh nguồn trích dẫn APA 7.
3. ScenarioLayout.tsx:
• Cột trái (7/12): Tiêu đề đồ thị + Chú giải màu (Legends) + EconGraph + ParamControls + PresetBar + StatCards + StepBreakdown.
• Cột phải (5/12): Thẻ bài giảng lý thuyết chuyên sâu của module + ComparisonTable + CrossCourseBridge (gợi ý liên kết sang mô hình vi mô/vĩ mô liên quan) + Footnote công thức hàm đang dùng.
4. ParamControls.tsx & PresetBar.tsx:
• Tự động đọc scenario.params để render các thanh trượt kèm nhãn mốc (trái, giữa, phải) và nút Đặt lại mặc định.
• Tự động đọc scenario.presets để render các nút bấm chọn nhanh kịch bản.
5. StatCards.tsx, StepBreakdown.tsx, ComparisonTable.tsx:
• Nhận mảng dữ liệu từ kết quả model(params), hiển thị đồng bộ theo thời gian thực.
src/scenarios/micro/consumer/)• Mục tiêu: Chuyển toàn bộ nội dung từ file mẫu sang kiến trúc mới theo đúng đặc tả trong docs/MODULE_MIGRATION.md, không ghi cứng bất kỳ con số nào.
• Danh sách các module cần hoàn thành:
1. Module 1: src/scenarios/micro/consumer/rationing/ (Phân phối định lượng)
• Thông số gốc: $I = 200, P_X = 10, P_Y = 10, U = X \cdot Y \Rightarrow A(10, 10), U_A = 100$.
• Thanh trượt: $\bar{X} \in [2, 14]$, bước $0.5$, mặc định $6.0$.
• Presets: Siết chặt định ngạch (X̄ = 6) | Hạn mức nhẹ (X̄ = 8) | Không ràng buộc (X̄ = 12).
• Giải thích cột phải và bảng đối sánh tự cập nhật theo $\bar{X}$; khi $\bar{X} \ge 10$ tự động hiển thị giải thích tại sao hạn mức cao hơn nhu cầu tự do thì không làm giảm phúc lợi.
2. Module 2: src/scenarios/micro/consumer/price_ceiling/ (Giá trần & Thiếu hụt)
• Thông số gốc: $I = 200, P_X = 10, P_Y = 10, U = X \cdot Y \Rightarrow A(10, 10), U_A = 100$.
• Hai thanh trượt: Giá trần $P_{X,\text{trần}} \in [2, 9]$ (mặc định $5.0$) và Lượng thực mua được $X_{\text{thực}} \in [2, 16]$ (mặc định $6.0$).
• Presets: Kịch bản 1: Dư giả hơn (Px' = 5, X_thực = 6 → UB = 102) | Kịch bản 2: Khó khăn hơn (Px' = 5, X_thực = 4 → UB = 72) | Kịch bản 3: Hòa vốn thỏa dụng (Px' = 5, X_thực = 5.86 → UB = 100).
• Vẽ thêm vạch dọc mảnh tại $X_{\text{hòa vốn}}$ để người học nhìn thấy ngay ranh giới phúc lợi.
• Gắn CrossCourseBridge: liên kết sang chủ đề Kiểm soát giá và Tổn thất vô ích (DWL) trên thị trường Cung Cầu (Vi mô Ch.2 & Ch.9) và Lạm phát bị kìm nén / Cú sốc cung (Vĩ mô AS AD).
3. Module 3A: src/scenarios/micro/consumer/corner_solution/ (Giải pháp góc trên trục, Hình 3.15)
• Hàm thỏa dụng đã fix: $U(X, Y) = (X + 10)^\alpha (Y + 10)^{1-\alpha}$, ngân sách $10X + 10Y = 200 \Rightarrow X + Y = 20$.
• Thanh trượt: Trọng số ưa thích Kem $\alpha \in [0.20, 0.95]$, bước $0.05$, mặc định $0.85$.
• Presets: Giải pháp góc: Chỉ mua Kem (α = 0.85 → B(20, 0), MRS = 1.89 > 1) | Ranh giới chuyển tiếp (α = 0.75 → B(20, 0), MRS = 1.00) | Giải pháp bên trong: Mua cả hai (α = 0.55 → E(12, 8), MRS = 1.00).
• Khi kéo $\alpha$, đường bàng quan thật dịch chuyển mượt mà từ tiếp điểm bên trong $E$ sang cắt trục hoành tại góc $B(20, 0)$.
4. Module 3B: src/scenarios/micro/consumer/inkind_vs_cash/ (Trợ cấp Hiện vật vs Tiền mặt, Hình 3.17 & Food Stamps)
• Hàm thỏa dụng đã fix: $U(X, Y) = X^\alpha Y^{1-\alpha}$, thu nhập gốc $I_0 = 100\text{ USD}$, $P_X = P_Y = 1$.
• Hai chế độ Preset chính (chuyển đổi ngay trên đầu module như bản gốc):
• Preset 1: Quỹ ủy thác giáo dục của Jane (Hình 3.17): $\alpha = 0.30$, thanh trượt quỹ học bổng $T \in [20, 140]$ (mặc định $80\text{ USD}$). Ngưỡng bắt đầu bị kẹt tại đỉnh gãy là $T^ = 42.86\text{ USD}$. Tại $T = 80$: điểm gốc $A(30, 70)$, điểm học bổng kẹt tại đỉnh gãy $B(80, 100)$ với $U_B = 93.52, MRS_B = 0.54 < 1$, điểm tiền mặt đạt tiếp điểm $C(54, 126)$ với $U_C = 97.72 > U_B$ (giá trị tiền mặt tương đương là $72.27\text{ USD}$).
• Preset 2: Tem phiếu thực phẩm (Food Stamps): $\alpha = 0.25$, thanh trượt mệnh giá phiếu $T \in [20, 140]$ (mặc định $70\text{ USD}$). Ngưỡng bắt đầu bị kẹt là $T^ = 33.33\text{ USD}$. Tại $T = 70$: điểm gốc $A(25, 75)$, điểm tem phiếu kẹt tại $B(70, 100)$ với $U_B = 91.47, MRS_B = 0.48 < 1$, điểm tiền mặt đạt $C(42.5, 127.5)$ với $U_C = 96.88 > U_B$ (giá trị tiền mặt tương đương là $60.51\text{ USD}$).
• Khi người học kéo thanh trượt $T$ xuống dưới ngưỡng $T^$ (ví dụ $T = 30$), đồ thị và lời giải tự động chỉ ra rằng khoản trợ cấp hiện vật nhỏ hơn mức chi tự nguyện nên không gây méo mó lựa chọn ($B$ trùng khít với $C$, $U_B = U_C$).
• Gắn CrossCourseBridge: liên kết sang Chuyển giao thu nhập và Tiêu dùng biên (MPC)* trong mô hình IS LM (Kinh tế Vĩ mô).
• Mục tiêu: Đảm bảo 100% bất biến kinh tế được kiểm chứng bằng code và xuất bản ứng dụng ra đường dẫn riêng.
• Các bước thực hiện:
1. Chạy npm test -- --run để xác nhận toàn bộ các bài test trong tests/engine/ và tests/scenarios/ đều pass.
2. Chạy npm run build để xuất bản tĩnh vào /opt/ai-os/products/ceo/projects/fsppm/econ_sim/dist/.
3. Cập nhật /etc/nginx/sites-available/hermes-dashboard (cổng 9121, đang nối với Tailscale Funnel), thêm 2 block:
nginx
location /econ-sim/ {
alias /opt/ai-os/products/ceo/projects/fsppm/econ_sim/dist/;
index index.html;
try_files $uri $uri/ /econ-sim/index.html;
}
location /micro-sim/ {
alias /opt/ai-os/products/ceo/projects/fsppm/econ_sim/dist/;
index index.html;
try_files $uri $uri/ /micro-sim/index.html;
}
4. Kiểm tra cấu hình bằng nginx -t rồi reload Nginx (systemctl reload nginx).
5. Xác minh HTTP 200 qua curl -I https://vmi3427693.tail8c1aaf.ts.net/econ-sim/.
Khi Nhi muốn giao cho một agent khác (hoặc bảo Khôi bắt đầu code ở phiên sau), chỉ cần gửi đúng câu lệnh ngắn gọn sau:
"Đọc bộ tài liệu tại
/opt/ai-os/products/ceo/projects/fsppm/econ_sim/theo thứ tự:AGENTS.md→docs/APP_CONTEXT.md→docs/MODULE_MIGRATION.md→docs/IMPLEMENTATION_PLAN.md, sau đó thực thi từ Task 1 đến Task 6."