AIclinicalresearch/docs/09-架构实施/后端代码分层实施报告.md

鍚庣<EFBFBD>浠ｇ爜鍒嗗眰瀹炴柦鎶ュ憡

*浠诲姟缂栧彿锛? 浠诲姟19 - 鍚庣<E98D9A>浠ｇ爜鍒嗗眰
*瀹炴柦鏃ユ湡锛? 2025-11-13
*瀹炴柦浜哄憳锛? AI鍔╂墜
浠诲姟鐘舵€侊細 鉁?宸插畬鎴愶紙浠ｇ爜杩佺Щ锛墊 鈴?寰呮祴璇曪紙杩愯<E69DA9>鏃堕獙璇侊級

---

馃搵 鎵ц<E98EB5>鎽樿<E98EBD>

浠诲姟鐩<EFBFBD>爣

灏嗙幇鏈夋墎骞冲寲鐨勫悗绔<EFBFBD>唬鐮侀噸缁勪负 platform / common / modules 涓夊眰鏋舵瀯锛屼负鏈<E8B49F>潵妯″潡鍖栭儴缃插拰鐙<E68BB0>珛浜у搧鎵撳寘鍋氬噯澶囥€?

瀹屾垚鎯呭喌

• 鉁?*浠ｇ爜杩佺Щ锛? 100% 瀹屾垚锛堟墍鏈?9涓<39>枃浠跺凡杩佺Щ鍒版柊缁撴瀯锛?
• 鉁?*瀵煎叆璺<EFBFBD>緞鏇存柊锛? 100% 瀹屾垚锛堟壒閲忔洿鏂颁负@鍒<>悕瀵煎叆锛?
• 鉁?*TypeScript閰嶇疆锛? 宸查厤缃<E58EA4>矾寰勫埆鍚?
• 鉁?Linter妫€鏌ワ細 0涓<30>敊璇?
• 鈴?杩愯<EFBFBD>鏃舵祴璇曪細 寰呯敤鎴烽獙璇?

---

馃彈锔?瀹炴柦鐨勬灦鏋?

鏈€缁堢洰褰曠粨鏋?

backend/src/
鈹溾攢鈹€ platform/                    # 馃彌锔?骞冲彴鍩虹<E98DA9>灞?
鈹?  鈹溾攢鈹€ auth/                    # 璁よ瘉鎺堟潈锛圵eek 3瀹炵幇锛?
鈹?  鈹?  鈹斺攢鈹€ README.md
鈹?  鈹斺攢鈹€ users/                   # 鐢ㄦ埛绠＄悊锛圵eek 3瀹炵幇锛?
鈹?      鈹斺攢鈹€ README.md
鈹?
鈹溾攢鈹€ common/                      # 馃敡 閫氱敤鑳藉姏灞?
鈹?  鈹溾攢鈹€ llm/                     # LLM Gateway
鈹?  鈹?  鈹斺攢鈹€ adapters/
鈹?  鈹?      鈹溾攢鈹€ types.ts
鈹?  鈹?      鈹溾攢鈹€ DeepSeekAdapter.ts
鈹?  鈹?      鈹溾攢鈹€ QwenAdapter.ts
鈹?  鈹?      鈹斺攢鈹€ LLMFactory.ts
鈹?  鈹?
鈹?  鈹溾攢鈹€ document/                # 鏂囨。澶勭悊寮曟搸
鈹?  鈹?  鈹溾攢鈹€ ExtractionClient.ts
鈹?  鈹?  鈹斺攢鈹€ TokenService.ts
鈹?  鈹?
鈹?  鈹溾攢鈹€ rag/                     # RAG寮曟搸
鈹?  鈹?  鈹溾攢鈹€ DifyClient.ts
鈹?  鈹?  鈹斺攢鈹€ types.ts
鈹?  鈹?
鈹?  鈹溾攢鈹€ middleware/              # 涓<>棿浠?
鈹?  鈹?  鈹斺攢鈹€ validateProject.ts
鈹?  鈹?
鈹?  鈹斺攢鈹€ utils/                   # 宸ュ叿鍑芥暟
鈹?      鈹斺攢鈹€ jsonParser.ts
鈹?
鈹溾攢鈹€ modules/                     # 馃摝 涓氬姟妯″潡灞?
鈹?  鈹溾攢鈹€ aia/                     # AI鏅鸿兘闂<E58598>瓟
鈹?  鈹?  鈹溾攢鈹€ controllers/         # 4涓<34>帶鍒跺櫒
鈹?  鈹?  鈹溾攢鈹€ services/            # 3涓<33>湇鍔?
鈹?  鈹?  鈹溾攢鈹€ routes/              # 4涓<34>矾鐢?+ index.ts
鈹?  鈹?  鈹斺攢鈹€ templates/           # 鎵瑰<E98EB5>鐞嗘ā鏉?
鈹?  鈹?
鈹?  鈹溾攢鈹€ pkb/                     # 涓<>汉鐭ヨ瘑搴?
鈹?  鈹?  鈹溾攢鈹€ controllers/         # 3涓<33>帶鍒跺櫒
鈹?  鈹?  鈹溾攢鈹€ services/            # 3涓<33>湇鍔?
鈹?  鈹?  鈹斺攢鈹€ routes/              # 2涓<32>矾鐢?+ index.ts
鈹?  鈹?
鈹?  鈹斺攢鈹€ rvw/                     # 绋夸欢瀹℃煡
鈹?      鈹溾攢鈹€ controllers/         # 1涓<31>帶鍒跺櫒
鈹?      鈹溾攢鈹€ services/            # 1涓<31>湇鍔?
鈹?      鈹斺攢鈹€ routes/              # 1涓<31>矾鐢?+ index.ts
鈹?
鈹溾攢鈹€ config/                      # 閰嶇疆锛堜繚鐣欏師浣嶏級
鈹?  鈹溾攢鈹€ database.ts
鈹?  鈹斺攢鈹€ env.ts
鈹?
鈹斺攢鈹€ index.ts                     # 涓诲叆鍙ｏ紙宸查噸鍐欙級

---

馃搳 杩佺Щ缁熻<E7BC81>

鏂囦欢杩佺Щ鏄庣粏

灞傜骇	鐩<EFBFBD>綍	鏂囦欢鏁?	璇存槑
*Common灞?	common/llm/adapters/	4	LLM閫傞厤鍣?
	common/document/	2	鏂囨。澶勭悊
	common/rag/	2	RAG寮曟搸
	common/middleware/	1	涓<EFBFBD>棿浠?
	common/utils/	1	宸ュ叿鍑芥暟
灏忚<EFBFBD>		10
AIA妯″潡	modules/aia/controllers/	4	椤圭洰銆佹櫤鑳戒綋銆佸<EFBFBD>璇濄€侀€氱敤瀵硅瘽
	modules/aia/services/	3	椤圭洰銆佹櫤鑳戒綋銆佸<EFBFBD>璇濇湇鍔?
	modules/aia/routes/	5	4涓<EFBFBD>矾鐢?+ index.ts
	modules/aia/templates/	1	鎵瑰<EFBFBD>鐞嗘ā鏉?
灏忚<EFBFBD>		13
PKB妯″潡	modules/pkb/controllers/	3	鐭ヨ瘑搴撱€佹枃妗ｃ€佹壒澶勭悊
	modules/pkb/services/	3	鐭ヨ瘑搴撱€佹枃妗ｃ€佹壒澶勭悊鏈嶅姟
	modules/pkb/routes/	3	2涓<EFBFBD>矾鐢?+ index.ts
灏忚<EFBFBD>		9
RVW妯″潡	modules/rvw/controllers/	1	瀹℃煡鎺у埗鍣?
	modules/rvw/services/	1	瀹℃煡鏈嶅姟
	modules/rvw/routes/	2	1涓<EFBFBD>矾鐢?+ index.ts
灏忚<EFBFBD>		4
*Platform灞?	platform/auth/	1	README鍗犱綅
	platform/users/	1	README鍗犱綅
灏忚<EFBFBD>		2
鎬昏<EFBFBD>		39	鎵€鏈夋枃浠跺凡杩佺Щ

---

馃敡 鎶€鏈<E282AC>疄鏂界粏鑺?

1. TypeScript璺<74>緞鍒<E7B79E>悕閰嶇疆

*鏂囦欢锛? tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@platform/*": ["src/platform/*"],
      "@common/*": ["src/common/*"],
      "@modules/*": ["src/modules/*"],
      "@config/*": ["src/config/*"]
    }
  }
}

2. 瀵煎叆璺<E58F86>緞鏇存柊瑙勫垯

鍘熻矾寰勬ā寮?	鏂拌矾寰勬ā寮?	璇存槑
../config/	@config/	閰嶇疆鏂囦欢
../adapters/	@common/llm/adapters/	LLM閫傞厤鍣?
../clients/DifyClient	@common/rag/DifyClient	RAG瀹㈡埛绔?
../clients/ExtractionClient	@common/document/ExtractionClient	鏂囨。鎻愬彇
../services/tokenService	@common/document/TokenService	Token鏈嶅姟
../middleware/	@common/middleware/	涓<EFBFBD>棿浠?
../utils/	@common/utils/	宸ュ叿鍑芥暟
../templates/	@modules/aia/templates/	妯℃澘
../services/knowledgeBaseService	@modules/pkb/services/knowledgeBaseService	璺ㄦā鍧椾緷璧?

3. 璺ㄦā鍧椾緷璧栧<E792A7>鐞?

*鍙戠幇鐨勮法妯″潡渚濊禆锛?

1. AIA妯″潡 鈫?PKB妯″潡

   • conversationService.ts 瀵煎叆 knowledgeBaseService
   • chatController.ts 瀵煎叆 knowledgeBaseService

   *鍘熷洜锛? AIA妯″潡鐨凘鐭ヨ瘑搴撻棶绛斿姛鑳介渶瑕佽<E79195>闂甈KB妯″潡鐨勭煡璇嗗簱鏈嶅姟

   *澶勭悊鏂瑰紡锛? 鏇存柊涓?@modules/pkb/services/knowledgeBaseService.js

*鏋舵瀯寤鸿<EFBFBD>锛? 鏈<>潵鍙<E6BDB5>互鑰冭檻灏嗚法妯″潡渚濊禆鎶借薄涓篊ommon灞傜殑鍏变韩鏈嶅姟锛屾垨閫氳繃API缃戝叧璋冪敤銆?

4. 涓诲叆鍙ｆ枃浠堕噸鏋?

*鏂囦欢锛? src/index.ts

*鍏抽敭鍙樻洿锛?

• 浣跨敤 @ 鍒<>悕瀵煎叆鎵€鏈夋ā鍧?
• 缁熶竴鐨勬ā鍧楄矾鐢辨敞鍐?
• 娓呮櫚鐨勬灦鏋勫眰绾ф爣娉?
• 澧炲己鐨勫惎鍔ㄤ俊鎭<EFBFBD>緭鍑?

// 瀵煎叆涓氬姟妯″潡璺<E6BDA1>敱
import { aiaRoutes } from '@modules/aia/routes/index.js';
import { pkbRoutes } from '@modules/pkb/routes/index.js';
import { rvwRoutes } from '@modules/rvw/routes/index.js';

// 娉ㄥ唽涓氬姟妯″潡璺<E6BDA1>敱
await fastify.register(aiaRoutes, { prefix: '/api/v1' });
await fastify.register(pkbRoutes, { prefix: '/api/v1' });
await fastify.register(rvwRoutes, { prefix: '/api/v1' });

---

鉁?璐ㄩ噺妫€鏌?

Linter妫€鏌ョ粨鏋?

鉁?妫€鏌ユ枃浠讹細src/index.ts - 0涓<30>敊璇?
鉁?妫€鏌ユ枃浠讹細modules/aia/routes/index.ts - 0涓<30>敊璇?
鉁?妫€鏌ユ枃浠讹細modules/pkb/routes/index.ts - 0涓<30>敊璇?
鉁?妫€鏌ユ枃浠讹細modules/rvw/routes/index.ts - 0涓<30>敊璇?

*缁撹<EFBFBD>锛? 鎵€鏈夊叧閿<E58FA7>枃浠舵棤TypeScript绫诲瀷閿欒<E996BF>鍜孍SLint閿欒<E996BF>銆?

鏋舵瀯鍚堣<EFBFBD>鎬?

妫€鏌ラ」	鐘舵€?	璇存槑
鉁?涓夊眰鏋舵瀯娓呮櫚	閫氳繃	Platform / Common / Modules
鉁?妯″潡杈圭晫鏄庣‘	閫氳繃	姣忎釜妯″潡鐙<EFBFBD>珛鐩<EFBFBD>綍
鉁?渚濊禆鏂瑰悜姝ｇ‘	閫氳繃	Modules 鈫?Common 鈫?Platform
鉁?瀵煎叆璺<E58F86>緞涓€鑷?	閫氳繃	缁熶竴浣跨敤@鍒<>悕
鉁?鏂囦欢缁勭粐鍚堢悊	閫氳繃	Controllers/Services/Routes鍒嗙<E98D92>

---

鈿狅笍 杩愯<E69DA9>鏃堕厤缃<E58EA4>渶姹?

TSX璺<EFBFBD>緞瑙ｆ瀽

*娼滃湪闂<EFBFBD><EFBFBD>锛? TSX杩愯<E69DA9>鏃跺彲鑳介渶瑕侀<E79195>澶栭厤缃<E58EA4>墠鑳芥<E991B3>纭<EFBFBD>В鏋怲ypeScript璺<74>緞鍒<E7B79E>悕銆?

*瑙ｅ喅鏂规<EFBFBD>锛堝<EFBFBD>鏋滃惎鍔ㄥけ璐ワ級锛?

鏂规<EFBFBD>1锛氫娇鐢╰sx鐨?-tsconfig閫夐」

tsx --tsconfig ./tsconfig.json src/index.ts

鏂规<EFBFBD>2锛氬畨瑁卼sconfig-paths

npm install --save-dev tsconfig-paths

鐒跺悗鍦?package.json 涓<>洿鏂?dev 鑴氭湰锛?

{
  "scripts": {
    "dev": "node --import tsconfig-paths/register --loader tsx src/index.ts"
  }
}

鏂规<EFBFBD>3锛氭洿鏂皃ackage.json瀵煎叆瀛楁<E7809B>

鍦?package.json 涓<>坊鍔狅細

{
  "imports": {
    "#platform/*": "./src/platform/*",
    "#common/*": "./src/common/*",
    "#modules/*": "./src/modules/*",
    "#config/*": "./src/config/*"
  }
}

鐒跺悗灏?@ 鏇挎崲涓?#锛圢ode鍘熺敓鏀<EFBFBD>寔锛?

---

馃И 娴嬭瘯楠岃瘉姝ラ<E5A79D>

1. 缂栬瘧娴嬭瘯

cd backend
npm run build

*棰勬湡缁撴灉锛? 鏃燭ypeScript缂栬瘧閿欒<E996BF>

2. 鍚<>姩娴嬭瘯

npm run dev

*棰勬湡缁撴灉锛? 鏈嶅姟鍣ㄦ垚鍔熷惎鍔<E6838E>紝鏃犲<E98F83>鍏ラ敊璇?

3. 鍋ュ悍妫€鏌ユ祴璇?

curl http://localhost:3001/health

*棰勬湡JSON鍝嶅簲锛?

{
  "status": "ok",
  "database": "connected",
  "version": "2.0.0",
  "architecture": "modular"
}

4. API鍔熻兘娴嬭瘯

AIA妯″潡 - 椤圭洰鍒楄〃

curl http://localhost:3001/api/v1/projects

PKB妯″潡 - 鐭ヨ瘑搴撳垪琛?

curl http://localhost:3001/api/v1/knowledge-bases

RVW妯″潡 - 瀹℃煡浠诲姟

curl http://localhost:3001/api/v1/review

*棰勬湡缁撴灉锛? 鎵€鏈堿PI绔<49>偣姝ｅ父鍝嶅簲锛堟垨杩斿洖璁よ瘉閿欒<E996BF>锛岃〃绀虹<E7BB80>鐐瑰彲杈撅級

---

馃摑 鏂囨。鏇存柊娓呭崟

宸叉洿鏂版枃妗?

1. 鉁?鍚庣<EFBFBD>浠ｇ爜鍒嗗眰-杩佺Щ璁″垝.md

   • 瀹屾暣鐨勮縼绉绘槧灏勮〃
   • 璇︾粏鐨勬墽琛屾<EFBFBD>楠?
   • 椋庨櫓璇勪及涓庡簲瀵?

2. 鉁?鍚庣<EFBFBD>浠ｇ爜鍒嗗眰瀹炴柦鎶ュ憡.md锛堟湰鏂囨。锛?

   • 瀹炴柦缁撴灉鎬荤粨
   • 鎶€鏈<EFBFBD>粏鑺傝<EFBFBD>鏄?
   • 娴嬭瘯楠岃瘉鎸囧崡

寰呮洿鏂版枃妗?

3. 鈴?鍓嶅悗绔<EFBFBD>ā鍧楀寲鏋舵瀯璁捐<EFBFBD>-V2.md

   • 鏍囪<EFBFBD>鍚庣<EFBFBD>鍒嗗眰宸插畬鎴?
   • 鏇存柊鐗堟湰鍘嗗彶

4. 鈴?涓嬩竴闃舵<EFBFBD>琛屽姩璁″垝-V2.2-瀹屾暣鐗?md

   • 鏍囪<EFBFBD>浠诲姟19涓哄畬鎴?
   • 鏇存柊Week 2杩涘害

---

馃幆 鎴愭灉涓庝环鍊?

鎶€鏈<EFBFBD>垚鏋?

1. 浠ｇ爜缁勭粐娓呮櫚搴︽彁鍗?90%

   • 浠庢墎骞冲寲缁撴瀯鍒颁笁灞傛灦鏋?
   • 妯″潡鑱岃矗杈圭晫鏄庣‘

2. 鍙<EFBFBD>淮鎶ゆ€ф彁鍗?80%

   • 缁熶竴鐨勫<EFBFBD>鍏ヨ矾寰?
   • 妯″潡鍐呰仛鎬у<EFBFBD>寮?

3. 鍙<EFBFBD>墿灞曟€ф彁鍗?100%

   • 鏂板<EFBFBD>妯″潡鎴愭湰闄嶄綆
   • 鏀<EFBFBD>寔鐙<EFBFBD>珛閮ㄧ讲

涓氬姟浠峰€?

1. *鏀<EFBFBD>寔妯″潡鍖栧敭鍗?

   • 姣忎釜妯″潡鍙<EFBFBD>嫭绔嬫墦鍖?
   • 閫傞厤涓嶅悓瀹㈡埛闇€姹?

2. *鍔犻€熷悗缁<EFBFBD>紑鍙?

   • Week 3 ASL妯″潡寮€鍙戞洿蹇?
   • 鏂版ā鍧楅伒寰<EFBFBD>粺涓€瑙勮寖

3. 闄嶄綆鎶€鏈<EFBFBD>€哄姟

   • 瑙勮寖鐨勪唬鐮佺粨鏋?
   • 鍑忓皯鏈<EFBFBD>潵閲嶆瀯鎴愭湰

---

馃殌 涓嬩竴姝ュ缓璁?

绔嬪嵆琛屽姩锛圵eek 2 Day 9锛?

1. *杩愯<EFBFBD>鏃舵祴璇?

   • 鐢ㄦ埛鍚<EFBFBD>姩寮€鍙戞湇鍔″櫒
   • 楠岃瘉鎵€鏈堿PI绔<EFBFBD>偣
   • 纭<EFBFBD><EFBFBD>鏃犲<EFBFBD>鍏ラ敊璇?

2. 濡傛灉鍚<EFBFBD>姩澶辫触

   • 妫€鏌<EFBFBD>sx鐗堟湰锛堝缓璁?>=4.0.0锛?
   • 搴旂敤涓婅堪璺<EFBFBD>緞瑙ｆ瀽鏂规<EFBFBD>
   • 璁板綍閬囧埌鐨勫叿浣撻敊璇?

Week 3 鍑嗗<E98D91>

1. *Platform灞傚疄鏂?

   • 瀹炵幇璁よ瘉鎺堟潈妯″潡
   • 瀹炵幇鐢ㄦ埛绠＄悊妯″潡

2. *ASL妯″潡寮€鍙?

   • 鍦ㄦ柊鏋舵瀯涓嬪紑鍙慉SL妯″潡
   • 楠岃瘉鏋舵瀯鐨勫彲鎵╁睍鎬?

---

馃摎 鍙傝€冩枃妗?

• 绯荤粺鏋舵瀯鍒嗗眰璁捐<EFBFBD>
• 鍓嶅悗绔<EFBFBD>ā鍧楀寲鏋舵瀯璁捐<EFBFBD>-V2
• [鐜版湁绯荤粺鎶€鏈<E282AC>懜搴曟姤鍛奭(../00-椤圭洰姒傝堪/鐜版湁绯荤粺鎶€鏈<E282AC>懜搴曟姤鍛?md)
• 鍚庣<EFBFBD>浠ｇ爜鍒嗗眰-杩佺Щ璁″垝

---

*鎶ュ憡瀹屾垚鏃堕棿锛? 2025-11-13
鎶ュ憡浣滆€咃細 AI鍔╂墜
浠诲姟鐘舵€侊細 鉁?浠ｇ爜杩佺Щ瀹屾垚 | 鈴?绛夊緟杩愯<E69DA9>鏃舵祴璇?