Skip to content

گزارش_جامع_پروژه_آتیه.md

Latest commit

 

History

History
389 lines (299 loc) · 12.5 KB

گزارش_جامع_پروژه_آتیه.md

File metadata and controls

389 lines (299 loc) · 12.5 KB
Raw

📋 گزارش جامع پروژه Atieh AI

🎯 خلاصه

سیستم نوبت‌دهی و مدیریت کلینیک دندانپزشکی آتیه — یک پلتفرم SaaS شامل:

  • نوبت‌دهی هوشمند با AI
  • داشبورد مالی و عملیاتی
  • جستجوی بیمار
  • مدیریت پرداخت‌ها و بیمه‌ها
  • اتصال به CRM
  • فرآیند ایمپورت خودکار داده

📁 ساختار پروژه

پوشه‌های اصلی

پوشه توضیح
app/ هسته برنامه — API، موتور، ایمپورترها
engine/ موتور Post-Import و Decision Logger
scripts/ اسکریپت‌های bridge، migration، چک‌ها
tests/ تست‌های واحد و یکپارچگی
tools/ ابزارهای build، دیتابیس، تشخیص
templates/ قالب HTML (Manager Dashboard)
static/ فایل‌های فرانت‌اند (HTML, CSS, JS)
public/ تصاویر و دارایی‌های عمومی
config/ تنظیمات YAML
data/ داده‌های ورودی/خروجی و mock
docs/ مستندات (۵۷+ فایل)
sql/ اسکریپت‌های خام SQL
watchers/ Folder Watcher برای ایمپورت خودکار
archive/ یادداشت‌های توسعه
backups/ بکاپ دیتابیس
routes/ مسیرهای بیمار
schemas/ اسکیمای Pydantic

فایل‌های اصلی ریشه

فایل توضیح
main.py نقطه ورود FastAPI، تمام روت‌ها و middleware
models.py مدل‌های SQLAlchemy
database.py تنظیمات و اتصال دیتابیس
ai_brain.py منطق AI
crm_integration.py لایه اتصال CRM
scoring_algorithm.py الگوریتم امتیازدهی
appointment_scheduler.py برنامه‌ریز نوبت
treatment_duration.py مدت درمان‌ها
schedule_engine.py موتور زمان‌بندی
launcher.py لانچر دسکتاپ (WebView)
desktop_app.py اپ دسکتاپ
run.py اجرای Uvicorn
conftest.py تنظیمات Pytest
requirements.txt وابستگی‌ها
Makefile دستورات build/test/run

🗄️ دیتابیس و مدل‌ها

پایگاه‌های داده

  • atieh_clinic.db — دیتابیس اصلی
  • atieh_clinic_working.db — دیتابیس عملیاتی مالی
  • atieh_clinic_smoke.db — تست
  • FINANCIAL_DB_PATH — مسیر دیتابیس مالی (از .env)

مدل‌های SQLAlchemy (models.py)

مدل فیلدهای مهم
Patient id, name, phone, national_id, payment_type, first_visit_date, lifetime_value_score
Appointment id, patient_id, appointment_date, duration_minutes, payment_type, treatment_type, priority_score, status, ai_priority_score, notes
ClinicSchedule id, day_of_week, start_time, end_time, is_active
PaymentType Enum: CASH, INSURANCE_1..20
TreatmentType Enum: TREATMENT_1..20

مایگریشن‌ها (app/db/migrations/)

  • 001_import_pipeline.sql
  • 002_financial_identity_payments.sql
  • 002_patient_scoring.sql
  • 003_payment_normalization.sql
  • 004_payments_staging.sql
  • 005_perf_indexes.sql
  • 006_financial_patient_dim.sql
  • 007_patient_financial_summary.sql
  • 008_financial_for_engine_view.sql
  • 009_recordno_patient_map.sql
  • 009_engine_scoring_config.sql
  • 011_v_financial_for_engine_recordno.sql
  • 012_v_patients_with_financial.sql
  • 013_appointment_recordno_bridge.sql
  • 014_patient_recordno_map.sql
  • 015_v_patients_financial_resolved.sql

🌐 API Endpoints

احراز هویت و صفحات (main.py)

روش مسیر توضیح
GET /login فرم ورود
POST /login ورود
GET /logout خروج
GET / صفحه اصلی (نیاز به session)
GET /manager داشبورد مدیر
GET /staff/search ریدایرکت جستجوی کارکنان
GET /health وضعیت سلامت

API هسته (main.py)

روش مسیر
POST /ai/score-patient
POST /ai/recommend-slot
GET /patients/search
GET /patients
GET /patients/{patient_id}
GET /debug/db
GET /backup-db
POST /imports/run
GET /imports/history
GET /appointments/suggest-time
GET /appointments/next-available
GET /appointments/suggestions
GET /appointments/available-slots
GET /appointments/{appointment_id}
GET /api

مالی عملیاتی (/financial)

مسیر توضیح
/financial/followup/contactable بیماران قابل تماس
/financial/followup/daily پیگیری روزانه
/financial/scheduling/top300 ۳۰۰ بیمار برتر
/financial/dashboard/summary خلاصه داشبورد
/financial/dashboard/insights بینش‌ها
/financial/dashboard/kpis KPIها
/financial/dashboard/trends روندها
/financial/top-vips VIPها
/financial/patient/{record_no} جزئیات بیمار
/financial/scheduling/priority اولویت AI
/financial/patient-lookup جستجوی بیمار
/financial/status وضعیت
/financial/appointment-suggestions پیشنهاد نوبت
POST /financial/appointment-suggestions/{id}/review

AI مالی (/ai/financial)

مسیر
/ai/financial/top-recordnos
/ai/financial/top-recordnos-explain-mixed
/ai/financial/top-recordnos-explain
/ai/financial/recordno/{record_no}
/ai/financial/status

AI (/api/ai)

مسیر
/api/ai/priority/record-no/{record_no}
/api/ai/top/priority-records
/api/ai/top/financial-records

موتور AI (/ai/engine)

مسیر
POST
GET
GET

Import (/api/import)

مسیر
/api/import/ping
POST
/api/import/runs
/api/import/runs/{run_id}
/api/import/runs/{run_id}/errors
/api/import/stats

Manager (/api/manager)

مسیر توضیح
/api/manager/dashboard/summary خلاصه (تعداد بیمار، VIP، tier)
/api/manager/patients/top-value بیماران با بیشترین ارزش مالی
/api/manager/decision-logs لاگ تصمیم‌گیری

Staff (/api/staff)

مسیر
/api/staff/patients/search

Frontend API

مسیر
/treatment-types
/payment-types
/patients
/appointments

🖥️ فرانت‌اند

فایل‌های HTML

فایل توضیح
static/index.html SPA اصلی (RTL، فارسی)، sidebar، topbar
templates/manager_dashboard.html داشبورد مدیر (KPIs، جدول، donut، لاگ‌ها)
templates/layout.html قالب لایه

CSS

فایل توضیح
static/css/design-system.css توکن‌های طراحی، فونت Vazirmatn
static/css/dashboard.css layout مشترک (sidebar، topbar، جدول‌ها)
static/css/manager-dashboard.css استایل داشبورد مدیر

JavaScript

فایل توضیح
static/js/api.js کلاینت API
static/js/app.js روتینگ SPA و منطق صفحات

صفحات SPA (از index.html)

  • داشبورد عملیاتی
  • Patient Search
  • Manager Dashboard
  • صف پیگیری
  • اولویت ۳۰۰
  • اولویت AI
  • نوبت جدید

⚙️ پکیج app/

زیرپکیج/ماژول نقش
app/api/ روت‌های API
app/api/manager/ API داشبورد مدیر
app/api/staff/ API جستجوی کارکنان
app/api/routes/ روت‌های موتور
app/api/services/ سرویس اجرای موتور
app/db/ دیتابیس و مایگریشن
app/engine/ موتور زمان‌بندی
app/engine/tvs/ کامپوننت‌های TVS
app/importers/ ایمپورترها
app/importers/common/ helpers (تاریخ شمسی، hashing و...)
app/integrations/ اتصالات
app/integrations/crm/ کلاینت، mock، factory، mapper
app/loaders/ لودر Excel/Atieh
app/routers/ روت فرانت‌اند
app/schemas/ اسکیمای Pydantic
app/security/ نقش‌ها و امنیت
app/utils/ نرمال‌سازی، متن، doctor_name و...

📜 اسکریپت‌ها

Bridge

  • bridge_1395_*.py تا bridge_1404_*.py برای سال‌های مختلف

Import/Load

  • load_payment_identity_staging.py
  • ingest_payments.py

Migration

  • scripts/migrations/ — تبدیل تاریخ، تغییر schema

چک و دیباگ

  • scripts/checks/ — DB، پرداخت‌ها، QA
  • scripts/debug/ — پچ‌ها و دیباگ
  • scripts/demos/ — داده نمونه، دمو scheduler

Tools (tools/)

  • build_* — map پرونده، payments، financial dims، appointment bridge
  • db_profile.py, match_diagnostics.py
  • discover_recordno_in_appointments.py

🔌 اتصال CRM

مسیر: app/integrations/crm/

فایل نقش
interface.py اینترفیس
client.py کلاینت (رابط)
mock.py mock برای تست
factory.py get_crm_client() بر اساس CRM_MODE
live_client.py کلاینت زنده
adapter.py, mapper.py اداپتر و مپر

⚙️ تنظیمات

فایل توضیح
.env متغیرها (DATABASE_URL, CRM_MODE, FINANCIAL_DB_PATH)
config/weights.yaml وزن‌های موتور، توصیه slot
requirements.txt openpyxl, pandas, fastapi, uvicorn, sqlalchemy, jdatetime, ...
desktop_app.spec مشخصات PyInstaller
Makefile install, mock-data, test, run, run-live, clean

🚀 راه‌اندازی و اجرا

لانچرها

فایل کاربرد
launcher.py اجرای API + watcher + پنجره WebView
run_api.bat Uvicorn روی پورت ۸۰۰۰
start_atieh_ai.bat API و folder watcher
run_atieh_ai.bat, run_watcher.bat اجرای جداگانه
run.py اجرای Uvicorn

Watcher

  • فایل: watchers/folder_watcher.py
  • ورودی: C:\AtiehAI\incoming
  • خروجی: C:\AtiehAI\processed، C:\AtiehAI\failed
  • عمل: فراخوانی /imports/run روی فایل جدید

📚 مستندات (۵۷+ فایل)

ریشه

  • README.md — ساختار و راهنمای loader
  • README_RUNTIME.md — مستندات runtime
  • delivery_checklist.md — چک‌لیست تحویل
  • گزارش_کامل_پروژه.md — گزارش پروژه

docs/

  • setup/: QUICKSTART، QUICKSTART_V2، QUICK_REFERENCE، TEST_GUIDE، IMPORT_GUIDE، CRM_SETUP، CRM_QUICKSTART، TEST_DATABASE_SETUP، IMPORT_QUICK_START
  • architecture/: ENGINE_SUMMARY، ENGINE_README، ENGINE_V2_DECISION_LOGIC، SCHEDULER_README، SCORING_README، TECHNICAL_ARCHITECTURE_REPORT، CRM_INTEGRATION_README
  • fixes/: SQLITE_STABILITY_FIX، ROUTE_COLLISION_FIX، DOCTOR_MATCHING_IMPROVEMENTS، CHOKE_POINT_FIX، PREFERRED_DOCTOR_FIX_SUMMARY، IMPORT_FIX_COMPLETE و...
  • reports/: SUMMARY، STATUS، REPROCESS_COMPLETE، AI_CORE_HARDENING_SUMMARY، CHANGELOG_COMPLETE
  • runbooks/: SMOKE_IMPORT_UPDATED، IMPORT_IMPLEMENTATION_COMPLETE، BRIDGE_PIPELINE_RUNBOOK
  • سایر: IMPORT_COMPLETE_REFERENCE، PATIENT_SCORING، TESTING، REFACTOR_SUMMARY، BRIDGE_1404_DIAGNOSTICS، RECORDNO_RESOLUTION_PIPELINE، PUBLIC_RELEASE_CHECKLIST

🔐 احراز هویت

  • Session: SessionMiddleware با atieh-ai-secret-key
  • کاربران: admin/atieh123 (manager)، operator/clinic123 (operator)

📦 وابستگی‌ها (requirements.txt)

  • openpyxl, pandas, pytest, pydantic, pyyaml
  • fastapi, uvicorn, sqlalchemy, requests
  • python-dateutil, Faker, jdatetime

گزارش تولیدشده بر اساس کدبیس پروژه Atieh — به‌روزرسانی: ۱۴۰۵/۰۳/۱۹