Mwongozo wa kuanza kutumia SoftJL Community: Unganisha mahitaji, UML, majaribio na nyaraka kwa AI

SoftJL Community ni nini

SoftJL Community ni kituo cha kazi cha uhandisi wa programu cha AI kinachoweza kujitegemea, kilichoundwa kwa ajili ya miradi ya kuhitimu katika programu, miradi ya kozi na kazi za UML. Huunganisha uchanganuzi wa mahitaji, uchanganuzi wa uwezekano, uundaji wa miundo ya UML, usanifu, majaribio, nyaraka za uhandisi na ufuatiliaji wa mabadiliko, ili kukusaidia kukagua ikiwa mahitaji yametekelezwa katika usanifu na majaribio, na kukusanya ushahidi unaoweza kufuatiliwa kwa ajili ya marekebisho, uwasilishaji na utetezi.

Toleo la jamii linatoa msimbo kamili wa chanzo chini ya leseni ya Apache License 2.0. Ikilinganishwa na toleo linalopangishwa kwenye tovuti rasmi, toleo la jamii linahitaji udhibiti mwenyewe wa huduma, hifadhidata na watoa huduma wa miundo, lakini linahifadhi uwezo mkuu kama vile uchimbaji wa kanuni za mahitaji, miundo kamili ya mahitaji na usanifu, ufunikaji wa majaribio, uundaji wa nyaraka, ufuatiliaji wa vyanzo, usimamizi wa miradi na muunganisho wa miundo ya BYOK.

Mtiririko mkuu wa kazi

Jukwaa linafanya kazi kwa kuzingatia mnyororo wa uhandisi kutoka mahitaji hadi uthibitishaji: kwanza weka mahitaji na uthibitishe kanuni, kisha fanya uchanganuzi wa uwezekano, unda modeli ya mahitaji na modeli ya usanifu, halafu unda kesi za majaribio na matriki ya ufunikaji, na mwisho unda nyaraka za uhandisi zinazoweza kuhaririwa na kupakuliwa.

• Kanuni za mahitaji: Huchimba kanuni kutoka kwa mahitaji ya lugha asilia, hufanya ukaguzi wa ubora, marekebisho, uthibitisho wa kibinadamu na upangaji wa masharti ya kukubalika.
• Uchanganuzi wa uwezekano: Huunda mchoro wa mazingira ya mfumo, michoro ya mtiririko wa biashara na mfumo, pamoja na uchanganuzi wa mpango wa utekelezaji.
• Miundo ya UML: Huunda miundo kama vile muundo wa utendaji, matumizi, dhana za kikoa, violesura vya mfano, mahitaji ya upelekaji, usanifu wa jumla, madarasa ya usanifu na hifadhidata.
• Majaribio na ufunikaji: Huunda kesi za majaribio ya matukio ya kawaida, yasiyo ya kawaida na ya mipaka, na hutumia matriki za ufunikaji na ufuatiliaji kutambua mapungufu.
• Nyaraka za uhandisi: Huunda ripoti ya utafiti wa uwezekano, waraka wa mahitaji ya programu na waraka wa usanifu wa programu, pamoja na kusaidia usimamizi wa matoleo na upakuaji wa DOCX.
• Athari za mabadiliko: Huonyesha uhusiano wa chanzo kati ya mahitaji, usanifu, majaribio na nyaraka, ili kubaini ni bidhaa zipi zinahitaji kusasishwa baada ya mabadiliko.
• Muunganisho wa miundo: Husababisha huduma za miundo zinazooana na OpenAI, ili kutumia watoa huduma wako wa miundo.

Matokeo yaliyoundwa yanatumika kutambua na kupanga ushahidi wa uhandisi. Bado unahitaji kukagua mwenyewe vikwazo vya miundo, maudhui ya michoro na ulinganifu wa kibiashara wa nyaraka, na kutekeleza majaribio katika mfumo halisi.

Maandalizi ya mazingira kabla ya usakinishaji

Unahitaji kuandaa mazingira yafuatayo kabla ya kuendesha kwa mara ya kwanza:

• Node.js 22
• npm 10
• Java 21
• Graphviz
• Si lazima: Docker, kwa ajili ya kuendesha PostgreSQL na OnlyOffice

Unapotumia huduma ya uchoraji kwa mara ya kwanza, mfumo unaweza kuhitaji kuunganishwa kwenye mtandao ili kupakua fonti za Kichina za PDF. Docker si lazima kwa kujaribu huduma kuu kwa muda, lakini kwa matumizi ya muda mrefu inashauriwa kusanidi PostgreSQL yenye uhifadhi endelevu; ikiwa unahitaji kuhariri DOCX mtandaoni, lazima pia uwashwe OnlyOffice.

Kuanzisha huduma kuu haraka

1. Pata msimbo wa chanzo na usakinishe utegemezi

git clone https://github.com/guolola/SoftJL.git
cd SoftJL
npm ci

2. Anzisha mazingira ya maendeleo

npm run dev

Amri hii hujenga kiotomatiki vifurushi vya pamoja vya contracts na prompts, kisha huanzisha Web, API na huduma ya uchoraji kwa wakati mmoja. Web kwa kawaida huendeshwa kwenye http://localhost:3000, API hutumia mlango 4101, na Render Service hutumia mlango 4002.

Baada ya kuona matokeo ya Web yenye Ready, unaweza kufungua http://localhost:3000. Pia inashauriwa kukagua hali ya afya:

http://localhost:3000/api/health
http://127.0.0.1:4002/health

Ncha zote mbili za ukaguzi wa afya zinapaswa kurudisha matokeo yenye status: "ok".

3. Elewa hali ya kumbukumbu ya muda

Kuendesha moja kwa moja npm run dev hutumia hali ya kumbukumbu ya muda kwa chaguo-msingi. Baada ya huduma kuwashwa upya, akaunti, miradi, usanidi wa huduma za miundo na historia ya uendeshaji vitapotea; faili za nyaraka huhifadhiwa kando katika saraka ya ndani na haziwezi kuchukua nafasi ya nakala rudufu ya hifadhidata. Kwa hiyo hali hii inafaa kwa kujaribu haraka, lakini si kwa kuhifadhi miradi kwa muda mrefu.

Kusanidi hifadhidata endelevu na uhariri wa mtandaoni

Kutumia PostgreSQL ya maendeleo

Baada ya kusakinisha na kuanzisha Docker kwenye kompyuta hii, unaweza kutumia amri ifuatayo kuendesha hifadhidata maalum ya maendeleo na huduma kuu:

npm run dev:postgres

Njia hii huhifadhi hifadhidata katika ujazo wa data wa Docker. Vitambulisho vya hifadhidata vilivyo kwenye hati hutumika kwa maendeleo ya ndani pekee; katika mazingira ya uzalishaji lazima vibadilishwe. Usitumie moja kwa moja hifadhidata iliyopo ya toleo kamili kama hifadhidata ya toleo la jamii.

Kuunganisha PostgreSQL iliyopo

Ikiwa tayari umeandaa PostgreSQL, nakili .env.example kutoka kwenye saraka kuu kuwa .env, kisha weka DATABASE_URL na UML_PROVIDER_CONFIG_SECRET uliyozalisha mwenyewe:

cp .env.example .env

Baada ya kukamilisha usanidi, endesha tena npm run dev. Hifadhi kwa uangalifu ufunguo wa usimbaji, kwa sababu kubadilisha kiholela UML_PROVIDER_CONFIG_SECRET kutafanya vitambulisho vya watoa huduma wa miundo vilivyohifadhiwa visiweze kusimbuliwa. Maelezo ya muunganisho wa hifadhidata na funguo pia havipaswi kuwasilishwa kwenye Git.

Kuwasha OnlyOffice

Unapohitaji kuhariri nyaraka mtandaoni, kwanza anzisha injini ya Docker, kisha endesha:

npm run dev:full

Skripti hii hukagua OnlyOffice kwenye mlango wa 8080 wa kompyuta hii; ikiwa huduma haipatikani, huunda au kuanzisha kontena linalohusika. Uendeshaji wa kwanza unaweza kuhitaji kupakua picha. Huduma kuu pekee zinaweza pia kuunda na kupakua nyaraka; uhariri wa mtandaoni unahitaji usanidi wa ziada wa OnlyOffice.

Kusanidi huduma za miundo ya AI

1. Anzisha huduma ya Web na uingie kwenye akaunti.
2. Fungua mipangilio ya akaunti na uongeze Provider anayeoana na OpenAI.
3. Weka HTTPS Base URL na API Key ya mtoa huduma wa miundo.
4. Tekeleza ugunduzi wa miundo na jaribio la muunganisho.
5. Chagua modeli inayopatikana kuwa modeli chaguomsingi.

Katika mazingira ya kujipangia, tumia huduma yako mwenyewe ya miundo; gharama za matumizi ya miundo hulipwa kwa mtoa huduma husika. Mazingira ya uzalishaji yanapaswa kutumia hifadhidata endelevu na ufunguo wa usimbaji wa vitambulisho, na kuzima lango la mgeni wa maendeleo pamoja na lango la urudishaji la maandishi wazi la legacy.

Kukamilisha uundaji wa mfumo wa kuhifadhi viti vya maktaba

Hapa tunatumia hitaji rahisi kama mfano: baada ya mwanafunzi kuingia, anaweza kutafuta viti vilivyo wazi, kuchagua tarehe na kipindi cha muda na kuwasilisha ombi la kuhifadhi; mwanafunzi huyo huyo hawezi kuhifadhi mara mbili katika kipindi kilekile; baada ya uhifadhi kufanikiwa, arifa hutumwa; msimamizi anaweza kudhibiti viti, kuona rekodi za uhifadhi na kushughulikia kughairi kusiko kwa kawaida.

Hatua ya 1: Unda mradi na uthibitishe kanuni za mahitaji

Baada ya kuunda mradi, weka maelezo ya biashara hapo juu kwenye jukwaa ili mfumo utoe kanuni za mahitaji. Kagua hasa majukumu ya watumiaji, masharti ya uhifadhi, kizuizi cha uhifadhi unaojirudia, tabia ya arifa na mchakato wa kughairi kusiko kwa kawaida. Baada ya kuthibitisha usahihi, hifadhi kanuni na masharti ya kukubalika ili kuzuia miundo ya baadaye kujengwa juu ya mahitaji yasiyoeleweka.

Hatua ya 2: Kamilisha uchanganuzi wa uwezekano

Kamilisha uchanganuzi wa aina tatu kulingana na mtiririko wa mradi:

• Mchoro wa mazingira ya mfumo: Bainisha mipaka na mwingiliano kati ya wanafunzi, wasimamizi, huduma ya arifa na mfumo wa kuhifadhi.
• Michoro ya mtiririko wa biashara na mfumo: Panga mchakato wa kutafuta viti, kuwasilisha uhifadhi, kutuma arifa na kughairi kusiko kwa kawaida.
• Mpango wa utekelezaji: Linganisha mipango mbadala na urekodi gharama, manufaa na hatari.

Baada ya uchanganuzi kukamilika, kwanza hakikisha kuwa mipaka ya mfumo na mtiririko vinaendana na mahitaji ya awali, kisha endelea kwenye hatua ya uundaji wa miundo.

Hatua ya 3: Unda modeli ya mahitaji na modeli ya usanifu

Jukwaa linaweza kuunda modeli kamili ya mahitaji kulingana na mahitaji yaliyothibitishwa, ikijumuisha muundo wa utendaji, mtiririko mkuu wa biashara, matumizi, dhana za kikoa, uhusiano wa violesura vya mfano na mahitaji ya upelekaji. Baada ya kuthibitisha modeli ya mahitaji, unda modeli ya usanifu kulingana na mahusiano ya awali, kama vile usanifu wa jumla, utekelezaji wa matumizi, madarasa ya usanifu, urambazaji wa kurasa, hifadhidata, uhusiano wa vipengele na usanifu wa upelekaji.

Baada ya uundaji, fungua uhusiano wa vyanzo na ukague ikiwa kila kipengele cha usanifu kinaweza kufuatiliwa hadi kwenye kanuni za mahitaji. Kwa njia hii, kanuni za uhifadhi zinapobadilika, unaweza kutambua kwa urahisi zaidi matumizi, madarasa, usanifu wa hifadhidata na majaribio yaliyoathiriwa.

Hatua ya 4: Unda majaribio na matriki ya ufunikaji

Kwenye mfumo wa kuhifadhi, angalau kagua matukio yafuatayo:

• Mwanafunzi anaweza kutafuta viti vilivyo wazi kwa tarehe na kipindi maalum cha muda.
• Mwanafunzi anaweza kuwasilisha uhifadhi halali na kupokea arifa.
• Mwanafunzi huyo huyo anapojaribu kuhifadhi tena katika kipindi kilekile, mfumo unaweza kukataa ombi.
• Wakati hakuna kiti kilicho wazi, kipindi cha muda si halali au taarifa za uhifadhi hazijakamilika, mfumo unaweza kushughulikia hitilafu.
• Msimamizi anaweza kudhibiti viti, kuona rekodi za uhifadhi na kushughulikia kughairi kusiko kwa kawaida.

Tumia matriki ya ufunikaji na matriki ya ufuatiliaji kutambua mahitaji yasiyo na msingi wa usanifu au majaribio. Kesi za majaribio zilizoundwa na jukwaa bado zinahitaji kutekelezwa katika mfumo halisi; kufanikiwa kwa uundaji pekee hakuwezi kuwa matokeo ya kukubalika.

Hatua ya 5: Unda nyaraka za uhandisi

Baada ya kukamilisha uchanganuzi wa uwezekano, modeli ya mahitaji na modeli ya usanifu, unaweza kuunda aina tatu za nyaraka za uhandisi: ripoti ya utafiti wa uwezekano, waraka wa mahitaji ya programu na waraka wa usanifu wa programu. Baada ya kuziunda, kagua ikiwa maandishi yanaendana na michoro, zirekebishe kulingana na violezo na mahitaji ya uumbizaji ya shule, kisha ufanye usimamizi wa matoleo na upakuaji wa DOCX.

Jinsi ya kushughulikia mabadiliko ya mahitaji

Kwa mfano, mradi unabadilisha kanuni kutoka “mwanafunzi huyo huyo hawezi kuhifadhi mara mbili katika kipindi kilekile” kuwa “mwanafunzi huyo huyo anaweza kuhifadhi vipindi viwili vya muda kwa siku.” Usibadilishe sentensi moja tu katika nyaraka; badala yake, kagua kwa kufuata uhusiano wa vyanzo na utegemezi:

1. Hifadhi na uthibitishe kanuni mpya ya mahitaji.
2. Fungua uhusiano wa vyanzo na athari za mabadiliko, kisha uone mahitaji, matumizi, usanifu na bidhaa za majaribio zilizoathiriwa.
3. Sasisha modeli ya mahitaji na modeli ya usanifu kulingana na mpangilio wa utegemezi.
4. Kagua tena vikwazo vya hifadhidata, mtiririko wa biashara na ushughulikiaji wa hitilafu.
5. Sasisha kesi za majaribio na matriki ya ufunikaji, kisha tekeleza majaribio ya urejeshaji katika mfumo halisi.
6. Unda upya au rekebisha nyaraka zinazohusika na uhifadhi rekodi za matoleo.

Viunganishi vya vyanzo na idadi ya ufunikaji vinafaa kukusaidia kutambua eneo la ukaguzi, lakini bado unapaswa kufungua miundo mahususi ili kuthibitisha kama vikwazo, masharti ya pembejeo na tabia vimekamilika.

Kuunganisha Coding Agent wa nje

Toleo la jamii linaweza kuwezeshwa na mtekelezaji ili kutoa muunganisho wa MCP wa kusoma pekee, unaowaruhusu Coding Agent wanaoendana kusoma usanifu uliohifadhiwa ndani ya upeo wa mradi, masharti ya kukubalika, vikwazo vya uhandisi na taarifa za majaribio. Lango la matumizi ya ndani la MCP linapatikana kwenye “Msaidizi wa programu” katika upau wa kando au “Unganisha mradi huu” katika mipangilio ya mradi; kabla ya kulitumia, lazima ukamilishe usakinishaji na ujenzi.

npm run dev:mcp

Muunganisho huu hutoa ushahidi wa uhandisi kwa kusoma pekee na hauwezi kuchukua nafasi ya ukaguzi wa msimbo, uendeshaji halisi na kukubalika kwa majaribio. README pia inaeleza hasa kuwa uoanifu wa mteja halisi wa Coding Agent na kukubalika kwa msimbo ulioundwa bado vinaboreshwa; unapotumia, rejelea maelezo ya muunganisho wa MCP.

Amri za kawaida za maendeleo

• npm run build:packages: Jenga vifurushi vya pamoja vya contracts na prompts.
• npm run build: Jenga vifurushi vya pamoja na programu zote.
• npm run dev:render: Anzisha huduma ya uchoraji ya PlantUML pekee.
• npm run test:contracts: Thibitisha mikataba ya pamoja.
• npm run test:api: Endesha majaribio ya API.
• npm run test:render: Endesha majaribio ya huduma ya uchoraji.
• npm run test:web: Endesha majaribio kamili ya Web.
• npm run typecheck:web: Kagua aina za Web.
• npm run lint:web: Tekeleza ukaguzi tuli wa Web.
• npm audit --audit-level=high: Kagua matangazo ya usalama ya utegemezi.

Baada ya vifurushi vya pamoja kubadilika, kabla ya kuanzisha programu pekee au kuendesha majaribio, tekeleza kwanza npm run build:packages. Matokeo ya ujenzi, usanidi wa mazingira, funguo za faragha, kumbukumbu na data ya uendeshaji ya ndani vinapaswa kubaki katika eneo linalopuuzwa na Git.

Muhtasari wa usanifu

Mradi hutumia muundo wa programu nyingi na vifurushi vya pamoja:

• apps/web: Nafasi ya kazi ya React, Next.js na kurasa.
• apps/api: API ya Fastify, uthibitishaji, mchakato wa uzalishaji, rekodi za uendeshaji na uundaji wa nyaraka.
• apps/render-service: Uchoraji wa michoro ya PlantUML.
• packages/contracts na packages/prompts: Mikataba na vidokezo vya uzalishaji vinavyoshirikiwa.
• packages/harness-e2e na packages/harness-eval: Majaribio ya kukubalika na tathmini ya ubora.

Mambo ya Kuzingatia Kuhusu Usambazaji na Matumizi

• Toleo la jumuiya linapaswa kutumia hifadhidata huru; lisitumike kama mbadala uliopunguzwa wa hifadhidata kamili ya tovuti rasmi.
• Vitambulisho vya hifadhidata katika hati za kuanzisha maendeleo vinafaa kutumika kwenye kompyuta ya ndani pekee; lazima vibadilishwe katika mazingira ya uzalishaji.
• Funguo za modeli, maelezo ya muunganisho wa hifadhidata na funguo za usimbaji fiche hazipaswi kuwasilishwa kwenye hazina ya msimbo.
• Hati ya maelezo ya mradi inaweza kutumika kama nyenzo ya ripoti ya mradi, lakini si sawa na tasnifu kamili ya kuhitimu.
• Ulinganifu wa kibiashara wa michoro, nyaraka na msimbo unahitaji kukaguliwa na binadamu na kuthibitishwa kwa ushahidi wa uendeshaji.
• Kabla ya kusambaza katika uzalishaji, badilisha kikoa cha huduma, hifadhidata, barua pepe na mipangilio ya modeli.

Muhtasari

SoftJL Community inafaa kwa wasanidi wanaotaka kupanga miradi yao ya kuhitimu au ya kozi kwa kufuata mchakato wa kihandisi. Baada ya kukamilisha usakinishaji wa mazingira, usanidi wa hifadhidata na modeli, unaweza kuanzia kwenye mahitaji na kanuni, kisha kuzalisha hatua kwa hatua uchanganuzi wa uwezekano, miundo ya mahitaji na usanifu ya UML, ufunikaji wa majaribio na hati ya maelezo ya mradi, huku ukifuatilia wigo wa athari mabadiliko ya mahitaji yanapotokea.

Inaweza kupunguza kutawanyika kwa nyenzo na upangaji wa kurudia-rudia, lakini haiwezi kuchukua nafasi ya uamuzi wa usanifu wa binadamu, utekelezaji wa msimbo, majaribio halisi na maandalizi ya mwisho ya utetezi. Inapendekezwa kutumia maudhui yanayozalishwa na jukwaa kama rasimu ya kihandisi inayoweza kufuatiliwa na msingi wa ukaguzi, kisha kukamilisha uwasilishaji wa mwisho kwa kuzingatia mahitaji ya chuo na matokeo halisi ya uendeshaji wa mfumo.