From 651cd10dc5a7c02411fd74cfe4b3b17560495c1e Mon Sep 17 00:00:00 2001
From: 云 <2163098428@qq.com>
Date: 星期三, 28 十月 2026 14:03:58 +0800
Subject: [PATCH] docs(agent): 添加智能体相关开发文档

---
 docs/sale_order_production_cancel_integration.md    |   84 ++
 docs/agent-material-import-开发进度.md                  |  109 ++
 docs/ai_model_capability_integration.md             |  107 ++
 docs/industrial-agent-python-design.md              |  162 ++++
 docs/work_order_process_warehouse_integration.md    |  110 ++
 docs/mes_workbench_workstation_pending_count.md     |   93 ++
 docs/mdm_item_category_unification.md               |   73 +
 docs/route_process_output_attribution.md            |  112 ++
 docs/industrial-agent-langgraph-technical-design.md |  285 +++++++
 sql/mysql/20261028_sp_generic_shift_dates.sql       |  290 +++++++
 docs/mes_collect_design.md                          |  289 +++++++
 docs/industrial-agent-authorization-design.md       |  110 ++
 docs/industrial-agent-document-onboarding-design.md |  192 ++++
 docs/industrial-agent-scenario-blueprint.md         |  189 ++++
 docs/mes_collect_frontend_integration.md            |  179 ++++
 15 files changed, 2,384 insertions(+), 0 deletions(-)

diff --git "a/docs/agent-material-import-\345\274\200\345\217\221\350\277\233\345\272\246.md" "b/docs/agent-material-import-\345\274\200\345\217\221\350\277\233\345\272\246.md"
new file mode 100644
index 0000000..b5623b5
--- /dev/null
+++ "b/docs/agent-material-import-\345\274\200\345\217\221\350\277\233\345\272\246.md"
@@ -0,0 +1,109 @@
+# 鏅鸿兘浣撶墿鏂欏鍏� - 寮�鍙戣繘搴�
+
+> 鏇存柊鏃堕棿锛�2026-10-22
+> 鍏宠仈椤圭洰锛歚D:\鐗涢┈\鍗楅�歕鍚庣\mom-industrial-agent`锛圥ython 鏅鸿兘浣擄級+ 鏈」鐩紙Java Bridge锛�
+> 娴嬭瘯搴擄細鏈湴 `ruoyi-vue-pro`锛圖ocker 瀹瑰櫒 `mysql8`锛孧ySQL 8.4.8锛�
+
+## 鎬讳綋鐘舵��
+
+绔埌绔摼璺凡鎵撻�氬苟瀹屾垚璐熶緥楠屾敹锛�
+
+```
+鍒涘缓琛ュ綍浼氳瘽 鈫� 涓婁紶 CSV 鈫� 缁戝畾闄勪欢 鈫� Python 鍒涘缓浠诲姟
+鈫� Java 鍙棰勬 鈫� 浜哄伐瀹℃牳纭 鈫� 骞傜瓑鎻愪氦 鈫� 閫愯鍥炴墽
+```
+
+闃舵 1~6 鍏ㄩ儴瀹屾垚锛孞ava 涓� Python 娴嬭瘯鍏ㄧ豢锛屾祴璇曟暟鎹凡閫昏緫鍒犻櫎銆�
+
+## 鍚勯樁娈靛畬鎴愭儏鍐�
+
+| 闃舵 | 鍐呭 | 鐘舵�� |
+|------|------|------|
+| 1 | 妗ユ帴鍓嶇疆淇锛氱湡瀹� HTTP 鐘舵�佺爜銆佺鎴峰厹搴曘�佹湇鍔′护鐗屽畧鍗�侀檮浠惰鍙栧鐢ㄣ��403 鏉冮檺鏄犲皠 | 瀹屾垚 |
+| 2 | 鎶藉彇鐗╂枡瀵煎叆瑙ｆ瀽锛坄buildImportContext/resolveImportRow`锛屽師瀵煎叆琛屼负涓嶅彉锛� | 瀹屾垚 |
+| 3 | Java 鍙棰勬锛堝垎绫�/鍗曚綅瑙ｆ瀽銆佺紪鐮佸瓨鍦ㄦ�с�丆REATE/SKIP/BLOCKED銆佺‘瀹氭�� preflight_hash锛� | 瀹屾垚 |
+| 4 | Java 骞傜瓑鎻愪氦锛坈ommand_id/idempotency_key銆丳LAN_STALE銆侀�愯鐙珛浜嬪姟銆佹煡璇㈠洖鎵э級 | 瀹屾垚 |
+| 5 | Python 鏀归�狅紙preflight/review/confirm/commit 鍥俱�丆ommonResult 瑙ｆ瀽銆佽秴鏃跺璐︺�乼oken 涓嶅叆 checkpoint锛� | 瀹屾垚 |
+| 6 | 鐪熷疄绔埌绔仈璋冦�佽礋渚嬨�佹暟鎹簱鏍稿銆佹竻鐞嗐�佹枃妗� | 瀹屾垚 |
+
+## 闃舵 6 瀹炴祴璁板綍
+
+姝ｅ悜閾捐矾锛�
+
+- 棰勬缁撴灉 2 琛� `CREATE`锛涙彁浜よ繑鍥� `SUCCEEDED`锛宍targetItemId` = 1994 / 1995銆�
+- `mdm_item` 1053 鈫� 1055锛屼腑鏂囧悕绉拌惤搴撴纭紱`mes_md_item` 鏃犲彉鍖栵紙鏈悓姝� MES锛夈��
+- 閲嶅鎻愪氦鍚屼竴璇锋眰杩斿洖鍘熷洖鎵э紝涓嶆柊澧炵墿鏂欍��
+- 娓呯悊锛氭寜 `target_item_id` 灏嗕袱鏉℃祴璇曠墿鏂欑疆 `deleted=1`锛屾暟閲忓洖鍒� 1053銆�
+
+璐熶緥楠屾敹锛�
+
+| 鍦烘櫙 | 缁撴灉 |
+|------|------|
+| 鏃� Bearer token | 401 |
+| 閿欒鏈嶅姟浠ょ墝 | 403 |
+| 鐢ㄦ埛鏃� `mdm:item:import` 鏉冮檺 | 403 `FORBIDDEN` |
+| 璺ㄧ敤鎴�/璺ㄤ細璇濋檮浠� | 404 / 鎷掔粷 |
+| source_sha256 绡℃敼 | `SOURCE_DIGEST_MISMATCH` |
+| 鍚� commandId 鏀瑰唴瀹� | 409 `COMMAND_ID_CONFLICT` |
+| 鍚屽箓绛夐敭鏀瑰唴瀹� | 409 `IDEMPOTENCY_CONFLICT` |
+| 棰勬杈撳叆鍙樺寲鍚庣敤鏃� hash 鎻愪氦 | 409 `PLAN_STALE`锛坆ody 甯︽渶鏂伴妫�锛� |
+| 鍏抽棴 Java 鍐欏紑鍏� | 503 `WRITE_DISABLED` |
+| 鍏抽棴 Python 鎻愪氦寮�鍏� | 409 `COMMIT_DISABLED` |
+| 涓婁紶瓒呰繃 8 MiB | 鎷掔粷 |
+
+娴嬭瘯缁撴灉锛�
+
+- Java锛�13 涓拡瀵规�у崟娴嬮�氳繃锛沗mvn -pl yudao-server -am -DskipTests package` 閫氳繃銆�
+- Python锛歚uv run pytest -q` 14 椤归�氳繃锛宍uv run ruff check .` 鏃犲憡璀︺��
+
+## 杩愯閰嶇疆
+
+| 寮�鍏� | 浣嶇疆 | 榛樿 |
+|------|------|------|
+| Java 鍐欏紑鍏� | `yudao.agent.bridge.write-enabled` | `false` |
+| Python 鎻愪氦寮�鍏� | `MOM_COMMIT_ENABLED` | `false` |
+| 鏈嶅姟浠ょ墝 | `yudao.agent.bridge-service-token`锛坓itignored `application-my.yaml`锛� | 蹇呭～锛屾湭閰嶇疆鍒欐嫆缁� |
+| MES 鍚屾 | 鍥哄畾 `syncMes=false` | 鍏抽棴 |
+
+鑱旇皟鏃堕渶鍚屾椂鎵撳紑涓や釜鍐欏紑鍏筹紱浠讳竴鍏抽棴鍗冲仠姝㈠啓鍏ョ墿鏂欍��
+
+## 鏁版嵁搴撳彉鏇�
+
+| 鑴氭湰 | 鍐呭 |
+|------|------|
+| `sql/mysql/system_agent_import_session_20261022.sql` | `system_agent_import_session` 琛ュ綍浼氳瘽 |
+| `sql/mysql/mdm_agent_import_command_20261022.sql` | `mdm_agent_import_command`銆乣mdm_agent_import_command_row` |
+| `docs/sql/config_export_all_20261022.sql` | 鍚堝苟鍒濆鍖栬剼鏈紝闃舵涓�琛ㄦ暟 416 鈫� 419锛堟柊澧炰笂杩� 3 寮犺〃锛� |
+
+浠ヤ笂鑴氭湰宸插湪鏈湴瀹瑰櫒 `mysql8` 鐨� `ruoyi-vue-pro` 鎵ц骞跺洖璇婚獙璇併��
+
+## 宸茬煡闄愬埗
+
+- 鍙柊寤虹墿鏂欙紝涓嶆洿鏂板凡鏈夌墿鏂欙紱缂栫爜宸插瓨鍦ㄦ椂棰勬 `SKIP`銆佹彁浜ゆ椂璺宠繃銆�
+- 涓嶅悓姝� MES锛涜姹� `sync_mes=true` 鐩存帴闃绘柇銆�
+- `mdm_item.code` 鏃犲敮涓�绱㈠紩锛屽苟鍙戝啓鍏ョ獥鍙ｄ緷璧栧懡浠ゅ箓绛夐敭涓庢彁浜ゅ墠閲嶆煡锛涢潪妗ユ帴骞跺彂鍐欏叆浠嶅彲鑳介噸澶嶃��
+- 鍚屼竴浼氳瘽閲嶅缁戝畾闄勪欢浼氭浛鎹㈡棫闄勪欢锛屾棫 `attachmentId` 澶辨晥銆�
+- 鎻愪氦涓哄悓姝ヨ姹傦紙寤鸿鍓嶇瓒呮椂 120 绉掞級锛岃秴鏃跺悗搴旀煡璇㈠懡浠ゅ洖鎵э紝涓嶈閲嶈瘯鎻愪氦銆�
+- `@PreAuthorize` 鍏滃簳鎷掔粷杩斿洖 HTTP 200 + body 403锛孭ython 渚у凡鍏煎瑙ｆ瀽锛涙ˉ鎺ヤ笟鍔″紓甯歌繑鍥炵湡瀹炵姸鎬佺爜銆�
+
+## 鍓嶇鑱旇皟锛�2026-10-22锛�
+
+| 椤� | 鍐呭 |
+|------|------|
+| 渚濊禆浠ｇ悊 | `vite.config.ts` 鏂板 `/agent-api` 鈫� `127.0.0.1:8091`锛堝幓鍓嶇紑锛� |
+| API 瀹㈡埛绔� | `src/api/mdm/item/agent.ts`锛岀嫭绔� `RequestClient`锛坆ody 妯″紡銆�120 绉掕秴鏃躲�佽嚜鍔ㄥ甫鐢ㄦ埛 token锛� |
+| 瀵煎叆寮圭獥 | `src/views/basicData/mdm/modules/agent-import.vue`锛屼笁姝ワ細涓婁紶 鈫� 瀹℃牳淇/纭 鈫� 鍥炴墽 |
+| 鍏ュ彛 | 鐗╂枡鍒楄〃宸ュ叿鏍忋�屾櫤鑳戒綋瀵煎叆銆嶏紝鏉冮檺 `mdm:item:import`锛屽彈 AI 鎬诲紑鍏虫帶鍒� |
+| 鏍￠獙 | `pnpm typecheck` 瀵规湰杞敼鍔ㄦ枃浠舵棤鏂板閿欒锛坄mdm/index.vue` Switch 鐨� `CheckedType` 涓烘棦鏈夐棶棰橈級 |
+
+### AI 鎬诲紑鍏�
+
+- `.env` 鏂板 `VITE_APP_AI_ENABLE`锛沗@vben/hooks` 鎻愪緵 `isAiEnable()`銆�
+- 鍏抽棴鍚庨殣钘忥細`/ai` 闈欐�佽矾鐢便�佺墿鏂欍�屾櫤鑳戒綋瀵煎叆銆嶃�丆RM 鎶ヤ环涓� ERP 鏉ョエ銆岃瘑鍒綍鍏ャ�嶃�佸伐鍗曞洓绫� AI 棰勬祴銆佽川妫� AI 鍒ゅ畾銆佽川妫�鍔╂墜銆�
+- 鏈疄闄呭惎鍔ㄦ祻瑙堝櫒楠岃瘉锛氭湰鍦� Java锛�48080锛変笌 Python锛�8091锛夊潎鏈繍琛岋紝鐧诲綍渚濊禆鍚庣锛涘惎鍔ㄤ袱绔悗鎸夎仈璋冩柟妗堝娴嬨��
+
+## 鍚庣画鍙�変簨椤�
+
+- 澧炲姞骞跺彂鎻愪氦鍘嬫祴涓� `mdm_item.code` 鍞竴鎬ф柟妗堣瘎浼般��
+- 璇勪及銆屾洿鏂板凡鏈夌墿鏂欍�嶇殑涓撶敤瀵煎叆鏂规硶锛堢姝㈠鐢ㄤ細鍒犻櫎 MES 鐗╂枡鐨� `updateItem`锛夈��
+- 鍚姩 Java/Python 鍚庢寜 `docs/agent_material_import_integration.md` 鍋氫竴娆℃祻瑙堝櫒绔埌绔娴嬨��
diff --git a/docs/ai_model_capability_integration.md b/docs/ai_model_capability_integration.md
new file mode 100644
index 0000000..167f500
--- /dev/null
+++ b/docs/ai_model_capability_integration.md
@@ -0,0 +1,107 @@
+# AI 妯″瀷绠＄悊 - 鍚敤涓庡垎绫昏仈璋冩柟妗�
+
+## 娑夊強椤甸潰
+
+- AI 澶фā鍨� 鈫� 妯″瀷绠＄悊锛坄ai/model/model/index`锛�
+- 渚濊禆妯″瀷涓嬫媺鐨勪笟鍔￠〉闈紙瀵硅瘽銆佸浘鍍忋�佺煡璇嗗簱銆佸伐浣滄祦锛�
+
+## 涓氬姟娴佺▼涓庢暟鎹甫鍏�
+
+1. 妯″瀷绠＄悊鍒楄〃鎸夈�屾ā鍨嬬被鍨嬨�嶅垎缁勫睍绀猴細鍚屼竴绫诲瀷鐨勫琛屽湪绫诲瀷鍒楃旱鍚戝悎骞舵垚涓�鏍笺��
+2. 姣忚鐘舵�佸垪鏀逛负銆屽惎鐢ㄣ�嶅紑鍏筹紝鐩存帴鍒囨崲璇ユā鍨嬬殑鍚敤/鍋滅敤銆�
+3. 鍚敤鏌愪釜妯″瀷鏃讹紝鍚庣鑷姩鍏抽棴**鍚岀被鍨� + 鍚岃兘鍔�**涓嬪凡鍚敤鐨勫叾浠栨ā鍨嬶紝鍓嶇鍙渶鏁撮〉鍒锋柊銆�
+4. 鍋滅敤妯″瀷涓嶄細鑷姩鍚敤鍏朵粬妯″瀷锛岃绫诲瀷璇ヨ兘鍔涘彲鑳藉洜姝ゆ病鏈夊彲鐢ㄦā鍨嬨��
+
+## API
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| PUT | `/ai/model/update-status` | 鏇存柊妯″瀷鍚敤鐘舵�侊紙鏈鏂板锛� |
+| GET | `/ai/model/page` | 妯″瀷鍒嗛〉锛屾柊澧� `capability` 鏌ヨ鍙傛暟 |
+| GET | `/ai/model/simple-list` | 妯″瀷涓嬫媺锛屾柊澧� `capability` 鏌ヨ鍙傛暟 |
+
+**璇锋眰鍙傛暟锛坲pdate-status锛夛細**
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| id | Long | 鏄� | 妯″瀷缂栧彿 |
+| status | Integer | 鏄� | 0-鍚敤锛�1-鍋滅敤 |
+
+**璇锋眰鍙傛暟锛坧age锛夛細**
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| pageNo | Integer | 鏄� | 椤电爜 |
+| pageSize | Integer | 鏄� | 姣忛〉鏉℃暟 |
+| name | String | 鍚� | 妯″瀷鍚嶅瓧锛屾ā绯婂尮閰� |
+| model | String | 鍚� | 妯″瀷鏍囪瘑锛屾ā绯婂尮閰� |
+| type | Integer | 鍚� | 妯″瀷绫诲瀷 |
+| capability | String | 鍚� | 妯″瀷鑳藉姏锛歵ext-鏂囨湰锛寁ision-瑙嗚 |
+| platform | String | 鍚� | 骞冲彴 |
+| status | Integer | 鍚� | 鐘舵�� |
+
+**鍝嶅簲瀛楁鏂板锛坧age / get / simple-list锛夛細**
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| capability | String | 妯″瀷鑳藉姏锛歵ext-鏂囨湰锛寁ision-瑙嗚 |
+
+**鍝嶅簲绀轰緥锛�**
+
+```json
+{
+  "code": 0,
+  "data": {
+    "list": [
+      {
+        "id": 2,
+        "name": "閫氫箟鍗冮棶瀵硅瘽妯″瀷",
+        "model": "qwen-max",
+        "platform": "TongYi",
+        "type": 1,
+        "capability": "text",
+        "status": 0
+      },
+      {
+        "id": 4,
+        "name": "閫氫箟鍗冮棶瑙嗚妯″瀷",
+        "model": "qwen-vl-plus",
+        "platform": "TongYi",
+        "type": 1,
+        "capability": "vision",
+        "status": 0
+      }
+    ],
+    "total": 4
+  }
+}
+```
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| 妯″瀷绫诲瀷 | 鍒楄〃棣栧垪 | 鍚岀被鍨嬪琛岀旱鍚戝悎骞讹紝褰㈡垚鍒嗙被鍒嗙粍 |
+| 妯″瀷鑳藉姏 | 鍒楄〃銆佽〃鍗� | 鏂囨湰/瑙嗚锛涗粎瀵硅瘽绫诲瀷闇�瑕佸尯鍒� |
+| 鍚敤 | 鍒楄〃鐘舵�佸垪 | 寮�鍏虫帶浠讹紝鍒囨崲鍗宠皟鐢� update-status |
+| 妯″瀷鏍囪瘑 | 鎼滅储琛ㄥ崟 | 鏀寔妯＄硦鎼滅储 |
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 鍚敤妯″瀷 | 鑷姩鍏抽棴鍚� `type + capability` 鐨勫叾浠栧惎鐢ㄦā鍨嬶紝淇濊瘉姣忕粍鍙湁涓�涓惎鐢� |
+| 鍋滅敤妯″瀷 | 鍙叧闂嚜韬紝涓嶈嚜鍔ㄥ惎鐢ㄥ叾浠栨ā鍨� |
+| 鏂板缓妯″瀷 | 鑻ョ姸鎬佷负鍚敤锛屽悓鏍蜂細鍏抽棴鍚岀粍鍏朵粬妯″瀷 |
+| 缂栬緫妯″瀷 | 妯″瀷绫诲瀷銆佽兘鍔涗笉鍙慨鏀癸紙鍓嶇宸茬鐢級锛涗粎鏂板缓鏃跺彲閫� |
+| 瀵硅瘽绫诲瀷 | 鏂囨湰鑳藉姏涓庤瑙夎兘鍔涘悇鍙惎鐢ㄤ竴涓紝浜掍笉瑕嗙洊 |
+| 闈炲璇濈被鍨� | 鑳藉姏鍥哄畾涓烘枃鏈紝姣忕粍鍙兘鍚敤涓�涓� |
+| 鍥剧墖璇嗗埆 | 鍙娇鐢ㄨ瑙夎兘鍔涚殑鍚敤妯″瀷锛屾湭鍚敤鏃舵帴鍙ｇ洿鎺ユ姤閿欐彁绀哄幓鍚敤 |
+
+## 娉ㄦ剰浜嬮」
+
+- 妯″瀷绫诲瀷銆佽兘鍔涘湪缂栬緫鏃朵笉鍙慨鏀广�傝嫢瑕佹敼鍙樻ā鍨嬪綊绫伙紝闇�鍒犻櫎鍚庨噸鏂板垱寤恒��
+- 鍚敤寮�鍏冲垏鎹㈠悗蹇呴』鏁撮〉鍒锋柊锛屽洜涓哄悓缁勫叾浠栬鐨勭姸鎬佸凡琚悗绔敼鍐欍��
+- 鍥剧墖璇嗗埆锛堝彂绁ㄣ�佹姤浠峰崟銆佽川妫�鎶ュ憡锛変緷璧栬瑙夎兘鍔涙ā鍨嬶紱濡傛灉鍋滅敤浜嗗敮涓�鐨勮瑙夋ā鍨嬶紝杩欎簺鍔熻兘浼氭姤閿欏苟鎻愮ず鍘诲惎鐢ㄣ��
+- 鑳藉姏瀛楁鍦ㄥ巻鍙叉暟鎹笂鐢卞悗绔寜妯″瀷鏍囪瘑鑷姩鍒ゅ畾锛堝惈 `vl` 鐨勫璇濇ā鍨嬪綊涓鸿瑙夛級锛屽墠绔棤闇�杩佺Щ銆�
+- 闈炲璇濈被鍨嬩笉闇�瑕佸睍绀鸿兘鍔涘瓧娈碉紝鎻愪氦鏃跺彲涓嶄紶锛屽悗绔粯璁ゆ寜 `text` 澶勭悊銆�
diff --git a/docs/industrial-agent-authorization-design.md b/docs/industrial-agent-authorization-design.md
new file mode 100644
index 0000000..04ed42f
--- /dev/null
+++ b/docs/industrial-agent-authorization-design.md
@@ -0,0 +1,110 @@
+# 宸ヤ笟鏅鸿兘浣撴巿鏉冭璁★細鑿滃崟銆佹寜閽笌鏁版嵁鑼冨洿
+
+> 2026-10-21锛岃璁＄銆傞�傜敤浜庤繍钀ュ満鏅�佸伐浣滄枃浠惰ˉ褰曘�佸畾鏃朵换鍔°�佸鎵规仮澶嶅拰缁撴灉瀵煎嚭銆傛ā鍨嬩緷鎹湇鍔＄鎻愪緵鐨勫彲鐢ㄨ兘鍔涜鍒掍换鍔★紱鏈�缁堟巿鏉冪敱 Java 鏈嶅姟绔墽琛屻��
+
+## 1. 鎺堟潈鍘熷垯涓庨」鐩緷鎹�
+
+鐢ㄦ埛閫氳繃鏅鸿兘浣撹闂笟鍔℃椂锛屾嫢鏈夌殑鑳藉姏涓嶅緱瓒呰繃鍏堕�氳繃姝ｅ父涓氬姟绯荤粺鑾峰噯浣跨敤鐨勮兘鍔涖�傚伐鍏锋巿鏉冪患鍚堝垽鏂ā鍧�/鑿滃崟鎺堟潈銆佹搷浣滄潈闄愮爜銆佸璞℃暟鎹寖鍥淬�佸瓧娈电瓥鐣ャ�佷笟鍔＄姸鎬佸拰鍔ㄤ綔瀹℃壒瑕佹眰銆備换鎰忎竴椤逛笉婊¤冻锛岀姝㈢浉搴旇皟鐢ㄣ��
+
+宸叉牳瀵圭殑浠ｇ爜鍩虹锛�
+
+- `AuthController.getPermissionInfo()` 鑾峰彇褰撳墠鐢ㄦ埛銆佸惎鐢ㄨ鑹插拰杩囨护绂佺敤椤瑰悗鐨勮彍鍗曞垪琛ㄣ��
+- `PermissionServiceImpl.hasAnyPermissions()` 涓� `getDeptDataPermission()` 鎻愪緵鍔熻兘鏉冮檺涓庨儴闂ㄨ寖鍥村熀纭�鑳藉姏銆�
+- 涓氬姟 Controller 浣跨敤 `@PreAuthorize` 妫�鏌ユ潈闄愮爜锛屼緥濡傚悎鍚岀殑 `crm:contract:query/create/update/delete/import/export`銆�
+- 鏁版嵁鏉冮檺妗嗘灦鍦ㄦ煡璇晶搴旂敤瑙勫垯锛汣RM 杩樻湁 `CrmPermissionAspect` 鐨勫璞＄骇鏉冮檺涓庡叕娴风瓑棰嗗煙瑙勫垯锛涘敭鍚庢湁鐙珛 `AfterSalePermissionService`銆�
+
+杩欎簺瑙勫垯缁勫悎鏂瑰紡鐢辩幇鏈� Java 鏉冮檺鏈嶅姟鍜屼笟鍔℃湇鍔″喅瀹氾紝Python 涓嶈嚜琛岀敤瑙掕壊鍚嶇О鎴栭儴闂� ID 鎺ㄧ畻鈥滃簲璇ユ湁鏉冮檺鈥濄�備笂闈㈢殑浠ｇ爜鏍稿涓嶄唬琛ㄦ瘡涓ā鍧楀潎宸插畬鎴愭暟鎹潈闄愬璁★紝鎺ュ叆鍓嶉渶楠岃瘉鍒楄〃銆佽鎯呫�佽仛鍚堜笌鍐欏叆鐨勪竴鑷存�с��
+
+## 2. 鑿滃崟銆佹寜閽�佹暟鎹笌瀛楁鐨勫叧绯�
+
+| 灞傛 | 浣滅敤 | Agent 鐨勮涓� |
+| --- | --- | --- |
+| 鑿滃崟/妯″潡鎺堟潈 | 鐢ㄦ埛鑾峰噯杩涘叆鐨勪笟鍔″煙 | 鏈嶅姟绔兘鍔涚洰褰曞叧鑱� menu_id/module锛涙棤鎺堟潈涓嶅紑鏀捐鍩熷伐鍏� |
+| 鎸夐挳/鎿嶄綔鏉冮檺 | 鏌ヨ銆佹柊澧炪�佷慨鏀广�佸垹闄ゃ�佸鍏ャ�佸鍑恒�佹彁浜ょ瓑 | 绮剧‘鏄犲皠宸ュ叿鍒版墍闇�鏉冮檺琛ㄨ揪寮忥紝涓嶇敤鈥滄湁鑿滃崟鈥濅唬鏇挎搷浣滄潈闄� |
+| 鏁版嵁鑼冨洿 | 鏈汉銆侀儴闂ㄣ�佷笅绾ч儴闂ㄣ�佽嚜瀹氫箟鍙婇鍩熷璞℃巿鏉� | 鏌ヨ鏃跺湪鏈嶅姟绔害鏉燂紱缁欏畾 ID 涔熻瀵硅薄鏍￠獙锛屼笉鑳藉彧杩囨护鍒楄〃 |
+| 瀛楁鏉冮檺 | 鎴愭湰銆佸簳浠枫�佽柂閰�佽处鍙枫�佽仈绯绘柟寮忕瓑鏁忔劅瀛楁 | 鍦ㄦ暟鎹繘鍏ユā鍨嬩箣鍓嶈繃婊わ紱鑻ョ幇鏈夌郴缁熸湭缁熶竴鎻愪緵锛屾柊澧炲瓧娈电瓥鐣� |
+| 鐘舵��/瀹℃壒 | 宸插叧闂�佸鎵逛腑銆佸凡鎵ц绛変笟鍔￠檺鍒� | 鏈夋寜閽潈闄愪粛闇�鏍￠獙鐘舵�侊紱瀹℃壒璧勬牸涓庢墽琛岃祫鏍煎垎鍒牳楠� |
+
+鑿滃崟鐨勫墠绔殣钘忓睘鎬с�侀〉闈㈣矾鐢卞彲瑙佹�у拰鏈嶅姟绔巿鏉冧笉鍚屻�傞殣钘忚鎯呴〉涓嶅簲涓�寰嬭涓烘湭鎺堟潈锛涗互鏈嶅姟绔疄闄呮巿鏉冨叧绯诲拰鑳藉姏鏄犲皠涓哄噯銆傝彍鍗曟巿鏉冧笉瀹屾暣銆佹棤瀵瑰簲鑿滃崟鐨勮法妯″潡鏈嶅姟鑳藉姏锛屽繀椤绘樉寮忕櫥璁帮紝涓嶈兘浠庡墠绔紶鏉ョ殑鑿滃崟鏍戝垽鏂��
+
+澶氳鑹茬殑鍔熻兘鏉冮檺涓庢暟鎹寖鍥村悎骞舵部鐢ㄧ幇鏈夌郴缁熻涔夛紱涓嶈兘瀵瑰叏閮ㄨ鑹茬畝鍗曟眰浜ら泦瀵艰嚧璇嫆锛屼篃涓嶈兘鎶婁笉鍚屼笟鍔″璞′笂鐨勬巿鏉冮殢鎰忔眰骞跺鑷存墿澶ц寖鍥淬�侫gent 鍔ㄤ綔绛栫暐鍙互鏀剁揣涓氬姟鏉冮檺锛屼笉寰楀皢鍏舵斁瀹姐��
+
+## 3. 鏈嶅姟绔兘鍔涚洰褰曚笌 LangGraph 璺緞
+
+鎷熸柊澧� Java `AgentAuthorizationService`锛氱敓鎴愯兘鍔涚洰褰曪紝鎵ц宸ュ叿/瀵硅薄/瀛楁鍒ゅ畾锛屽苟璁板綍鎺堟潈鍐崇瓥銆傛嫙鎻愪緵 `capabilities` 鍜� `check-action` 鍐呴儴鎺ュ彛锛涘墠鑰呯敤浜庤鍒掞紝鍚庤�呭強涓氬姟鏈嶅姟鐢ㄤ簬瀹為檯璋冪敤銆�
+
+```text
+楠岃瘉褰撳墠鐢ㄦ埛/鍙楁帶濮旀墭
+鈫� Java 璁＄畻鍙敤鑳藉姏涓� policy_revision
+鈫� LangGraph 鍙粦瀹氬綋鍓嶅満鏅殑宸叉巿鏉冨伐鍏�
+鈫� 妯″瀷鎻愬嚭缁撴瀯鍖栬鍒�
+鈫� 浠ｇ爜妫�鏌ヨ鍒掑伐鍏蜂笌鍙傛暟鑼冨洿
+鈫� Java 姣忔閲嶆柊閴存潈骞舵墽琛屽甫鑼冨洿鐨勪笟鍔℃煡璇�/鍛戒护
+鈫� 杩囨护瀛楁鍚庝氦缁欐ā鍨�
+鈫� 缁撴灉鏌ョ湅銆侀檮浠朵笅杞姐�佸鍑轰笌鍙戦�佹椂鍐嶆妫�鏌�
+```
+
+鑳藉姏鐩綍绀烘剰锛�
+
+```json
+{
+  "policy_revision": "server-generated-version",
+  "capabilities": [{
+    "tool": "crm.contract.read",
+    "module": "crm",
+    "operation": "query",
+    "scope_summary": "浠呭綋鍓嶇敤鎴峰彲瑙佸悎鍚�",
+    "allowed_fields": ["code", "customer_name", "delivery_date"],
+    "can_execute": true
+  }]
+}
+```
+
+鐩綍鏄煭鏈熻鍒掓彁绀猴紝涓嶆槸鍙暱鏈熶娇鐢ㄧ殑鎺堟潈鍑瘉銆傛湇鍔＄淇濆瓨鐪熷疄鏉冮檺琛ㄨ揪寮忎笌鏁版嵁瑙勫垯锛屼笉蹇呮妸瀹屾暣瑙掕壊閰嶇疆銆佸彲璁块棶 ID 鍒楄〃鎴栧唴閮� SQL 鍙戠粰妯″瀷銆傚瓧娈电櫧鍚嶅崟鎸夊叿浣撳璞′笌鐢ㄦ埛绛栫暐杩涗竴姝ユ敹绱с��
+
+LangGraph 鍦ㄥ叆鍙ｅ鍔� `load_capabilities`锛屽湪璁″垝鍚庡鍔� `authorize_plan`锛屽伐鍏峰皝瑁呯粺涓� `authorize_and_invoke`銆傛潈闄愪笉瓒宠蛋 `access_limited` 鍒嗘敮锛屽悜鐢ㄦ埛璇存槑鍙墽琛岄儴鍒嗗拰缂哄皯鐨勬搷浣滄潈闄愶紝涓嶆硠闇叉棤鏉冨璞＄殑鍚嶇О銆佹暟閲忔垨鍐呭銆�
+
+## 4. Java Bridge 鐨勫己鍒舵鏌�
+
+Bridge 鐩存帴璋冪敤 Service 鏃讹紝鍘� Controller 涓婄殑 `@PreAuthorize` 涓嶄細鍥犳鑷姩鎵ц锛屽繀椤绘樉寮忔鏌ュ搴斿姛鑳芥潈闄愶紱瀵硅薄瑙勫垯涔熷繀椤荤粡杩囧疄闄呯敓鏁堢殑 Service/AOP/鏌ヨ璺緞銆備笉寰椾负璺ㄦā鍧楁柟渚夸娇鐢ㄥ叏灞�绠＄悊鍛樿韩浠姐�乣executeIgnore` 鎴栧叧闂暟鎹繃婊ゆ潵浠ｆ煡銆�
+
+婧愯韩浠界敱 Java 閴村埆骞剁鍙戠煭鏃跺鎵樹笂涓嬫枃锛屽寘鍚敤鎴枫�佺鎴枫�乤udience銆佹湁鏁堟湡涓庡厑璁哥敤閫斻�傚伐鍏峰弬鏁颁腑鐨� user_id/dept_id/owner_id 涓嶅叿鏈夋巿鏉冩晥鍔涖�傚悗鍙扮嚎绋嬫墽琛屾椂寤虹珛姝ｇ‘鐨勬湇鍔＄韬唤涓婁笅鏂囧苟鍦ㄧ粨鏉熸椂娓呯悊锛岄槻姝㈢嚎绋嬪鐢ㄤ覆韬唤銆�
+
+鏌ヨ銆佽鎯呫�佸叧鑱旀煡璇€�佽仛鍚堛�佹悳绱㈠缓璁�佹枃浠舵绱㈤兘瑕佹墽琛岀浉鍚岃寖鍥磋鍒欙紱绂佹鈥滃厛鏌ュ叏閲忥紝妯″瀷鍐嶇瓫閫夆�濄�傛洿鏂�/鍒犻櫎闄や簡鏉冮檺鐮侊紝杩樻牎楠岀洰鏍囧璞★紱鏂板鏍￠獙鍙寚瀹氱殑閮ㄩ棬銆佽礋璐ｄ汉銆佷粨搴撱�佸鎴风瓑鍏宠仈瀵硅薄锛屼笉鑳藉�熸柊澧炴妸鏁版嵁鎸傚埌鏃犳潈閮ㄩ棬銆�
+
+## 5. 璺ㄦā鍧楀垎鏋愪笌杈撳嚭鎺у埗
+
+渚嬪閿�鍞湁鍚堝悓鏌ヨ鏉冮檺浣嗘病鏈夐噰璐环鏍兼潈闄愶細鍙互鍦ㄥ凡鎺堟潈鑼冨洿鍐呭垎鏋愬悎鍚岋紱涓嶈兘鎶婇噰璐崟鏄庣粏鍜屼环鏍兼彁渚涚粰妯″瀷銆傚鏋滀紒涓氬笇鏈涢攢鍞簡瑙ｄ氦浠樿兘鍔涳紝鏂板缁忚繃鎺堟潈鐨勨�滀氦鏈熻瘎浼版憳瑕佲�濊兘鍔涳紝鐢辨湇鍔＄闄愬埗杈撳嚭瀛楁鍜屾潵婧愯寖鍥达紝鑰岄潪鑷姩缁ф壙閲囪喘鏄庣粏鏉冮檺銆�
+
+璺ㄦā鍧椾换鍔￠�愯妭鐐规巿鏉冿紝蹇呴渶鏁版嵁鏃犳潈闄愭椂鏍囨敞鈥滃綋鍓嶆巿鏉冭寖鍥翠笉瓒充互瀹屾垚璇勪及鈥濓紝涓嶅緱鎶婁笉鍙閮ㄥ垎褰撲綔涓嶅瓨鍦ㄦ垨 0銆傜粨鏋滄敞鏄庘�滃綋鍓嶅彲瑙佽寖鍥粹�濓紝涓嶅緱瀹ｇО鏄叏浼佷笟缁熻銆傝嫢鎻愪緵璺ㄨ寖鍥存眹鎬伙紝闇�鏈夌嫭绔嬭仛鍚堟巿鏉冨強杈撳嚭绛栫暐锛屼笉鑳藉�熸眹鎬绘帹鏂殣钘忓鎴锋垨鏁忔劅閲戦銆�
+
+鏉冮檺杩囨护鍚屾牱瑕嗙洊璇佹嵁閾炬帴銆佸紩鐢ㄦ爣棰樸�侀檮浠堕瑙堛�丼SE銆佹姤鍛婁笅杞姐�佸垎浜笌閫氱煡銆傚鍑洪渶瑕佸搴斿鍑烘巿鏉冿紱鏌ヨ鏉冮檺涓嶈嚜鍔ㄥ寘鍚鍑烘潈闄愩�傚彂閫佺粨鏋滃悓鏃舵鏌ュ彂璧蜂汉鍙戦�佹潈闄愬強鎺ユ敹浜虹殑鍙鑼冨洿銆傚師濮嬫潵婧愮殑鏉冮檺涓嶄細鍥犱负鍋氭垚鎽樿鑰屾秷澶便��
+
+## 6. 鏂囦欢琛ュ綍鐨勬潈闄愯鍒�
+
+涓婁紶鏉冮檺銆佹煡鐪嬫枃浠舵潈闄愩�佸尮閰嶇郴缁熸暟鎹潈闄愩�佸缓绔嬩富鏁版嵁鏉冮檺銆佸鍏ヤ笟鍔℃潈闄愬拰鏇存柊鏃㈡湁鏁版嵁鏉冮檺鍒嗗埆鍒ゆ柇銆傜敤鎴蜂笂浼犱簡鏂囦欢锛屼笉浠ｈ〃鑾峰噯鏌ヨ鏂囦欢涓彁鍙婄殑鎵�鏈夌郴缁熻褰曪紝涔熶笉浠ｈ〃鑾峰噯瀵煎叆鍏朵腑鍏ㄩ儴鏁版嵁銆�
+
+- 瀹炰綋鍖归厤鍙繑鍥炲彲瑙佸�欓�夛紱鍙戠幇鍏ㄥ眬鍞竴閿啿绐佷絾鐩爣涓嶅彲瑙佹椂锛岃繑鍥為�氱敤鍐茬獊鍜屽彈鎺у鐞嗗叆鍙ｏ紝涓嶉�忛湶鐩爣璁板綍淇℃伅銆�
+- 瀵煎叆鍔ㄤ綔閲囩敤缁忚繃璇勫鐨勬潈闄愮粍鍚堬細渚嬪闇�妯″潡瀵煎叆鏉冮檺鍙婄浉搴斿垱寤�/鏇存柊鑳藉姏锛屽叿浣撲笌鐜版湁瀵煎叆 Service 璇箟瀵归綈锛涗笉鑳芥搮鑷亣璁句竴涓� import 鏉冮檺娑电洊鍏ㄩ儴鎿嶄綔銆�
+- 鎵规涓湁鏉冨拰鏃犳潈璁板綍鍒嗗埆鏍囪瘑锛涙棤鏉冭闃绘柇鍏朵緷璧栭摼銆傛槑纭鎵硅鍒掑悗鎵嶅厑璁哥嫭绔嬫湁鏉冨垎缁勭户缁墽琛屻��
+- 琛ュ綍涓绘暟鎹己澶辨椂锛屾棤鏂板鏉冮檺鐨勭敤鎴峰彧鑳芥彁鍑虹敵璇锋垨鏆傚瓨鍊欓�夛紝涓嶈嚜鍔ㄦ柊寤哄鎴枫�佺墿鏂欍�佷粨搴撱��
+- 璐熻矗浜�/閮ㄩ棬褰掑睘銆佽縼绉诲巻鍙茬姸鎬併�佹湡鍒濅綑棰濈瓑娑夊強棰濆鏉冮檺锛岄�愬瓧娈�/鍔ㄤ綔鏍￠獙銆俤ry-run銆佹彁浜ゅ拰鍥炶閮介噸鏂版巿鏉冦��
+- 鍘熷鏂囦欢銆佸�欓�夈�侀棶棰樻竻鍗曘�佷汉宸ヤ慨璁㈠拰瀵煎叆鎶ュ憡璁炬壒娆� ACL锛涘崗浣滀汉鍛樼湅鍒扮殑鍐呭鎸夊叾鏉冮檺瑁佸壀锛屼笉鑳藉洜鍙備笌鎵规灏辫幏鍑嗘煡鐪嬫墍鏈夎柂閰垨鎴愭湰銆�
+
+## 7. 瀹℃壒鎭㈠銆佸畾鏃朵换鍔′笌鏉冮檺鍙樺寲
+
+瀹℃壒浜烘湁瀹℃壒鏉冿紝涓嶄唬琛ㄥ彂璧蜂汉鑷姩鑾峰緱鎵ц鏉冦�傞粯璁ゆ墽琛岃姹傚彂璧蜂汉鐨勫綋鍓嶆巿鏉冧粛鏈夋晥锛涘涓氬姟鍏佽鐢辩嫭绔嬫墽琛屼富浣撴帴绠★紝蹇呴』璁板綍鏄庣‘鐨勪富浣撳垏鎹€�佸鎵樿寖鍥村拰瀹℃壒渚濇嵁锛屼笉鑳介粯榛樹娇鐢ㄥ鎵逛汉鎴栫鐞嗗憳韬唤銆�
+
+瑙掕壊鎾ら攢銆佽处鍙风鐢ㄣ�佺鑱屼氦鎺ャ�佸璞″綊灞炲彉鍖栥�佽彍鍗曠鐢ㄦ椂锛屾洿鏂版巿鏉冪増鏈苟澶辨晥鑳藉姏缂撳瓨銆傛寕璧峰浘鎭㈠鏃堕噸鏂板姞杞芥潈闄愶紱鍑嗗濂界殑鏂规涓嶄繚鐣欐棫鎺堟潈銆傛墽琛屾椂浠嶆鏌ユ渶鏂版潈闄愶紝閬垮厤鍙緷璧栧け鏁堥�氱煡銆�
+
+涓汉瀹氭椂浠诲姟浣跨敤鏄庣‘鐨勫彈鎺у鎵橈紝鐢ㄦ埛鍋滅敤/鎾ゆ潈鍚庢殏鍋溿�備紒涓氬贰妫�浣跨敤涓撻棬鏈嶅姟涓讳綋鍜屾壒鍑嗙殑鏁版嵁鑼冨洿锛涘悜涓汉鎺ㄩ�佸墠鎸夋帴鏀朵汉鏉冮檺瑁佸壀銆備釜浜哄璇濅笉鍙�熶紒涓氬贰妫�涓讳綋鎵╁ぇ鏌ヨ鑼冨洿銆�
+
+缂撳瓨鎸夌鎴枫�佷富浣撱�佹潈闄愮増鏈�佸璞�/瀛楁鑼冨洿闅旂锛涙鏌ョ偣鍜屼骇鐗╀笉鐩存帴闈㈠悜鍓嶇銆傛潈闄愭敹绱у悗锛屽啀娆¤鍙栨棫缁撴灉銆佹仮澶嶄細璇濇垨閲嶅缓妯″瀷涓婁笅鏂囨椂閲嶆柊鎺堟潈锛屽繀瑕佹椂閬斀鎴栭噸鏂扮敓鎴愩�傚凡鍚戠敤鎴峰睍绀鸿繃鐨勪俊鎭棤娉曟挙鍥烇紝浣嗙郴缁熶笉鑳界户缁繑鍥炲凡鎾ゆ潈鍐呭銆�
+
+## 8. 瀹¤涓庨獙鏀�
+
+姣忔鎺堟潈鍐崇瓥璁板綍涓讳綋銆佸鎵樹富浣撱�乼ool/action銆佸璞″紩鐢ㄣ�佹潈闄愮増鏈�佸喅绛栥�佸師鍥犵爜銆乼ask_id銆乤pproval_id锛堥�傜敤鏃讹級銆傛嫆缁濇棩蹇楅伩鍏嶈褰曞畬鏁存晱鎰熷瓧娈点�傚墠绔師鍥犲尯鍒嗘棤鎿嶄綔鏉冮檺銆佹暟鎹寖鍥翠笉瓒炽�佺姸鎬佷笉鍏佽銆佸鎵圭己澶变笌鎺堟潈杩囨湡锛涗笉寰楁硠闇叉棤鏉冨璞″瓨鍦ㄦ�с��
+
+楠屾敹蹇呴』鍖呭惈锛氭湁鑿滃崟鏃犳煡璇㈡寜閽紱鍙煡涓嶅彲鏀癸紱鍙煡涓嶅彲瀵煎嚭锛涙湰浜烘暟鎹秺鐣岃鎯� ID锛涜法閮ㄩ棬鑱氬悎锛汣RM 鍙/璇诲啓/璐熻矗浜猴紱鍞悗瀵硅薄鏉冮檺锛涙柊澧炴椂鎸囧畾鏃犳潈璐熻矗浜猴紱瀵煎叆鍚棤鏉冨叧鑱斿璞★紱瀹℃壒绛夊緟涓挙鏉冿紱鏃ф鏌ョ偣涓庣紦瀛樻硠婕忥紱鏈嶅姟璐﹀彿宸℃缁撴灉鎺ㄩ�侊紱瀛楁鑴辨晱锛汢ridge 缁曡繃 Controller 鐨勯槻鎶ゃ��
+
+鏈涓烘柟妗堣ˉ鍏咃紝鏈敼鍙樼幇鏈夋潈闄愪唬鐮併�傚疄鏂芥椂閫愭ā鍧楃櫥璁扳�滆彍鍗曠粦瀹氥�佸伐鍏锋潈闄愯〃杈惧紡銆佸璞¤鍒欍�佸瓧娈电瓥鐣ャ�佺姸鎬佽鍒欍�佸鎵归棬妲涒�濓紝鏈櫥璁版垨鏍搁獙澶辫触鐨勮兘鍔涢粯璁ゅ叧闂��
diff --git a/docs/industrial-agent-document-onboarding-design.md b/docs/industrial-agent-document-onboarding-design.md
new file mode 100644
index 0000000..3e7d31b
--- /dev/null
+++ b/docs/industrial-agent-document-onboarding-design.md
@@ -0,0 +1,192 @@
+# 鏍稿績鑳藉姏锛氫紒涓氬伐浣滄枃浠剁悊瑙ｃ�佹牳瀵逛笌鏁版嵁琛ュ綍
+
+> 鎶�鏈柟妗� v1锛�2026-10-21銆備綔涓� LangGraph 骞冲彴鐨勭浜屾潯鏍稿績涓荤嚎锛屼笌涔濅釜杩愯惀鍦烘櫙骞跺垪銆傞潰鍚戜紒涓氬垵娆′笂绾垮強鏃ュ父澧為噺琛ュ綍锛涙湰杞粎璁捐锛屾湭澶勭悊鐪熷疄鏂囦欢鎴栧鍏ヤ笟鍔℃暟鎹��
+
+鎺堟潈瑙勫垯鍙傝 [缁熶竴鏉冮檺鏂规](industrial-agent-authorization-design.md)锛氫笂浼犮�佸疄浣撳尮閰嶃�佸垱寤恒�佹洿鏂般�佸鍏ャ�佸鍑哄垎鍒巿鏉冿紝鎵规涓殑姣忔潯璁板綍鍙婂叾鍏宠仈瀵硅薄閮介渶瑕侀獙璇佹暟鎹寖鍥淬��
+
+## 1. 鐩爣涓庝氦浠樼粨鏋�
+
+浼佷笟鍙寜鏂囦欢澶�/鎵规鎻愪氦鏃ュ父 WPS 宸ヤ綔鏂囦欢锛岀郴缁熻瘑鍒叾涓殑瀹㈡埛銆佷緵搴斿晢銆佺墿鏂欍�佽澶囥�佸悎鍚屻�佽鍗曘�佸簱瀛樸�佹姤宸ャ�佽川妫�绛夊唴瀹癸紝缁忚繃澶氳疆妫�鏌ヤ笌浜哄憳琛ュ厖锛屽舰鎴愬彲棰勮銆佸彲杩芥函銆佸彲鎭㈠鐨勫鍏ユ柟妗堛��
+
+姣忔瀵煎叆浜や粯浜旈」浜х墿锛氬師濮嬫枃浠舵竻鍗曚笌鐗堟湰鍏崇郴銆佸瓧娈垫槧灏勫拰鏉ユ簮璇佹嵁銆佸緟琛ュ厖/鍐茬獊娓呭崟銆佸甫渚濊禆椤哄簭鐨勫叆搴撹鍒掋�侀�愰」鎵ц涓庢牳瀵规姤鍛娿�傛枃浠跺唴瀹瑰瓨鍦ㄤ笉纭畾鎬ф椂淇濈暀鍘熷�煎拰鍊欓�夊�硷紱鏈‘璁ょ殑鍘嗗彶浜嬪疄涓嶈兘閫氳繃妯″瀷鎺ㄦ祴琛ラ綈銆�
+
+## 2. 鏂囦欢鑼冨洿涓庤В鏋愮瓥鐣�
+
+| 鏂囦欢绫诲瀷 | 瑙ｆ瀽鐩爣 | 闄嶇骇鎴栭檺鍒� |
+| --- | --- | --- |
+| WPS 缂栬緫鐨� xlsx/xls/csv | 宸ヤ綔琛ㄣ�佸尯鍩熴�佽〃澶淬�佸崟鍏冩牸銆佸叕寮忎笌鍙敤缂撳瓨鍊笺�佸娉ㄣ�侀殣钘忚鍒� | 缂撳瓨缂哄け/澶栭摼鏂紑鏍囦负寰呮牳瀹烇紱涓嶅緱鎶婄┖缂撳瓨褰� 0 |
+| WPS 缂栬緫鐨� docx/doc | 娈佃惤銆佽〃鏍笺�侀〉鐪夐〉鑴氥�佹壒娉�/淇銆佸唴宓屽浘鐗� | 鍘嗗彶浜岃繘鍒舵牸寮忛�氳繃鍙楁敮鎸佽浆鎹㈤�傞厤鍣ㄥ鐞嗗苟鏍稿鍓嶅悗鍐呭 |
+| pptx/ppt 鍙婃眹鎶ユ潗鏂� | 琛ㄦ牸銆佹枃鏈�佸浘绀轰腑鐨勬寚鏍囧拰瀵硅薄绾跨储 | 姹囨�绘寚鏍囦笉榛樿鎷嗘垚鏄庣粏浜ゆ槗锛涚己灏戝師濮嬪彴璐︽椂鍙綊妗ｆ垨鐢熸垚鏍稿疄浠诲姟 |
+| PDF銆佹壂鎻忎欢銆佺収鐗� | 鏂囨湰灞備紭鍏堬紝鎵弿鍖哄煙 OCR锛岄〉鐮�/鍧愭爣鍙婄増闈㈣瘉鎹� | 灏忔暟鐐广�佽礋鍙枫�佺紪鐮併�佺绔犲拰璺ㄩ〉琛ㄦ牸杩涘叆閲嶇偣澶嶆牳 |
+| WPS 鍘熺敓 et/wps/dps | 鏂囦欢璇嗗埆銆佽浆鎹㈠悗鎸夋爣鍑嗘牸寮忓鐞� | 涓嶆壙璇烘墍鏈夌増鏈棤鎹燂紱杞崲澶辫触杩涘叆寰呭鐞嗭紝鍙姹傚彟瀛樻爣鍑嗘牸寮� |
+| 鏂囦欢澶广�佸帇缂╁寘 | 淇濈暀璺緞銆佹枃浠堕棿寮曠敤鍜岀浉瀵瑰叧绯伙紝閫愭枃浠惰В鏋� | 闄愬埗瑙ｅ帇鏁伴噺/娣卞害/澶у皬锛涘紓甯告枃浠堕殧绂伙紝涓嶉樆濉炴棤渚濊禆鏂囦欢 |
+
+瑙ｆ瀽閲囩敤鈥滄牸寮忕粨鏋勮В鏋� 鈫� 鐗堥潰/鍖哄煙璇嗗埆 鈫� 灞�閮� OCR 鈫� 璇箟鏄犲皠鈥濄�傚叿浣撹В鏋�/杞崲缁勪欢閫氳繃鐪熷疄鏍锋湰鍏煎娴嬭瘯鍚庨�夊瀷锛屼笉鍦ㄨ璁￠樁娈靛绉板凡鍏煎鎵�鏈� WPS 鐗堟湰銆傝浆鎹㈡湇鍔＄嫭绔嬮殧绂伙紝绂佹鑷姩鎵ц瀹忋�佽剼鏈垨澶栭儴鏁版嵁杩炴帴銆�
+
+淇濈暀鍘熷鏂囦欢涓嶅彲鍙樺壇鏈�佹枃浠� hash銆佸師鏍煎紡銆佽В鏋愬櫒鐗堟湰鍙婅浆鎹骇鐗┿�傛枃浠跺瘑鐮佺敱瀹夊叏杈撳叆娴佺▼澶勭悊锛屼笉鍐欒繘瀵硅瘽銆佹鏌ョ偣鎴栨棩蹇椼�傚け璐ュ師鍥犲繀椤诲叿浣撳埌鈥滃姞瀵嗏�濃�滄崯鍧忊�濃�滄牸寮忎笉鏀寔鈥濃�淥CR 涓嶇‘瀹氣�濈瓑銆�
+
+## 3. 琛ュ綍瀵硅薄涓庤竟鐣�
+
+| 鏁版嵁灞� | 瀵瑰簲椤圭洰 | 澶勭悊瑕佹眰 |
+| --- | --- | --- |
+| 鍩虹涓绘暟鎹� | MDM 鐗╂枡/SKU銆佸垎绫汇�佸崟浣嶃�佷粨搴擄紱CRM 瀹㈡埛鑱旂郴浜猴紱SRM 渚涘簲鍟嗭紱璁惧/鐝粍 | 浼樺厛鍖归厤鐜版湁璁板綍锛屽啀鎻愬嚭鏂板锛涘埆鍚嶄笌姝ｅ紡鍚嶇О鍒嗗埆绠＄悊 |
+| 涓氬姟缁撴瀯 | BOM銆佸伐鑹鸿矾绾裤�佹楠屾爣鍑嗐�佸鎴蜂骇鍝佸鐓� | 淇濆瓨閫傜敤鑼冨洿銆佺敓鏁堢増鏈�佹暟閲忓崟浣嶏紱楠岃瘉寰幆渚濊禆涓庢浛浠ｅ叧绯� |
+| 杩涜涓崟鎹� | 鍚堝悓銆侀噰璐�/閿�鍞崟銆丮PS/宸ュ崟銆佸緟鏀跺緟鍙戙�佹湭缁撳敭鍚� | 瀵煎叆鍓╀綑璐ｄ换銆佸凡鎵ц閲忎笌鏉ユ簮锛涗笉閲嶆柊鎵ц宸插彂鐢熺殑鍙戣揣/浠樻 |
+| 鍘嗗彶浜嬪疄 | 鎶ュ伐銆佹楠屻�佺淮淇�佹敹鍙戣揣銆佸巻鍙插洖娆� | 浣跨敤涓撻棬鍘嗗彶杩佺Щ璇箟鍜岀湡瀹炰笟鍔℃棩鏈燂紝淇濆瓨琛ュ綍鏃堕棿涓庢搷浣滆�� |
+| 鏈熷垵鐘舵�� | 搴撳瓨銆佸簲鏀跺簲浠樸�佸湪鍒躲�佹湭缁撴暟閲� | 浠ュ垏鎹㈡椂鐐圭粺涓�瀵硅处锛屾寜涓氬姟璁ゅ彲鐨勬湡鍒濇帴鍙ｅ叆璐� |
+| 鏂囨。鐭ヨ瘑 | SOP銆佸浘绾搞�佺邯瑕併�佸埗搴︺�佹姤鍛� | 杩涘叆闄勪欢/鐭ヨ瘑搴擄紱涓嶅洜鏂囨。瀛樺湪灏辫櫄鏋勪氦鏄撴垨瀹℃壒璁板綍 |
+
+浠ヤ笂鏄洰鏍囪寖鍥达紝涓嶈〃绀虹幇鏈夐」鐩凡缁忔彁渚涙墍鏈夊巻鍙茶縼绉绘帴鍙ｃ�傛瘡绫诲璞￠�氳繃鑳藉姏鐧昏杩斿洖鈥滃彲瀵煎叆 / 浠呰崏绋� / 浠呭綊妗� / 闇�鏂板涓氬姟鎺ュ彛鈥濄�侶R 钖叕銆佷釜浜鸿瘉浠剁瓑瀛楁浠呭悜鎺堟潈宀椾綅寮�鏀撅紝鏄犲皠鍜岄瑙堝悓鏍峰彈鏁版嵁鏉冮檺鎺у埗銆�
+
+## 4. LangGraph 鍥捐璁�
+
+鍦ㄤ富璺敱鏂板 `document_onboarding`锛屼笟鍔℃浠朵互 `import_batch_id` 涓烘牳蹇冿紝瀛愪换鍔℃寜鏂囦欢/鍖哄煙瑙ｆ瀽锛岄殢鍚庡湪鎵规灞傜粺涓�娑堟鍜屾牳瀵广��
+
+```mermaid
+flowchart TD
+    A[寤虹珛瀵煎叆鎵规涓庤縼绉昏寖鍥碷 --> B[鏂囦欢娓呭崟 / 鍘婚噸 / 鐗堟湰璇嗗埆]
+    B --> C[骞惰瑙ｆ瀽鏂囦欢涓庤〃鏍煎尯鍩焆
+    C --> D[璇嗗埆涓氬姟绫诲瀷涓庡瓧娈垫槧灏刔
+    D --> E[瑙勮寖鍖栧�欓�夎褰曚笌瀛楁璇佹嵁]
+    E --> F[涓绘暟鎹尮閰� / 璺ㄦ枃浠跺叧鑱擼
+    F --> G[缁撴瀯 / 涓氬姟 / 鏁伴噺閲戦 / 鏃跺簭鏍￠獙]
+    G --> H{瀛樺湪闃绘柇闂锛焳
+    H -->|鏄瘄 I[鑱氬悎鍚岀被闂涓庡缓璁甝
+    I --> J[interrupt 绛夊緟纭 / 琛ユ枃浠� / 鏀瑰�糫
+    J --> K[搴旂敤淇锛屾爣璁板彈褰卞搷渚濊禆澶辨晥]
+    K --> F
+    H -->|鍚 L[鐢熸垚渚濊禆 DAG 涓� Java dry-run]
+    L --> M[鍐荤粨鏂规鐗堟湰銆佸奖鍝嶉瑙堜笌瀹℃壒]
+    M --> N[interrupt 绛夊緟鎺堟潈鎵ц]
+    N --> O[閲嶆柊鏍搁獙鏉冮檺 / 鏂规 hash / 鐩爣鐗堟湰]
+    O -->|鍙樺寲| F
+    O -->|鏈夋晥| P[鎸変笟鍔¤仛鍚堝垎鎵瑰箓绛夊鍏
+    P --> Q[鍥炶 / 瀵硅处 / 瀹屾暣鎬ч獙璇乚
+    Q --> R{閫氳繃锛焳
+    R -->|鍚 S[鏆傚仠鐩稿叧閾撅紝淇鎴栦笟鍔¤ˉ鍋縘
+    R -->|鏄瘄 T[褰掓。鎶ュ憡 / 鍏抽棴鎵规]
+```
+
+瑙ｆ瀽瀛愬浘鎸夋枃浠剁嫭绔嬭繍琛岋紝鍙苟琛岋紱鍖归厤銆佸幓閲嶅拰渚涘簲/閲戦姹囨�诲湪鎵规鑼冨洿瀹屾垚銆傚鎵瑰拰鍏ュ簱闆嗕腑鍦ㄥ懡浠ゆ墽琛屽浘锛岃В鏋愯妭鐐逛笉鐩存帴鍐欎笟鍔℃暟鎹�傚ぇ鏂囦欢鎸夌ǔ瀹氬垎鍖哄鐞嗭紝璁板綍鍒嗗尯杩涘害锛涙鏌ョ偣淇濆瓨寮曠敤锛屼笉淇濆瓨鏁存湰琛ㄦ牸鎴栧浘鐗囥��
+
+闂鍙嶉鍙Е鍙戝彈褰卞搷鐨勮褰曘�佹牎楠屽櫒鍜屼笅娓镐緷璧栭噸鏂拌繍琛屻�傚彉鏇村崟浣嶆槧灏勮閲嶇畻鐩稿叧鏁伴噺涓庨噾棰濓紱鍙樻洿瀹㈡埛褰掑睘瑕侀噸鍋氭潈闄愬拰鍏宠仈妫�鏌ワ紱涓婁紶鏂版枃浠惰鍒ゆ柇鏄ˉ鍏呰瘉鎹繕鏄浛浠ｇ増鏈�傝凯浠ｈ疆鏁版湁棰勭畻锛屾湭瑙ｅ喅浜嬮」杞汉宸ュ鐞嗭紱涓嶈兘涓轰簡缁撴潫寰幆鑷姩鎶婅鍛婃敼鎴愰�氳繃銆�
+
+## 5. 澶氳疆妫�鏌ョ殑鍏蜂綋鍒嗗伐
+
+| 杞 | 妫�鏌ュ唴瀹� | 浜х墿 / 璋佽礋璐� |
+| --- | --- | --- |
+| 绗竴杞細璇绘噦鏂囦欢 | 鏂囦欢绫诲瀷銆佸涓〃鏍煎尯鍩熴�佽〃澶村眰绾с�佹眹鎬�/鏄庣粏鍖恒�佸崟浣嶄笌鏈熼棿 | 瑙ｆ瀽缁撴瀯鍥俱�佹棤娉曡瘑鍒尯鍩燂紱瑙ｆ瀽鍣� + 妯″瀷杈呭姪 |
+| 绗簩杞細瀵归綈瀵硅薄 | 瀛楁涓庝笟鍔″璞℃槧灏勩�佸鎴�/渚涘簲鍟�/鐗╂枡鍊欓�夈�佸崟鎹垎缁� | 鏄犲皠鑽夌銆佸疄浣撳�欓�夈�侀渶瑕佺‘璁ょ殑绠�绉� |
+| 绗笁杞細浜ゅ弶鏍稿 | 澶氭枃浠剁増鏈啿绐併�佽鍗曚笌鍙戣揣/鍥炴鍏宠仈銆佽灏忚涓庢�昏銆佸簱瀛�/鏈熷垵鍏崇郴 | 瑙勫垯鍖栧樊寮傛姤鍛婏紱纭畾鎬ц绠楀櫒 |
+| 绗洓杞細涓氬姟鏍搁獙 | 蹇呭～銆佺姸鎬佹満銆佸崟浣嶆崲绠椼�佸鎵硅姹傘�佹暟鎹寖鍥淬�佺洰鏍囪褰曞啿绐� | Java dry-run 鐨勯�愯褰曠粨鏋滀笌鍓綔鐢ㄦ竻鍗� |
+| 绗簲杞細浜哄伐琛ュ厖 | 缂哄皯鐨勮矗浠讳汉/浠撳簱/绋庣巼銆佹涔夊尮閰嶃�佸巻鍙叉棩鏈熴�侀噰鐢ㄧ増鏈� | 甯︿汉鍛樸�佹椂闂淬�侀�傜敤鑼冨洿鐨勫喅绛栬ˉ涓� |
+| 绗叚杞細鎻愪氦鍓嶅鏌� | 鏂规 hash銆佺洰鏍囩増鏈�佷緷璧栭綈澶囥�佹�婚噺/閲戦涓庨噸澶嶈褰� | 鍙墽琛屾柟妗堜笌闃绘柇椤癸紱纭鍚庢墽琛� |
+| 绗竷杞細鍏ュ簱鍚庢牳瀵� | 閫愯褰曞洖璇汇�佹�婚噺閲戦銆佸叧鑱斿畬鏁淬�佹剰澶栧壇浣滅敤 | 鎴愬姛/澶辫触/缁撴灉鏈煡/鏈皾璇曞垎椤规姤鍛� |
+
+妯″瀷澶嶆牳鍙互鎻愬嚭閬楁紡鎴栧啿绐侊紝浣嗕笉鑳芥浛浠ｆ暟閲忛噾棰濇牳绠椾笌 Java 涓氬姟鏍￠獙銆傚鏍镐互鐙珛瑙勫垯銆佹簮鏂囦欢璇佹嵁鍜屼汉宸ュ喅绛栦负渚濇嵁锛涘娆℃ā鍨嬬粰鍑虹浉鍚岀瓟妗堜笉浠ｈ〃閫氳繃銆�
+
+## 6. 瀛楁绾ц瘉鎹笌鏆傚瓨妯″瀷
+
+姣忎釜鍊欓�夊瓧娈典繚瀛� `raw_value`銆乣normalized_value`銆佺被鍨嬨�佹潵婧愬畾浣嶃�佸彉鎹㈣鍒欍�佹彁鍙栧彲闈犲害銆佸尮閰嶄緷鎹笌纭鐘舵�併�傝〃鏍煎畾浣嶄负鏂囦欢鐗堟湰/宸ヤ綔琛�/鍗曞厓鏍兼垨鍖哄煙锛涙枃妗ｅ畾浣嶄负椤电爜/娈佃惤/琛ㄦ牸锛涙壂鎻忎欢淇濆瓨椤电爜/妗嗗潗鏍囥�傛帓搴忔垨閲嶈В鏋愬悗浠嶄繚鐣欏師濮嬪畾浣嶃��
+
+鍊欓�夎褰曟湁绋冲畾 `candidate_id`锛屼笌涓氬姟 ID 鍒嗗紑锛涘師濮嬭銆佷笟鍔″崟鎹ご銆佸崟鎹閲囩敤鏄惧紡鍒嗙粍鍏崇郴銆備竴涓簮琛屽彲瀵瑰簲澶氭潯涓氬姟璁板綍锛屽涓簮琛屼篃鍙粍鎴愪竴寮犲崟鎹紝姣忔鎷嗗垎/鍚堝苟淇濈暀杞崲閾俱��
+
+鏂板鏆傚瓨琛細
+
+- `import_batch`锛氬鍏ユā寮忋�佸垏鎹㈡椂鐐广�佽寖鍥淬�佽礋璐ｄ汉銆佸綋鍓� revision 涓庣姸鎬併��
+- `import_file_version / import_region`锛氭枃浠惰缂樸�乭ash銆佺増鏈叧绯汇�佽В鏋愬尯鍩熶笌缂撳瓨銆�
+- `import_candidate / import_field_evidence`锛氬�欓�夊璞°�佸瓧娈点�佹潵婧愪笌鍙樻崲杩囩▼銆�
+- `import_entity_match`锛氱郴缁熷�欓�夈�佸尮閰嶇壒寰併�佸喅绛栦笌鍒悕閫傜敤鑼冨洿銆�
+- `import_issue / import_resolution`锛氶棶棰樼被鍨嬨�侀樆鏂骇鍒�佸奖鍝嶅璞°�佷汉宸ヨˉ涓佷笌澶辨晥鐘舵�併��
+- `import_plan / import_plan_item / import_dependency`锛氫笉鍙彉鏂规銆佺洰鏍囩増鏈�佷緷璧� DAG銆�
+- `import_execution / import_record_link`锛氬箓绛夐敭銆佷笟鍔� ID銆佹簮鍒扮洰鏍囨槧灏勩�佸洖璇荤粨鏋溿��
+
+鍊欓�夎褰曠姸鎬佷负 `寰呰В鏋� 鈫� 寰呭尮閰� 鈫� 寰呰ˉ鍏� 鈫� 鍙牎楠� 鈫� 鍙彁浜� 鈫� 宸叉彁浜� 鈫� 宸叉牳瀹瀈锛屽彟鏈� `璺宠繃 / 鍐茬獊 / 澶辫触 / 缁撴灉鏈煡`銆傛枃浠惰В鏋愭垚鍔熶笉绛変簬鍊欓�夎褰曞彲鎻愪氦銆傜晫闈㈠垎鍒粺璁℃枃浠舵暟銆佹簮琛屾暟銆佸�欓�夊璞℃暟銆佷笟鍔″崟鎹暟鍜屾槑缁嗚鏁帮紝閬垮厤涓嶅悓璁℃暟娣峰湪涓�璧枫��
+
+## 7. 澶嶆潅鎯呭喌澶勭悊娓呭崟
+
+| 鎯呭喌 | 璇嗗埆涓庡鐞嗚鍒� |
+| --- | --- |
+| 鍚堝苟琛ㄥご銆佹棤鏍囬琛ㄣ�佹í鍚戞湀浠姐�佸琛ㄥ悓椤点�佽法椤电画琛� | 鍒嗗尯鍩熻瘑鍒紱淇濈暀灞傜骇锛涢噸澶嶉〉鐪変笌鍚堣涓嶅綋浣滄槑缁嗭紱鍏堝睍绀烘槧灏勬牱鏈� |
+| 鍚堝苟鍗曞厓鏍艰〃绀衡�滃悓涓娾�濄�佺┖鐧借〃绀烘湭鐭ユ垨 0 | 浠呭湪纭鐨勫尯鍩熻鍒欏唴鍚戜笅濉厖锛涙湭鐭ャ�佺┖銆�0 鍒嗗埆缂栫爜 |
+| 闅愯棌琛屽垪銆佺瓫閫夎銆佸娉ㄣ�佸垹闄ょ嚎銆佷慨璁� | 鎻愮ず瀛樺湪骞剁‘瀹氱撼鍏ユ斂绛栵紱涓嶈兘榛樿闅愯棌椤逛綔搴熸垨榛樿淇宸叉帴鍙� |
+| 鍏紡缂撳瓨鏃с�佸閾炬柇寮�銆佹墜濉悎璁′笉绛変簬琛屽悎璁� | 鍚屾椂淇濈暀鍏紡/鏄剧ず鍊�/鐙珛鏍哥畻鍊硷紱鍐茬獊闃绘柇鐩稿叧閲戦鏁伴噺鎻愪氦 |
+| 缂栫爜鍓嶅 0銆侀暱缂栧彿绉戝璁℃暟娉曘�佹棩鏈熷簭鍒椼�佸崈鍒嗕綅 | 鍘熷绫诲瀷浼樺厛锛涚紪鍙锋寜鏂囨湰锛涗笉鍙仮澶嶇殑绮惧害鎹熷け瑕佹眰鍘熶欢鏍稿疄 |
+| 鏃ユ湡缂哄勾銆佹湀/鏃ユ涔夈�佸啘鍘嗐�佽嚜鐒惰瑷�鏃ユ湡 | 浣跨敤宸茬‘璁ょ殑鏂囦欢鏈熼棿瑙ｉ噴锛涗笉鑳界敤涓婁紶鏃ユ湡鐚滃巻鍙蹭笟鍔℃棩鏈� |
+| 鍚屽悕涓嶅悓瀹㈡埛銆佸鎴风畝绉般�佷緵搴斿晢鏇剧敤鍚� | 澶氱壒寰佸尮閰嶃�佹樉绀哄�欓�夎瘉鎹紱涓嶈法浼佷笟/閮ㄩ棬鏉冮檺鑼冨洿鑷姩鍚堝苟 |
+| 鍚屽悕鐗╂枡涓嶅悓瑙勬牸銆佸鎴锋枡鍙蜂笌鍐呴儴鏂欏彿銆佸崟浣嶄笉鍚� | 瑙勬牸/鍨嬪彿/SKU/鍗曚綅涓�璧峰尮閰嶏紱瀹㈡埛鏂欏彿鏄犲皠鎸夊鎴烽殧绂伙紱鎹㈢畻闇�纭 |
+| 鍚屾枃浠堕噸澶嶄笂浼犮�佹敼鍚嶄笂浼犮�佹敼涓�鏍煎啀浼� | hash 闃叉枃浠剁骇閲嶅锛涗笟鍔￠敭/鍐呭鎸囩汗闃茶褰曢噸澶嶏紱淇敼鐗堣繘琛岄�愬瓧娈� diff |
+| 鈥滄渶缁堢増鈥濃�滄渶缁堢増2鈥濅笌鏃ユ湡/鍐呭鐭涚浘 | 寤虹珛鐗堟湰鍏崇郴锛岀敤鎴风‘璁ゆ潈濞佹潵婧愶紱涓嶆寜鏂囦欢鍚嶆垨淇敼鏃堕棿鑷姩瑕嗙洊 |
+| 姹囨�昏〃涓庢槑缁嗚〃銆佸璐﹀崟涓庡彂璐у崟閲嶅鎻忚堪鍚屼竴浜ゆ槗 | 鍖哄垎浜嬪疄鏉ユ簮涓庢牳瀵规潵婧愶紱鍙缓涓�娆′氦鏄擄紝姹囨�荤敤浜庢帶鍒舵�婚 |
+| 涓�鍗曞娆″彂璐с�佸绗斿洖娆炬姷澶氬崟銆佸悎骞跺紑绁ㄣ�侀��琛ヨ揣 | 寤虹珛鍒嗛厤鍏崇郴鍙婃湭鍒嗛厤浣欓锛涙病鏈夎瘉鎹椂涓嶉殢鎰忓钩鍧囧垎鎽� |
+| 绋庣巼/鍚◣浠�/鎶樻墸/杩愯垂/甯佺鍙ｅ緞涓嶅悓 | 鏄庣‘鍑�浠�/绋庨/鍚◣棰濄�佽垗鍏ヤ綅鏁颁笌姹囩巼鏃ユ湡锛涗娇鐢� Decimal 鏍哥畻 |
+| 閲囪喘涓庨攢鍞�佸鍗忓彂鏂欎笌鎴愬搧鍥炴敹鏁伴噺涓嶇瓑 | 鎸変笟鍔＄被鍨嬨�丅OM/璁￠噺鎹㈢畻鍜屽悎鍚屽厑璁告崯鑰楁牎楠岋紱涓嶄互鏁伴噺涓嶅悓鐩存帴鍒ら敊 |
+| 鎵规/SN 缂哄け銆佸簱瀛樺彧鏈夋�绘暟銆佷粨搴撳埆鍚� | 鍙舰鎴愬緟鍒嗛厤鏈熷垵鑽夌锛涗笉鍙紪閫犳壒娆�/SN銆佸簱浣嶆垨渚涘簲鍟嗗綊灞� |
+| 鏃х郴缁熷凡鎵瑰噯/宸叉敮浠�/宸插彂璐э紝褰撳墠绯荤粺鏃犳祦绋� | 淇濆瓨鍘嗗彶鐘舵�佹潵婧愶紱璧拌縼绉绘帴鍙ｏ紝涓嶄吉閫犲鎵逛汉鎴栭噸鏀惧疄鏃朵笟鍔″姩浣� |
+| 鍘熻〃閬楁紡璐熸暟銆佺孩瀛楀啿閿�銆佸彇娑堝崟/浣滃簾鍗� | 淇濈暀绗﹀彿涓庡啿閿�鍏崇郴锛涗笉鍙粺涓�鍙栫粷瀵瑰�兼垨鍏ㄩ儴鎸夋湁鏁堝崟瀵煎叆 |
+| OCR 灏� 0/O銆�1/I銆�8/B銆佸皬鏁扮偣/璐熷彿娣锋穯 | 鐢ㄧ紪鐮佸瓧鍏搞�佺畻鏈笌鍘熷浘浜ゅ弶楠岃瘉锛涘叧閿瓧娈典笉纭畾鍒欎汉宸ュ鏍� |
+| 閮ㄥ垎鏂囦欢鎹熷潖/鍔犲瘑/缂洪檮浠� | 缁欏嚭鍙楀奖鍝嶅璞★紱鏃犱緷璧栧垎鏀彲缁х画锛屼緷璧栧垎鏀繚鎸侀樆鏂� |
+| 瀵煎叆鏈熼棿绯荤粺琚叾瀹冧汉淇敼 | 鐩爣鐗堟湰/鍐呭 hash 涔愯鏍￠獙锛屽啿绐佸洖鍒伴瑙堬紝宸插鎵规棫鏂规澶辨晥 |
+| 澶ф枃浠躲�佸鏂囦欢銆佸鐢ㄦ埛鍚屾椂鏀规槧灏� | 鍒嗗尯瑙ｆ瀽銆佹壒娆� revision 涔愯閿併�佸奖鍝嶈寖鍥撮噸绠楋紱淇濈暀淇敼璁板綍 |
+| 鏂囦欢鍐呭鍖呭惈鎸囦护銆佸畯銆佸閮ㄩ摼鎺� | 浣滀负寰呰В鏋愭暟鎹紝涓嶆敼鍙樺伐鍏锋潈闄愶紱涓嶈嚜鍔ㄦ墽琛屽畯鎴栬闂閾� |
+
+涓嶅瓨鍦ㄥ彲闈犲尮閰嶇殑瀹炰綋鍙彁璁柊寤猴紝浣嗛粯璁も�滃緟鏂板纭鈥濓紝涓嶆槸鑷姩鍒堕�犵墿鏂欐垨瀹㈡埛銆傜己澶辨硶瀹�/璐㈠姟/杩芥函鍏抽敭瀛楁鏃堕樆鏂浉鍏冲璞★紱闈炲繀濉瓧娈靛彲淇濈暀绌哄苟鍒楀叆琛ュ厖娓呭崟锛屼笉鑳藉鍏モ�滈粯璁ゅ鎴封�濃�滈粯璁や粨搴撯�濇帺鐩栭棶棰樸��
+
+## 8. 浜哄伐琛ュ厖涓庡杞氦浜�
+
+瀵煎叆宸ヤ綔鍙伴噰鐢ㄢ�滄簮鏂囦欢璇佹嵁鈥斿�欓�変笟鍔℃暟鎹�旈棶棰樹笌澶勭悊鈥濅笁鏍忋�傞�夋嫨鏌愬瓧娈垫椂瀹氫綅鍘熻〃鍗曞厓鏍兼垨鍘熸枃鍖哄煙锛涙壒閲忛�夋嫨鍚岀被闂鍚庡彲涓�娆＄‘璁ゆ槧灏勶紝渚嬪鈥滆繖浜涙枃浠堕噷鐨勨�樹欢鈥欏潎鏄犲皠鎴愮郴缁熷崟浣� PCS鈥濄�傜‘璁ゅ繀椤婚檺瀹氭枃浠�/鍖哄煙/鐗╂枡绫诲埆绛夎寖鍥达紝涓嶈兘鏃犳潯浠舵墿鏁ｅ埌鍏ㄤ紒涓氥��
+
+鎻愰棶鎸夊奖鍝嶉潰浼樺厛锛氬厛纭瀵煎叆妯″紡銆佹湡闂淬�佷富浣撱�佹潈濞佹枃浠讹紝鍐嶈В鍐冲奖鍝嶅ぇ閲忚褰曠殑鍗曚綅/瀹炰綋鏄犲皠锛屾渶鍚庡鐞嗕釜鍒己澶便�傜敤鎴峰彲琛ユ枃浠躲�佷慨姝ｅ瓧娈点�侀�夋嫨鍊欓�夈�佹殏缂撱�佽烦杩囨垨瑕佹眰浜哄伐澶勭悊銆傛壒閲忓簲鐢ㄥ墠鏄剧ず褰卞搷鏁伴噺鍜岀ず渚嬶紝搴旂敤鍚庨噸璺戠浉鍏虫鏌ャ��
+
+姣忔鍥炵瓟鎴愪负鐗堟湰鍖� `ResolutionPatch`锛屽寘鍚洰鏍囧瓧娈�/闂銆佸師鍊笺�佹柊鍊笺�佷緷鎹�佹搷浣滆�呫�佹椂闂淬�佷綔鐢ㄨ寖鍥翠笌鍩虹嚎 revision銆傞棶棰樺彲浠ラ噸鏂版墦寮�锛涙柊璇佹嵁鎺ㄧ炕鏃у喅绛栨椂鏍囪鏃у喅绛栬繃鏈熴�傞噾棰濄�佹暟閲忋�佸巻鍙茬姸鎬佺瓑蹇呴』鑳借В閲婇噰鐢ㄥ摢涓潵婧愩��
+
+## 9. 鍓嶆湡涓婄嚎琛ュ綍锛氬垏鎹㈡椂鐐逛笌闃叉閲嶅璁拌处
+
+鎵规蹇呴』閫夋嫨妯″紡锛氣憼涓绘暟鎹垵濮嬪寲锛涒憽鍘嗗彶璧勬枡褰掓。锛涒憿鏈粨涓氬姟杩佺Щ锛涒懀鏈熷垵浣欓/搴撳瓨锛涒懁鏃ュ父鏂板/淇銆備笉鍚屾ā寮忔湁涓嶅悓鍏佽鍔ㄤ綔鍜屾帴鍙ｏ紝涓嶅叡鐢ㄤ竴涓�滃叏閲忓鍏モ�濆紑鍏炽��
+
+鍏堢‘瀹氬垏鎹㈡椂鐐� T銆佺粍缁�/浠撳簱鑼冨洿銆佷笟鍔℃湡闂淬�佹潈濞佸彴璐﹀拰鎺у埗鎬婚銆俆 涔嬪墠鐨勭疮璁″巻鍙蹭笌 T 鏃剁偣浣欓閲囩敤鏄庣‘杩佺Щ绛栫暐锛氳嫢鍘嗗彶鏀跺彂鍙綔褰掓。锛屾湡鍒濆簱瀛樺叆璐︿竴娆★紱鑻ラ噸寤哄畬鏁翠氦鏄撻摼锛屽垯涓嶅緱鍐嶆妸鐩稿悓浣欓浣滀负棰濆搴撳瓨鍏ヨ处銆傚簲鏀跺簲浠樸�佸湪鍒朵笌鏈粨璁㈠崟鍚屾牱澶勭悊銆�
+
+渚嬪鍘嗗彶鍚堝悓宸茬敓鎴愯鍗曚笖宸插彂閮ㄥ垎璐э紝琛ュ綍鍚堝悓鏃朵笉鑳藉啀娆¤Е鍙戔�滃鎵归�氳繃鑷姩鐢熸垚閿�鍞鍗曗�濓紝涔熶笉鑳介噸璺戦攢鍞崟鐢熸垚 MPS銆佹姤宸ュ�掑啿銆佽川妫�鍥炶皟鍜岄�氱煡銆侸ava 闇�瑕佹槑纭殑杩佺Щ鍏ュ彛銆佽縼绉绘潈闄愪笌鍙楁帶鍓綔鐢ㄧ瓥鐣ワ紱涓嶆敮鎸佹椂浠呭鍏ヨ崏绋�/褰掓。骞舵爣璁板悗缁緟寤鸿锛屼笉缁曡繃鏈嶅姟鍐欏簱銆�
+
+涓氬姟鍙戠敓鏃堕棿銆佸師绯荤粺鍒涘缓/瀹℃壒鏃堕棿锛堟湁璇佹嵁鏃讹級銆佹湰娆¤ˉ褰曟椂闂村垎鍒繚瀛樸�傚巻鍙插鎵硅瘉鎹綔涓洪檮浠�/鏉ユ簮璁板綍锛屽綋鍓嶇郴缁熸搷浣滄棩蹇楄褰曠湡瀹炶ˉ褰曟搷浣滆�咃紝涓嶈兘鍐掑厖鍘嗗彶浜哄憳鎵ц瀹℃壒銆�
+
+## 10. Java 瀵煎叆鍗忚涓庢墽琛岄『搴�
+
+鐜版湁 `MdmItemController` 鐗╂枡瀵煎叆銆丆RM 鍚堝悓瀵煎叆銆丒RP 閲囪喘鐢宠/閲囪喘鍗曞鍏ュ彲浣滀负棰嗗煙鏍￠獙涓庢槧灏勫弬鑰冦�傚畠浠殑妯℃澘瀵煎叆璇箟涓嶇瓑浜庨�氱敤鍘嗗彶杩佺Щ璇箟锛涢�愰」瀹℃煡 Service 鐨勯粯璁ゅ�笺�佽嚜鍔ㄧ紪鍙枫�佹洿鏂扮瓥鐣ャ�佺姸鎬佹帹杩涗笌鑷姩鐢熸垚涓嬫父鍗曟嵁鍚庡啀澶嶇敤銆�
+
+鎷熷鍔犲唴閮ㄦ帴鍙ｏ細`capabilities` 杩斿洖鏀寔瀵硅薄/瀛楁/妯″紡/闄愬埗锛沗validate` 鍋氭棤鍓綔鐢ㄦ牎楠屽苟杩斿洖寮曠敤鍐茬獊涓庡壇浣滅敤棰勮锛沗plan` 鍐荤粨鎵ц璁″垝锛沗commit` 鎸夋柟妗堢増鏈笌鎺堟潈浠ょ墝鎵ц锛沗status` 鎸夊懡浠ゅ彿鏌ヨ锛沗reconcile` 鍥炶瀵硅处銆侺LM 浠呯敓鎴愬�欓�� DTO锛屼笉鑳界洿鎺ヨ皟鐢� `commit`銆�
+
+渚濊禆閫氬父涓哄崟浣�/鍒嗙被/浠撳簱 鈫� 瀹㈡埛/渚涘簲鍟�/鐗╂枡 鈫� 浜у搧 BOM/宸ヨ壓 鈫� 鍚堝悓/璁㈠崟 鈫� 宸ュ崟/鏀跺彂/璐ㄦ绛夛紝浣嗘渶缁堜互瀵硅薄渚濊禆 DAG 鍐冲畾锛岀幆渚濊禆鍗曠嫭鎷嗚В銆傛殏瀛樺�欓�夐�氳繃 `candidate_id` 寮曠敤锛屽叆搴撳悗鐢熸垚鍊欓�夊埌鐪熷疄 ID 鏄犲皠渚涗笅娓镐娇鐢ㄣ��
+
+浠ュ畬鏁翠笟鍔¤仛鍚堬紙鍗曟嵁澶�+鍏ㄩ儴琛岋級涓哄師瀛愯竟鐣岋紝涓嶉�愯鎻愪氦鍗婂紶鍗曟嵁銆傞粯璁や竴涓緷璧栫粍澶辫触鍒欓樆姝笅娓革紱鏃犱緷璧栫粍鍙�夋嫨缁х画锛屽苟鍦ㄥ鎵规柟妗堥噷鏄庣‘绛栫暐銆傚閮ㄦ帴鍙ｈ繑鍥炴垚鍔熷悗蹇呴』鍥炶楠岃瘉銆�
+
+璁板綍骞傜瓑閿敱浼佷笟/杩佺Щ鑼冨洿銆佺ǔ瀹氭簮璁板綍鏍囪瘑銆佺洰鏍囧璞°�佹柟妗堢増鏈拰鍔ㄤ綔缁勬垚锛涘彟璁捐法鎵规涓氬姟鍞竴閿�/鍐呭鎸囩汗鍐茬獊妫�娴嬶紝閬垮厤鏂板缓鎵规缁曡繃闃查噸銆傛簮璁板綍淇敼浣跨敤鏄惧紡鏇存柊绛栫暐涓庢湡鏈涚洰鏍囩増鏈紱涓嶈兘榛橀粯瑕嗙洊宸叉湁浜哄伐淇敼銆�
+
+鎻愪氦瓒呮椂鍏堟煡璇㈢粨鏋溿�傞儴鍒嗘垚鍔熷悗鍙ˉ澶辫触/鏈皾璇曢」锛涢噸璇曚笉閲嶆柊瀵煎叆鎴愬姛璁板綍銆傛挙閿�鎸変笟鍔¤兘鍔涙墽琛岋細鏈寮曠敤鐨勮崏绋垮彲浠ユ挙閿�锛涘凡鍙戠敓搴撳瓨/璧勯噾/涓嬫父寮曠敤鐨勮褰曡蛋鍐查攢鎴栧彈鎺ф洿姝ｏ紝涓嶈兘鎵胯鏁存壒纭垹闄ゅ洖婊氥��
+
+## 11. 瀵硅处銆侀獙鏀朵笌瀹炴柦浼樺厛绾�
+
+鎻愪氦鍓嶅悗鎺у埗鎬婚鑷冲皯鍖呮嫭瀵硅薄鏁般�佽鏁般�佺墿鏂欐暟閲忥紙鎸夊崟浣嶅垎缁勶級銆侀噾棰濓紙鎸夊竵绉嶄笌绋庡彛寰勫垎缁勶級銆佸簱瀛橈紙鎸変粨搴�/鐗╂枡/鎵规鍙ｅ緞锛夈�佸簲鏀跺簲浠�/鏈粨鏁伴噺锛屼互鍙婂紩鐢ㄥ畬鏁寸巼銆傝法鍗曚綅/甯佺涓嶈兘鐩存帴姹傛�诲拰銆傛姤鍛婃槑纭彲鏍稿銆佷笉鍙牳瀵广�佷汉宸ョ‘璁ゅ樊寮傚強鍘熷洜銆�
+
+鏍锋湰闆嗚鐩栵細鏍囧噯琛ㄣ�佸鏉傚悎骞惰〃銆佹壂鎻忎欢銆佽法鏂囦欢鍐茬獊銆佸悓鍚嶅疄浣撱�侀噸澶嶇増鏈�佸叕寮忛敊璇�佹棩鏈�/閲戦姝т箟銆佺己灏戞壒娆°�佸巻鍙插凡鎵ц鍗曟嵁銆佸悓鏃舵湡鍒濅笌鍘嗗彶浜ゆ槗銆佸苟鍙戜慨鏀广�佹墽琛屽悗鏂綉銆侀儴鍒嗗け璐ュ拰鏇存閲嶅銆傚叧閿簨瀹炰笉寰楃敱妯″瀷鍑┖琛ュ叏锛涢樆鏂棶棰樻湭瑙ｅ喅涓嶅緱鎻愪氦銆�
+
+浜や粯椤哄簭鎻愬崌涓猴細A 鍥捐繍琛屼笌鏆傚瓨/璇佹嵁搴曞骇锛汢 涓绘暟鎹枃浠惰ˉ褰曢棴鐜紱C 鍚堝悓/閲囪喘/閿�鍞瓑涓氬姟鑽夌涓庢湭缁撹縼绉伙紱D 鏈熷垵搴撳瓨鍙婂鏉傚巻鍙茶縼绉伙紱E 涓庤繍钀ヤ節鍦烘櫙鑱斿姩銆傚鏉傚巻鍙茶縼绉绘寜瀹為檯涓氬姟鎺ュ彛鎴愮啛搴﹀紑鏀撅紝涓嶈兘涓轰簡琛ュ綍閫熷害缁曡繃瀹℃壒鍜屽簱瀛樿鍒欍��
+
+涓婄嚎鍓嶉渶瑕佷紒涓氭彁渚涜劚鏁忕殑甯哥敤鏍锋湰涓庡搴旀纭粨鏋滐紝寤虹珛鏍煎紡鍏煎闆嗗拰涓氬姟鍩哄噯闆嗭紱褰撳墠鏂规涓嶈姹傚厛涓婁紶鏂囦欢鎵嶈兘缁х画鎶�鏈璁°�傛渶缁堥獙鏀剁湅瀛楁鍑嗙‘銆佸疄浣撳叧鑱斻�侀噸澶嶉槻鎶ゃ�佹帶鍒舵�婚銆佷汉宸ュ伐浣滈噺涓庢仮澶嶈兘鍔涳紝鍒嗗埆缁熻鑷姩纭涓庝汉宸ョ‘璁ょ粨鏋溿��
+
+## 12. Python 妯″潡澧為噺
+
+```text
+graphs/scenarios/document_onboarding.py
+graphs/documents/parse.py, resolve.py, review.py, import.py
+documents/adapters/       # 鏍煎紡瑙ｆ瀽銆佽浆鎹€�丱CR 鐨勫彲鏇挎崲鎺ュ彛
+documents/layout/         # 鍖哄煙銆佽〃澶淬�佸崟鎹垎缁勪笌鏉ユ簮瀹氫綅
+documents/normalization/  # 鏃ユ湡銆侀噾棰濄�佸崟浣嶃�佺紪鐮侊紝淇濈暀鍘熷鍊�
+documents/matching/       # 瀹炰綋鍖归厤銆佽法鏂囦欢鐗堟湰鍜屼笟鍔″叧鑱�
+documents/validation/     # 缁撴瀯銆佷笟鍔°�佺畻鏈�佽法鏂囦欢銆佽縼绉昏鍒�
+documents/staging/        # 鍊欓�夈�佽瘉鎹�侀棶棰樸�佷慨璁€�佹柟妗堢増鏈�
+documents/planning/       # 渚濊禆 DAG銆乨ry-run銆佸奖鍝嶉瑙�
+documents/reconciliation/ # 鍏ュ簱鍥炶銆佹帶鍒舵�婚銆佸紓甯告仮澶�
+```
+
+璇ヨ兘鍔涘叡浜富骞冲彴鐨勬潈闄愩�佹鏌ョ偣銆佸懡浠ゅ箓绛夈�佸鎵逛笌浜嬩欢绯荤粺锛屽苟鐙珛淇濆瓨鏂囦欢瑙ｆ瀽鍜屽�欓�夋暟鎹�傝繍钀ュ浘鍙湁鍦ㄧ浉搴旀暟鎹凡鏍稿疄鍏ュ簱鍚庯紝鎵嶆妸瀹冧綔涓哄疄鏃朵笟鍔′簨瀹炰娇鐢紱鏈‘璁ゅ�欓�変粎鐢ㄤ簬琛ュ綍宸ヤ綔鍙般��
diff --git a/docs/industrial-agent-langgraph-technical-design.md b/docs/industrial-agent-langgraph-technical-design.md
new file mode 100644
index 0000000..0d9623f
--- /dev/null
+++ b/docs/industrial-agent-langgraph-technical-design.md
@@ -0,0 +1,285 @@
+# MOM 宸ヤ笟鏅鸿兘浣擄細LangGraph 瀹氬埗鎶�鏈柟妗�
+
+> 璁捐鐗堟湰锛歷1锛�2026-10-21銆傞樁娈碉細鎶�鏈柟妗堣瘎瀹★紝灏氭湭瀹炴柦銆�
+> 涓氬姟鑼冨洿鎵挎帴 [鍏ㄦā鍧楄璁(industrial-agent-python-design.md) 涓� [涔濆満鏅摑鍥綸(industrial-agent-scenario-blueprint.md)銆傛湰鏂规纭畾浣跨敤 Python + LangGraph锛涘叿浣撲緷璧栫増鏈湪瀹炴柦鏃跺畬鎴愬吋瀹归獙璇佸悗鍐欏叆閿佹枃浠躲��
+
+鏂板骞跺垪鏍稿績鑳藉姏锛歔浼佷笟宸ヤ綔鏂囦欢鐞嗚В涓庡杞ˉ褰昡(industrial-agent-document-onboarding-design.md)銆傚崗璋冧富鍥惧鍔� `document_onboarding` 璺敱锛岃ˉ褰曟殏瀛樸�佸瓧娈佃瘉鎹�佸杞汉宸ヤ慨璁€�佷緷璧栧鍏ヤ笌瀵硅处浣滀负涓撶敤瀛愬浘銆傚疄鏂介『搴忚皟鏁翠负鍏堝畬鎴愪富鏁版嵁琛ュ綍闂幆锛屽啀閫愭鑱斿姩杩愯惀鍦烘櫙锛涙湡鍒濅笌鍘嗗彶杩佺Щ閲囩敤涓撻棬涓氬姟鎺ュ彛銆�
+
+缁熶竴鎺堟潈璇﹁ [鑿滃崟銆佹寜閽笌鏁版嵁鏉冮檺鏂规](industrial-agent-authorization-design.md)锛氫富鍥惧鍔犺兘鍔涘姞杞戒笌璁″垝鎺堟潈鑺傜偣锛屾墍鏈夋煡璇�/鎿嶄綔澶嶇敤 Java 褰撳墠鐢ㄦ埛鏉冮檺锛涙ā鍨嬪彲鐢ㄥ伐鍏枫�佸瓧娈点�佷骇鐗╀笌鎭㈠杩囩▼鍧囧彈绾︽潫銆�
+
+## 1. 鏍稿績鎶�鏈喅绛�
+
+閲囩敤鐙珛 Python 椤圭洰 `mom-industrial-agent`锛屼互 LangGraph `StateGraph` 缂栨帓涓氬姟娴佺▼銆傝璁′负**鍗忚皟涓诲浘 + 涔濅釜鍦烘櫙瀛愬浘 + 鍏ㄦā鍧楅鍩熷伐鍏� + 缁熶竴鍛戒护鎵ц閫氶亾**銆傛煡璇€�佽绠椼�佸缓璁笌鎵ц鏈夋槑纭妭鐐瑰拰鏁版嵁濂戠害銆�
+
+LLM 璐熻矗鑷劧璇█鎰忓浘銆佷笟鍔″璞℃秷姝с�佹枃妗ｈВ閲娿�佽瘉鎹�荤粨鍜屽�欓�夎鍔紱搴撳瓨鍙敤閲忋�侀噾棰濄�佸伐搴忕害鏉熴�佹楠岃鍒欍�佹潈闄愪笌瀹℃壒缁撹鐢辩‘瀹氭�т唬鐮佸強 Java 涓氬姟鏈嶅姟璐熻矗銆傛ā鍨嬭緭鍑哄繀椤荤粡杩囩粨鏋勬牎楠屽拰棰嗗煙绛栫暐鏍￠獙锛屾墠鑳芥垚涓哄伐鍏疯緭鍏ャ��
+
+涓诲浘閲囩敤鏄庣‘璺敱锛涘満鏅瓙鍥句互棰勫畾涔夋祦绋嬩负涓汇�備粎鍦ㄧ煡璇嗘绱㈡垨鍘熷洜鍒嗘瀽鑺傜偣涓厑璁告湁棰勭畻鐨勫姩鎬佸伐鍏峰惊鐜�傛鏋舵敮鎸佺敤鐘舵�併�佽妭鐐瑰拰杈硅〃杈捐繖绉嶆祦绋嬶紝鑺傜偣鍙互鎵ц鏅�氳绠楁垨妯″瀷璋冪敤銆俒LangGraph Graph API](https://docs.langchain.com/oss/python/langgraph/graph-api)
+
+## 2. 閮ㄧ讲涓庣郴缁熻亴璐�
+
+```mermaid
+flowchart TB
+    UI[鐜版湁 Vue / 绉诲姩绔痌 --> GW[Java Agent 缃戝叧锛氳韩浠戒笌鏁版嵁鑼冨洿]
+    GW --> API[Python FastAPI锛氫换鍔″叆鍙� / SSE]
+    API --> DB[(Agent PostgreSQL锛氫换鍔′笌妫�鏌ョ偣)]
+    API --> Q[Redis Streams锛氫换鍔″垎鍙慮
+    Q --> W[LangGraph Worker]
+    W --> GRAPH[鍗忚皟鍥句笌鍦烘櫙瀛愬浘]
+    GRAPH --> MODEL[妯″瀷閫傞厤灞俔
+    GRAPH --> KNOW[鐭ヨ瘑妫�绱㈤�傞厤灞俔
+    GRAPH --> BRIDGE[Java Agent Bridge锛氶鍩熸煡璇笌鍛戒护]
+    BRIDGE --> SVC[CRM / ERP / SRM / MES / HRM / BI / System]
+    BRIDGE --> BPM[鐜版湁 BPM 瀹℃壒]
+    SVC --> MYSQL[(鐜版湁涓氬姟 MySQL)]
+    SVC --> OUT[涓氬姟 Outbox]
+    BPM --> OUT
+    OUT --> EVENTS[浜嬩欢鎺ュ叆 / 鍘婚噸 / 璺敱]
+    EVENTS --> Q
+    GRAPH --> DB
+```
+
+| 缁勪欢 | 閫夊瀷涓庤矗浠� |
+| --- | --- |
+| Python API | FastAPI + Pydantic锛屾牎楠岃緭鍏ャ�佺櫥璁颁换鍔°�佽鍙栫粨鏋溿�佽緭鍑轰笟鍔′簨浠舵祦 |
+| 鍥捐繍琛� | LangGraph锛岃嚜瀹氫箟鐘舵�佷笌鑺傜偣锛涘紓姝ユā鍨嬪拰 HTTP 璋冪敤 |
+| 涓氬姟杩炴帴 | httpx 璁块棶 Java 鍐呴儴 Bridge锛涙湁闄愯繛鎺ユ睜銆佹槑纭秴鏃躲�佸彧璇婚噸璇� |
+| 妫�鏌ョ偣 | `langgraph-checkpoint-postgres` 鐨勫紓姝ユ寔涔呭寲瀹炵幇锛涘垵濮嬪寲/杩佺Щ鍦ㄥ彂甯冧换鍔℃墽琛� |
+| 浠诲姟璁板綍 | 鐙珛 PostgreSQL 淇濆瓨浠诲姟銆佹柟妗堛�佷簨浠躲�佹墽琛岃褰曪紱涓氬姟搴撶户缁娇鐢ㄧ幇鏈� MySQL |
+| 闃熷垪 | Redis Streams + consumer group锛汸ostgreSQL outbox 淇濊瘉鎻愪氦浠诲姟鍚庡彲琛ュ彂锛孯edis 涓嶄綔涓哄敮涓�浠诲姟浜嬪疄婧� |
+| 瀹氭椂瑙﹀彂 | 浼樺厛澶嶇敤椤圭洰鐜版湁 Quartz锛屽彂閫佸満鏅簨浠讹紱浼佷笟鐝/鑺傚亣鏃ラ厤缃喅瀹氭椂闂� |
+| 鏂囨。 | 澶嶇敤闄勪欢涓庣煡璇嗗簱锛涘ぇ鏂囦欢鍦ㄥ璞″瓨鍌紝妫�鏌ョ偣浠呭瓨寮曠敤涓庢憳瑕� |
+| 鍙娴� | 缁撴瀯鍖栨棩蹇椼�乼race_id銆佽妭鐐硅�楁椂銆佸伐鍏疯皟鐢ㄥ璁°�佹寚鏍囷紱澶栭儴杩借釜骞冲彴鎸夐儴缃茶姹傞�夐厤 |
+
+杩欎慨璁簡鏃╂湡鈥滃叏閮ㄦ部鐢� MySQL/Redis鈥濈殑寤鸿锛歀angGraph 鐢熶骇妫�鏌ョ偣浼樺厛閲囩敤瀹樻柟鏂囨。鍒楀嚭鐨� PostgreSQL 瀹炵幇锛屽噺灏戣嚜鐮旀鏌ョ偣閫傞厤宸ヤ綔锛涘紑鍙戝彲鐢� SQLite锛屽唴瀛樻鏌ョ偣浠呬緵鍗曞厓娴嬭瘯銆俒Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)
+
+API 涓� Worker 鍙嫭绔嬫墿瀹广�傚悓涓�涓笟鍔′换鍔″彧鍏佽涓�涓� Worker 鎸佹湁鎵ц绉熺害锛涚画绉熴�乫encing token 鍜屽懡浠ゅ箓绛夊叡鍚屽鐞嗚繘绋嬪け鑱斻�侾ython 鏈嶅姟鏃犻渶杩佺Щ Java 涓氬姟鏁版嵁锛屼篃涓嶆寔鏈変笟鍔℃暟鎹簱鍐欐潈闄愩��
+
+## 3. 涓诲浘璁捐
+
+```mermaid
+flowchart TD
+    START([璇锋眰 / 涓氬姟浜嬩欢]) --> AUTH[validate_context锛氭牳楠岃韩浠戒笌瀵硅薄鑼冨洿]
+    AUTH --> INTENT[resolve_request锛氱粨鏋勫寲鎰忓浘涓庡璞
+    INTENT --> CLEAR{瀵硅薄鍜岃寖鍥存槑纭紵}
+    CLEAR -->|鍚 CLARIFY[clarify锛歩nterrupt 绛夊緟琛ュ厖]
+    CLARIFY --> INTENT
+    CLEAR -->|鏄瘄 ROUTE[route_scenario锛氱櫧鍚嶅崟鍦烘櫙璺敱]
+    ROUTE --> SUB[鍦烘櫙瀛愬浘锛氬彇璇� / 璁＄畻 / 鏍￠獙]
+    SUB --> CHECK[validate_evidence锛氬畬鏁村害涓庢柊椴滃害]
+    CHECK -->|涓嶈冻| PARTIAL[鐢熸垚缂哄彛鎶ュ憡]
+    CHECK -->|鍏呭垎| PROPOSE[鏋勫缓缁撴灉涓庡姩浣滄柟妗圿
+    PROPOSE --> POLICY{鍔ㄤ綔绛栫暐鍒ゅ畾}
+    POLICY -->|鍙缁撴灉| PUBLISH[淇濆瓨骞跺彂甯冪粨鏋淽
+    POLICY -->|闇�瀹℃壒| SUBMIT[骞傜瓑鐧昏鏂规涓� BPM 鐢宠]
+    SUBMIT --> WAIT[await_approval锛歩nterrupt]
+    WAIT --> RECHECK[閲嶆柊鏍搁獙瀹℃壒 / 鏉冮檺 / 鏁版嵁鐗堟湰]
+    RECHECK -->|閫氳繃| EXEC[鎵ц鏄庣‘鎺堟潈鐨勫懡浠
+    RECHECK -->|杩囨湡| SUB
+    RECHECK -->|鎷掔粷| REJECT[璁板綍鎷掔粷 / 鍏抽棴鍔ㄤ綔]
+    POLICY -->|瑙勫垯鎺堟潈鐨勫唴閮ㄥ緟鍔瀨 EXEC
+    EXEC --> VERIFY[鎸夊懡浠ゅ彿鏌ヨ骞堕獙璇佺粨鏋淽
+    VERIFY --> PUBLISH
+    PARTIAL --> PUBLISH
+    REJECT --> PUBLISH
+    PUBLISH --> END([缁撴潫鏈疆 / 鐧昏鍚庣画浜嬩欢璁㈤槄])
+```
+
+鑺傜偣鑱岃矗锛�
+
+- `validate_context`锛氭帴鍙� Java 绛惧彂鐨勯檺鏃剁敤鎴峰鎵樻垨绯荤粺宸℃韬唤锛涗笟鍔″璞″繀椤诲湪褰撳墠鑼冨洿鍐呫�傝韩浠戒笌璁块棶浠ょ墝涓嶆斁鍏ュ彲鎸佷箙鍖栧浘鐘舵�併��
+- `resolve_request`锛氳緭鍑� `scenario_id + business_refs + time_window + requested_action`銆傚璞℃涔夋椂浜х敓寰呰ˉ鍏呴」锛屼笉鑳借嚜琛屼粠鍚屽悕瀹㈡埛涓�夋嫨銆�
+- `route_scenario`锛氭寜閰嶇疆鍏佽鐨勫満鏅笌鏉冮檺璺敱锛屾ā鍨嬩笉鐢熸垚浠绘剰 Python 鍑芥暟鍚嶆垨 URL銆�
+- `validate_evidence`锛氬垽鏂暟鎹己澶便�佹潵婧愬啿绐併�佸崟浣嶄笉涓�鑷村拰蹇収杩囨湡锛涘け璐ユ椂鍙緭鍑洪儴鍒嗙粨鏋滐紝浣嗛樆姝㈢浉鍏冲啓鎿嶄綔銆�
+- `POLICY`锛氱敱浠ｇ爜鎸夊姩浣滅被鍨嬩笌鐢ㄦ埛鎺堟潈鍒ゅ畾瀹℃壒瑕佹眰锛涙枃鏈腑鍑虹幇鈥滃凡鎵瑰噯鈥濅笉鑳芥敼鍙樿缁撴灉銆�
+- `VERIFY`锛氬尯鍒嗏�滃懡浠ゅ凡鎺ユ敹鈥濃�滃鎵逛腑鈥濃�滃崟鎹凡鍒涘缓鈥濃�滀笟鍔″畬鎴愨�濓紱鍓嶇鎹灞曠ず鐘舵�併��
+
+## 4. 涔濅釜涓氬姟瀛愬浘涓庡鐢ㄨ妭鐐�
+
+| 鍦烘櫙瀛愬浘 | 鏍稿績鑺傜偣椤哄簭 | Java 棰嗗煙渚濊禆 | 涓昏鏂板鍐呭 |
+| --- | --- | --- | --- |
+| `order_review` | 璁㈠崟涓婁笅鏂� 鈫� 榻愬 鈫� 浜ц兘妯℃嫙 鈫� 浜ゆ湡姣旇緝 鈫� 璇勫鏂规 | CRM 鍚堝悓銆丒RP 閿�鍞崟銆丮PS/宸ュ崟銆佸簱瀛樸�佹帓绋� | 璁㈠崟琛屽叧鑱旇仛鍚堛�佹壙璇烘棩璁＄畻銆佸奖鍝嶈鍗曞垪琛� |
+| `material_readiness` | 宸ュ崟鑼冨洿 鈫� BOM 涓庣墿鏂欐槧灏� 鈫� 鍙敤搴撳瓨/鍦ㄩ�� 鈫� 纭畾鎬у垎閰� 鈫� 缂哄彛鍚堝苟 | MDM銆丮ES BOM/WMS銆丒RP 閲囪喘銆丼RM | 璺ㄥ伐鍗曞垎閰嶇瓥鐣ャ�佸偓浜ゅ洖鎵т笌鍑�缂哄彛蹇収 |
+| `progress_patrol` | 璁″垝鍩虹嚎 鈫� 鏈夋晥鎶ュ伐 鈫� 鏃ュ巻/鏆傚仠璁板綍 鈫� 閫炬湡璁＄畻 鈫� 璐ｄ换褰掑彛 | 宸ュ崟/浠诲姟/鎶ュ伐銆佹帓鐝�丠RM | 杩炵画瓒呮湡妫�娴嬨�佸緟鍔炲幓閲嶄笌鍗囩骇 |
+| `reschedule` | 璧勬簮蹇収 鈫� 褰撳墠鏂规 鈫� 鎻掑崟棰勮 鈫� 褰卞搷宸紓 鈫� 鎻愪氦鍊欓�夋柟妗� | MES 鎺掔▼銆佽澶囥�佺彮缁勩�丒RP/CRM | 澶氭柟妗堝揩鐓с�佸鎵逛笌鐗堟湰鍐嶉獙璇� |
+| `shipment_check` | 閿�鍞 鈫� 鍑哄簱/搴撳瓨/瑁呯 鈫� OQC/鍐荤粨 鈫� 鍙彂閲� 鈫� 闃绘柇鎶ュ憡 | ERP銆丮ES-WM銆丮ES-QC | 鍙戣揣鍓嶈仛鍚堣鍥� |
+| `quality_containment` | 妫�楠岃鍒欑増鏈� 鈫� 瓒婇檺鍒ゅ畾 鈫� 鎵规娴佽浆 鈫� 褰卞搷闈� 鈫� NCR/澶嶉獙鏂规 | IQC/IPQC/OQC/RQC銆丯CR銆佸簱瀛� | 妫�楠岃澶囨帴鍏ャ�侀殧绂诲強鍋滃绾垮鎵规祦绋� |
+| `equipment_patrol` | 璁″垝绐楀彛 鈫� 鏈夋晥璁板綍 鈫� 缁翠慨鍘婚噸 鈫� 宸ュ崟褰卞搷 鈫� 琛ユ/淇濆吇鏂规 | 璁惧銆佺偣妫�/淇濆吇銆佺淮淇�佹帓鐝� | 鍙獙璇佺殑鏈烘椂閲囬泦銆佸叧閿澶囨帓搴� |
+| `outsource_reconciliation` | 澶栧崗鍗� 鈫� 鍙戞敹閫�鏂�/IQC 鈫� 鍚堝悓鐗堟湰 鈫� 鏁伴噺浠峰樊 鈫� 鏍稿疄娓呭崟 | 澶栧崗浠撳偍銆丒RP銆丼RM | 鍚堝悓鎹熻�楃巼銆佸姞宸ヨ垂鍙ｅ緞涓庡樊寮傚鐞� |
+| `complaint_trace` | 鍞悗/鎵瑰彿瑙ｆ瀽 鈫� 鍙嶅悜杩芥函 鈫� 姝ｅ悜褰卞搷 鈫� 鎶ュ憡闄勪欢 鈫� 鍥炲鑽夌 | 鍞悗銆丆RM銆丒RP銆佹壒娆�/SN銆佽川妫�鎶ュ憡 | 璺ㄦā鍧楀叧绯昏ˉ鍏ㄤ笌璇佹嵁鏂偣浠诲姟 |
+
+瀛愬浘鐢ㄧ嫭绔� input/output schema锛岄�氳繃鍖呰鑺傜偣杞崲鐖跺瓙鐘舵�併�傞粯璁ら噰鐢ㄦ瘡娆¤皟鐢ㄧ嫭绔嬬殑瀛愬浘鐘舵�侊紝缁ф壙鐖跺浘妫�鏌ョ偣锛涗笉璁╀笉鍚岃鍗曞叡浜鍩熸秷鎭巻鍙层�傛壒閲忓贰妫�鍙敤 `Send` 鍒嗗彂鐙珛宸ュ崟锛岀粨鏋滄寜瀵硅薄閿仛鍚堬紝鏄庣‘鍒嗛〉鍜屽苟鍙戜笂闄愩�傚瓙鍥炬寔涔呭寲妯″紡鍙婄埗鍥惧叧绯昏 [Subgraphs](https://docs.langchain.com/oss/python/langgraph/use-subgraphs)銆�
+
+鍏ㄦā鍧椾互棰嗗煙宸ュ叿鍖呰鐩栵細`mdm / crm / srm / erp / mes_pro / mes_wm / mes_qc / mes_dv / mes_cal / mes_energy / qcreport / aftersales / hrm / bpm / bi / system / infra / ai_knowledge`銆侫rchive銆丗inance銆丷esearch銆乁MS銆乄XCP 绛夊厛鐧昏鑳藉姏娓呭崟锛屾牳瀹炲疄闄呮帴鍙ｅ悗鍚敤锛汭M/Member 榛樿鍏抽棴銆傜粡钀ラ棶绛斻�佹垚鏈垎鏋愪綔涓哄悗缁法鍩熷浘锛屽鐢ㄥ悓涓�宸ュ叿灞傘��
+
+## 5. 鐘舵�佷笌韬唤妯″瀷
+
+涓嶈鎶婃墍鏈変笟鍔℃暟鎹杩� `messages`銆傚浘鐘舵�侀噰鐢ㄦ槑纭殑涓氬姟瀛楁锛岃竟鐣� DTO 浣跨敤 Pydantic 鏍￠獙锛涙秷鎭彧淇濆瓨蹇呰鐨勪汉鏈哄線鏉ャ��
+
+| 瀛楁 | 绫诲瀷/鍚箟 | 鍚堝苟绛栫暐 |
+| --- | --- | --- |
+| `task_id / case_id / graph_version` | 鎵ц浠诲姟銆佷笟鍔℃浠躲�佸浘鐗堟湰 | 鍗曚竴鍗忚皟鑺傜偣鍐� |
+| `scenario_id / business_refs` | 鍦烘櫙涓庡璞″紩鐢� | 楠岃瘉鍚庡浐瀹氾紝淇敼闇�鏂版柟妗堢増鏈� |
+| `time_window / rule_versions` | 鏈璁＄畻鑼冨洿涓庤鍒欑増鏈� | 鍗曚竴鍐欏叆 |
+| `snapshot_refs` | 鍚勫伐鍏风粨鏋滅殑瀛樺偍寮曠敤銆佷笟鍔＄増鏈�侀噰闆嗘椂闂� | 鎸� source_key 鍚堝苟 |
+| `evidence` | 璇佹嵁 ID銆佹潵婧愬璞°�佸瓧娈垫憳瑕併�佸彲淇＄▼搴� | 鎸� evidence_id 鍘婚噸鍚堝苟锛涘悓 ID 鍐茬獊鎶ラ敊 |
+| `findings` | 纭畾浜嬪疄銆佹帹鏂�佺己鍙ｄ笌椋庨櫓 | 鎸� finding_id 鍚堝苟 |
+| `proposal_ref` | 涓嶅彲鍙樺姩浣滄柟妗� ID銆佺増鏈�乭ash | 鍗曚竴鑺傜偣鍐欏叆 |
+| `approval_ref / command_refs` | BPM 瀹炰緥涓庡懡浠よ褰曞紩鐢� | 鎸変笟鍔￠敭鍘婚噸 |
+| `result_ref / status / errors` | 杈撳嚭浜х墿涓庝换鍔＄姸鎬� | 鐘舵�佹満鎺у埗 |
+
+骞惰鑺傜偣浠呰繑鍥炶嚜宸辫礋璐ｇ殑灞�閮ㄦ洿鏂帮紱鍏变韩缁撴灉瀛楁閰嶇疆 reducer锛岄伩鍏嶅苟琛岃鐩栥�傚悓涓�鏉¤瘉鎹噸鏀惧悗涓嶉噸澶嶈鏁般�傜姸鎬佷繚瀛� JSON 鍙簭鍒楀寲鍊间笌寮曠敤锛岀姝㈡妸杩炴帴姹犮�丠TTP 瀹㈡埛绔�佸嚟鎹�佸畬鏁撮檮浠舵斁杩涙鏌ョ偣銆�
+
+`conversation_id` 鏄敤鎴峰璇濓紱`case_id` 鏄笟鍔￠棶棰樼敓鍛藉懆鏈燂紱`task_id` 瀵瑰簲涓�娆″畬鏁村浘鎵ц锛屼綔涓� `thread_id` 鐨勬湇鍔＄鏄犲皠锛沗run_id` 鏄竴娆¤繍琛屾垨鎭㈠灏濊瘯銆備竴涓璇濆彲鏈夊涓浠跺拰浠诲姟銆傚鎵规仮澶嶄娇鐢ㄥ師 thread锛涘畾鏃跺鏌ュ缓绔嬫柊浠诲姟骞跺叧鑱斿師 case锛岄伩鍏嶆棫鍥剧姸鎬佹棤闄愬闀裤��
+
+璇锋眰鏃剁殑鏉冮檺蹇収浠呯敤浜庡璁°�傛瘡娆℃煡璇€�佸鎵规仮澶嶅拰鍐欏叆閮界敱 Java 妫�鏌ユ渶鏂版潈闄愩�傛仮澶嶄换鍔￠噸鏂板彇寰楀彈鎺ц闂笂涓嬫枃锛屼笉渚濊禆鍑犲ぉ鍓嶅凡杩囨湡鐨勭櫥褰� token銆�
+
+## 6. 閲嶇偣瀛愬浘锛氶綈濂楀垎鏋愮殑鐪熷疄璁＄畻鍙ｅ緞
+
+```text
+load_workorders
+  鈫� resolve_bom_and_units
+  鈫� fetch_material_snapshot锛堝簱瀛樸�佸喕缁撱�佸崰鐢ㄣ�侀噰璐湪閫旓級
+  鈫� validate_snapshot
+  鈫� allocate_supply_across_orders
+  鈫� calculate_shortages
+  鈫� aggregate_by_material_and_supplier
+  鈫� explain_with_evidence
+  鈫� propose_expedite_tasks
+```
+
+涓�涓壒娆″贰妫�鍏堢粺涓�鍔犺浇鐗╂枡渚涘簲蹇収锛屽啀鎸夌‘瀹氱殑宸ュ崟浼樺厛绾у垎閰嶄緵搴斻�傞�愬伐鍗曠嫭绔嬭鍙栧悓涓�搴撳瓨浼氶噸澶嶆壙璇哄悓涓�鎵圭墿鏂欙紝鍥犳涓嶈兘绠�鍗曞苟琛岃绠楀悗鐩稿姞銆備紭鍏堢骇銆佹浛浠ｆ枡瑙勫垯銆佽閲忓崟浣嶅拰鍏佽鎹熻�楀繀椤荤増鏈寲銆�
+
+搴撳瓨鏈嶅姟鎻愪緵鏉冨▉鐨勫彲鍒嗛厤閲忓強鍏跺彛寰勩�傚喕缁撲笌鍗犵敤鍙兘閲嶅彔锛屼笉鑳芥湭缁忛獙璇佸氨閲嶅鎵ｅ噺锛涗篃瑕佸尯鍒嗘湰宸ュ崟鍗犵敤涓庡叾瀹冨伐鍗曞崰鐢ㄣ�佸凡棰嗙墿鏂欏拰鍦ㄩ�旈璁″埌璐с�傚墠鏈熻摑鍥剧殑绠�鍖栧噣鍙敤鍏紡浠ユ湰鑺備负瀹炴柦渚濇嵁銆�
+
+璺ㄦā鍧楄鍙栨湭蹇呮槸鍚屼竴涓暟鎹簱浜嬪姟蹇収锛屽洜姝ょ粨鏋滆褰曟瘡涓潵婧愮殑鐗堟湰涓庨噰闆嗘椂闂淬�備粎灏嗙粨鏋滅О浣溾�滄埅鑷虫煇鏃剁偣鐨勮瘎浼扳�濓紱鎵ц棰嗘枡鎴栭噰璐瓑鍔ㄤ綔鏃讹紝鐢卞師涓氬姟浜嬪姟閲嶆柊鏍￠獙锛屼笉鎶婂垎鏋愬揩鐓у綋搴撳瓨閿併��
+
+## 7. 宸ュ叿鍗忚涓� Java 瀵规帴
+
+鍐呴儴鎺ュ彛寤鸿鏀惧湪 `yudao-module-ai` 鐨� `bridge` 鍏ュ彛锛涜皟鐢ㄥ悇妯″潡宸叉湁 Service/API锛屽苟琛ヨ冻缂哄け鐨勫彧璇昏仛鍚� API銆傚叕鍏� DTO 鏀惧湪鐩稿簲 `*-api` 妯″潡锛岄伒寰幇鏈� Maven 渚濊禆鏂瑰悜锛岄槻姝� AI 涓� MES 鐩镐簰渚濊禆銆傚ぇ鍨嬫帴鍏ュ彲鐙珛涓� `yudao-module-agent`锛岄渶瑕佸厛鏍稿缂栬瘧渚濊禆鍥俱��
+
+```json
+{
+  "tool": "mes.material.readiness_snapshot",
+  "schema_version": "1",
+  "request_id": "uuid",
+  "task_id": "uuid",
+  "arguments": {"work_order_ids": [101, 102]},
+  "response": {
+    "data_ref": "snapshot-id",
+    "source_versions": {"workorder:101": "revision"},
+    "observed_at": "ISO-8601",
+    "completeness": "partial",
+    "missing": ["purchase_delivery_confirmation"]
+  }
+}
+```
+
+涓婁緥鏄绾﹀舰鐘剁ず鎰忥紝瀹為檯璇锋眰鍜屽搷搴斿垎鍒紶杈撱�傜敤鎴�/绉熸埛韬唤鏉ヨ嚜鏈嶅姟绔鍙戠殑濮旀墭涓婁笅鏂囷紝涓嶆帴鍙楁ā鍨嬬敓鎴愮殑韬唤瀛楁銆傚伐鍏风櫥璁板寘鎷鍩熴�佽鍐欑骇鍒�佹潈闄愮爜銆乻chema銆佽秴鏃躲�佸垎椤典笂闄愩�佸彲閲嶈瘯閿欒鍜屾晱鎰熷瓧娈电瓥鐣ャ��
+
+鐜版湁浠ｇ爜鍙埄鐢ㄧ殑鍏蜂綋鍏ュ彛鍖呮嫭锛�
+
+- `MesProTaskController`锛歚POST /mes/pro/task/auto-schedule/preview` 涓� `/auto-schedule`銆傛寮忔墽琛岃鏄庝负閲嶆柊鏍￠獙棰勮骞舵暣鎵瑰師瀛愭彁浜わ紝鎺ュ叆鏃剁户缁皟鐢ㄨ涓氬姟瑙勫垯銆傚綋鍓嶉瑙堣鏄庢湁 09鈥�18 鐐瑰強鍛ㄦ湯/鑺傚亣鏃ョ害鏉燂紱澶滅彮銆佸鐝笌棰濆鎹㈠瀷绾︽潫闇�鎵╁睍骞堕獙璇併��
+- `MesProAiController`锛氬洓绫荤敓浜ч娴嬶紝浣滀负鏃㈡湁寤鸿鑳藉姏瀵规帴锛岀‘瀹氭�ц绠楃粨鏋滀紭鍏堛��
+- `MesProWorkOrderController`锛氬伐鍗曡繘搴︿笌璁″垝鏌ヨ锛沗MesWmBatchController`锛氬墠鍚庡悜鍙婂伐搴忚拷婧��
+- 鐐规銆佺淮淇�丯CR銆佸鍗忓彂鏂�/鍏ュ簱銆侀攢鍞嚭搴撶瓑鎺у埗鍣ㄥ凡鏈夊璞″叆鍙ｏ紝闇�閫氳繃 Bridge 鏆撮湶鏈�灏忓瓧娈甸泦銆�
+
+杩欎簺 HTTP 璺緞鏄簮鐮佷腑鐨� Controller 鐩稿璺緞锛涢儴缃茬殑 `/admin-api` 绛夊墠缂�銆侀壌鏉冨拰鏁版嵁鑼冨洿椤诲湪鑱旇皟涓‘璁ゃ�侾ython 涓嶉�氳繃瓒呯骇绠＄悊鍛樿处鍙疯浆鍙戝叏閮ㄤ笟鍔¤姹傘��
+
+## 8. 瀹℃壒鎭㈠涓庝笟鍔″箓绛�
+
+LangGraph `interrupt()` 鐢ㄤ簬鏆傚仠绛夊緟锛屾仮澶嶄娇鐢ㄥ悓涓� thread 涓嬬殑 `Command(resume=...)`銆傛仮澶嶄細浠庝腑鏂妭鐐硅捣鐐归噸璺戯紝鍥犳瀹℃壒鑺傜偣鍙鍙栧凡鐧昏鏂规骞跺彂鍑轰腑鏂紝寤哄崟銆佸彂閫氱煡绛夊壇浣滅敤鏀惧湪鐙珛鐨勫箓绛夎妭鐐广�備笉鑳界敤娉涘寲寮傚父鎹曡幏鍚炴帀涓柇銆俒Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts)
+
+瀹屾暣娴佺▼锛�
+
+1. `prepare_proposal` 鍐荤粨鍙傛暟銆佷笟鍔＄増鏈�佽瘉鎹紩鐢ㄣ�佹湁鏁堟湡锛岀敓鎴� `proposal_id + version + hash`銆�
+2. `register_approval` 閫氳繃 Java 骞傜瓑鍒涘缓瀹℃壒璁板綍锛涗簨鍔℃彁浜ゅ悗鐢� outbox 閫氱煡銆�
+3. `await_approval` 涓柇骞堕噴鏀� Worker锛屼笉淇濇寔 HTTP 鎴栨暟鎹簱杩炴帴绛夊緟銆�
+4. BPM 鍥炶皟鍏堣惤 inbox 鍘婚噸锛岄獙璇佸鎵瑰疄渚嬨�佸姩浣� hash 涓庣缃叉潈闄愶紱鑻ュ浘灏氭湭鍒颁腑鏂偣锛屼簨浠朵繚鐣欑瓑寰咃紝涓嶈兘涓㈠純銆�
+5. Worker 鎸佹湁浠诲姟绉熺害锛岃鍙栧搴� interrupt锛涚敤缁忚繃楠岃瘉鐨勫鎵硅褰曞紩鐢ㄦ仮澶嶏紝绂佹鍓嶇鐩存帴鎻愪氦浠绘剰 `resume` 鍊笺��
+6. `revalidate` 鍐嶆煡鏉冮檺銆佸鎵规挙閿�鐘舵�併�佸弬鏁� hash銆佸璞＄増鏈拰鏈夋晥鏈熴�傛暟鎹彉鏇撮渶閲嶇畻锛屽姩浣滃弬鏁板彉鏇撮』閲嶆柊瀹℃壒銆�
+7. `execute_command` 甯︾ǔ瀹� `command_id`銆佸箓绛夐敭鍜屾湡鏈涚増鏈氦缁� Java銆傚箓绛夐敭鐢卞満鏅�佹柟妗堢増鏈�佸姩浣滅被鍨嬪強涓氬姟瀵硅薄鏋勬垚锛屽悓涓�鎵瑰噯鍔ㄤ綔閲嶆斁鏃朵繚鎸佷笉鍙樸��
+8. Java 鍦ㄥ悓涓�涓氬姟浜嬪姟鍐呯櫥璁板懡浠ょ粨鏋滀笌涓氬姟鍙樻洿锛屽敮涓�绾︽潫鎷︽埅閲嶅璇锋眰锛涢噸璇曡繑鍥炲師涓氬姟鍗曞彿銆�
+9. 缃戠粶瓒呮椂灞炰簬鈥滅粨鏋滄湭鐭モ�濓紝鎸夊懡浠� ID 鏌ヨ缁撴灉锛屼笉鑳界洿鎺ュ綋澶辫触鍐嶅缓鏂板崟銆傚洖璇绘垚鍔熷悗鎵嶅悜鍓嶇鏄剧ず鈥滃凡鎵ц鈥濄��
+
+妫�鏌ョ偣涓嶆彁渚涘閮ㄧ郴缁熺殑 exactly-once 淇濊瘉銆備笟鍔′竴鑷存�т緷璧� Java 浜嬪姟銆佸懡浠ゅ幓閲嶃�佺増鏈牎楠屼笌瀵硅处琛ュ伩銆傝法妯″潡闀挎祦绋嬫媶鎴愬彲鏍稿鐨勫懡浠ゅ簭鍒楋紱涓�斿け璐ュ仠姝㈠悗缁姩浣滐紝琛ュ伩浠呰皟鐢ㄤ笟鍔″厑璁哥殑鎾ら攢鎺ュ彛锛屽苟淇濈暀浜哄伐澶勭悊鍏ュ彛銆�
+
+## 9. 浜嬩欢銆佷富鍔ㄥ贰妫�涓庢仮澶�
+
+寤鸿浜嬩欢绫诲瀷锛歚sales.delivery_changed`銆乣purchase.delivery_confirmed`銆乣production.feedback_approved`銆乣quality.inspection_completed`銆乣equipment.repair_changed`銆乣warehouse.receipt_completed`銆乣bpm.approval_decided`銆傚悕绉颁负鎷熷畾濂戠害锛岄渶瑕佹柊澧炲彂甯冮�傞厤銆�
+
+浜嬩欢鑷冲皯鍖呭惈 `event_id`銆乣event_type`銆乣aggregate_ref`銆乣aggregate_version`銆乣occurred_at`銆乣schema_version` 鍜岀鎴枫�備笟鍔′簨鍔″啓 outbox锛屽紓姝ュ彂甯冿紱Python inbox 鐢ㄤ簨浠� ID 鍘婚噸锛屾寜瀵硅薄鐗堟湰澶勭悊涔卞簭锛屾寜浜嬩欢鍏宠仈鍞ら啋妗堜欢鎴栧惎鍔ㄥ鏌ャ��
+
+瀹氭椂鍣ㄤ笌浜嬩欢鎺ュ叆璐熻矗鍙戣捣/鎭㈠鍥撅紝LangGraph 鏈韩涓嶅厖褰撶敓浜у畾鏃惰皟搴︽湇鍔°�傜瓑寰呮湡闂翠笉浣跨敤闀挎椂闂� sleep銆傝窡杩涜褰曞惈涓嬫妫�鏌ユ椂闂淬�佽矗浠讳汉銆佹埅姝㈡椂闂淬�佸崌绾х瓥鐣ヤ笌鍋滄鏉′欢锛涢�氱煡璁板綍淇濆瓨娓犻亾鍥炴墽锛屾湭鍙樺寲鐨勫贰妫�缁撴灉涓嶅弽澶嶆彁閱掋��
+
+## 10. 鏁版嵁琛ㄤ笌鎸佷箙鍖栬竟鐣�
+
+| Agent 鑷湁琛� | 鏍稿績鐢ㄩ��/绾︽潫 |
+| --- | --- |
+| `agent_case` | 涓氬姟妗堜欢鍙婂叧鑱斿璞°�佸綋鍓嶅鐞嗛樁娈� |
+| `agent_task` | case/thread 鏄犲皠銆佸浘鐗堟湰銆佺绾︺�佺姸鎬侊紱鍚屼换鍔″崟鎵ц鑰� |
+| `agent_run` | 姣忔鎵ц/鎭㈠鐨勮緭鍏ユ憳瑕併�佽捣姝㈡椂闂淬�侀敊璇笌鎴愭湰 |
+| `agent_snapshot` | 鏁版嵁鏉ユ簮銆佺増鏈�侀噰闆嗘椂闂淬�佸畬鏁村害銆佸璞″瓨鍌ㄥ紩鐢� |
+| `agent_proposal` | 涓嶅彲鍙樻柟妗堢増鏈�佸弬鏁� hash銆佹湁鏁堟湡 |
+| `agent_command` | 鍛戒护 ID銆佸箓绛夐敭銆佽姹� hash銆佽繙绔粨鏋滐紱鎵ц鏉冨▉缁撴灉鍦� Java |
+| `agent_inbox / agent_outbox` | 鍙潬浜嬩欢鎺ユ敹涓庡彂閫侊紱浜嬩欢 ID 鍞竴 |
+| `agent_followup` | 涓嬫澶嶆煡涓庡崌绾ф潯浠躲�佸叧闂師鍥� |
+| `agent_ui_event` | 鏈夊簭鐣岄潰浜嬩欢銆丼SE 閲嶈繛娓告爣 |
+| 妗嗘灦妫�鏌ョ偣琛� | 鐢卞浐瀹氱増鏈� saver 绠＄悊锛屼笉鎵嬪伐浼�犳垨淇敼鐘舵�� |
+
+Checkpointer 淇濆瓨绾跨▼鎵ц鐘舵�侊紱璺ㄤ换鍔＄殑鍋忓ソ涓庡彈瀹℃牳鐭ヨ瘑鍙互浣跨敤 Store 鎴栧簲鐢ㄦ暟鎹〃锛屽苟鎸夌鎴�/鐢ㄦ埛鍛藉悕绌洪棿闅旂銆傚疄鏃跺簱瀛樸�佸凡鍙樻洿瀹℃壒銆佸鎴蜂俊鐢ㄧ瓑浜嬪疄姣忔閲嶆柊鏌ヨ锛屼笉浠庤亰澶╄蹇嗗綋浣滃綋鍓嶇湡鍊笺�俒Checkpointers](https://docs.langchain.com/oss/python/langgraph/checkpointers)
+
+鍥剧増鏈浐瀹氬埌浠诲姟锛屽崌绾т繚鐣欐棫鐗堟湰 Worker 鐩磋嚦鎸傝捣浠诲姟缁撴潫锛屾垨鍋氱粡杩囨祴璇曠殑鐘舵�佽縼绉汇�傞儴缃叉椂涓嶈兘闅忔剰閲嶅懡鍚嶇瓑寰呬腑鐨勮妭鐐�/鍒犻櫎鐘舵�佸瓧娈点�傞厤缃鏌ョ偣涓庝骇鐗╀繚鐣欐湡锛屼笟鍔″璁℃寜浼佷笟瑕佹眰鍗曠嫭鐣欏瓨銆�
+
+## 11. 妯″瀷銆佺煡璇嗕笌鐣岄潰鍗忚
+
+妯″瀷缃戝叧鎸夎兘鍔涢�夋嫨鏂囨湰銆佺粨鏋勫寲杈撳嚭鍜岃瑙夋ā鍨嬶紝瀵嗛挜淇濈暀鏈嶅姟绔�傜煭鏈熺敤鐜版湁 `AiChatApi` 閫傞厤鑷劧璇█璇存槑锛涜嫢鍏朵粎杩斿洖鏂囨湰锛屽垯 Python 浣跨敤 JSON schema 鏍￠獙骞舵湁闄愪慨澶嶃�傞渶瑕佸師鐢熷伐鍏疯皟鐢ㄦ椂鏂板鍗忚閫傞厤锛屼笉鍋囪鐜版湁瀛楃涓叉帴鍙ｅ凡鎻愪緵璇ヨ兘鍔涖��
+
+鐭ヨ瘑妫�绱紶鍏ラ鍩熴�佺墿鏂�/浜у搧銆佹爣鍑嗙増鏈�佺敓鏁堟棩鏈熷拰鏉冮檺杩囨护銆傝瘉鎹褰曟枃妗� ID銆佺増鏈�侀〉鐮�/娈佃惤銆侀檮浠跺紩鐢紱宸ヨ壓鍙樻洿鎸変笟鍔″彂鐢熸椂闂撮�夋湁鏁堢増鏈�傛绱㈡枃妗ｄ綔涓哄唴瀹规暟鎹紝涓嶈兘鏀瑰彉宸ュ叿鏉冮檺鎴栦笟鍔¤鍒欍��
+
+鍓嶇閲囩敤绋冲畾鐨勪笟鍔� SSE 鍗忚锛歚task_started`銆乣step_completed`銆乣evidence_added`銆乣result_ready`銆乣approval_required`銆乣command_submitted`銆乣command_verified`銆乣task_failed`銆傚墠绔笉娑堣垂鍘熷 checkpoint銆佸唴閮� prompt 鎴栧畬鏁村伐鍏疯繑鍥炪�傛湇鍔＄灏� LangGraph 娴佷簨浠惰浆鎹㈡垚涓婅堪鍗忚骞惰繃婊ゆ潈闄愶紱鏂嚎鍚庢寜 event_id 琛ュ彂銆傚畼鏂规敮鎸佺姸鎬佹洿鏂般�佹秷鎭強鑷畾涔夋祦锛岄�夊畾鐗堟湰鍚庡浐瀹氶�傞厤鍣ㄥ苟瑕嗙洊鍗忚娴嬭瘯銆俒Streaming](https://docs.langchain.com/oss/python/langgraph/streaming)
+
+## 12. Python 宸ョ▼鐩綍涓庝緷璧栫瓥鐣�
+
+```text
+mom-industrial-agent/
+  pyproject.toml / uv.lock
+  src/mom_agent/
+    api/                  # tasks銆乧ases銆乺esults銆丼SE锛涘唴閮ㄤ簨浠舵帴鍏�
+    runtime/              # Worker銆佺绾︺�佹仮澶嶃�佸浘鐗堟湰娉ㄥ唽
+    graphs/
+      coordinator.py
+      scenarios/          # 涔濅釜鍦烘櫙 StateGraph
+      shared/             # 璇佹嵁鏍￠獙銆佹柟妗堛�佸鎵广�佸懡浠ゅ洖璇�
+    state/                # 鐖跺瓙鍥剧姸鎬併�乺educer銆乻chema 杩佺Щ
+    domains/              # 瑕嗙洊鎵�鏈夊疄闄呬笟鍔℃ā鍧楃殑宸ュ叿濂戠害
+    calculators/          # 榻愬鍒嗛厤銆佸伐鏃躲�佸樊寮傜瓑鍙祴璇曡绠�
+    integrations/         # Java銆佹ā鍨嬨�佺煡璇嗗簱銆侀�氱煡娓犻亾
+    policies/             # 鏉冮檺闇�姹傘�佸姩浣滅瓑绾с�侀绠椼�佹暟鎹湁鏁堟湡
+    persistence/          # PostgreSQL 妫�鏌ョ偣涓庡簲鐢ㄨ〃
+    events/               # inbox/outbox銆佷簨浠跺叧鑱斻�佽窡杩涗换鍔�
+    observability/        # 鏃ュ織銆佹寚鏍囥�乼race
+  tests/unit/ contracts/ graph/ recovery/ scenarios/
+  evaluations/            # 鑴辨晱鐪熷疄妗堜緥銆佸熀鍑嗙粨鏋滀笌鏍囨敞
+  migrations/
+  deploy/                 # 瀹瑰櫒銆侀厤缃ず渚嬨�佽繍琛屾墜鍐�
+```
+
+Python 3.11+锛涗緷璧栭攣瀹� LangGraph銆乧heckpoint-postgres銆丳ydantic銆丗astAPI銆乭ttpx銆佹暟鎹簱椹卞姩涓庢ā鍨嬮�傞厤鍖呯殑鍏煎缁勫悎銆傚彧閲囩敤宸查獙璇佹墍闇� API锛涗笉鑷姩璺熼殢鏈�鏂扮増鏈紝涓嶄负鍒濇湡鏂规寮曞叆棰濆澶氭櫤鑳戒綋妗嗘灦銆�
+
+## 13. 楠屾敹涓庡疄鏂芥媶鍒�
+
+绗竴鍖咃細鍥捐繍琛屽簳搴с�丣ava 濮旀墭韬唤銆佸彧璇诲伐鍏枫�佹鏌ョ偣銆丼SE銆佷换鍔�/浜嬩欢琛ㄣ�傞�氳繃鈥滄寕璧峰悗閲嶅惎浠嶈兘鎭㈠銆佸悓浠诲姟骞跺彂鍙楁帶銆佽秺鏉冮殧绂汇�佷簨浠朵笉涓笉閲嶅鈥濈殑楠屾敹銆�
+
+绗簩鍖咃細榻愬銆佸伐鍗曞贰妫�鍜屼氦鏈熻瘎瀹′笁鍥俱�傜敤鑴辨晱鐪熷疄宸ュ崟瀵规瘮浜哄伐鍩哄噯锛涙楠屽悓鎵瑰簱瀛樹笉琚噸澶嶅垎閰嶃�佸喕缁撳崰鐢ㄤ笉琚噸澶嶆墸鍑忋�佹潵婧愮己澶变笉鐢熸垚纭畾鎬ф壙璇恒��
+
+绗笁鍖咃細瀹℃壒涓庡啓鍛戒护銆傝鐩栧洖璋冨厛鍒�/閲嶅鍒般�佸鎵瑰悗涓氬姟鍙樺寲銆佹墽琛屽悗缃戠粶鏂紑銆佸啓鎴愬姛浣嗘鏌ョ偣鏈繚瀛樸�佸鎵规挙閿�绛夋晠闅滄敞鍏ワ紱閲嶈窇涓嶉噸澶嶅缓鍗曘��
+
+绗洓鍖咃細璐ㄩ噺/杩芥函銆佽澶囥�佸彂璐с�佸澶栵紱琛ュ厖鍏ㄦā鍧楁煡璇㈠浘銆佺粡钀ラ棶绛斾笌鎴愭湰鍙ｅ緞銆傚満鏅紑鏀惧墠閫愰」鏍稿鐪熷疄鏁版嵁涓庝笟鍔℃帴鍙ｏ紝涓嶄互瀛樺湪 Controller 浣滀负瀹屾暣鍙敤鐨勮瘉鎹��
+
+瀹屾垚鏍囧噯锛氫節鍦烘櫙鍚勬湁鑺傜偣鍥俱�佽緭鍏ヨ緭鍑哄绾︺�佹潈闄愭竻鍗曘�佷汉宸ヨ竟鐣屻�佸け璐ヨ矾寰勫拰鐪熷疄鏍锋湰锛涙瘡涓粨鏋滃彲杩芥函鏉ユ簮锛屾瘡涓姩浣滃彲鍏宠仈瀹℃壒鍜屼笟鍔″崟鍙枫�傛椂寤躲�佹ā鍨嬫垚鏈拰骞跺彂鐩爣鍦ㄧ湡瀹炴暟鎹妯″帇娴嬪悗璁惧畾锛屼笉娌跨敤瀹ｄ紶鍥句腑鐨勮�楁椂鎴栦氦浠樺懆鏈熴��
+
+## 14. 鏈疆宸茬‘瀹氫笌鍚庣画璇勫鐐�
+
+宸茬‘瀹氾細Python 鐙珛椤圭洰銆丩angGraph 鑷畾涔夌紪鎺掋�佷富鍥句笌涔濆満鏅瓙鍥俱�丣ava 淇濈暀涓氬姟鎵ц涓庡鎵广�佺敓浜ф寔涔呭寲妫�鏌ョ偣銆佷簨浠堕┍鍔ㄨ窡杩涖�佽瘉鎹崱杈撳嚭銆�
+
+鍚庣画璇勫锛氭柊澧� PostgreSQL 鐨勯儴缃茶祫婧愶紱棣栨壒妯″瀷涓庢暟鎹嚭鍩熻姹傦紱鐜版湁 BPM 鏄惁瑕嗙洊鍌氦/鍋滃绾跨瓑鏂版祦绋嬶紱濮斿浠锋牸鎹熻�椾笌鏈烘椂鏉ユ簮锛涘悇宀椾綅鍔ㄤ綔鎺堟潈銆備互涓婂奖鍝嶆帴鍙ｄ笌涓婄嚎鑼冨洿锛屼笉濡ㄧ鍏堝畬鎴愬浘銆佸伐鍏峰拰鏁版嵁濂戠害璁捐銆�
diff --git a/docs/industrial-agent-python-design.md b/docs/industrial-agent-python-design.md
new file mode 100644
index 0000000..51eeb0f
--- /dev/null
+++ b/docs/industrial-agent-python-design.md
@@ -0,0 +1,162 @@
+# 鍏ㄤ笟鍔″伐涓氭櫤鑳戒綋 Python 椤圭洰璁捐鑽夋
+
+> 鐘舵�侊細鏂规璁ㄨ绋匡紱浠呰璁★紝灏氭湭瀹炴柦銆傜洰鏍囨槸涓烘湰浠撳簱寤虹珛鐙珛鐨� Python 鏅鸿兘浣撴湇鍔★紝骞堕�氳繃鍙楁帶鎺ュ彛瑕嗙洊瀹為檯涓氬姟閾捐矾銆�
+
+涔濅釜涓氬姟鍦烘櫙鐨勮Е鍙戙�佸彇璇併�佽绠椼�佺粨鏋溿�佸鎵硅竟鐣屼笌浠撳簱鎺ュ叆鏍稿瑙� [鍦烘櫙钃濆浘](industrial-agent-scenario-blueprint.md)銆�
+
+妗嗘灦宸茬‘瀹氫负 LangGraph锛涗互 [LangGraph 鎶�鏈柟妗圿(industrial-agent-langgraph-technical-design.md) 涓哄伐绋嬪疄鐜颁緷鎹紝鍏朵腑鏄庣‘浜嗘鏌ョ偣瀛樺偍銆佸浘鐘舵�佷笌瀹℃壒鎭㈠缁嗚妭锛屽苟淇鏃╂湡瀛樺偍寤鸿銆�
+
+浼佷笟鍒濇涓婄嚎涓庢棩甯歌ˉ褰曟柊澧炴牳蹇冧富绾匡細[WPS 绛夊伐浣滄枃浠跺垎鏋愩�佸杞牳瀵逛笌涓氬姟鍏ュ簱](industrial-agent-document-onboarding-design.md)锛屼笌杩愯惀鍦烘櫙骞跺垪寤鸿銆�
+
+## 1. 椤圭洰瀹氫綅涓庤竟鐣�
+
+鏈粨搴撲互 Spring Boot 妯″潡鎵胯浇涓氬姟瑙勫垯銆佹潈闄愩�佸鎵瑰拰鏁版嵁锛孭ython 椤圭洰璐熻矗璺ㄦā鍧楃悊瑙ｃ�佹绱€�佸垎鏋愩�佽鍒掍笌寤鸿銆傜敤鎴蜂粠鐜版湁鍓嶇鎴栦笟鍔″崟鎹彂璧蜂换鍔★紱Java 缃戝叧閴存潈骞舵彁渚涘伐鍏锋帴鍙ｏ紱Python 鏅鸿兘浣撶敓鎴愬甫璇佹嵁鐨勫缓璁垨寰呭鎵规搷浣滐紱鎵�鏈変笟鍔″啓鍏ヤ粛缁忓師鏈� Java 鏈嶅姟瀹屾垚銆�
+
+璁捐鐩爣鏄�滀竴涓櫤鑳戒綋骞冲彴 + 澶氫釜棰嗗煙鑳藉姏鍖� + 璺ㄩ鍩熸祦绋嬧�濓紝鑰屼笉鏄负姣忎釜妯″潡澶嶅埗涓�涓亰澶╂満鍣ㄤ汉銆傚钩鍙板厛鎺ュ叆鍏ㄩ儴涓氬姟瀵硅薄鐨�**鐩綍鍜屽彧璇昏兘鍔�**锛屽啀鎸夐闄╅�愭寮�鏀惧彲瀹℃壒鐨勫姩浣溿�傜洰褰曡鐩栦笉绛変簬绗竴鐗堝氨鏈夊畬鏁寸殑鑷姩鎵ц鑳藉姏銆�
+
+### 浠撳簱渚濇嵁
+
+- `docs/project-business/data/modules.json` 缁欏嚭浜� MDM銆丆RM銆丼RM銆丒RP銆佺敓浜с�佷粨鍌ㄣ�佽川閲忋�佽川妫�鎶ュ憡銆佽澶囥�佸敭鍚庛�丠RM銆丅PM銆丄I 鐨勪笟鍔″璞′笌涓婁笅娓搞��
+- `yudao-module-ai` 宸叉湁妯″瀷閰嶇疆銆佺煡璇嗗簱鍜� `AiChatApi`锛汣RM 鎶ヤ环 OCR銆丒RP 鏉ョエ OCR銆丮ES 璐ㄦ寤鸿涓庡洓绫荤敓浜ч娴嬪凡鏈夎皟鐢ㄧ偣銆傛柊 Python 鏈嶅姟搴斿鎺ユ垨閫愭杩佺Щ杩欎簺鑳藉姏锛岄伩鍏嶅弻濂楃瓟妗堜笌閰嶇疆銆�
+- `yudao-module-mes` 鏈夎澶囥�佺偣妫�銆佺淮淇�佸伐鍗曘�佸簱瀛樸�佹楠岀瓑棰嗗煙锛沗yudao-module-bi` 鏈変华琛ㄧ洏涓庡浘琛ㄩ厤缃�俙archive`銆乣finance`銆乣research`銆乣ums`銆乣wxcp` 鍦ㄥ綋鍓嶆簮鐮佷腑缂哄皯鍙洿鎺ヨ瘉鏄庣殑绠＄悊绔帶鍒跺櫒锛屽厛鏀惧叆鑳藉姏鐩綍锛屽緟閫愪竴鏍稿疄鎺ュ彛鍚庡紑鏀俱��
+- `im` 涓� `member` 妯″潡铏芥湁浠ｇ爜锛岀幇鏈変笟鍔″湴鍥惧皢鍏跺垪涓轰富閾捐矾鏈秷璐规垨閬楃暀鑳藉姏銆傞粯璁や笉鎶婂畠浠綔涓洪鎵圭敓浜у伐鍏枫��
+
+## 2. 鎬讳綋鏋舵瀯
+
+```mermaid
+flowchart LR
+    U[Vue / 绉诲姩绔� / 鍗曟嵁鎸夐挳] --> J[Java 鏅鸿兘浣撶綉鍏砞
+    J --> P[Python FastAPI 鏅鸿兘浣撴湇鍔
+    P --> O[浠诲姟缂栨帓涓庣姸鎬佹満]
+    O --> R[棰嗗煙宸ュ叿鐩綍]
+    O --> K[鐭ヨ瘑妫�绱
+    O --> M[妯″瀷涓庤鍒� / 棰勬祴鍣╙
+    R --> J
+    J --> B[鐜版湁 Java 涓氬姟 Service / API]
+    B --> D[(涓氬姟搴�)]
+    O --> A[(鏅鸿兘浣撲細璇� / 璇佹嵁 / 瀹¤)]
+    O --> H[浜哄伐瀹℃壒闃熷垪]
+    H --> J
+```
+
+**璐ｄ换鍒掑垎**
+
+| 灞� | 鑱岃矗 | 涓嶆壙鎷� |
+| --- | --- | --- |
+| Java 鏅鸿兘浣撶綉鍏� | 鐜版湁鐧诲綍鎬併�丷BAC銆佹暟鎹寖鍥淬�佷笟鍔� API 灏佽銆佸鎵逛笌骞傜瓑鍐欏叆 | 妯″瀷鎺ㄧ悊涓庤法鍩熻鍒� |
+| Python 鏅鸿兘浣撴湇鍔� | 鎰忓浘璺敱銆佸伐鍏疯鍒掋�佽瘉鎹眹鎬汇�佺害鏉熸牎楠屻�佸缓璁敓鎴愩�佷細璇濆璁� | 鐩磋繛骞朵慨鏀逛笟鍔¤〃銆佺粫杩� BPM |
+| 棰嗗煙宸ュ叿 | 缁撴瀯鍖栨煡璇€�佽绠椼�佹ā鎷熶笌鍙楁帶鍛戒护锛涙瘡涓伐鍏峰０鏄庢潈闄愩�佸瓧娈靛拰鐗堟湰 | 杩斿洖涓嶅彈鎺х殑鏁村簱鏁版嵁 |
+| 鐭ヨ瘑灞� | SOP銆佸伐鑹恒�佽川妫�瑙勮寖銆佷骇鍝佹墜鍐屻�佸埗搴︾瓑鏂囨。妫�绱� | 鎶婄煡璇嗘枃妗ｅ綋浣滃疄鏃跺簱瀛樻垨瀹℃壒鐘舵�� |
+| 瑙勫垯涓庢ā鍨嬪眰 | 纭畾鎬ф牎楠屻�侀娴嬫ā鍨嬨�丩LM 璇█瑙ｉ噴 | 璁� LLM 鍐冲畾纭�т笟鍔¤鍒� |
+
+鍏抽敭璇锋眰涓婁笅鏂囷細`user_id`銆侀儴闂�/鏁版嵁鑼冨洿銆乣tenant_id`锛堝嵆浣垮綋鍓嶅叧闂篃淇濈暀瀛楁锛夈�乣task_id`銆乣trace_id`銆佸満鏅�佷笟鍔″璞″紩鐢ㄥ拰鏉冮檺蹇収銆侾ython 涓嶅彲淇′换鍓嶇浼犲叆鐨勬潈闄愬０鏄庯紱姣忔宸ュ叿璋冪敤鐢� Java 鏈嶅姟绔寜褰撳墠鐢ㄦ埛閲嶆柊閴存潈銆�
+
+## 3. 棰嗗煙鑳藉姏鍥捐氨
+
+涓嬭〃鏄�**鐩爣宸ュ叿鐩綍**锛屼笉鏄鐜版湁鎺ュ彛鍧囧凡鍙敤鐨勫０鏄庛�傛瘡琛屽厛浜や粯鍙宸ュ叿鍜屽紩鐢ㄩ摼鎺ワ紝鍐欏姩浣滃彟琛岃繘琛屾帴鍙ｄ笌鏉冮檺鏍稿疄銆�
+
+| 棰嗗煙 | 棣栨壒鍙鑳藉姏 | 鍚庣画寤鸿鎴栧鎵瑰姩浣� |
+| --- | --- | --- |
+| MDM 涓绘暟鎹� | 鐗╂枡/SKU銆佽閲忓崟浣嶃�佷粨搴撱�佹壒娆″睘鎬ф煡璇紱缂栫爜娑堟 | 涓绘暟鎹噸澶嶉」淇寤鸿 |
+| CRM 閿�鍞� | 瀹㈡埛銆佸晢鏈恒�佹姤浠枫�佸悎鍚屻�佸洖娆捐鍒掋�侀攢鍞洰鏍囨憳瑕� | 璺熻繘寤鸿銆佸悎鍚岄闄╂彁绀恒�佹姤浠疯崏绋� |
+| SRM 渚涘簲鍟� | 渚涘簲鍟嗚祫璐ㄣ�佹嫑鎶曟爣銆佷氦浠樹笌缁╂晥鏌ヨ | 璧勮川鍒版湡鎻愰啋銆佸�欓�変緵搴斿晢姣旇緝 |
+| ERP 閲囪喘/閿�鍞�/璧勯噾 | 閲囪喘鐢宠涓庤鍗曘�佹潵绁ㄤ粯娆俱�侀攢鍞鍗曘�佹敹娆剧姸鎬� | 缂鸿揣閲囪喘寤鸿銆佽鍗曞紓甯歌В閲娿�佸璐﹀�欓�夐」 |
+| MES 鐢熶骇 | MPS銆佸伐鍗曘�佸伐搴忎换鍔°�佹姤宸ャ�佸伐鑹鸿矾绾裤�佸伐鍗� BOM | 缂烘枡/宸ユ椂/椋庨櫓/浜や粯棰勬祴鏁村悎锛屾帓绋嬫柟妗堟ā鎷� |
+| MES 浠撳偍 | 搴撳瓨缁村害銆佸崰鐢ㄣ�佸喕缁撱�佹壒娆�/SN銆佸嚭鍏ュ簱浜嬪姟 | 璋冩嫧/琛ヨ揣寤鸿锛岃拷婧摼鐢熸垚 |
+| MES 璐ㄩ噺 | IQC/IPQC/OQC/RQC銆佹寚鏍囥�佺己闄枫�丯CR | 妫�楠屽垽瀹氬缓璁�佸紓甯稿綊鍥犮�丯CR 澶勭疆鑽夌 |
+| 璐ㄦ鎶ュ憡 | 妯℃澘鐗堟湰銆佹姤鍛婂疄渚嬨�佸喕缁撳揩鐓у紩鐢� | 鎶ュ憡缂哄彛瑙ｉ噴涓庣敓鎴愬墠妫�鏌� |
+| 璁惧/宸ヨ/鎺掔彮/鑳借�� | 璁惧鐘舵�併�佺偣妫�/缁翠慨銆佸伐瑁呫�佺彮缁勩�佽兘鑰楄褰� | 缁翠慨浼樺厛绾с�佽澶囬闄┿�佹帓鐝啿绐佸缓璁� |
+| 鍞悗 | 宸ュ崟銆佺淮淇�侀��璐с�佽川妫�涓庨��娆惧洖璋冪姸鎬� | 瀹㈣瘔褰掑洜銆侀��璐ц繘搴﹁В閲娿�佸鐞嗚崏绋� |
+| HRM | 浜哄憳鍙敤鎬с�佹帓鐝�佽�冨嫟涓庝氦鎺ョ姸鎬佺殑鏈�灏忓繀瑕佹憳瑕� | 浜哄姏缂哄彛寤鸿锛涜柂閰暟鎹粯璁や笉杩涘叆閫氱敤浼氳瘽 |
+| BPM | 娴佺▼瀹炰緥銆佸綋鍓嶄换鍔°�佸鎵硅建杩广�佷笟鍔″洖璋冪姸鎬� | 寰呭姙瑙ｉ噴銆佸鎵规潗鏂欑己鍙ｆ彁绀猴紱瀹℃壒鍐冲畾浠嶇敱瀹℃壒浜烘墽琛� |
+| BI | 鎸囨爣瀹氫箟銆佷华琛ㄧ洏鑱氬悎缁撴灉 | 璺ㄥ煙缁忚惀瑙ｉ噴銆佸紓甯搁捇鍙栥�佹寚鏍囧彛寰勫紩鐢� |
+| AI/鐭ヨ瘑 | 鐜版湁妯″瀷涓庣煡璇嗗簱銆丱CR/棰勬祴璋冪敤鐧昏 | 缁熶竴妯″瀷缃戝叧銆佹彁绀鸿瘝鐗堟湰涓庤瘎浼� |
+| System/Infra | 鐢ㄦ埛鍙鑼冨洿銆佸瓧鍏搞�侀檮浠跺紩鐢ㄣ�佷换鍔�/瀹¤鏃ュ織 | 绠＄悊閰嶇疆寤鸿锛涢珮鏉冮檺宸ュ叿鍗曠嫭瀹℃壒 |
+| Archive/Finance/Research/UMS/WXCP | 寤虹珛妯″潡娓呭崟銆佹牳瀹炴槸鍚︽湁涓氬姟 API | 鏈夊疄闄呮帴鍙ｄ笌璐ｄ换浜哄悗鍔犲叆宸ュ叿鐩綍 |
+| IM/Member | 淇濈暀鍏煎鍏ュ彛锛屼笉鍦ㄩ粯璁や笟鍔″姪鎵嬫悳绱㈣寖鍥村唴 | 涓氬姟纭鍚敤鍚庡啀鎺ュ叆 |
+
+**璺ㄥ煙璇箟灞�**缁熶竴浣跨敤 `BusinessRef(module, object_type, id, code)` 鍜屼笟鍔′簨浠跺叧绯伙紝閬垮厤鍦ㄦ彁绀鸿瘝涓嫾鎺ヨ〃鍚嶃�備紭鍏堣繛鎺モ�滈攢鍞鍗曗啋MPS鈫掑伐鍗曗啋棰嗘枡/鎶ュ伐鈫掕川妫�鈫掑叆搴�/鍑哄簱鈫掑洖娆�/鍞悗鈥濈瓑鐪熷疄鍗曟嵁寮曠敤锛涙病鏈夌‘瀹氬叧鑱旀椂鏄庣‘鏄剧ず鈥滃緟鏍稿疄鈥濓紝涓嶉潬鍚嶇О鐚滄祴銆�
+
+## 4. 涓変釜棣栬璺ㄦā鍧楀満鏅�
+
+### A. 璁㈠崟浜や粯椋庨櫓
+
+杈撳叆閿�鍞鍗曟垨鍚堝悓缂栧彿銆傝鍙� CRM 鍚堝悓銆丒RP 閿�鍞鍗曘�丮PS/宸ュ崟/鎶ュ伐銆佸簱瀛樺崰鐢ㄣ�侀噰璐埌璐с�佽澶囧仠鏈恒�佽川妫�闃绘柇涓庡巻鍙蹭氦浠樸�傜‘瀹氭�ц绠楃己鍙ｅ拰棰勮瀹屾垚鑼冨洿锛涙ā鍨嬭鏄庝富瑕侀闄┿�佽瘉鎹�佷笅涓�姝ヤ笌璐ｄ换宀椾綅銆傝緭鍑烘槸鈥滈闄╁崱 + 璇佹嵁寮曠敤 + 鍙�夊鐞嗘柟妗堚�濓紝鎺掔▼鎴栭噰璐粎鐢熸垚鑽夌銆�
+
+### B. 璐ㄩ噺寮傚父杩芥函
+
+杈撳叆 IQC/IPQC/OQC/RQC/NCR 鎴栨壒娆″彿銆傛部渚涘簲鍟嗐�佹潵鏂欍�佸簱瀛樻壒娆°�佸伐鍗曞伐搴忋�佽澶囥�佹楠屾寚鏍囥�侀攢鍞嚭搴撳拰鍞悗閾捐矾杩芥函銆傝緭鍑哄奖鍝嶆壒娆�/璁㈠崟娓呭崟銆佹椂闂寸嚎銆佸凡鐭ヤ笌鏈煡鐜妭銆備换浣曞簱瀛樺喕缁撱�佽繑宸ャ�侀��璐у拰鎶ュ簾鍔ㄤ綔杩涘叆鍘熸湁瀹℃壒娴併��
+
+### C. 缁忚惀涓庣幇鍦哄紓甯搁棶绛�
+
+鐢ㄦ埛鎻愰棶鈥滄湰鍛ㄤ氦浠樹负浣曚笅闄嶏紵鈥濅箣绫婚棶棰樸�傚厛璇嗗埆鍙闂殑 BI 鎸囨爣鍙ｅ緞锛屽啀鏌ヨ仛鍚堟暟鎹拰鐩稿叧鍗曟嵁锛屽紩鐢ㄥ叿浣撴椂闂磋寖鍥翠笌鏉ユ簮銆傚尯鍒嗕簨瀹炪�佽绠楃粨鏋滀笌鎺ㄦ祴锛涙病鏈夎冻澶熸暟鎹椂缁欏嚭缂哄け娓呭崟銆傝鍏ュ彛鍙鐩栧叏閮ㄥ凡鎺ュ叆妯″潡锛屼絾浠呰繑鍥炵敤鎴峰彲瑙佺殑鏁版嵁銆�
+
+## 5. 鏅鸿兘浣撳伐浣滄満鍒�
+
+```text
+鎺ユ敹浠诲姟 鈫� 閴存潈/璇嗗埆涓氬姟瀵硅薄 鈫� 閫夌敤鍦烘櫙妯℃澘 鈫� 瑙勫垝鍙宸ュ叿
+鈫� 骞惰鍙栬瘉 鈫� 鏍￠獙鏃堕棿銆佸崟浣嶃�佸彛寰勪笌鍏宠仈 鈫� 瑙勫垯/棰勬祴璁＄畻
+鈫� 鐢熸垚甯︽潵婧愮殑绛旀/鏂规 鈫� 濡傞渶鍐欏叆鍒欏舰鎴愬緟瀹℃壒鍛戒护
+鈫� Java 鍐嶉壌鏉冧笌涓氬姟鏍￠獙 鈫� BPM/浜哄伐纭 鈫� 鎵ц骞跺洖璇荤粨鏋�
+```
+
+宸ュ叿璋冪敤浣跨敤 JSON Schema/Pydantic 杈撳叆杈撳嚭銆傛瘡涓伐鍏风櫥璁帮細`name`銆乣domain`銆乣read_or_write`銆乣permission`銆乣data_scope`銆乣timeout`銆乣schema_version`銆乣idempotency_key`銆傛煡璇㈤粯璁ゅ垎椤典笌闄愭椂锛涜法鍩熶换鍔￠檺鍒舵渶澶ф楠ゃ�佹渶澶у伐鍏疯皟鐢ㄦ鏁板拰鎴愭湰銆傚け璐ユ椂杩斿洖宸叉牳瀹為儴鍒嗕笌缂哄け璇佹嵁锛屼笉浼�犵粨璁恒��
+
+杈撳嚭缁熶竴涓� `answer`銆乣facts[]`銆乣inferences[]`銆乣unknowns[]`銆乣citations[]`銆乣risk_level`銆乣proposed_actions[]`銆乣approval_required`銆傛瘡鏉℃潵婧愬寘鍚笟鍔″璞°�佹帴鍙ｇ増鏈�侀噰闆嗘椂闂村拰鍙湪鍘熺郴缁熸墦寮�鐨勯摼鎺ャ�傚浜庨噾棰濄�佸簱瀛樸�佸悎鏍煎垽瀹氥�佸鎵规潈闄愮瓑纭害鏉燂紝浠ヤ笟鍔℃湇鍔¤繑鍥炵殑瑙勫垯鍜岀姸鎬佷负鍑嗐��
+
+## 6. Python 椤圭洰缁撴瀯锛堟嫙锛�
+
+```text
+industrial-agent/
+  pyproject.toml
+  src/industrial_agent/
+    api/                 # FastAPI 璺敱锛氫細璇濄�佷换鍔°�佸鎵硅崏绋裤�佸仴搴锋鏌�
+    core/                # 鐘舵�佹満銆佽鍒掑櫒銆佸伐鍏疯皟搴︺�佷笂涓嬫枃銆佸璁�
+    contracts/           # Pydantic DTO 涓庣増鏈寲宸ュ叿濂戠害
+    domains/             # mdm/crm/srm/erp/mes/qc/aftersales/hrm/bpm/bi ...
+    workflows/           # 浜や粯椋庨櫓銆佽川閲忚拷婧�佽法鍩熼棶绛�
+    integrations/        # Java 缃戝叧銆佹ā鍨嬨�佺煡璇嗗簱銆佷簨浠舵�荤嚎閫傞厤鍣�
+    policies/            # 鏉冮檺鑼冨洿銆佹晱鎰熷瓧娈点�佸鎵归棬妲涖�侀绠�
+    evaluation/          # 鍦烘櫙鏍锋湰銆佸洖褰掓寚鏍囥�佺粨鏋滄爣娉�
+  tests/
+  docs/
+```
+
+寤鸿閫夌敤 Python 3.11+銆丗astAPI銆丳ydantic銆乭ttpx锛涗换鍔＄姸鎬佷笌瀹¤瀛樺偍閲囩敤浠撳簱鐜版湁 MySQL/Redis 浣撶郴锛屼絾浣跨敤鐙珛 schema/琛ㄥ拰鏈嶅姟璐﹀彿锛屼笉鐩存帴淇敼涓氬姟琛ㄣ�傛ā鍨嬮�傞厤灞傚吋瀹瑰凡鏈� AI 妯″瀷閰嶇疆锛屽叿浣撳鐢ㄦ柟寮忚鍦ㄥ疄鏂藉墠鏍稿璁よ瘉涓� API銆俁AG 鍙互鍏堟秷璐圭幇鏈� AI 鐭ヨ瘑搴撹兘鍔涳紝涓嶉璁惧啀娆￠儴缃插悜閲忓簱銆�
+
+### Java 鈫� Python 濂戠害鑽夋
+
+- `POST /agent/tasks`锛氬甫涓氬姟瀵硅薄寮曠敤涓庣敤鎴锋剰鍥撅紝杩斿洖 `task_id`銆�
+- `GET /agent/tasks/{id}`锛氭祦寮忔垨杞鑾峰彇鐘舵�併�佽瘉鎹拰缁撴灉銆�
+- `POST /agent/tasks/{id}/proposals`锛氱敓鎴愮粨鏋勫寲寰呭鎵瑰懡浠わ紱涓嶇洿鎺ュ啓涓氬姟鍗曟嵁銆�
+- `POST /agent/tasks/{id}/approve`锛氱敱 Java 缃戝叧涓� BPM 澶勭悊瀹℃壒锛屼笉鎺ュ彈 Python 鑷姤瀹℃壒閫氳繃銆�
+- 棰嗗煙宸ュ叿鐢� Java 缃戝叧鏆撮湶鍐呴儴 API锛岃繑鍥炴渶灏忓瓧娈甸泦銆佹潈闄愯繃婊ょ粨鏋滃強 `source_ref`锛涘唴閮ㄩ�氫俊浣跨敤鏈嶅姟璁よ瘉锛岀敤鎴蜂笂涓嬫枃鐢辩綉鍏崇鍙戝苟闄愭椂銆�
+
+## 7. 鏂规閫夋嫨
+
+| 鏂规 | 褰㈡�� | 浼樼偣 | 浠ｄ环/閫傜敤鎯呭喌 |
+| --- | --- | --- | --- |
+| A锛氱粺涓�闂瓟灞� | Python 鏈嶅姟鍙皟鍙宸ュ叿鍜岀煡璇嗗簱 | 鎺ュ叆蹇�侀闄╀綆锛岄�傚悎鍏堝仛缁熶竴鍏ュ彛 | 寰堥毦瑕嗙洊瀹℃壒涓庢墽琛岄棴鐜� |
+| **B锛氬钩鍙� + 棰嗗煙鑳藉姏鍖咃紙鎺ㄨ崘锛�** | 缁熶竴浠诲姟缂栨帓銆侀鍩熷伐鍏枫�佽法鍩熷伐浣滄祦銆佸垎绾у鎵� | 鑳介�愭瑕嗙洊鎵�鏈変笟鍔★紝鍙堜繚鐣欏悇妯″潡瑙勫垯 | 闇�瑕佸缓璁� Java 缃戝叧鍜屽伐鍏峰绾� |
+| C锛氬鑷不鏅鸿兘浣撶兢 | 姣忎釜棰嗗煙鐙珛瑙勫垝涓庡崗鍟� | 棰嗗煙鍥㈤槦鍙嫭绔嬫紨杩� | 鍗忚皟銆佸璁°�佹潈闄愬拰缁撴灉涓�鑷存�у鏉傦紝褰撳墠涓嶅疁鐩存帴浣滀负棣栫増 |
+
+鎺ㄨ崘 B 鐨勭涓�闃舵鍙杩愯锛屼繚鐣欐湭鏉ヤ粠鍗曚竴缂栨帓鍣ㄥ彂灞曚负棰嗗煙涓撻暱鏅鸿兘浣撶殑鎺ュ彛銆傞�夋嫨鏂规鏃堕噸鐐规瘮杈冿細鎯冲厛瑙ｅ喅鐨勮法鍩熶换鍔°�佺幇鏈� Java API 鐨勫彲澶嶇敤绋嬪害銆佹槸鍚﹀厑璁告櫤鑳戒綋鎻愪氦瀹℃壒鑽夌锛屼互鍙婁笂绾挎湡闄愩��
+
+## 8. 鍒嗛樁娈佃惤鍦颁笌楠屾敹
+
+1. **涓氬姟鍜屾帴鍙ｇ洏鐐�**锛氶�愭ā鍧楁爣璁扳�滃凡楠岃瘉 API / 闇�鏂板 API / 鏆傛棤涓氬姟鍏ュ彛鈥濓紱缁樺埗瀵硅薄鍏崇郴涓庢潈闄愯竟鐣屻�傞獙鏀讹細姣忎釜鐩爣宸ュ叿閮芥湁涓氬姟璐熻矗浜恒�佹潵婧愭帴鍙ｃ�佸瓧娈点�佹暟鎹寖鍥村拰娴嬭瘯鏍蜂緥銆�
+2. **骞冲彴楠ㄦ灦**锛歅ython API銆佸伐鍏锋敞鍐屻�佷换鍔＄姸鎬佹満銆佸璁°�佹ā鍨嬮�傞厤銆佸彧璇� Java 缃戝叧銆傞獙鏀讹細瓒婃潈璇锋眰琚嫆缁濓紱鏁呴殰鍙拷韪埌 `trace_id`锛涚瓟妗堟湁鏉ユ簮閾炬帴銆�
+3. **妯悜瑕嗙洊**锛氭帴鍏ヤ笂杩版墍鏈夊疄闄呬笟鍔℃ā鍧楃殑鍙鐩綍涓庤嚦灏戜竴涓叧閿煡璇紝鏈疄鐜版ā鍧楁槑纭爣璁颁笉鍙敤銆傞獙鏀讹細妯″潡鑳藉姏娓呭崟鍙嚜鍔ㄦ鏌ワ紝涓嶅皢绌烘ā鍧楀睍绀烘垚宸叉帴鍏ャ��
+4. **娣卞害鍦烘櫙**锛氫紭鍏堜氦浠橀闄╀笌璐ㄩ噺杩芥函锛屽叾娆＄粡钀ラ棶绛斻�侀噰璐崗鍚屻�佽澶囩淮鎶ゃ�佸敭鍚庨棴鐜�傞獙鏀讹細涓庝汉宸ュ熀鍑嗙粨鏋滄瘮瀵逛簨瀹炴纭巼銆佸叧鑱斿噯纭巼銆佹紡鎶ョ巼鍜屽搷搴旀椂寤躲��
+5. **鍙楁帶鎵ц**锛氬彧瀵圭粡杩囦笟鍔¤瘎瀹＄殑鍛戒护寮�鏀捐崏绋�/鎻愪氦锛岀粡 Java 鍐嶉壌鏉冦�佸箓绛夋牎楠屼笌 BPM 瀹℃壒鍚庢墽琛屻�傞獙鏀讹細閲嶅璇锋眰涓嶉噸澶嶅缓鍗曪紱鎷掔粷瀹℃壒涓嶄骇鐢熶笟鍔″啓鍏ワ紱鍙寜鍗曟嵁鍥炴斁瀹¤閾俱��
+
+棣栨壒璇勪及闆嗗簲鍖呭惈缂烘枡銆侀噸澶嶅簱瀛樺崰鐢ㄣ�佽川妫�涓嶅悎鏍笺�佸凡瀛樺湪缁翠慨鍗曘�佽法閮ㄩ棬瓒婃潈銆佸凡鎾ら攢瀹℃壒銆佹暟鎹繃鏈熴�佹帴鍙ｈ秴鏃躲�佸叧鑱旀柇閾剧瓑妗堜緥銆備笂绾块噰鐢ㄨ瀵熸ā寮忥紝鍏堟瘮瀵瑰缓璁笌浜哄伐澶勭悊锛屽啀鎵╁ぇ鍙墽琛岃寖鍥淬��
+
+## 9. 寰呴�夋嫨涓庢鼎鑹茬殑闂
+
+1. 棣栦釜鍙紨绀洪棴鐜�夆�滆鍗曚氦浠橀闄┾�濄�佲�滆川閲忓紓甯歌拷婧�濊繕鏄�滆法鍩熺粡钀ラ棶绛斺�濓紵
+2. 绗竴鐗堟槸鍚﹀彧璇伙紝鎴栧厑璁稿垱寤�**寰呭鎵硅崏绋�**锛�
+3. 鐢ㄦ埛鍏ュ彛浼樺厛鏀惧叏灞�鍔╂墜銆佷笟鍔″崟鎹晶鏍忥紝杩樻槸涓よ�呭苟琛岋紵
+4. 妯″瀷閮ㄧ讲浼樺厛娌跨敤鐜版湁 `yudao-module-ai` 閰嶇疆锛岃繕鏄敱 Python 鐙珛绠＄悊锛熻繖闇�瑕佹牳瀵瑰綋鍓嶆ā鍨嬫湇鍔＄殑鍙皟鐢ㄦ帴鍙ｄ笌杩愮淮鏂瑰紡銆�
+
+浠ヤ笂閫夊畾鍚庯紝鍐嶆敹鏁涙帴鍙ｆ竻鍗曘�佷氦浜掓祦绋嬨�佹暟鎹簱琛ㄣ�侀儴缃插浘鍜岄獙鏀舵牱渚嬶紝褰㈡垚鍙疄鏂界増鏈��
diff --git a/docs/industrial-agent-scenario-blueprint.md b/docs/industrial-agent-scenario-blueprint.md
new file mode 100644
index 0000000..e8a4187
--- /dev/null
+++ b/docs/industrial-agent-scenario-blueprint.md
@@ -0,0 +1,189 @@
+# 宸ヤ笟鏅鸿兘浣撳満鏅摑鍥撅細浠庤鍗曞埌浜や粯
+
+> 鏂规娣卞寲绋裤�傚熀浜庣敤鎴风粰鍑虹殑鍦烘櫙绀烘剰鍥撅紝闈㈠悜鏈粨搴撶殑瀹為檯妯″潡鍜屾帴鍙ｉ噸鏂板畾涔夈�傚浘鐗囦腑鐨勬暟瀛椼�佸鎴枫�佽澶囧拰鎵ц鐘舵�佷粎浣滀氦浜掔ず渚嬶紝涓嶄唬琛ㄦ湰绯荤粺鐪熷疄鏁版嵁鎴栧凡瀹炵幇鍔熻兘銆傛湰鏂囧彧璁捐锛屼笉鏀瑰姩涓氬姟浠ｇ爜銆�
+
+宸ョ▼瀹炵幇鍙傝 [LangGraph 瀹氬埗鎶�鏈柟妗圿(industrial-agent-langgraph-technical-design.md)锛屽叾涓綈濂楀垎閰嶄笌搴撳瓨鍙ｅ緞鏄湰钃濆浘绠�鍖栧叕寮忕殑瀹炴柦缁嗗寲銆�
+
+鍓嶆湡鏁版嵁鍑嗗涓庢棩甯稿閲忚ˉ褰曠敱 [宸ヤ綔鏂囦欢琛ュ綍鏍稿績鑳藉姏](industrial-agent-document-onboarding-design.md) 鎵挎媴锛涙湭鏍稿疄鐨勬枃浠跺�欓�夋暟鎹笉鑳界洿鎺ヤ綔涓轰節鍦烘櫙涓殑褰撳墠涓氬姟浜嬪疄銆�
+
+## 涓�銆佷骇鍝佺洰鏍�
+
+鐢ㄦ埛瑕佺殑涓嶆槸鈥滆兘鍥炵瓟鍒堕�犱笟闂鐨勮亰澶╂鈥濓紝鑰屾槸涓�涓湪鐜版湁 CRM銆丒RP銆丼RM銆丮ES銆乄MS銆佽川妫�銆佽澶囥�佸敭鍚庛�丅PM 鍜� BI 涓婂伐浣滅殑**涓氬姟鎵ц鍔╃悊**锛氭寜璁″垝涓诲姩宸℃锛涚敤鎴锋彁闂椂鑳芥部璁㈠崟涓庢壒娆￠摼鎵捐瘉鎹紱缁欏嚭鍙牳绠楃殑缁撹锛涙妸闇�瑕佸鐞嗙殑浜嬮」浜ょ粰姝ｇ‘宀椾綅锛涙寔缁窡杩涘埌涓氬姟绯荤粺鍥炲啓瀹屾垚銆�
+
+涓�涓満鏅繀椤诲悓鏃跺叿澶囦簲閮ㄥ垎鎵嶇畻浜や粯锛�**瑙﹀彂鏉′欢 鈫� 涓氬姟鍙栬瘉 鈫� 纭畾鎬ц绠�/鍒ゆ柇 鈫� 鍙牳瀵圭殑缁撴灉 鈫� 浜烘満杈圭晫涓庡洖鍐�**銆傜晫闈笂鐨勨�滃凡鎵ц鈥濅粎鍦� Java 涓氬姟鎺ュ彛杩斿洖鐪熷疄涓氬姟鍗曞彿鍚庡嚭鐜般�傗�滈娴嬧�濃�滃缓璁�濃�滆崏绋库�濃�滃鎵逛腑鈥濃�滃凡鎵ц鈥濃�滃凡鍏抽棴鈥濇槸涓嶅悓鐘舵�侊紝涓嶈兘娣风敤銆�
+
+## 浜屻�佷節涓満鏅矾绾�
+
+| 缂栧彿 | 鍦烘櫙 | 瑙﹀彂 | 涓昏绯荤粺 | 绗竴鐗堜骇鐗� | 鍚庣画闂幆 |
+| --- | --- | --- | --- | --- | --- |
+| 01 | 鎺ュ崟璇勫涓庝氦鏈熺瓟澶� | 鍚堝悓/閿�鍞鍗曞垱寤烘垨浜ゆ湡鍙樻洿 | CRM銆丒RP銆丮ES銆乄MS | 鏈�鏃╁彲鎵胯鏃ヤ笌鍐茬獊娓呭崟 | 璇勫鍗曘�佺瓟澶嶈崏绋裤�佷汉宸ュ彂閫� |
+| 02 | 寮�宸ラ綈濂椾笌缂烘枡鍌氦 | 娆℃棩宸ュ崟瀹氭椂宸℃/宸ュ崟涓嬪彂 | MES銆乄MS銆丒RP銆丼RM | 榻愬鐜囥�佸噣缂哄彛銆侀噰璐叧鑱� | 鍌氦寰呭姙銆佸洖鎵т笌鍐嶆璁＄畻 |
+| 03 | 宸ュ崟瓒呮湡宸℃ | 姣忕彮/姣忔棩宸℃鍜屾姤宸ュ彉鍖� | MES銆佹帓鐝�佽澶� | 鐪熻秴鏈熷伐鍗曘�佸崱鐐逛笌璐ｄ换缁� | 鎸囨淳寰呭姙銆佽秴鏃跺崌绾� |
+| 04 | 鎻掑崟涓庢帓绋嬮噸绠� | 鎬ュ崟鐢宠/璧勬簮鎴栬澶囧彉鍖� | CRM銆丒RP銆丮ES銆佽澶囥�佹帓鐝� | 涓ゅ鎺掔▼鏂规涓庡彈褰卞搷璁㈠崟 | 浜哄鍚庤皟鐢ㄧ幇鏈夋帓绋嬫湇鍔� |
+| 05 | 鍙戣揣涓庝粨鍌ㄦ嫤鎴� | 鍙戣揣閫氱煡/鍑哄簱鍓嶆鏌� | WMS銆丒RP銆丱QC銆佹壒娆�/SN | 鍙彂鏁伴噺銆侀樆鏂師鍥犮�佷綅缃� | 鎷ｈ揣/鍙戣揣寤鸿锛屽崟鎹収鍘熷鎵� |
+| 06 | 璐ㄩ噺寮傚父涓庡仠绾垮楠� | IPQC 瓒婇檺/NCR/璁惧妫�楠屼簨浠� | MES-QC銆佸伐鍗曘�佷粨鍌ㄣ�佽澶� | 褰卞搷鎵规鍜屽凡娴佽浆鑼冨洿 | 闅旂寤鸿銆佸楠屽緟鍔炪�佸仠绾跨敵璇峰緟绛� |
+| 07 | 璁惧婕忔涓庝繚鍏� | 鐐规鏃剁獥/杩愯鏃堕暱鍒版湡 | 璁惧銆佸伐鍗曘�佹帓鐝� | 婕忔娓呭崟鍜屽叧閿澶囨帓搴� | 淇濆吇/琛ユ寰呭姙涓庣淮淇洖鎵� |
+| 08 | 濮斿鍔犲伐瀵硅处 | 鏈堢粨鎴栧鍗忓崟瀹岀粨 | MES-WM銆丒RP銆丼RM | 鍙戞敹鑰楁崯涓庝环鏍煎樊寮傛竻鍗� | 閲囪喘鏍稿疄銆佽储鍔″鎵瑰悗缁撶畻 |
+| 09 | 瀹㈣瘔鎵规杩芥函 | 鍞悗宸ュ崟/瀹㈡埛鎵瑰彿鎻愰棶 | 鍞悗銆丒RP銆乄MS銆丮ES-QC | 姝ｅ弽鍚戣拷婧浘銆佸彈褰卞搷瀹㈡埛 | 鍥炲鑽夌銆佺己璇佹嵁浠诲姟 |
+
+妯悜鑳藉姏鍖呮嫭**宸ュ崟鎴愭湰褰掗泦**銆�**缁忚惀寮傚父闂瓟**銆�**鏃�/鍛ㄦ姤鐢熸垚**銆傝繖浜涘彲娑堣垂涔濅釜鍦烘櫙鐨勫彲淇＄粨鏋滐紝浣嗘垚鏈牳绠楅』鍏堢‘璁ゆ潗鏂欎环銆佸伐鏃惰垂鐜囥�佸澶栬垂鐢ㄣ�佹湡闂村彛寰勫拰璐㈠姟璐ｄ换浜猴紝涓嶈兘鐩存帴鎶婃姤宸ユ椂鏁颁箻涓�涓寽娴嬭垂鐜囥��
+
+## 涓夈�佸満鏅粏鍖�
+
+### 01 鎺ュ崟璇勫涓庝氦鏈熺瓟澶�
+
+- **鍏稿瀷闂彞**锛氣�滃鎴疯鎶婅繖鍗曟彁鍓嶅埌 15 鍙凤紝鑳界瓟搴斿悧锛熲��
+- **鍙栬瘉**锛欳RM 鍚堝悓/瀹㈡埛瑕佹眰銆丒RP 閿�鍞鍗曡銆丮ES MPS/宸ュ崟涓庡伐鑹鸿矾绾裤�佸伐鍗� BOM銆乄MS 鍙敤搴撳瓨鍜屽崰鐢ㄣ�佸湪閫旈噰璐笌璁惧/鐝鑳藉姏銆傚叏閮ㄤ互鍚屼竴璁㈠崟琛屻�佷骇鍝� SKU銆佹暟閲忓拰鍗曚綅涓哄熀鍑嗐��
+- **璁＄畻**锛歚鏈�鏃╃墿鏂欓綈濂楁椂闂碻 涓庡悇宸ュ簭鍙敤浜ц兘绐楀彛缁撳悎锛屾ā鎷熸渶鏃╁畬宸ヤ笌 OQC/鍑哄簱鏃堕棿锛涙壙璇烘棩瑕佸姞涓婇厤缃殑妫�楠屼笌鐗╂祦鎻愬墠鏈熴�傜幇鏈夌敓浜� AI 浜や粯棰勬祴鍙綔鍙傝�冿紝涓嶈兘鏇夸唬鎺掔▼涓庡簱瀛樼‖绾︽潫銆�
+- **缁撴灉**锛氬彲鎵胯鏃ヨ寖鍥淬�佺浉瀵瑰鎴疯姹傜殑宸銆佸彈褰卞搷宸ュ崟銆佸叧閿矾寰勫拰璇佹嵁鏃堕棿銆傝嫢璁＄畻涓嶅彲琛岋紝鍒楀嚭鈥滃姞鐝�/璋冭澶�/鎸崟鈥濇柟妗堝強姣忎釜鏂规鎸ゅ崰鍝簺璁㈠崟銆�
+- **鍔ㄤ綔杈圭晫**锛氱敓鎴愭帴鍗曡瘎瀹¤崏绋垮拰瀹㈡埛鍥炲鑽夌锛涢攢鍞�/璁″垝鍛橀�夋嫨鏂规锛屽悎鍚屽彉鏇村強瀹㈡埛娑堟伅蹇呴』鐢辨巿鏉冧汉鎻愪氦銆傜郴缁熻褰曢噰鐢ㄤ簡鍝釜鐗堟湰鐨勬帓绋嬫暟鎹��
+- **缂哄彛**锛氶渶瑕佺粺涓�鐨勮鍗曞埌宸ュ崟鍏宠仈鏌ヨ銆佸簱瀛樺彲鐢ㄩ噺鍙ｅ緞銆佹帓绋嬫ā鎷熺粨鏋滅殑鐗堟湰蹇収銆佷氦鏈熷洖澶嶅鎵逛笌鍙戦�佸叆鍙ｃ��
+
+### 02 寮�宸ラ綈濂椾笌缂烘枡鍌氦
+
+- **鍏稿瀷闂彞**锛氣�滄槑澶╄寮�鐨勫伐鍗曪紝鍝簺鏂欓綈浜嗭紵鈥�
+- **鍙栬瘉**锛氬凡鎵瑰噯宸ュ崟 BOM 鐗堟湰銆佸伐鍗曢渶姹傞噺銆乄MS 搴撳瓨鐨勪粨搴�/搴撲綅/鎵规/鍐荤粨/鍗犵敤銆侀鏂欒褰曘�侀噰璐鍗曟湭鍒版暟閲忋�佷緵搴斿晢浜ゆ湡銆�
+- **璁＄畻**锛氶�愮墿鏂欒绠� `鍑�鍙敤 = 鍚堟牸鐜板瓨 鈭� 宸插崰鐢� 鈭� 鍐荤粨 鈭� 涓嶅彲鐢ㄦ壒娆锛宍鍑�缂哄彛 = max(闇�姹� 鈭� 宸查 鈭� 鍑�鍙敤, 0)`锛涙寜鐩稿悓鐗╂枡銆佸崟浣嶃�侀噰璐潵婧愬悎骞剁己鍙ｏ紝鍚屾椂淇濈暀宸ュ崟鍒嗘憡鏄庣粏銆備笉鑳芥妸鈥滃湪閫斺�濈洿鎺ヨ鍏ョ幇瀛樸��
+- **缁撴灉**锛氬伐鍗曠骇榻愬/娆犳枡鍒嗙被銆佹寜鐗╂枡鍚堝苟鐨勯噰璐偓浜ゆ竻鍗曘�佷緵搴斿晢鎵胯鏃ヤ笌寮�宸ユ椂闂村樊銆佹棤閲囪喘鍗曟垨浜ゆ湡涓嶆槑椤圭洰銆�
+- **鍔ㄤ綔杈圭晫**锛氬彲鑷姩鐢熸垚閲囪喘鍐呴儴寰呭姙骞舵彁閱掕矗浠讳汉锛涢噰璐敼浜ゆ湡銆佷笅鍗曘�佹浛鏂欍�佺壒閲囬』璧板師涓氬姟瀹℃壒銆傛瘡娆￠噰璐洖鎵�/鍏ュ簱鍚庨噸绠楀苟鏄剧ず鍙樺寲銆�
+- **缂哄彛**锛氱幇鏈夊簱瀛樹笌 BOM 鎺ュ彛闇�鑱氬悎鎴愪竴娆″彲澶嶇敤榻愬蹇収锛涘偓浜ゅ緟鍔炲拰渚涘簲鍟嗗洖鎵ч渶瑕佹槑纭郴缁熷唴鎵胯浇鏂瑰紡銆�
+
+### 03 宸ュ崟瓒呮湡宸℃
+
+- **鍏稿瀷闂彞**锛氣�滀粖澶╂湁鍝簺宸ュ崟璺熶笉涓婅鍒掞紵鈥�
+- **鍙栬瘉**锛氬伐鍗曞伐搴忚鍒掕妭鐐广�佹姤宸ュ鎵瑰悗鐨勫疄闄呭畬鎴愰噺銆佽澶囧仠鏈恒�佺彮娆℃棩鍘嗐�佸伐鍗曠姸鎬併�佽矗浠荤彮缁勩��
+- **璁＄畻**锛氭帓闄ゅ凡瀹屾垚/鍙栨秷/鏀规湡骞堕噸鏂板熀绾跨殑宸ュ崟锛涗粎鍦ㄨ鍒掕妭鐐瑰埌鏈熶笖瀹為檯杩涘害涓嶈冻鏃跺垽瓒呮湡銆傝繛缁袱鐝棤鏈夋晥鎶ュ伐鏄崟鐙闄╋紝涓嶈兘鑷姩绛夊悓鈥滄病骞叉椿鈥濓紝杩樿鏍稿鎶ュ伐瀹℃壒涓笌绂荤嚎琛ユ姤銆�
+- **缁撴灉**锛氳秴鏈熸竻鍗曘�侀璁″欢璇噺銆佸崱浣忕殑宸ュ簭銆佽繛缁湭杩涘睍鏃堕暱銆佽矗浠荤粍銆佷笅娓镐氦浠樺奖鍝嶃��
+- **鍔ㄤ綔杈圭晫**锛氱敓鎴愮彮缁勯暱寰呭姙銆佹埅姝㈡椂闂淬�佹湭鍥炲鍗囩骇瑙勫垯锛涗换浣曠彮缁勭哗鏁堝垽鏂敱涓荤纭銆傜姸鎬佺敱寰呭姙鍥炴墽鍙婃柊鎶ュ伐鑷姩鏇存柊銆�
+- **缂哄彛**锛氶渶瑕佺粺涓�璁″垝鑺傜偣涓庡疄闄呰繘搴︾殑鏃堕棿鍙ｅ緞銆侀�炬湡鍩虹嚎鐗堟湰锛屼互鍙婁笌鐜版湁閫氱煡/浠诲姟绯荤粺鐨勫鎺ャ��
+
+### 04 鎻掑崟涓庢帓绋嬮噸绠�
+
+- **鍏稿瀷闂彞**锛氣�滄妸杩欎釜鎬ュ崟鎻掕繘鍘伙紝浼氬奖鍝嶈皝锛熲��
+- **鍙栬瘉**锛氳鍗曚紭鍏堢骇銆佸凡鎵胯浜ゆ湡銆佸湪鍒跺伐鍗曘�佸伐鑹鸿矾绾夸笌璁惧鏁堢巼銆佽澶囩淮鎶ょ獥鍙ｃ�佺彮缁勬帓鐝�佺墿鏂欓綈濂楁儏鍐点��
+- **璁＄畻**锛氫娇鐢ㄧ幇鏈夋帓绋嬮瑙堣兘鍔涚敓鎴愨�滀繚鎸佺幇鐘垛�濅笌鈥滄彃鍗曟柟妗堚�濅袱浠藉揩鐓э紝閫愬伐鍗曟瘮杈冨紑濮�/缁撴潫鏃堕棿銆佽澶囧崰鐢ㄣ�佹敼鏈熷ぉ鏁板拰宸叉壙璇哄鎴枫��
+- **缁撴灉**锛氬彈鐩婅鍗曘�佸彈鎹熻鍗曘�佷笉鍙敤璧勬簮銆侀渶鍚屾剰鐨勫矖浣嶃�佹帓绋嬪彉鍖栧浘锛涙棤娉曟弧瓒崇害鏉熸椂杩斿洖鍘熷洜锛屼笉杈撳嚭鈥滃凡瀹夋帓鈥濄��
+- **鍔ㄤ綔杈圭晫**锛氳鍒掑憳纭銆佸繀瑕佹椂閿�鍞‘璁ゅ鎴蜂氦鏈熷悗锛孞ava 涓氬姟鏈嶅姟鎵ц姝ｅ紡鎺掔▼銆侫gent 涓嶈兘鑷瑕嗙洊宸叉壒鍑嗙殑宸ュ崟璁″垝銆�
+- **浠撳簱渚濇嵁**锛歚MesProTaskController` 宸叉湁 `auto-schedule/preview` 鍜屾寮忔帓绋嬪叆鍙ｏ紱璺ㄨ鍗曞奖鍝嶆瘮杈冧笌瀹℃壒闂ㄦ闇�琛ュ厖銆�
+
+### 05 鍙戣揣涓庝粨鍌ㄦ嫤鎴�
+
+- **鍏稿瀷闂彞**锛氣�滆繖鍗曟槑澶╄兘鍙戝悧锛熺己鍦ㄥ摢涓�鏍硷紵鈥�
+- **鍙栬瘉**锛氶攢鍞鍗曘�佸彂璐ч�氱煡銆佹垚鍝佸簱瀛樹綅缃�/鎵规/SN銆佸簱瀛樺喕缁撲笌鍗犵敤銆丱QC 缁撹銆佹嫞璐�/瑁呯涓庡嚭搴撶姸鎬併��
+- **璁＄畻**锛氭寜璁㈠崟琛屼笌鎵规鏍哥畻鍙彂鏁伴噺锛涘垪鍑鸿川閲忔湭鏀捐銆佸喕缁撱�佸凡鍗犵敤銆佸簱浣嶄笉鏄庢垨鏁伴噺涓嶈冻鐨勯樆鏂」銆傚簲浣跨敤浠撳偍涓氬姟鏈嶅姟纭鍙敤閲忥紝涓嶅鍒诲簱瀛樹簨鍔¤鍒欍��
+- **缁撴灉**锛氬彲鍙�/涓嶅彲鍙戞暟閲忋�侀樆鏂師鍥犮�侀璁¤В闄ゆ椂闂淬�佸簱浣嶆竻鍗曘�佸悓鎵规鍏宠仈璁㈠崟銆�
+- **鍔ㄤ綔杈圭晫**锛氬彲鐢熸垚鎷ｈ揣涓庤ˉ璇佹嵁寤鸿锛涘簱瀛樿皟鏁淬�佽В鍐汇�佹寮忓嚭搴撱�佸彂璐ч�氱煡浠嶈蛋鍘熺郴缁熸潈闄愬強瀹℃壒銆�
+- **缂哄彛**锛氶渶姹囨�� ERP 閿�鍞鍗曚笌 WMS 鍑哄簱/搴撳瓨鍗犵敤/OQC 鐨勬煡璇㈣鍥俱��
+
+### 06 璐ㄩ噺寮傚父涓庡仠绾垮楠�
+
+- **鍏稿瀷闂彞**锛氣�滆繖鎵圭殑缂洪櫡鏄笉鏄湁鐐瑰锛熷凡缁忔祦鍒板摢閲岋紵鈥�
+- **鍙栬瘉**锛欼PQC 鎸囨爣鍊间笌妫�楠屾爣鍑嗙増鏈�佺己闄疯褰曘�佸伐鍗曟壒娆°�佸凡浜у嚭閲忋�佷笅閬撳伐搴忔祦杞�佸簱瀛樻壒娆°�佽澶囨垨妫�楠岃澶囨棩蹇椼��
+- **璁＄畻**锛氭寜鎸囨爣瑙勫垯鍒よ秺闄愶紝缁熻杩炵画娆℃暟銆佹牱鏈暟閲忋�佸奖鍝嶆壒娆�/宸ヤ欢銆佸凡娴佽浆鑼冨洿銆傚尯鍒嗏�滆鍒欏垽瓒婇檺鈥濃�滃缓璁殧绂烩�濃�滃仠绾垮凡鎵瑰噯鈥濃�滃疄鏈哄仠绾垮凡鎵ц鈥濄��
+- **缁撴灉**锛氬紓甯稿崟/NCR 鑽夌銆佸奖鍝嶉潰娓呭崟銆佸楠屼换鍔°�佸仠绾跨敵璇疯崏绋匡紱鍏ㄩ儴闄勫師濮嬫楠岃褰曚笌鏍囧噯鐗堟湰銆�
+- **鍔ㄤ綔杈圭晫**锛氳秺闄愬彲鑷姩鍛婅涓庣敓鎴愬楠屽緟鍔烇紱闅旂/搴撳瓨鍐荤粨闇�浠撳偍鎴栬川閲忔巿鏉冿紱鍋滅嚎鍜屽绾垮垎鍒敱鏈夋潈闄愬矖浣嶇瀛楋紝Agent 涓嶄笅鍙戞帶鍒舵寚浠ゃ��
+- **缂哄彛**锛氭湰浠撳簱鏈� IPQC銆丯CR 涓庡伐鍗曞叧鑱旓紝浣嗗浘鐗囦腑鐨勬楠岃澶囨暟鎹噰闆嗐�佸仠绾垮弻绛惧拰鎺у埗绯荤粺鍥炶闇�瑕佹柊澧為泦鎴愪笌娴佺▼銆�
+
+### 07 璁惧婕忔涓庝繚鍏�
+
+- **鍏稿瀷闂彞**锛氣�滄槰澶╃殑鐐规鏈夋病鏈夋病鍋氱殑锛熷摢浜涗細褰卞搷鍏抽敭宸ュ簭锛熲��
+- **鍙栬瘉**锛氳澶囧彴璐︺�佺偣妫�璁″垝/璁板綍銆佷繚鍏昏鍒�/璁板綍銆佺淮淇崟銆佸伐鍗曡澶囧垎閰嶃�佺彮娆′笌璁惧杩愯鏃堕暱锛堣嫢鏈夊彲淇￠噰闆嗘簮锛夈��
+- **璁＄畻**锛氭寜璁惧閫傜敤璁″垝銆佺彮娆＄獥鍙ｅ拰鏈夋晥鎻愪氦璁板綍鎵炬紡妫�锛涙帓闄ゅ仠鐢ㄣ�佺淮鎶や腑鍜岃鍒掓殏鍋滅殑璁惧銆傛寜鐓ф湭鏉ョ敓浜у崰鐢ㄥ拰宸ュ簭鍏抽敭鎬ф帓搴忋��
+- **缁撴灉**锛氭紡妫�璁惧銆佹渶鍚庢湁鏁堢偣妫�鏃堕棿銆侀璁″奖鍝嶅伐鍗曘�佷粖鏃ュ埌鏈熶繚鍏汇�佸凡瀛樺湪缁翠慨鍗曘��
+- **鍔ㄤ綔杈圭晫**锛氱敓鎴愯ˉ妫�涓庝繚鍏诲緟鍔烇紝閬垮厤閲嶅寤哄崟锛涚淮淇汉瀹屾垚骞跺洖鍐欒褰曞悗鍏抽棴銆傛槸鍚︾户缁娇鐢ㄨ澶囩敱璁惧璐熻矗浜轰緷鎹幇鍦烘鏌ュ喅瀹氥��
+- **缂哄彛**锛氳繍琛屾椂闀胯Е鍙戦渶鍙潬 IoT/璁惧閲囬泦婧愶紱浠呮湁鎵嬪伐鍙拌处鏃跺厛鎸夎鍒掑懆鏈熻Е鍙戙��
+
+### 08 濮斿鍔犲伐瀵硅处
+
+- **鍏稿瀷闂彞**锛氣�滆繖涓湀濮斿鐨勮处宸湪鍝嚑绗旓紵鈥�
+- **鍙栬瘉**锛氬鍗忓伐鍗曘�佸鍗忓彂鏂�/鍏ュ簱銆両QC 鍚堟牸閲忋�佷緵搴斿晢銆侀噰璐垨鍚堝悓绾﹀畾鎹熻�楃巼涓庡崟浠枫�佹潵绁ㄤ笌浠樻鐘舵�併��
+- **璁＄畻**锛氶�愬崟閫愮墿鏂欐瘮瀵瑰彂鏂欍�佹敹鍥炪�佹姤搴�/閫�鏂欍�佸悎鍚屽厑璁告崯鑰楋紝璁＄畻瓒呰�楁暟閲忥紱閫愬悎鍚岀増鏈瘮杈冪粨绠椾环涓庣害瀹氫环锛屽垪鍑烘暟閲忓樊鍜屼环宸�傚崟浣嶆崲绠椼�佺◣鐜囥�佸竵绉嶃�侀��琛ユ枡瑕佹槑纭鐞嗐��
+- **缁撴灉**锛氬樊寮傚彴璐︼紝鍚崟鍙枫�佷緷鎹�佹暟閲忋�侀噾棰濄�佽矗浠诲緟纭椤癸紱涓嶈兘鎶婃湭楠屾敹鐨勬敹璐у綋浣滃悎鏍煎叆搴撱��
+- **鍔ㄤ綔杈圭晫**锛氶噰璐牳瀹炲苟璁板綍渚涘簲鍟嗙瓟澶嶏紝璐㈠姟澶嶆牳鍚庢墠鐢熸垚搴斾粯鎴栨墸娆俱�侫gent 鍙互璺熻釜閫炬湡鏈牳瀹為」锛屼笉鑳借嚜琛屽垽瀹氭崯鑰楀綊灞炪��
+- **缂哄彛**锛歁ES 宸叉湁澶栧崗鍙戞枡/鍏ュ簱瀵硅薄锛涘悎鍚岀害瀹氭崯鑰椼�佸姞宸ヤ环鍜岀粨绠楀彛寰勬槸鍚﹀湪褰撳墠绯荤粺瀹屾暣鍙煡闇�杩涗竴姝ョ洏鐐广��
+
+### 09 瀹㈣瘔鎵规杩芥函
+
+- **鍏稿瀷闂彞**锛氣�滃鎴锋姇璇夌殑杩欎釜鎵瑰彿锛屾槸鍝壒鏂欏仛鐨勶紵杩樺彂缁欎簡璋侊紵鈥�
+- **鍙栬瘉**锛氬敭鍚庡伐鍗曘�丒RP 閿�鍞鍗曘�乄MS 閿�鍞嚭搴�/SN/鎵规銆丮ES 宸ュ崟棰嗘枡銆佹潵鏂欐壒娆°�両QC/IPQC/OQC 涓庤川妫�鎶ュ憡鐗堟湰銆�
+- **璁＄畻**锛氭部鈥滃嚭璐ф壒娆♀啋宸ュ崟浜у嚭鈫掗鏂欐壒娆♀啋鍒拌揣/渚涘簲鍟嗏�濆弽鍚戣拷婧紝鍐嶄粠鍙枒鏉ユ枡鎵规姝ｅ悜瀵绘壘鍏跺畠宸ュ崟銆佸簱瀛樺拰瀹㈡埛銆傛瘡鏉¤竟璁板綍鏉ユ簮鍗曟嵁銆佹暟閲忋�佹椂闂村拰鍙俊搴︺��
+- **缁撴灉**锛氬彲灞曞紑鐨勮拷婧浘銆佸彈褰卞搷瀹㈡埛/搴撳瓨/鍦ㄥ埗娓呭崟銆佽瘉鎹柇鐐广�佸鎴峰洖澶嶈崏绋裤�傜焊璐ㄦ姤鍛婃垨鏈數瀛愬綊妗ｈ祫鏂欐槑纭垪涓烘柇鐐癸紝涓嶈兘缁欏嚭瀹屾暣杩芥函缁撹銆�
+- **鍔ㄤ綔杈圭晫**锛氬鏈嶄笌璐ㄩ噺璐熻矗浜虹‘璁ゅ閮ㄥ洖澶嶏紱鏄惁閫氱煡鍏朵粬瀹㈡埛銆佸彫鍥炪�佸喕缁撳簱瀛樼瓑鐢卞搴旇礋璐ｄ汉鍐冲畾銆�
+- **浠撳簱渚濇嵁**锛氱幇鏈夋壒娆″墠鍚�/鍚庡悜鍙婂伐搴忚拷婧叆鍙ｅ彲澶嶇敤锛涘敭鍚庝笌鍑哄簱鐨勮法鍩熷叧鑱斻�佹姤鍛婇檮浠跺畬鏁存�ц繕闇�楠岃瘉銆�
+
+## 鍥涖�佹敮鎾戜笂杩板満鏅殑缁熶竴鑳藉姏
+
+### 4.1 璁㈠崟涓庢壒娆″叧绯诲浘
+
+缁熶竴閿负涓氬姟瀵硅薄寮曠敤 `module + object_type + id + code`锛岃竟鏉ヨ嚜涓氬姟澶栭敭鎴栧洖璋冭褰曘�備富绾夸负锛�
+
+```mermaid
+flowchart LR
+  CRM[CRM 鍚堝悓] --> SO[ERP 閿�鍞鍗昡
+  SO --> MPS[MES MPS]
+  MPS --> WO[鐢熶骇宸ュ崟]
+  WO --> BOM[宸ュ崟 BOM]
+  WO --> FB[宸ュ簭浠诲姟/鎶ュ伐]
+  BOM --> ST[搴撳瓨/鍗犵敤/棰嗘枡鎵规]
+  FB --> QC[IPQC/OQC]
+  FB --> FG[鎴愬搧鎵规/SN]
+  FG --> SHIP[鍑哄簱/鍙戣揣]
+  SHIP --> AFTER[鍞悗/瀹㈣瘔]
+  ST --> SUP[閲囪喘/渚涘簲鍟�/IQC]
+```
+
+姣忔潯鍏宠仈鍒嗕负**鐩存帴澶栭敭銆佷笟鍔″洖璋冦�佽鍒欐帹瀵笺�佷汉宸ョ‘璁�**鍥涚銆備粎鍓嶄袱绉嶅彲浣滀负鈥滃凡纭浜嬪疄鈥濄�備笟鍔＄紪鍙风浉浼笺�佹椂闂存帴杩戜笉鑳借嚜鍔ㄨ浣滃悓涓�鍗曟嵁銆�
+
+### 4.2 涓诲姩杩愯涓庢寔缁窡杩�
+
+- 瀹氭椂浠诲姟锛氭鏃ラ綈濂楋紙寤鸿鏃╃彮鍓嶏級銆佸伐鍗曡秴鏈燂紙姣忕彮锛夈�佽澶囩偣妫�锛堣鍒掔獥鍙ｅ悗锛夈�佸澶栧璐︼紙鏈堢粨锛夈�傚叿浣撴椂闂村彇浼佷笟鐝/鑺傚亣鏃ヨ缃紝涓嶇‖缂栫爜鍥剧墖閲岀殑 07:30銆�08:00銆�06:30銆�
+- 浜嬩欢瑙﹀彂锛氳鍗曚氦鏈熷彉鏇淬�侀噰璐氦鏈熸洿鏂般�佹姤宸ュ鎵广�佽川妫�瓒婇檺銆佺淮淇姸鎬佸彉鍖栥�佸嚭搴撳畬鎴愩�佸敭鍚庡伐鍗曞垱寤恒��
+- 宸℃缁撴灉瑕佸幓閲嶏細`鍦烘櫙 + 涓氬姟瀵硅薄 + 鍩虹嚎鐗堟湰 + 鏃堕棿绐楀彛` 褰㈡垚浜嬩欢閿紱浠呭叧閿簨瀹炲彉鍖栨椂閲嶆柊閫氱煡銆傚緟鍔炴湁璐熻矗浜恒�佸埌鏈熸椂闂淬�佸洖鎵х姸鎬併�佸崌绾ц矾寰勫拰鍏抽棴鏉′欢銆�
+- 宸ヤ綔娴佺姸鎬侊細`寰呭彇璇� 鈫� 璁＄畻涓� 鈫� 寰呬汉宸ュ垽鏂�/寰呭鎵� 鈫� 宸叉彁浜や笟鍔＄郴缁� 鈫� 涓氬姟澶勭悊涓� 鈫� 宸查獙璇佸叧闂璥锛屽彟鏈� `璇佹嵁涓嶈冻`銆乣杩囨湡闇�閲嶇畻`銆乣鎵ц澶辫触`銆侫gent 鐨勪换鍔″畬鎴愪笉浠ｈ〃涓氬姟鍗曟嵁瀹屾垚銆�
+
+### 4.3 鍥炵瓟涓庢搷浣滃崱鐗�
+
+瀵硅瘽鏄叆鍙ｏ紝鍗＄墖鏄彲鎿嶄綔鐨勫伐浣滃彴銆傛瘡涓粨鏋滃崱鑷冲皯鏄剧ず锛�**缁撹銆佺粺璁″彛寰�/鏃堕棿銆佸叧閿暟瀛椼�佽瘉鎹崟鎹�佸仛杩囩殑涓夋銆佸缓璁姩浣溿�佸綋鍓嶇姸鎬併�佽矗浠讳汉銆佷笅涓�娆℃鏌ユ椂闂�**銆傜偣鍑绘暟瀛楀彲灞曞紑鏄庣粏锛岀偣鍑昏瘉鎹烦鍘熶笟鍔￠〉闈紱鈥滅‘璁ゅ彂閫�/瀹℃壒/鏀规帓绋嬧�濇寜閽彧鍦ㄦ湁鏉冮檺涓旀暟鎹湭杩囨湡鏃跺嚭鐜般��
+
+閲囩敤涓庡綋鍓� Vue 绠＄悊绔竴鑷寸殑鎿嶄綔鍨嬪竷灞�锛氬乏渚т换鍔�/鍦烘櫙瀵艰埅锛屼腑闂寸粨璁轰笌璇佹嵁锛屽彸渚у緟鍔炰笌瀹℃壒鐘舵�併�傜Щ鍔ㄧ浼樺厛鏄剧ず缁撹銆佸緟鍔炲拰璇佹嵁鎽樿锛屽鏉傝拷婧浘鎻愪緵琛ㄦ牸鏇夸唬銆傛墍鏈夌姸鎬佸悓鏃剁敤鏂囧瓧鍜岄鑹茶〃杈撅紝鎸夐挳鏈夋槑纭殑鍔犺浇銆佸け璐ャ�佹棤鏉冮檺鍜屾暟鎹繃鏈熷弽棣堛�傚浘鐗囬噷鐨勬牱寮忓彲浣滆瑙夊弬鑰冿紝鐪熷疄鐣岄潰蹇呴』鏄剧ず鐪熷疄鍗曞彿鍙婃墽琛岀粨鏋溿��
+
+**鍦烘櫙 02 鐨勭晫闈㈡牱渚嬶紙绾ず渚嬫暟鎹級**锛氱敤鎴烽棶鈥滄槑澶╄鍒掑紑宸ョ殑 10 寮犲伐鍗曪紝鍝簺鑳藉紑锛熲�濆崱鐗囧厛绛斺��6 寮犻綈濂楋紝4 寮犵己鏂欌�濓紝鏄剧ず鈥滄鏌ヤ簡 10 浠藉伐鍗� BOM銆佸簱瀛�/鍗犵敤銆�7 寮犲叧鑱旈噰璐崟鈥濓紝鍐嶅垪鍑烘瘡寮犳瑺鏂欏伐鍗曠殑鐗╂枡銆佸噣缂哄彛銆侀噰璐崟鍙婁緵搴斿晢浜ゆ湡銆備笅涓�寮犲崱灞曠ず鈥滈噰璐偓浜ゅ緟鍔炶崏绋匡細2 鍚嶈礋璐ｄ汉銆佹埅姝粖鏃� 16:00鈥濄�傜敤鎴风‘璁ゅ悗锛孞ava 鏈嶅姟杩斿洖寰呭姙缂栧彿锛岀晫闈㈡墠鏀逛负鈥滃凡娲惧彂鈥濓紱閲囪喘鍥炴墽鎴栧簱瀛樺叆搴撳悗閲嶆柊璁＄畻锛屾棫缁撹鏄剧ず鈥滄暟鎹凡鍙樺寲锛岃鏌ョ湅鏂扮増鈥濄�傛暟瀛椼�佸姩浣滃拰璇佹嵁濮嬬粓鍙睍寮�鏍稿銆�
+
+### 4.4 浜烘満杈圭晫鐭╅樀
+
+| 绾у埆 | 渚嬪瓙 | 榛樿琛屼负 |
+| --- | --- | --- |
+| L0 鑷姩鍙栬瘉 | 鏌ュ伐鍗曘�佸簱瀛樸�佹壒娆°�佹楠屻�佸鎵圭姸鎬� | 鏈夋潈闄愬嵆鍙繍琛屽苟鐣欑棔 |
+| L1 鑷姩璁＄畻/鎻愰啋 | 榻愬銆侀�炬湡銆佹紡妫�銆佸樊寮傘�佸唴閮ㄦ彁閱� | 瑙勫垯鐗堟湰鍖栥�佸彲鎾ゅ洖鎻愰啋銆佸彲澶嶇畻 |
+| L2 寰呭姙/鑽夌 | 鍌氦寰呭姙銆佸楠屽緟鍔炪�佸洖澶嶇銆佽瘎瀹＄ | 鎸夊矖浣嶆巿鏉冿紝鍥炴樉鑽夌涓庝笟鍔″崟鍙� |
+| L3 瀹℃壒鍚庡啓鍏� | 鎺掔▼鍙樻洿銆佸簱瀛橀殧绂�/瑙ｅ喕銆侀噰璐崟銆佽储鍔＄粨绠� | Java 鏍￠獙銆丅PM 瀹℃壒銆佸箓绛夋墽琛屻�佸洖璇婚獙璇� |
+| L4 鐜板満瀹夊叏鍐冲畾 | 鍋滅嚎/澶嶇嚎銆佽澶囩户缁娇鐢ㄣ�佺壒閲�/鏀捐銆佸彫鍥� | 蹇呴』鐢辨湁鏉冧汉鍛樺喅瀹氾紱Agent 鍙彁渚涜瘉鎹笌鐢宠 |
+
+### 4.5 鎶�鏈惤鐐�
+
+Python 鐙珛鏈嶅姟閲囩敤鈥滃満鏅紪鎺掑櫒 + 棰嗗煙宸ュ叿娉ㄥ唽琛� + 纭畾鎬ц绠楀櫒 + 鐭ヨ瘑妫�绱� + 妯″瀷璇存槑鍣ㄢ�濄�侸ava 澧炲姞闈㈠悜鏅鸿兘浣撶殑鍐呴儴鑱氬悎 API锛岃礋璐ｇ幇鏈夌敤鎴疯韩浠姐�佹暟鎹寖鍥淬�佷笟鍔℃牎楠屽拰瀹℃壒銆侾ython 涓嶇洿鎺ユ搷浣滀笟鍔℃暟鎹簱銆傞鎵瑰伐鍏峰寘鎷� `get_order_context`銆乣calculate_material_readiness`銆乣preview_schedule`銆乣inspect_workorder_progress`銆乣trace_batch`銆乣get_quality_context`銆乣get_equipment_due`銆乣reconcile_outsource`锛涙瘡涓伐鍏锋湁杈撳叆/杈撳嚭 schema銆佹潈闄愩�佺増鏈拰娴嬭瘯鍩哄噯銆�
+
+## 浜斻�佷笌褰撳墠浠撳簱鐨勬帴鍏ユ牳瀵�
+
+| 鑳藉姏 | 浠ｇ爜涓凡鐪嬪埌鐨勫叆鍙� | 浠嶉渶寤鸿鎴栨牳瀹� |
+| --- | --- | --- |
+| 鐢熶骇棰勬祴 | `MesProAiController` 鍥涚被棰勬祴 | 涓庣‘瀹氭�ф帓绋�/搴撳瓨鍙ｅ緞铻嶅悎銆佺粨鏋滄牎鍑� |
+| 鐢熶骇鎺掔▼ | `MesProTaskController` 棰勮鍜屾墽琛� | 澶氭柟妗堟瘮杈冦�佸彈褰卞搷璁㈠崟銆佸鎵归棬妲� |
+| 浠撳偍 | 鐗╂枡搴撳瓨銆佸崰鐢ㄣ�佸嚭搴撱�佹壒娆¤拷婧帶鍒跺櫒 | 璺ㄤ粨/鎵规鐨勫噣鍙敤鑱氬悎鍜屾簮鏁版嵁鏃剁偣 |
+| 璐ㄦ | IQC/IPQC/OQC/RQC銆丯CR銆佽川妫�鎶ュ憡 | 妫�楠岃澶囬噰闆嗐�佸仠绾�/澶嶇嚎绛炬壒銆佹姤鍛婇檮浠惰ˉ鍏� |
+| 璁惧 | 鐐规璁″垝/璁板綍銆佷繚鍏�/缁翠慨鎺у埗鍣� | 杩愯鏃堕暱閲囬泦銆佸叧閿伐搴忓奖鍝嶆帓搴� |
+| 濮斿 | 澶栧崗鍙戞枡涓庡叆搴撴帶鍒跺櫒 | 鍚堝悓浠�/鎹熻�楃巼銆佸畬鏁存湀缁撲笌褰掕矗娴佺▼ |
+| 閿�鍞笌鍞悗 | CRM 鍚堝悓銆丒RP 閿�鍞鍗曘�佸敭鍚庡伐鍗� | 缁熶竴璁㈠崟鍒版壒娆￠摼涓庤法绯荤粺瀹㈡埛鍥炲娴佺▼ |
+| 瀹℃壒/閫氱煡 | BPM 涓庣郴缁熼�氱煡鍩虹鑳藉姏 | Agent 涓撶敤寰呭姙銆佹彁閱掑洖鎵с�佸璁¤鍥� |
+
+杩欎簺鈥滃凡鐪嬪埌鐨勫叆鍙ｂ�濆彧璇佹槑瀵硅薄鍜岄儴鍒嗘搷浣滃瓨鍦紱涓婄嚎鍓嶄粛椤绘鏌ュ弬鏁般�佹潈闄愭敞瑙ｃ�佹暟鎹寖鍥淬�佸崟鎹姸鎬佹満鍜岀湡瀹炴暟鎹畬鏁村害銆�
+
+## 鍏�佸缓璁殑棣栨壒浜や粯缁勫悎
+
+鎺ㄨ崘浠� **01 鎺ュ崟璇勫 + 02 寮�宸ラ綈濂� + 03 瓒呮湡宸℃** 涓虹涓�鏉＄旱鍚戦摼锛氶攢鍞兘鍥炵瓟鑳藉惁鎺ワ紝璁″垝鐭ラ亾鑳藉惁寮�宸ワ紝杞﹂棿鐭ラ亾鍝噷鍗′綇銆傝繖鏉￠摼鑳藉鐢ㄧ幇鏈夌敓浜ч娴嬨�佸簱瀛樺拰鎺掔▼鍏ュ彛锛屽苟涓哄叾浣欏満鏅墦涓嬭鍗曞叧绯诲浘銆佷富鍔ㄥ贰妫�銆佸緟鍔炲洖鎵у拰璇佹嵁鍗″熀纭�銆�
+
+绗簩鏉￠摼鍋� **06 璐ㄩ噺寮傚父 + 09 鎵规杩芥函**锛岄噸鐐归獙璇佽法鎵规鍏宠仈涓庘�滆瘉鎹柇鐐光�濊〃杈俱�傜涓夋潯閾惧仛 **07 璁惧 + 08 濮斿 + 05 鍙戣揣**锛�04 鎺掔▼姝ｅ紡鎵ц寰呭鎵归摼瀹屽杽鍚庡紑鏀俱��
+
+楠屾敹涓嶄互婕旂ず瀵硅瘽娴佺晠涓哄噯锛岃�屼互涓氬姟缁撴灉涓哄噯锛氱粨璁鸿兘澶嶇畻銆佸彈褰卞搷鍗曟嵁涓嶆紡涓嶄覆銆佹潈闄愪笉绌块�忋�佸緟鍔炵湡鐨勫埌浜恒�佸鎵逛笌涓氬姟鍗曞彿鑳藉洖璇汇�佹暟鎹彉鍖栧悗鑳芥挙閿�杩囨湡缁撹銆傛瘡涓満鏅嚦灏戝噯澶囨甯搞�佹暟鎹己澶便�佽法鏉冮檺銆佸崟鎹彉鏇村拰鍔ㄤ綔澶辫触鏍锋湰銆�
+
+**寰呮渶缁堥�夋嫨**锛氫節鍦烘櫙璺嚎涓庢帹鑽愪氦浠橀『搴忔槸鍚︾鍚堜紒涓氫紭鍏堢骇锛涙槸鍚︽妸鈥滃伐鍗曟垚鏈綊闆嗏�濆拰鈥滅粡钀ラ棶绛斺�濇彁鍗囦负绗竴鎵广�傜‘璁ゅ悗鍐嶅皢鏈摑鍥炬敹鏁涗负鎺ュ彛娓呭崟銆佹暟鎹绾︺�侀〉闈㈡祦绋嬪拰瀹炴柦浠诲姟銆�
diff --git a/docs/mdm_item_category_unification.md b/docs/mdm_item_category_unification.md
new file mode 100644
index 0000000..e86a776
--- /dev/null
+++ b/docs/mdm_item_category_unification.md
@@ -0,0 +1,73 @@
+# 鐗╂枡鍒嗙被缁熶竴鍒� mdm_item_category 鏂规
+
+## 鑳屾櫙
+
+鍩虹鏁版嵁 鈫� 鐗╂枡绠＄悊鍦ㄤ繚瀛樼墿鏂欏苟鍕鹃�夈�屽悓姝ュ埌 MES銆嶆椂鎻愮ず銆岀墿鏂欏垎绫讳笉瀛樺湪銆嶃��
+
+鏍瑰洜鏄墿鏂欏垎绫诲瓨鍦ㄤ袱濂楄〃涓旀湭鍚屾锛�
+
+- 銆屽熀纭�鏁版嵁 鈫� 鐗╂枡鍒嗙被銆嶉〉闈㈢殑鏂板/淇敼/鍒犻櫎璧� MES 鎺ュ彛 `MesMdItemTypeServiceImpl`锛屽彧鍐� `mes_md_item_type`锛�
+- 鐗╂枡琛ㄥ崟鐨勫垎绫讳笅鎷夎蛋 `/mes/md/item-type/simple-list`锛岃鐨勪篃鏄� `mes_md_item_type`锛�
+- 浣� MDM 鐗╂枡鍚屾鍒� MES 鏃讹紙`MdmItemServiceImpl#syncItemToMes`锛夋寜鍒嗙被 ID 鏌� `mdm_item_category`锛屾煡涓嶅埌鍗虫姏 `MDM_ITEM_CATEGORY_NOT_EXISTS`銆�
+
+鍥犳鑰佸垎绫诲彲鐢紙鍘嗗彶鏁版嵁涓よ〃閮芥湁锛夛紝鏂板垎绫诲繀鎶ラ敊銆�
+
+## 鐩爣
+
+鐗╂枡鍒嗙被缁熶竴浠� `mdm_item_category` 涓哄敮涓�鏁版嵁婧愶細
+
+- MES 鍒嗙被鎺ュ彛 `/mes/md/item-type/*` 淇濈暀锛屽墠绔矾寰勪笌鍑哄叆鍙備笉鍙橈紝浣嗗簳灞傝鍐欏叏閮ㄦ敼涓� `mdm_item_category`锛�
+- MDM 涓� MES 鐨勫垎绫讳笅鎷夈�佺墿鏂欎繚瀛樸�佸悓姝ャ�佸鍏ュ叏閮ㄥ熀浜庡悓涓�寮犺〃锛�
+- `mes_md_item_type` 涓嶅啀鍐欏叆锛屼粎浣滀负鍘嗗彶澶囦唤淇濈暀銆�
+
+## 鏀瑰姩鑼冨洿
+
+### 鍚庣
+
+| 妯″潡 | 鏂囦欢 | 鏀瑰姩 |
+|------|------|------|
+| mdm | `MdmItemCategoryApi` | 澧炲姞 create / update / delete / 鍏ㄩ噺鍒楄〃 RPC 鏂规硶 |
+| mdm | `MdmItemCategoryApiImpl` | 瀹炵幇涓婅堪鏂规硶 |
+| mdm | `MdmItemCategorySaveReqDTO`锛堟柊澧烇級 | RPC 鍐欏叆鍙傛暟 |
+| mdm | `MdmItemCategoryRespDTO` | 琛� `remark`銆乣createTime` |
+| mdm | `MdmItemCategoryService(Impl)` | 澧炲姞鍏ㄩ噺鍒楄〃鏂规硶 |
+| mes | `MesMdItemTypeServiceImpl` | 澧炲垹鏀规煡銆佸瓙鍒嗙被銆佸鍏ュ叏閮ㄦ敼涓鸿皟鐢� MDM 鍒嗙被 API |
+
+### 鍓嶇
+
+**鏃犻渶鏀瑰姩銆�** 椤甸潰璋冪敤鐨勪粛鏄澶栬矾寰勶細
+
+- 鍒嗙被绠＄悊椤碉細`/mes/md/item-type/list|get|create|update|delete|import`
+- 鍒嗙被涓嬫媺锛歚/mes/md/item-type/simple-list`
+- MDM 鐗╂枡椤靛垎绫讳笅鎷夛細鍚屾牱璋冪敤 `/mes/md/item-type/simple-list`
+
+鍝嶅簲瀛楁淇濇寔 `id / parentId / code / name / itemOrProduct / sort / status / remark / createTime`銆�
+
+## 鏁版嵁杩佺Щ
+
+涓婄嚎鍓嶆墽琛� `docs/sql/mdm_item_category_migration.sql`锛屾妸 `mes_md_item_type` 鍏ㄩ噺锛堝惈宸查�昏緫鍒犻櫎璁板綍锛夋寜**鍘� ID** 杩佺Щ鍒� `mdm_item_category`锛屼繚璇侊細
+
+- `mes_md_item.item_type_id`銆乣mdm_item.category_id` 绛夊巻鍙插閿户缁湁鏁堬紱
+- `item_type` 鐢� `item_or_product` 鎺ㄥ锛歚PRODUCT 鈫� 2锛堜骇鍝侊級`锛屽叾浣� `鈫� 1锛堢墿鏂欙級`锛�
+- 鑴氭湰鍙噸澶嶆墽琛岋紙鎸変富閿� upsert锛夈��
+
+杩佺Щ鍚庢柊鍒嗙被鐢� `mdm_item_category` 鑷 ID 鐢熸垚锛屼袱濂� ID 浣撶郴鑷劧鏀舵暃涓轰竴濂椼��
+
+## 涓氬姟瑙勫垯
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 鏂板鍒嗙被 | 鍐� `mdm_item_category`锛岀紪鐮佸叏灞�鍞竴銆佸悓涓�鐖剁骇涓嬪悕绉板敮涓�锛堢敱 MDM 鏍￠獙锛� |
+| 淇敼鍒嗙被 | 鎸夊師 ID 鏇存柊 `mdm_item_category` |
+| 鍒犻櫎鍒嗙被 | 鍏堟牎楠� MES 鐗╂枡寮曠敤锛屽啀鐢� MDM 鏍￠獙瀛愬垎绫讳笌 MDM 鐗╂枡寮曠敤 |
+| 鐗╂枡淇濆瓨 + 鍚屾 MES | 鎸� `categoryId` 鏌� `mdm_item_category` 鍙� code锛屾甯稿悓姝� |
+| 鐗╂枡瀵煎叆 | 鎸夊垎绫诲悕绉板湪 `mdm_item_category` 涓В鏋� |
+| 璁惧鑱斿姩鐗╂枡 | `EQUIPMENT` 鍒嗙被杩佺Щ鍚� MDM 渚у彲姝ｅ父鎸� code 瑙ｆ瀽 |
+
+## 楠岃瘉
+
+1. 鎵ц杩佺Щ SQL锛屾牳瀵� `mes_md_item_type` 涓� `mdm_item_category` 璁板綍鏁般�両D 涓�涓�瀵瑰簲銆�
+2. 銆屽熀纭�鏁版嵁 鈫� 鐗╂枡鍒嗙被銆嶆柊澧炪�屾祴璇曘�嶅垎绫伙紝纭 `mdm_item_category` 鍑虹幇璁板綍銆乣mes_md_item_type` 涓嶆柊澧炪��
+3. 銆屽熀纭�鏁版嵁 鈫� 鐗╂枡绠＄悊銆嶇紪杈戠墿鏂欙紝閫夋嫨銆屾祴璇曘�嶏紝鍕鹃�夈�屽悓姝ュ埌 MES銆嶄繚瀛橈紝搴旀垚鍔熴��
+4. 鍒嗙被涓嬫媺銆佺墿鏂欏垪琛ㄥ垎绫诲悕绉板睍绀恒�佸垎绫荤紪杈戝洖鏄撅紙鍚娉級姝ｅ父銆�
+5. 鍒嗙被瀵煎叆銆佺墿鏂欐寜鍒嗙被鍚嶇О瀵煎叆姝ｅ父銆�
diff --git a/docs/mes_collect_design.md b/docs/mes_collect_design.md
new file mode 100644
index 0000000..ffe7dca
--- /dev/null
+++ b/docs/mes_collect_design.md
@@ -0,0 +1,289 @@
+# MES 娉ㄥ鏈烘暟閲囧鎺ラ渶姹備笌璁捐
+
+> 鐘舵�侊細寰呰瘎瀹★紙璇勫閫氳繃鍚庡紑濮嬬紪鐮侊級
+> 缂栧啓鏃ユ湡锛�2026-10-20
+> 閫傜敤鏁版嵁搴擄細`mom-kyzn`
+> 娑夊強妯″潡锛歚yudao-module-mes`
+
+## 1. 鑳屾櫙涓庣洰鏍�
+
+瀹㈡埛娉ㄥ鏈洪�氳繃寮樿閲囬泦缃戝叧锛屽皢杩愯鐘舵�併�佸懆鏈熻繃绋嬨�佸伐鑹哄弬鏁般�佸弬鏁板彉鏇村拰鎶ヨ浠� MQTT 鎶ユ枃鎺ㄩ�佸埌 EMQX銆傚綋鍓� MES 娌℃湁浠讳綍 MQTT 鎺ュ叆浠ｇ爜锛岄渶瑕佸畬鎴愨�滆闃� 鈫� 瑙ｆ瀽 鈫� 钀藉簱 鈫� 鏌ヨ/灞曠ず鈥濈殑鍏ㄩ摼璺鎺ワ紝骞舵妸閲囬泦鏁版嵁涓� MES 璁惧鍙拌处銆佺敓浜т换鍔�/宸ュ崟鍏宠仈璧锋潵銆�
+
+鏈湡鐩爣锛堝凡涓庣敤鎴风‘璁わ級锛�
+
+1. **鍏ㄩ噺鎺ュ叆**锛歳ealtime锛堝疄鏃剁姸鎬侊級銆乻pc锛堝懆鏈熻繃绋嬶級銆乼ech锛堝伐鑹哄弬鏁帮級銆乷pLog锛堝弬鏁板彉鏇达級銆佹姤璀︿簲绫绘暟鎹叏閮ㄨ惤搴撱��
+2. **璁惧缁戝畾**锛氬湪 `mes_dv_machinery` 璁惧鍙拌处涓婂鍔犫�滄暟閲囪澶囩紪鍙封�濓紝`devId`锛堝 `C01`锛夌洿鎺ュ尮閰嶅彴璐︺��
+3. **宸ュ崟鑱斿姩**锛氶噰闆嗘暟鎹寜鈥滆澶囨墍灞炲伐浣滅珯涓婃鍦ㄨ繍琛岀殑鐢熶骇浠诲姟鈥濊嚜鍔ㄥ叧鑱� `taskId / workOrderId`锛屽叧鑱斾笉鍒版椂鐣欑┖銆�
+4. **鍒嗙骇淇濈暀**锛氬師濮嬫姤鏂� 7 澶┿�佸疄鏃跺巻鍙� 30 澶┿�佸懆鏈�/宸ヨ壓/鍙樻洿/鎶ヨ闀挎湡淇濈暀銆�
+
+涓嶅湪鏈湡鑼冨洿锛氬墠绔〉闈唬鐮侊紙鎸夐」鐩鍒欏彧杈撳嚭鑱旇皟鏂规锛夈�佽澶囧弽鍚戞帶鍒讹紙涓嬭鎸囦护锛夈�佸瀹炰緥鍏变韩璁㈤槄銆�
+
+## 2. 鎺ュ叆淇℃伅
+
+| 椤圭洰 | 鍊� |
+|------|----|
+| EMQX 鍦板潃 | `36.213.90.123:1883`锛圡QTT锛夛紝`18083`锛圖ashboard/HTTP API锛� |
+| 璐﹀彿 | `admin / public`锛圖ashboard 涓� MQTT 鍏辩敤锛� |
+| 鍗忚 | MQTT 3.1.1锛孮oS 0 |
+| 涓婚鍓嶇紑 | `/YLCY/IMM`锛堝彲閰嶇疆锛� |
+| 璁惧缂栧彿 | `C01` ~ `C08`锛坄devId`锛� |
+| 璁㈤槄閫氶厤 | `{prefix}/+/+`锛屽嵆 `/YLCY/IMM/+/+` |
+| 瀹㈡埛绔� ID 绀轰緥 | `/YLCY/IMM/C03/id` |
+
+涓婚绾﹀畾锛堟潵鑷噰闆嗘枃妗ｏ級锛�
+
+| 鏁版嵁绫诲瀷 | 涓婚 | 璇存槑 |
+|----------|------|------|
+| realtime | `{prefix}/{devId}/realtime` | 瀹炴椂杩愯鐘舵�併�佹俯搴︺�佹补娓� |
+| spc | `{prefix}/{devId}/spc` | 姣忎釜娉ㄥ鍛ㄦ湡鐨勮繃绋嬫暟鎹� |
+| tech | `{prefix}/{devId}/tech` | 宸ヨ壓璁惧畾鍙傛暟鍏ㄩ噺蹇収 |
+| opLog | `{prefix}/{devId}/opLog` | 鍗曚釜鍙傛暟淇敼鍓嶅悗鍊� |
+| 鎶ヨ | 鏂囨。鏈粰鍑轰富棰樺悕 | 閫氳繃鎶ユ枃 `topic` 瀛楁鎴� `Data.wmId` 璇嗗埆锛涜闃呴�氶厤鍏滃簳 |
+
+> 璇存槑锛氭姤璀︿富棰樺悕鍦ㄦ枃妗ｆ埅鍥句腑缂哄け锛屽洜鎶ユ枃鑷甫 `topic` 瀛楁涓� `Data` 涓� `wmId/wmMsg/wmTime` 鐗瑰緛鍞竴锛屼唬鐮佹寜鎶ユ枃鐗瑰緛璇嗗埆锛屼富棰樺悗缂�浠呬綔涓洪厤缃」鍏滃簳锛屼笉闃诲鎺ュ叆銆�
+
+## 3. 鎶ユ枃瑙勮寖
+
+### 3.1 鍏叡淇″皝
+
+```json
+{
+  "clientId": "/YLCY/IMM/C03/id",
+  "devId": "C03",
+  "topic": "realtime",
+  "sendTime": "2026-09-24 11:37:00",
+  "sendStamp": 1790221000000,
+  "time": "2026-09-24 11:37:00",
+  "timestamp": 1790221000000,
+  "Data": { }
+}
+```
+
+- 鏁版嵁鏃堕棿浼樺厛鍙� `time`锛坄yyyy-MM-dd HH:mm:ss`锛夛紝缂哄け鏃跺洖閫� `timestamp`銆�
+- `Data` 鍙兘涓哄璞★紱鑻ヤ负瀛楃涓诧紝浜屾瑙ｆ瀽涓哄璞°��
+- 鏁版嵁绫诲瀷浼樺厛鍙� `topic` 瀛楁锛屽叾娆℃寜涓婚鍚庣紑锛屾渶鍚庢寜 `Data` 鐗瑰緛璇嗗埆銆�
+
+### 3.2 realtime锛堝疄鏃剁姸鎬侊級
+
+`Data` 绀轰緥瀛楁锛�
+
+| 缂栫爜 | 鍚箟 | 澶囨敞 |
+|------|------|------|
+| `STS` | 鐘舵�� | 1 寰呮満锛�2 鐢熶骇 |
+| `OPM` | 杩愯妯″紡 | 0 鎵嬪姩锛�1 鍗婅嚜鍔紝2 鐢电溂鑷姩锛�3 鏃堕棿鑷姩锛�4 璋冩ā浣跨敤 |
+| `OT` | 娌规俯 | |
+| `T1..Tn` | 鍚勬娓╁害 | 娈垫暟鎸夊疄闄呬负鍑嗭紝鍔ㄦ�佽В鏋� |
+| `ASTS` | 闄勫姞鐘舵�� | 鍘熸牱淇濆瓨 |
+
+### 3.3 spc锛堝懆鏈熻繃绋嬫暟鎹級
+
+| 缂栫爜 | 鍚箟 |
+|------|------|
+| `CYCN` | 鍛ㄦ湡搴忓彿锛堥儴鍒嗙郴鍒楃嫭绔嬭鏁帮紝澧為噺涓�鑷达級 |
+| `ECYCT` | 鍛ㄦ湡鏃堕棿 |
+| `EISS` | 灏勫嚭璧风偣 |
+| `EIVM` | 鏈�澶у皠閫� |
+| `EIPM` | 鏈�澶у皠鍘� |
+| `ESIPT` | 杞繚鍘嬫椂闂� |
+| `ESIPP` | 杞繚鍘嬪帇鍔� |
+| `ESIPS` | 杞繚鍘嬩綅缃� |
+| `EIPT` | 灏勫嚭鏃堕棿 |
+| `EIPSE` | 灏勫嚭缁堢偣浣嶇疆 |
+| `EPLST` | 鍌ㄦ枡鏃堕棿 |
+| `EPLSSE` | 鍌ㄦ枡缁堢偣 |
+| `EPLSPM` | 鏈�澶у偍鏂欏帇鍔� |
+| `ET1..ETn` | 鐢熶骇娓╁害锛堝悇娈碉級 |
+
+### 3.4 tech锛堝伐鑹哄弬鏁帮級
+
+鎸夋枃妗ｇ 3 鑺傚叏閲忓瓧娈典繚瀛橈紙TS/IP/IV/IS/IT/ITUSE/ISUSE/SIPT/SIPS/SIPP/PP/PV/PT/SBS/SBT/PLLT/PLV/PLP/PLBP/PLS/SBV/SBP/SBS/SBT/CT/MCV/MCP/MCS/MOV/MOP/MOS/EFDT/EFV/EFP/EFS/EBDT/EBV/EBP/EBS/CP1M~CP4M/CPI1S~CPI4S/CPI1P~CPI4P/CPI1V~CPI4V/CPI1T~CPI4T/CPO1S~CPO4S/CPO1P~CPO4P/CPO1V~CPO4V/CPO1T~CPO4T/CFP/CFV/CFS/CFT/CBP/CBV/CBS/CBT/CBDT锛夈�傚瓧娈垫暟閲忓涓斿彲鑳芥墿灞曪紝**涓嶅缓瀹借〃**锛屾暣鍖� JSON 蹇収淇濆瓨锛屽墠绔寜 JSON 娓叉煋銆�
+
+### 3.5 opLog锛堝弬鏁板彉鏇达級
+
+```json
+{
+  "devId": "5",
+  "time": "2022-12-09 12:09:48",
+  "Data": {
+    "varId": "SIPS",
+    "value": 37.5,
+    "lastValue": 37,
+    "modifyTime": "2022-12-09 12:09:46"
+  }
+}
+```
+
+### 3.6 鎶ヨ
+
+```json
+{
+  "devId": "6",
+  "Data": {
+    "wmId": 2,
+    "wmMsg": "瀹夊叏闂ㄦ湭鍏�",
+    "wmTime": "2022-12-09 16:42:22"
+  }
+}
+```
+
+- `wmId = 2`锛氭姤璀︿骇鐢� 鈫� 鏂板涓�鏉♀�滄湭娑堥櫎鈥濊褰曘��
+- `wmId = 0`锛氭姤璀︽秷澶� 鈫� 鎶婅璁惧鎵�鏈夆�滄湭娑堥櫎鈥濊褰曠疆涓衡�滃凡娑堥櫎鈥濓紝鍐欏叆 `clearTime`銆�
+
+## 4. 鏁版嵁妯″瀷
+
+> 鎵�鏈夋柊琛ㄦ部鐢ㄩ」鐩� `BaseDO` 瀛楁锛歚creator/create_time/updater/update_time/deleted`銆傞珮棰戞棩蹇楄〃鎸変繚鐣欑瓥鐣ョ墿鐞嗘竻鐞嗐��
+
+### 4.1 璁惧鍙拌处鎵╁睍
+
+```sql
+ALTER TABLE mes_dv_machinery
+  ADD COLUMN collect_device_code VARCHAR(64) NULL COMMENT '鏁伴噰璁惧缂栧彿锛圡QTT devId锛屽 C01锛�' AFTER workstation_id,
+  ADD COLUMN collect_enabled BIT(1) NOT NULL DEFAULT b'0' COMMENT '鏄惁鍚敤鏁伴噰' AFTER collect_device_code;
+
+ALTER TABLE mes_dv_machinery
+  ADD UNIQUE INDEX uk_collect_device_code (collect_device_code);
+```
+
+- `collect_device_code` 涓虹┖琛ㄧず鏈粦瀹氭暟閲囥��
+- 鍞竴绱㈠紩鍏佽澶氫釜 `NULL`锛屼笉浼氬奖鍝嶅瓨閲忚澶囥��
+- 鍏宠仈浠诲姟鏃朵娇鐢ㄥ彴璐﹀凡鏈夌殑 `workstation_id`銆�
+
+### 4.2 鏂板缓琛�
+
+| 琛ㄥ悕 | 鐢ㄩ�� | 淇濈暀 |
+|------|------|------|
+| `mes_collect_realtime` | 姣忚澶囨渶鏂板疄鏃剁姸鎬侊紙UPSERT锛� | 甯搁┗ |
+| `mes_collect_realtime_history` | 瀹炴椂鐘舵�佸巻鍙� | 30 澶� |
+| `mes_collect_cycle` | 鍛ㄦ湡杩囩▼鏁版嵁 | 闀挎湡 |
+| `mes_collect_tech` | 宸ヨ壓鍙傛暟鏈�鏂板揩鐓э紙UPSERT锛� | 甯搁┗ |
+| `mes_collect_operate_log` | 鍙傛暟鍙樻洿鏃ュ織 | 闀挎湡 |
+| `mes_collect_alarm` | 鎶ヨ璁板綍 | 闀挎湡 |
+| `mes_collect_message` | 鍘熷鎶ユ枃锛堟帓闅溿�佽ˉ鏁颁緷鎹級 | 7 澶� |
+
+鍏抽敭瀛楁锛�
+
+- `mes_collect_realtime`锛歚device_code`锛堝敮涓�锛夈�乣machinery_id`銆乣task_id`銆乣work_order_id`銆乣sts`銆乣opm`銆乣asts`銆乣ot`銆乣temps` JSON銆乣data_json`銆乣collect_time`銆�
+- `mes_collect_realtime_history`锛氬瓧娈靛悓涓婏紝鍞竴閿� `(device_code, collect_time)`锛岀储寮� `(device_code, collect_time)`銆乣(work_order_id, collect_time)`銆�
+- `mes_collect_cycle`锛歚device_code`銆乣cycle_no`銆乣collect_time`銆乣ecyct/eiss/eivm/eipm/esipt/esipp/esips/eipt/eipse/eplst/eplsse/eplspm`銆乣et_temps` JSON銆乣data_json`锛涘敮涓�閿� `(device_code, cycle_no, collect_time)`銆�
+- `mes_collect_tech`锛歚device_code`锛堝敮涓�锛夈�乣task_id`銆乣work_order_id`銆乣collect_time`銆乣data_json`銆�
+- `mes_collect_operate_log`锛歚device_code`銆乣var_id`銆乣old_value`銆乣new_value`銆乣modify_time`銆乣collect_time`銆乣data_json`锛涚储寮� `(device_code, modify_time)`銆�
+- `mes_collect_alarm`锛歚device_code`銆乣wm_id`銆乣wm_msg`銆乣wm_time`銆乣status`锛�0 鏈秷闄�/1 宸叉秷闄わ級銆乣clear_time`銆乣data_json`锛涚储寮� `(device_code, status)`銆乣(wm_time)`銆�
+- `mes_collect_message`锛歚device_code`銆乣machinery_id`銆乣mqtt_topic`銆乣msg_type`銆乣event_time`銆乣raw_payload` LONGTEXT銆乣process_status`锛�0 鎴愬姛/1 澶辫触锛夈�乣error_msg`銆乣receive_time`銆�
+
+### 4.3 钀藉簱瑙勫垯
+
+- `realtime`锛氭洿鏂� `mes_collect_realtime` 蹇収 + 鍐� `mes_collect_realtime_history`锛堝敮涓�閿幓閲嶏級銆�
+- `spc`锛氬啓 `mes_collect_cycle`锛堝敮涓�閿幓閲嶏紝`INSERT IGNORE`锛夈��
+- `tech`锛氭暣鍖� JSON UPSERT `mes_collect_tech`锛涗笉閲嶅鐢熸垚鍙樻洿鏃ュ織锛屽彉鏇翠互璁惧涓婃姤鐨� `opLog` 涓哄噯銆�
+- `opLog`锛氶�愭潯鍐� `mes_collect_operate_log`銆�
+- 鎶ヨ锛氭寜 `wmId` 瑙勫垯鏂板/娓呴櫎銆�
+- 鎵�鏈夋姤鏂囧厛鍐� `mes_collect_message`锛岃В鏋愬け璐ヤ篃淇濈暀鍘熸枃骞惰褰� `error_msg`銆�
+- 鏈粦瀹氬彴璐︾殑 `devId`锛氱粨鏋勫寲鏁版嵁鐓у父鍏ュ簱锛坄machinery_id/task_id/work_order_id` 涓虹┖锛夛紝鍘熷鎶ユ枃淇濈暀锛屽苟浠ラ檺娴佹棩蹇楁彁绀鸿ˉ缁戝彴璐︼紝閬垮厤璁惧宸蹭笂绾夸絾鍙拌处鏈淮鎶ゆ椂涓㈡暟鎹��
+
+## 5. 宸ュ崟鑷姩鍏宠仈
+
+```
+devId 鈫� mes_dv_machinery.collect_device_code 鈫� machinery.workstation_id
+      鈫� mes_pro_task锛坵orkstation_id 鍖归厤銆乨eleted=0銆乻tatus IN (1 鐢熶骇涓�, 2 閮ㄥ垎瀹屾垚, 9 宸插仠宸�)锛�
+      鈫� 鍙� last_feedback_time / id 鏈�鏂扮殑涓�鏉� 鈫� task_id + work_order_id
+```
+
+- 缁撴灉缂撳瓨 30 绉掞紙鎸� `workstationId`锛夛紝閬垮厤姣忔潯鎶ユ枃鏌ュ簱銆�
+- 鍏宠仈涓嶅埌鏃� `task_id / work_order_id` 涓虹┖锛屼笉褰卞搷钀藉簱銆�
+- 浠诲姟鍒囨崲鍚庢渶澶� 30 绉掑欢杩熺敓鏁堛��
+
+## 6. 鍚庣瀹炵幇璁捐
+
+### 6.1 浠ｇ爜浣嶇疆
+
+```
+yudao-module-mes/
+鈹溾攢鈹� controller/admin/collect/                  # 鏌ヨ鎺ュ彛 + VO
+鈹溾攢鈹� service/collect/                           # 鏌ヨ銆佽В鏋愩�佽惤搴撱�佸叧鑱�
+鈹�   鈹溾攢鈹� MesCollectQueryService
+鈹�   鈹溾攢鈹� MesCollectDataService
+鈹�   鈹溾攢鈹� MesCollectMessageDispatcher
+鈹�   鈹溾攢鈹� MesCollectDataParser
+鈹�   鈹溾攢鈹� MesCollectTaskResolver
+鈹�   鈹斺攢鈹� MesCollectCleanupJob锛園Scheduled锛�
+鈹溾攢鈹� framework/collect/mqtt/MesCollectMqttClient # Paho 杩炴帴銆佽闃呫�侀噸杩�
+鈹溾攢鈹� dal/dataobject/collect/                    # DO
+鈹斺攢鈹� dal/mysql/collect/                         # Mapper
+```
+
+- MQTT 瀹㈡埛绔娇鐢ㄩ」鐩緷璧栫鐞嗛噷宸叉湁鐨� `org.eclipse.paho.client.mqttv3:1.2.5`锛屽湪 `yudao-module-mes/pom.xml` 寮曞叆鍗冲彲銆�
+- Paho 鍥炶皟鍙仛瑙ｆ瀽鍏ラ槦锛岃惤搴撴斁鍒板崟绾跨▼鏈夌晫闃熷垪鎵ц锛岄伩鍏嶉樆濉炲績璺炽��
+- 寮�鍚� `automaticReconnect`锛屽鎴风 ID 浣跨敤 `{prefix}-{hostname}-{random}`锛�**鐢熶骇鍗曞疄渚嬮儴缃�**锛屽瀹炰緥浼氶噸澶嶆秷璐癸紙鍚庣画鍙敼鍏变韩璁㈤槄锛夈��
+- 閫氳繃 `yudao.mes.collect.mqtt.enabled` 鎺у埗鏄惁杩炴帴锛岄粯璁ゅ叧闂紝鎸夌幆澧冨紑鍚��
+
+### 6.2 閰嶇疆椤癸紙`application-kyzn.yaml`锛屽苟鍚屾 `local/test`锛�
+
+```yaml
+yudao:
+  mes:
+    collect:
+      mqtt:
+        enabled: true
+        url: tcp://36.213.90.123:1883
+        username: admin
+        password: public
+        client-id-prefix: mes-collect
+        topic-prefix: /YLCY/IMM
+        qos: 0
+        keep-alive: 65
+        connection-timeout: 10
+        alarm-topic-suffix: wm
+      retention:
+        raw-days: 7
+        realtime-days: 30
+```
+
+### 6.3 娓呯悊浠诲姟
+
+- 姣忔棩 03:30 鎵ц銆�
+- 鐗╃悊鍒犻櫎 `mes_collect_message` 涓� `receive_time < now - 7 澶ー銆乣mes_collect_realtime_history` 涓� `collect_time < now - 30 澶ー 鐨勬暟鎹��
+- 鍗曟鍒犻櫎闄愬埗鎵归噺锛岄伩鍏嶉暱浜嬪姟閿佽〃銆�
+
+## 7. 鍚庣鎺ュ彛
+
+缁熶竴鍓嶇紑 `/mes/collect`锛屽叏閮ㄨ繑鍥為」鐩爣鍑� `CommonResult`銆�
+
+| 鏂规硶 | 璺緞 | 璇存槑 | 鏉冮檺 |
+|------|------|------|------|
+| GET | `/device/list` | 璁惧鏁伴噰鐘舵�佸垪琛紙鍙拌处 + 鏈�鏂扮姸鎬� + 褰撳墠浠诲姟锛� | `mes:collect:query` |
+| GET | `/realtime/get` | 鎸囧畾璁惧鏈�鏂板疄鏃剁姸鎬� | `mes:collect:query` |
+| GET | `/realtime/history-page` | 瀹炴椂鐘舵�佸巻鍙插垎椤� | `mes:collect:query` |
+| GET | `/cycle/page` | 鍛ㄦ湡杩囩▼鏁版嵁鍒嗛〉 | `mes:collect:query` |
+| GET | `/cycle/get` | 鍛ㄦ湡鏄庣粏 | `mes:collect:query` |
+| GET | `/tech/get` | 鎸囧畾璁惧鏈�鏂板伐鑹哄弬鏁板揩鐓� | `mes:collect:query` |
+| GET | `/operate-log/page` | 鍙傛暟鍙樻洿鍒嗛〉 | `mes:collect:query` |
+| GET | `/alarm/page` | 鎶ヨ鍒嗛〉 | `mes:collect:query` |
+| PUT | `/alarm/ack` | 鎵嬪伐纭鎶ヨ | `mes:collect-alarm:ack` |
+
+璁惧缁戝畾澶嶇敤鐜版湁璁惧鍙拌处鏂板/鏇存柊鎺ュ彛锛屾柊澧炲瓧娈� `collectDeviceCode`銆乣collectEnabled`锛涘彴璐﹀垎椤垫敮鎸佹寜 `collectDeviceCode` 杩囨护銆�
+
+## 8. 鏉冮檺涓庤彍鍗�
+
+- 鏂板鏉冮檺鐮侊細`mes:collect:query`銆乣mes:collect-alarm:ack`銆�
+- 鑿滃崟锛氳澶囩鐞嗭紙5300锛変笅鏂板鈥滄暟閲囩洃鎺р�濓紙`collect/monitor`锛夈��
+- 鍚屾鍐欏叆 `docs/sql/config_export_all_*.sql` 涓庢暟鎹簱鍒濆鍖栬剼鏈紝閬垮厤鏂板簱缂鸿彍鍗�/鏉冮檺銆�
+- 鎸夆�滄潈闄愮爜涓夋柟瀵归綈鈥濊鍒欙紝鑿滃崟銆佽鑹叉巿鏉冦�佸悗绔敞瑙ｄ笁澶勫悓鏃惰惤鍦般��
+
+## 9. 閮ㄧ讲涓庨獙璇�
+
+1. 鎵ц `docs/sql/mes_collect_20261020.sql`锛堟湰鍦� `mom-kyzn` 鍏堟墽琛岄獙璇侊紱鐢熶骇鐢辫繍缁存墽琛岋級銆�
+2. 鍦ㄨ澶囧彴璐﹀～鍐� `collect_device_code` 骞跺惎鐢ㄦ暟閲囥��
+3. 鍚姩鍚庣锛岀‘璁ゆ棩蹇楀嚭鐜� MQTT 杩炴帴鎴愬姛銆佽闃呮垚鍔熴��
+4. 瑙傚療 `mes_collect_message` 鏄惁鏈夊悇绫诲瀷鎶ユ枃鍏ュ簱銆�
+5. 鏍￠獙 `mes_collect_realtime / cycle / tech / operate_log / alarm` 鏁版嵁涓� EMQX 鎶ユ枃涓�鑷淬��
+6. 瑙﹀彂涓�娆″弬鏁颁慨鏀逛笌鎶ヨ锛岀‘璁ゅ彉鏇存棩蹇楀拰鎶ヨ鐘舵�佹祦杞纭��
+7. 楠岃瘉宸ュ崟鍏宠仈锛氬伐浣滅珯瀛樺湪鐢熶骇涓换鍔℃椂锛屾柊鏁版嵁鐨� `task_id/work_order_id` 涓嶄负绌恒��
+
+## 10. 椋庨櫓涓庤鏄�
+
+- **鎶ヨ涓婚鍚嶇己澶�**锛氭寜鎶ユ枃鐗瑰緛璇嗗埆锛屽凡鍏滃簳锛涘鍚庣画纭涓婚鍚嶅彧闇�鏀归厤缃��
+- **CYCN 閲嶇疆**锛氬懆鏈熷簭鍙峰彲鑳介殢璁惧閲嶅惎閲嶇疆锛屽幓閲嶉敭鍖呭惈閲囬泦鏃堕棿锛岄伩鍏嶈鍚堝苟銆�
+- **澶氬疄渚嬮儴缃�**锛氬綋鍓嶄负鍗曞疄渚嬫秷璐癸紝澶氬疄渚嬩細浜х敓閲嶅鏁版嵁锛涘悗缁彲鍒囨崲 EMQX 鍏变韩璁㈤槄銆�
+- **鏃堕挓鍋忓樊**锛氳澶囨椂闂翠笌鏈嶅姟鍣ㄦ椂闂村彲鑳戒笉涓�鑷达紝浜嬩欢鏃堕棿浠ユ姤鏂� `time` 涓哄噯锛屽彟瀛� `receive_time`銆�
+- **鏁版嵁閲�**锛氭寜 8 鍙拌澶囥��30 绉掍竴甯т及绠楋紝瀹炴椂鍘嗗彶绾� 70 涓囪/鏈堬紱濡傚悗缁彁楂橀鐜囷紝闇�璇勪及鍒嗗尯鎴栨敼鏃跺簭搴撱��
+- **涓嶄慨鏀瑰墠绔唬鐮�**锛氭寜椤圭洰瑙勫垯鍙﹁杈撳嚭鍓嶇鑱旇皟鏂规銆�
diff --git a/docs/mes_collect_frontend_integration.md b/docs/mes_collect_frontend_integration.md
new file mode 100644
index 0000000..020ca22
--- /dev/null
+++ b/docs/mes_collect_frontend_integration.md
@@ -0,0 +1,179 @@
+# 娉ㄥ鏈烘暟閲囩洃鎺� - 鍓嶇鑱旇皟鏂规
+
+## 娑夊強椤甸潰
+
+- 璁惧绠＄悊 - 璁惧鍙拌处锛堟柊澧炴暟閲囧瓧娈点�佸鍏ユā鏉匡級
+- 璁惧绠＄悊 - 鏁伴噰鐩戞帶锛堟柊澧烇級
+- 璁惧绠＄悊 - 鏁伴噰鐩戞帶 - 璁惧璇︽儏/鍘嗗彶锛堟柊澧烇級
+- 璁惧绠＄悊 - 鏁伴噰鎶ヨ锛堟柊澧烇紝鎴栦綔涓烘暟閲囩洃鎺ч〉绛撅級
+
+## 涓氬姟娴佺▼涓庢暟鎹甫鍏�
+
+1. 璁惧鍙拌处缁存姢 `collectDeviceCode`锛堝 `C01`锛夊苟鍚敤 `collectEnabled` 鍚庯紝鏁伴噰鎶ユ枃鎵嶈兘鑷姩鍏宠仈鍒拌璁惧銆�
+2. 鏁伴噰鐩戞帶鍒楄〃浠ヨ澶囧彴璐︿负鍩哄噯灞曠ず锛宍collectDeviceCode` 鏄垪琛ㄤ笌鍚勬槑缁嗘帴鍙ｄ箣闂寸殑鍞竴鍏宠仈閿紝閫変腑璁惧鍚庨渶鎶婅鍊间綔涓� `deviceCode` 甯﹀叆瀹炴椂鐘舵�併�佸伐鑹哄弬鏁般�佸懆鏈熸暟鎹�佸弬鏁板彉鏇淬�佹姤璀︽煡璇€��
+3. 鍒楄〃涓殑 `taskId / workOrderId` 鐢卞悗绔寜璁惧鎵�鍦ㄥ伐浣滅珯鑷姩瑙ｆ瀽褰撳墠杩愯浠诲姟锛屽墠绔彧璇诲睍绀猴紝涓嶉渶瑕佷紶鍙傘��
+4. 浠庡垪琛ㄨ繘鍏ユ姤璀︽椂锛屽缓璁粯璁ゅ甫鍏ュ綋鍓� `deviceCode` 涓� `status=0`锛堟湭娑堥櫎锛夛紝淇濊瘉鐢ㄦ埛鍏堢湅鍒板綋鍓嶈澶囩殑寰呭鐞嗘姤璀︺��
+
+## API
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| GET | `/mes/collect/device/list` | 鏁伴噰璁惧鐘舵�佸垪琛� |
+| GET | `/mes/collect/realtime/get` | 璁惧鏈�鏂板疄鏃剁姸鎬� |
+| GET | `/mes/collect/realtime/history-page` | 瀹炴椂鐘舵�佸巻鍙插垎椤� |
+| GET | `/mes/collect/cycle/page` | 鍛ㄦ湡杩囩▼鏁版嵁鍒嗛〉 |
+| GET | `/mes/collect/cycle/get` | 鍛ㄦ湡杩囩▼鏁版嵁鏄庣粏 |
+| GET | `/mes/collect/tech/get` | 璁惧鏈�鏂板伐鑹哄弬鏁板揩鐓� |
+| GET | `/mes/collect/operate-log/page` | 鍙傛暟鍙樻洿鏃ュ織鍒嗛〉 |
+| GET | `/mes/collect/alarm/page` | 鎶ヨ璁板綍鍒嗛〉 |
+| PUT | `/mes/collect/alarm/ack` | 浜哄伐纭娑堥櫎鎶ヨ |
+
+### 璁惧鍙拌处瀛楁鏂板
+
+鏂板/鏇存柊銆佸垎椤垫煡璇€�丒xcel 瀵煎叆瀵煎嚭鍧囬渶鏀寔浠ヤ笅瀛楁锛�
+
+| 瀛楁 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| collectDeviceCode | String | 鍚� | 鏁伴噰璁惧缂栧彿锛圡QTT devId锛夛紝鍏ㄥ眬鍞竴锛屽 `C01` |
+| collectEnabled | Boolean | 鍚� | 鏄惁鍚敤鏁伴噰锛岄粯璁ゅ惁 |
+
+- 璁惧鍙拌处鍒嗛〉鏌ヨ鏀寔鎸� `collectDeviceCode`銆乣collectEnabled` 杩囨护銆�
+- Excel 瀵煎叆妯℃澘鏂板鈥滄暟閲囪澶囩紪鍙封�濆垪锛涘悓涓�娆″鍏ュ唴閲嶅鐨勭紪鍙蜂細鏁磋澶辫触骞惰繑鍥炲叿浣撹鍙蜂笌缂栧彿銆�
+
+### 璁惧鐘舵�佸垪琛�
+
+`GET /mes/collect/device/list`
+
+鏃犺姹傚弬鏁帮紝杩斿洖宸查厤缃� `collectDeviceCode` 鐨勫叏閮ㄨ澶囥��
+
+鍝嶅簲瀛楁锛�
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| machineryId | Long | 璁惧鍙拌处缂栧彿 |
+| machineryCode | String | 璁惧缂栫爜 |
+| machineryName | String | 璁惧鍚嶇О |
+| workstationId | Long | 宸ヤ綔绔欑紪鍙� |
+| workstationName | String | 宸ヤ綔绔欏悕绉� |
+| collectDeviceCode | String | 鏁伴噰璁惧缂栧彿 |
+| collectEnabled | Boolean | 鏄惁鍚敤鏁伴噰 |
+| lastCollectTime | DateTime | 鏈�杩戦噰闆嗘椂闂� |
+| online | Boolean | 鏄惁鍦ㄧ嚎锛�5 鍒嗛挓鍐呮湁鏁版嵁锛� |
+| sts / stsName | Integer / String | 杩愯鐘舵�侊細1 寰呮満銆�2 鐢熶骇 |
+| opm / opmName | Integer / String | 杩愯妯″紡锛�0 鎵嬪姩銆�1 鍗婅嚜鍔ㄣ��2 鐢电溂鑷姩銆�3 鏃堕棿鑷姩銆�4 璋冩ā浣跨敤 |
+| ot | Decimal | 娌规俯 |
+| temps | String | 鍚勬娓╁害 JSON 瀛楃涓� |
+| taskId / taskCode / taskName | Long / String / String | 褰撳墠鐢熶骇浠诲姟 |
+| workOrderId / workOrderCode | Long / String | 褰撳墠鐢熶骇宸ュ崟 |
+| activeAlarmCount | Long | 鏈秷闄ゆ姤璀︽暟閲� |
+
+### 瀹炴椂鐘舵��
+
+`GET /mes/collect/realtime/get`锛屽弬鏁� `deviceCode`锛堝繀濉級銆�
+
+鍝嶅簲瀛楁锛歚id`銆乣machineryId`銆乣deviceCode`銆乣taskId`銆乣workOrderId`銆乣collectTime`銆乣sts/stsName`銆乣opm/opmName`銆乣asts`銆乣ot`銆乣temps`銆乣dataJson`銆傝澶囨殏鏃犳暟鎹椂 `data` 涓� `null`銆�
+
+`GET /mes/collect/realtime/history-page`
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| pageNo / pageSize | Integer | 鏄� | 鍒嗛〉鍙傛暟 |
+| deviceCode | String | 鍚� | 鏁伴噰璁惧缂栧彿 |
+| machineryId | Long | 鍚� | 璁惧鍙拌处缂栧彿 |
+| taskId | Long | 鍚� | 鐢熶骇浠诲姟缂栧彿 |
+| workOrderId | Long | 鍚� | 鐢熶骇宸ュ崟缂栧彿 |
+| collectTime | DateTime[] | 鍚� | 閲囬泦鏃堕棿鑼冨洿锛屼紶寮�濮嬨�佺粨鏉熶袱涓�� |
+
+鍝嶅簲缁撴瀯鍚屽疄鏃剁姸鎬侊紝鎸夐噰闆嗘椂闂村�掑簭銆�
+
+### 鍛ㄦ湡杩囩▼鏁版嵁
+
+`GET /mes/collect/cycle/page`
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| pageNo / pageSize | Integer | 鏄� | 鍒嗛〉鍙傛暟 |
+| deviceCode | String | 鍚� | 鏁伴噰璁惧缂栧彿 |
+| machineryId | Long | 鍚� | 璁惧鍙拌处缂栧彿 |
+| taskId | Long | 鍚� | 鐢熶骇浠诲姟缂栧彿 |
+| workOrderId | Long | 鍚� | 鐢熶骇宸ュ崟缂栧彿 |
+| collectTime | DateTime[] | 鍚� | 閲囬泦鏃堕棿鑼冨洿 |
+
+鍝嶅簲瀛楁锛歚id`銆乣machineryId`銆乣deviceCode`銆乣taskId`銆乣workOrderId`銆乣cycleNo`銆乣collectTime`銆乣ecyct`銆乣eiss`銆乣eivm`銆乣eipm`銆乣esipt`銆乣esipp`銆乣esips`銆乣eipt`銆乣eipse`銆乣eplst`銆乣eplsse`銆乣eplspm`銆乣etTemps`锛圝SON 瀛楃涓诧紝閿负 ET1..ETn锛夈�乣dataJson`銆�
+
+`GET /mes/collect/cycle/get`锛屽弬鏁� `id`锛堝繀濉級锛岃繑鍥炲崟鏉℃槑缁嗭紝瀛楁鍚屼笂銆�
+
+### 宸ヨ壓鍙傛暟蹇収
+
+`GET /mes/collect/tech/get`锛屽弬鏁� `deviceCode`锛堝繀濉級銆�
+
+鍝嶅簲瀛楁锛歚id`銆乣machineryId`銆乣deviceCode`銆乣taskId`銆乣workOrderId`銆乣collectTime`銆乣dataJson`銆俙dataJson` 涓鸿澶囦笂鎶ョ殑瀹屾暣宸ヨ壓鍙傛暟閿�煎锛岀害 150 涓彉閲忥紱鏃犳暟鎹椂 `data` 涓� `null`銆�
+
+### 鍙傛暟鍙樻洿鏃ュ織
+
+`GET /mes/collect/operate-log/page`
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| pageNo / pageSize | Integer | 鏄� | 鍒嗛〉鍙傛暟 |
+| deviceCode | String | 鍚� | 鏁伴噰璁惧缂栧彿 |
+| machineryId | Long | 鍚� | 璁惧鍙拌处缂栧彿 |
+| workOrderId | Long | 鍚� | 鐢熶骇宸ュ崟缂栧彿 |
+| varId | String | 鍚� | 鍙橀噺缂栫爜锛屽 `SIPS` |
+| modifyTime | DateTime[] | 鍚� | 鍙傛暟淇敼鏃堕棿鑼冨洿 |
+
+鍝嶅簲瀛楁锛歚id`銆乣machineryId`銆乣deviceCode`銆乣taskId`銆乣workOrderId`銆乣varId`銆乣oldValue`銆乣newValue`銆乣modifyTime`銆乣collectTime`銆乣dataJson`銆�
+
+### 鎶ヨ璁板綍
+
+`GET /mes/collect/alarm/page`
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| pageNo / pageSize | Integer | 鏄� | 鍒嗛〉鍙傛暟 |
+| deviceCode | String | 鍚� | 鏁伴噰璁惧缂栧彿 |
+| machineryId | Long | 鍚� | 璁惧鍙拌处缂栧彿 |
+| workOrderId | Long | 鍚� | 鐢熶骇宸ュ崟缂栧彿 |
+| status | Integer | 鍚� | 0 鏈秷闄ゃ��1 宸叉秷闄� |
+| wmTime | DateTime[] | 鍚� | 鎶ヨ鏃堕棿鑼冨洿 |
+
+鍝嶅簲瀛楁锛歚id`銆乣machineryId`銆乣deviceCode`銆乣taskId`銆乣workOrderId`銆乣wmId`锛�2 浜х敓銆�0 娑堝け锛夈�乣wmMsg`銆乣wmTime`銆乣status/statusName`銆乣clearTime`銆乣collectTime`銆乣dataJson`銆�
+
+`PUT /mes/collect/alarm/ack`锛屽弬鏁� `id`锛堝繀濉級锛屾棤璇锋眰浣擄紝鎴愬姛杩斿洖 `true`銆�
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| collectDeviceCode | 鍙拌处鍒楄〃銆佸彴璐﹁鎯呫�佹暟閲囩洃鎺у垪琛� | 鍙拌处鍒楄〃鍙洿鎺ュ睍绀猴紝渚夸簬鐜板満鏍稿 |
+| collectEnabled | 鍙拌处鍒楄〃銆佸彴璐﹁〃鍗� | 鏈惎鐢ㄧ殑璁惧浠嶅睍绀哄湪鐩戞帶鍒楄〃锛屼究浜庡彂鐜伴厤缃敊璇� |
+| online | 鐩戞帶鍒楄〃 | 鍦ㄧ嚎涓虹豢鑹叉爣璇嗭紝绂荤嚎涓虹伆鑹诧紱渚濇嵁 5 鍒嗛挓閲囬泦绐楀彛 |
+| sts/stsName | 鐩戞帶鍒楄〃銆佽澶囪鎯� | 鐢熶骇/寰呮満涓ゆ�� |
+| opm/opmName | 鐩戞帶鍒楄〃銆佽澶囪鎯� | 浜旀�佹灇涓撅紝鐩存帴灞曠ず涓枃鍚嶇О |
+| ot銆乼emps | 鐩戞帶鍒楄〃銆佽澶囪鎯� | `temps` 涓� JSON 瀛楃涓诧紝鍓嶇瑙ｆ瀽鍚庢寜 T1..Tn 灞曠ず |
+| taskCode/taskName銆亀orkOrderCode | 鐩戞帶鍒楄〃銆佽澶囪鎯� | 鍙锛涙棤杩愯浠诲姟鏃舵樉绀轰负绌� |
+| activeAlarmCount | 鐩戞帶鍒楄〃 | 澶т簬 0 鏃堕珮浜紝鍙偣鍑昏烦杞姤璀﹂〉绛惧苟甯﹀叆璁惧 |
+| status/statusName | 鎶ヨ鍒楄〃 | 鏈秷闄�/宸叉秷闄� |
+| dataJson | 鍚勮鎯呮娊灞� | 浣滀负鈥滃師濮嬫暟鎹�濇姌鍙犲睍绀猴紝渚夸簬鎺掗殰 |
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 璁惧鏈厤缃暟閲囩紪鍙� | 涓嶅嚭鐜板湪 `/device/list`锛屼絾鍚庣浠嶄細鎺ユ敹骞朵繚瀛樺叾鎶ユ枃锛岃ˉ缁戝彴璐﹀悗鏂版暟鎹嚜鍔ㄥ叧鑱� |
+| 璁惧绂荤嚎鍒ゅ畾 | 鏈�杩戦噰闆嗘椂闂存棭浜庡綋鍓嶆椂闂� 5 鍒嗛挓鍗崇绾匡紝涓庤澶囧惎鍋滄棤鍏� |
+| 宸ュ崟甯﹀叆 | 鍚庣鎸夎澶囧伐浣滅珯鑷姩鍖归厤鐢熶骇涓�/閮ㄥ垎瀹屾垚/宸插仠宸ヤ换鍔★紝浠诲姟鍒囨崲鏈�闀� 30 绉掔敓鏁� |
+| 鎶ヨ浜х敓 | 璁惧涓婃姤 `wmId=2` 鏂板涓�鏉℃湭娑堥櫎璁板綍锛屽悓涓�鎶ヨ閲嶅涓婃姤涓嶉噸澶嶇敓鎴� |
+| 鎶ヨ娑堝け | 璁惧涓婃姤 `wmId=0` 鑷姩鎶婅璁惧鍏ㄩ儴鏈秷闄よ褰曠疆涓哄凡娑堥櫎骞跺啓娑堥櫎鏃堕棿 |
+| 浜哄伐纭 | 浠呮湭娑堥櫎璁板綍鍙‘璁わ紱宸叉秷闄よ褰曞啀娆＄‘璁や細鎻愮ず鈥滆鎶ヨ宸叉秷闄わ紝鏃犻渶閲嶅纭鈥� |
+| 鍛ㄦ湡鏁版嵁鍘婚噸 | 鍚屼竴璁惧銆佸悓涓�鍛ㄦ湡搴忓彿銆佸悓涓�閲囬泦鏃堕棿鍙繚鐣欎竴鏉� |
+| 鏁版嵁淇濈暀 | 鍘熷鎶ユ枃 7 澶┿�佸疄鏃跺巻鍙� 30 澶╋紝鍛ㄦ湡/宸ヨ壓/鍙傛暟鍙樻洿/鎶ヨ闀挎湡淇濈暀 |
+
+## 娉ㄦ剰浜嬮」
+
+- 鎵�鏈夋暟閲囨煡璇㈡帴鍙ｉ渶鏉冮檺 `mes:collect:query`锛屼汉宸ョ‘璁ゆ姤璀﹂渶 `mes:collect-alarm:ack`銆�
+- `deviceCode` 缁熶竴浣跨敤鍙拌处 `collectDeviceCode`锛屼笉瑕佷娇鐢ㄨ澶囩紪鐮� `machineryCode`銆�
+- `collectTime`銆乣modifyTime`銆乣wmTime` 鏃堕棿鑼冨洿涓轰袱涓�硷細绗竴涓负寮�濮嬫椂闂达紝绗簩涓负缁撴潫鏃堕棿銆�
+- `temps`銆乣etTemps`銆乣dataJson` 鍧囦负 JSON 瀛楃涓诧紝闇�瑕佸墠绔簩娆¤В鏋愶紱瑙ｆ瀽澶辫触鏃舵寜鍘熸枃鏈睍绀猴紝閬垮厤椤甸潰鎶ラ敊銆�
+- 璁惧鍒楄〃鎺ュ彛涓�娆¤繑鍥炲叏閮ㄥ凡閰嶇疆鏁伴噰鐨勮澶囷紙褰撳墠 8 鍙帮級锛屼笉闇�瑕佸垎椤点��
+- 鍙拌处淇濆瓨鏃舵暟閲囩紪鍙烽噸澶嶄細杩斿洖鈥滄暟閲囪澶囩紪鍙峰凡琚叾浠栬澶囧崰鐢ㄢ�濓紝闇�鎻愮ず鐢ㄦ埛鏇存崲缂栧彿銆�
diff --git a/docs/mes_workbench_workstation_pending_count.md b/docs/mes_workbench_workstation_pending_count.md
new file mode 100644
index 0000000..6620682
--- /dev/null
+++ b/docs/mes_workbench_workstation_pending_count.md
@@ -0,0 +1,93 @@
+# 鐢熶骇宸ヤ綔鍙� - 宸ヤ綔绔欏緟瀹屾垚鏁伴噺鑱旇皟鏂规
+
+## 娑夊強椤甸潰
+
+- 鐢熶骇宸ヤ綔鍙帮紙`/mes/workbench`锛夆啋銆岄�夋嫨宸ヤ綔绔欍�嶅脊绐�
+
+## 闇�姹傝鏄�
+
+宸ヤ綔绔欏崱鐗囬渶瑕佸睍绀鸿宸ヤ綔绔欑殑**寰呭畬鎴愭暟閲�**锛屽彛寰勪笌宸ヤ綔鍙板乏渚с�屽伐鍗曞垪琛ㄣ�嶏紙寰呮姤宸ュ彴璐︼級涓�鑷达細
+
+- 浠诲姟鐘舵�佷负杩涜涓細鑽夌(0)銆佺敓浜т腑(1)銆侀儴鍒嗗畬鎴�(2)銆佸凡鍋滃伐(9)
+- 涓斾粛鏈夊緟鎶ュ伐閲忥細`鎺掍骇鏁伴噺 - 宸茬敓浜ф暟閲� > 0`
+- 鍗＄墖鏄剧ず鐨勬槸婊¤冻涓婅堪鏉′欢鐨�**浠诲姟鏉℃暟**锛屼笉鏄暟閲忔�诲拰
+
+## API
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| GET | `/mes/pro/task/pending-count-by-workstation` | 鎸夊伐浣滅珯缁熻寰呮姤宸ヤ换鍔℃潯鏁� |
+
+**璇锋眰鍙傛暟锛�** 鏃�
+
+**鍝嶅簲瀛楁锛�**
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| data | Map<Long, Long> | 宸ヤ綔绔欑紪鍙� 鈫� 寰呮姤宸ヤ换鍔℃潯鏁帮紱鏃犲緟鍔炵殑宸ヤ綔绔欎笉杩斿洖 |
+
+**鍝嶅簲绀轰緥锛�**
+
+```json
+{
+  "code": 0,
+  "data": {
+    "9": 1,
+    "10": 1,
+    "11": 1,
+    "12": 1,
+    "13": 1,
+    "14": 1,
+    "15": 1
+  },
+  "msg": ""
+}
+```
+
+**鏉冮檺锛�** `mes:pro-task:query`锛堜笌寰呮姤宸ュ彴璐︽帴鍙ｄ竴鑷达紝宸ヤ綔鍙伴〉闈㈠凡鍏峰璇ユ潈闄愶級
+
+## 鎺ュ彛璋冪敤鏃跺簭
+
+1. 鎵撳紑銆岄�夋嫨宸ヤ綔绔欍�嶅脊绐�
+2. 骞惰璇锋眰锛�
+   - `GET /mes/md-workstation/page?pageNo=1&pageSize=200` 鑾峰彇宸ヤ綔绔欏垪琛�
+   - `GET /mes/pro/task/pending-count-by-workstation` 鑾峰彇鍚勫伐浣滅珯寰呭姙鏁�
+3. 鍗＄墖娓叉煋鏃剁敤 `宸ヤ綔绔� id` 鏌ヨ鏄犲皠锛屾湭鍛戒腑鏄剧ず 0
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| 寰呭畬鎴愭暟閲� | 鍗＄墖鍚嶇О鍙充晶寰芥爣 | 鏈変换鍔℃椂姗欒壊寰芥爣"寰呭畬鎴� N"锛汵=0 鏃剁伆鑹插窘鏍�"寰呭畬鎴� 0" |
+| 寰呭畬鎴愭暟閲� | 寰芥爣 hover 鎻愮ず | "璇ュ伐浣滅珯寰呮姤宸ヤ换鍔℃暟锛歂" |
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 缁熻鍙ｅ緞 | 涓庛�屽緟鎶ュ伐鍙拌处銆嶅畬鍏ㄤ竴鑷达紝閬垮厤鍗＄墖鏁伴噺涓庡乏渚у伐鍗曞垪琛ㄥ涓嶄笂 |
+| 缁熻鎺ュ彛澶辫触 | 闅愯棌鍏ㄩ儴寰芥爣锛屼笉褰卞搷宸ヤ綔绔欏垪琛ㄥ姞杞戒笌閫夋嫨锛堢粺璁′负杈呭姪淇℃伅锛� |
+| 宸ヤ綔绔欐殏鏃犲緟鍔� | 鏄剧ず鐏拌壊"寰呭畬鎴� 0"锛屼繚鎸佸崱鐗囧竷灞�涓�鑷� |
+| 鏁伴噺鍚箟 | 浠诲姟鏉℃暟锛涘悓涓�宸ヤ綔绔欏鏉′换鍔℃椂鎸夋潯绱姞锛屼笉鍚堝苟涓烘暟閲忓悎璁� |
+
+## 娉ㄦ剰浜嬮」
+
+- 缁熻鎺ュ彛杩斿洖鐨� Map key 鏄瓧绗︿覆褰㈠紡鐨勫伐浣滅珯缂栧彿锛屽墠绔寜 `String(宸ヤ綔绔檌d)` 鍙栧��
+- 寮圭獥姣忔鎵撳紑閮戒細閲嶆柊璇锋眰缁熻锛屾姤宸ュ悗閲嶆柊鎵撳紑鍗冲彲鐪嬪埌鏈�鏂版暟閲�
+- 璇ユ帴鍙ｈ繑鍥炲叏閲忓伐浣滅珯缁熻锛屾暟鎹噺寰堝皬锛堟瘡宸ヤ綔绔欎竴琛岋級锛屾棤闇�鎸夊伐浣滅珯 id 杩囨护
+- 鑻ュ悗缁渶瑕�"寰呭畬鎴愭暟閲忔�诲拰"锛堝墿浣欏彲鎶ュ伐閲忓悎璁★級锛屽彲澶嶇敤鍚屼竴鏌ヨ澧炲姞 `SUM(quantity - produced_quantity)` 瀛楁锛屾棤闇�鏂板鎺ュ彛
+
+## 鍚庣鏀瑰姩
+
+| 鏂囦欢 | 鏀瑰姩 |
+|------|------|
+| `MesProTaskMapper` | 鏂板 `selectPendingFeedbackCountByWorkstation()`锛屾寜 `workstation_id` 鍒嗙粍缁熻 |
+| `MesProTaskService` / `Impl` | 鏂板 `getPendingFeedbackCountByWorkstation()`锛岃繑鍥� Map |
+| `MesProTaskController` | 鏂板 `GET /pending-count-by-workstation` 鎺ュ彛 |
+
+## 鍓嶇鏀瑰姩
+
+| 鏂囦欢 | 鏀瑰姩 |
+|------|------|
+| `src/api/mes/pro/task/index.ts` | 鏂板 `getPendingFeedbackCountByWorkstation()` |
+| `src/views/mes/workbench/components/WorkstationSelectDialog.vue` | 骞惰鍔犺浇缁熻锛屽崱鐗囧悕绉拌澧炲姞寰呭畬鎴愬窘鏍� |
diff --git a/docs/route_process_output_attribution.md b/docs/route_process_output_attribution.md
new file mode 100644
index 0000000..a099447
--- /dev/null
+++ b/docs/route_process_output_attribution.md
@@ -0,0 +1,112 @@
+# 宸ヨ壓璺嚎宸ュ簭浜у嚭褰掑睘 - 鍓嶇鑱旇皟鏂规
+
+## 娑夊強椤甸潰
+
+- 宸ヨ壓璺嚎 - 宸ュ簭涓庝骇鍑洪〉绛� - 宸ュ簭鏂板/缂栬緫寮圭獥锛坧rocess-form.vue锛�
+- 宸ヨ壓璺嚎 - 鍚敤鍓嶆鏌ワ紙route-configurator.vue锛�
+- 鐢熶骇宸ュ崟 - 鏂板/缂栬緫寮圭獥 - 宸ュ簭鍒楄〃锛堝彈褰掑睘杩囨护褰卞搷锛屾棤闇�鏂板瀛楁锛�
+- 鐢熶骇浠诲姟 - 鑷姩鐢熸垚浠诲姟锛堜骇鍑虹墿鏂欐寜褰掑睘甯﹀叆锛�
+
+## 涓氬姟娴佺▼涓庢暟鎹甫鍏�
+
+1. 宸ヨ壓璺嚎宸ュ簭鐨勪骇鍑虹墿鏂欐柊澧炪�屽綊灞炪�嶆蹇碉細
+   - 褰掑睘涓虹┖ = 澶氫骇鍝侀�氱敤锛堣璺嚎涓嬫墍鏈変骇鍝侀兘浼氫骇鍑鸿鐗╂枡锛岄�傚悎鍚岀嚎鍏辩敤鐨勫崐鎴愬搧锛夛紱
+   - 褰掑睘涓烘煇涓骇鍝� = 浜у搧涓撳睘锛堝彧鏈夌敓浜ц浜у搧鏃舵墠浼氫骇鍑猴級銆�
+2. 閫夋嫨浜у嚭鐗╂枡鏃堕粯璁ゅ綊灞炲埌鐗╂枡鑷韩锛涘浜у搧鍏辩敤鐨勫崐鎴愬搧闇�鎵嬪姩鏀逛负銆岄�氱敤銆嶃��
+3. 涓嬪崟锛堟柊寤哄伐鍗曪級鏃讹紝鎸夊伐鍗曚骇鍝佽繃婊ゅ伐鑹鸿矾绾垮伐搴忎骇鍑猴細鍙甫鍏ャ�岄�氱敤銆嶄骇鍑哄拰銆岃浜у搧涓撳睘銆嶄骇鍑恒��
+4. 鑷姩鐢熸垚浠诲姟鏃讹紝浠诲姟浜у嚭鐗╂枡鍚屾牱鎸夊綊灞炶繃婊わ紝浼樺厛鍙栬繃婊ゅ悗鐨勭涓�涓骇鍑猴紱娌℃湁浜у嚭鏃跺彇宸ュ崟鎴愬搧銆�
+5. 鏈亾宸ュ簭鐨勬垚鍝佷骇鍑哄繀椤诲綊灞炲埌鑷韩浜у搧锛堜笉鑳戒负銆岄�氱敤銆嶏級锛屽惁鍒欏惎鐢ㄨ矾绾挎椂浼氭姤閿欍��
+
+## API
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| POST | /mes/pro/route-process/create | 鏂板宸ュ簭锛堣姹傛柊澧� outputs锛� |
+| PUT | /mes/pro/route-process/update | 淇敼宸ュ簭锛堣姹傛柊澧� outputs锛� |
+| GET | /mes/pro/route-process/get | 宸ュ簭璇︽儏锛堝搷搴旀柊澧� outputs锛� |
+| GET | /mes/pro/route-process/list-by-route | 鎸夎矾绾胯幏鍙栧伐搴忥紙鍝嶅簲鏂板 outputs锛� |
+| GET | /mes/pro/route-process/list-by-product | 鎸変骇鍝佽幏鍙栧伐搴忥紙浜у嚭宸叉寜褰掑睘杩囨护锛� |
+
+**璇锋眰鍙傛暟鏂板锛坈reate / update锛夛細**
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| outputs | Array | 鍚� | 浜у嚭鐗╂枡褰掑睘閰嶇疆锛屼紶鍏ュ悗浼樺厛浜� outputItemIds |
+| outputs[].itemId | Long | 鏄� | 浜у嚭鐗╂枡缂栧彿锛屽繀椤绘槸鏈矾绾跨粦瀹氱殑浜у搧 |
+| outputs[].productId | Long | 鍚� | 褰掑睘浜у搧缂栧彿锛涗笉浼犳垨浼犵┖琛ㄧず澶氫骇鍝侀�氱敤 |
+| outputs[].sort | Integer | 鍚� | 鎺掑簭锛屼笉浼犳寜鏁扮粍椤哄簭 |
+| outputs[].remark | String | 鍚� | 澶囨敞 |
+
+> 鍏煎璇存槑锛氫粛鍙彧浼� outputItemIds锛堣�侀〉闈�/宸ヨ壓璁捐椤碉級锛屽悗绔細鑷姩鍒ゅ畾褰掑睘鈥斺�斾骇鍑烘槸璺嚎缁戝畾浜у搧鏃跺綊灞炲埌鑷韩锛屽惁鍒欒涓洪�氱敤銆�
+
+**鍝嶅簲瀛楁鏂板锛坓et / list-by-route / list-by-product锛夛細**
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| outputs | Array | 浜у嚭褰掑睘鍒楄〃 |
+| outputs[].id | Long | 褰掑睘璁板綍缂栧彿 |
+| outputs[].routeProcessId | Long | 宸ュ簭缂栧彿 |
+| outputs[].productId | Long | 褰掑睘浜у搧缂栧彿锛岀┖琛ㄧず閫氱敤 |
+| outputs[].productName | String | 褰掑睘浜у搧鍚嶇О |
+| outputs[].itemId | Long | 浜у嚭鐗╂枡缂栧彿 |
+| outputs[].itemCode | String | 浜у嚭鐗╂枡缂栫爜 |
+| outputs[].itemName | String | 浜у嚭鐗╂枡鍚嶇О |
+| outputs[].sort | Integer | 鎺掑簭 |
+| outputs[].remark | String | 澶囨敞 |
+
+**鍝嶅簲绀轰緥锛�**
+
+```json
+{
+  "code": 0,
+  "data": {
+    "id": 123,
+    "processName": "鍖呰鍏ュ簱",
+    "outputs": [
+      {
+        "productId": 201,
+        "productName": "娌规蹈寮忛厤鐢靛彉鍘嬪櫒",
+        "itemId": 201,
+        "itemName": "娌规蹈寮忛厤鐢靛彉鍘嬪櫒",
+        "sort": 1
+      },
+      {
+        "productId": null,
+        "productName": null,
+        "itemId": 300,
+        "itemName": "閫氱敤鍖呰绠�",
+        "sort": 2
+      }
+    ]
+  }
+}
+```
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| outputs | 宸ュ簭鏂板/缂栬緫寮圭獥銆屾湰宸ュ簭浜у嚭銆� | 姣忚涓や釜涓嬫媺锛氫骇鍑虹墿鏂欍�佸綊灞烇紱鎻愪緵銆屾坊鍔犱骇鍑恒�嶃�屽垹闄ゃ�� |
+| 褰掑睘涓嬫媺 | 宸ュ簭鏂板/缂栬緫寮圭獥 | 閫夐」涓恒�岄�氱敤锛堟墍鏈変骇鍝侊級銆�+ 璺嚎浜у搧鍒楄〃 |
+| 浜у嚭鐗╂枡涓嬫媺 | 宸ュ簭鏂板/缂栬緫寮圭獥 | 閫夐」闄愬畾涓鸿矾绾跨粦瀹氱殑浜у搧 |
+| outputs | 宸ュ簭鍒楄〃銆屾湰宸ュ簭浜у嚭銆嶅垪 | 灞曠ず涓恒�岀墿鏂欏悕锛堝綊灞炰骇鍝佸悕锛夈�嶆垨銆岀墿鏂欏悕锛堥�氱敤锛夈�� |
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 閫夋嫨浜у嚭鐗╂枡 | 榛樿褰掑睘鍒扮墿鏂欒嚜韬紝鍙墜鍔ㄦ敼涓恒�岄�氱敤銆� |
+| 澶氫骇鍝佸叡鐢ㄥ崐鎴愬搧 | 褰掑睘閫夋嫨銆岄�氱敤銆嶏紝鎵�鏈変骇鍝佷笅鍗曟椂閮戒細甯﹀叆璇ヤ骇鍑� |
+| 浜у搧涓撳睘浜у嚭 | 褰掑睘閫夋嫨瀵瑰簲浜у搧锛屽彧鏈夎浜у搧鐨勫伐鍗�/浠诲姟浼氬甫鍏� |
+| 鏈亾宸ュ簭鎴愬搧 | 姣忎釜鎴愬搧蹇呴』褰掑睘鍒拌嚜韬骇鍝侊紝涓嶈兘浣跨敤銆岄�氱敤銆� |
+| 瀛橀噺鏁版嵁 | 鍘� output_item_id 鑷姩鎷嗗垎锛氭槸璺嚎浜у搧鐨勫綊灞炲埌鑷韩锛屽惁鍒欒涓洪�氱敤 |
+| 鍙紶 outputItemIds | 鍚庣鑷姩鎸夈�岃矾绾夸骇鍝佲啋涓撳睘銆佸叾瀹冣啋閫氱敤銆嶅垽瀹氬綊灞� |
+| 浜у嚭鑱氬悎瀛楁 | output_item_id 浠嶄繚鐣欏苟鑷姩鑱氬悎锛屼緵浠诲姟銆佺墿鏂欓渶姹傜瓑鏃ч�昏緫浣跨敤 |
+
+## 娉ㄦ剰浜嬮」
+
+- 褰掑睘浜у搧涓嬫媺鐨勯�夐」灏辨槸褰撳墠宸ヨ壓璺嚎缁戝畾鐨勪骇鍝佸垪琛紝鏈粦瀹氫骇鍝佷笉鑳戒綔涓哄綊灞炪��
+- 浜у嚭鐗╂枡蹇呴』灞炰簬璺嚎缁戝畾浜у搧锛屽惁鍒欏惎鐢ㄨ矾绾挎椂浼氭姤銆屼骇鍑烘湭缁戝畾鍒板綋鍓嶅伐鑹鸿矾绾裤�嶃��
+- 鍚屼竴閬撳伐搴忓彲浠ュ悓鏃跺瓨鍦ㄩ�氱敤浜у嚭鍜屽涓骇鍝佷笓灞炰骇鍑恒��
+- 宸ュ簭浜у嚭褰掑睘淇濆瓨鍚庯紝宸插垱寤虹殑宸ュ崟宸ュ簭蹇収涓嶅彈褰卞搷锛堝揩鐓у湪涓嬪崟鏃舵寜褰撴椂鐨勫綊灞炶繃婊わ級銆�
+- 宸ヨ壓璺嚎鍚敤鏃讹紝鏈亾宸ュ簭鑻ュ瓨鍦ㄣ�岄�氱敤銆嶆垚鍝佷骇鍑轰細鏍￠獙澶辫触锛岄渶瑕佸湪宸ュ簭缂栬緫涓敼涓轰骇鍝佷笓灞炪��
diff --git a/docs/sale_order_production_cancel_integration.md b/docs/sale_order_production_cancel_integration.md
new file mode 100644
index 0000000..2dc6ea9
--- /dev/null
+++ b/docs/sale_order_production_cancel_integration.md
@@ -0,0 +1,84 @@
+# 閿�鍞鍗曠敓浜х姸鎬佲�滃凡鍙栨秷鈥� - 鍓嶇鑱旇皟鏂规
+
+## 娑夊強椤甸潰
+
+- ERP 閿�鍞鍗曞垪琛ㄩ〉
+- ERP 閿�鍞鍗曡鎯呴〉
+
+## 涓氬姟鑳屾櫙
+
+鐢熶骇璁″垝锛圡PS锛夊彇娑堟椂锛屼細鍚屾鏇存柊鏉ユ簮閿�鍞鍗曠殑鐢熶骇鐘舵�併�傛鍓嶅彇娑堝悗璁㈠崟鍙細鍥炲埌鈥滄湭瀹屾垚鈥濓紝鏃犳硶鍖哄垎鈥滀粠鏈敓浜р�濆拰鈥滅敓浜ц鍒掑凡鍙栨秷鈥濄�傜幇鏂板鐢熶骇鐘舵�� `2-宸插彇娑坄銆�
+
+鐘舵�佸彇鍊硷細
+
+| productionStatus | 鍚箟 | 瑙﹀彂鏃舵満 |
+|------------------|------|----------|
+| 0 | 鏈畬鎴� | 璁㈠崟瀹℃牳閫氳繃鐢熸垚鐢熶骇璁″垝锛涙垨鍙栨秷鍚庨噸鏂板鏍哥敓鎴愪簡鏂扮殑鐢熶骇璁″垝 |
+| 1 | 宸插畬鎴� | 鐢熶骇瀹屾垚浜嬩欢锛圥roductionFinishedEvent锛� |
+| 2 | 宸插彇娑� | 鏉ユ簮鐢熶骇璁″垝琚彇娑堬紙ProductionCanceledEvent锛� |
+
+## API
+
+鎺ュ彛璺緞涓庡弬鏁版棤鍙樺寲锛屼粎鍝嶅簲瀛楁 `productionStatus` 澧炲姞鍙栧�� `2`銆�
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| GET | /erp/sale-order/page | 閿�鍞鍗曞垎椤� |
+| GET | /erp/sale-order/get | 閿�鍞鍗曡鎯� |
+
+**鍝嶅簲瀛楁锛�**
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| productionStatus | Integer | 鐢熶骇鐘舵�侊細0-鏈畬鎴愶紝1-宸插畬鎴愶紝2-宸插彇娑� |
+| productionFinishTime | DateTime | 鐢熶骇瀹屾垚鏃堕棿锛屼粎 productionStatus=1 鏃舵湁鍊� |
+
+**鍝嶅簲绀轰緥锛�**
+
+```json
+{
+  "code": 0,
+  "data": {
+    "id": 1310,
+    "no": "XSDD20261026000002",
+    "needProduction": 1,
+    "productionStatus": 2,
+    "productionFinishTime": null
+  }
+}
+```
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| productionStatus | 鍒楄〃鈥滅敓浜х姸鎬佲�濆垪 | 闈炩�滄棤闇�鐢熶骇鈥濇椂鎸� 0/1/2 鍒嗗埆灞曠ず鏈畬鎴� / 宸插畬鎴� / 宸插彇娑堬紱寤鸿鈥滃凡鍙栨秷鈥濅娇鐢ㄥ尯鍒簬鈥滃凡瀹屾垚鈥濈殑閱掔洰棰滆壊 |
+| productionStatus | 璇︽儏椤碘�滅敓浜х姸鎬佲�� | 鍚屼笂锛屼粎鍦ㄦ槑缁嗛渶瑕佺敓浜ф椂灞曠ず |
+| productionFinishTime | 鍒楄〃銆佽鎯� | 浠呭湪 productionStatus=1 鏃跺睍绀猴紝鐘舵�佷负 2 鏃朵笉灞曠ず |
+
+## 鏌ヨ绛涢�夎鍒�
+
+鍒楄〃绛涢�夆�滅敓浜х姸鎬佲�濅笅鎷夐渶鏂板閫夐」锛�
+
+| 閫夐」 | 浼犲弬 |
+|------|------|
+| 鏃犻渶鐢熶骇 | needProduction=0锛堟部鐢ㄧ幇鏈夌壒娈婂鐞嗭級 |
+| 鏈畬鎴� | productionStatus=0 |
+| 宸插畬鎴� | productionStatus=1 |
+| 宸插彇娑� | productionStatus=2 |
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 鍙栨秷鐢熶骇璁″垝 | 閿�鍞鍗� productionStatus 缃负 2锛宲roductionFinishTime 娓呯┖ |
+| 鍙栨秷鍚庨噸鏂板鏍歌鍗� | 绯荤粺妫�娴嬪埌鍘熺敓浜ц鍒掑凡鍙栨秷锛屼細閲嶆柊鐢熸垚鏂扮殑鐢熶骇璁″垝锛屽苟鎶婅鍗� productionStatus 閲嶇疆涓� 0 |
+| 璁㈠崟瀛樺湪鏈夋晥鐢熶骇璁″垝鏃跺啀娆″鏍� | 澶嶇敤宸叉湁鐢熶骇璁″垝锛屼笉鏀瑰彉鐢熶骇鐘舵�� |
+| 涓�鍗曞鏄庣粏 | 鐢熶骇鐘舵�佷负璁㈠崟绾э紱浠讳竴鏄庣粏鍙栨秷鐢熶骇璁″垝锛屾暣鍗曟樉绀衡�滃凡鍙栨秷鈥� |
+
+## 娉ㄦ剰浜嬮」
+
+- 璁㈠崟鐘舵�� `status`锛堟湭瀹℃牳/宸插鏍�/宸蹭綔搴燂級涓嶅彈鐢熶骇璁″垝鍙栨秷褰卞搷锛屼粛淇濇寔鈥滃凡瀹℃牳鈥濄��
+- productionStatus=2 鏃惰鍗曚粛鍙墽琛屽弽瀹℃牳銆佺紪杈戯紝閲嶆柊瀹℃牳鍚庝細鑷姩鐢熸垚鏂扮敓浜ц鍒掋��
+- 鍘嗗彶宸插彇娑堢殑鐢熶骇璁″垝瀵瑰簲鐨勮鍗曚笉浼氳拷婧埛鏂帮紝浠嶆樉绀哄師鐘舵�侊紱濡傞渶淇璇峰崟鐙鐞嗗瓨閲忔暟鎹��
+- 鍓嶇绛涢�変笅鎷夋柊澧炩�滃凡鍙栨秷鈥濆悗锛屽巻鍙蹭笂姝ゅ墠鍙栨秷涓旂姸鎬佸凡琚疆涓� 0 鐨勮鍗曚粛浼氳惤鍦ㄢ�滄湭瀹屾垚鈥濈瓫閫夐」涓嬨��
diff --git a/docs/work_order_process_warehouse_integration.md b/docs/work_order_process_warehouse_integration.md
new file mode 100644
index 0000000..fe87281
--- /dev/null
+++ b/docs/work_order_process_warehouse_integration.md
@@ -0,0 +1,110 @@
+# 鐢熶骇宸ュ崟宸ュ簭鎶ュ伐浠撳簱 - 鍓嶇鑱旇皟鏂规
+
+## 娑夊強椤甸潰
+
+- 鐢熶骇宸ュ崟 - 鏂板/缂栬緫寮圭獥 - 宸ュ簭鍒楄〃锛坧rocess-list.vue锛�
+- 鐢熶骇宸ュ崟 - 宸ュ簭鏂板/缂栬緫寮圭獥锛坧rocess-form.vue锛�
+- 宸ヨ壓璺嚎 - 浜у搧椤电锛堝伐鑹鸿矾绾夸骇鍝佹姤宸ヤ粨搴撻厤缃紝浣滀负宸ュ簭榛樿鍊兼潵婧愶級
+
+## 涓氬姟娴佺▼涓庢暟鎹甫鍏�
+
+1. 宸ヨ壓璺嚎浜у搧閰嶇疆鎶ュ伐浠撳簱锛坄mes_pro_route_product` 鐨� `warehouseId/locationId/areaId`锛夛紝璇ラ厤缃槸宸ュ簭鐨�**榛樿鍊兼潵婧�**銆�
+2. 鐢熶骇璁㈠崟涓嬪崟锛堟柊寤哄伐鍗曪級鏃讹紝宸ュ簭鍒楄〃浠庡伐鑹鸿矾绾垮甫鍏ワ紝宸ュ簭鐨勬姤宸ヤ粨搴�/搴撳尯/搴撲綅榛樿鍙栧伐鑹鸿矾绾夸骇鍝佺殑閰嶇疆銆�
+3. 涓嬪崟鏃跺彲瀵规瘡閬撳伐搴忓崟鐙慨鏀规姤宸ヤ粨搴�/搴撳尯/搴撲綅锛屼慨鏀圭粨鏋滈殢宸ュ崟宸ュ簭涓�璧蜂繚瀛橈紙宸ュ崟宸ュ簭涓哄揩鐓э紝涓嶅彈鍚庣画宸ヨ壓璺嚎淇敼褰卞搷锛夈��
+4. 鐢熶骇鎶ュ伐瀹℃壒閫氳繃鍚庯紝浜у嚭鐗╂枡鎸変互涓嬩紭鍏堢骇鍐冲畾鍏ュ簱浣嶇疆锛�
+   - 鈶� 宸ュ崟宸ュ簭涓婇厤缃殑鎶ュ伐浠撳簱/搴撳尯/搴撲綅锛�
+   - 鈶� 宸ヨ壓璺嚎浜у搧涓婇厤缃殑鎶ュ伐浠撳簱/搴撳尯/搴撲綅锛�
+   - 鈶� 铏氭嫙绾胯竟浠擄紙鍘嗗彶鏁版嵁鍏滃簳锛夈��
+5. 宸ュ崟宸插瓨鍦ㄤ絾宸ュ簭鏈厤缃粨搴擄紙鏈鏀归�犲墠鐨勫巻鍙插伐鍗曪級鏃讹紝鑷姩璧� 鈶°�佲憿锛屾棤闇�琛ユ暟鎹��
+
+## API
+
+| 鏂规硶 | 璺緞 | 璇存槑 |
+|------|------|------|
+| GET | /mes/pro/route-process/list-by-product | 鎸変骇鍝佽幏鍙栧伐鑹鸿矾绾垮伐搴忓垪琛紙鏂板锛氶粯璁ゆ姤宸ヤ粨搴擄級 |
+| GET | /mes/pro/work-order-process/list-by-product-id | 鎸変骇鍝佽幏鍙栧伐鍗曞伐搴忛濉垪琛紙鏂板锛氶粯璁ゆ姤宸ヤ粨搴擄級 |
+| GET | /mes/pro/work-order-process/list-by-work-order-id | 鑾峰彇宸ュ崟宸ュ簭鍒楄〃锛堟柊澧烇細鎶ュ伐浠撳簱鍙婂悕绉帮級 |
+| GET | /mes/pro/work-order-process/get | 鑾峰彇宸ュ崟宸ュ簭璇︽儏锛堟柊澧烇細鎶ュ伐浠撳簱鍙婂悕绉帮級 |
+| POST | /mes/pro/work-order-process/batch-save | 鎵归噺淇濆瓨宸ュ崟宸ュ簭锛堣姹傛柊澧炰粨搴撳瓧娈碉級 |
+| POST/PUT | /mes/pro/work-order-process/create銆�/update | 鍗曟潯鏂板/淇敼锛堣姹傛柊澧炰粨搴撳瓧娈碉級 |
+
+**璇锋眰鍙傛暟锛坆atch-save / create / update锛夛細**
+
+| 鍙傛暟 | 绫诲瀷 | 蹇呭～ | 璇存槑 |
+|------|------|------|------|
+| warehouseId | Long | 鍚� | 鎶ュ伐浠撳簱缂栧彿锛屼笉濉垯鎸夊伐鑹鸿矾绾夸骇鍝佸厹搴� |
+| locationId | Long | 鍚� | 鎶ュ伐搴撳尯缂栧彿锛岄渶涓� warehouseId 鍖归厤 |
+| areaId | Long | 鍚� | 鎶ュ伐搴撲綅缂栧彿锛岄渶涓� locationId 鍖归厤 |
+
+> 浠撳簱/搴撳尯/搴撲綅涓夎�呭悓鏃跺～鍐欐椂锛屽悗绔牎楠屽眰绾у綊灞炲叧绯伙紱鍙～閮ㄥ垎鏃讹紝鎶ュ伐浜у嚭鎸夊伐鑹鸿矾绾夸骇鍝佸厹搴曘��
+
+**鍝嶅簲瀛楁鏂板锛坙ist-by-product銆乴ist-by-work-order-id銆乬et 绛夊伐搴忔煡璇㈡帴鍙ｏ級锛�**
+
+| 瀛楁 | 绫诲瀷 | 璇存槑 |
+|------|------|------|
+| warehouseId | Long | 鎶ュ伐浠撳簱缂栧彿 |
+| warehouseName | String | 鎶ュ伐浠撳簱鍚嶇О |
+| locationId | Long | 鎶ュ伐搴撳尯缂栧彿 |
+| locationName | String | 鎶ュ伐搴撳尯鍚嶇О |
+| areaId | Long | 鎶ュ伐搴撲綅缂栧彿 |
+| areaName | String | 鎶ュ伐搴撲綅鍚嶇О |
+
+**鍝嶅簲绀轰緥锛�**
+
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "processId": 1,
+      "processName": "鐒婃帴",
+      "sort": 1,
+      "warehouseId": 5,
+      "warehouseName": "鍗婃垚鍝佷粨",
+      "locationId": 12,
+      "locationName": "閫氱敤搴撳尯",
+      "areaId": 31,
+      "areaName": "榛樿搴撲綅"
+    }
+  ]
+}
+```
+
+## 瀛楁灞曠ず瑙勫垯
+
+| 瀛楁 | 灞曠ず浣嶇疆 | 璇存槑 |
+|------|----------|------|
+| warehouseName | 宸ュ崟宸ュ簭鍒楄〃銆屾姤宸ヤ粨搴撱�嶅垪 | 鏈夊簱浣嶆椂鎷兼帴鏄剧ず銆屼粨搴�/搴撳尯/搴撲綅銆嶏紝鏈厤缃樉绀恒��-銆� |
+| warehouseId | 宸ュ簭鏂板/缂栬緫寮圭獥 | 涓嬫媺鍗曢�夛紝閫夐」鏉ヨ嚜浠撳簱绮剧畝鍒楄〃锛屽厑璁告竻绌� |
+| locationId | 宸ュ簭鏂板/缂栬緫寮圭獥 | 涓嬫媺鍗曢�夛紝渚濊禆 warehouseId锛屼粨搴撳彉鏇存椂娓呯┖ |
+| areaId | 宸ュ簭鏂板/缂栬緫寮圭獥 | 涓嬫媺鍗曢�夛紝渚濊禆 locationId锛屽簱鍖哄彉鏇存椂娓呯┖ |
+
+## 浜у嚭鐗╂枡杩囨护
+
+鍚屼竴宸ヨ壓璺嚎鍙互鍏宠仈澶氫釜浜у搧锛堝伐鑹鸿矾绾夸骇鍝侊級銆備笅鍗�/鎺掍骇鎸変骇鍝佽幏鍙栧伐鑹鸿矾绾垮伐搴忔椂锛屽伐搴忕殑浜у嚭鐗╂枡浼氳嚜鍔ㄨ繃婊わ紝鍙繚鐣欍�岄�氱敤浜у嚭銆嶅拰銆屽綋鍓嶄骇鍝佷笓灞炰骇鍑恒�嶏紝鍏跺畠浜у搧鐨勪笓灞炰骇鍑轰笉浼氬甫鍏ャ��
+
+浜у嚭褰掑睘鍦ㄥ伐鑹鸿矾绾垮伐搴忓脊绐椾腑閰嶇疆锛氫骇鍑虹墿鏂欏彲褰掑睘鍒版煇涓骇鍝侊紙涓撳睘锛夛紝涔熷彲鐣欑┖琛ㄧず澶氫骇鍝侀�氱敤锛堥�傚悎鍚岀嚎鍏辩敤鐨勫崐鎴愬搧锛夈�傝瑙� `docs/route_process_output_attribution.md`銆�
+
+绀轰緥锛氳矾绾垮悓鏃跺叧鑱斻�屾补娴稿紡閰嶇數鍙樺帇鍣ㄣ�嶅拰銆屽厜浼忓浐瀹氭敮鏋躲�嶏紝鍖呰鍏ュ簱宸ュ簭鍒嗗埆涓轰袱涓骇鍝侀厤缃笓灞炰骇鍑恒�備笅鍗曘�屽厜浼忓浐瀹氭敮鏋躲�嶆椂锛岃宸ュ簭鍙甫鍏ャ�屽厜浼忓浐瀹氭敮鏋躲�嶏紱鑻ヨ宸ュ簭杩樻湁涓�涓�岄�氱敤銆嶅崐鎴愬搧浜у嚭锛屼篃浼氫竴骞跺甫鍏ャ��
+
+> 宸ヨ壓璺嚎閰嶇疆椤碉紙鎸� routeId 鏌ヨ锛変笉鍙楀奖鍝嶏紝浠嶅睍绀哄叏閮ㄥ凡閰嶇疆鐨勪骇鍑虹墿鏂欏強鍏跺綊灞炪��
+
+宸ュ崟宸ュ簭鏂板/缂栬緫寮圭獥涓殑銆屼骇鍑虹墿鏂欍�嶉�夋嫨鍣ㄥ悓鏍锋寜姝よ鍒欐敹鏁涳細鍊欓�夎寖鍥� = 璇ヤ骇鍝佸伐鑹鸿矾绾夸腑甯﹀叆鐨勪骇鍑猴紙閫氱敤 + 鏈骇鍝佷笓灞烇級+ 璇ュ伐搴忓凡鏈変骇鍑� + 宸ュ崟浜у搧鏈韩銆備骇鍝佹湭鍏宠仈宸ヨ壓璺嚎鏃朵笉鍋氶檺鍒讹紝淇濇寔鍘熸湁鍙�夎寖鍥淬��
+
+## 涓氬姟瑙勫垯璇存槑
+
+| 鍦烘櫙 | 瑙勫垯 |
+|------|------|
+| 鏂板缓宸ュ崟甯﹀叆宸ュ簭 | 浠撳簱/搴撳尯/搴撲綅榛樿鍙栧伐鑹鸿矾绾夸骇鍝佺殑鎶ュ伐浠撳簱閰嶇疆锛屽彲閫愬伐搴忎慨鏀� |
+| 淇敼宸ュ簭浠撳簱 | 淇敼鍚庨殢宸ュ簭淇濆瓨鍒板伐鍗曞伐搴忓揩鐓э紝鎶ュ伐鎸夊揩鐓ф墽琛� |
+| 宸ヨ壓璺嚎鍚庣画淇敼 | 涓嶅奖鍝嶅凡鍒涘缓鐨勫伐鍗曞伐搴忓揩鐓� |
+| 宸ュ簭鏈厤缃粨搴� | 鎶ュ伐浜у嚭鍥為��鍒板伐鑹鸿矾绾夸骇鍝侀厤缃紝鍐嶅洖閫�铏氭嫙绾胯竟浠� |
+| 浠撳簱灞傜骇涓嶅尮閰� | 鍚庣鏍￠獙 `warehouse 鈫� location 鈫� area` 褰掑睘鍏崇郴锛屼笉鍖归厤鏃舵姤閿� |
+| 鍊掑啿鎵ｆ枡 | 浠嶅浐瀹氫粠铏氭嫙绾胯竟浠撴墸鏂欙紝涓庝骇鍑轰粨搴撴棤鍏� |
+
+## 娉ㄦ剰浜嬮」
+
+- 宸ュ簭浠撳簱涓夌骇瀛楁涓哄彲閫夛細鍘嗗彶宸ュ崟宸ュ簭娌℃湁浠撳簱鏁版嵁鏃讹紝鎶ュ伐鑷姩鍥為��锛屼笉浼氭姤閿欍��
+- 鍓嶇疆浠撳簱銆佸簱鍖恒�佸簱浣嶄笅鎷夋暟鎹垎鍒潵鑷� `/mes/wm/warehouse/simple-list`銆乣/mes/wm/warehouse-location/simple-list?warehouseId=`銆乣/mes/wm/warehouse-area/simple-list?locationId=`銆�
+- 鍙竻绌轰粨搴撹�屼笉娓呯┖搴撳尯/搴撲綅浼氫骇鐢熻剰鏁版嵁锛屽墠绔湪涓婄骇瀛楁鍙樻洿鏃堕渶绾ц仈娓呯┖涓嬬骇瀛楁銆�
+- 浜у嚭浠撳簱鏀逛负瀹為檯浠撳簱鍚庯紝铏氭嫙绾胯竟浠撶殑搴撳瓨涓嶅啀闅忎骇鍑哄鍔狅紙鍊掑啿鎵ｆ枡浠嶄粠铏氭嫙浠撴墸鍑忥級锛屽睘浜庨鏈熻涓恒��
diff --git a/sql/mysql/20261028_sp_generic_shift_dates.sql b/sql/mysql/20261028_sp_generic_shift_dates.sql
new file mode 100644
index 0000000..911fee8
--- /dev/null
+++ b/sql/mysql/20261028_sp_generic_shift_dates.sql
@@ -0,0 +1,290 @@
+-- sp_generic_shift_dates锛氭寜鎸囧畾鏃堕棿绐楀彛骞崇Щ搴撳唴鏃ユ湡绫诲瓧娈�
+-- 淇鐐癸細
+-- 1) 鍞竴绱㈠紩鍖呭惈鏃ユ湡鍒楃殑琛紙濡� hrm_attendance_record.uk_user_date锛夋敼涓烘暣琛ㄧ粺涓�骞崇Щ锛�
+--    甯搁噺鍋忕Щ涓嶄細鐮村潖鍞竴閿紝閬垮厤 1062 Duplicate entry
+-- 2) 鍗曡〃鎵ц澶辫触涓嶅啀涓柇鏁磋疆锛岄敊璇鍏ラ瑙堣〃鍚庣户缁鐞嗗悗缁〃
+
+DROP PROCEDURE IF EXISTS `sp_generic_shift_dates`;
+
+DELIMITER $$
+
+CREATE DEFINER = `root`@`%` PROCEDURE `sp_generic_shift_dates`(
+    IN p_schema VARCHAR(64),
+    IN p_start DATETIME,
+    IN p_end DATETIME,
+    IN p_execute BOOLEAN,
+    IN p_exclude_regex VARCHAR(1000),
+    IN p_include_regex VARCHAR(1000)
+)
+BEGIN
+    DECLARE v_done BOOL DEFAULT FALSE;
+    DECLARE v_table VARCHAR(64);
+    DECLARE v_pk VARCHAR(64);
+    DECLARE v_pk_count INT;
+    DECLARE v_cols LONGTEXT;
+    DECLARE v_anchor VARCHAR(64);
+    DECLARE v_sql LONGTEXT;
+    DECLARE v_seconds BIGINT;
+    DECLARE v_count BIGINT DEFAULT 0;
+    DECLARE v_tables BIGINT DEFAULT 0;
+    DECLARE v_fields INT;
+    DECLARE v_uniq_hit INT;
+    DECLARE v_uniq_cols VARCHAR(1000);
+    DECLARE v_min_expr LONGTEXT;
+    DECLARE v_max_expr LONGTEXT;
+    DECLARE v_regex VARCHAR(1000);
+    DECLARE v_err TEXT;
+    DECLARE cur CURSOR FOR
+        SELECT t.TABLE_NAME
+        FROM information_schema.TABLES t
+        WHERE t.TABLE_SCHEMA = p_schema
+          AND t.TABLE_TYPE = 'BASE TABLE'
+          AND (p_exclude_regex IS NULL OR TRIM(p_exclude_regex) = ''
+               OR NOT REGEXP_LIKE(t.TABLE_NAME, p_exclude_regex, 'i'))
+        ORDER BY t.TABLE_NAME;
+    DECLARE CONTINUE HANDLER FOR NOT FOUND SET v_done = TRUE;
+
+    IF p_schema IS NULL OR p_schema = '' OR p_schema IN ('mysql','information_schema','performance_schema','sys') THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Invalid or system schema';
+    END IF;
+    IF p_start IS NULL OR p_end IS NULL OR p_end < p_start THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Invalid date range';
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = p_schema) THEN
+        SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Schema not found';
+    END IF;
+
+    -- 鍒楁竻鍗曞彲鑳藉緢闀匡紝閬垮厤 GROUP_CONCAT 琚粯璁� 1024 瀛楄妭鎴柇
+    SET SESSION group_concat_max_len = 1048576;
+
+    SET v_seconds = TIMESTAMPDIFF(SECOND, p_start, p_end);
+    -- 绌轰覆涓嶆槸 NULL锛屽繀椤绘樉寮忓綊涓�鍖栵細MySQL 8 鐨� REGEXP_LIKE 閬囧埌绌烘ā寮忎細鎶� 3685
+    IF p_include_regex IS NULL OR TRIM(p_include_regex) = '' THEN
+        SET v_regex = '(^|_)(create|created|update|updated|modify|modified|order|production|produce|receipt|receive|delivery|ship|stock|inbound|outbound|start|end|finish|complete|plan|actual|inspect|check|approve|audit|pay|payment|due|expire|expiry|effective|business|biz|date|time|timestamp)(_|$)';
+    ELSE
+        SET v_regex = p_include_regex;
+    END IF;
+
+    DROP TEMPORARY TABLE IF EXISTS tmp_date_shift_preview;
+    CREATE TEMPORARY TABLE tmp_date_shift_preview (
+        table_name VARCHAR(64),
+        anchor_column VARCHAR(64),
+        shift_mode VARCHAR(16),
+        field_count INT,
+        affected_rows BIGINT,
+        statement_text LONGTEXT
+    );
+
+    OPEN cur;
+    loop_tables: LOOP
+        FETCH cur INTO v_table;
+        IF v_done THEN LEAVE loop_tables; END IF;
+
+        SELECT COUNT(*), MAX(k.COLUMN_NAME) INTO v_pk_count, v_pk
+        FROM information_schema.KEY_COLUMN_USAGE k
+        WHERE k.TABLE_SCHEMA = p_schema AND k.TABLE_NAME = v_table AND k.CONSTRAINT_NAME = 'PRIMARY';
+        IF v_pk_count <> 1 THEN ITERATE loop_tables; END IF;
+
+        SELECT COUNT(*) INTO v_fields
+        FROM information_schema.COLUMNS c
+        WHERE c.TABLE_SCHEMA = p_schema AND c.TABLE_NAME = v_table
+          AND c.DATA_TYPE IN ('date','datetime','timestamp')
+          AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+          AND c.EXTRA NOT LIKE '%on update%'
+          AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i');
+        IF v_fields = 0 THEN ITERATE loop_tables; END IF;
+
+        SELECT c.COLUMN_NAME INTO v_anchor
+        FROM information_schema.COLUMNS c
+        WHERE c.TABLE_SCHEMA = p_schema AND c.TABLE_NAME = v_table
+          AND c.DATA_TYPE IN ('date','datetime','timestamp')
+          AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+          AND c.EXTRA NOT LIKE '%on update%'
+          AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i')
+        ORDER BY CASE WHEN c.COLUMN_NAME IN ('create_time','created_at','creation_time','created_time') THEN 0 ELSE 1 END,
+                 c.ORDINAL_POSITION
+        LIMIT 1;
+
+        -- 寰呭钩绉荤殑鏃ユ湡鍒椾腑鏄惁鏈夎惤鍦ㄥ敮涓�绱㈠紩涓婄殑
+        SELECT COUNT(*) INTO v_uniq_hit
+        FROM information_schema.STATISTICS s
+        JOIN information_schema.COLUMNS c
+          ON c.TABLE_SCHEMA = s.TABLE_SCHEMA
+         AND c.TABLE_NAME = s.TABLE_NAME
+         AND c.COLUMN_NAME = s.COLUMN_NAME
+        WHERE s.TABLE_SCHEMA = p_schema AND s.TABLE_NAME = v_table AND s.NON_UNIQUE = 0
+          AND c.DATA_TYPE IN ('date','datetime','timestamp')
+          AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+          AND c.EXTRA NOT LIKE '%on update%'
+          AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i');
+
+        SET @tbl = CONCAT('`', REPLACE(p_schema,'`','``'), '`.`', REPLACE(v_table,'`','``'), '`');
+        SET @anchor = CONCAT('`', REPLACE(v_anchor,'`','``'), '`');
+
+        inner_block: BEGIN
+            DECLARE EXIT HANDLER FOR SQLEXCEPTION
+            BEGIN
+                GET DIAGNOSTICS CONDITION 1 v_err = MESSAGE_TEXT;
+                INSERT INTO tmp_date_shift_preview
+                VALUES (v_table, v_anchor, 'failed', v_fields, 0, CONCAT('[error] ', v_err));
+            END;
+
+            IF v_uniq_hit > 0 THEN
+                -- 缁熶竴骞崇Щ锛氭暣琛ㄤ娇鐢ㄥ悓涓�鍋忕Щ锛屼繚鐣欏敮涓�閿��
+                -- 鍋忕Щ閲忔寜鎵�鏈夊緟骞崇Щ鍒楃殑鏁翠綋璺ㄥ害璁＄畻锛屼繚璇佹瘡涓�鍒楅兘钀藉湪鐩爣绐楀彛鍐呫��
+                -- COALESCE 淇濇姢锛氭暣鍒椾负 NULL 鏃� MIN/MAX 杩斿洖 NULL锛屼細璁� LEAST/GREATEST 鏁翠綋鍙� NULL
+                SELECT GROUP_CONCAT(CONCAT('COALESCE(MIN(`', REPLACE(c.COLUMN_NAME,'`','``'), '`), ''9999-12-31 23:59:59'')')
+                                    ORDER BY c.ORDINAL_POSITION SEPARATOR ', '),
+                       GROUP_CONCAT(CONCAT('COALESCE(MAX(`', REPLACE(c.COLUMN_NAME,'`','``'), '`), ''1000-01-01 00:00:00'')')
+                                    ORDER BY c.ORDINAL_POSITION SEPARATOR ', ')
+                INTO v_min_expr, v_max_expr
+                FROM information_schema.COLUMNS c
+                WHERE c.TABLE_SCHEMA = p_schema AND c.TABLE_NAME = v_table
+                  AND c.DATA_TYPE IN ('date','datetime','timestamp')
+                  AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+                  AND c.EXTRA NOT LIKE '%on update%'
+                  AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i');
+
+                SET @sql = CONCAT('SELECT LEAST(', v_min_expr, '), GREATEST(', v_max_expr,
+                                  ') INTO @min_all, @max_all FROM ', @tbl);
+                PREPARE stmt FROM @sql;
+                EXECUTE stmt;
+                DEALLOCATE PREPARE stmt;
+
+                SET @span_days = TIMESTAMPDIFF(DAY, DATE(@min_all), DATE(@max_all));
+                SET @range_days = TIMESTAMPDIFF(DAY, DATE(p_start), DATE(p_end));
+
+                IF @min_all IS NULL OR @min_all >= '9999-01-01' THEN
+                    INSERT INTO tmp_date_shift_preview
+                    VALUES (v_table, v_anchor, 'skipped', v_fields, 0, 'no non-null date value');
+                ELSEIF @span_days > @range_days THEN
+                    INSERT INTO tmp_date_shift_preview
+                    VALUES (v_table, v_anchor, 'skipped', v_fields, 0,
+                            CONCAT('date span ', @span_days, ' days exceeds target range ', @range_days, ' days'));
+                ELSE
+                    -- 鎸夋暣鏃ュ钩绉伙紝淇濈暀鏃跺垎绉掍笌鐩稿椤哄簭
+                    SET @shift_delta = (TIMESTAMPDIFF(DAY, DATE(@min_all), DATE(p_start))
+                                        + FLOOR(RAND() * (@range_days - @span_days + 1))) * 86400;
+                    -- 闅忔満鍒� 0 澶╃瓑浜庢病鏀癸紝寮哄埗鑷冲皯骞崇Щ 1 澶�
+                    IF @shift_delta = 0 AND @span_days < @range_days THEN
+                        SET @shift_delta = 86400;
+                    END IF;
+
+                    SELECT GROUP_CONCAT(
+                               CONCAT('`', REPLACE(c.COLUMN_NAME,'`','``'), '` = DATE_ADD(`',
+                                      REPLACE(c.COLUMN_NAME,'`','``'), '`, INTERVAL @shift_delta SECOND)')
+                               ORDER BY c.ORDINAL_POSITION SEPARATOR ', ')
+                    INTO v_cols
+                    FROM information_schema.COLUMNS c
+                    WHERE c.TABLE_SCHEMA = p_schema AND c.TABLE_NAME = v_table
+                      AND c.DATA_TYPE IN ('date','datetime','timestamp')
+                      AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+                      AND c.EXTRA NOT LIKE '%on update%'
+                      AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i');
+
+                    -- InnoDB 閫愯鏇存柊鍞竴閿細鐬椂鍐茬獊锛屾寜鍋忕Щ鏂瑰悜鍐冲畾鎵弿椤哄簭锛�
+                    -- 姝ｅ亸绉诲厛鍔ㄨ緝澶х殑鍊硷紝璐熷亸绉诲厛鍔ㄨ緝灏忕殑鍊�
+                    SELECT GROUP_CONCAT(CONCAT('`', REPLACE(d.COLUMN_NAME,'`','``'), '`')
+                                        ORDER BY d.ORDINAL_POSITION SEPARATOR ', ')
+                    INTO v_uniq_cols
+                    FROM (
+                        SELECT DISTINCT c.COLUMN_NAME, c.ORDINAL_POSITION
+                        FROM information_schema.STATISTICS s
+                        JOIN information_schema.COLUMNS c
+                          ON c.TABLE_SCHEMA = s.TABLE_SCHEMA
+                         AND c.TABLE_NAME = s.TABLE_NAME
+                         AND c.COLUMN_NAME = s.COLUMN_NAME
+                        WHERE s.TABLE_SCHEMA = p_schema AND s.TABLE_NAME = v_table AND s.NON_UNIQUE = 0
+                          AND c.DATA_TYPE IN ('date','datetime','timestamp')
+                          AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+                          AND c.EXTRA NOT LIKE '%on update%'
+                          AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i')
+                    ) d;
+
+                    SET @update_sql = CONCAT('UPDATE ', @tbl, ' SET ', v_cols,
+                                             ' ORDER BY ', v_uniq_cols, ' ',
+                                             IF(@shift_delta >= 0, 'DESC', 'ASC'));
+                    SET @count_sql = CONCAT('SELECT COUNT(*) INTO @affected FROM ', @tbl);
+                    PREPARE stmt FROM @count_sql;
+                    EXECUTE stmt;
+                    DEALLOCATE PREPARE stmt;
+
+                    IF p_execute THEN
+                        PREPARE stmt FROM @update_sql;
+                        EXECUTE stmt;
+                        DEALLOCATE PREPARE stmt;
+                    END IF;
+
+                    SET v_count = v_count + @affected;
+                    INSERT INTO tmp_date_shift_preview
+                    VALUES (v_table, v_anchor, IF(p_execute, 'uniform-executed', 'uniform-preview'),
+                            v_fields, @affected, @update_sql);
+                    SET v_tables = v_tables + 1;
+                END IF;
+            ELSE
+                -- 閫愯闅忔満锛氭瘡琛屼竴涓殢鏈虹洰鏍囨椂闂达紝浠ラ敋鐐规暣浣撳钩绉�
+                SELECT GROUP_CONCAT(
+                           CONCAT('`', REPLACE(c.COLUMN_NAME,'`','``'), '` = CASE WHEN `',
+                                  REPLACE(c.COLUMN_NAME,'`','``'), '` IS NULL THEN NULL ELSE ',
+                                  CASE WHEN c.DATA_TYPE = 'date' THEN 'DATE(' ELSE '' END,
+                                  'DATE_ADD(`', REPLACE(c.COLUMN_NAME,'`','``'), '`, INTERVAL TIMESTAMPDIFF(SECOND, `',
+                                  REPLACE(v_anchor,'`','``'), '`, __new_anchor) SECOND)',
+                                  CASE WHEN c.DATA_TYPE = 'date' THEN ')' ELSE '' END, ' END')
+                           ORDER BY c.ORDINAL_POSITION SEPARATOR ', ')
+                INTO v_cols
+                FROM information_schema.COLUMNS c
+                WHERE c.TABLE_SCHEMA = p_schema AND c.TABLE_NAME = v_table
+                  AND c.DATA_TYPE IN ('date','datetime','timestamp')
+                  AND c.EXTRA NOT LIKE '%VIRTUAL GENERATED%' AND c.EXTRA NOT LIKE '%STORED GENERATED%'
+                  AND c.EXTRA NOT LIKE '%on update%'
+                  AND REGEXP_LIKE(c.COLUMN_NAME, v_regex, 'i');
+
+                DROP TEMPORARY TABLE IF EXISTS tmp_shift_row_dates;
+                SET @sql = CONCAT('CREATE TEMPORARY TABLE tmp_shift_row_dates AS SELECT `',
+                                  REPLACE(v_pk,'`','``'), '` AS __pk, DATE_ADD(?, INTERVAL FLOOR(RAND() * ',
+                                  v_seconds + 1, ') SECOND) AS __new_anchor FROM ', @tbl,
+                                  ' WHERE ', @anchor, ' IS NOT NULL');
+
+                IF p_execute THEN
+                    PREPARE stmt FROM @sql;
+                    SET @start_date = p_start;
+                    EXECUTE stmt USING @start_date;
+                    DEALLOCATE PREPARE stmt;
+
+                    SET @update_sql = CONCAT('UPDATE ', @tbl, ' t JOIN tmp_shift_row_dates s ON t.`',
+                                             REPLACE(v_pk,'`','``'), '` = s.__pk SET ',
+                                             REPLACE(v_cols, '__new_anchor', 's.__new_anchor'));
+                    SET @count_sql = 'SELECT COUNT(*) INTO @affected FROM tmp_shift_row_dates';
+                    PREPARE stmt FROM @count_sql;
+                    EXECUTE stmt;
+                    DEALLOCATE PREPARE stmt;
+
+                    PREPARE stmt FROM @update_sql;
+                    EXECUTE stmt;
+                    DEALLOCATE PREPARE stmt;
+
+                    SET v_count = v_count + @affected;
+                    INSERT INTO tmp_date_shift_preview
+                    VALUES (v_table, v_anchor, 'random-executed', v_fields, @affected, @update_sql);
+                    DROP TEMPORARY TABLE tmp_shift_row_dates;
+                ELSE
+                    SET @count_sql = CONCAT('SELECT COUNT(*) INTO @affected FROM ', @tbl, ' WHERE ', @anchor, ' IS NOT NULL');
+                    PREPARE stmt FROM @count_sql;
+                    EXECUTE stmt;
+                    DEALLOCATE PREPARE stmt;
+                    INSERT INTO tmp_date_shift_preview
+                    VALUES (v_table, v_anchor, 'random-preview', v_fields, @affected,
+                            CONCAT('Will shift ', v_fields, ' date columns per row; anchor=', v_anchor));
+                END IF;
+                SET v_tables = v_tables + 1;
+            END IF;
+        END inner_block;
+    END LOOP;
+    CLOSE cur;
+
+    SELECT * FROM tmp_date_shift_preview ORDER BY shift_mode, table_name;
+    SELECT p_schema AS database_name, p_execute AS executed,
+           v_tables AS tables_processed, v_count AS rows_targeted;
+END$$
+
+DELIMITER ;

--
Gitblit v1.9.3