Sana Bridge · AI Sana MVP

Бизнес-міндетті нақтылау, дайындық рейтингін көтеру және студенттік команданы ашық таңдау платформасы.

Интерфейс пен қорғау материалы қазақ тілінде. Қосымша интернетсіз, API кілтінсіз және қосымша Python кітапханаларын орнатпай жұмыс істейді. Python 3.10 немесе жаңа нұсқасы қажет.

1. Жылдам іске қосу

Windows

1. Мұрағатты толық ашыңыз. ZIP ішінен тікелей іске қоспаңыз.
2. sana-bridge бумасындағы start.bat файлын екі рет басыңыз.
3. Браузерде http://127.0.0.1:8000 ашылады. Серверден бұрын ашылса, бетті бір рет жаңартыңыз.
4. Терминал терезесі ашық тұруы керек. Тоқтату: Ctrl+C.

Немесе сол бумадағы терминалда:

py -3 server.py

py командасы жоқ болса: python server.py. Python орнатылмаған болса, Python 3.10+ орнатып, PATH параметрін қосыңыз.

macOS / Linux

cd sana-bridge
python3 server.py

Браузерде http://127.0.0.1:8000 ашыңыз. Қосымша npm install, pip install немесе build талап етпейді.

Порт бос емес болса

python3 server.py --port 8001

Сонда http://127.0.0.1:8001 ашылады. Windows-та python3 орнына py -3 қолданыңыз.

2. Нені көрсетуге болады?

1. Бизнес → Міндет құрастыру: еркін сипаттаманы енгізу.
2. Талдау және нақтылау: кемінде үш сұрақ; жетіспейтін мәліметке байланысты қосымша сұрақтар.
3. Карточка: он өрісті өңдеу, әр мәліметті қолмен растау, рейтингті бірден қайта есептеу.
4. Растап, жариялау: міндет ортақ каталогқа шығады; рейтинг оның орнына әсер етеді.
5. Студент: кез келген команда, кез келген жарияланған міндет, шексіз ұсыныс. Идея, жоспар, мерзім, прототип сілтемесі.
6. Бизнес → Ұсыныстар: салыстыру, қабылдау немесе қабылдамау. Бірнеше команданы таңдауға болады. Ешқайсысын таңдамау да мүмкін.
7. Студент → Менің ұсыныстарым: таңдалған команда кезең нәтижесін жібереді.
8. Бизнес нәтижені растайды немесе түсініктемемен толықтыруға қайтарады. Расталған кезең командаға ұпай береді.

Дайын мысалды бастау үшін Демонстрация → Демоны бастау. Толық сөйлеу мәтіні: DEMO_KK.md.

3. Архитектура

HTML/CSS/JavaScript интерфейсі JSON HTTP API арқылы Python серверіне сұрау жібереді. Сервер domain.py ережелерін орындайды және міндеттерді, командаларды, ұсыныстар мен кезеңдерді SQLite базасында сақтайды.

• server.py: JSON API, жергілікті статикалық файлдар, транзакциялар, рөлдік әрекеттер.
• domain.py: таза функциялар; рейтинг клиенттен қабылданбайды, серверде есептеледі.
• static/: қазақша интерфейс, сүзгі, редактор, модаль терезелер, рөл ауыстыру.
• data/seed.json: 5 бастапқы сипаттама, 5 карточка, 5 команда, 5 ұсыныс.
• data/demo.json: толық қорғауға арналған бір мысал.
• data/sana.sqlite3: алғашқы іске қосқанда автоматты жасалады. Серверді қайта қосқанда деректер сақталады.
• tests/test_app.py: бизнес ережелері мен шынайы HTTP API тестілері.
• docs/AI_CONTRACT.md: промпт, кіріс/шығыс және қате жауапты өңдеу.
• docs/TEST_REPORT.md: орындалған тексерулер мен шектеулері.

Клиентке тек жарияланған міндеттер көрсетіледі. Бизнес өз жобаларын да көреді. Студент ұсыныстар тізімінде өз командасының ұсыныстарын көреді. Барлық жарияланған карточка кез келген командаға қолжетімді.

4. Деректер моделі

Кесте	Негізгі өрістер	Байланыс / ереже
tasks	id, owner, topic, fields, confirmed, published, revision, timestamps	fields: карточканың он өрісі; confirmed: расталған кілттер
teams	id, profile	атауы, қызығушылығы, дағдысы, технологиясы; ұпай кезеңдерден есептеледі
proposals	id, task_id, team_id, idea, plan, timeline, link, status	бір міндетке және бір командаға бірнеше ұсыныс рұқсат
milestones	id, proposal_id, stage, evidence, note, status, feedback, points	(proposal_id, stage) бірегей; ұпай бір рет беріледі

Карточканың міндетті құрылымы: title, context, need, users, data, constraints, outcome, success, contact, interaction. Құрылым барлық өрісті қамтиды; белгісіз мәндер бос қалады, олар ұпай қоспайды.

5. Рейтинг формуласы

R = Σ weight(field) × valid(field) × confirmed(field); нәтиже 0–100.

Критерий	Ұпай	Есептеу
Контекст және қажеттілік	20	контекст 10 + қажеттілік 10
Деректер мен материалдар	20	деректердің сипаттамасы
Күтілетін нәтиже	15	команда тапсыратын өнім
Табыс критерийлері	15	сандық мақсаты бар сипаттама
Шектеулер	10	мерзім / технология / қолжетімділік
Пайдаланушылар	10	кім үшін жасалады
Бизнеспен байланыс	10	email/телефон 5 + өзара әрекет форматы 5
Барлығы	100	атау ұпай қоспайды

Есеп ашық: әр топтың жиналған және ең жоғары ұпайы, жетіспейтін өріс пен ықтимал ұпай көрсетіледі. Мәтін минималды ұзындықтан өтуі керек; табыс критерийінде сан болуы, байланыста email/телефон форматы болуы қажет. Бұл MVP-де формалды толықтықты тексеру қолданылады; мәліметтің шынайылығы мен мазмұн сапасын бизнес өзі растайды. Толық семантикалық сараптама жасалмайды.

Өрісті өзгерткенде интерфейс сол өрістің растауын алып тастайды. Жариялау үшін барлық толтырылған өріс расталуы тиіс. Бос өрістер жариялауға кедергі емес. Расталмаған мәліметті жоба түрінде сақтауға болады. Бұрын жарияланған карточканың өзгерістері де қайта расталады. Жоба режимінде сақтау жарияланған карточканы каталогтан алып тастамайды.

Ұпай	Деңгей	Каталогтағы мағынасы
0–39	Жоба	көрінеді, нақтылау қажет деген белгі бар, ұсыныс беруге болады
40–69	Жұмыс	негізгі мәліметтер бар, ұсыныс беруге болады
70–89	Дайын	рейтингіне сай жоғарырақ орын
90–100	Басым	ерекшеленген карточка, толық дайындық

6. Каталог пен таңдау ережелері

• Жарияланған міндеттер ұпайы бойынша кему ретімен сұрыпталады.
• Ұпайы бірдей болса, ертерек жасалған міндет бірінші, одан кейін id бойынша тұрақты рет.
• Сүзгі: сала, дайындық деңгейі; мәтіндік іздеу барлық карточка өрістеріне қолданылады.
• Төмен ұпай міндетті жасырмайды және ұсынысты бұғаттамайды.
• Қызығушылығы сәйкес студентке белгі көрсетіледі; басқа міндеттер көрініп тұрады.
• Автоматты команда тағайындау, автоматты қабылдау немесе жеке сезімтал белгілермен іріктеу жоқ.
• Бір, бірнеше немесе нөл команда таңдалуы мүмкін. Қабылдамаудан кейін қайта таңдау рұқсат.
• Кезең жіберіліп қойған ұсынысты қабылдамауға тыйым салынған: орындалған жұмыс пен ұпай тарихы сақталады.

7. Команда прогресі

Кезең	Ұпай	Берілетін шарт
Мәселені зерттеу	20	таңдалған команда дәлел жібереді; бизнес растайды
Прототип	30	сол тәртіп
Нәтижені тексеру	50	сол тәртіп

Ұсыныс беру мен таңдалу өздігінен ұпай бермейді. Ұпайдың жалғыз көзі — бизнес растаған кезең. Транзакция және бірегей кілт қосарланған марапаттауды болдырмайды. Толықтыруға қайтарылған кезең қайта жіберіледі; ұпай растауға дейін нөл.

8. AI функциясы

Қолданылған режим: жергілікті ережелік заглушка (local_stub). Сыртқы генеративті модель қосылмаған. Бұл хакатон шартында рұқсат етілген API-сыз нұсқа.

Мазмұнды функция: жетіспейтін не жеткіліксіз өрістерді анықтау, салаға қарай сұрақтың ретін бейімдеу, кемінде үш сұрақ беру, жауаптарды карточкаға дәл көшіру. Белгісіз факт бос қалады; атау да пайдаланушы жауап бергенде ғана толады. Әр енгізілген өріске дереккөз белгісі беріледі.

analyze(body, provider=None) адаптері JSON-ды, кілттерді, дереккөз сәйкестігін тексереді. Қате JSON, ойдан шығарылған дерек немесе адаптер қатесі қауіпсіз жергілікті жауаппен ауыстырылып, ескерту қайтарылады. Нақты LLM қосу үшін осы адаптерді және құрылымды промптты пайдаланып, келісімшарт тексеруін сақтау керек. Қазіргі валидатор детерминдік stub нәтижесін дәл талап етеді.

Толық промпт, JSON мысалы және шектеулер: AI_CONTRACT.md.

9. API

Барлық POST: Content-Type: application/json. Демо рөлі: X-Demo-Role: business|student, команда: X-Team-ID: team_1 … team_5.

Әдіс	Жол	Мақсаты
GET	/api/state	рөлге сай міндеттер, командалар, ұсыныстар, кезеңдер
GET	/api/demo	синтетикалық демонстрациялық жауаптар
POST	/api/analyze	сипаттаманы нақтылау, карточка құрастыру
POST	/api/rating	сақтау алдында серверлік рейтинг есебі
POST	/api/tasks	жоба жасау немесе жариялау
POST	/api/tasks/{id}	revision тексерумен өңдеу және қайта есептеу
POST	/api/proposals	студент ұсынысы
POST	/api/proposals/{id}/decision	бизнес қабылдайды / қабылдамайды
POST	/api/milestones	таңдалған команда кезең жібереді
POST	/api/milestones/{id}/review	бизнес растайды / толықтыруға қайтарады

Қате жауап: {"error":"Қазақша түсінікті хабарлама"}. Қолданылатын кодтар: 400 валидация; 403 рөл/иелік; 404 табылмады; 409 нұсқа/кезең қайшылығы; 413 көлем; 415 JSON емес.

10. Тексеру

python3 -m unittest discover -s tests -v

Windows: py -3 -m unittest discover -s tests -v.

Тестілер бөлек уақытша SQLite базасын пайдаланады, демо деректеріңізді өзгертпейді. Негізгі тексерулер: толық сценарий, рейтинг салмағы мен шекарасы, жарияланбаған жобаны жасыру, төмен рейтингке шексіз ұсыныс, бірнеше команда таңдау, ұпайды қайталап бермеу, кері байланыспен қайта жіберу, сақтау, нұсқа қақтығысы, қауіпті URL және жарамсыз AI шығысы.

Қолмен қабылдау сценарийлері TEST_REPORT.md файлында.

11. Қорғауды қайта бастау

Қазіргі деректі өшірмей, жаңа жеке дерекқормен іске қосыңыз:

python3 server.py --port 8001 --db data/rehearsal.sqlite3

Жаңа базаға бес үлгі автоматты көшіріледі. Негізгі sana.sqlite3 сақталады. Архивте дайын пайдаланушы базасы жоқ; ол алғаш қосқанда жасалады.

12. MVP шекарасы

Бұл — жергілікті хакатон нұсқасы. Рөл ауыстырғышы мен HTTP header — демонстрациялық механизм, шынайы аутентификация емес. Бір бизнес өкілі және бес алдын ала берілген команда бар. Production-ға шығару үшін аутентификация, ұйымға тиесілілік, HTTPS, орналастыру және пайдалану шектеулері қажет. Қазір сервер әдепкіде тек 127.0.0.1 тыңдайды.

Нақты чат, файл қоймасы, ML оқыту және күрделі трекер енгізілмеген — тапсырма оларды талап етпейді. Барлық бастапқы мәліметтер синтетикалық; example.com сілтемелері нақты прототиптерге апармайды. Қолданушы өзінің нақты сілтемесін жаза алады.

13. 5 сағаттық командалық жұмыс жоспары

Уақыт	Жұмыс	Жауапты рөл
0–30 мин	сценарий, схема, критерий	бүкіл команда
30–100 мин	конструктор, сұрақтар, AI келісімшарты	backend + frontend
100–165 мин	рейтинг, растау, жетіспейтін өрістер	backend + QA
165–225 мин	каталог, ұсыныстар, қолмен шешім	frontend + backend
225–270 мин	біріктіру, валидация, кезең прогресі	бүкіл команда
270–300 мин	деректер, README, 5 минуттық репетиция	QA + спикер

Бұл кесте қорғауда команданың жұмысын ұйымдастыруға арналған жоспар; нақты жұмсалған уақыт есебі емес.