HƯỚNG DẪN 2: CODE MỘT HỆ THỐNG EDTECH THỰC CHỨNG CHO AI AGENT

Mục đích

Tài liệu này hướng dẫn AI coding agent biến thiết kế sản phẩm từ HUONG-DAN-1-THIET-KE-DOMAIN-HE-THONG-EDTECH-CHO-AI-AGENT.md thành một hệ thống EdTech có thể chạy, kiểm thử và mở rộng. Agent phải code như đang xây sản phẩm thật, không làm demo mỏng.

Ưu tiên của hệ thống:

1. Học tập trước tính năng. 2. Giáo viên có quyền kiểm soát thật. 3. AI có audit, evaluation và fallback. 4. Dữ liệu học tập được bảo vệ từ kiến trúc. 5. MVP nhỏ nhưng domain sạch. 6. Code dễ thay đổi khi sản phẩm học từ pilot.

Nguyên tắc làm việc

Trước khi code, agent phải:

1. Đọc HUONG-DAN-1-THIET-KE-DOMAIN-HE-THONG-EDTECH-CHO-AI-AGENT.md. 2. Đọc Hệ thống Synvia hiện tại.md. 3. Đọc sơ bộ repo lms/, đặc biệt lms/sy, lms/docs/dev, lms/docs/test/review. 4. Mặc định phát triển trên stack Django hiện tại của Synvia, không khởi tạo project Next.js/TypeScript mới. 5. Chỉ đề xuất tách sản phẩm riêng nếu repo lms/ không thể chạy, không thể bảo mật hoặc không thể tích hợp bằng adapter. 6. Viết architecture note ngắn trước khi tạo nhiều file.

Agent không được:

  • Bắt đầu bằng chatbot tổng quát.
  • Hard-code mọi thứ cho IELTS nếu sản phẩm muốn mở rộng.
  • Cho AI chấm high-stakes không có human review.
  • Tạo dashboard chỉ để hiển thị số liệu.
  • Trộn dữ liệu sale với dữ liệu học tập nhạy cảm.
  • Dùng prompt rải rác trong code không versioning.
  • Gửi toàn bộ dữ liệu tenant vào model AI.
  • Thêm model mới vào sy/models/lms.py nếu có thể tạo app/module mới sạch hơn.
  • Commit hoặc mở rộng code khi secrets/API keys vẫn đang hard-code trong settings hoặc JSON key files.

Stack mặc định trong repo Synvia

Vì repo Synvia đã tồn tại trong lms/, stack mặc định là:

  • Language: Python.
  • App: Django 4.x monolith hiện tại.
  • Main app hiện có: lms/sy.
  • Database: PostgreSQL.
  • Background jobs: Celery + Redis.
  • Frontend hiện tại: Django templates + vanilla JS/CSS, có thể dùng HTMX/Alpine nhẹ nếu phù hợp.
  • Existing AI provider: Google Gemini qua google-genai.
  • Existing audio/grammar support: AudioAnalysisService, LanguageToolService.
  • Existing integrations: Zalo, Facebook, Sepay, VdoCipher, email.
  • File storage: đang có local/S3-compatible path tùy settings; thiết kế mới phải giữ tương thích.
  • Auth: Django auth + judge.models.Profile.
  • Testing: Django TestCase/pytest-django nếu được cấu hình, ưu tiên test service và permission.

Chỉ dùng Next.js/TypeScript nếu có quyết định tách frontend độc lập sau này. Trong giai đoạn này, không tạo stack mới chỉ vì nó đẹp hơn trên giấy.

Stack nếu xây mới hoàn toàn

Đây là phương án dự phòng, không phải mặc định. Chỉ dùng nếu đã quyết định không đi từ Synvia:

  • TypeScript.
  • Next.js App Router.
  • PostgreSQL.
  • Prisma hoặc Drizzle.
  • Redis + worker queue.
  • S3-compatible object storage.
  • OIDC-ready auth.
  • AI orchestration service riêng.

Nếu dùng phương án này, agent vẫn phải viết adapter/import plan để không mất dữ liệu và domain knowledge từ Synvia.

Kiến trúc tổng thể

MVP nên là modular monolith trước, không microservices sớm.

Lý do:

  • Domain còn đang học từ pilot.
  • Đội nhỏ cần tốc độ.
  • Transaction giữa assignment, submission, feedback và review cần rõ.
  • Microservices sớm làm tăng chi phí vận hành và làm chậm iteration.

Cấu trúc đề xuất trong repo lms/:

lms/
  sy/                         # Synvia hiện tại: LMS, Sale, Notification, AI grading cũ
  learning_core/              # App mới khuyến nghị
    models/
    services/
    adapters/
    ai/
    permissions.py
    events.py
    tests/
    views/
    templates/
  templates/
    learning_core/
  docs/
    dev/
    test/

Không bắt buộc tên app là learning_core; có thể dùng sy_learning nếu muốn giữ namespace Synvia. Nhưng agent phải giữ ranh giới:

learning_core/
  models/curriculum.py
  models/assessment.py
  models/feedback.py
  models/analytics.py
  models/ai_governance.py
  services/assessment_service.py
  services/feedback_service.py
  services/evidence_service.py
  adapters/synvia.py
  ai/orchestrator.py
  ai/prompts.py
  ai/schemas.py

Không đưa thêm model mới vào sy/models/lms.py nếu model đó thuộc rubric, evidence, AI audit, revision hoặc learner state. sy/models/lms.py đã quá lớn; chỉ chạm vào nó khi cần thêm field nhỏ có migration rõ và không thể đặt ở app mới.

MVP code scope khuyến nghị

Trong repo hiện tại, agent nên code MVP từ Synvia:

Synvia Learning Core: Evidence-based AI Assessment & Teacher Workbench

MVP gồm:

1. App mới learning_core hoặc sy_learning. 2. Adapter đọc dữ liệu từ Profile, SyClass, SyEnrollment, SyAssignment, SyActivitySubmission, SyQuestionSubmission. 3. Curriculum map: objective, skill, rubric version. 4. Rubric-based AI feedback cho writing/speaking dựa trên submission hiện tại. 5. Teacher review: sửa feedback, override score, approve/reject, mark AI error. 6. Revision loop: học viên sửa bài và phản tư sau feedback. 7. Error clustering cho lớp dựa trên submissions hiện có. 8. Student dashboard: tiến bộ theo skill, bài cần sửa, feedback history. 9. Teacher dashboard: bài cần chấm, lỗi phổ biến, học viên cần chú ý. 10. AI audit log: model, prompt version, input hash, output, reviewer. 11. Evaluation log: feedback uptake, revision quality, teacher workload. 12. Permission layer cho class/submission/parent access.

Không code trong MVP:

  • AI tutor tổng quát toàn hệ thống.
  • Proctoring.
  • Emotion detection.
  • Full CRM/sale nếu chưa có.
  • DRM.
  • Marketplace.
  • Parent app phức tạp.
  • Recommendation engine toàn phần.

Agent phải tạo adapter quanh module Synvia cũ thay vì sửa lan man. Nếu cần sửa code cũ, sửa ở điểm tích hợp nhỏ, có test, và không làm đổi hành vi hiện tại ngoài phạm vi task.

Mapping với model Synvia hiện tại

Agent phải hiểu mapping này trước khi tạo schema mới:

| Domain mới | Model Synvia hiện tại | Ghi chú | | --- | --- | --- | | User | judge.models.Profile | Không tạo user model mới nếu chưa có quyết định lớn. | | Teacher | TeacherProfile | Có thể bổ sung metadata ở app mới bằng FK/OneToOne. | | Class | SyClass | Adapter gọi là ClassCohort nếu cần ngôn ngữ domain mới. | | Enrollment | SyEnrollment | Dùng làm nguồn danh sách học viên. | | Sale course | SyCourse | Là sản phẩm bán hàng, không đồng nhất với curriculum học tập. | | Lesson/material | SyLesson, SyMaterial | Dùng cho hoạt động hiện tại; objective map nên ở app mới. | | Assignment bank | SyAssignment, SyQuestionGroup, SyQuestion | Không thay bằng model mới trong MVP. | | Class activity | SyClassActivity | Là assignment được giao cho lớp. | | Submission | SyActivitySubmission, SyQuestionSubmission | Là nguồn bài làm và điểm hiện tại. | | AI request/result cũ | AIAssessmentRequest, AIAssessmentResult | Có thể bọc bằng AIRun mới để audit tốt hơn. | | Notification | NotificationLog, NotificationSchedule | Tái dùng cho parent/teacher notification. | | Payment | SyCoursePurchase, SyTransaction | Tách quyền khỏi learning data. |

Domain model tối thiểu

Agent phải tạo schema theo hướng domain sạch, nhưng không nhân đôi model Synvia đang có nếu không cần. Các model dưới đây là khái niệm sản phẩm. Khi code trong repo lms/, hãy ưu tiên dùng FK/OneToOne/adapter tới model hiện có, và chỉ tạo model mới cho phần Synvia chưa có.

Identity và tenancy

Trong Synvia hiện tại, Profile, Center, Theme, SyBranch và permission Django đang giữ một phần vai trò identity/tenant. Không tạo lại User hoặc Organisation trong MVP nếu chưa có quyết định migration.

LearningConsent
  id
  profile FK -> Profile
  center/tenant reference optional
  consent_type
  status
  granted_at
  revoked_at

LearningAccessAudit
  id
  actor FK -> Profile
  target_profile FK -> Profile optional
  object_type
  object_id
  action
  created_at

Class và enrollment

Trong MVP, không tạo Course, ClassCohort, Enrollment mới. Dùng adapter tới SyCourse, SyClass, SyEnrollment, TeacherProfile.

SynviaClassAdapter
  wraps SyClass

SynviaEnrollmentAdapter
  wraps SyEnrollment

SynviaTeacherAdapter
  wraps TeacherProfile

Curriculum và competency

LearningObjective
  id
  center/tenant reference optional
  sy_course FK -> SyCourse optional
  sy_class_type FK -> SyClassType optional
  code
  title
  description
  subject
  level

Skill
  id
  center/tenant reference optional
  name
  parentSkillId optional

ObjectiveSkill
  objectiveId
  skillId

Rubric
  id
  center/tenant reference optional
  name
  assessmentType
  version
  status

RubricCriterion
  id
  rubricId
  name
  description
  scale
  weight

Assignment và submission

Trong MVP, SyAssignment, SyClassActivity, SyActivitySubmission, SyQuestionSubmission vẫn là nguồn chính. Model mới chỉ bổ sung revision/reflection/evidence nếu Synvia chưa có.

AssignmentObjectiveMap
  id
  sy_assignment FK -> SyAssignment
  objective FK -> LearningObjective

SubmissionRevision
  id
  sy_activity_submission FK -> SyActivitySubmission
  revisionNo
  contentText
  reflectionText
  createdAt

Assessment và feedback

AssessmentResult
  id
  sy_activity_submission FK -> SyActivitySubmission
  rubricId
  assessorType
  assessor_profile FK -> Profile optional
  aiRunId optional
  totalScore
  confidence
  status

CriterionScore
  id
  assessmentResultId
  criterionId
  score
  rationale

FeedbackItem
  id
  assessmentResultId
  category
  skillId optional
  severity
  evidenceText
  feedbackText
  nextAction

TeacherReview
  id
  assessmentResultId
  teacher_profile FK -> Profile
  decision
  editedFeedback
  editedScore
  note

Analytics và intervention

LearningEvent
  id
  actor_profile FK -> Profile
  objectType
  objectId
  verb
  eventTime
  metadata

ErrorCluster
  id
  sy_assignment FK -> SyAssignment optional
  sy_class FK -> SyClass
  skillId optional
  title
  description
  exampleSubmissionIds
  confidence

Intervention
  id
  sy_class FK -> SyClass
  student_profile FK -> Profile optional
  teacher_profile FK -> Profile
  reason
  action
  status
  outcome

AI governance

AIPolicy
  id
  center/tenant reference optional
  name
  allowedRoles
  allowedDataScopes
  humanReviewRequired
  maxAutonomyLevel

PromptTemplate
  id
  name
  taskType
  version
  template
  status

AIRun
  id
  actor_profile FK -> Profile
  taskType
  modelProvider
  modelName
  modelVersion
  promptTemplateId
  promptVersion
  inputHash
  outputText
  outputJson
  tokenUsage
  latencyMs
  status
  error

AIIncident
  id
  aiRunId
  severity
  category
  description
  resolution

Permission model

Agent phải code authorization theo resource, không chỉ ẩn UI.

Quy tắc tối thiểu:

  • Owner xem toàn tổ chức, nhưng dữ liệu nhạy cảm học viên cần audit.
  • Admin quản lý user, lớp, lịch, cấu hình.
  • Academic manager quản lý curriculum, rubric, teacher dashboard.
  • Teacher chỉ xem lớp mình được phân công.
  • Student chỉ xem dữ liệu của mình.
  • Parent chỉ xem dữ liệu được phép của con.
  • Sales không xem submission chi tiết, AI feedback nhạy cảm hoặc learner weakness trừ khi chính sách cho phép rõ.
  • AI service chỉ nhận data scope đã được policy cho phép.

Mọi API mutation phải kiểm tra:

1. User/Profile thuộc đúng center/class/branch hoặc scope tương đương trong Synvia. 2. User có role phù hợp. 3. User có quyền trên resource cụ thể. 4. Resource cùng tenant/scope dữ liệu. 5. Nếu dữ liệu nhạy cảm, ghi audit.

AI architecture

Agent phải tạo lớp AI orchestration riêng. Không gọi model trực tiếp từ component UI.

Interface Python/Django đề xuất:

from dataclasses import dataclass, field
from typing import Any

@dataclass(frozen=True)
class AIRunRequest:
    actor_profile_id: int
    task_type: str
    policy_id: int | None
    prompt_template_id: int
    input_data: dict[str, Any]
    data_scope: dict[str, int | str]

@dataclass(frozen=True)
class AIRunResult:
    ai_run_id: int
    output: dict[str, Any]
    confidence: float | None = None
    warnings: list[str] = field(default_factory=list)

Pipeline tối thiểu:

1. Validate quyền user. 2. Validate AI policy. 3. Lấy dữ liệu đúng scope. 4. Redact dữ liệu không cần thiết. 5. Render prompt từ template versioned. 6. Gọi provider. 7. Parse structured output. 8. Validate output schema. 9. Chạy guardrails. 10. Lưu AIRun. 11. Nếu cần human review, tạo review task. 12. Trả kết quả.

Với AI grading hiện có, không cần xóa AIGradingService ngay. Hãy bọc nó bằng orchestrator mới:

1. Adapter lấy SyActivitySubmission và SyAssignment. 2. Orchestrator tạo AIRun. 3. Gọi AIGradingService.grade_submission(...). 4. Validate kết quả theo schema mới. 5. Tạo AssessmentResult/FeedbackItem mới hoặc đồng bộ ngược vào SyQuestionSubmission nếu UI cũ cần. 6. Ghi TeacherReview khi giáo viên sửa.

Prompt và structured output

Prompt phải nằm trong versioned templates, không hard-code rải rác.

Mỗi prompt cần:

  • Task purpose.
  • Input schema.
  • Rubric hoặc criteria.
  • Output schema.
  • Boundaries: không bịa nguồn, không đưa lời giải trọn nếu policy cấm, không dùng dữ liệu ngoài scope.
  • Tone: cụ thể, có hành động, không phán xét nhân cách người học.
  • Safety: không chẩn đoán tâm lý, không tạo nhãn cố định.

AI output cho feedback nên là JSON có schema:

{
  "summary": "string",
  "criterionScores": [
    {
      "criterionId": "string",
      "score": 0,
      "rationale": "string",
      "confidence": 0.0
    }
  ],
  "feedbackItems": [
    {
      "category": "grammar|vocabulary|coherence|argument|fluency|other",
      "severity": "low|medium|high",
      "evidenceText": "string",
      "feedbackText": "string",
      "nextAction": "string",
      "skillId": "string|null"
    }
  ],
  "revisionPrompt": "string",
  "teacherWarnings": ["string"]
}

Không lưu output tự do nếu downstream cần chấm, analytics hoặc review.

Teacher-in-the-loop implementation

Các điểm bắt buộc phải code:

1. Teacher thấy AI feedback trước khi approve nếu assignment high-stakes. 2. Teacher có thể sửa từng feedback item. 3. Teacher có thể override score. 4. Teacher có thể mark AI output là wrong, too harsh, too vague, over-helping, biased, unsafe. 5. Mỗi sửa đổi lưu version và audit. 6. Error của AI đi vào evaluation dataset. 7. Dashboard phân biệt AI draft và teacher-approved feedback.

Không được chỉ tạo nút "Approve all" nếu chưa có summary rủi ro, confidence và sampling review.

Learner experience implementation

Người học cần trải nghiệm học, không phải chỉ nhận điểm.

Màn hình student tối thiểu:

  • Bài được giao.
  • Rubric dễ hiểu.
  • Bản nộp và feedback.
  • Việc cần sửa tiếp theo.
  • Revision editor.
  • Reflection prompt.
  • Skill progress.
  • Spaced review queue.

Quy tắc:

  • Feedback phải nói "làm gì tiếp", không chỉ "sai gì".
  • Không hiển thị quá nhiều metric cùng lúc.
  • Không dùng nhãn cố định như "yếu toàn diện".
  • Khi AI hỗ trợ, cho người học biết AI đang đóng vai gì.
  • Với bài luyện, yêu cầu thử trước khi xem gợi ý sâu.

Teacher dashboard implementation

Màn hình teacher tối thiểu:

  • Today: lớp hôm nay, bài cần chấm, cảnh báo cần xử lý.
  • Class overview: tiến độ, chuyên cần, submission status.
  • Error clusters: lỗi phổ biến, ví dụ, gợi ý mini-lesson.
  • Review queue: AI feedback cần duyệt.
  • Student detail: lịch sử bài làm, feedback uptake, kỹ năng, ghi chú.

Mỗi insight phải có action:

  • Create mini lesson.
  • Assign practice.
  • Message student.
  • Message parent.
  • Schedule check-in.
  • Mark as resolved.
  • Ignore with reason.

Nếu insight không có action, đừng đưa lên dashboard chính.

Evidence and evaluation implementation

MVP phải ghi dữ liệu để biết sản phẩm có đang giúp học không.

Metric tối thiểu:

  • Feedback turnaround time.
  • Teacher review time.
  • Number of feedback items edited by teacher.
  • Feedback uptake: người học có sửa theo feedback không.
  • Revision quality: điểm/rubric thay đổi sau revision.
  • Error recurrence: lỗi có lặp lại sau 1-3 bài không.
  • Student completion.
  • Delayed review performance nếu có.
  • Teacher workload self-report ngắn.
  • AI error rate theo teacher review.

Không kết luận hiệu quả chỉ từ:

  • Login count.
  • Time on platform.
  • Number of AI generations.
  • Satisfaction.
  • Number of assignments created.

URL/API design trong Synvia

Vì Synvia đang dùng Django views/templates, agent không cần ép mọi thứ thành REST ngay. Với MVP, ưu tiên thêm URL có namespace rõ và có thể nhúng vào UI hiện tại:

GET    /sy/admin/learning/classes/<class_id>/workbench/
GET    /sy/admin/learning/submissions/<submission_id>/review/
POST   /sy/admin/learning/submissions/<submission_id>/ai-feedback/
POST   /sy/admin/learning/assessment-results/<result_id>/review/
GET    /sy/admin/learning/classes/<class_id>/error-clusters/
POST   /sy/admin/learning/classes/<class_id>/interventions/
GET    /sy/learning/dashboard/
GET    /sy/learning/submissions/<submission_id>/feedback/
POST   /sy/learning/submissions/<submission_id>/revisions/

Nếu cần API JSON cho AJAX/HTMX:

POST   /sy/api/learning/submissions/<submission_id>/generate-feedback/
POST   /sy/api/learning/reviews/<result_id>/
GET    /sy/api/learning/classes/<class_id>/clusters/

Quy tắc:

  • URL dùng int:id phải có object-level permission thật.
  • Public/parent-facing links nên dùng token/UUID và scope rõ.
  • View chỉ điều phối request/response; logic nằm trong service.
  • Không để template gọi trực tiếp AI endpoint không qua permission và policy.

File upload và media

Quy tắc:

  • File bài làm, audio, video lưu object storage.
  • Database chỉ lưu metadata và object key.
  • Có virus/mime validation nếu triển khai thật.
  • Có giới hạn size theo tenant.
  • Signed URL có thời hạn.
  • Audio/video transcription là async job.
  • Submission không mất dữ liệu nếu AI job fail.

Analytics event schema

Mỗi event tối thiểu:

{
  "id": "string",
  "actorProfileId": "string",
  "syClassId": "string|null",
  "centerId": "string|null",
  "verb": "submitted|viewed_feedback|started_revision|completed_revision|teacher_reviewed|assigned_practice",
  "objectType": "assignment|submission|feedback|revision|intervention",
  "objectId": "string",
  "eventTime": "datetime",
  "metadata": {}
}

Event phải phục vụ câu hỏi học tập hoặc vận hành. Không log mọi click nếu không có mục đích.

Privacy and safety implementation

Agent phải code các cơ chế tối thiểu:

1. Tenant isolation ở query layer. 2. Authorization test cho resource nhạy cảm. 3. Audit log cho xem/sửa assessment, submission, learner profile, payment. 4. Data retention config tối thiểu theo center/tenant hoặc theo chính sách Synvia hiện có. 5. AI context redaction. 6. AI output moderation/guardrail cho nội dung nguy hiểm. 7. Export dữ liệu học viên theo request. 8. Delete hoặc anonymise theo policy. 9. Secret management qua env, không commit key. 10. Rate limit cho AI endpoints.

Nếu có trẻ em, không tự động bật tính năng hội thoại AI tự do. Cần policy theo tổ chức và độ tuổi.

Testing strategy

Agent phải viết test theo rủi ro.

Unit tests:

  • Permission checks.
  • Rubric score aggregation.
  • Feedback output schema validation.
  • Skill mastery update nếu có.
  • AI policy data scope.

Integration tests:

  • Teacher tạo assignment.
  • Student nộp bài.
  • AI tạo feedback.
  • Teacher review.
  • Student sửa bài.
  • Error cluster được tạo.
  • Parent không xem được dữ liệu cấm.
  • Sales không xem được submission nhạy cảm.

E2E tests:

  • Complete assignment-feedback-revision loop.
  • Teacher dashboard action loop.
  • AI failure fallback.

AI evaluation tests:

  • Prompt không cho lời giải trọn khi policy cấm.
  • Feedback có nextAction.
  • Feedback không xúc phạm người học.
  • Output parse được JSON.
  • Rubric consistency trên sample cố định.
  • Không leak dữ liệu học viên khác trong cùng tenant.

Seed data

Agent nên tạo seed data có ý nghĩa:

  • Một center/trung tâm ngoại ngữ.
  • Hai lớp: IELTS Writing và Speaking.
  • Ba giáo viên.
  • Mười học viên.
  • Một rubric writing.
  • Một rubric speaking.
  • Ba assignments.
  • Một số submissions có lỗi khác nhau.
  • Một số AI feedback đã duyệt và chưa duyệt.
  • Một dashboard có error clusters.

Seed data phải giúp demo workflow thật, không chỉ tạo user rỗng.

UI principles

Giao diện phải làm việc được cho người dùng thật.

Teacher UI:

  • Dày thông tin vừa phải.
  • Ưu tiên việc cần làm hôm nay.
  • Mỗi cảnh báo có lý do.
  • Có ví dụ bài làm thật khi nói lỗi phổ biến.
  • Chỉnh feedback nhanh, không bắt giáo viên đi qua nhiều modal.

Student UI:

  • Ít nhiễu.
  • Thấy rõ bài cần làm, feedback, sửa gì tiếp.
  • Progress theo skill nhưng không gây nhãn hóa.
  • Không biến dashboard thành bảng điểm đáng sợ.

Admin/owner UI:

  • Lớp, chuyên cần, bài chờ chấm, dòng tiền nếu có.
  • Tách academic health với revenue.
  • Không dùng learning weakness để tạo sale pressure.

Migration path nếu dùng Synvia

Vì repo Synvia hiện đã có trong lms/, agent phải làm theo trình tự:

1. Kiểm tra dirty worktree và không đụng các thay đổi không liên quan. 2. Dọn hoặc cô lập secrets: dmoj/local_settings.py, JSON key files, .env. 3. Inventory module hiện có: LMS, Sale, AI chấm bài, dashboard, điểm danh, thông báo. 4. Tìm schema đang chứa user, class, course, submission, score. 5. Không đổi schema lớn ngay nếu đang chạy production. 6. Tạo app mới learning_core hoặc sy_learning. 7. Tạo adapter:

  • SynviaProfileAdapter
  • SynviaClassAdapter
  • SynviaAssignmentAdapter
  • SynviaSubmissionAdapter
  • SynviaAIGradingAdapter
  • SynviaPaymentAdapter nếu cần

    • 8. Xây Learning Core mới quanh objective, rubric, feedback, review, revision, analytics, AI audit. 9. Đồng bộ dữ liệu cần thiết qua adapter, không copy dữ liệu hàng loạt nếu chưa cần. 10. Gắn UI mới vào class detail/submission detail/teacher dashboard hiện có. 11. Từng bước chuyển flow cũ sang dùng service mới. 12. Viết migration chỉ khi có test và backup plan.

Mục tiêu là làm Synvia mạnh hơn mà không phá vận hành hiện tại.

Guardrails riêng cho repo hiện tại

1. Không thêm secrets mới vào settings.py, local_settings.py, .env hoặc JSON trong repo. 2. Không import vòng giữa sy và app mới; app mới được phụ thuộc vào sy, nhưng sy chỉ gọi qua service/adapters ở điểm tích hợp rõ. 3. Không sửa judge.models.Profile nếu có thể dùng model bổ sung bằng OneToOne/FK. 4. Không xóa/move migrations cũ. 5. Không refactor sy/models/lms.py cùng lúc với feature mới, trừ khi task chính là refactor và đã có test. 6. Không thay đổi hành vi AI grading cũ nếu chưa có regression samples. 7. Không mở dữ liệu học viên cho sale dashboard nếu mục tiêu chỉ là learning analytics.

Definition of Done

Một task code chỉ được coi là xong khi:

1. Có UI hoặc API dùng được cho workflow liên quan. 2. Có authorization đúng tenant. 3. Có audit/event nếu chạm dữ liệu học tập. 4. Có test cho logic rủi ro chính. 5. AI output có schema validation nếu task dùng AI. 6. Có trạng thái loading/error/empty. 7. Không có secret trong code. 8. Không làm mất khả năng teacher override. 9. Không thêm metric vô nghĩa vào dashboard. 10. Có seed/demo path nếu là tính năng chính.

Thứ tự triển khai đề xuất

Sprint 1: Foundations

  • Kiểm tra và dọn cấu hình secrets.
  • Tạo app learning_core hoặc sy_learning.
  • Tạo adapters cho Profile, SyClass, SyAssignment, SyActivitySubmission.
  • Thêm object-level permission helpers.
  • Tạo models nền: LearningObjective, Skill, Rubric, RubricCriterion, AIRun.
  • Viết test permission tối thiểu.

Sprint 2: Curriculum and assignments

  • Mapping SyAssignment với objective/skill.
  • Rubric builder hoặc admin form cho rubric version.
  • Gắn rubric vào assignment/activity hiện có.
  • Không thay flow nộp bài cũ nếu chưa cần.

Sprint 3: AI feedback

  • Bọc AIGradingService bằng orchestrator mới.
  • Prompt templates versioned.
  • Structured output validation.
  • AIRun logs.
  • Generate feedback cho writing/speaking từ submission hiện có.
  • Teacher review queue.

Sprint 4: Revision loop

  • Student feedback view trong UI Synvia hiện có.
  • Revision editor.
  • Reflection prompt.
  • Feedback uptake events.
  • Assessment comparison.

Sprint 5: Teacher workbench

  • Teacher workbench gắn vào class detail/dashboard hiện có.
  • Error clustering.
  • Student detail.
  • Intervention actions.

Sprint 6: Governance and pilot evaluation

  • AI incident marking.
  • Evaluation metrics.
  • Export pilot report.
  • Permission hardening.
  • Seed/demo polish.

Các câu hỏi agent phải trả lời trước khi mở rộng

1. Người học có sửa bài nhiều hơn không? 2. Giáo viên có tiết kiệm thời gian thật không? 3. AI feedback bị giáo viên sửa ở điểm nào nhiều nhất? 4. Error clustering có dẫn tới bài dạy lại không? 5. Học viên yếu có được hỗ trợ tốt hơn hay bị gắn nhãn hơn? 6. Có dữ liệu nào đang thu nhưng không dùng không? 7. Có tác vụ nào AI đang làm thay phần người học cần tự làm không? 8. Mô hình chi phí AI trên mỗi học viên có bền không?

Nếu chưa trả lời được, không nên thêm tính năng lớn.

Ghi chú cuối cho coding agent

Sản phẩm này không phải "LMS có chatbot". Nó là một hệ thống học tập có bằng chứng, nơi AI nằm trong vòng thiết kế, phản hồi, đánh giá và cải tiến. Code phải phản ánh điều đó: domain rõ, quyền rõ, dữ liệu rõ, AI có kiểm soát, giáo viên có quyền thật, người học có cơ hội sửa và tiến bộ.