Ichi

Ichi là sản phẩm học tiếng Nhật đa nền tảng dành cho người đi làm. MVP hiện tập trung vào một luồng rõ ràng: người học mở app, xem bài cần học hôm nay, đi theo lộ trình, luyện viết, làm checkpoint tương tác nếu bài có checkpoint thật, rồi hoàn thành bài và quay lại ôn tập. Đội vận hành dùng Admin web để xem gói học, chặng học, bài học, giao dịch, gia hạn và dữ liệu triển khai.

Workspace gồm năm phần chính:

Khu vực	Vai trò	Công nghệ
ichi-android	Ứng dụng Android cho người học	Kotlin, Android Views
ichi-ios	Ứng dụng iOS cho người học	SwiftUI
ichi-backend	API học tập, quyền học, billing, roadmap, progress	Spring Boot
ichi-admin	Trang quản trị nội dung và vận hành	VueJS, Vite, nginx
docs	Tài liệu sản phẩm, ảnh chụp và bằng chứng QA	Markdown, PNG, XML

Trang quyền riêng tư dùng cho người học và store review nằm ở docs/privacy.md. Bản HTML tĩnh để publish qua GitHub Pages nằm ở docs/privacy.html.

Giới Thiệu Nhanh

Ichi phục vụ hai nhóm người dùng:

Nhóm	Mục tiêu	Màn hình chính
Người học Android/iOS	Học 15-30 phút mỗi ngày, biết bài tiếp theo, luyện viết và ôn đúng lỗi	Trang chủ, lộ trình, chi tiết bài, bảng viết, quyền học
Người vận hành Admin	Kiểm tra dữ liệu học, gói bán, chặng học, giao dịch và gia hạn	Dashboard, gói học, chặng học, bài học, giao dịch, gia hạn

Điểm đã chốt sau audit CEO ngày 07/06/2026:

• Android release hiện là version 0.2.2 (versionCode = 4) để phát hành AAB mới nhất của luồng phân tầng quyền học, bật R8 và có tệp gỡ rối mã nguồn mapping.txt.
• Giá gói Ichi Lộ trình tháng đồng bộ giữa backend, admin, Android và iOS là 199.000 VND / tháng.
• Android mở bằng Guide bắt đầu ở lần vào đầu tiên, sau đó người học mới đi vào trang chủ, lộ trình, luyện viết, ôn tập và gói học.
• Android có navbar cố định ở đáy màn hình, mỗi mục dùng icon font local kèm nhãn Trang chủ, Lộ trình, Viết, Ôn tập, Gói; bấm tab nào app cuộn tới đúng vùng chức năng đó.
• Android hiển thị Hệ thống gói rõ ràng: Ichi Khởi đầu miễn phí mở 5 bài đầu, bài 6-12 mở từng bài bằng quảng cáo thưởng AdMob, từ bài 13 cần Ichi Lộ trình tháng; catalog gói được lấy từ /api/packages và có fallback offline.
• AdMob Android đang dùng Google Mobile Ads SDK play-services-ads:25.3.0, App ID test ca-app-pub-3940256099942544~3347511713 và rewarded test ad unit ca-app-pub-3940256099942544/5224354917; trước khi publish production phải thay bằng ID thật.
• Luyện viết Android không cho nhập romaji hoặc bản dịch để qua bài; người học phải nhập đúng mẫu tiếng Nhật, viết nét đủ dài/rõ và vượt checkpoint nếu bài có checkpoint thật.
• Android/iOS không còn kẹt hoàn thành bài khi bài chưa có checkpoint tương tác; bài đó chỉ yêu cầu luyện viết đạt trước khi chốt.
• Android/iOS không còn mặc định dùng chung user-demo; mỗi cài đặt app sinh một ichi-user-* riêng để tránh ghi chung tiến độ/quyền học.
• Android vẫn cho bắt đầu với Ichi Khởi đầu không cần đăng nhập Google, nhưng khi mua hoặc gia hạn Ichi Lộ trình tháng app bắt đăng nhập Google trước, rồi gắn quyền học và giao dịch với learner id dạng google_*.
• iOS không giả vờ có StoreKit production: bản Debug/MVP ghi rõ kích hoạt demo, bản Release khóa mock nếu chưa bật cấu hình riêng.
• Admin nginx cho phép preflight header X-Ichi-Admin-Key.

Ảnh Chụp Màn Hình Thật

Các ảnh dưới đây là bộ ảnh thật của vòng audit CEO. Ảnh Android được chụp lại sau thay đổi guide, navbar, hệ thống gói, quảng cáo thưởng và luyện viết với hậu tố 20260607-ad-tier; bản build hiện tại là version 0.2.2 và không đổi layout so với bộ ảnh này.

Bảng Ảnh Android

README không ghép nhiều màn vào một ảnh duy nhất. Mỗi ảnh rời bên dưới đi kèm ghi chú chức năng để người dùng biết màn đó dùng làm gì.

Màn hình	Ảnh	Chức năng
Guide bắt đầu		Màn đầu tiên khi cài mới: giải thích chặng học, bài đầu tiên, luật luyện viết đúng, 5 bài đầu miễn phí, bài 6-12 mở bằng quảng cáo thưởng và bài cao hơn cần mua gói.
Trang chủ		Cho người học xem nhịp học hôm nay, bài đang học, sổ tay lộ trình, CTA bắt đầu theo guide và navbar icon font cố định ở đáy.
Lộ trình		Hiển thị danh sách bài theo chặng, trạng thái đã mở/đang học/Xem quảng cáo/Cần gói, lý do khóa nếu có và tab Lộ trình đang active.
Chi tiết bài		Mở nội dung bài đã mở, câu mẫu, mục tiêu, luyện tập, nút hoàn thành và vẫn giữ navbar để quay nhanh về các vùng chính.
Bảng viết		Cho người học viết nét dài rõ, nhập đúng mẫu tiếng Nhật, xóa bảng, nhận feedback nếu nhập romaji hoặc nét quá ngắn.
Hệ thống gói		Cho biết gói đang dùng, giải thích Ichi Khởi đầu miễn phí, tầng quảng cáo thưởng, gói tháng, trạng thái Google và hành động mua/gia hạn yêu cầu đăng nhập Google trước.

Bảng Ảnh Admin Web

Màn hình	Ảnh	Chức năng
Dashboard Admin		Cho đội vận hành xem tổng quan gói, doanh thu, roadmap, giao dịch và trạng thái API đang dùng.
Thư viện bài học		Cho đội vận hành rà danh sách bài học, nội dung preview, trạng thái dữ liệu và các mục cần chỉnh.
Admin mobile		Kiểm tra layout responsive khi vận hành trên màn nhỏ, đảm bảo sidebar/nội dung xếp dọc dễ đọc.

Bảng Ảnh iOS

README dùng ảnh rời trong bảng Markdown để mỗi màn iOS có ghi chú chức năng rõ ràng.

Màn hình	Ảnh	Chức năng
Trang chủ		Cho người học xem bài trọng tâm, sổ tay lộ trình, danh sách bài và trạng thái ôn tập trong trang cuộn chính.
Chi tiết bài		Hiển thị câu mẫu, ý nghĩa, giải thích, luyện nói, luyện viết và phần luyện tập của bài đang chọn.
Nội dung sâu		Dùng để kiểm tra phần nội dung học sâu/fallback: câu mẫu, ý nghĩa, giải thích và hướng dẫn luyện nói.
Bảng viết		Cho người học viết trong khung, xóa bảng, nhập lại mẫu và nộp luyện viết; bản chụp evidence đưa phần này lên đầu để dễ QA.

iOS Trên macVPS

iOS đã được build lại trên macVPS bằng Xcode 26.5 từ source hiện tại:

xcodebuild -project Ichi.xcodeproj -scheme Ichi -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath .derivedData CODE_SIGNING_ALLOWED=NO build

Kết quả: ** BUILD SUCCEEDED ** tại /Users/Minh/Documents/Ichi/ichi-ios-audit-20260606-202232. Simulator iPhone 17 Pro đã boot, app launch được bundle solutions.thanhtruc.ichi, và bộ ảnh iOS mới đã được chụp bằng cùng hậu tố 20260606-ceo-audit. Các màn chi tiết dùng biến evidence khi launch simulator: ICHI_EVIDENCE_DETAIL_FIRST, ICHI_EVIDENCE_DEPTH_ONLY và ICHI_EVIDENCE_WRITING_FIRST; nếu không có các biến này, luồng production vẫn mở trang chủ cuộn bình thường.

Lưu ý nguồn dữ liệu: bộ ảnh iOS trong README được chụp với SIMCTL_CHILD_ICHI_API_BASE_URL=http://127.0.0.1:9 để ép app dùng fallback local khi public backend chưa redeploy seed nội dung mới. Vì vậy Home iOS hiển thị 3 khóa · 3 chặng · 9 bài. Gate traversal local bên dưới vẫn chạy backend Windows local ở port 28086, nên kết quả là 15 khóa, 45 chặng, 217 bài; đây là hai nguồn dữ liệu kiểm thử khác nhau chứ không phải ảnh cũ hoặc cache CDN.

Hướng Dẫn Layout Và Luồng Sử Dụng

README chính là tài liệu hướng dẫn người dùng và người vận hành. Mỗi khi đổi layout, navigation, trạng thái màn hình, CTA, quyền học, purchase, loading, error, empty, locked, entitlement hoặc fallback, CEO phải cập nhật README này cùng lúc bằng tiếng Việt có dấu.

Layout Cho Người Học

Người học đọc màn hình từ trên xuống:

1. Lần đầu mở Android, app hiển thị Guide bắt đầu để người học hiểu chặng học, bài đầu tiên, luật luyện viết và hệ thống gói.
2. Sau khi bắt đầu guide, header cho biết nhịp học, điểm và trạng thái gói; navbar icon font cố định ở đáy giúp nhảy tới Trang chủ, Lộ trình, Viết, Ôn tập, Gói.
3. Kế hoạch hôm nay hiển thị bài nên học ngay, thời lượng và nút tiếp tục.
4. Sổ tay lộ trình giải thích mục tiêu chặng, mẫu cần nhớ và có nút Bắt đầu theo guide.
5. Lộ trình học cho biết bài đang học, bài đã mở, bài có thể mở bằng quảng cáo thưởng, bài cần gói tháng và số bài còn lại.
6. Chi tiết bài hiển thị mục tiêu, câu mẫu, nội dung sâu, từ vựng, ví dụ, luyện viết và luyện tập.
7. Bảng viết tay yêu cầu người học nhập đúng mẫu tiếng Nhật, viết nét đủ dài/rõ và không dùng romaji để thay thế.
8. Nếu bài có checkpoint tương tác, người học phải đạt từ 80 điểm. Nếu bài chưa có checkpoint item thật, app nói rõ chỉ cần luyện viết đạt để hoàn thành.
9. Hệ thống gói cho biết gói đang dùng, Ichi Khởi đầu miễn phí, tầng quảng cáo thưởng, gói tháng, trạng thái Google và hành động mua/gia hạn.

Luồng Người Học Android

flowchart TD
  open["Mở app Android"] --> first{"Đã xem Guide bắt đầu?"}
  first -->|Chưa| guide["Hiển thị Guide bắt đầu"]
  guide --> guideAction["Bắt đầu bài đầu tiên, xem lộ trình hoặc xem gói học"]
  first -->|Rồi| user["Sinh hoặc đọc learner id riêng của thiết bị"]
  guideAction --> user
  user --> entitlement["Đọc quyền học đã lưu và làm mới từ backend"]
  entitlement --> packages["Tải catalog gói từ /api/packages, nếu lỗi dùng fallback"]
  packages --> home["Hiển thị Trang chủ cùng navbar đáy"]
  home --> path["Chọn tab Lộ trình, Viết, Ôn tập hoặc Gói"]
  path --> tier{"Bài thuộc tầng nào?"}
  tier -->|5 bài đầu hoặc đã mua gói| detail["Mở chi tiết bài"]
  tier -->|Bài 6-12| reward["Xem quảng cáo thưởng AdMob"]
  reward --> earned{"Đã nhận reward?"}
  earned -->|Có| detail
  earned -->|Chưa| path
  tier -->|Từ bài 13| buy["Mở tab Gói để mua Ichi Lộ trình tháng"]
  buy --> signin["Đăng nhập Google trước khi mua hoặc gia hạn"]
  signin --> entitlement
  detail --> writing["Nhập đúng mẫu tiếng Nhật và viết nét rõ trên bảng viết tay"]
  writing --> localCheck{"Mẫu/nét viết hợp lệ?"}
  localCheck -->|Không| feedback["Hiện feedback: không dùng romaji, nét quá ngắn hoặc thiếu nét"]
  localCheck -->|Có| checkpoint{"Có checkpoint tương tác?"}
  checkpoint -->|Có| pass["Làm checkpoint, cần >= 80 điểm"]
  checkpoint -->|Không| complete["Hoàn thành sau luyện viết"]
  pass --> complete
  complete --> review["Lưu tiến độ, mở bài tiếp theo và đưa mục vào ôn tập"]

Loading

Luồng quyền học Android chia theo cấp rõ ràng. Ichi Khởi đầu là miễn phí và mở 5 bài đầu. Bài 6-12 thuộc tầng quảng cáo thưởng: người học bấm Xem quảng cáo để mở, app tải rewarded ad bằng AdMob, nhận reward thì lưu lesson id vào bộ nhớ riêng và mở bài đó. Từ bài 13 trở đi là tầng mua gói, người học được đưa về tab Gói để mua hoặc gia hạn Ichi Lộ trình tháng.

Luồng mua gói Android nằm ở tab Gói. Người học thấy thẻ Hệ thống gói trước danh sách package để hiểu Ichi Khởi đầu miễn phí, tầng quảng cáo thưởng và Ichi Lộ trình tháng mở toàn bộ đường học hiện có, ôn tập ngắt quãng và bài đánh giá. Catalog gói được tải bằng GET /api/packages; nếu API lỗi, app dùng fallback tiếng Việt để màn gói không bị trống. Người học có thể bắt đầu với gói Khởi đầu không cần đăng nhập Google. Khi bấm mua hoặc gia hạn Ichi Lộ trình tháng, app kiểm tra tài khoản Google; nếu chưa có, app mở Google Sign-In, lưu email/id Google, đổi learner id sang dạng google_*, rồi mới mở Google Play Billing. Debug/local dùng nút Thử mua gói; release dùng Google Play Billing. App gửi purchase token đến backend để xác minh, rồi lưu entitlement active nếu backend trả quyền học hợp lệ.

AdMob trong bản Android version 0.2.2 đang dùng test ads theo tài liệu Google: test App ID ca-app-pub-3940256099942544~3347511713 và rewarded test ad unit ca-app-pub-3940256099942544/5224354917. Các ID này chỉ dùng để QA/dev, không dùng làm ID kiếm tiền production.

Luồng Người Học iOS

iOS dùng một trang SwiftUI cuộn chính. HomeViewModel.bootstrap() làm mới entitlement, tải roadmap, assessment queue, daily review và sổ tay chặng. Người học chọn bài trong lộ trình, học trong StudyLessonCard, hoàn thành luyện viết, rồi hoàn thành bài.

iOS hiện chưa có StoreKit production. Bản Debug/MVP hiển thị rõ kích hoạt demo; bản Release không kích hoạt mock nếu chưa bật ICHI_ENABLE_DEMO_PURCHASES=1. Khi làm bán thật, cần nối StoreKit trước khi xem purchase iOS là production-ready.

Luồng Admin Cho Người Vận Hành

flowchart TD
  open["Mở Ichi Admin"] --> key["Nhập Khóa admin nếu backend yêu cầu"]
  key --> dashboard["Xem tổng quan gói, doanh thu, gia hạn, lộ trình"]
  dashboard --> packages["Kiểm tra Gói học"]
  dashboard --> units["Kiểm tra hoặc chỉnh Chặng học"]
  dashboard --> lessons["Xem trước Bài học"]
  dashboard --> purchases["Rà Giao dịch"]
  dashboard --> subscriptions["Rà Gia hạn"]
  dashboard --> export["Xuất báo cáo JSON"]

Loading

Admin web hiện có sidebar cố định trên desktop và layout xếp dọc trên mobile. Dashboard dùng API thật khi có VITE_API_BASE_URL; nếu không có API, admin dùng dữ liệu mẫu và phải hiển thị nhãn Dữ liệu mẫu.

Trạng Thái Người Dùng Cần Hiểu

Trạng thái	Người dùng thấy gì	Hành động tiếp theo
loading	Skeleton, progress hoặc thông báo đang tải	Chờ backend hoặc kiểm tra mạng
error	Banner/thông báo lỗi	Thử lại, đổi backend local hoặc báo vận hành
empty	Danh sách trống	Kiểm tra dữ liệu backend/admin
locked	Bài/gói bị khóa và có lý do: Xem quảng cáo hoặc Cần gói	Bài 6-12 xem quảng cáo thưởng để mở; từ bài 13 mua/gia hạn gói
entitlement active	Gói đang mở	Tiếp tục học trong phạm vi gói
entitlement expired	Quyền học hết hạn	Quay về gói Khởi đầu hoặc gia hạn
fallback	Nội dung có sẵn được dùng khi backend lỗi	Vẫn học được phần tối thiểu, vận hành kiểm tra API
checkpoint thiếu item	Không có checkpoint tương tác	Hoàn thành sau khi luyện viết đạt

Checklist CEO Khi Đổi Layout

CEO phải kiểm đủ các điểm này trước khi chốt:

1. README mô tả đúng màn hình mới, thứ tự section và thao tác tiếp theo của người dùng.
2. README có tiếng Việt có dấu, không dùng ảnh cũ hoặc đường dẫn cache-prone.
3. Nếu đổi mobile layout, phải chụp lại từng ảnh điện thoại rời và đưa vào bảng Markdown có cột Chức năng.
4. Nếu đổi Admin layout, phải chụp lại desktop và mobile.
5. Nếu đổi iOS layout, phải chạy xcodebuild trên macVPS hoặc ghi rõ blocker.
6. Nếu đổi purchase/entitlement, README phải nói rõ debug, mock, Google Play, StoreKit và production.
7. Nếu đổi guide, navbar hoặc CTA, README phải nói rõ màn nào xuất hiện trước, tab nào đưa tới đâu và nút nào tạo hành động gì.
8. Nếu đổi bài học/progress, README phải nói rõ loading, error, empty, locked, entitlement và fallback.
9. Chạy lại gate phù hợp trước khi push.

Kiểm Chứng Audit CEO

Các lệnh đã chạy trong vòng này:

Gate	Kết quả
npm run build trong ichi-admin	Pass
.\gradlew.bat test trong ichi-backend	Pass
.\gradlew.bat :app:assembleDebug trong ichi-android	Pass, đã cài debug để chụp ảnh guide/navbar/quảng cáo thưởng/gói
.\gradlew.bat :app:assembleRelease :app:bundleRelease trong ichi-android	Pass, đã tạo APK/AAB release ký bằng Orin tại D:\ThanhTrucSolutions\Ichi\ichi-android\app\build\outputs\bundle\release\app-release.aab
R8/ProGuard mapping	Release bật R8 và tạo D:\ThanhTrucSolutions\Ichi\ichi-android\app\build\outputs\mapping\release\mapping.txt để upload lên Play Console khi cần tệp gỡ rối mã nguồn
apksigner verify --verbose --print-certs app-release.apk	Pass, APK release ký v2 bằng chứng chỉ Orin
jarsigner -verify -verbose -certs app-release.aab	Pass, AAB release có chữ ký JAR Orin; cảnh báo chain là chứng chỉ tự ký
adb install -r app-release.apk trên emulator-5554	Pass, bản minified chạy với versionCode=4, versionName=0.2.2
node tools\verify-mobile-client-contract.mjs	Pass 44 checks
node tools\verify-readme-layout-sync.mjs	Pass 14 headings và 13 ảnh bắt buộc, gồm 6 ảnh Android hậu tố 20260607-ad-tier
node tools\verify-ichi-roadmap.mjs với backend local 28086	Pass: 15 khóa, 45 chặng, 217 bài, full traversal 217/217
xcodebuild trên macVPS	Pass

Rủi ro còn lại cho production:

• Backend vẫn là MVP chưa có auth/session thật; nhiều endpoint còn nhận userId từ client. Mobile đã tránh dùng chung user-demo, nhưng production cần identity/auth trước khi bán rộng.
• iOS StoreKit production chưa nối.
• Mobile vẫn dùng HTTP public endpoint theo cấu hình hiện tại; production nên chuyển sang HTTPS trước khi gửi purchase token thật.
• Backend store vẫn là in-memory + JSON file, phù hợp MVP nhưng chưa thay thế được database/migration/audit trail.

Lệnh Build Cục Bộ

Android:

cd D:\ThanhTrucSolutions\Ichi\ichi-android
.\gradlew.bat :app:assembleDebug

Admin web:

cd D:\ThanhTrucSolutions\Ichi\ichi-admin
npm install
npm run build

Backend:

cd D:\ThanhTrucSolutions\Ichi\ichi-backend
.\gradlew.bat test

iOS trên macOS/Xcode:

cd /path/to/Ichi/ichi-ios
xcodebuild -project Ichi.xcodeproj -scheme Ichi -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build