From 4e8817d7686924641d778d314f9cc555dc69f131 Mon Sep 17 00:00:00 2001 From: eaiadmin Date: Tue, 18 Aug 2026 20:19:58 +0800 Subject: [PATCH] =?UTF-8?q?init:=20=E6=95=B0=E5=AD=97=E5=91=98=E5=B7=A5?= =?UTF-8?q?=E5=B9=B3=E5=8F=B0=E5=88=9D=E5=A7=8B=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含前端（Vue3 + VueFlow 画布）、后端（Go）、文档体系。 - 工作台画布：节点拖放、连线模式、右键菜单、AI 助手 - 后端：连接器 API、专员种子数据 - 导航：左侧导航、工坊、市场、控制台 --- .gitattributes | 9 + .gitignore | 35 + CODING_RULES.md | 243 ++ debug-admin-auth-misjudge.md | 21 + docs/00_AI_Context/README.md | 16 + .../forai01_engineering_progress.md | 35 + ...2_2026-08-16_导航品牌与系统配置调整交接.md | 102 + docs/01_System_Overall/README.md | 44 + .../01_System_Overall/SY01_System_Overview.md | 81 + .../SY02_Design_Principles.md | 64 + ...owledge_Centric_Agent_Platform_Strategy.md | 728 +++++ ...gin_Workflow_Ontology_Delivery_Platform.md | 344 +++ ...ork_Enterprise_Integration_Architecture.md | 535 ++++ ...grade_Starting_Point_Decision_Framework.md | 286 ++ ..._Industry_Agent_Pack_Landscape_Overview.md | 215 ++ .../SY08_Legal_Industry_Agent_Pack.md | 202 ++ .../SY09_Healthcare_Industry_Agent_Pack.md | 185 ++ .../SY10_Industrial_Industry_Agent_Pack.md | 178 ++ .../SY11_Financial_Industry_Agent_Pack.md | 177 ++ ..._Freight_Forwarding_Industry_Agent_Pack.md | 168 ++ ...merce_Microbusiness_Industry_Agent_Pack.md | 164 ++ ...ctor_And_Application_Requirement_Matrix.md | 360 +++ ...rk_Ontology_Semantic_Layer_Object_Layer.md | 460 +++ ..._Generalizes_Data_Actions_And_Workflows.md | 505 ++++ .../SY17_Workbench_UI_Wireframes.md | 628 ++++ .../SY18_DWP_DW_ADW_Formal_Design_Contract.md | 995 +++++++ ...Y18_Specialist_Minimal_Definition_Model.md | 202 ++ docs/02_Architecture/AR01_Backend_Arch.md | 173 ++ docs/02_Architecture/AR02_Frontend_Arch.md | 175 ++ docs/02_Architecture/AR03_Database_Arch.md | 83 + docs/02_Architecture/AR04_Deploy_Arch.md | 140 + docs/02_Architecture/README.md | 16 + docs/04_Backend/BE01_Auth_Module.md | 155 + docs/04_Backend/BE02_Exam_Module.md | 136 + docs/04_Backend/BE03_Media_Module.md | 233 ++ docs/04_Backend/BE04_AI_Chat_Module.md | 350 +++ .../BE05_Knowledge_Ingest_Module.md | 226 ++ .../BE06_AI_Config_Credits_Module.md | 226 ++ docs/04_Backend/README.md | 18 + docs/06_Product_Lines/PL01_Global_Layout.md | 379 +++ docs/06_Product_Lines/PL02_Employee_Views.md | 266 ++ docs/06_Product_Lines/PL03_Admin_Views.md | 266 ++ docs/06_Product_Lines/README.md | 15 + docs/08_Design_Rules/DR01_Theme_System.md | 257 ++ docs/08_Design_Rules/DR02_Navigation_Rules.md | 146 + .../08_Design_Rules/DR03_Interaction_Rules.md | 113 + docs/08_Design_Rules/README.md | 15 + .../Workflow_Canvas_Interaction_Research.md | 625 ++++ docs/09_Research/工业AI观察员/README.md | 19 + docs/09_Research/工业AI观察员/assets/img1.jpg | 3 + docs/09_Research/工业AI观察员/assets/img2.jpg | 3 + docs/09_Research/工业AI观察员/assets/img3.jpg | 3 + docs/09_Research/工业AI观察员/assets/img4.jpg | 3 + docs/09_Research/工业AI观察员/assets/img5.jpg | 3 + ...造：一个硬核项目怎么帮客户省下真金白银.md | 73 + .../cb09274421816d69abb794f5b90ed9cc.jpg | 3 + .../博昇慧源AI研究院 · 技术能力概览 · V1.0.md | 312 ++ .../博昇慧源AI研究院（EAI）· 完整版介绍.md | 310 ++ .../博昇慧源xBAI·AI落地产品与方案体系 V1.0.md | 464 +++ ...力中心-资本化合作提案_分页幻灯片版_32页.md | 1105 +++++++ docs/PRD.md | 196 ++ docs/api.md | 576 ++++ docs/changelog.md | 183 ++ docs/db_schema.md | 336 +++ docs/deploy.md | 222 ++ docs/eaisalestrain_app设计稿.md | 493 ++++ docs/博昇产品与渠道合作表.md | 120 + docs/完整分析_pj0231_vs_pj006-zhilianyuan2.md | 383 +++ docs/对比分析_pj0231_vs_pj006-zhilianyuan2.md | 161 + docs/设计稿_岗位与知识对应能力.md | 406 +++ eai_ap_app/.gitignore | 29 + eai_ap_app/CLAUDE.md | 85 + eai_ap_app/PROJECT_STATE.md | 105 + eai_ap_app/backend-go/cmd/server/main.go | 62 + eai_ap_app/backend-go/config/ai_config.json | 1 + .../backend-go/config/ai_secrets.example.json | 12 + eai_ap_app/backend-go/config/platform.json | 8 + eai_ap_app/backend-go/deploy/DELIVERY.md | 133 + .../backend-go/deploy/clonezilla-cleanup.sh | 80 + .../backend-go/deploy/eaisalestrain.env | 31 + .../backend-go/deploy/eaisalestrain.service | 33 + eai_ap_app/backend-go/go.mod | 52 + eai_ap_app/backend-go/go.sum | 122 + eai_ap_app/backend-go/internal/ai/credits.go | 82 + eai_ap_app/backend-go/internal/ai/llm.go | 397 +++ eai_ap_app/backend-go/internal/ai/retrieve.go | 163 ++ .../backend-go/internal/ai/retrieve_test.go | 42 + .../backend-go/internal/api/ai_admin.go | 63 + eai_ap_app/backend-go/internal/api/ai_chat.go | 209 ++ .../backend-go/internal/api/ai_usage.go | 166 ++ eai_ap_app/backend-go/internal/api/auth.go | 75 + .../backend-go/internal/api/certificate.go | 69 + .../backend-go/internal/api/company_train.go | 115 + .../backend-go/internal/api/connectors.go | 59 + eai_ap_app/backend-go/internal/api/courses.go | 169 ++ .../backend-go/internal/api/department.go | 275 ++ .../backend-go/internal/api/essay_grade.go | 88 + eai_ap_app/backend-go/internal/api/exam.go | 1212 ++++++++ .../backend-go/internal/api/exam_test.go | 139 + eai_ap_app/backend-go/internal/api/helpers.go | 19 + .../backend-go/internal/api/knowledge.go | 391 +++ .../internal/api/knowledge_export.go | 338 +++ .../backend-go/internal/api/learning.go | 114 + eai_ap_app/backend-go/internal/api/media.go | 596 ++++ eai_ap_app/backend-go/internal/api/note.go | 137 + .../backend-go/internal/api/notification.go | 88 + eai_ap_app/backend-go/internal/api/points.go | 90 + .../backend-go/internal/api/position.go | 397 +++ .../backend-go/internal/api/products.go | 207 ++ eai_ap_app/backend-go/internal/api/profile.go | 162 + eai_ap_app/backend-go/internal/api/router.go | 179 ++ eai_ap_app/backend-go/internal/api/routes.go | 51 + .../backend-go/internal/api/specialist.go | 342 +++ eai_ap_app/backend-go/internal/api/stats.go | 384 +++ eai_ap_app/backend-go/internal/api/system.go | 348 +++ eai_ap_app/backend-go/internal/auth/auth.go | 58 + .../backend-go/internal/config/config.go | 107 + .../backend-go/internal/config/json_loader.go | 552 ++++ .../backend-go/internal/connector/kingdee.go | 645 ++++ .../internal/connector/kingdee_test.go | 93 + .../internal/connector/static_catalog.go | 373 +++ .../backend-go/internal/connector/types.go | 94 + .../backend-go/internal/middleware/auth.go | 103 + .../backend-go/internal/model/ai_call_log.go | 23 + .../backend-go/internal/model/certificate.go | 20 + .../backend-go/internal/model/course.go | 24 + .../backend-go/internal/model/department.go | 16 + .../backend-go/internal/model/exam_paper.go | 22 + .../backend-go/internal/model/exam_record.go | 21 + .../internal/model/knowledge_chunk.go | 17 + .../internal/model/knowledge_source.go | 22 + .../internal/model/learning_progress.go | 15 + .../backend-go/internal/model/media_file.go | 26 + .../internal/model/mistake_record.go | 23 + .../backend-go/internal/model/notification.go | 17 + .../backend-go/internal/model/point_event.go | 17 + .../backend-go/internal/model/position.go | 27 + .../internal/model/position_exam_blueprint.go | 18 + .../internal/model/position_knowledge.go | 20 + .../backend-go/internal/model/product.go | 24 + .../backend-go/internal/model/question.go | 20 + .../backend-go/internal/model/specialist.go | 38 + .../backend-go/internal/model/study_note.go | 16 + .../internal/model/system_config.go | 14 + eai_ap_app/backend-go/internal/model/user.go | 23 + eai_ap_app/backend-go/internal/store/db.go | 62 + eai_ap_app/backend-go/internal/store/seed.go | 649 ++++ .../internal/store/specialist_records.go | 271 ++ eai_ap_app/backend-go/internal/web/errors.go | 37 + .../backend-go/internal/web/response.go | 17 + .../knowledge_source/01_通用规则.md | 66 + .../knowledge_source/02_资本咨询类.md | 94 + .../knowledge_source/03_资质认定辅导类.md | 86 + .../knowledge_source/04_AI咨询与实施类.md | 141 + .../knowledge_source/05_企业级AI工具与平台.md | 313 ++ .../knowledge_source/06_资质认定政策与实操.md | 165 ++ .../knowledge_source/07_资本运作与股权融资.md | 165 ++ .../knowledge_source/08_企业AI落地方法论.md | 166 ++ .../knowledge_source/09_顾问式销售方法论.md | 166 ++ .../knowledge_source/10_管理员审批测试样本.md | 46 + .../backend-go/knowledge_source/README.md | 76 + eai_ap_app/frontend/index.html | 12 + eai_ap_app/frontend/package-lock.json | 1833 ++++++++++++ eai_ap_app/frontend/package.json | 24 + .../frontend/public/studio-design-mockup.html | 714 +++++ eai_ap_app/frontend/src/App.vue | 21 + eai_ap_app/frontend/src/api/ai.js | 95 + eai_ap_app/frontend/src/api/auth.js | 9 + eai_ap_app/frontend/src/api/certificate.js | 10 + eai_ap_app/frontend/src/api/company.js | 5 + eai_ap_app/frontend/src/api/connector.js | 13 + eai_ap_app/frontend/src/api/courses.js | 17 + eai_ap_app/frontend/src/api/department.js | 23 + eai_ap_app/frontend/src/api/exam.js | 71 + eai_ap_app/frontend/src/api/http.js | 38 + eai_ap_app/frontend/src/api/knowledge.js | 42 + eai_ap_app/frontend/src/api/learning.js | 9 + eai_ap_app/frontend/src/api/media.js | 13 + eai_ap_app/frontend/src/api/note.js | 18 + eai_ap_app/frontend/src/api/notification.js | 17 + eai_ap_app/frontend/src/api/position.js | 51 + eai_ap_app/frontend/src/api/products.js | 21 + eai_ap_app/frontend/src/api/profile.js | 16 + eai_ap_app/frontend/src/api/specialist.js | 25 + eai_ap_app/frontend/src/api/system.js | 90 + .../frontend/src/components/NotePanel.vue | 168 ++ .../frontend/src/components/VideoPlayer.vue | 476 +++ .../src/components/charts/BarChart.vue | 147 + .../src/components/charts/DonutChart.vue | 145 + .../src/components/charts/LineChart.vue | 149 + .../src/components/charts/RadarChart.vue | 128 + eai_ap_app/frontend/src/config/navigation.js | 112 + eai_ap_app/frontend/src/config/workbench.js | 764 +++++ eai_ap_app/frontend/src/layout/MainLayout.vue | 898 ++++++ .../frontend/src/layout/PathCoachPanel.vue | 254 ++ .../frontend/src/layout/SectionTabs.vue | 119 + eai_ap_app/frontend/src/layout/SideNav.vue | 228 ++ eai_ap_app/frontend/src/main.js | 20 + eai_ap_app/frontend/src/router/guards.js | 28 + eai_ap_app/frontend/src/router/index.js | 61 + eai_ap_app/frontend/src/store/aiChat.js | 35 + eai_ap_app/frontend/src/store/auth.js | 46 + eai_ap_app/frontend/src/store/notification.js | 22 + eai_ap_app/frontend/src/store/workbench.js | 78 + eai_ap_app/frontend/src/styles/global.css | 77 + eai_ap_app/frontend/src/utils/labels.js | 65 + eai_ap_app/frontend/src/views/Login.vue | 180 ++ .../frontend/src/views/Notification.vue | 159 + .../src/views/companyTrain/CompanyTrain.vue | 140 + .../frontend/src/views/exam/ExamFormal.vue | 251 ++ .../frontend/src/views/exam/ExamMyRecord.vue | 165 ++ .../frontend/src/views/exam/ExamSelfTest.vue | 221 ++ .../frontend/src/views/exam/Leaderboard.vue | 90 + .../src/views/exam/MyCertificates.vue | 157 + .../frontend/src/views/exam/MyMistakes.vue | 342 +++ .../frontend/src/views/exam/MyPosition.vue | 100 + .../frontend/src/views/exam/MyProfile.vue | 158 + .../frontend/src/views/home/HomePage.vue | 464 +++ .../src/views/knowledge/ExamQuestionBank.vue | 548 ++++ .../src/views/knowledge/ExamRecordManage.vue | 502 ++++ .../src/views/knowledge/MaterialAudit.vue | 208 ++ .../src/views/knowledge/MaterialManage.vue | 394 +++ .../src/views/product/ProductDetail.vue | 97 + .../src/views/product/ProductList.vue | 220 ++ .../src/views/salesTrain/CourseDetail.vue | 152 + .../src/views/salesTrain/CourseList.vue | 163 ++ .../frontend/src/views/system/AiUsage.vue | 262 ++ .../src/views/system/CompanyConfigPage.vue | 114 + .../src/views/system/DepartmentManage.vue | 206 ++ .../src/views/system/PositionManage.vue | 440 +++ .../src/views/system/SystemConfigPage.vue | 316 ++ .../frontend/src/views/system/UserManage.vue | 482 +++ .../src/views/workbench/BusinessAppPage.vue | 877 ++++++ .../src/views/workbench/ConsolePage.vue | 230 ++ .../src/views/workbench/KnowledgeHub.vue | 132 + .../src/views/workbench/MarketPage.vue | 1431 +++++++++ .../src/views/workbench/StudioPage.vue | 2600 +++++++++++++++++ eai_ap_app/frontend/vite.config.js | 39 + start_dev_10231_10232.sh | 285 ++ 239 files changed, 48631 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 CODING_RULES.md create mode 100644 debug-admin-auth-misjudge.md create mode 100644 docs/00_AI_Context/README.md create mode 100644 docs/00_AI_Context/forai01_engineering_progress.md create mode 100644 docs/00_AI_Context/forai02_2026-08-16_导航品牌与系统配置调整交接.md create mode 100644 docs/01_System_Overall/README.md create mode 100644 docs/01_System_Overall/SY01_System_Overview.md create mode 100644 docs/01_System_Overall/SY02_Design_Principles.md create mode 100644 docs/01_System_Overall/SY03_Knowledge_Centric_Agent_Platform_Strategy.md create mode 100644 docs/01_System_Overall/SY04_Plugin_Workflow_Ontology_Delivery_Platform.md create mode 100644 docs/01_System_Overall/SY05_Connector_Network_Enterprise_Integration_Architecture.md create mode 100644 docs/01_System_Overall/SY06_AI_Upgrade_Starting_Point_Decision_Framework.md create mode 100644 docs/01_System_Overall/SY07_Industry_Agent_Pack_Landscape_Overview.md create mode 100644 docs/01_System_Overall/SY08_Legal_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY09_Healthcare_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY10_Industrial_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY11_Financial_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY12_Logistics_Freight_Forwarding_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY13_Social_Commerce_Microbusiness_Industry_Agent_Pack.md create mode 100644 docs/01_System_Overall/SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md create mode 100644 docs/01_System_Overall/SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md create mode 100644 docs/01_System_Overall/SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md create mode 100644 docs/01_System_Overall/SY17_Workbench_UI_Wireframes.md create mode 100644 docs/01_System_Overall/SY18_DWP_DW_ADW_Formal_Design_Contract.md create mode 100644 docs/01_System_Overall/SY18_Specialist_Minimal_Definition_Model.md create mode 100644 docs/02_Architecture/AR01_Backend_Arch.md create mode 100644 docs/02_Architecture/AR02_Frontend_Arch.md create mode 100644 docs/02_Architecture/AR03_Database_Arch.md create mode 100644 docs/02_Architecture/AR04_Deploy_Arch.md create mode 100644 docs/02_Architecture/README.md create mode 100644 docs/04_Backend/BE01_Auth_Module.md create mode 100644 docs/04_Backend/BE02_Exam_Module.md create mode 100644 docs/04_Backend/BE03_Media_Module.md create mode 100644 docs/04_Backend/BE04_AI_Chat_Module.md create mode 100644 docs/04_Backend/BE05_Knowledge_Ingest_Module.md create mode 100644 docs/04_Backend/BE06_AI_Config_Credits_Module.md create mode 100644 docs/04_Backend/README.md create mode 100644 docs/06_Product_Lines/PL01_Global_Layout.md create mode 100644 docs/06_Product_Lines/PL02_Employee_Views.md create mode 100644 docs/06_Product_Lines/PL03_Admin_Views.md create mode 100644 docs/06_Product_Lines/README.md create mode 100644 docs/08_Design_Rules/DR01_Theme_System.md create mode 100644 docs/08_Design_Rules/DR02_Navigation_Rules.md create mode 100644 docs/08_Design_Rules/DR03_Interaction_Rules.md create mode 100644 docs/08_Design_Rules/README.md create mode 100644 docs/09_Research/Workflow_Canvas_Interaction_Research.md create mode 100644 docs/09_Research/工业AI观察员/README.md create mode 100644 docs/09_Research/工业AI观察员/assets/img1.jpg create mode 100644 docs/09_Research/工业AI观察员/assets/img2.jpg create mode 100644 docs/09_Research/工业AI观察员/assets/img3.jpg create mode 100644 docs/09_Research/工业AI观察员/assets/img4.jpg create mode 100644 docs/09_Research/工业AI观察员/assets/img5.jpg create mode 100644 docs/09_Research/工业AI观察员/钨合金烧结全流程数字化改造：一个硬核项目怎么帮客户省下真金白银.md create mode 100644 docs/10-eaiintro/cb09274421816d69abb794f5b90ed9cc.jpg create mode 100644 docs/10-eaiintro/博昇慧源AI研究院 · 技术能力概览 · V1.0.md create mode 100644 docs/10-eaiintro/博昇慧源AI研究院（EAI）· 完整版介绍.md create mode 100644 docs/10-eaiintro/博昇慧源xBAI·AI落地产品与方案体系 V1.0.md create mode 100644 docs/10-eaiintro/博通产研_算力中心-资本化合作提案_分页幻灯片版_32页.md create mode 100644 docs/PRD.md create mode 100644 docs/api.md create mode 100644 docs/changelog.md create mode 100644 docs/db_schema.md create mode 100644 docs/deploy.md create mode 100644 docs/eaisalestrain_app设计稿.md create mode 100644 docs/博昇产品与渠道合作表.md create mode 100644 docs/完整分析_pj0231_vs_pj006-zhilianyuan2.md create mode 100644 docs/对比分析_pj0231_vs_pj006-zhilianyuan2.md create mode 100644 docs/设计稿_岗位与知识对应能力.md create mode 100644 eai_ap_app/.gitignore create mode 100644 eai_ap_app/CLAUDE.md create mode 100644 eai_ap_app/PROJECT_STATE.md create mode 100644 eai_ap_app/backend-go/cmd/server/main.go create mode 100644 eai_ap_app/backend-go/config/ai_config.json create mode 100644 eai_ap_app/backend-go/config/ai_secrets.example.json create mode 100644 eai_ap_app/backend-go/config/platform.json create mode 100644 eai_ap_app/backend-go/deploy/DELIVERY.md create mode 100644 eai_ap_app/backend-go/deploy/clonezilla-cleanup.sh create mode 100644 eai_ap_app/backend-go/deploy/eaisalestrain.env create mode 100644 eai_ap_app/backend-go/deploy/eaisalestrain.service create mode 100644 eai_ap_app/backend-go/go.mod create mode 100644 eai_ap_app/backend-go/go.sum create mode 100644 eai_ap_app/backend-go/internal/ai/credits.go create mode 100644 eai_ap_app/backend-go/internal/ai/llm.go create mode 100644 eai_ap_app/backend-go/internal/ai/retrieve.go create mode 100644 eai_ap_app/backend-go/internal/ai/retrieve_test.go create mode 100644 eai_ap_app/backend-go/internal/api/ai_admin.go create mode 100644 eai_ap_app/backend-go/internal/api/ai_chat.go create mode 100644 eai_ap_app/backend-go/internal/api/ai_usage.go create mode 100644 eai_ap_app/backend-go/internal/api/auth.go create mode 100644 eai_ap_app/backend-go/internal/api/certificate.go create mode 100644 eai_ap_app/backend-go/internal/api/company_train.go create mode 100644 eai_ap_app/backend-go/internal/api/connectors.go create mode 100644 eai_ap_app/backend-go/internal/api/courses.go create mode 100644 eai_ap_app/backend-go/internal/api/department.go create mode 100644 eai_ap_app/backend-go/internal/api/essay_grade.go create mode 100644 eai_ap_app/backend-go/internal/api/exam.go create mode 100644 eai_ap_app/backend-go/internal/api/exam_test.go create mode 100644 eai_ap_app/backend-go/internal/api/helpers.go create mode 100644 eai_ap_app/backend-go/internal/api/knowledge.go create mode 100644 eai_ap_app/backend-go/internal/api/knowledge_export.go create mode 100644 eai_ap_app/backend-go/internal/api/learning.go create mode 100644 eai_ap_app/backend-go/internal/api/media.go create mode 100644 eai_ap_app/backend-go/internal/api/note.go create mode 100644 eai_ap_app/backend-go/internal/api/notification.go create mode 100644 eai_ap_app/backend-go/internal/api/points.go create mode 100644 eai_ap_app/backend-go/internal/api/position.go create mode 100644 eai_ap_app/backend-go/internal/api/products.go create mode 100644 eai_ap_app/backend-go/internal/api/profile.go create mode 100644 eai_ap_app/backend-go/internal/api/router.go create mode 100644 eai_ap_app/backend-go/internal/api/routes.go create mode 100644 eai_ap_app/backend-go/internal/api/specialist.go create mode 100644 eai_ap_app/backend-go/internal/api/stats.go create mode 100644 eai_ap_app/backend-go/internal/api/system.go create mode 100644 eai_ap_app/backend-go/internal/auth/auth.go create mode 100644 eai_ap_app/backend-go/internal/config/config.go create mode 100644 eai_ap_app/backend-go/internal/config/json_loader.go create mode 100644 eai_ap_app/backend-go/internal/connector/kingdee.go create mode 100644 eai_ap_app/backend-go/internal/connector/kingdee_test.go create mode 100644 eai_ap_app/backend-go/internal/connector/static_catalog.go create mode 100644 eai_ap_app/backend-go/internal/connector/types.go create mode 100644 eai_ap_app/backend-go/internal/middleware/auth.go create mode 100644 eai_ap_app/backend-go/internal/model/ai_call_log.go create mode 100644 eai_ap_app/backend-go/internal/model/certificate.go create mode 100644 eai_ap_app/backend-go/internal/model/course.go create mode 100644 eai_ap_app/backend-go/internal/model/department.go create mode 100644 eai_ap_app/backend-go/internal/model/exam_paper.go create mode 100644 eai_ap_app/backend-go/internal/model/exam_record.go create mode 100644 eai_ap_app/backend-go/internal/model/knowledge_chunk.go create mode 100644 eai_ap_app/backend-go/internal/model/knowledge_source.go create mode 100644 eai_ap_app/backend-go/internal/model/learning_progress.go create mode 100644 eai_ap_app/backend-go/internal/model/media_file.go create mode 100644 eai_ap_app/backend-go/internal/model/mistake_record.go create mode 100644 eai_ap_app/backend-go/internal/model/notification.go create mode 100644 eai_ap_app/backend-go/internal/model/point_event.go create mode 100644 eai_ap_app/backend-go/internal/model/position.go create mode 100644 eai_ap_app/backend-go/internal/model/position_exam_blueprint.go create mode 100644 eai_ap_app/backend-go/internal/model/position_knowledge.go create mode 100644 eai_ap_app/backend-go/internal/model/product.go create mode 100644 eai_ap_app/backend-go/internal/model/question.go create mode 100644 eai_ap_app/backend-go/internal/model/specialist.go create mode 100644 eai_ap_app/backend-go/internal/model/study_note.go create mode 100644 eai_ap_app/backend-go/internal/model/system_config.go create mode 100644 eai_ap_app/backend-go/internal/model/user.go create mode 100644 eai_ap_app/backend-go/internal/store/db.go create mode 100644 eai_ap_app/backend-go/internal/store/seed.go create mode 100644 eai_ap_app/backend-go/internal/store/specialist_records.go create mode 100644 eai_ap_app/backend-go/internal/web/errors.go create mode 100644 eai_ap_app/backend-go/internal/web/response.go create mode 100644 eai_ap_app/backend-go/knowledge_source/01_通用规则.md create mode 100644 eai_ap_app/backend-go/knowledge_source/02_资本咨询类.md create mode 100644 eai_ap_app/backend-go/knowledge_source/03_资质认定辅导类.md create mode 100644 eai_ap_app/backend-go/knowledge_source/04_AI咨询与实施类.md create mode 100644 eai_ap_app/backend-go/knowledge_source/05_企业级AI工具与平台.md create mode 100644 eai_ap_app/backend-go/knowledge_source/06_资质认定政策与实操.md create mode 100644 eai_ap_app/backend-go/knowledge_source/07_资本运作与股权融资.md create mode 100644 eai_ap_app/backend-go/knowledge_source/08_企业AI落地方法论.md create mode 100644 eai_ap_app/backend-go/knowledge_source/09_顾问式销售方法论.md create mode 100644 eai_ap_app/backend-go/knowledge_source/10_管理员审批测试样本.md create mode 100644 eai_ap_app/backend-go/knowledge_source/README.md create mode 100644 eai_ap_app/frontend/index.html create mode 100644 eai_ap_app/frontend/package-lock.json create mode 100644 eai_ap_app/frontend/package.json create mode 100644 eai_ap_app/frontend/public/studio-design-mockup.html create mode 100644 eai_ap_app/frontend/src/App.vue create mode 100644 eai_ap_app/frontend/src/api/ai.js create mode 100644 eai_ap_app/frontend/src/api/auth.js create mode 100644 eai_ap_app/frontend/src/api/certificate.js create mode 100644 eai_ap_app/frontend/src/api/company.js create mode 100644 eai_ap_app/frontend/src/api/connector.js create mode 100644 eai_ap_app/frontend/src/api/courses.js create mode 100644 eai_ap_app/frontend/src/api/department.js create mode 100644 eai_ap_app/frontend/src/api/exam.js create mode 100644 eai_ap_app/frontend/src/api/http.js create mode 100644 eai_ap_app/frontend/src/api/knowledge.js create mode 100644 eai_ap_app/frontend/src/api/learning.js create mode 100644 eai_ap_app/frontend/src/api/media.js create mode 100644 eai_ap_app/frontend/src/api/note.js create mode 100644 eai_ap_app/frontend/src/api/notification.js create mode 100644 eai_ap_app/frontend/src/api/position.js create mode 100644 eai_ap_app/frontend/src/api/products.js create mode 100644 eai_ap_app/frontend/src/api/profile.js create mode 100644 eai_ap_app/frontend/src/api/specialist.js create mode 100644 eai_ap_app/frontend/src/api/system.js create mode 100644 eai_ap_app/frontend/src/components/NotePanel.vue create mode 100644 eai_ap_app/frontend/src/components/VideoPlayer.vue create mode 100644 eai_ap_app/frontend/src/components/charts/BarChart.vue create mode 100644 eai_ap_app/frontend/src/components/charts/DonutChart.vue create mode 100644 eai_ap_app/frontend/src/components/charts/LineChart.vue create mode 100644 eai_ap_app/frontend/src/components/charts/RadarChart.vue create mode 100644 eai_ap_app/frontend/src/config/navigation.js create mode 100644 eai_ap_app/frontend/src/config/workbench.js create mode 100644 eai_ap_app/frontend/src/layout/MainLayout.vue create mode 100644 eai_ap_app/frontend/src/layout/PathCoachPanel.vue create mode 100644 eai_ap_app/frontend/src/layout/SectionTabs.vue create mode 100644 eai_ap_app/frontend/src/layout/SideNav.vue create mode 100644 eai_ap_app/frontend/src/main.js create mode 100644 eai_ap_app/frontend/src/router/guards.js create mode 100644 eai_ap_app/frontend/src/router/index.js create mode 100644 eai_ap_app/frontend/src/store/aiChat.js create mode 100644 eai_ap_app/frontend/src/store/auth.js create mode 100644 eai_ap_app/frontend/src/store/notification.js create mode 100644 eai_ap_app/frontend/src/store/workbench.js create mode 100644 eai_ap_app/frontend/src/styles/global.css create mode 100644 eai_ap_app/frontend/src/utils/labels.js create mode 100644 eai_ap_app/frontend/src/views/Login.vue create mode 100644 eai_ap_app/frontend/src/views/Notification.vue create mode 100644 eai_ap_app/frontend/src/views/companyTrain/CompanyTrain.vue create mode 100644 eai_ap_app/frontend/src/views/exam/ExamFormal.vue create mode 100644 eai_ap_app/frontend/src/views/exam/ExamMyRecord.vue create mode 100644 eai_ap_app/frontend/src/views/exam/ExamSelfTest.vue create mode 100644 eai_ap_app/frontend/src/views/exam/Leaderboard.vue create mode 100644 eai_ap_app/frontend/src/views/exam/MyCertificates.vue create mode 100644 eai_ap_app/frontend/src/views/exam/MyMistakes.vue create mode 100644 eai_ap_app/frontend/src/views/exam/MyPosition.vue create mode 100644 eai_ap_app/frontend/src/views/exam/MyProfile.vue create mode 100644 eai_ap_app/frontend/src/views/home/HomePage.vue create mode 100644 eai_ap_app/frontend/src/views/knowledge/ExamQuestionBank.vue create mode 100644 eai_ap_app/frontend/src/views/knowledge/ExamRecordManage.vue create mode 100644 eai_ap_app/frontend/src/views/knowledge/MaterialAudit.vue create mode 100644 eai_ap_app/frontend/src/views/knowledge/MaterialManage.vue create mode 100644 eai_ap_app/frontend/src/views/product/ProductDetail.vue create mode 100644 eai_ap_app/frontend/src/views/product/ProductList.vue create mode 100644 eai_ap_app/frontend/src/views/salesTrain/CourseDetail.vue create mode 100644 eai_ap_app/frontend/src/views/salesTrain/CourseList.vue create mode 100644 eai_ap_app/frontend/src/views/system/AiUsage.vue create mode 100644 eai_ap_app/frontend/src/views/system/CompanyConfigPage.vue create mode 100644 eai_ap_app/frontend/src/views/system/DepartmentManage.vue create mode 100644 eai_ap_app/frontend/src/views/system/PositionManage.vue create mode 100644 eai_ap_app/frontend/src/views/system/SystemConfigPage.vue create mode 100644 eai_ap_app/frontend/src/views/system/UserManage.vue create mode 100644 eai_ap_app/frontend/src/views/workbench/BusinessAppPage.vue create mode 100644 eai_ap_app/frontend/src/views/workbench/ConsolePage.vue create mode 100644 eai_ap_app/frontend/src/views/workbench/KnowledgeHub.vue create mode 100644 eai_ap_app/frontend/src/views/workbench/MarketPage.vue create mode 100644 eai_ap_app/frontend/src/views/workbench/StudioPage.vue create mode 100644 eai_ap_app/frontend/vite.config.js create mode 100644 start_dev_10231_10232.sh diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e9aaa04 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +*.mp4 filter=lfs diff=lfs merge=lfs -text +*.pdf filter=lfs diff=lfs merge=lfs -text +*.docx filter=lfs diff=lfs merge=lfs -text +*.pptx filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text +*.jpeg filter=lfs diff=lfs merge=lfs -text +*.png filter=lfs diff=lfs merge=lfs -text +*.gif filter=lfs diff=lfs merge=lfs -text +*.img filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2e5041f --- /dev/null +++ b/.gitignore @@ -0,0 +1,35 @@ +# ===== 运行数据 ===== +data/ +debuglog/ +*.db + +# ===== IDE ===== +.idea/ +.vscode/ +*.swp +*.swo +.claude/ +.dbg/ + +# ===== Node ===== +node_modules/ + +# ===== 构建产物 ===== +dist/ +bin/ +*.exe + +# ===== 大文件/素材（不入 Git） ===== +eai_ap_app/training_materials/ +docs/10-eaiintro/*.pptx +docs/10-eaiintro/*.pdf +docs/09_Research/wechat/ +docs/09_Research/工业AI观察员/raw/ + +# ===== 环境变量 ===== +.env +.env.local + +# ===== 操作系统 ===== +.DS_Store +Thumbs.db \ No newline at end of file diff --git a/CODING_RULES.md b/CODING_RULES.md new file mode 100644 index 0000000..8d66df6 --- /dev/null +++ b/CODING_RULES.md @@ -0,0 +1,243 @@ +# eaisalestrain_app 博昇内部培训平台 — 编码与调试最高准则 + +> **版本：V1.0** +> **日期：2026-08-15** +> **状态：必须强制执行 (Highest Priority)** +> **适用范围：博昇内部培训平台前端、后端、数据库、考试引擎、AI PathCoach、素材上传与审批** +> **AI 助手启动任何任务前必须先读取并确认本文件。** + +--- + +> **整理说明**：参考 pj034-oeamgt TOP_CODING_RULES.md 结构体系重组。 +> **分组方式**：第一部分是 EAIHub 博昇 AI 中心通用规则；第二部分是本项目专用规则。 +> **编号方式**：第一部分 G01-G08；第二部分 P01-P05。 + +--- + +# 第一部分：通用开发规则 + +> **适用范围**：适用于 eaisalestrain_app 及 EAIHub 下其他涉及 FastAPI/Vue3/AI 的项目。 +> **使用方式**：新任务开始前应先通读本部分；项目专用规则(P)在遵守本部分基础上叠加。 + +## 索引 + +- G01：深度调试日志 — 全链路埋点 + 特殊日志文件 +- G02：Fail Fast 与零静默兜底 +- G03：变量命名锚定 — 防命名漂移 +- G04：测试与验收 — 完成判定必须靠事实 +- G05：安全迁移与重构流程 +- G06：AI 助手行为规范 +- G07：交互控件可用态颜色统一 +- G08：分层清晰，禁止前后端职责串线 + +--- + +## G01 最高原则：深度调试日志 (Special Log & Console Print) + +**任何**涉及功能异常、逻辑排错、API 失败或模板渲染问题的任务，必须遵循以下调试流程： + +1. **强制全链路埋点**：禁止盲目猜测，必须在后端路由、中间件、服务层以及前端 JS 关键回调中，大量写入过程性输出。 +2. **统一特殊日志文件**： + - 路径：`backend/logs/special_trace_YYYY-MM-DD.log`（按天生成） + - 内容：必须包含 `[时间戳] [模块名] [详细描述]` + - 必须包含：请求参数、Session 状态、关键业务变量 + - **脱敏红线**：落盘前必须脱敏/删除敏感信息（Authorization/Cookie/JWT/密码/API Key 等） +3. **同步控制台输出**：所有写入调试日志的内容必须同步 `print` 到 Console，以便开发者实时观察。 +4. **排查先读日志**：在提出任何修复方案前，必须先调用读取工具检查该日志。 + +### 关键埋点清单 + +| 埋点位置 | 必须记录内容 | +|---|---| +| API 调用 | 请求参数、响应状态、异常栈 | +| 数据库交互 | 查询关键参数、结果集摘要 | +| 文件操作 | 上传/转换/提取的文件路径、大小、状态 | +| AI LLM 调用 | 发送给 AI 的完整 Payload + 返回原始正文；落盘前脱敏密钥/令牌 | + +--- + +## G02 最高原则：Fail Fast 与零静默兜底 (Fail Fast & Zero-Fallback) + +1. **禁止隐式回退**：所有涉及配置、运行时资产的读取，**严禁使用硬编码的默认值进行静默兜底**。 +2. **配置/字段缺失即报错**：如果代码依赖某项配置或 JSON 字段且其缺失，必须立即抛出异常并终止流程。 +3. **禁止入口层吞错**：路由入口不得 `try/except` 后静默放行；凡关键身份、权限、业务校验失败，必须返回明确错误（4xx/5xx）并阻断流程。 +4. **禁止"先跑通再修正"策略**：不得为"先可用"加入 hardcode 默认值、临时跳过校验等行为。这类行为视为质量事故。 +5. **错误可见性强制**：任何违反业务规则或数据约束的问题，必须对开发者显式可见（日志 + 返回错误 + 可复现路径），禁止隐藏真实错误来源。 +6. **图片不做 OCR**：严格按照 PRD V1.1 规定，图片（png/jpg/jpeg）不做 OCR、不进 AI 文本库。 + +### 反例与正例 + +| | 反例 ❌ | 正例 ✅ | +|---|---|---| +| A | 文件审批状态未知时默认视为"已通过" | 状态非 `approved` 则拦截并返回明确错误 | +| B | LLM 配置缺失时使用硬编码的默认地址 | 配置缺失立即报错，引导管理员在系统参数补充 | +| C | 考试 session 不存在时返回空结果 | Session 不存在返回 404 + 明确错误信息 | + +--- + +## G03 原则：变量命名锚定 — 防命名漂移 (Identity Anchoring) + +1. **变量名前缀强制化**：所有业务相关变量必须带明确前缀（如 `media_file_id`, `exam_session_key`, `product_code`）。禁止使用 `id`, `data`, `res` 等模糊命名。 +2. **变量名全链路同步**：同一业务参数在 API、Service、Model 层必须保持变量名完全一致。 +3. **最小长度约束**：变量名原则上不短于 5 个字符（循环索引除外）。 +4. **AI 引用已定义标识符必须按字符复制**：AI 在生成或修改代码时，引用任何**已在项目中定义过**的标识符，必须先 Read/Grep 找到定义处，**按字符原样复制**，禁止自行改写大小写或分隔符。例如 `user_id` 不应被写成 `userId` 或 `uid`。 + +--- + +## G04 最高原则：测试与验收 — 「我说完成」必须靠观察的事实 + +1. **完成判定必须看 exit code，禁止仅看屏幕末尾文字**：命令后立刻 `echo $?` 或 `if [ $? -ne 0 ]`；链式命令必须确认每一段都退出 0。 +2. **修改既存文件前必须 Read 整文件**，禁止凭印象 Edit。 +3. **新依赖必须同步进 `requirements.txt` / `package.json`**：任何新 import 出现必检查此包是否在依赖清单中。 +4. **测试/build 失败时禁止"再试一次"侥幸**：失败原因必须先找出来。 +5. **声明完成前的最小验证清单**： + - [ ] 后端：`python -c "from app.main import app"` 无 import error + - [ ] 前端：`npx vite build` exit 0 + - [ ] API smoke：`/api/health` 返回 200，管理员 login 返回 200 + - [ ] 任何新 import 在依赖清单中 + +--- + +## G05 原则：安全迁移与重构流程 (Secure Migration) + +1. **非简化原则**：重构不得以简化逻辑为目的，必须保留所有原始业务深度。 +2. **实质性内容保护**：除非内容明确放错位置、存在重复副本或已经完成等价迁移验证，否则不得删除原有实质性内容与技术细节。 +3. **全量备份**：大规模操作前，将原始文件完整备份。 +4. **文件安全强制**： + - 文件扩展名白名单校验（仅允许 ppt/pptx/pdf/doc/docx/mp4/png/jpg/jpeg） + - 文件名重命名为存储 UUID，杜绝路径穿越 + - 上传目录对静态预览只读，禁止直接执行 + +--- + +## G06 原则：AI 助手行为规范 + +1. **任务启动预读**：AI 助手在接收到新任务后的第一步操作中，必须读取本项目根目录下的 `CODING_RULES.md` 与 `eaisalestrain_app/CLAUDE.md`。 +2. **持续追踪**：直到问题完全解决并经由日志或接口验证通过前，不得结束任务。 +3. **新对话启动仪式**：新对话必须先读 `eaisalestrain_app/PROJECT_STATE.md` → `CODING_RULES.md`，再开始干活。 +4. **发现规则与实现冲突时**，优先提醒并修正，不得静默忽略。 + +--- + +## G07 原则：交互控件可用态颜色统一规范 + +1. **按钮可用态统一蓝底**：所有可点击的关键交互按钮必须使用蓝色底（推荐 `#1677ff`）。 +2. **按钮不可用态统一灰底**：所有不可点击按钮必须使用灰色底（推荐 `#cbd5e1`）与灰色文字（推荐 `#64748b`），并保持 `cursor: not-allowed`。 +3. **状态变化必须实时联动视觉**：按钮的 `disabled` 状态变化后，底色必须立即同步变化。 +4. **Element Plus 严格类型约束**：`el-tag` / `el-button` 的 type prop 禁止传入 `""` 或 `null`；无条件匹配时应传 `undefined`。 + +--- + +## G08 原则：分层清晰，禁止前后端职责串线 + +1. **前端只负责**：页面渲染、用户交互、表单收集、数据展示 +2. **后端必须负责**：登录认证、权限校验、文件操作、AI 接口调用、业务判分逻辑、数据库操作 +3. **前端不可以直接持有 JWT Secret 或 AI API Key** — 敏感凭据只在后端 +4. **前端可以做格式和必填校验，但后端必须再次做强校验** +5. **所有权限以后端鉴权为准**：前端路由守卫仅作 UX 隐藏，不作为安全边界 + +--- + +# 第二部分：eaisalestrain_app 项目专用规则 + +> **适用范围**：仅适用于博昇内部培训平台项目。 +> **使用方式**：本部分在通用规则之上叠加。若两者看似冲突，应先检查是否为项目专用规则对通用规则的场景化收敛。 + +## 索引 + +- P01：培训平台定位 — 知识库 + 考试 + 素材审批 +- P02：知识库安全与检索边界 +- P03：考试判分与记录规则 +- P04：素材上传与审批流程 +- P05：AI PathCoach 对话安全边界 + +--- + +## P01 最高原则：培训平台定位 — 知识库 + 考试 + 素材审批 + +1. 博昇内部培训平台是**公司培训知识库 + 考试引擎 + 素材审批**系统，不是在线课程平台，不是 AI 对话机器人平台。 +2. **四个核心业务模块**不可偏移： + - **公司介绍**：博昇介绍 + 资质荣誉 + 发展历程（静态内容） + - **产品知识**：四大产品线（资本咨询/资质辅导/AI咨询/AI工具）的知识体系 + - **销售培训**：对应四大产品的销售课程（话术/流程/异议处理/避坑） + - **考试中心**：自测练习 + 正式考试 + 成绩记录 +3. **知识库是后台能力**：素材审批 → 文本提取 → 知识切片 → AI PathCoach 检索，不独立为前台页面。 +4. **AI PathCoach 是辅助工具**：嵌入全局右侧栏，提供产品知识问答 + 情景演练 + 佣金查询 + 产品对比，不是产品中心。 +5. 开始写某个模块前，先明确对应文档： + - `docs/04_Backend/BE*.md`（后端详细设计） + - `docs/06_Product_Lines/PL*.md`（产品原型） + - `docs/08_Design_Rules/DR*.md`（设计规则） + +### 关联 + +- 关联 G08：前端不持有业务逻辑，AI PathCoach 调用必须走后端 API +- 关联 G02：配置/素材缺失必须报错，不静默兜底 + +--- + +## P02 最高原则：知识库安全与检索边界 + +1. **只存元数据，不存文件二进制**：数据库仅存储文件路径、大小、类型等元数据。 +2. **素材文本存 knowledge_chunk 表**：审批通过的文档类素材经异步转换提取文本，切片写入。 +3. **FULLTEXT 全文检索**：AI PathCoach 知识检索基于 MySQL FULLTEXT 索引，不做向量检索（不上 Milvus/Elasticsearch）。 +4. **图片不进知识库**：png/jpg/jpeg 仅做存储预览，不做 OCR 提取，不进 AI 文本检索。 +5. **审批前置**：素材只有 `approved` 状态才会触发异步转换；`pending` / `rejected` 的素材不进知识库。 +6. **视频仅存储**：mp4 文件上传后仅做存储和预览，不做视频分析、不做帧提取。 + +### 关联 + +- 关联 G02：状态非 `approved` 的前端预览请求必须拦截 +- 关联 G05：文件安全校验（扩展名 + UUID存储 + 只读预览） +- 关联 P04：审批是转换的前置条件 + +--- + +## P03 原则：考试判分与记录规则 + +1. **确定性判分**：判分逻辑采用确定性规则（单选/多选/判断），不涉及 AI 评分。 +2. **判分逻辑必须在后端**：前端仅做选项展示和提交，不得在前端判分。 +3. **自测 vs 正式考**： + - **自测(self_test)**：提交后立即显示正确答案 + 解析，不持久化成绩 + - **正式考(formal)**：提交后判分落 `exam_record` 表，不显示正确答案 +4. **考试 session 内存存储**：`_exam_sessions: dict[str, dict]` — 启动考试时抽题存入内存，不落数据库。 +5. **正式考不可重做**：同一用户对同一正式考卷仅可提交一次（后端校验）。 + +--- + +## P04 原则：素材上传与审批流程 + +1. **管理员上传自动通过**：管理员（`role=admin`）上传的素材直接 `approved` + 立即触发异步转换。 +2. **员工上传需审批**：员工上传后状态为 `pending`，管理员审批通过后才转 `approved`。 +3. **驳回必须填写理由**：管理员驳回素材时，`reject_reason` 字段必填。 +4. **异步转换管线**：审批通过 → 后台线程执行 `LibreOffice(ppt/docx→pdf) → PyMuPDF(提取文本) → 切片 → 写入 knowledge_chunk`。 +5. **前端轮询状态**：前端通过 `GET /api/media/{id}/status` 轮询素材/转换状态，不使用 WebSocket。 +6. **分片上传**：> 100MB 的视频文件走分片上传（init → chunk → complete）。 + +### 关联 + +- 关联 G02：状态/配置缺失必须报错 +- 关联 G05：文件安全校验 +- 关联 P02：审批是知识库转换的前置条件 + +--- + +## P05 原则：AI PathCoach 对话安全边界 + +1. **SSE 流式响应**：AI PathCoach 对话采用 SSE (Server-Sent Events)，末包采集 token usage。 +2. **上下文注入规则**：AI 回答基于知识库检索结果 + 当前页面上下文，禁止注入管理员凭据/内部配置。 +3. **快捷动作限范围**： + - `scenario`（情景演练）— 使用预设 prompt 模拟客户对话 + - `commission`（查佣金）— 检索产品佣金数据 + - `compare`（产品对比）— 对比两个产品参数 +4. **LLM 配置链**：system_config 表 → .env 文件两层优先级，缺失任何一项（base_url/api_key/model）抛 `501 LLMNotConfiguredError`。 +5. **禁止功能**：AI PathCoach 不做图片生成、不做代码生成、不做外部 API 调用。 + +### 关联 + +- 关联 G02：配置缺失 Fail Fast（501），不静默兜底 +- 关联 G01：AI LLM 调用完整 Payload + 返回正文必须埋点日志 +- 关联 G08：AI 调用全程在后端，前端仅展示流式输出 + +--- + +*注：本准则放置于项目根目录，作为全局 Rule 永久锁定。* \ No newline at end of file diff --git a/debug-admin-auth-misjudge.md b/debug-admin-auth-misjudge.md new file mode 100644 index 0000000..0dc4b0a --- /dev/null +++ b/debug-admin-auth-misjudge.md @@ -0,0 +1,21 @@ +# [OPEN] admin-auth-misjudge + +## 症状 +- 用户当前使用系统管理员账号，但界面中出现“需要管理员权限”提示。 +- 预期行为：管理员访问管理员页面与管理员接口时，不应被后端返回 403。 + +## 当前范围 +- 前端：登录态恢复、路由守卫、请求拦截器、管理员页面初始化请求。 +- 后端：JWT 解析、中间件注入 `current_user`、管理员鉴权中间件。 + +## 待证伪假设 +1. 前端页面初始化时，某个管理员接口在 `fetchMe()` 完成前提前发出，导致用旧 token 或空用户态触发 403。 +2. 浏览器中实际持有的 token 与当前展示的管理员身份不一致，存在多标签页/旧 token 残留。 +3. 后端 `Auth` 中间件能识别登录用户，但 `RequireAdmin` 前拿到的 `current_user` 为空或角色不是 `admin`。 +4. 某个被认为是“管理员页面”的请求实际命中了错误接口或未走标准鉴权链，导致误报 403。 + +## 调试计划 +- 给前端请求链与后端鉴权链加入最小化埋点。 +- 重现一次管理员访问触发“需要管理员权限”的场景。 +- 对照日志确认是 token、`/me`、路由守卫还是后端鉴权分叉。 +- 基于证据做最小修复，再做前后对比验证。 diff --git a/docs/00_AI_Context/README.md b/docs/00_AI_Context/README.md new file mode 100644 index 0000000..63c6bbd --- /dev/null +++ b/docs/00_AI_Context/README.md @@ -0,0 +1,16 @@ +# 00_AI_Context — AI 协作上下文 + +> **命名规则：** `forai{NN}_{描述}.md` +> **用途：** 记录 AI 助手的工程进度、上下文、调试库等 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `forai01_engineering_progress.md` | 工程进度摘要 | +| `forai02_2026-08-16_导航品牌与系统配置调整交接.md` | 本轮前端导航、品牌与系统配置拆分交接 | + +## 使用规范 + +- `foraiNN_*.md` — 按需创建的特定上下文 / 决策记录 diff --git a/docs/00_AI_Context/forai01_engineering_progress.md b/docs/00_AI_Context/forai01_engineering_progress.md new file mode 100644 index 0000000..b313f5c --- /dev/null +++ b/docs/00_AI_Context/forai01_engineering_progress.md @@ -0,0 +1,35 @@ +# forai01 — 工程进度摘要 + +> **版本：V1.2 | 最后更新：2026-08-16** + +--- + +## 整体进度 + +| 阶段 | 状态 | 说明 | +|------|------|------| +| **V1 培训平台（学习/考试/AI 答疑）** | ✅ 已交付 | 见 `docs/changelog.md` V1.0–V1.7 | +| **后端重写 Go + Gin + GORM** | ✅ 完成 | V1.2，替换原 FastAPI/Python | +| **数据库 MySQL 8.0 + FAISS** | ✅ 进行中 | 关系数据 MySQL + 语义检索 FAISS | +| **V1.4–V1.7 能力扩展** | ✅ 已落地 | 岗位映射 / 错题本 / 积分证书 / 部门消息 | +| **数字员工平台战略** | 📋 规划中 | 见 SY03–SY17，对外「专员」为能力单元 | + +## 当前主线 + +1. **已完成**：V1 培训平台闭环（资料入库 → AI 答疑 → 考试验收），Go 后端，MySQL + FAISS 检索。 +2. **进行中**：从「内部培训系统」升级为「数字员工平台」——知识底座统一主实体化、专员矩阵（通用数字员工 + 行业专属数字员工）、客户半定制专员工坊。 +3. **目标态**：以 `01_System_Overall/SY03` 为战略主轴，SY04–SY17 为配套设计。 + +## 详细历史 + +- 具体版本变更（V1.0–V1.7）以 `docs/changelog.md` 为准。 +- 文档定位与技术栈冲突已在本轮（2026-08-16）对齐，见 `docs/PRD.md`、`SY01`、`SY02`、`db_schema.md`、`deploy.md`。 + +## 下一个关键决策 + +- 按 SY03「推荐的最小落地路线」落地 MVP 第一阶段：4 个标准智能体（知识顾问 / 陪练教官 / 合规审查官 / 认证考官）+ 1 个场景陪练模板。 +- 一级导航逐步演进为：知识库 / 智能体 / 学习与考试 / 陪练与认证 / 内容运营 / 组织与系统。 + +## 当前问题 + +- 无阻塞项。文档层已消除定位与技术栈的较大冲突。 diff --git a/docs/00_AI_Context/forai02_2026-08-16_导航品牌与系统配置调整交接.md b/docs/00_AI_Context/forai02_2026-08-16_导航品牌与系统配置调整交接.md new file mode 100644 index 0000000..fab2815 --- /dev/null +++ b/docs/00_AI_Context/forai02_2026-08-16_导航品牌与系统配置调整交接.md @@ -0,0 +1,102 @@ +# forai02 — 导航品牌与系统配置调整交接 + +> **日期：2026-08-16** +> **对话名：导航品牌与系统配置调整交接** + +--- + +## 本次工作范围 + +本轮主要处理前端界面中的品牌展示、左侧导航结构、顶部页签未读角标，以及管理员端系统配置入口拆分。整体遵循“最小改动”原则，未改后端接口和业务逻辑。 + +## 已完成事项 + +### 1. 品牌展示调整 + +- 侧边栏品牌区已改为三行： + - `博昇AI研究院` + - `内部培训平台` + - `EAI-Training` +- 登录页品牌展示已同步为三行 +- 首页欢迎文案和证书标题中的品牌文案已同步更新 +- 侧边栏品牌区图标和文字整体偏移已调整为左移 `6px` + +### 2. 未读消息角标位置调整 + +- 未读消息数字不再挂在左侧 `1 工作台` +- 未读角标已改为显示在顶部二级页签 `1.2 消息通知` +- 这样可以避免用户把未读数误解为工作台本身的数字 + +### 3. 一级导航结构调整 + +- 原 `6 组织与系统` 已拆分为两个一级菜单： + - `6 组织管理` + - `7 系统设置` +- 当前导航结构如下： + - `6 组织管理` + - `6.1 岗位管理` + - `6.2 部门管理` + - `6.3 用户管理` + - `6.4 公司信息配置` + - `7 系统设置` + - `7.1 AI 用量` + - `7.2 参数配置` + +### 4. 系统配置页面拆分 + +- 原 `7.2.1 公司信息配置` 已从 `7.2 参数配置` 中迁出 +- 已新增独立页面 `6.4 公司信息配置` +- 原 `7.2 参数配置` 内部页签已顺延为： + - `7.2.1 文件与存储` + - `7.2.2 其他信息配置` + - `7.2.3 AI 配置` + +## 关键文件 + +### 品牌与布局 + +- `eaisalestrain_app/frontend/src/layout/SideNav.vue` +- `eaisalestrain_app/frontend/src/layout/SectionTabs.vue` +- `eaisalestrain_app/frontend/src/views/Login.vue` +- `eaisalestrain_app/frontend/src/views/home/HomePage.vue` +- `eaisalestrain_app/frontend/src/views/exam/MyCertificates.vue` + +### 导航与路由 + +- `eaisalestrain_app/frontend/src/config/navigation.js` +- `eaisalestrain_app/frontend/src/router/index.js` + +### 系统配置页面 + +- `eaisalestrain_app/frontend/src/views/system/CompanyConfigPage.vue` +- `eaisalestrain_app/frontend/src/views/system/SystemConfigPage.vue` +- `eaisalestrain_app/frontend/src/views/system/AiUsage.vue` + +## 当前状态 + +- 上述改动均已完成前端诊断检查 +- 当前未发现新增诊断错误 +- `CompanyConfigPage.vue` 复用了原有系统配置接口： + - `getConfig` + - `updateConfig` +- 当前没有改动后端路由、接口协议和数据库结构 + +## 建议下一步 + +- 将 `AI 用量` 页面标题补齐为 `7.1 AI 用量`，与 `7.2 参数配置` 的编号风格统一 +- 做一次浏览器人工验收，重点检查： + - 品牌区三行文案与偏移量 + - `消息通知` 页签角标显示 + - `6 组织管理 / 7 系统设置` 的一级切换 + - `6.4 公司信息配置` 的保存功能 + - `7.2 参数配置` 页签顺序是否符合预期 + +## 新对话接手提示 + +如果需要在新对话里继续，可以直接说明： + +1. 前端品牌区已调整为三行品牌展示，侧边栏整体左移 `6px` +2. 消息未读角标已从左侧 `1 工作台` 挪到顶部 `1.2 消息通知` +3. 管理员导航已拆成 `6 组织管理` 和 `7 系统设置` +4. `7.2.1 公司信息配置` 已迁移为独立页面 `6.4 公司信息配置` +5. 请基于当前状态继续，不要回退已有改动 diff --git a/docs/01_System_Overall/README.md b/docs/01_System_Overall/README.md new file mode 100644 index 0000000..6b9a1c3 --- /dev/null +++ b/docs/01_System_Overall/README.md @@ -0,0 +1,44 @@ +# 01_System_Overall — 系统总览 + +> **命名规则：** `SY{NN}_{描述}.md` +> **用途：** 系统概述、架构愿景、设计原则 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `SY01_System_Overview.md` | 系统概述（当前产品闭环与范围） | +| `SY02_Design_Principles.md` | 核心设计原则（极简 / 本地化 / 审批前置） | +| `SY03_Knowledge_Centric_Agent_Platform_Strategy.md` | 知识库中心化、业务层扩展与智能体平台战略 | +| `SY04_Plugin_Workflow_Ontology_Delivery_Platform.md` | 数字员工平台（共享对象层 + 任务系统 + 专员市场 / 工坊 / 工作台） | +| `SY05_Connector_Network_Enterprise_Integration_Architecture.md` | 六层架构 + 连接器网络（企业原有业务系统融合总图） | +| `SY06_AI_Upgrade_Starting_Point_Decision_Framework.md` | AI 升级起步判断框架（知识库先行 / 工作流先行 / 连接器先行） | +| `SY07_Industry_Agent_Pack_Landscape_Overview.md` | 六个行业反推平台需求总览（连接器需求 + 应用方向需求） | +| `SY08_Legal_Industry_Agent_Pack.md` | 法律行业需求样本（Matter / Contract 驱动） | +| `SY09_Healthcare_Industry_Agent_Pack.md` | 医疗行业需求样本（Patient / Encounter 驱动） | +| `SY10_Industrial_Industry_Agent_Pack.md` | 工业行业需求样本（Asset / Order / Alarm 驱动） | +| `SY11_Financial_Industry_Agent_Pack.md` | 金融行业需求样本（Customer / Transaction / Alert 驱动） | +| `SY12_Logistics_Freight_Forwarding_Industry_Agent_Pack.md` | 物流货代行业需求样本（Shipment / Booking / Milestone 驱动） | +| `SY13_Social_Commerce_Microbusiness_Industry_Agent_Pack.md` | 微商行业需求样本（Lead / Conversation / Campaign 驱动） | +| `SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md` | 从六个行业反推连接器与应用方向矩阵 | +| `SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md` | 本体层 / 语义层 / 对象层命名基准研究（含星邺汇捷 / Palantir / Microsoft / Salesforce 对照） | +| `SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md` | 本体如何让数据、动作、工作流一般化 | +| `SY17_Workbench_UI_Wireframes.md` | 数字员工平台 UI 线框图（知识库固定 + 专员动态生长） | +| `SY18_DWP_DW_ADW_Formal_Design_Contract.md` | DWP / DW / ADW 正式设计合同（供人和 AI 共用的对象基准） | + +## 当前主线关系 + +1. `SY01`：定义当前系统范围与业务闭环 +2. `SY02`：定义强约束设计原则 +3. `SY03`：把平台主轴从培训系统扩展到知识库中心化智能体平台 +4. `SY04`：继续升级为数字员工平台 +5. `SY05`：补齐连接器网络，明确如何与企业原有业务系统融合 +6. `SY06`：给出 AI 升级的起步判断框架 +7. `SY07`：把六个行业重新定位为平台需求样本，而不是当前阶段的行业交付目标 +8. `SY08` - `SY13`：分别沉淀六个行业的需求样本，帮助反推连接器与应用方向 +9. `SY14`：把六个行业汇总成连接器与应用方向矩阵，直接服务六层架构设计 +10. `SY15`：澄清本体层、语义层、对象层的理论边界与厂商实践，服务六层架构术语统一 +11. `SY16`：解释本体为何要把数据、动作、工作流提升为统一业务表达，服务六层架构理解与对象建模 +12. `SY17`：把六层架构落成数字员工平台工作台线框，明确平台不再是单一导航后台 +13. `SY18`：正式定义 DWP / DW / ADW 的结构合同、字段规范和 AI 生成规则 diff --git a/docs/01_System_Overall/SY01_System_Overview.md b/docs/01_System_Overall/SY01_System_Overview.md new file mode 100644 index 0000000..a6481c8 --- /dev/null +++ b/docs/01_System_Overall/SY01_System_Overview.md @@ -0,0 +1,81 @@ +# SY01 — 系统概述 + +> **版本：V1.2 | 最后更新：2026-08-16** + +--- + +## 0. 文档状态与定位演进 + +本项目已从「内部培训系统」升级为**以知识库底座为核心、以智能体为能力单元、支持客户半定制的销售训练与认证平台**（知识库中心化智能体平台）。当前产品主轴、分层架构与目标态见 [SY03](SY03_Knowledge_Centric_Agent_Platform_Strategy.md) 及 SY04–SY17；本文档第 1–6 节描述的是已交付的 V1 培训底座（学习/考试/AI 答疑闭环），是平台的起始形态，不再是终点形态。 + +--- + +## 1. 项目定位 + +**eaisalestrain_app**（博昇内部培训平台）是一个纯内网本地化部署的内部专属员工培训系统，并以此为基础演进为知识库中心化的智能体平台。 + +**核心价值（V1 已交付）：** +- 新人快速了解公司文化和业务 +- 员工系统化学习产品知识和佣金规则 +- 销售团队通过话术培训提升能力 +- 统一考试验收学习成果 +- 全局 AI 助教 PathCoach 提供实时答疑和情景演练 + +**演进方向（见 SY03–SY17）：** 知识底座统一主实体化、智能体矩阵（知识顾问/产品顾问/陪练教官/合规审查官/认证考官/出题组卷官/复盘教练/内容工坊助手）、客户半定制智能体工坊、销售赋能/陪练认证/合规经营/内容生产等业务层扩展。 + +## 2. 系统边界 + +### 包含 +- 公司介绍培训（认知层） +- 产品知识手册（四大分类，含佣金/规则） +- 产品销售培训（四大课程，含话术/流程） +- 题库 + 组卷 + 自测/正式考试 +- 素材上传 + 审批流 + 文档转换管线 +- AI PathCoach 全局聊天框 +- 管理员后台（用户/素材/考试/系统配置） + +### 不包含 / 已放开（V1.1 约束，随平台升级调整） +- ~~学习进度仪表盘、学情分析、能力档案~~ → V1.6 起已实现（积分/排行榜/证书/学习档案/能力雷达） +- ~~向量检索（不引入 embedding 依赖）~~ → 已采用 MySQL + FAISS 混合检索 +- 复杂权限、多级角色、多租户洋葱模型 → 仍保持单租户极简，暂不引入 +- 视频转码、语音转写（ASR）→ 仍不引入 +- 外网依赖、云存储（MinIO/OSS）→ 仍保持本地化 +- 强制学习任务、课程解锁限制 → 仍不引入 + +## 3. 用户角色 + +| 角色 | 可见模块 | 权限 | +|------|---------|------| +| **employee**（员工） | 首页、公司介绍、产品知识、销售培训、考试 | 浏览 + 自测 + 正式考试 + 提交素材建议 | +| **admin**（管理员） | 员工全部 + 知识管理 + 系统管理 + 内容管理 | 员工权限 + 素材审批 + 用户管理 + 考试配置 + 系统参数 | + +## 4. 核心业务流程 + +``` +学公司认知 → 查产品手册（价格/佣金/规则）→ 学销售谈单能力 +→ 看课件视频辅助学习 → AI 模拟演练答疑 → 正式考试存档验收 +→ 管理员统一审核素材、维护产品/课程/题库、管理账号、查看全员成绩 +``` + +## 5. 系统运行闭环 + +``` +┌─────────────┐ ┌─────────────┐ ┌──────────────┐ +│ 员工学习 │ → │ AI 辅助答疑 │ → │ 考试验收 │ +│ (公司/产品/ │ │ (PathCoach) │ │ (自测/正式) │ +│ 销售培训) │ │ │ │ │ +└─────────────┘ └─────────────┘ └──────┬───────┘ + │ + ▼ + ┌─────────────────────────┐ + │ 管理员运营 │ + │ (素材审批/用户/配置/成绩)│ + └─────────────────────────┘ +``` + +## 6. 全局统一布局 + +全站固定三栏结构： +1. **顶部导航菜单** — 根据角色动态显示可用菜单 +2. **中间主内容区** — 各业务模块页面 +3. **右侧 AI PathCoach 聊天框** — 可收起/展开，全局常驻 \ No newline at end of file diff --git a/docs/01_System_Overall/SY02_Design_Principles.md b/docs/01_System_Overall/SY02_Design_Principles.md new file mode 100644 index 0000000..a026c74 --- /dev/null +++ b/docs/01_System_Overall/SY02_Design_Principles.md @@ -0,0 +1,64 @@ +# SY02 — 核心设计原则 + +> **版本：V1.2 | 状态：强制 | 最后更新：2026-08-16** +> +> **文档状态：V1 基线，已升级。** 本项目已于 2026-08 升级为「知识库中心化智能体平台」，产品主轴与目标态见 [SY03](SY03_Knowledge_Centric_Agent_Platform_Strategy.md) 及 SY04–SY17。本文档为 V1 培训平台基线的设计原则，其中「不做向量检索 / 无学情分析 / 无能力档案」等约束已随 V1.6 起逐步放开，当前实现以 `docs/changelog.md` 与 `docs/db_schema.md` 为准。 + +--- + +## 原则 1：100% 本地化部署 + +- 不上云、无 OSS、无 MinIO、不依赖任何公网云服务 +- AI 所用 LLM 必须为内网可达地址（Ollama / vLLM / 内网统一 LLM 网关） +- 严禁直连公网 AI API +- 数据库使用 MySQL 8.0 本地实例 + FAISS 向量检索 +- 文件存储使用本地磁盘（backend/data/media → 现为 `data/kb_data`） + +## 原则 2：极致极简（V1 约束，已随平台升级部分放开） + +- 所有功能以"够用"为标准，不做任何冗余 +- **V1.1 曾明确不做、现已放开的：** 学情分析、能力档案、学习进度仪表盘（V1.6 起已实现积分/排行榜/证书/学习档案/能力雷达）；岗位与部门概念（V1.4 / V1.7 已引入）。复杂权限与多级角色仍保持单租户极简，暂不引入多租户洋葱模型 +- 保持前端轻量：Vue3 + Element Plus，不用状态管理库（如 Pinia 按需判断） +- 保持后端简洁：Go + Gin + GORM 单二进制，不加消息队列（异步任务用简单线程池） +- AI 知识检索：MySQL 全文索引（关键词）+ FAISS 向量检索（语义）双路混合召回，见 `docs/db_schema.md` + +## 原则 3：审批前置 + +- 所有素材必须经过审批才能生效 +- 未审批/驳回素材：前台完全不可见、不解析、不进 AI 知识库 +- 审批通过后才执行文档转换管线（PPT/Word → PDF → 文本提取 → 入库） +- 员工提交素材建议走弹窗，管理员直接上传自动通过 + +## 原则 4：视频仅预览 + +- MP4 不做转码（仅支持 H.264 标准格式） +- 不做语音转写（ASR） +- 视频不进 AI 文本知识库 +- 审批通过后仅支持在线原生 video 播放 + +## 原则 5：后端安全第一 + +- JWT 认证 + bcrypt 密码哈希 +- 后端 API 统一鉴权（不是前端路由） +- 管理员接口额外校验 role == admin +- 文件上传严格执行白名单（仅 7 种扩展名） +- 文件名重命名为 UUID，杜绝路径穿越 +- 禁用账号即时失效（token 校验时检查 status） + +## 原则 6：数据库只存元数据 + +- 不存文件二进制 +- 文件存储路径：data/kb_data/approved/（已审批）· pending/（待审批）· rejected/（已驳回） + +## 原则 7：异步非阻塞转换 + +- 审批通过后的文档转换 + 文本提取为后台异步任务 +- 不阻塞请求（后端立即返回，任务后台执行） +- 前端轮询或接口查询转换状态 +- 任务结果写入 media_file.extracted 字段 + 日志 + +## 原则 8：数据对齐业务 + +- 所有产品数据严格对齐《博昇产品与渠道合作表 V1.0》 +- 产品编号、名称、分类、佣金比例、分成规则等字段不可随意修改 +- 支持批量导入（Excel / JSON），导入数据需管理员确认后生效 \ No newline at end of file diff --git a/docs/01_System_Overall/SY03_Knowledge_Centric_Agent_Platform_Strategy.md b/docs/01_System_Overall/SY03_Knowledge_Centric_Agent_Platform_Strategy.md new file mode 100644 index 0000000..bcdd9bd --- /dev/null +++ b/docs/01_System_Overall/SY03_Knowledge_Centric_Agent_Platform_Strategy.md @@ -0,0 +1,728 @@ +# SY03 — 知识库中心化与智能体平台战略 + +> **版本：V1.0 | 最后更新：2026-08-16** + +--- + +## 1. 文档目的 + +本文档用于沉淀项目从“内部培训系统”向“知识库中心化平台”演进的整体分析与战略方案，统一以下几类判断： + +- 为什么当前项目需要从培训系统升级为知识底座平台 +- 知识层、业务层、经营层应如何重新分层 +- 学习/考试之外，还能长出哪些业务层 +- 为什么应该采用“智能体矩阵”而不是单一 AI 助手 +- 哪些智能体应由平台内置，哪些能力应允许客户配置 + +本文档不讨论具体代码改造细节，重点用于产品定位、架构愿景和后续模块规划。 + +## 2. 背景与问题重述 + +### 2.1 当前项目的既有基础 + +当前项目已经具备以下基础能力： + +- 资料上传、审批、知识入库、切片与检索 +- 学习内容浏览、学习进度、笔记沉淀 +- 自测、正式考试、错题本、证书与学习档案 +- 全局 AI 助手入口和基础对话能力 +- 岗位知识映射、AI 点数、AI 调用审计 + +这说明项目并不是从零开始，而是已经拥有“知识底座雏形 + 学习考试闭环 + AI 入口”的基础形态。 + +### 2.2 当前形态的核心局限 + +虽然已有知识库、学习、考试、AI 三类能力，但当前系统主轴仍然更接近“培训业务系统”，而不是“知识底座平台”。 + +主要问题有： + +- 知识对象尚未成为全系统统一主实体 +- 题库、课程、知识块、AI 检索之间关联偏弱 +- 学习/考试之外的业务层尚未展开 +- AI 入口更像通用聊天框，而不是业务型智能体矩阵 +- 客户难以基于平台能力定制自己的业务智能体 + +### 2.3 战略转向的必要性 + +如果项目继续停留在“学习 + 考试 + 右侧 AI 面板”层面，后续会遇到两个明显上限： + +- 业务上限：只能做培训，无法自然扩展到销售赋能、陪练认证、合规审查、内容工厂等更高价值场景 +- 产品上限：AI 只能作为附属功能存在，无法成长为平台级能力单元 + +因此，项目需要完成一次主轴上收： + +**从“知识库服务于模块”转向“模块生长在知识库之上”。** + +## 3. 总体战略定义 + +### 3.1 新的平台定义 + +项目未来不应再只被定义为“带 AI 的培训系统”，而应定义为： + +**一个以知识库底座为核心、以智能体为能力单元、支持客户半定制的销售训练与认证平台。** + +### 3.2 三层视角 + +为了避免后续再次混淆“底座能力”和“业务应用”，建议统一采用三层视角： + +#### 第一层：知识层 + +负责“知识能不能进来、管起来、找得到、信得过”。 + +包括： + +- 知识源接入 +- 知识加工与结构化 +- 知识治理与版本管理 +- 检索、引用、权限、审计 + +#### 第二层：业务层 + +负责“知识如何进入岗位工作与业务流程”。 + +包括： + +- 学习 +- 考试 +- 陪练 +- 认证 +- 销售赋能 +- 合规审查 +- 内容生产 +- 复盘与教练 + +#### 第三层：经营层 + +负责“知识与业务效果如何被度量、复盘和持续优化”。 + +包括： + +- 知识热度 +- 薄弱知识点 +- 高频错误表达 +- 培训与认证通过率 +- 陪练效果 +- 团队能力短板 +- AI 使用与 ROI + +## 4. 五层架构建议 + +结合当前项目现状，建议进一步统一为五层架构： + +### 4.1 知识源层 + +沉淀原始输入对象： + +- 文档资料 +- 视频与图片素材 +- 产品资料 +- 制度规范 +- 课程内容 +- 历史问答 +- 考试题目 +- 真实对话与训练脚本 + +### 4.2 知识加工层 + +负责把原始资料转成平台可消费对象： + +- 抽取 +- 切片 +- 标签 +- 分类 +- 主题归并 +- 知识点抽取 +- FAQ 生成 +- 训练脚本生成 + +### 4.3 知识底座层 + +这是后续最关键的一层，需要建立统一知识实体体系。 + +建议统一抽象以下对象： + +- 知识主题 +- 知识点 +- 知识资源 +- 知识衍生物 + +其中： + +- 知识资源：文档、视频、产品资料、制度、案例 +- 知识衍生物：课程、题目、FAQ、话术卡、陪练脚本、认证规则 + +### 4.4 能力服务层 + +这是知识底座之上的通用能力层，包括： + +- 搜索与检索 +- 智能问答 +- 内容生成 +- 出题组卷 +- 陪练对话 +- 评分与认证 +- 合规审查 +- 复盘分析 + +### 4.5 应用模块层 + +这是面向用户可见的业务模块层，包括： + +- 学习中心 +- 考试中心 +- 陪练中心 +- 认证中心 +- 合规助手 +- 内容运营 +- 智能体中心 +- 智能体工坊 + +## 5. 业务层不应只等于学习与考试 + +### 5.1 当前业务层状态 + +从现状来看，已经成型的业务层主要是： + +- 学习内容 +- 练习与考试 +- 我的学习 + +这条线是成立的，但它只能证明平台具备“培训业务壳”，不能证明平台已经具备“知识平台的业务上层”。 + +### 5.2 业务层的正确理解 + +业务层不是“更多页面”，而是“知识库被某类岗位工作强制拉出来的应用形态”。 + +因此，业务层设计必须回答： + +- 哪个岗位在使用知识 +- 使用知识是为了完成什么任务 +- 任务结果如何被验证 +- 任务表现是否能反哺知识治理 + +### 5.3 未来可成立的核心业务层 + +在当前项目语境下，最值得发展的业务层不止学习考试，还包括： + +#### 1. 销售赋能层 + +- 产品知识顾问 +- 竞品对比助手 +- 客户场景推荐 +- 成交话术助手 +- 场景化解决方案输出 + +#### 2. 陪练认证层 + +- AI 角色陪练 +- 异议处理训练 +- 合规表达训练 +- 产品知识认证 +- 上岗认证 + +#### 3. 合规风控层 + +- 违规表述识别 +- 缺失披露提醒 +- 风险用语替换建议 +- 审查留痕与可追溯依据 + +#### 4. 内容工厂层 + +- FAQ 生成 +- 课程大纲生成 +- 微课脚本生成 +- 题目生成 +- 话术卡片生成 +- 陪练脚本生成 + +#### 5. 复盘教练层 + +- 训练后复盘 +- 考试后补训建议 +- 会话复盘 +- 团队能力画像 +- 经理周报 + +#### 6. 经营分析层 + +- 知识热度分析 +- 常见错误表达 +- 高频薄弱知识点 +- 培训 ROI +- 认证通过率趋势 + +## 6. 三个行业母型带来的启发 + +为了避免只在“培训系统”视角里做收敛，需要借助外部行业母型反推业务层结构。这里最有借鉴价值的三个母型分别是金融/保险、客服/电商、制造/现场服务。 + +### 6.1 金融/保险型 + +这类行业的关键矛盾不是“员工学没学过”，而是： + +- 当场能不能说对 +- 说对的同时能不能成交 +- 成交时会不会踩合规红线 + +因此，知识库上面长出来的不是普通 LMS，而是： + +- 产品顾问 +- 合规成交助手 +- 异议处理陪练 +- 销售知识认证 +- 经理教练台 + +这也是当前项目最接近的行业母型。 + +### 6.2 客服/电商型 + +这类行业的关键矛盾不是培训，而是： + +- 响应是否足够快 +- 口径是否一致 +- 能不能从回答直接进入流程处理 + +因此，知识库上面会长出： + +- 客户自助问答 +- 坐席辅助 +- 工单流程执行 +- 政策口径统一 +- 服务运营分析 + +这类母型提醒我们：知识库的上层不一定只有学习，也可以直接挂服务流程。 + +### 6.3 制造/现场服务型 + +这类行业的关键矛盾是： + +- 现场是否能快速拿到正确 SOP +- 是否能减少返工、停机、错误操作 +- 老师傅经验能否沉淀下来 + +因此，知识库上面会长出： + +- 故障诊断 Copilot +- SOP Copilot +- Checklist 执行助手 +- 上岗认证 +- 现场复盘系统 + +这类母型最值得借鉴的，不是行业内容本身，而是其系统纪律： + +- 必须引用来源 +- 必须有版本控制 +- 文档没覆盖时要敢于拒答 +- 关键流程要能进入 checklist 或认证模式 + +## 7. 项目最终应参考的行业母型 + +综合判断，当前项目的最佳路径不是简单复制企业培训平台，而是： + +### 7.1 主母型：金融/保险销售能力平台 + +平台主轴应围绕： + +- 产品知识 +- 销售作战 +- 合规成交 +- 陪练训练 +- 认证上岗 + +### 7.2 借鉴母型：制造/现场服务的 SOP 纪律 + +重点借鉴： + +- 来源引用 +- 版本控制 +- 拒答机制 +- 认证式校验 + +### 7.3 中远期扩展：客服/服务支持平台 + +未来可向以下方向扩展： + +- 售前答疑助手 +- 售后政策助手 +- 服务标准口径台 +- 客户问题分流与复盘 + +## 8. 为什么要采用智能体矩阵 + +### 8.1 单一 AI 助手的局限 + +单一 AI 助手存在几个明显问题： + +- 职责混杂，什么都能做但什么都不够专业 +- 难以建立清晰的入口和使用心智 +- 难以绑定不同的知识范围、规则和评分机制 +- 难以支持客户定制 + +### 8.2 智能体矩阵的优势 + +采用智能体矩阵后，可以把 AI 能力拆成多个可治理、可配置、可组合的能力单元。 + +每个智能体具备： + +- 明确职责 +- 明确知识范围 +- 明确输入输出 +- 明确规则与评分逻辑 +- 明确适用人群 + +这比“一个超级 AI”更适合企业平台长期演进。 + +## 9. 建议的 8 个核心智能体 + +### 9.1 知识顾问 + +作用： + +- 回答产品、制度、流程、话术依据 + +定位： + +- 平台通用知识入口 + +### 9.2 产品顾问 + +作用： + +- 把知识库里的产品资料转成销售可用表达 + +定位： + +- 销售作战前台的产品表达助手 + +### 9.3 陪练教官 + +作用： + +- 模拟客户对话，完成角色扮演与训练反馈 + +定位： + +- 平台最核心的训练型智能体 + +### 9.4 合规审查官 + +作用： + +- 检查话术、回答、材料是否合规 + +定位： + +- 培训与风控之间的桥梁型智能体 + +### 9.5 认证考官 + +作用： + +- 负责认证性评估与通过判断 + +定位： + +- 从普通考试升级到上岗判断 + +### 9.6 出题组卷官 + +作用： + +- 基于知识点、岗位、难度生成题目和试卷 + +定位： + +- 题库建设与考试生成的生产型智能体 + +### 9.7 复盘教练 + +作用： + +- 复盘训练、考试和真实沟通记录，给出改进建议 + +定位： + +- 形成“练后有复盘、考后有补训”的闭环 + +### 9.8 内容工坊助手 + +作用： + +- 把知识沉淀成 FAQ、课程、脚本、题目、话术卡 + +定位： + +- 知识库向内容工厂演进的关键智能体 + +## 10. 智能体之间的关系 + +### 10.1 前台主链路 + +知识顾问 -> 产品顾问 -> 陪练教官 -> 认证考官 -> 复盘教练 + +### 10.2 后台生产链路 + +内容工坊助手 -> 出题组卷官 -> 合规审查官 + +### 10.3 管理闭环 + +认证考官 -> 复盘教练 -> 内容工坊助手 -> 新一轮训练/认证 + +## 11. 为什么允许客户定制一部分智能体 + +### 11.1 商业层面 + +客户真正需要的不是“通用 AI 很聪明”，而是： + +- 很懂我的产品 +- 很懂我的流程 +- 很懂我的客户场景 +- 很懂我的管理口径 + +因此，让客户定制一部分智能体，不是可选项，而是提升粘性和形成平台差异化的关键。 + +### 11.2 产品层面 + +客户最常需要定制的不是底层模型，而是： + +- 智能体人设 +- 场景模板 +- 知识范围 +- 评分规则 +- 输出模板 + +因此，平台应开放“业务配置”，而不是开放“底层随意编程”。 + +## 12. 客户定制智能体工坊 + +### 12.1 基本原则 + +不建议做成完全开放式 Agent 平台，而应做成： + +**标准智能体 + 模板化工坊 + 半定制配置。** + +### 12.2 三层模型 + +#### 第一层：平台标准智能体 + +由平台内置，客户开箱即用。 + +适合： + +- 知识顾问 +- 陪练教官 +- 合规审查官 +- 认证考官 + +#### 第二层：客户可配置智能体 + +客户可在平台模板基础上做半定制。 + +适合： + +- 场景陪练型 +- 产品顾问型 +- 认证考核型 +- 内容生成型 + +#### 第三层：专家交付型智能体 + +针对行业客户或大客户，由平台实施团队交付深度定制版本。 + +适合： + +- 车险续保陪练官 +- 理财产品认证官 +- 网点合规审查官 +- 区域化销售教练 + +### 12.3 推荐开放的配置项 + +客户最适合配置以下内容： + +- 智能体名称 +- 角色说明 +- 适用对象 +- 知识范围 +- 场景模板 +- 客户画像或陪练人设 +- 工作流步骤 +- 评分规则 +- 输出格式 +- 发布范围 + +### 12.4 不建议下放的能力 + +以下能力建议始终由平台统一控制： + +- 底层模型路由 +- 权限模型 +- 审计与留痕 +- 引用与溯源机制 +- 平台级合规底线 +- 安全边界与数据隔离 + +## 13. 智能体工坊的产品结构 + +### 13.1 智能体中心 + +展示： + +- 标准智能体 +- 我的智能体 +- 部门智能体 +- 平台模板 + +### 13.2 创建方式 + +支持三种方式： + +- 从标准模板创建 +- 从已有智能体复制 +- 从空白配置创建 + +推荐默认入口： + +- 从模板创建 + +### 13.3 配置面板 + +建议至少包含： + +- 基础信息 +- 知识范围 +- 角色与场景 +- 输出格式 +- 评分与规则 +- 发布范围 + +### 13.4 测试区 + +在发布前必须可测试： + +- 试问答 +- 试陪练 +- 试评分 +- 试审查 + +### 13.5 发布与版本 + +发布状态建议统一为： + +- 草稿 +- 测试中 +- 已发布 +- 已停用 + +必须保留版本号与变更记录。 + +## 14. 权限模型建议 + +### 14.1 平台管理员 + +负责： + +- 平台模板 +- 平台底线规则 +- 租户级安全策略 + +### 14.2 客户管理员 + +负责： + +- 客户知识包 +- 客户标准智能体 +- 发布审批 + +### 14.3 部门管理员 + +负责： + +- 基于模板做部门级配置 +- 调整评分权重 +- 管理场景模板 + +### 14.4 普通用户 + +负责： + +- 使用智能体 +- 收藏模板 +- 复制个人版 + +不负责： + +- 对全员发布 + +## 15. 推荐的最小落地路线 + +### 15.1 MVP 第一阶段 + +先做 4 个标准智能体： + +- 知识顾问 +- 陪练教官 +- 合规审查官 +- 认证考官 + +同时只提供 1 个模板： + +- 场景陪练模板 + +### 15.2 MVP 第二阶段 + +开放客户半定制的 3 个能力： + +- 知识范围 +- 客户画像 +- 评分规则 + +### 15.3 MVP 第三阶段 + +扩展为完整工坊，增加： + +- 产品顾问模板 +- 认证模板 +- 内容生成模板 + +## 16. 导航与产品信息架构建议 + +如果平台完成知识底座与智能体化升级，一级导航建议逐步演进为： + +- 知识库 +- 智能体 +- 学习与考试 +- 陪练与认证 +- 内容运营 +- 组织与系统 + +其中“智能体”下建议至少包含： + +- 标准智能体 +- 我的智能体 +- 智能体工坊 +- 模板中心 +- 发布记录 + +## 17. 对当前项目的最终判断 + +### 17.1 当前项目不应停留在“培训系统 + AI 聊天框” + +它已经具备升级为平台的关键前提： + +- 有知识入库链路 +- 有学习考试闭环 +- 有 AI 对话入口 +- 有岗位知识映射 + +### 17.2 最有前景的方向 + +项目未来最有价值的定位不是继续堆培训页面，而是： + +**以知识底座为核心，围绕销售赋能、陪练认证、合规经营和内容生产，形成一个多智能体平台。** + +### 17.3 一句话结论 + +项目的最终形态应是： + +**知识底座 + 标准智能体中心 + 客户半定制智能体工坊 + 销售训练与认证闭环。** diff --git a/docs/01_System_Overall/SY04_Plugin_Workflow_Ontology_Delivery_Platform.md b/docs/01_System_Overall/SY04_Plugin_Workflow_Ontology_Delivery_Platform.md new file mode 100644 index 0000000..dd3c01c --- /dev/null +++ b/docs/01_System_Overall/SY04_Plugin_Workflow_Ontology_Delivery_Platform.md @@ -0,0 +1,344 @@ +# SY04 — 数字员工平台（共享对象层 + 任务系统 + 专员市场/工坊/工作台） + +> 版本：V1.2 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于把项目从“培训系统 + AI 面板”升级为“数字员工平台”的关键分析沉淀成可复用结论，避免在仓库更名/迁移后丢失对话上下文。 + +本文档覆盖： + +- 为什么要从“智能体矩阵”升级为“工作流交付系统” +- 为什么必须引入本体层（Ontology Layer） +- 为什么本体层本质上是在让数据、动作、工作流一般化 +- L1–L6 自下而上分层模型（面向专员市场、工坊装配、工作台交付） +- UI 应该长什么样（像 Dify 的装配感，但更强调交付/审计/复盘） +- 最小落地路线（不分仓、渐进演进、可回滚） + +相关参考文档： + +- [SY03_Knowledge_Centric_Agent_Platform_Strategy.md](file:///home/eaiadmin/eaifiles/codebase/pj0231-eaisalestraining/docs/01_System_Overall/SY03_Knowledge_Centric_Agent_Platform_Strategy.md) +- [09_Research/wechat/叶小钗](file:///home/eaiadmin/eaifiles/codebase/pj0231-eaisalestraining/docs/09_Research/wechat/%E5%8F%B6%E5%B0%8F%E9%92%97)（专家/专家团、任务系统、生产级 Agent 工程清单） +- [SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform/docs/01_System_Overall/SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md) +- [SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md](file:///home/eaiadmin/eaifiles/codebase/pj0235-eai_agentplatform/docs/01_System_Overall/SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md) + +--- + +## 1. 核心结论（一句话） + +平台的主轴应从“知识库 + 智能体矩阵”升级为： + +**数字员工是产品形态 → 专员是最小装配单元 → 工作流是协作骨架 → 共享对象层是对象/动作/工作流的一般化骨架 → 知识/模型/工具是底座能力。** + +补充一句产品口径： + +- **对用户**：看到的是数字员工与 `xxx专员` +- **对平台实现**：底层仍然由插件、连接器、工作流、对象模型组成 + +--- + +## 2. 为什么 SY03 视野不够（需要扩大） + +SY03 在业务方向上提出“知识底座 + 智能体矩阵 + 半定制工坊”是正确的，但存在两个缺口： + +- 平台缺少“交付闭环”主轴：用户需要的是把任务做完并产出可验收结果，而不只是一个通用聊天入口。 +- 平台缺少“生产级工程底座”：任务系统（依赖/并行/状态快照/返工/人工接管）、事件流可观测、可审计回放、版本隔离等。 + +新增研究材料（WorkBuddy/AgentScope/生产级 Agent 实践指南）提供了关键补齐： + +- 专家/专家团产品化：把 prompt/工具/方法论封装为“角色/团队包”，用户只选角色交任务。 +- 多 Agent 的落地点是任务系统：依赖、并行、汇总、状态面板、事件投影，而不是“多开几个 chat”。 +- 企业购买“培训/工具”的真实诉求是“从业务问题到可上线交付的路径”（SOP/数据/评测/影子运行/灰度/接入）。 + +--- + +## 3. 必须引入本体层（Ontology Layer） + +说明： + +- 从理论目标上，这一层可以称为 `本体层（Ontology Layer）` +- 从当前工程落地上，它更接近 `共享对象层 / 语义对象层` + +本文仍沿用 `本体层` 这一目标形态表述，但当前实施重点应放在： + +- 统一业务对象 +- 统一业务动作 +- 统一工作流上下文 + +### 3.1 为什么需要本体层 + +如果没有本体层，平台会长期卡在： + +- 检索不稳（仅靠切片与向量，缺少业务对象与状态约束） +- 工作流难固化（依赖与状态只能靠模型“猜”） +- 专员/插件之间无法可靠交换数据（只能复制粘贴文本，无法稳定消费上游结果） + +### 3.2 本体层解决什么 + +本体层提供平台统一语义： + +- 实体（Entity）：平台中“存在什么对象” +- 关系（Relation）：对象之间如何关联 +- 状态（State）：对象处于什么阶段（草稿/发布/审核/运行中/完成） +- 约束（Constraint）：字段类型、必填、枚举、版本兼容 + +专员之间在产品层表现为协作，在实现层交换的应是“本体对象引用 + 字段”，不是纯文本。 + +更进一步说，本体层的价值不只是“描述对象”，而是让智能体面对一个稳定的业务世界： + +- 不直接面对原始表结构，而面对业务对象 +- 不直接面对系统 API，而面对业务动作 +- 不直接面对零散 SOP，而面对可运行的工作流骨架 + +也就是说，本体层本质上是在做三类一般化： + +### 3.3 数据一般化 + +把底层异构字段和记录，提升为统一业务对象。 + +例如： + +- CRM、ERP、OA 中含义相近但结构不同的数据 +- 统一映射为 `Customer / Order / Approval / Shipment / Task / Artifact` + +这样智能体读取的就不再是“字段堆”，而是稳定对象。 + +### 3.4 动作一般化 + +把底层系统接口和页面操作，提升为统一业务动作。 + +例如： + +- `创建跟进记录` +- `提交审批` +- `更新订单状态` +- `发送通知` + +统一提升为： + +- `CreateFollowUp` +- `SubmitApproval` +- `UpdateOrderStatus` +- `NotifyStakeholder` + +这样智能体面对的就不再是散乱 API，而是稳定动作契约。 + +### 3.5 工作流一般化 + +把零散的人工 SOP、页面顺序和经验步骤，提升为统一运行骨架。 + +例如统一为： + +- `Run` +- `Stage` +- `Task` +- `Dependency` +- `Checkpoint` +- `Artifact` + +这样平台才能从“会答”升级为“会把事情做完”。 + +### 3.6 最小可行本体（MVO） + +优先落地能驱动工作流与专员协作交换的对象： + +- Task（任务） +- Artifact（交付物） +- Evidence（证据片段/引用链） +- KnowledgeAsset（原始资料） +- KnowledgeNode（知识点/主题） +- PolicyRule（合规规则/条款） +- Scenario（场景语境/客户画像） +- AgentPlugin（底层插件能力单元：输入/输出 schema + 权限，对外产品化为 `xxx专员`） + +配套优先定义的通用业务动作建议： + +- FetchContext（取上下文） +- GenerateArtifact（生成交付物） +- SubmitApproval（提交审批） +- NotifyStakeholder（通知相关方） +- WriteBack（回写外部系统） +- EscalateRisk（升级风险） +- RequestHumanReview（请求人工确认） + +--- + +## 4. L1–L6（自下而上）平台分层 + +### L1 运行与安全底座（Runtime & Governance） + +管什么：鉴权、权限、配额、审计、隔离、可观测、模型路由与连接器。 + +关键对象： + +- Tenant/User/Role/Policy +- Provider/Route/Secret +- MCP Connector +- AuditLog / Usage + +### L2 知识接入与加工层（Ingestion & Processing） + +管什么：把资料变成可引用证据与可检索素材。 + +关键对象： + +- KnowledgeAsset（文档/视频/图片/制度/对话） +- Chunk（切片） +- Evidence（来源、页码/时间戳、哈希） + +### L3 共享对象与索引层（目标形态：Ontology Layer） + +管什么：把底层异构数据统一为业务对象、关系、状态和约束；提供向量/关键词/结构化索引与权限过滤；支持结构化交换与溯源引用。 + +关键能力： + +- 数据一般化：把原始字段与记录提升为稳定业务对象 +- 统一对象模型：Task / Artifact / Evidence / PolicyRule / Scenario / AgentPlugin +- 统一状态与约束：字段类型、必填、枚举、状态迁移、版本兼容 +- 结构化交换：outputs/artifacts/citations（evidence_ids） +- 结构化引用：交付物可追溯到证据片段 + +### L4 能力服务层（Capabilities Services） + +管什么：将检索、生成、抽取、评分、合规、连接器调用等封装为稳定 API，并把底层系统操作提升为统一业务动作。 + +统一返回建议： + +- outputs（结构化字段） +- artifacts（交付物列表与引用） +- citations（evidence_ids） +- risks（风险项） + +关键能力补充： + +- 动作一般化：把底层 API/页面操作抽象为统一业务动作 +- 输入输出契约统一：专员背后的插件、连接器、模型能力都返回同一结构 +- 动作权限与审计：动作调用可绑定角色、审批、审计与写回控制 + +### L5 工作流与任务运行时（Workflow & Task Runtime） + +管什么：把对象和动作组织成可交付工作，形成统一运行骨架，支持依赖、并行、状态机、返工、人工接管与可观察。 + +关键对象： + +- WorkflowTemplate / Stage / Task / Dependency +- Run / Checkpoint（人工确认点） +- ArtifactRegistry（产物版本与归档） + +关键能力补充： + +- 工作流一般化：把零散 SOP 提升为 Run/Stage/Task/Checkpoint 骨架 +- 任务推进：对象状态变化与动作执行可以推进流程 +- 人机协同：在关键节点插入 checkpoint 与人工接管 +- 交付闭环：每次运行都沉淀 artifacts / evidence / risks / replay + +### L6 数字员工与工作台层（Digital Employees / Marketplace / Studio / Workbench UI） + +管什么：提供“专员市场下载感、工坊自由装配感、业务工作台交付可见感”。 + +三大界面： + +- Digital Employees / Workbench（数字员工工作台）：围绕“我的专员、当前事项、交付物、风险、证据链”展开业务处理 +- Marketplace（专员市场）：发现/安装/升级/卸载专员，查看职责、权限提示、版本 +- Studio/Workshop（工坊）：装配工作流模板、字段映射、配置、测试、发布，把底层插件装配成 `xxx专员` + +--- + +## 5. UI 应该是什么样（像 Dify，但更偏交付系统） + +### 5.1 一级导航建议（面向数字员工与交付） + +- 数字员工 +- 专员市场 +- 工坊（Studio） +- 知识库（Knowledge） +- 控制台（Console） + +### 5.2 推荐 UI 形态：多窗格工作台（Multi-pane） + +采用三栏/多窗格是业务必需（同时呈现过程、状态、数据、装配）： + +- 左栏：任务/步骤（阶段、依赖、状态、返工、人工接管） +- 中栏：过程/配置（对话/事件流/专员配置/工作流装配，使用 tabs） +- 右栏：数据抽屉（Outputs/Artifacts/Evidence/Risks） + +### 5.3 “专员市场感”的五个信号 + +- 专员可识别为岗位型商品（头像/岗位名、职责、版本、更新日志、分类） +- 生命周期（安装/启用/卸载/升级） +- 权限提示（读写范围、外部连接、点数消耗） +- 配置页（schema 生成表单）+ 测试区 +- 可分发来源（内置市场/私有市场/导入包） + +### 5.4 “专员之间协作感”的三个载体 + +- 变量（Outputs）：结构化字段树，可被下游专员引用 +- 产物（Artifacts）：文件/报告/表格，版本化并可回放 +- 引用（Evidence）：来源、页码/时间戳、片段预览（证据链） + +--- + +## 6. 不分仓的最小落地路线（可回滚） + +不建议因 UI 改造另开仓库；推荐同仓双模式并行，路由隔离 + 功能开关 + 新布局容器。 + +### 6.1 路由隔离 + +- 保留原路径不动 +- 新增 `/workbench`（或 `/studio`）作为新工作台入口 + +### 6.2 功能开关（Feature Flags） + +- 通过配置决定是否显示数字员工工作台/专员市场/工坊 +- 先管理员可见、灰度开放 + +### 6.3 新布局容器（WorkbenchLayout） + +- 新增 WorkbenchLayout（三栏/多窗格） +- 旧页面继续用旧 Layout，避免一次性大手术 + +### 6.4 MVP 顺序（建议） + +1) 先本体化 Artifact（每次运行都有可见交付物） +2) 再本体化 Task（任务看板与状态机） +3) 再统一业务动作契约（让现有快捷动作可以被编排与回写） +4) 再把现有快捷动作产品化为专员（安装/启用） +5) 最后补专员市场与工坊（装配与发布） + +--- + +## 7. 与“简历整理智能体”场景的对应 + +简历类场景的关键差异化不在“写得像人”，而在“交付工作流”： + +- S0 资料澄清 → S1 经历结构化 → S2 JD 匹配矩阵 → S3 多版本生成 → S4 风险校验 → S5 交付包与版本记录 + +该场景天然需要： + +- Task/Stage 状态机（可返工） +- Artifact 归档（简历 v1/v2/v3、匹配报告） +- Evidence 引用（材料来源、用户确认点） + +--- + +## 8. 与本仓库现状的对照（关键缺口） + +当前前端更接近“系统功能 + 固定 AI 面板”，缺少： + +- 数字员工/专员市场/工坊 三套产品形态入口 +- 底层插件 manifest 与专员安装生命周期 +- Task/Artifact/Evidence 的可视化数据抽屉（用于交换感） +- 本体层/共享对象层（统一对象模型、动作语义与交换协议） +- 任务系统（依赖/并行/状态快照/人工确认点/交付闭环） + +--- + +## 9. 交付物清单（本次沉淀） + +- 本文档：SY04（平台升级分析、分层、UI、落地路线） +- 研究材料已入库： + - [09_Research/wechat/叶小钗](file:///home/eaiadmin/eaifiles/codebase/pj0231-eaisalestraining/docs/09_Research/wechat/%E5%8F%B6%E5%B0%8F%E9%92%97) + - [生产级Agent实践指南/PAG00](file:///home/eaiadmin/eaifiles/codebase/pj0231-eaisalestraining/docs/09_Research/wechat/%E5%8F%B6%E5%B0%8F%E9%92%97/%E7%94%9F%E4%BA%A7%E7%BA%A7Agent%E5%AE%9E%E8%B7%B5%E6%8C%87%E5%8D%97/PAG00_%E5%90%88%E9%9B%86%E6%80%BB%E8%A7%88_%E6%91%98%E8%A6%81%E4%B8%8E%E5%B7%A5%E7%A8%8B%E6%A3%80%E6%9F%A5%E5%8D%95_01-14.md) + - [PAG14](file:///home/eaiadmin/eaifiles/codebase/pj0231-eaisalestraining/docs/09_Research/wechat/%E5%8F%B6%E5%B0%8F%E9%92%97/%E7%94%9F%E4%BA%A7%E7%BA%A7Agent%E5%AE%9E%E8%B7%B5%E6%8C%87%E5%8D%97/PAG14_%E7%AC%AC14%E7%AF%87_%E5%A4%9AAagent%E7%BC%96%E6%8E%92%E4%B8%8E%E4%BB%BB%E5%8A%A1%E7%B3%BB%E7%BB%9F_%E4%BB%8E%E4%B8%80%E6%AC%A1%E5%A7%94%E6%B4%BE%E5%88%B0%E4%BB%BB%E5%8A%A1%E5%B7%A5%E4%BD%9C%E6%B5%81.md) diff --git a/docs/01_System_Overall/SY05_Connector_Network_Enterprise_Integration_Architecture.md b/docs/01_System_Overall/SY05_Connector_Network_Enterprise_Integration_Architecture.md new file mode 100644 index 0000000..afe2844 --- /dev/null +++ b/docs/01_System_Overall/SY05_Connector_Network_Enterprise_Integration_Architecture.md @@ -0,0 +1,535 @@ +# SY05 — 六层架构 + 连接器网络（企业原有业务系统融合总图） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于补齐 SY04 中相对弱化的一块：**平台如何与企业原有业务系统深度结合**。 + +这里说的不是“开放平台 API”，而是更接近 WorkBuddy 语境中的： + +- CRM / ERP / OA / BPM / HR / IM / 邮件 / 网盘 / 文件系统 / 数据库 / BI +- 这些企业存量系统如何通过 **连接器网络（Connector Network）** 接入平台 +- 并成为工作流的输入源、触发器、执行器、回写口与审计链的一部分 + +一句话定义： + +**连接器不是外围适配层，而是平台主梁之一。它负责把企业原有系统稳定接入工作流运行时。** + +--- + +## 1. 核心结论（一句话） + +平台不应被定义为“一个新的大一统业务系统”，而应定义为： + +**数字员工平台 = 工作流运行时 + 共享对象层 + 连接器网络 + 专员背后的能力插件 + 交付界面。** + +其中： + +- 工作流负责把事做完 +- 本体负责统一交换语义 +- 连接器负责把企业原系统接进来 +- 底层插件负责提供可装配能力，并在产品层表现为 `xxx专员` +- 数字员工工作台 / 工坊 / 控制台负责把这一切产品化 + +--- + +## 2. 为什么连接器必须上升为一级架构对象 + +如果没有连接器网络，平台会长期卡在以下状态： + +- 新平台成为“孤岛系统”，只能人工录入上下文 +- 工作流只能在平台内部自循环，无法挂接真实业务进度 +- AI 或专员产物无法回写 CRM/OA/ERP，交付闭环中断 +- 用户需要在多个系统之间复制粘贴，平台价值被稀释 +- 市场/工坊即使做出来，也只是“内部拼装台”，不是企业级工作枢纽 + +因此，连接器要解决的不是“能不能调通接口”，而是： + +**能不能把企业原系统转化成平台可稳定消费的工作流节点。** + +--- + +## 3. 六层架构 + 连接器网络总图 + +```text + ┌──────────────────────────────────────┐ + │ 企业原有业务系统 │ + │ CRM | ERP | OA/BPM | HR | IM/企微 │ + │ 邮件 | 网盘 | 文件系统 | DB | BI/WMS │ + └──────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ 连接器网络 Connector Network │ +│ │ +│ 读取型 Read | 触发型 Trigger | 执行型 Action | 回写型 Writeback │ +│ Pull/Query | Event/Webhook | Create/Update | Result/Artifact/Status │ +│ │ +│ 统一能力：认证、字段映射、事件订阅、重试、幂等、审计、健康检查、限流 │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L1 运行与治理底座 │ +│ Auth / Role / Policy / Secret / Quota / Audit / Isolation / Observability │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L2 知识接入与加工层 │ +│ KnowledgeAsset / Chunk / Evidence / Source Snapshot / Parsing / Enrichment │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L3 本体与索引层 │ +│ Task / Artifact / Evidence / Scenario / PolicyRule / AgentPlugin │ +│ ConnectorBinding / FieldMapping / EntityLink / State / Constraint │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L4 能力服务层 │ +│ Search / Extract / Generate / Score / Compliance / Connector Actions │ +│ 统一返回：outputs / artifacts / citations / risks │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L5 工作流与任务运行时 │ +│ WorkflowTemplate / Run / Stage / Task / Dependency / Checkpoint │ +│ Trigger / Retry / Human Handoff / Replay / Writeback / ArtifactRegistry │ +└────────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────┐ +│ L6 应用与交付界面层 │ +│ Run | Studio | Market | Knowledge | Governance │ +│ 其中 Connectors 在 Studio / Governance 中是一等公民 │ +└────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 4. 连接器在六层中的准确职责 + +### 4.1 L1：连接器的运行与治理 + +L1 负责连接器“能不能安全稳定跑”： + +- 凭据管理（API Key / Token / Cookie / DB 连接串） +- 权限范围与最小授权 +- 调用审计、限流、熔断、超时、重试 +- 租户隔离、环境隔离（测试/生产） +- 连接器实例健康状态与告警 + +最小对象建议： + +- `ConnectorDefinition` +- `ConnectorInstance` +- `ConnectorCredential` +- `ConnectorHealthCheck` +- `ConnectorAuditLog` + +### 4.2 L2：连接器的数据读取与接入 + +L2 负责把企业原系统的数据拉入平台： + +- 从 CRM 读取客户/商机/跟进记录 +- 从 ERP 读取订单/合同/回款/库存 +- 从 OA/BPM 读取审批单/流程状态 +- 从 HR 读取组织架构/岗位/员工信息 +- 从 IM 读取通知、消息、会话上下文 +- 从文件系统/网盘读取附件与交付材料 + +这些数据在进入平台时仍然是“源数据”，还没有成为统一对象。 + +### 4.3 L3：连接器的语义映射与本体绑定 + +L3 是连接器网络最关键的一层。 +企业原系统字段不能直接在平台里乱流，必须先做统一语义映射。 + +典型映射示例： + +- CRM 商机 -> `Scenario` / `Task` +- ERP 报价单 -> `Artifact` +- OA 审批记录 -> `Evidence` +- HR 岗位 -> `Role` / `OrgUnit` +- 文件系统中的合同附件 -> `KnowledgeAsset` / `Evidence` + +最小对象建议： + +- `ConnectorBinding` +- `FieldMapping` +- `EntityLink` +- `ExternalReference` +- `SourceSnapshot` + +### 4.4 L4：连接器作为可调用能力节点 + +进入 L4 后，连接器不再只是“接口”，而是可被工作流装配的能力： + +- `CRM.ReadCustomer` +- `CRM.WriteFollowup` +- `ERP.CreateQuote` +- `OA.StartApproval` +- `HR.QueryEmployee` +- `WeCom.SendMessage` + +所有连接器动作应遵守统一返回协议： + +```ts +{ + outputs: {}, + artifacts: [], + citations: [], + risks: [] +} +``` + +### 4.5 L5：连接器进入工作流运行时 + +在 L5，连接器扮演 4 种角色： + +1. 触发器：原系统事件触发 Run +2. 输入源：给 Task 提供上下文与业务对象 +3. 执行器：在任务执行中调用外部系统动作 +4. 回写口：把结果、状态、产物回写外部系统 + +典型闭环： + +`CRM 商机进入阶段 -> 触发 Run -> 读取客户/历史记录 -> 生成方案/报价 -> 发起 OA 审批 -> 审批通过 -> 回写 CRM -> 发送企微通知` + +### 4.6 L6：连接器必须产品化，而不是藏在系统设置里 + +连接器在 L6 至少应该有两种产品站位： + +- `Studio`：把连接器动作拖入工作流，做字段映射、测试、版本化 +- `Governance`：管理连接器安装、授权、健康状态、调用日志、失败重试 + +可选地，在 `Market` 中作为“可安装连接器包”分发。 + +--- + +## 5. 连接器的四种核心类型 + +### 5.1 读取型连接器（Read Connector） + +作用： + +- 拉取上下文 +- 查询业务主数据 +- 读取历史记录与原始证据 + +典型系统： + +- CRM / ERP / HR / BI / 文件系统 / 数据库 + +### 5.2 触发型连接器（Trigger Connector） + +作用： + +- 监听外部系统事件 +- 触发新的 Run +- 推进已有 Run 的状态 + +典型系统： + +- OA/BPM 事件 +- CRM 商机状态变化 +- 工单系统状态变化 +- 邮件或 IM 消息事件 + +### 5.3 执行型连接器（Action Connector） + +作用： + +- 让平台主动调用原系统动作 + +典型动作： + +- 创建报价单 +- 创建跟进记录 +- 发起审批 +- 更新工单状态 +- 发送消息或邮件 + +### 5.4 回写型连接器（Writeback Connector） + +作用： + +- 把平台输出回写企业原系统 + +典型回写： + +- 写回商机建议摘要 +- 上传报告或报价单 +- 更新业务状态 +- 回填审批结果 +- 绑定 artifact 链接或 evidence 引用 + +--- + +## 6. 典型企业系统接入矩阵 + +| 企业系统 | 主要连接器类型 | 平台中的典型作用 | 对应本体对象 | +|----------|----------------|------------------|--------------| +| CRM | Read / Trigger / Writeback | 客户、商机、跟进、状态推进 | `Scenario` / `Task` / `Artifact` | +| ERP | Read / Action / Writeback | 报价、订单、回款、库存、合同 | `Artifact` / `Task` / `Evidence` | +| OA / BPM | Trigger / Action / Writeback | 审批触发、人审确认、流程状态 | `Checkpoint` / `Evidence` | +| HR | Read | 组织、岗位、员工、权限边界 | `User` / `Role` / `OrgUnit` | +| 企业微信 / 钉钉 / IM | Trigger / Action | 消息触达、人工接管、反馈收集 | `Task` / `Checkpoint` | +| 文件系统 / 网盘 / DMS | Read / Writeback | 原始文件、附件、交付包 | `KnowledgeAsset` / `Artifact` | +| DB / 数据仓库 / BI | Read | 指标、报表、经营上下文 | `Evidence` / `Scenario` | + +--- + +## 7. 连接器的统一对象模型（最小建议） + +### 7.1 连接器定义层 + +- `ConnectorDefinition` + - 连接器类型（CRM / ERP / OA / HR / IM / DB） + - 支持的认证方式 + - 支持的事件、动作、对象 + - manifest 版本 + +### 7.2 连接器实例层 + +- `ConnectorInstance` + - 实例名称 + - 所属租户/环境 + - 授权状态 + - 健康状态 + - 默认策略（超时/重试/限流） + +### 7.3 连接器绑定层 + +- `ConnectorBinding` + - 哪个工作流/模板/插件使用了哪个连接器实例 + - 绑定的外部对象类型 + - 字段映射配置 + +### 7.4 外部引用层 + +- `ExternalReference` + - 外部系统类型 + - 外部对象 id + - 外部 URL 或定位信息 + - 同平台对象的映射关系 + +### 7.5 事件订阅层 + +- `ConnectorEventSubscription` + - 订阅哪个系统的什么事件 + - 事件如何映射到 Run/Task + - 去重键、幂等键、失败处理策略 + +--- + +## 8. 连接器协议（最小工程约束） + +连接器必须遵守统一协议，不应每个系统都各写一套散乱调用逻辑。 + +### 8.1 输入约束 + +- 明确输入 schema +- 明确必填字段 +- 明确上下文字段来源 +- 明确幂等键 + +### 8.2 输出约束 + +统一输出： + +```ts +{ + outputs: {}, + artifacts: [], + citations: [], + risks: [] +} +``` + +### 8.3 运行约束 + +- 必须声明超时 +- 必须支持失败可诊断 +- 必须支持重试语义 +- 必须支持审计日志 +- 必须支持最小权限原则 + +### 8.4 错误模型 + +至少区分： + +- 认证失败 +- 权限不足 +- 对象不存在 +- 外部系统超时 +- 幂等冲突 +- 字段映射失败 +- 回写失败 + +--- + +## 9. 工作流中的连接器闭环示例 + +### 9.1 售前方案工作流 + +```text +CRM 商机变更 + -> Trigger Connector 触发 Run + -> Read Connector 拉取客户/历史跟进/订单背景 + -> 平台生成方案建议与报价草案 + -> Action Connector 发起 OA 审批 + -> 审批结果回流到 Run Checkpoint + -> Writeback Connector 回写 CRM 商机记录 + -> Action Connector 发送企微通知 + -> ArtifactRegistry 归档交付物 +``` + +### 9.2 培训交付工作流 + +```text +HR 岗位变化 + -> Trigger Connector 触发培训 Run + -> Read Connector 拉取员工、岗位、课程要求 + -> 平台生成个性化学习路径 + -> Action Connector 创建学习任务/消息通知 + -> 考试结果写回 HR 或培训系统 + -> Artifact 归档培训包、记录、证书 +``` + +--- + +## 10. UI 形态：连接器在产品中应该长什么样 + +### 10.1 Studio 中的连接器 + +Studio 中连接器应表现为可装配节点： + +- `CRM.读取客户` +- `ERP.创建报价` +- `OA.发起审批` +- `企微.发送通知` +- `DB.查询经营指标` + +每个节点都应有： + +- 输入输出 schema +- 字段映射 +- 凭据来源 +- 测试按钮 +- 上次运行结果 + +### 10.2 Governance 中的连接器 + +Governance 中连接器应作为治理对象管理： + +- 连接器实例列表 +- 授权状态 +- 权限范围 +- 健康状态 +- 最近调用日志 +- 失败重试记录 +- 环境切换（测试/生产） + +### 10.3 Market 中的连接器 + +Market 中连接器应作为“可安装包”出现： + +- 图标 +- 描述 +- 支持系统 +- 支持事件 +- 支持动作 +- 权限提示 +- 版本与更新日志 + +--- + +## 11. 架构边界：连接器不应该做什么 + +为避免连接器层膨胀失控，连接器不应承担以下职责： + +- 不在连接器中硬编码业务流程 +- 不在连接器中直接拼 Prompt 或业务文案 +- 不把字段映射散落在前端页面逻辑里 +- 不让工作流直接耦合外部系统原始字段名 +- 不绕过本体层直接把外部结果塞给下游插件 + +一句话： + +**连接器负责接入与动作，不负责平台业务编排。编排属于 L5，语义属于 L3。** + +--- + +## 12. 最小落地顺序（建议） + +不考虑成本、只追求正确架构时，连接器网络的建设顺序建议如下： + +### 第一步：先抽象统一连接器模型 + +先定义： + +- `ConnectorDefinition` +- `ConnectorInstance` +- `ConnectorBinding` +- `ExternalReference` +- `ConnectorEventSubscription` + +### 第二步：优先做 3 个高价值连接器 + +推荐顺序： + +1. `CRM` +2. `OA/BPM` +3. `企业微信/钉钉` + +这 3 类最容易形成“触发 -> 执行 -> 回写”的闭环。 + +### 第三步：把连接器节点纳入 Studio + +让连接器不再是后端暗逻辑，而是工作流可见节点。 + +### 第四步：把连接器运行日志纳入 Governance + +让失败、重试、审计、健康状态可见。 + +### 第五步：补 Market 分发与模板化接入 + +到这一步，连接器网络才真正从“项目集成”升级为“平台能力”。 + +--- + +## 13. 对本仓库下一步设计工作的直接启发 + +如果后续继续演进本仓库，建议新增以下设计产物： + +1. 连接器对象模型草案 +2. 连接器协议草案（输入/输出/错误/重试/幂等） +3. Studio 中连接器节点的页面框架 +4. Governance 中连接器治理台页面框架 +5. CRM/OA/企微 三类连接器的样板流程图 + +--- + +## 14. 最终结论 + +如果说 SY04 解决的是“平台为什么要从聊天升级为工作流交付系统”， +那么 SY05 解决的是“这个工作流交付系统如何真正嵌入企业现有业务系统”。 + +最终定义应升级为： + +**平台 = 六层内核 + 连接器网络。** + +其中： + +- 六层内核保证平台有语义、有运行时、有交付界面 +- 连接器网络保证平台能接住企业真实业务流 + +没有前者，平台立不起来；没有后者，平台落不下去。 diff --git a/docs/01_System_Overall/SY06_AI_Upgrade_Starting_Point_Decision_Framework.md b/docs/01_System_Overall/SY06_AI_Upgrade_Starting_Point_Decision_Framework.md new file mode 100644 index 0000000..7d324ac --- /dev/null +++ b/docs/01_System_Overall/SY06_AI_Upgrade_Starting_Point_Decision_Framework.md @@ -0,0 +1,286 @@ +# SY06 — AI 升级起步判断框架（知识库先行 / 工作流先行 / 连接器先行） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于回答一个高频但经常被说泛的问题： + +**公司做 AI 升级，到底应该从知识库开始、从工作流开始，还是从连接器开始？** + +本文给出一个可执行的判断框架，避免团队陷入抽象争论。 + +--- + +## 1. 核心结论（一句话） + +不是所有公司都适合从知识库起步。 +更准确的判断应是： + +- **不知道答案**：知识库先行 +- **知道答案但做不完**：工作流先行 +- **知道怎么做但系统不通**：连接器先行 + +--- + +## 2. 三种先行路线的定义 + +### 2.1 知识库先行 + +适用于： + +- 知识分散 +- 标准口径不一致 +- 经验依赖个人 +- 新人学习成本高 +- 高频问题主要是“找不到、找不准、找不全” + +目标： + +- 先把组织知识治理好 +- 建立 AI 可消费的知识底座 +- 形成可引用、可溯源、可版本化的资料体系 + +### 2.2 工作流先行 + +适用于： + +- 跨部门协作长 +- 返工、催办、漏步骤频繁 +- 交付物质量不稳定 +- 过程不可见 +- 管理层更关心状态、责任链、风险和产物 + +目标： + +- 先把“事情怎么做完”标准化 +- 建立任务运行时、状态机、产物管理和回放能力 + +### 2.3 连接器先行 + +适用于： + +- 核心信息分散在多个系统 +- 业务依赖实时结构化数据 +- 需要跨系统取数、执行、回写 +- 过去自动化项目卡在系统兼容或最后一公里 + +目标： + +- 先把业务系统打通 +- 建立连接器网络与统一接入协议 +- 让 AI 从“会答”变成“能干” + +--- + +## 3. 最实用的三问判断法 + +### Q1：员工最常抱怨的是“找不到答案”吗？ + +典型信号： + +- 文档很多，但没人知道最新版在哪里 +- 同一个问题，不同人说法不一致 +- 大量时间花在问人、翻群、翻表格 +- 培训、制度、产品资料解释成本很高 + +若答案为“是”，优先考虑 **知识库先行**。 + +### Q2：员工明明知道怎么做，但事情还是推进不动吗？ + +典型信号： + +- 任务要追很多人 +- 审批、返工、补资料频繁 +- 谁卡住流程不清楚 +- 交付物经常不齐、不稳定、不可追溯 + +若答案为“是”，优先考虑 **工作流先行**。 + +### Q3：问题根本不是人不会做，而是系统之间不通吗？ + +典型信号： + +- 一个任务要切 CRM / ERP / OA / 企微 / Excel 多个系统 +- 关键数据靠人工搬运 +- 外部状态变化无法自动触发内部动作 +- 结果生成后无法回写原系统 + +若答案为“是”，优先考虑 **连接器先行**。 + +--- + +## 4. 评分法（更适合项目立项） + +每项 1-5 分，哪一类总分最高，就先做哪一类。 + +### 4.1 知识库先行评分 + +- 知识分散严重 +- 标准口径不一致 +- 新人培养成本高 +- 高频问答占比高 +- 现有资料很多但利用率低 + +### 4.2 工作流先行评分 + +- 跨部门协作频繁 +- 返工与催办频繁 +- 交付物需要版本与审计 +- 状态不可见 +- 风险点与人工接管点很多 + +### 4.3 连接器先行评分 + +- 多系统切换频繁 +- 实时数据依赖高 +- 必须回写原系统 +- 自动化最后一公里问题突出 +- 历史系统异构严重 + +--- + +## 5. 二维判断图 + +```text + 流程复杂度 / 闭环要求 + 高 + ↑ + │ + 知识库先行 │ 工作流先行 + （知识高，流程较轻） │ （流程长，协同多，系统中等） + │ + 培训 / 咨询 / 售前 / 客服 │ 法律 / 微商 / 项目交付 / 理赔运营 + │ +───────────────────────────────────┼──────────────────────────────────→ + │ 系统耦合 / 实时数据依赖 + │ 高 + │ + 知识库工具层 │ 连接器先行 + （做问答有用，但不是主战场） │ （多系统割裂，数据不通，不接就跑不起来） + │ + 轻内部知识问答场景 │ 医疗 / 工业 / 金融 / 物流货代 + │ + ↓ + 低 +``` + +备注： + +- `知识密度` 不放在坐标轴上单独作为补充判断 +- 高知识行业往往仍然需要知识底座，但不一定适合作为第一优先级 + +--- + +## 6. 适合“知识库先行”的公司类型 + +典型类型： + +- 培训型组织 +- 咨询与方案型团队 +- 售前支持团队 +- 客服知识中心 +- 制度密集型中后台组织 + +适合原因： + +- 80% 的问题可以在现有资料中找到答案 +- 主要瓶颈是找不到与不统一，而不是执行闭环 + +常见误区： + +- 以为知识库做完就等于业务 AI 升级完成 + +更准确说法： + +**知识库更像 AI 升级的第一层基础设施，而不是最终产品形态。** + +--- + +## 7. 适合“工作流先行”的公司类型 + +典型类型： + +- 项目制服务公司 +- 交付型团队 +- 法务事项团队 +- 理赔与售后团队 +- 培训交付与审批型组织 + +适合原因： + +- 大家通常知道要做什么 +- 但任务依赖、审批、人审、返工、跟踪导致效率低 + +关键建设点： + +- WorkflowTemplate +- Run / Task 状态机 +- Checkpoint +- ArtifactRegistry +- Replay / Audit + +--- + +## 8. 必须“连接器先行”的公司类型 + +典型类型： + +- 金融机构 +- 医疗机构 +- 工业制造企业 +- 物流货代公司 +- 多系统并存的中大型集团企业 + +适合原因： + +- 核心业务数据主要在业务系统而不是文档里 +- 不打通连接器，工作流和知识库都只能停留在浅层 + +关键建设点： + +- ConnectorDefinition / ConnectorInstance +- 凭据与权限治理 +- 事件订阅与回写 +- 字段映射与语义绑定 + +--- + +## 9. 最常见的正确路径并不是三选一 + +大多数企业最终会走成以下三条组合路线之一： + +### 路径 A：知识库 -> 工作流 -> 连接器 + +适合： + +- 培训、咨询、售前、法务支持 + +### 路径 B：连接器 -> 工作流 -> 知识增强 + +适合： + +- 金融、医疗、工业、物流货代 + +### 路径 C：工作流 -> 补知识库 -> 再接连接器 + +适合： + +- 项目交付、售后、理赔、运营协同 + +--- + +## 10. 最终结论 + +“从知识库开始”不是错，但不是普遍规律。 +更成熟的判断方式应是： + +- 看公司主要卡在知识、流程，还是系统连接 +- 看核心价值来自查询、协同，还是闭环执行 +- 看最终产物是回答、任务完成，还是跨系统业务动作 + +一句话收束： + +**AI 升级可以从知识库开始，但不能机械地从知识库开始。** diff --git a/docs/01_System_Overall/SY07_Industry_Agent_Pack_Landscape_Overview.md b/docs/01_System_Overall/SY07_Industry_Agent_Pack_Landscape_Overview.md new file mode 100644 index 0000000..e1c9aca --- /dev/null +++ b/docs/01_System_Overall/SY07_Industry_Agent_Pack_Landscape_Overview.md @@ -0,0 +1,215 @@ +# SY07 — 六个行业反推平台需求总览（连接器需求 + 应用方向需求） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于纠正一个容易跑偏的方向： + +当前阶段的目标**不是直接做六个行业包**，而是借六个行业来反推平台六层架构还缺什么。 + +因此本文档的用途是： + +- 用六个行业识别平台必须具备的连接器类型 +- 用六个行业识别平台必须支持的应用方向 +- 用行业差异反推 L3 / L4 / L5 / L6 应具备的通用能力 +- 为六层平台内核建设提供需求样本，而不是直接进入行业化交付 + +--- + +## 1. 核心结论（一句话） + +引入法律、医疗、工业、金融、物流货代、微商这六个行业，当前最重要的意义不是“确定先做哪个行业包”，而是： + +**借这些行业把平台必须具备的连接器能力和应用方向逼出来。** + +--- + +## 2. 六个行业的共同规律 + +广泛观察后，六个行业虽然差异很大，但真正能落地的业务智能体都有共性： + +- 都从高频高价值流程切入 +- 都严重依赖原有系统连接器 +- 都需要 Evidence / Audit / Replay +- 都更适合多智能体分工，而不是单一万能助手 +- 都不是“会答”就够，而是必须“能推进业务” + +--- + +## 3. 六个行业的需求样本矩阵 + +| 行业 | 核心对象 | 关键连接器 | 当前最重要的反推价值 | 平台中的典型主轴 | +|------|----------|------------|----------|------------------| +| 法律 | Matter / Contract / Clause / Playbook | DMS / CLM / eDiscovery / 法律研究平台 | 逼出文档类连接器、审查类工作流、Evidence 抽屉 | 事项工作台 + 文档审查流 | +| 医疗 | Patient / Encounter / Note / Guideline | EHR / HIS / LIS / PACS / 医保/支付方 | 逼出病例上下文引擎、多系统取数、强 Checkpoint | 病例上下文引擎 + 临床协同流 | +| 工业 | Asset / Order / Alarm / WorkOrder | MES / ERP / SCADA / PLC / CMMS / LIMS | 逼出 OT/IT 连接器、异常事件、控制塔式 Runtime | 现场闭环 + 异常控制塔 | +| 金融 | Customer / Transaction / Alert / Approval | 核心系统 / KYC / AML / LOS / 保司系统 | 逼出审计、留痕、可解释与高风险人审 | 合规与审计化工作流 | +| 物流货代 | Shipment / Booking / Milestone / Document | TMS / WMS / 报关 / 船司 / 邮件 / 财务 | 逼出节点事件、单证工作流、多组织协同 | 履约控制塔 + 单证与异常流 | +| 微商 | Lead / Conversation / Campaign / Distributor | 企微 / SCRM / 商城 / 内容工具 / 分佣系统 | 逼出私域会话、内容工坊、线索状态机 | 私域增长工作流 + 代理协同 | + +--- + +## 4. 这里为什么暂时不讨论“直接做行业包” + +如果六层架构还没有打好，就直接进入行业包，会有两个问题： + +- 容易在应用层堆场景，却没有统一内核 +- 容易做出很多“行业页面”，但连接器协议、对象模型、任务运行时都不稳 + +因此当前更合理的顺序是： + +1. 先用行业样本反推平台需求 +2. 先把六层内核打稳 +3. 再考虑是否固化为行业包 + +也就是说，六个行业现在的作用是： + +**做需求牵引，不做实现承诺。** + +--- + +## 5. 六个行业的差异本质 + +### 5.1 法律 + +深度不在法律知识本身，而在： + +- 事项上下文 +- 条款审查标准 +- 权限与 ethical wall +- redline 与审计轨迹 + +### 5.2 医疗 + +深度不在医学问答本身，而在： + +- 病例上下文连续性 +- 临床责任与人机协同 +- 指南 / 文献循证 +- 生成前校验与生成后审计 + +### 5.3 工业 + +深度不在工业知识本身，而在： + +- OT / IT 融合 +- 异常到工单的闭环 +- 排产、设备、质量的联动 +- 现场时效与安全边界 + +### 5.4 金融 + +深度不在金融术语本身，而在： + +- 高风险场景的人审边界 +- 可解释性 +- 审计和责任链 +- 数据权限与模型治理 + +### 5.5 物流货代 + +深度不在物流知识本身，而在： + +- 节点事件 +- 单证一致性 +- 多组织协同 +- 异常处置与客户同步 + +### 5.6 微商 + +深度不在商品知识本身，而在： + +- 私域会话 +- 内容与转化链路 +- 代理网络 +- 活动节奏与复购运营 + +--- + +## 6. 六个行业的主要 Artifact 形态 + +| 行业 | 典型 Artifact | +|------|----------------| +| 法律 | redline 结果、审查清单、事项摘要、尽调包 | +| 医疗 | 结构化病历、质控提示、循证建议、先审材料、随访计划 | +| 工业 | RCA 报告、工单、质检处置单、排产调整说明、班报 | +| 金融 | KYC 决策包、调查摘要、授信 memo、对账报告、理赔意见 | +| 物流货代 | 报价单、订舱确认、单证包、异常记录、对账单 | +| 微商 | 跟进脚本、内容日历、活动方案、代理培训包、转化复盘 | + +--- + +## 7. 六个行业的主要 Checkpoint / 风险点 + +| 行业 | 关键 Checkpoint | +|------|------------------| +| 法律 | 律师复核、对外发送前确认、签署前校验 | +| 医疗 | 医师确认、病历归档、医嘱与风险提示复核 | +| 工业 | 工单下发前确认、质量 hold、排产重调度确认 | +| 金融 | 合规官复核、信贷审批、理赔审批、报送前确认 | +| 物流货代 | 单证确认、节点异常升级、费用确认、客户通知确认 | +| 微商 | 线索升级、成交前关键确认、代理政策确认、活动上线审核 | + +--- + +## 8. 六个行业反推出的平台刚性能力 + +这六个行业叠加起来，平台至少必须具备以下能力： + +### 8.1 必须有的连接器大类 + +- 文档 / 文件 / 知识库类 +- 办公协同 / 邮件 / IM 类 +- 业务主系统类（CRM / ERP / TMS / LOS / EHR / MES） +- 审批 / 事务 / 工作流类 +- 外部监管 / 研究 / 名单 / 指南 / 公共数据类 +- 财务 / 结算 / 账务类 +- IoT / 设备 / 时序事件类 + +### 8.2 必须有的应用方向 + +- 文档审查与证据链 +- 病例 / 事项 / 客户 / 运单 / 设备等“案例上下文工作台” +- 异常事件处理 +- 人审 Checkpoint +- 产物归档与回放 +- 状态推进与回写 +- 控制塔 / 运行台式可视化 + +--- + +## 9. 一句话定位修正 + +这套平台最终不应被定义为： + +- 通用 AI 助手 +- 通用插件市场 +- 通用工作流拖拽器 + +而应定义为： + +**六层平台内核 + 连接器网络 + 通用对象协议 + 通用工作流运行时。** + +行业只是用来证明这套内核是否足够强，而不是现在就要把六个行业分别产品化。 + +--- + +## 10. 后续文档关系 + +本文档是总览，具体行业样本拆解见： + +- `SY08` 法律行业 +- `SY09` 医疗行业 +- `SY10` 工业行业 +- `SY11` 金融行业 +- `SY12` 物流货代行业 +- `SY13` 微商行业 + +如果继续往六层架构推进，优先应参考： + +- `SY04` 插件化工作流交付平台 +- `SY05` 连接器网络架构 +- `SY14` 行业反推连接器与应用方向矩阵 diff --git a/docs/01_System_Overall/SY08_Legal_Industry_Agent_Pack.md b/docs/01_System_Overall/SY08_Legal_Industry_Agent_Pack.md new file mode 100644 index 0000000..20b144f --- /dev/null +++ b/docs/01_System_Overall/SY08_Legal_Industry_Agent_Pack.md @@ -0,0 +1,202 @@ +# SY08 — 法律行业智能体包（Matter / Contract 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对法律行业的中立判断： + +- 法律行业真正可落地的业务智能体是什么 +- 为什么法律行业不能只做法律问答或法律知识库 +- 法律行业智能体包在本平台中应该如何定义 + +--- + +## 1. 核心结论（一句话） + +法律行业真正成立的，不是“法律问答助手”，而是： + +**以 Matter / Contract 为主对象、以 playbook 为规则核心、以 DMS / CLM / 研究平台为连接器底座的法务操作系统。** + +--- + +## 2. 为什么法律行业不能只做知识库 + +法律是高知识密度行业，但真正的业务问题并不只是“查法条”。 + +真正高频且高价值的工作是： + +- 合同审查 +- 条款比对 +- 尽调与事项推进 +- 诉讼材料整理 +- 监管扫描与法务分流 + +这些工作都依赖： + +- 事项上下文 +- 权限控制 +- 条款审查标准 +- redline 轨迹 +- 证据链 + +因此，法律行业更适合： + +**工作流先行，知识库作为规则与依据底座。** + +--- + +## 3. 法律行业的核心本体 + +最关键的对象不是“文档”本身，而是： + +- `Matter` +- `Contract` +- `Clause` +- `Counterparty` +- `Playbook` +- `Obligation` +- `Approval` +- `Evidence` + +这些对象决定了平台中的： + +- Task 怎么拆 +- Artifact 长什么样 +- Evidence 从哪来 +- Run 里谁负责签字和确认 + +--- + +## 4. 法律行业的关键连接器 + +典型连接器包括： + +- 文档管理系统（DMS） +- 合同生命周期系统（CLM） +- eDiscovery / Litigation 平台 +- 法律研究平台 +- 电子签署平台 +- 邮件 / Office 套件 +- 虚拟数据室 / 并购资料室 + +如果没有这些连接器，平台只能停留在： + +- 上传文档 +- 粗粒度摘要 +- 单份审查 + +很难进入真实法律工作流。 + +--- + +## 5. 真正高价值的法律智能体 + +### 5.1 合同审查智能体 + +职责： + +- 读取合同 +- 对照企业或律所 playbook +- 标出风险点 +- 生成 redline 建议 +- 输出可复核审查清单 + +### 5.2 合同生命周期智能体 + +职责： + +- 起草 +- 审查 +- 签署前校验 +- 义务跟踪 +- 续约与到期提醒 + +### 5.3 事项 Intake / 分流智能体 + +职责： + +- 接收新法务请求 +- 分类事项 +- 分配处理人 +- 生成所需材料清单与回复草稿 + +### 5.4 尽调智能体 + +职责： + +- 扫描数据室 +- 追踪缺失材料 +- 生成尽调摘要与清单 +- 识别高风险条款与缺口 + +### 5.5 诉讼 / 证据整理智能体 + +职责： + +- 拉取案卷与附件 +- 整理案件脉络 +- 生成摘要 +- 准备可审查的文书草稿 + +### 5.6 监管变化跟踪智能体 + +职责： + +- 监测法规、监管变化 +- 映射到合同模板、内部制度、相关事项 +- 生成影响评估 + +--- + +## 6. 法律行业的典型 Artifact + +- 合同 redline 结果 +- 审查清单 +- 条款风险摘要 +- 尽调包 +- 事项摘要 +- 文书草稿 +- 监管变化简报 + +--- + +## 7. 法律行业的主要 Checkpoint + +法律工作不适合全自动闭环，关键人工卡点必须明确： + +- 律师复核 +- 对外发送前确认 +- 签署前最终校验 +- 高风险条款确认 +- 尽调结论确认 + +--- + +## 8. 法律行业智能体包定义 + +一个可用的法律行业包至少包括： + +1. Matter / Contract / Clause / Playbook 本体 +2. DMS / CLM / 研究平台连接器 +3. 合同审查与事项流转模板 +4. 审查清单与风险分级规则 +5. 权限、审计、证据链治理策略 + +--- + +## 9. 对本平台的启发 + +法律行业非常适合验证以下平台能力： + +- Workbench 多窗格工作台 +- Artifact + Evidence 抽屉 +- ConnectorBinding +- Checkpoint +- Replay / Audit + +一句话： + +**法律行业不是“知识库行业”，而是“高规则、高证据、高权限的事项工作流行业”。** diff --git a/docs/01_System_Overall/SY09_Healthcare_Industry_Agent_Pack.md b/docs/01_System_Overall/SY09_Healthcare_Industry_Agent_Pack.md new file mode 100644 index 0000000..91e99ec --- /dev/null +++ b/docs/01_System_Overall/SY09_Healthcare_Industry_Agent_Pack.md @@ -0,0 +1,185 @@ +# SY09 — 医疗行业智能体包（Patient / Encounter 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对医疗行业的判断： + +- 医疗行业真正高价值的智能体是什么 +- 为什么医疗行业不能从“医学问答”理解 AI 升级 +- 医疗行业包在本平台中应如何定义 + +--- + +## 1. 核心结论（一句话） + +医疗行业真正成立的，不是“医学聊天助手”，而是： + +**以 Patient / Encounter 为主对象、以病例上下文引擎为核心、以 EHR / HIS / LIS / PACS 等系统连接为前提的临床协同工作流平台。** + +--- + +## 2. 为什么医疗行业必须连接器先行 + +医疗行业最大的特点不是知识密度高，而是： + +- 数据分散在多个临床系统 +- 工作流跨接诊、文书、检查、医保、随访 +- 法律责任和临床责任极重 +- 输出必须可解释、可追溯、可复核 + +如果不先打通连接器，平台即使能做： + +- 医学问答 +- 病历摘要 +- 文献检索 + +也难以进入真实临床工作流。 + +因此，医疗行业更适合： + +**连接器先行，再做工作流，再叠加知识与循证能力。** + +--- + +## 3. 医疗行业的核心本体 + +关键对象建议为： + +- `Patient` +- `Encounter` +- `Episode` +- `ClinicalNote` +- `Diagnosis` +- `Order` +- `Guideline` +- `Evidence` +- `PriorAuthorization` +- `Claim` +- `FollowUpPlan` + +这些对象共同构成“病例上下文”。 + +--- + +## 4. 医疗行业的关键连接器 + +典型连接器包括： + +- EHR / EMR +- HIS +- LIS +- PACS / 影像系统 +- 医保 / 支付方系统 +- 预约与随访系统 +- 语音文书系统 +- 患者门户 / 消息通道 + +--- + +## 5. 真正高价值的医疗智能体 + +### 5.1 临床文书智能体 + +职责： + +- 采集医患对话 +- 生成结构化病历 +- 回写 EHR + +### 5.2 病历质控智能体 + +职责： + +- 缺项检查 +- 逻辑一致性检查 +- 质量风险提示 + +### 5.3 循证支持智能体 + +职责： + +- 结合指南和文献给出建议 +- 输出证据出处 +- 供医生复核，而非替代决策 + +### 5.4 先审 / 预授权智能体 + +职责： + +- 检查 payer 要求 +- 整理提交材料 +- 跟踪状态 +- 处理拒绝与补件 + +### 5.5 编码 / 理赔 / RCM 智能体 + +职责： + +- 编码辅助 +- 材料整理 +- 拒赔处理 +- 收入周期异常识别 + +### 5.6 院后随访智能体 + +职责： + +- 生成随访计划 +- 跟踪患者状态 +- 输出提醒与风险信号 + +--- + +## 6. 医疗行业的典型 Artifact + +- 结构化病历 +- 质控提示单 +- 循证建议单 +- 先审提交包 +- 理赔材料包 +- 随访计划 +- MDT / 病例讨论材料 + +--- + +## 7. 医疗行业的关键 Checkpoint + +医疗场景必须强制保留人工与制度卡点： + +- 医师确认 +- 病历归档确认 +- 医嘱复核 +- 风险提示确认 +- 先审 / 理赔关键节点确认 + +--- + +## 8. 医疗行业智能体包定义 + +一个可用的医疗行业包至少包括： + +1. Patient / Encounter / Note / Guideline 本体 +2. EHR / HIS / LIS / PACS / 支付方连接器 +3. 病历文书、质控、先审、随访工作流模板 +4. 循证与审计能力 +5. 生成前校验与生成后审计机制 + +--- + +## 9. 对本平台的启发 + +医疗行业会强烈要求平台具备： + +- 共享案例上下文引擎 +- 多连接器取数 +- Evidence 与 citations +- 人机协同 Checkpoint +- 高强度治理与审计 + +一句话： + +**医疗不是“会回答医学问题”就够，而是要把 AI 真正嵌进病例工作流。** diff --git a/docs/01_System_Overall/SY10_Industrial_Industry_Agent_Pack.md b/docs/01_System_Overall/SY10_Industrial_Industry_Agent_Pack.md new file mode 100644 index 0000000..078737c --- /dev/null +++ b/docs/01_System_Overall/SY10_Industrial_Industry_Agent_Pack.md @@ -0,0 +1,178 @@ +# SY10 — 工业行业智能体包（Asset / Order / Alarm 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对工业行业的判断： + +- 工业智能体真正高价值的切入点是什么 +- 为什么工业行业不能按“工业知识问答”理解 +- 工业行业包在本平台中应如何定义 + +--- + +## 1. 核心结论（一句话） + +工业行业真正成立的，不是“工业 Copilot 问答界面”，而是： + +**以 Asset / ProductionOrder / AlarmEvent 为主对象、以 MES / ERP / SCADA / PLC / CMMS 连接为基础、以异常闭环为核心价值的现场工作流平台。** + +--- + +## 2. 为什么工业行业必须连接器先行 + +工业场景最关键的不是知识是否存在，而是： + +- 设备、工艺、排产、质量、维保数据分散 +- OT / IT 系统天然异构 +- 现场异常需要分钟级响应 +- 很多收益来自“缩短发现到处理”的闭环时间 + +因此，工业行业不能只做： + +- 工业知识问答 +- 看板上的解释层 + +而必须先解决： + +- 数据接入 +- 异常到工单的闭环 +- 现场和后台的协同 + +--- + +## 3. 工业行业的核心本体 + +关键对象建议为： + +- `Asset` +- `ProductionOrder` +- `WorkCenter` +- `Operation` +- `AlarmEvent` +- `QualityIssue` +- `MaintenanceWorkOrder` +- `MaterialLot` +- `Schedule` +- `SafetyIncident` + +--- + +## 4. 工业行业的关键连接器 + +典型连接器包括： + +- ERP +- MES +- APS +- SCADA +- PLC / Historian +- CMMS / EAM +- QMS / LIMS +- WMS / 供应链系统 +- EHS / 巡检系统 + +--- + +## 5. 真正高价值的工业智能体 + +### 5.1 停机根因分析智能体 + +职责： + +- 拉取 fault log、MES 事件、历史传感器数据、维修历史 +- 输出 RCA 假设与证据链 +- 草拟维修工单 + +### 5.2 预测性维护智能体 + +职责： + +- 设备健康监控 +- 风险预警 +- 维保计划与备件建议 + +### 5.3 智能排产 / 重排产智能体 + +职责： + +- 处理插单、缺料、设备异常 +- 快速重算排程 +- 输出受影响订单和建议动作 + +### 5.4 质量处置智能体 + +职责： + +- 缺陷识别 +- 工艺参数关联 +- 生成 hold / 返工 / CAPA 建议 + +### 5.5 供应链异常处理智能体 + +职责： + +- 催料 +- 发运异常识别 +- 替代料与交期影响分析 + +### 5.6 EHS 巡检智能体 + +职责： + +- 巡检记录 +- 风险项跟踪 +- 整改任务闭环 + +--- + +## 6. 工业行业的典型 Artifact + +- RCA 报告 +- 维修工单 +- 质量处置单 +- 排程调整说明 +- 班报 / 日报 +- EHS 整改记录 + +--- + +## 7. 工业行业的关键 Checkpoint + +工业行业必须保留清晰的人审和安全边界： + +- 工单下发确认 +- 质量 hold 确认 +- 排产调整确认 +- EHS 风险确认 +- 不应轻易让 AI 直接接管安全关键控制回路 + +--- + +## 8. 工业行业智能体包定义 + +一个可用的工业行业包至少包括： + +1. Asset / Alarm / WorkOrder / QualityIssue 本体 +2. MES / ERP / PLC / SCADA / CMMS 连接器 +3. 异常处置、维保、排产、质量工作流模板 +4. 工单与证据链机制 +5. 现场安全与权限治理策略 + +--- + +## 9. 对本平台的启发 + +工业行业会倒逼平台加强以下能力： + +- 多源时序与事件接入 +- 异常控制塔式 Run UI +- 工单与审批闭环 +- 现场数据与业务数据的统一语义绑定 + +一句话： + +**工业行业的 AI 价值不在“看懂工业知识”，而在“把异常闭环变短”。** diff --git a/docs/01_System_Overall/SY11_Financial_Industry_Agent_Pack.md b/docs/01_System_Overall/SY11_Financial_Industry_Agent_Pack.md new file mode 100644 index 0000000..8ba98f7 --- /dev/null +++ b/docs/01_System_Overall/SY11_Financial_Industry_Agent_Pack.md @@ -0,0 +1,177 @@ +# SY11 — 金融行业智能体包（Customer / Transaction / Alert 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对金融行业的判断： + +- 金融智能体真正高价值的应用形态是什么 +- 为什么金融行业不能按“金融助手”理解 +- 金融行业包在本平台中应如何定义 + +--- + +## 1. 核心结论（一句话） + +金融行业真正成立的，不是“更聪明的金融问答”，而是： + +**以 Customer / Transaction / Alert / Approval 为主对象、以核心系统连接与审计留痕为底座、以人机协同与责任可追溯为前提的高风险工作流平台。** + +--- + +## 2. 为什么金融行业必须连接器先行 + +金融行业最核心的不是知识能否回答，而是： + +- 关键业务数据主要在核心业务系统中 +- 高风险场景必须可解释、可追溯 +- 人工审核与责任链不能消失 +- 合规要求远高于普通行业 + +因此，金融行业不适合从纯知识库切入。 +更适合： + +**连接器先行 + 强治理工作流。** + +--- + +## 3. 金融行业的核心本体 + +关键对象建议为： + +- `Customer` +- `Entity` +- `Account` +- `Transaction` +- `KYCFile` +- `Alert` +- `Case` +- `CreditMemo` +- `Claim` +- `Policy` +- `Approval` +- `LedgerEntry` + +--- + +## 4. 金融行业的关键连接器 + +典型连接器包括： + +- 核心银行 / 核心保险系统 +- KYC / 身份认证系统 +- AML / 制裁名单 / 外部尽调数据源 +- 贷款审批 / 授信系统 +- 理赔系统 +- 总账 / 财务 / 对账系统 +- OA / 审批 / 邮件系统 + +--- + +## 5. 真正高价值的金融智能体 + +### 5.1 KYC / 尽调智能体 + +职责： + +- 收集资料 +- 字段核验 +- 名单筛查 +- 缺口补件 +- 形成决策包供人工确认 + +### 5.2 AML / 可疑交易调查智能体 + +职责： + +- 拉流水、身份、外部名单、舆情 +- 生成调查摘要 +- 草拟报送材料 + +### 5.3 授信 / 贷款审批辅助智能体 + +职责： + +- 整理申请资料 +- 校验一致性 +- 生成授信 memo +- 路由人工审批 + +### 5.4 理赔智能体 + +职责： + +- 收集保单与理赔材料 +- 规则校验 +- 形成理赔建议与补件要求 + +### 5.5 对账 / 月结智能体 + +职责： + +- 发现差异 +- 追踪根因 +- 生成 close checklist 与审计说明 + +### 5.6 监管变化 / 制度解读智能体 + +职责： + +- 监测监管变化 +- 映射内部制度与流程 +- 输出整改建议 + +--- + +## 6. 金融行业的典型 Artifact + +- KYC 决策包 +- 调查摘要 +- SAR / 报送材料草稿 +- 授信 memo +- 理赔意见单 +- 对账报告 +- 合规变化简报 + +--- + +## 7. 金融行业的关键 Checkpoint + +金融行业的高风险场景必须保留人工与制度卡点： + +- 合规官复核 +- 授信审批 +- 理赔审批 +- 报送前确认 +- 高风险例外审批 + +--- + +## 8. 金融行业智能体包定义 + +一个可用的金融行业包至少包括： + +1. Customer / Transaction / Alert / Approval 本体 +2. 核心系统、KYC、AML、授信、理赔连接器 +3. KYC、AML、授信、对账、理赔工作流模板 +4. 审计与可解释机制 +5. 高风险场景的人机协同治理策略 + +--- + +## 9. 对本平台的启发 + +金融行业会强烈要求平台具备： + +- 可解释性 +- 全链路审计 +- 人工 Checkpoint +- 权限与责任边界 +- Connector + Workflow 的强绑定 + +一句话： + +**金融智能体不是为了取消人工审核，而是为了让人工审核建立在更完整、更可追溯的工作流之上。** diff --git a/docs/01_System_Overall/SY12_Logistics_Freight_Forwarding_Industry_Agent_Pack.md b/docs/01_System_Overall/SY12_Logistics_Freight_Forwarding_Industry_Agent_Pack.md new file mode 100644 index 0000000..d768d09 --- /dev/null +++ b/docs/01_System_Overall/SY12_Logistics_Freight_Forwarding_Industry_Agent_Pack.md @@ -0,0 +1,168 @@ +# SY12 — 物流货代行业智能体包（Shipment / Booking / Milestone 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对物流货代行业的判断： + +- 为什么物流货代非常适合工作流平台 +- 这个行业真正高价值的智能体是什么 +- 物流货代行业包在本平台中应如何定义 + +--- + +## 1. 核心结论（一句话） + +物流货代行业真正成立的，不是“查单助手”，而是： + +**以 Shipment / Booking / Milestone / Document 为主对象、以节点事件和单证协同为主线、以跨组织连接器网络为前提的履约控制塔平台。** + +--- + +## 2. 为什么物流货代必须连接器先行 + +物流货代最核心的不是知识是否可答，而是： + +- 关键状态分散在多个系统与合作方渠道中 +- 大量关键信息存在邮件、Excel、扫描件、群消息中 +- 履约是强事件驱动业务 +- 异常处理决定客户体验与利润空间 + +如果没有连接器网络，平台很难从“看板”走向“闭环执行”。 + +--- + +## 3. 物流货代行业的核心本体 + +关键对象建议为： + +- `Shipment` +- `Booking` +- `Container` +- `Order` +- `Milestone` +- `Document` +- `Exception` +- `RateQuote` +- `Partner` +- `Invoice` +- `Reconciliation` + +--- + +## 4. 物流货代行业的关键连接器 + +典型连接器包括： + +- TMS +- WMS +- 货代业务系统 +- 船司 / 航司 / 港口节点接口 +- 报关系统 +- GPS / IoT / 在途跟踪平台 +- 邮件 / 企业微信 / WhatsApp +- ERP / 财务 / 开票系统 +- Excel / PDF / 网盘 + +--- + +## 5. 真正高价值的物流货代智能体 + +### 5.1 询报价智能体 + +职责： + +- 汇总运价 +- 匹配航线与舱位规则 +- 输出报价方案与毛利测算 + +### 5.2 订舱编排智能体 + +职责： + +- 从委托到订舱、拖车、报关、提单资料准备进行编排 +- 跟踪关键前置动作 + +### 5.3 单证审核智能体 + +职责： + +- 校验提单、装箱单、发票、报关资料的一致性 +- 标记缺失与风险字段 + +### 5.4 节点跟踪智能体 + +职责： + +- 跟踪 ETA / ETD / 截关 / 进港 / 到港 / 签收 +- 生成状态更新与异常预警 + +### 5.5 异常处置智能体 + +职责： + +- 处理延误、甩柜、改单、查验、缺件、费用异常 +- 自动拉齐责任方并生成处置任务 + +### 5.6 对账结算智能体 + +职责： + +- 应收应付核对 +- 异常账单识别 +- 毛利归因 + +--- + +## 6. 物流货代行业的典型 Artifact + +- 报价单 +- 订舱确认 +- 单证包 +- 异常处置记录 +- 节点状态报告 +- 对账单 +- 利润分析说明 + +--- + +## 7. 物流货代行业的关键 Checkpoint + +物流货代行业的关键人工卡点通常包括： + +- 单证确认 +- 异常升级确认 +- 费用确认 +- 对外客户通知确认 +- 高风险节点人工接管 + +--- + +## 8. 物流货代行业智能体包定义 + +一个可用的物流货代行业包至少包括： + +1. Shipment / Booking / Milestone / Document 本体 +2. TMS / WMS / 报关 / 船司 / 财务连接器 +3. 报价、订舱、单证、节点跟踪、异常处理、对账工作流模板 +4. 单证与证据链能力 +5. 多组织协同与客户通知策略 + +--- + +## 9. 对本平台的启发 + +物流货代行业非常适合验证平台的以下能力： + +- 事件驱动 Run +- Artifact / Evidence 抽屉 +- 多连接器聚合 +- 异常控制塔式 UI +- 对外回写与通知能力 + +一句话： + +**物流货代不是知识查询业务，而是事件、单证、异常、协同驱动的履约业务。** diff --git a/docs/01_System_Overall/SY13_Social_Commerce_Microbusiness_Industry_Agent_Pack.md b/docs/01_System_Overall/SY13_Social_Commerce_Microbusiness_Industry_Agent_Pack.md new file mode 100644 index 0000000..2af00df --- /dev/null +++ b/docs/01_System_Overall/SY13_Social_Commerce_Microbusiness_Industry_Agent_Pack.md @@ -0,0 +1,164 @@ +# SY13 — 微商行业智能体包（Lead / Conversation / Campaign 驱动） + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档用于沉淀对微商行业的判断： + +- 为什么微商行业不能只理解为“会话机器人” +- 这个行业真正高价值的智能体是什么 +- 微商行业包在本平台中应如何定义 + +--- + +## 1. 核心结论（一句话） + +微商行业真正成立的，不是“自动回复机器人”，而是： + +**以 Lead / Conversation / Campaign / Distributor 为主对象、以私域转化和代理协同为主线、以内容工坊和运营节奏编排为核心的增长工作流平台。** + +--- + +## 2. 为什么微商行业更适合工作流先行 + +微商行业虽然知识和素材很多，但真正的关键不在“答案”，而在： + +- 私聊跟进节奏 +- 线索分层与转化推进 +- 内容生产和分发 +- 代理赋能和协同 +- 复购与裂变运营 + +因此，微商行业更适合： + +**工作流先行，内容/知识库作为素材底座，连接器作为增长与成交闭环增强。** + +--- + +## 3. 微商行业的核心本体 + +关键对象建议为： + +- `Lead` +- `CustomerProfile` +- `Conversation` +- `ContentAsset` +- `Campaign` +- `AgentDistributor` +- `Order` +- `FollowUpTask` +- `Community` +- `ProductBundle` +- `Proof` + +--- + +## 4. 微商行业的关键连接器 + +典型连接器包括： + +- 企业微信 / 私域工具 +- SCRM +- 小程序商城 / 订单系统 +- 支付 / 财务 / 分佣系统 +- 素材库 / 图片视频工具 +- 表单与社群运营工具 +- 直播 / 短视频 / 内容分发平台 + +--- + +## 5. 真正高价值的微商智能体 + +### 5.1 私聊转化智能体 + +职责： + +- 结合客户画像、历史对话、意向阶段 +- 输出下一轮跟进建议与脚本 + +### 5.2 内容运营智能体 + +职责： + +- 生成朋友圈、社群、活动内容 +- 形成日更与活动节奏 + +### 5.3 线索分层智能体 + +职责： + +- 识别高意向、犹豫、沉默、复购、代理潜力用户 +- 路由后续跟进动作 + +### 5.4 成交跟单智能体 + +职责： + +- 从咨询、下单、支付到复购提醒形成任务链 + +### 5.5 代理赋能智能体 + +职责： + +- 为代理生成话术、素材包、活动说明、培训任务 + +### 5.6 售后稳客智能体 + +职责： + +- 做评价引导、复购提醒、流失预警、裂变推荐 + +--- + +## 6. 微商行业的典型 Artifact + +- 跟进脚本 +- 内容日历 +- 活动方案 +- 素材包 +- 代理培训包 +- 客户分层清单 +- 成交复盘报告 + +--- + +## 7. 微商行业的关键 Checkpoint + +微商行业虽然不如金融医疗强监管，但关键卡点仍然存在： + +- 高价值客户升级确认 +- 关键活动上线审核 +- 代理政策确认 +- 成交前关键话术确认 +- 敏感内容与合规素材审核 + +--- + +## 8. 微商行业智能体包定义 + +一个可用的微商行业包至少包括： + +1. Lead / Conversation / Campaign / Distributor 本体 +2. 私域、商城、分佣、内容工具连接器 +3. 跟进、活动、复购、代理赋能工作流模板 +4. 素材与内容资产底座 +5. 运营节奏与角色协同策略 + +--- + +## 9. 对本平台的启发 + +微商行业会要求平台在以下方向更强： + +- 线索状态机 +- 内容工坊与流程的结合 +- 会话上下文与任务推进结合 +- 代理网络协同 +- 复购 / 裂变工作流 + +一句话： + +**微商行业不是“聊天更自然”就够，而是要把内容、转化、代理和成交链路编排起来。** diff --git a/docs/01_System_Overall/SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md b/docs/01_System_Overall/SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md new file mode 100644 index 0000000..67ca77a --- /dev/null +++ b/docs/01_System_Overall/SY14_Industry_Derived_Connector_And_Application_Requirement_Matrix.md @@ -0,0 +1,360 @@ +# SY14 — 从六个行业反推连接器与应用方向矩阵 + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文档专门服务当前阶段的核心目标： + +**六层架构还没打稳时，先借六个行业反推平台必须具备的连接器类型和应用方向。** + +这不是行业化路线图，也不是行业优先级文档。 +它是六层平台内核的需求输入文档。 + +--- + +## 1. 核心结论（一句话） + +引入法律、医疗、工业、金融、物流货代、微商六个行业，当前最重要的价值是： + +**逼出平台必须支持的连接器大类、案例上下文类型、工作流样式与 UI 形态。** + +--- + +## 2. 先看总矩阵 + +| 行业 | 平台必须支持的连接器 | 平台必须支持的应用方向 | +|------|----------------------|------------------------| +| 法律 | DMS / CLM / eDiscovery / 法律研究 / Office / eSign | 文档审查、事项流转、条款比对、尽调、监管扫描 | +| 医疗 | EHR / HIS / LIS / PACS / 支付方 / 随访通道 | 病例上下文、临床文书、病历质控、先审、随访 | +| 工业 | ERP / MES / APS / SCADA / PLC / Historian / CMMS / QMS | 异常控制塔、停机 RCA、工单闭环、排产重调度、质量处置 | +| 金融 | 核心系统 / KYC / AML / LOS / 保司理赔 / 总账 / 审批系统 | KYC、AML 调查、授信辅助、理赔辅助、对账、监管映射 | +| 物流货代 | TMS / WMS / 报关 / 船司节点 / 邮件 / 财务 / 文件系统 | 履约控制塔、节点跟踪、单证审核、异常处置、对账结算 | +| 微商 | 企微 / SCRM / 商城 / 内容工具 / 分佣 / 表单工具 | 线索推进、内容编排、私聊转化、代理赋能、复购运营 | + +--- + +## 3. 反推出来的连接器大类 + +六个行业叠加后，可以比较明确地看出平台必须支持的连接器大类。 + +### 3.1 文档与知识类连接器 + +来源行业： + +- 法律 +- 医疗 +- 物流货代 +- 金融 + +典型对象： + +- 文档库 +- 文件系统 +- 网盘 +- 合同库 +- 资料室 +- 指南 / 研究库 + +平台需求： + +- 统一读取 +- 权限透传 +- 结构化抽取 +- 引用与证据链 + +### 3.2 办公协同与消息类连接器 + +来源行业： + +- 法律 +- 物流货代 +- 微商 +- 金融 + +典型对象： + +- 邮件 +- IM +- 企业微信 / WhatsApp / 短信 +- Office 工具 + +平台需求： + +- 收取上下文 +- 发送通知 +- 生成草稿 +- 形成任务触发与回写 + +### 3.3 业务主系统类连接器 + +来源行业： + +- 医疗 +- 工业 +- 金融 +- 物流货代 +- 微商 + +典型对象： + +- CRM +- ERP +- TMS +- EHR / HIS +- MES +- LOS +- 核心银行 / 核心保司系统 + +平台需求： + +- 结构化取数 +- 结构化回写 +- 状态同步 +- 权限与审计 + +### 3.4 审批 / 工作流类连接器 + +来源行业： + +- 法律 +- 金融 +- 医疗 +- 物流货代 + +平台需求： + +- 触发审批 +- 等待结果 +- 作为 Checkpoint 回流 Run + +### 3.5 外部规则 / 研究 / 公共数据类连接器 + +来源行业： + +- 法律 +- 医疗 +- 金融 + +平台需求： + +- 拉法规、指南、名单、研究资料 +- 形成 Evidence +- 参与决策与审查 + +### 3.6 财务 / 结算类连接器 + +来源行业： + +- 金融 +- 物流货代 +- 微商 +- 工业 + +平台需求： + +- 账单 +- 对账 +- 应收应付 +- 回款状态 +- 毛利归因 + +### 3.7 IoT / 设备 / 时序事件类连接器 + +来源行业： + +- 工业 +- 物流货代（部分 GPS / 在途） + +平台需求： + +- 实时事件流 +- 告警与节点状态 +- 事件到工作流触发 + +--- + +## 4. 反推出来的应用方向 + +这六个行业叠加后，平台在应用层至少要支持以下方向。 + +### 4.1 案例上下文工作台 + +这是最重要的方向。 +每个行业都有自己的 case： + +- 法律：Matter +- 医疗：Encounter / Episode +- 工业：Incident / Shift / Asset Context +- 金融：Case / Customer Context +- 物流货代：Shipment / Booking +- 微商：Lead / Conversation + +平台需求： + +- 一个 Run 必须围绕“案例上下文”展开 +- 所有 Task / Artifact / Evidence 都挂在这个上下文上 + +### 4.2 文档审查与证据链 + +来源行业： + +- 法律 +- 医疗 +- 金融 +- 物流货代 + +平台需求： + +- 文档对比 +- 审查清单 +- 引用链 +- 审计与归档 + +### 4.3 异常控制塔 + +来源行业： + +- 工业 +- 物流货代 +- 金融（Alert / Case） + +平台需求： + +- 事件流 +- 状态机 +- 升级 +- 人工接管 +- 处置回放 + +### 4.4 人审 Checkpoint + +来源行业： + +- 医疗 +- 金融 +- 法律 +- 工业 + +平台需求： + +- 平台原生支持 Checkpoint +- 不把人工复核当异常分支，而是当一等工作流节点 + +### 4.5 产物归档与回写 + +来源行业： + +- 全行业 + +平台需求： + +- 统一 Artifact 协议 +- 可回写原系统 +- 可回放 +- 可追责 + +### 4.6 内容 / 脚本 / 方案工坊 + +来源行业： + +- 微商 +- 法律 +- 金融 +- 培训类场景 + +平台需求： + +- 内容模板 +- 方案生成 +- 变量映射 +- 产物版本化 + +--- + +## 5. 反推到六层架构的具体要求 + +### 5.1 对 L1 的要求 + +- 连接器凭据管理 +- 权限与 RBAC +- 审计日志 +- 健康检查 +- 限流与重试 + +### 5.2 对 L2 的要求 + +- 文档 / 结构化数据接入 +- 事件流接入 +- 证据提取 +- 来源快照 + +### 5.3 对 L3 的要求 + +- 统一案例上下文模型 +- ExternalReference +- ConnectorBinding +- Evidence / Artifact / Task 关系 + +### 5.4 对 L4 的要求 + +- 连接器动作标准化 +- 所有能力统一返回： + +```ts +{ + outputs: {}, + artifacts: [], + citations: [], + risks: [] +} +``` + +### 5.5 对 L5 的要求 + +- 事件触发 Run +- Checkpoint +- 回写 +- 异常升级 +- Replay + +### 5.6 对 L6 的要求 + +- Run：案例上下文工作台 / 控制塔 +- Studio：连接器节点 + 字段映射 + 测试 +- Governance：连接器治理、日志、权限、重试 + +--- + +## 6. 当前阶段最值得先定的不是行业，而是平台通用件 + +结合六个行业，当前阶段应优先明确的通用件如下： + +1. `ConnectorDefinition / ConnectorInstance / ConnectorBinding` +2. `ExternalReference` +3. `CaseContext`（通用案例上下文抽象） +4. `Artifact / Evidence / Task` 统一协议 +5. `Checkpoint` +6. `ConnectorNode` 在 Studio 中的产品形态 +7. `Connector Governance Console` 在 Governance 中的产品形态 + +--- + +## 7. 最终结论 + +当前阶段不应问： + +- 先做法律还是金融 +- 先做哪个行业包 + +而应问： + +- 六个行业共同要求我们必须先支持哪些连接器 +- 六个行业共同要求我们必须先支持哪些工作流形态 +- 哪些能力如果不先做，行业文档再多也只是概念堆叠 + +一句话收束： + +**行业只是样本，六层内核才是主线。** diff --git a/docs/01_System_Overall/SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md b/docs/01_System_Overall/SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md new file mode 100644 index 0000000..b948332 --- /dev/null +++ b/docs/01_System_Overall/SY15_Terminology_Benchmark_Ontology_Semantic_Layer_Object_Layer.md @@ -0,0 +1,460 @@ +# SY15 — 本体层 / 语义层 / 对象层 命名基准研究 + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文用于回答一个非常具体的问题： + +- `本体层` 这个词有没有理论基础？ +- 企业级平台里有没有公开采用类似命名？ +- 星邺汇捷到底有没有用这一类概念？ +- 对本仓库当前六层架构来说，`本体层`、`语义层`、`对象层` 哪个更合适？ + +本文不是泛泛讨论术语，而是结合： + +- 知识工程与信息系统中的 `ontology` +- Palantir、Microsoft、Salesforce 等官方表述 +- 星邺汇捷公开官网与公开专利/报道可见信息 + +来给出一个更稳的命名判断。 + +--- + +## 1. 核心结论 + +### 1.1 `本体` 这个词本身是成立的 + +`Ontology` 在知识工程领域有成熟理论基础，经典定义来自： + +- Gruber：`an explicit specification of a conceptualization` +- Borst / Studer：进一步强调 `formal`、`shared` + +所以从理论上说，把企业统一语义层叫做 `本体层`，不是乱用高级词。 + +### 1.2 企业产品里也确实有人公开使用 `Ontology` + +公开可验证的代表： + +- **Palantir**：直接把 `Ontology` 作为 Foundry 的核心平台概念，对外明确表述为企业的 `operational layer` / `digital twin` +- **Microsoft Fabric IQ**：已经公开使用 `ontology (preview)`，并把它和 `semantic model` 区分开 +- **星邺汇捷**：官网产品页已经明确出现 **`本体大脑`** 这一表述 + +所以，如果问题是“企业 AI 平台里有没有人公开用这一套词”，答案是：**有，而且不止一家。** + +### 1.3 但 `本体层` 不一定是当前阶段最稳的工程命名 + +虽然 `本体层` 理论正确，但它容易让项目显得已经走到了更重的知识工程形态，例如： + +- 形式化建模 +- 机器可验证约束 +- 语义推理 +- 统一词汇体系 +- 跨系统严格映射 + +如果当前阶段主要落地的是： + +- `Task / Run / Artifact / Evidence / ConnectorBinding` 等共享对象 +- 对象关系 +- 状态机 +- 字段约束 +- 插件/连接器交换协议 + +那么只叫 `本体层` 会略显超前。 + +### 1.4 对本项目更稳的建议 + +建议采用双层口径： + +- **架构目标语**：`本体层（Ontology Layer）` +- **当前工程语**：`共享对象层` 或 `语义对象层` + +一句话说： + +**目标形态是本体层，当前落地形态是共享对象层。** + +--- + +## 2. 理论基础：为什么 `Ontology` 可以译为 `本体` + +### 2.1 学术与工程上的常见定义 + +知识工程领域常见定义链如下： + +- Gruber：对概念化的显式说明 +- Borst：补上形式化和共享 +- Studer 等：形成常见表述 + `a formal, explicit specification of a shared conceptualization` + +对应到工程上，严格意义上的本体通常包含： + +- 概念/类 +- 属性 +- 关系 +- 约束 +- 共享语义 +- 形式化表达 + +它比普通数据库 schema 更强调： + +- 语义一致性 +- 跨系统互操作 +- 业务含义显式化 + +### 2.2 它和普通 schema / model 的区别 + +如果一个系统只有： + +- 表结构 +- 字段 +- CRUD + +那通常还只是： + +- schema +- data model +- entity model + +如果它进一步承担了： + +- 统一对象定义 +- 对象关系与状态约束 +- 跨系统语义映射 +- 面向工作流与动作的共享交换协议 + +才开始接近 `ontology` 在企业系统中的实际用法。 + +### 2.3 中文语境中的译法 + +中文技术语境中，`ontology` 长期被译为 `本体` 或 `本体论`，并非临时造词。 +在计算机、语义网、知识工程文献中，`本体` 是可以成立的标准技术译法。 + +--- + +## 3. 厂商对照：谁真的在用 `本体/ontology` + +## 3.1 Palantir：最强势、最彻底的 `Ontology` 路线 + +Palantir 官方把 `Ontology` 直接定义为平台核心： + +- 是组织的 `operational layer` +- 是组织的 `digital twin` +- 把数据、模型、流程映射成： + - Objects + - Properties + - Links + - Actions + - Functions + +它不是把 ontology 当作一个附属模块，而是把它当成： + +**连接数据、分析、操作系统、应用和 AI 的统一业务表示层。** + +这点非常关键，因为它说明： + +- `Ontology` 在企业产品里可以不是学术饰词 +- 它可以直接成为运行时平台骨架 + +Palantir 相关公开资料： + +- https://www.palantir.com/explore/platforms/foundry/ontology +- https://www.palantir.com/docs/foundry/ontology/overview +- https://www.palantir.com/docs/foundry/ontology/core-concepts +- https://www.palantir.com/docs/foundry/ontology-sdk/overview + +### 对我们最有参考价值的点 + +Palantir 不是只做“语义描述”，而是把下列东西一起放进 `Ontology`： + +- 对象 +- 关系 +- 权限 +- 动作 +- 写回 +- 工作流触发 +- 应用开发 SDK + +这意味着它的 ontology 已经不是狭义知识图谱，而是： + +**语义层 + 操作层 + 应用层的统一底座。** + +--- + +## 3.2 Microsoft：同时保留 `semantic model` 和 `ontology` + +Microsoft 最近的公开表述很有参考价值，因为它比 Palantir 更清楚地区分了两个概念： + +- `semantic model` +- `ontology` + +Fabric IQ 的公开结构是： + +- `semantic model`：偏分析、指标、维度、层级 +- `ontology (preview)`：偏企业实体、关系、规则、动作 + +这说明微软的口径其实在告诉我们： + +**`ontology` 不是 `semantic model` 的同义词，而是更偏运行时业务对象与动作语义。** + +Microsoft 公开资料： + +- https://www.microsoft.com/en-us/microsoft-fabric/features/iq +- https://learn.microsoft.com/en-nz/fabric/iq/overview +- https://learn.microsoft.com/da-dk/azure/foundry/agents/how-to/tools/fabric-iq + +### 对我们最有参考价值的点 + +微软这套口径很适合借鉴： + +- 分析和 BI 层：`semantic model` +- 企业动作和业务实体层：`ontology` + +这对我们当前六层架构是个提醒： + +- 如果只是指标、数据分析、NL2SQL/NL2DAX，一般更接近 `语义层` +- 如果已经定义 `Task / Artifact / Evidence / Action / Rule / ConnectorBinding`，就开始接近 `ontology` + +--- + +## 3.3 Salesforce：更偏 `semantic layer / semantic model` + +Salesforce 当前更偏向使用： + +- `semantic layer` +- `Semantic Data Model` +- `Tableau Semantics` + +其核心主张是： + +- 把原始数据翻译成业务语言 +- 保持指标定义一致 +- 服务 AI agents 与 BI 的统一理解 + +Salesforce 的表达强烈偏向： + +**共享业务语义与治理的一致性** + +但相较于 Palantir 和 Microsoft 的 ontology 表达，它对“动作/写回/对象操作运行时”的公开强调略弱。 + +公开资料： + +- https://www.salesforce.com/blog/what-is-tableau-semantics +- https://www.salesforce.com/blog/semantic-layer-ai-agents-data-360 +- https://www.salesforce.com/news/stories/trusted-ai-foundation-agentic-enterprise/ + +### 对我们最有参考价值的点 + +Salesforce 提醒我们： + +如果重点在： + +- 指标定义一致 +- 数据翻译为业务语言 +- 给 BI 与 agent 统一语义 + +那 `语义层` 往往比 `本体层` 更容易被市场理解。 + +--- + +## 3.4 星邺汇捷：公开已出现 `本体大脑` + +这是本次搜索里最重要的新发现。 + +星邺汇捷公开官网产品页已经明确写出： + +- **“星智平台是基于本体大脑的组织级深度推理与执行平台”** +- **“超级智能体通过接入本体大脑获取企业专有知识，并调用组织内部各类业务工具，实现从知识推理到行动执行的全链路智能化”** + +这说明： + +1. 他们公开用了 `本体` 相关命名 +2. 而且不是学术说明，而是产品级主概念 +3. 这个概念被放在： + - 企业专有知识 + - 工具调用 + - 深度推理 + - 执行动作 + 的统一中枢位置 + +星邺汇捷公开资料： + +- 官网产品页： + http://www.staryea.com/product/technology.html +- 官网介绍页： + http://www.staryea.com/about.html + +### 但要注意一个细节 + +星邺汇捷官网 `about` 页仍然主要强调： + +- 知识图谱 +- 融合 RAG +- 多智能体 +- 多模态 + +这说明它对外有两层表达： + +1. **技术架构层**：知识图谱 / RAG / 多智能体 +2. **产品心智层**：本体大脑 + +换句话说： + +**它确实用了“本体”概念，但公开可见材料里还看不出它是否采用了严格知识工程意义上的 ontology engineering 实现。** + +### 从公开专利和报道能推到什么 + +可见公开线索包括： + +- `一种多源数据联合空间的建模方法` +- `一种客服智能体及其实现方法` + +这些线索说明它确实在做： + +- 多源数据统一建模 +- 业务意图映射 +- 业务流程自动化 + +但从当前公开摘要，还不足以证明它已经公开形成了一套像 Palantir 那样结构完整、定义清晰的 `Ontology` 体系。 + +因此，中立判断应当是： + +**星邺汇捷已经公开使用了“本体大脑”作为产品概念；但从公开资料看，更像“以知识图谱/RAG/多智能体为底座的统一业务语义与执行中枢”，而不是已经完整公开了严谨的 ontology 方法论。** + +--- + +## 4. 命名对照表 + +| 机构 | 官方主词 | 公开强调重点 | 更偏哪种层 | +|------|-----------|--------------|------------| +| Palantir | `Ontology` | 对象、关系、动作、函数、写回、应用、治理 | 强本体层 | +| Microsoft Fabric IQ | `ontology` + `semantic model` | ontology 负责实体/关系/规则/动作，semantic model 负责分析语义 | 本体层与语义层双轨 | +| Salesforce | `semantic layer` / `semantic model` | 业务语言、指标一致性、AI/BI 共享语义 | 强语义层 | +| 星邺汇捷 | `本体大脑` + 知识图谱/RAG/多智能体 | 企业知识、推理、工具调用、执行闭环 | 接近本体层，但公开定义未完全展开 | + +--- + +## 5. 对本项目的命名影响 + +## 5.1 如果继续叫 `本体层` + +优点： + +- 理论上站得住 +- 与 Palantir / Microsoft / 星邺汇捷这类路线对齐 +- 能表达“不是普通数据库 schema” +- 能表达“这是平台统一业务语义层” + +风险： + +- 容易让读者误以为我们已经做了很完整的 ontology engineering +- 容易让工程团队联想到过重的语义网/OWL 路线 +- 在当前阶段可能比实际落地状态超前一步 + +## 5.2 如果改叫 `对象层` + +优点： + +- 工程团队理解门槛低 +- 容易接受 +- 贴近当前 `Task / Artifact / Evidence / Run` 这类建模实践 + +风险： + +- 太宽泛 +- 容易被理解成普通 entity/model 层 +- 不能凸显“跨连接器、跨插件、跨工作流共享语义”的意图 + +## 5.3 如果改叫 `共享对象层` + +优点： + +- 比 `对象层` 更准确 +- 能强调跨系统共享 +- 既保留工程落地感，又不完全丢掉语义层含义 + +风险： + +- 理论色彩比 `本体层` 弱 +- 对外品牌感不如 `本体层` 强 + +## 5.4 如果改叫 `语义对象层` + +优点： + +- 比 `共享对象层` 多了一层语义意味 +- 比 `本体层` 更不吓人 +- 能较好表达“对象 + 关系 + 状态 + 约束” + +风险： + +- 名字略长 +- 传播性不如 `本体层` + +--- + +## 6. 最终建议 + +### 6.1 架构目标层面的建议 + +如果文档是在讲平台最终目标，保留： + +- `本体层（Ontology Layer）` + +是可以成立的。 + +### 6.2 当前实现层面的建议 + +如果文档是在讲当前版本的工程落地，建议改成： + +- `共享对象层` + +或： + +- `语义对象层` + +### 6.3 最稳妥的双层表述 + +建议统一成这句话： + +**L3 当前落地为共享对象层，其目标形态是本体层（Ontology Layer）。** + +这样可以同时满足： + +- 理论正确 +- 工程稳妥 +- 对外叙事不过度拔高 + +--- + +## 7. 对当前仓库的直接建议 + +如果后续要统一修正文档，我建议： + +1. 在 `SY04` 里把原 `本体与索引层` 改成： + - `共享对象与索引层` +2. 在同一节正文中补一句： + - `该层的目标形态是平台级本体层（Ontology Layer），当前优先以共享对象模型、关系、状态约束和交换协议落地。` +3. 在 `SY05 / SY14` 中保持同样口径，避免术语飘忽 + +--- + +## 8. 参考资料 + +- Gruber 对 ontology 的经典定义： + https://tomgruber.org/writing/definition-of-ontology/ +- Palantir Foundry Ontology： + https://www.palantir.com/explore/platforms/foundry/ontology + https://www.palantir.com/docs/foundry/ontology/overview + https://www.palantir.com/docs/foundry/ontology/core-concepts +- Microsoft Fabric IQ： + https://www.microsoft.com/en-us/microsoft-fabric/features/iq + https://learn.microsoft.com/en-nz/fabric/iq/overview +- Salesforce Tableau Semantics： + https://www.salesforce.com/blog/what-is-tableau-semantics + https://www.salesforce.com/blog/semantic-layer-ai-agents-data-360 +- 星邺汇捷公开材料： + http://www.staryea.com/about.html + http://www.staryea.com/product/technology.html + https://www.163.com/dy/article/L4A3DF7U0519QIKK.html diff --git a/docs/01_System_Overall/SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md b/docs/01_System_Overall/SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md new file mode 100644 index 0000000..103fc84 --- /dev/null +++ b/docs/01_System_Overall/SY16_Ontology_Generalizes_Data_Actions_And_Workflows.md @@ -0,0 +1,505 @@ +# SY16 — 本体如何让数据、动作、工作流一般化 + +> 版本：V1.0 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文用于回答一个非常具体的问题： + +**本体层，是否本质上是在让智能体的数据和动作“一般化”？** + +结论是： + +**是，但这里的“一般化”不是抽象到空洞，而是在不丢业务语义的前提下，把异构数据和系统动作提升为可复用、可交换、可编排的统一业务表达。** + +本文把这个问题拆成三层： + +- 数据一般化 +- 动作一般化 +- 工作流一般化 + +--- + +## 1. 一句话结论 + +**本体的核心作用，是让智能体不再直接面对原始表结构、页面按钮、系统 API，而是面对统一的业务对象、业务动作和工作流上下文。** + +也可以换一种说法： + +**本体把“系统世界”翻译成“业务世界”，再把“业务世界”交给智能体理解和执行。** + +--- + +## 2. 为什么需要这种“一般化” + +如果没有本体或共享对象层，智能体面对的通常是： + +- 不同系统里命名不一致的字段 +- 不同系统里语义不一致的记录 +- 不同系统里风格不一致的接口 +- 大量只能靠 prompt 临时解释的隐含业务规则 + +这会带来三个问题： + +### 2.1 太碎 + +每个系统一套字段、一套命名、一套操作方式。 + +例如： + +- CRM 叫 `cust_nm` +- ERP 叫 `customer_name` +- OA 表单里可能叫 `申请对象` + +本质是同一个业务对象，但智能体看到的是三套世界。 + +### 2.2 太脆 + +只要底层字段名、接口、页面按钮变化，智能体的理解和动作就会失效。 + +### 2.3 太难编排 + +如果节点之间只能传自然语言文本，工作流很难形成稳定接力。 + +例如： + +- 上游节点说“客户订单已批准” +- 下游节点却不知道“批准”对应哪个字段、哪个状态、哪个系统动作 + +所以，本体层的意义不是“把世界讲得更高级”，而是： + +**给智能体一个稳定可操作的中间世界。** + +--- + +## 3. 三层一般化总图 + +```text +原始企业系统层 +------------------------------------------------------------ +CRM / ERP / OA / MES / HIS / TMS / 企微 / Excel / 邮件 / API +字段、表、按钮、接口、附件、日志、消息、审批单、业务记录 + + │ 映射 / 对齐 / 归一 / 绑定 + ▼ + +本体 / 共享对象层 +------------------------------------------------------------ +业务对象：Customer / Order / Approval / Shipment / Task / Artifact +业务关系：belongs_to / depends_on / generated_from / approved_by +业务状态：draft / pending / approved / running / completed / failed +业务动作：CreateFollowUp / SubmitApproval / GenerateQuote / NotifyStakeholder +业务约束：必填、枚举、角色权限、状态转移、来源引用 + + │ 给智能体与工作流统一消费 + ▼ + +智能体运行层 +------------------------------------------------------------ +Agent 读取对象 -> 判断状态 -> 触发动作 -> 生成产物 -> 回写对象 -> 推进流程 +``` + +这个图里最关键的，不是“对象”两个字，而是中间层同时统一了： + +- 数据 +- 动作 +- 状态 +- 约束 +- 引用 + +--- + +## 4. 第一层：数据一般化 + +## 4.1 原始数据的问题 + +企业系统原始数据通常是系统中心化的，而不是业务中心化的。 + +也就是说，数据首先服务于： + +- 某个具体产品 +- 某个具体数据库 +- 某个具体表结构 +- 某个具体页面流程 + +例如同样是“客户”： + +- CRM 里是销售客户 +- ERP 里是结算客户 +- 客服系统里是服务对象 +- 风控系统里是主体户 + +这些数据在字段级、状态级、主键级都可能不一致。 + +## 4.2 本体如何做数据一般化 + +本体不是直接抹平这些差异，而是建立一层更稳定的业务对象表达。 + +例如： + +### 原始系统层 + +- `crm_customer_tbl.customer_id` +- `erp_buyer_master.party_code` +- `service_user_archive.user_no` + +### 一般化后的对象层 + +- `Customer.id` +- `Customer.name` +- `Customer.type` +- `Customer.status` +- `Customer.external_refs[]` + +这样做的意义不是“换个名字”，而是把： + +- 多系统身份 +- 对象含义 +- 状态 +- 来源映射 + +统一挂到一个稳定对象上。 + +## 4.3 数据一般化的产物 + +数据一般化之后，智能体消费的就不再是“字段堆”，而是： + +- `Customer` +- `Order` +- `Task` +- `Artifact` +- `Evidence` +- `Approval` +- `Shipment` + +也就是说： + +**智能体面对的是业务对象，而不是数据库字段。** + +--- + +## 5. 第二层：动作一般化 + +## 5.1 原始动作的问题 + +底层系统动作本来是系统实现中心化的。 + +例如： + +- `POST /crm/followups` +- `erp.updateOrderStatus()` +- `oa.submitForm()` +- `wx.sendMessage()` + +这些动作的问题在于： + +- 过度绑定具体系统 +- 难复用 +- 难迁移 +- 难解释给智能体 + +## 5.2 本体如何做动作一般化 + +本体或共享对象层，会把系统动作提升成业务动作。 + +例如： + +### 系统动作 + +- 创建 CRM 跟进记录 +- 提交 OA 审批单 +- 更新 ERP 订单状态 +- 发送企业微信消息 + +### 一般化后的业务动作 + +- `CreateFollowUp` +- `SubmitApproval` +- `UpdateOrderStatus` +- `NotifyStakeholder` + +这样做之后，智能体不必知道： + +- 是哪个系统在执行 +- 具体 API 长什么样 +- 鉴权细节是什么 +- 底层回写字段有哪些 + +智能体只需要知道： + +- 什么条件下可以触发这个动作 +- 这个动作需要什么输入 +- 这个动作会产生什么结果 +- 这个动作会推进哪个对象状态 + +## 5.3 动作一般化的真正价值 + +动作一般化让平台获得三个能力： + +### 1. 可编排 + +不同连接器背后的系统动作，可以被统一编排进工作流。 + +### 2. 可替换 + +今天是 CRM-A，明天换 CRM-B，上层业务动作可以保持不变。 + +### 3. 可治理 + +权限、审计、checkpoint 可以绑定在业务动作上，而不是散在各系统接口里。 + +也就是说： + +**智能体面对的是业务动作，而不是系统 API。** + +--- + +## 6. 第三层：工作流一般化 + +## 6.1 为什么还需要工作流一般化 + +只有数据一般化和动作一般化，还不够。 + +因为智能体真正要完成的是： + +- 推进任务 +- 协调步骤 +- 产出交付物 +- 处理返工 +- 经过人工确认 +- 回写原系统 + +这就需要第三层： + +**工作流一般化** + +## 6.2 工作流一般化是什么 + +工作流一般化，就是把原本散落在各部门 SOP、页面操作、人工经验中的流程，提升成统一的运行时结构。 + +例如统一为： + +- `Run` +- `Stage` +- `Task` +- `Dependency` +- `Checkpoint` +- `Artifact` +- `Evidence` +- `Risk` + +这样，无论是法律、金融、物流货代还是培训交付，上层都可以复用同一套运行骨架。 + +不同的只是： + +- 对象不一样 +- 动作不一样 +- 连接器不一样 +- 规则不一样 + +但运行逻辑可以一致： + +- 触发 +- 取上下文 +- 执行动作 +- 生成人工审阅点 +- 产出交付物 +- 回写 +- 结束/返工 + +## 6.3 工作流一般化后的意义 + +工作流一般化让智能体不再只是“回答者”，而成为： + +- 可推进任务的执行者 +- 可协同多个节点的参与者 +- 可形成交付闭环的运行单元 + +也就是说： + +**智能体面对的不是一段 prompt，而是一条运行中的工作链。** + +--- + +## 7. 三层一般化的关系 + +这三层不是并列模块，而是层层递进： + +### 第一步：数据一般化 + +让智能体看懂“有什么” + +### 第二步：动作一般化 + +让智能体知道“能做什么” + +### 第三步：工作流一般化 + +让智能体知道“这件事怎么做完” + +可以压缩成一句： + +**数据一般化定义对象，动作一般化定义能力，工作流一般化定义闭环。** + +--- + +## 8. 什么不叫一般化 + +这里要特别避免一个误区： + +**一般化不等于抽象到空洞。** + +以下这种命名虽然“泛”，但没有实际价值： + +- `Entity` +- `Thing` +- `Record` +- `Operation` + +这种抽象无法直接支持： + +- 业务理解 +- 状态推进 +- 权限治理 +- 连接器映射 +- 交付闭环 + +所以，真正有效的一般化必须满足四个条件： + +1. 对业务仍有明确含义 +2. 对连接器仍能映射回原系统 +3. 对智能体仍可理解和操作 +4. 对工作流仍能稳定传递上下文 + +例如： + +- `Customer` +- `Order` +- `Approval` +- `Shipment` +- `Artifact` +- `Evidence` + +就是有效的一般化； + +而： + +- `Thing1` +- `EntityX` + +就是无效的一般化。 + +--- + +## 9. 对六层架构的启发 + +这套理解直接解释了为什么 L3 很关键。 + +### L3 不是普通 model 层 + +L3 的职责不是做 ORM，也不是单纯定义数据库表。 + +L3 的职责是： + +- 一般化数据 +- 一般化动作 +- 支撑工作流一般化 + +所以它更接近： + +- 共享对象层 +- 语义对象层 +- 目标形态上的本体层 + +### L4 为什么也依赖它 + +因为能力服务要统一输入输出。 + +### L5 为什么更依赖它 + +因为工作流运行时需要稳定对象、动作、状态机和产物语义。 + +### L6 为什么会被它改变 + +因为 Run / Studio / Governance UI，不再围绕页面表单转，而会围绕： + +- 对象 +- 动作 +- 交付物 +- 风险 +- 引用 + +来构建。 + +--- + +## 10. 对本项目的直接建议 + +如果把这份理解落到本项目，我建议在文档和实现上明确三件事： + +### 10.1 明确最小共享对象集合 + +优先定义： + +- `Task` +- `Run` +- `Artifact` +- `Evidence` +- `ConnectorBinding` +- `ExternalReference` +- `Checkpoint` + +### 10.2 明确最小业务动作集合 + +优先定义： + +- `FetchContext` +- `GenerateArtifact` +- `SubmitApproval` +- `NotifyStakeholder` +- `WriteBack` +- `EscalateRisk` +- `RequestHumanReview` + +### 10.3 明确最小工作流骨架 + +优先定义： + +- `Run` +- `Stage` +- `Task` +- `Dependency` +- `Checkpoint` +- `Artifact` + +也就是说，先不要追求一套巨大 ontology，而是先把： + +**对象、动作、工作流三层一般化骨架** + +搭起来。 + +--- + +## 11. 最终结论 + +回到原问题： + +**本体是不是为了让智能体的动作、数据可以一般化？** + +答案是： + +**是，而且还要再补一句，它最终是为了让工作流也一般化。** + +更完整的表述是： + +**本体/共享对象层的价值，在于把异构数据提升为统一业务对象，把系统操作提升为统一业务动作，再把业务执行提升为统一工作流骨架，从而让智能体能够跨系统理解、编排、执行和复用。** + +--- + +## 12. 可直接引用的话 + +可以在后续文档中直接引用下面这句： + +**本体不是为了把世界讲复杂，而是为了让智能体操作的不是表和接口，而是对象、动作和工作流。** diff --git a/docs/01_System_Overall/SY17_Workbench_UI_Wireframes.md b/docs/01_System_Overall/SY17_Workbench_UI_Wireframes.md new file mode 100644 index 0000000..0d7c1b2 --- /dev/null +++ b/docs/01_System_Overall/SY17_Workbench_UI_Wireframes.md @@ -0,0 +1,628 @@ +# SY17 — 数字员工平台 UI 线框图（知识库固定 + 专员工作区动态生长） + +> 版本：V1.2 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文用于把当前六层架构、连接器网络、共享对象层、任务运行时，落成更贴近业务人员心智的 UI 线框。 + +这版文档明确修正两个判断： + +- **不应把 `Run` 作为业务人员的一等入口概念** +- **不应让首页看起来像“平台配置页”** +- **不应让用户首先感知“插件”，而应首先感知“数字员工 / xxx专员”** + +业务人员真正想看到的不是： + +- Run +- Studio +- Market + +而是： + +- 我的知识库 +- 我的业务流 +- 我的待办 +- 我当前正在推进的客户/事项/订单/项目 + +因此，这版 UI 采用新的主结构： + +- **知识库是固定入口** +- **数字员工/专员工作区是动态入口** +- **市场/工坊/控制台属于后台能力，不占据业务首页主心智** + +--- + +## 1. 重新定义 UI 主心智 + +## 1.1 不再是“五个固定模式” + +上一版把平台分成： + +- Run +- Studio +- Market +- Knowledge +- 控制台 + +这个划分从平台架构视角没问题，但从业务人员视角太“平台化”了。 + +业务人员不会说： + +- “我去 Run 看看” + +他更可能说： + +- “我去做合同审查” +- “我去推进售前方案” +- “我去处理培训交付” +- “我去跟进货代履约” + +也就是说，**用户入口应该是数字员工与事项，而不是平台内部术语。** + +## 1.2 新的主结构 + +新的产品结构应该是： + +### 固定入口 + +- `知识库` + +### 动态入口 + +- 已安装并启用的数字员工 / 专员工作区 +- 每个专员都围绕一类事项或业务流负责 +- 专员在产品层明确分成两层： + - `通用专员`：跨行业可复用的共性工种 + - `行业专员`：绑定行业对象、行业连接器、行业工作流的垂直工种 + +例如： + +- `售前方案` +- `合同审查` +- `培训交付` +- `货代履约` +- `客户跟进` +- `理赔审核` + +### 后台入口 + +- 市场 +- 工坊 +- 控制台 + +这些依然存在，但更适合： + +- 管理员 +- 配置者 +- 运营者 +- 平台搭建者 + +而不应该成为业务人员首页的主结构。 + +--- + +## 2. 新的整体骨架 + +```text ++--------------------------------------------------------------------------------------------------+ +| Logo | Global Search | Alerts | 最近专员切换 | User | ++--------------------------------------------------------------------------------------------------+ +| Fixed Nav | Business Workspace | Context Drawer | +|---------------------|-----------------------------------------------------|---------------------| +| 知识库 | 业务流看板 / 事项详情 / 流程推进 / 表单协作 | Outputs | +|---------------------| | Artifacts | +| 专员工作区 | | Evidence | +| - 通用专员 | | Risks | +| - 培训交付专员 | | | +| - 行业专员 | | | +| - 售前方案专员 | | Risks | +| - 合同审查专员 | | | +| - 履约跟单专员 | | | +| - 客户跟进专员 | | | +|---------------------|-----------------------------------------------------|---------------------| +| 后台 | Optional Bottom Panel: event / replay / logs / trace | +| - 市场 | | +| - 工坊 | | +| - 控制台 | | ++--------------------------------------------------------------------------------------------------+ +``` + +这里最关键的变化是： + +- **左侧第一项固定是知识库** +- **左侧第二块不是固定产品模块，而是动态专员工作区** +- **业务真正的主入口是“专员工作区/我的事项”** + +--- + +## 3. 首页不应该像配置页，而应该像业务工作台 + +业务首页应该先回答四个问题： + +1. 我现在有哪些业务流可用？ +2. 哪些业务流里有我的待办？ +3. 哪些事项卡住了？ +4. 哪些交付物刚刚产生，需要我处理？ + +### 3.1 首页线框 + +```text ++--------------------------------------------------------------------------------------------------+ +| Logo | Search | Alerts | User | ++--------------------------------------------------------------------------------------------------+ +| 知识库 | 专员工作区 | 专员市场 | 工坊 | 控制台 | ++--------------------------------------------------------------------------------------------------+ +| [我的待办] [我的业务流] [最近交付物] [高风险事项] | ++--------------------------------------------------------------------------------------------------+ +| +-------------------------+ +-------------------------+ +-------------------------+ | +| | 培训交付专员 | | 售前方案专员 | | 合同审查专员 | | +| | 通用专员 / 训练运营 | | 行业专员 / 售前 | | 行业专员 / 法务 | | +| | 3 个待办 / 1 个逾期 | | 2 个待审批 / 1 个高风险 | | 5 个进行中 | | +| | [进入应用] | | [进入应用] | | [进入应用] | | +| +-------------------------+ +-------------------------+ +-------------------------+ | +| +-------------------------+ +-------------------------+ +-------------------------+ | +| | 履约跟单专员 | | 客户跟进专员 | | 新安装专员推荐 | | +| | 行业专员 / 货代履约 | | 行业专员 / 客户成功 | | 通用 / 行业双层浏览 | | +| | 1 个异常 / 2 个节点延迟 | | 6 个待跟进 | | [查看专员市场] | | +| | [进入应用] | | [进入应用] | | | | +| +-------------------------+ +-------------------------+ +-------------------------+ | ++--------------------------------------------------------------------------------------------------+ +| 时间线：最近交付物 / 最近异常 / 最近人工确认 | ++--------------------------------------------------------------------------------------------------+ +``` + +### 3.2 首页气质 + +它应该像： + +- 业务工作台 +- 事项中心 +- 交付中心 + +而不是： + +- 配置中心 +- 低代码平台首页 +- 节点编辑器入口页 + +--- + +## 4. 知识库作为固定第一入口 + +这是你提的关键点，我认为是对的。 + +## 4.1 为什么知识库应该固定 + +因为知识库不是某个专员，而是整个平台的公共底座。 + +它承担： + +- 资料沉淀 +- 证据引用 +- 规则维护 +- 共享对象定义 +- 场景上下文 + +也就是说，不管你打开的是： + +- 合同审查 +- 售前方案 +- 培训交付 +- 货代履约 + +最终都要回到知识库提供的： + +- `Evidence` +- `PolicyRule` +- `Scenario` +- `Object Dictionary` + +所以，知识库应该像“文件系统/资料台”一样，是一个稳定存在的主入口。 + +## 4.2 知识库线框 + +```text ++--------------------------------------------------------------------------------------------------+ +| Logo | Search | Alerts | User | ++--------------------------------------------------------------------------------------------------+ +| 知识库 | 我的应用 | 市场 | 工坊 | 控制台 | ++--------------------------------------------------------------------------------------------------+ +| Knowledge Tree | [Assets] [Evidence] [Rules] [Scenarios] [Objects] [Graph] | +|----------------------|----------------------------------------------------------------------------| +| - 资料资产 | [Evidence Explorer] | +| - 证据片段 | +--------------------+ +--------------------+ +--------------------+ | +| - 规则库 | | e-2391 合同片段 | | e-4412 通话纪要 | | e-9912 CRM 记录 | | +| - 场景模板 | +--------------------+ +--------------------+ +--------------------+ | +| - 对象字典 | | +|----------------------|----------------------------------------------------------------------------| +| Filters | 对象/规则/场景详情 | +| - 来源 | - Contract | +| - 可靠性 | - Related Rules: 4 | +| - 敏感等级 | - Connected Apps: 合同审查 / 售前方案 | +| | - Connected Connectors: CRM / OA / DMS | +|----------------------|----------------------------------------------------|----------------------| +| Graph / Dictionary | | Context Drawer | +| - 对象图谱 | | 相关交付物 | +| - 同义词 | | 风险 | +| - 映射规则 | | 引用关系 | ++--------------------------------------------------------------------------------------------------+ +``` + +--- + +## 5. 动态业务应用区 + +业务应用区不是平台预设死的五个页面，而是： + +**安装什么插件、发布什么业务流，就长出什么应用。** + +## 5.1 左侧导航新结构 + +```text ++---------------------------+ +| 知识库 | +|---------------------------| +| 我的应用 | +| - 售前方案 | +| - 合同审查 | +| - 培训交付 | +| - 货代履约 | +| - 客户跟进 | +|---------------------------| +| 后台 | +| - 市场 | +| - 工坊 | +| - 控制台 | ++---------------------------+ +``` + +### 5.2 这意味着什么 + +- 平台骨架是固定的 +- 业务应用是动态的 +- 插件不只是一个能力点，而是能长成一个业务工作台 + +例如安装： + +- `合同审查插件包` + +左侧就会出现： + +- `合同审查` + +安装： + +- `货代履约插件包` + +左侧就会出现： + +- `货代履约` + +这才符合“插件化工作流交付平台”的心智。 + +--- + +## 6. 业务应用页面：不是 Run，而是业务流详情页 + +这里是最重要的纠偏。 + +用户点开的不应该叫： + +- `Run` + +而应该直接叫业务名字，比如： + +- `合同审查` +- `售前方案` +- `培训交付` +- `货代履约` + +平台内部当然仍然可以有 `Run` 这个对象和运行实例，但**不要把它作为业务入口名称暴露给用户。** + +## 6.1 业务流详情页线框（以“合同审查”为例） + +```text ++--------------------------------------------------------------------------------------------------+ +| Logo | Search | Alerts | User | ++--------------------------------------------------------------------------------------------------+ +| 知识库 | 合同审查 | 售前方案 | 培训交付 | 货代履约 | ... | ++--------------------------------------------------------------------------------------------------+ +| Cases / Matters | [合同审查 / 华东客户主协议修订] [进度] [时间线] [对话记录] [回放] | +|-----------------------|-------------------------------------------------------------------------------| +| 我的事项 | 阶段 1：资料收集 -> 已完成 | +| - 待我处理 | 阶段 2：条款识别 -> 进行中 | +| - 待审批 | 阶段 3：风险分析 -> 待处理 | +| - 已完成 | 阶段 4：人工复核 -> 待确认 | +|-----------------------|-------------------------------------------------------------------------------| +| 当前流程 | [主工作区] | +| - 条款识别 | +-------------------+ +-------------------+ +-------------------+ | +| - 风险分析 | | 条款抽取 | | 风险矩阵 | | 人工确认 | | +| - 红线建议 | | 进行中 | | 待生成 | | 等待中 | | +| - 人工确认 | +-------------------+ +-------------------+ +-------------------+ | +|-----------------------|-------------------------------------------------------------------------------| +| Quick Views | 文档预览 / 审查结果 / 风险卡片 / 审批说明 | +| - 全部交付物 | | +| - 风险项 | | +| - 待确认点 | | +| - 引用证据 | | +|-----------------------|----------------------------------------------------|----------------------| +| Related Cases | | Outputs | +| - 上一版合同 | | Artifacts | +| - 相关补充协议 | | Evidence | +| | | Risks | ++--------------------------------------------------------------------------------------------------+ +``` + +### 6.2 这类页面的重点 + +- 看的不是“配置” +- 看的不是“节点” +- 看的不是“系统对象” + +而是： + +- 当前业务事项 +- 当前推进阶段 +- 当前卡点 +- 当前交付物 +- 当前证据和风险 + +这才是业务人员真正关心的。 + +--- + +## 7. Studio 工坊应该退到后台，不应该成为业务主首页 + +Studio 仍然重要，但它属于： + +- 配置者 +- 管理员 +- 业务设计者 +- 插件装配者 + +不属于一线业务人员的日常主入口。 + +## 7.1 工坊线框 + +```text ++--------------------------------------------------------------------------------------------------+ +| Logo | Search | Alerts | User | ++--------------------------------------------------------------------------------------------------+ +| 知识库 | 我的应用 | 市场 | 工坊 | 控制台 | ++--------------------------------------------------------------------------------------------------+ +| Templates / Plugins | [合同审查模板] [流程画布] [Schema] [测试] [发布] | +|---------------------|-------------------------------------------------------------------------------| +| 节点库 | [Workflow Canvas] | +| - 连接器节点 | +----------------+ +----------------+ +----------------+ | +| - 能力节点 | | FetchContract | -> | AnalyzeClause | -> | HumanReview | | +| - 人工节点 | +----------------+ +----------------+ +----------------+ | +| - 输出节点 | | +|---------------------|-------------------------------------------------------------------------------| +| 版本 | 节点配置 / 字段映射 / 重试策略 / 权限 / 发布说明 | ++--------------------------------------------------------------------------------------------------+ +``` + +### 7.2 Studio 的定位 + +它仍然是平台核心，但应该是： + +- 后台工坊 +- 设计面 +- 编排面 + +而不是一线业务人员每天第一眼看到的首页。 + +--- + +## 8. 市场和控制台也应该退后 + +### 市场 + +更像应用商店/插件中心，用户需要时再进，不是工作主界面。 + +### 控制台 + +更像管理控制台，主要服务管理员，不是普通业务人员首页。 + +所以对普通业务人员来说，真正的一线主结构应该是： + +1. 知识库 +2. 我的应用 / 我的业务流 + +而不是： + +1. Run +2. Studio +3. Market +4. 控制台 + +--- + +## 9. 新旧两种 UI 思路的差别 + +| 维度 | 旧思路 | 新思路 | +|------|--------|--------| +| 一级入口 | 五个固定模式 | 知识库固定 + 业务流动态 | +| 业务首页 | 平台结构中心 | 业务事项中心 | +| 用户看到的词 | Run / Studio | 合同审查 / 售前方案 / 培训交付 | +| 工坊位置 | 一等前台模式 | 后台配置面 | +| 应用生长方式 | 固定菜单 | 插件/业务流动态加入 | + +--- + +## 10. 最值得先落地的界面顺序 + +按现在这个更合理的方向，建议先做： + +### 10.1 业务首页 + +先把： + +- 我的应用 +- 我的待办 +- 我的业务流 +- 最近交付物 + +做出来。 + +### 10.2 一个真实业务应用详情页 + +比如： + +- 合同审查 +- 售前方案 + +二选一先做透。 + +### 10.3 知识库固定入口 + +把 `Evidence / Rules / Objects` 这些底座能力做成稳定入口。 + +### 10.4 最后再补工坊 + +因为工坊再强，如果前台业务页面不像业务流，产品仍然会显得像配置平台。 + +--- + +## 11. 最终结论 + +这套平台最终 UI 不应该是： + +- 五个固定平台模式平铺给所有人 + +而应该是： + +- **知识库固定存在** +- **业务应用随着插件/业务流动态长出来** +- **业务人员看到的是自己的业务流，不是平台内部术语** +- **市场/工坊/控制台退到后台** + +一句话说： + +**前台应该是“知识库 + 我的业务流”，后台才是“市场 + 工坊 + 控制台”。** + +--- + +## 12. 参考 `pj213` 后的最终判断：不要老式 JEE 多窗口，要现代多窗格 + +在参考 `pj213-HAWMS` 后，需要明确一个设计边界： + +- **不要回到 `左树 + 多 iframe + easyui-tabs` 的传统后台壳子** +- **要支持多任务并行，但应采用现代 SPA 的多窗格 + 轻量多标签** + +也就是说，我们要借的是“并行处理多个业务上下文”的能力，**不是**借它的老式技术与页面组织方式。 + +### 12.1 不采用的形态 + +不采用下面这种典型老式后台： + +```text ++------------------------------------------------------------------------------------+ +| 顶栏 | ++------------------------------------------------------------------------------------+ +| 左菜单树 | Tab1 | Tab2 | Tab3 | Tab4 | +| - 菜单A |---------------------------------------------------------| +| - 菜单B | [iframe 页面 A] | +| - 菜单C | | +| - 菜单D | | +| | | ++------------------------------------------------------------------------------------+ +``` + +这个形态适合： + +- ERP / WMS / OA 的传统后台 +- 表格 CRUD 和单据页 +- 菜单中心而不是业务上下文中心 + +但它不适合这套平台，因为它很难自然承载： + +- 统一的 `Artifacts / Evidence / Risks` +- 工作流回放与事件流 +- 跨应用共享上下文 +- 插件动态装配 + +### 12.2 采用的形态 + +应采用下面这种现代工作台： + +```text ++-------------------------------------------------------------------------------------------------------------------+ +| Logo | Search | Alerts | 最近事项 | User | ++-------------------------------------------------------------------------------------------------------------------+ +| 知识库 | 我的应用 | 市场 | 工坊 | 控制台 | ++-------------------------------------------------------------------------------------------------------------------+ +| App Nav / Case List | Workspace Tabs | Context Drawer | +|-------------------------------------|---------------------------------------------|----------------------------------| +| 我的应用 | [合同审查 / 华东客户] [售前方案 / A客户] | Outputs | +| - 合同审查 | [培训交付 / 新人班] | Artifacts | +| - 售前方案 |---------------------------------------------| Evidence | +| - 培训交付 | | Risks | +|-------------------------------------| 主工作区 |----------------------------------| +| 当前事项 | - 业务详情 | Checkpoints | +| - 待我处理 | - 流程推进 | Related Objects | +| - 待确认 | - 文档预览 | Recent Events | +| - 高风险 | - 表单协作 | | +|-------------------------------------| | | +| 最近交付物 | | | ++-------------------------------------------------------------------------------------------------------------------+ +| Bottom Panel (按需展开): Timeline / Replay / Event Log / Trace / Connector Log | ++-------------------------------------------------------------------------------------------------------------------+ +``` + +### 12.3 这个形态的关键点 + +- **左侧不是菜单树，而是“知识库 + 我的应用 + 当前事项”** +- **中间不是 iframe 页面，而是统一工作区** +- **顶部标签不是系统全量页面标签，而是“正在处理的业务上下文”** +- **右侧抽屉固定存在，用来承载交付上下文** +- **底部面板按需展开，用来承载事件流、回放、trace、连接器日志** + +--- + +## 13. 多窗口到底要不要 + +结论是： + +- **不要老式多窗口** +- **要现代并行工作能力** + +### 13.1 不要什么 + +- 不要浏览器里堆很多独立子窗口 +- 不要每个 tab 一个 iframe +- 不要所有系统页面都能无限开标签 + +### 13.2 要什么 + +- **轻量多标签**：同时保留多个业务事项上下文 +- **多窗格对照**：中间处理业务，右侧看证据/产物/风险 +- **按需弹出**：Artifact 预览、Evidence 对照、Connector 日志可弹层或抽屉 + +### 13.3 为什么这样更适合平台 + +因为这个平台的核心不是“切页面”，而是： + +- 在一个稳定上下文里推进业务 +- 随时查看证据和交付物 +- 在不同事项之间快速切换 +- 保持工作流与运行态的连续性 + +所以我们需要的是： + +**多上下文并行** + +而不是： + +**多页面后台** + +--- + +## 14. 最终 UI 定稿建议 + +如果把这次结论压缩成一句话： + +**不采用 `pj213` 那种 JEE 多 iframe 后台，而采用“知识库固定 + 业务应用动态 + 多窗格工作区 + 轻量多标签 + 右侧上下文抽屉”的现代业务工作台。** diff --git a/docs/01_System_Overall/SY18_DWP_DW_ADW_Formal_Design_Contract.md b/docs/01_System_Overall/SY18_DWP_DW_ADW_Formal_Design_Contract.md new file mode 100644 index 0000000..53a2ab8 --- /dev/null +++ b/docs/01_System_Overall/SY18_DWP_DW_ADW_Formal_Design_Contract.md @@ -0,0 +1,995 @@ +# SY18 — DWP / DW / ADW 正式设计合同 + +> 版本：V1.1 | 最后更新：2026-08-16 + +--- + +## 0. 文档目的 + +本文用于把当前平台中已经形成的产品判断、对象模型和运行时要求，正式收敛为一套可复用的设计合同。 + +本文有两个直接用途： + +- 供本项目后续设计、建模、实现时统一口径 +- 供另一个 AI 或子系统直接读取，作为 `DW / ADW` 的标准定义与生成模板 + +本文是规范文档，不是讨论稿。 + +--- + +## 1. 术语定稿 + +### 1.1 平台层 + +- `DWP = Digital Worker Platform` + +`DWP` 指平台本身。它不是单个员工，而是承载数字员工的操作系统与管理底座。 + +### 1.2 个体层 + +- `DW = Digital Worker` + +`DW` 指一个数字员工工作单元。它有身份、职责、权限、信息入口、技能和可执行动作，但自治程度可控。 + +### 1.3 高级自治层 + +- `ADW = Autonomous Digital Worker` + +`ADW` 是 `DW` 的高级形态。它不是“会聊天的 DW”，而是具备更高自主执行、委派、升级、学习与技能沉淀能力的数字员工。 + +--- + +## 2. 设计总原则 + +### 2.1 不是 Prompt，而是工作单元 + +`DW / ADW` 不是一个 prompt，不是一个聊天页，不是一个插件说明卡。 + +它必须是一个带有以下骨架的工作单元： + +- 身份 +- 信息入口 +- 技能 +- 动作 +- 权限边界 +- 规则边界 +- 输出协议 +- 记忆 +- 运行状态 + +### 2.2 ADW 比 DW 多出的不是“更聪明”，而是“更多自治能力” + +`ADW` 与 `DW` 的核心差别不在模型大小，而在运行权责边界。 + +`ADW` 必须比 `DW` 多出以下能力： + +- 自主规划 +- 自主委派 +- 条件升级 +- 审批前置 +- 策略记忆 +- 技能沉淀 + +### 2.3 必须同时可供人和 AI 使用 + +因此本规范同时给出： + +- 面向人的语义设计 +- 面向 AI 的结构化合同 +- 面向工程的字段定义 + +### 2.4 信源、权限、动作、结果必须前台清晰可见 + +真正使用 `DW / ADW` 时，业务用户最关心的不是模型参数，而是： + +- 信息从哪里来 +- 它现在能做哪些动作 +- 哪些动作可以自动做，哪些需要审批 +- 它已经产出了什么结果，结果当前处于什么状态 + +因此，`DWP` 的工作区设计必须把以下四类信息作为一等对象展示： + +- `Sources` +- `Permissions` +- `Actions` +- `Results` + +如果这四类信息在 UI 上不可见，即使后端对象模型完整，也不能视为合格的 `DW / ADW` 产品形态。 + +说明： + +- 产品术语统一使用 `信源` +- 内部结构字段统一使用 `inputs_*` 命名 + +--- + +## 3. DWP 平台职责 + +`DWP` 负责管理和承载所有 `DW / ADW`。 + +### 3.1 DWP 必备能力 + +1. `directory` +数字员工目录。负责注册、分类、启停、版本、状态管理。 + +2. `identity` +数字员工身份系统。负责 worker id、角色、归属、租户、环境、可见范围。 + +3. `connectors` +信息与动作入口。包括企业系统连接器、资源读取器、写回器、触发器。 + +4. `skills` +技能包系统。负责基本技能、推荐技能、生成技能、技能版本管理。 + +5. `runtime` +运行时。负责任务执行、上下文装配、工具调用、审批、日志、回放、追踪。 + +6. `memory` +记忆层。负责工作记忆、案例记忆、策略记忆、技能记忆。 + +7. `governance` +治理层。负责权限、审批、禁止动作、升级规则、审计与可观测性。 + +8. `workbench` +工作区。负责业务操作界面、上下文抽屉、底部运行面板与人工接管入口。 + +### 3.2 DWP 与 DW / ADW 的关系 + +- `DWP` 是平台 +- `DW` 是普通数字员工 +- `ADW` 是高自治数字员工 + +关系上： + +`DWP > DW > ADW(高级形态)` + +更准确地说： + +- `ADW` 继承 `DW` 的基础合同 +- `ADW` 在 `governance` 和 `runtime` 上比 `DW` 多出自治能力字段 + +--- + +## 4. DW 正式对象模型 + +## 4.1 DW 定义 + +`DW` 是一个带身份、入口、技能、动作、权限和记忆的数字工作单元。 + +### 4.2 DW 最小必要字段 + +一个合格的 `DW` 至少需要以下 8 类字段： + +1. `identity` +2. `bindings` +3. `capabilities` +4. `governance` +5. `runtime` +6. `memory` +7. `status` +8. `presentation` + +--- + +## 5. ADW 正式对象模型 + +## 5.1 ADW 定义 + +`ADW` 是具备可控自治能力的数字员工。它必须在 `DW` 的基础上，增加： + +- 自治等级 +- 自主执行边界 +- 审批前置 +- 委派规则 +- 升级规则 +- 经验沉淀 + +### 5.2 ADW 与 DW 的结构关系 + +可以把 `ADW` 理解为： + +`ADW = DW + autonomy + delegation + escalation + learning` + +--- + +## 6. 标准结构合同 + +下面是本项目正式采用的 `DW / ADW` 顶层结构。 + +```json +{ + "kind": "dw_or_adw", + "specVersion": "1.0", + "identity": {}, + "bindings": {}, + "capabilities": {}, + "governance": {}, + "runtime": {}, + "memory": {}, + "status": {}, + "presentation": {} +} +``` + +--- + +## 7. 字段设计 + +## 7.1 identity + +表示“它是谁”。 + +```json +{ + "id": "server-patrol", + "name": "服务器巡视专员", + "workerType": "adw", + "role": "巡检与异常发现", + "department": "运维", + "tenant": "default", + "environment": ["prod", "staging"], + "owner": "ops-platform", + "version": "v1.0", + "status": "active", + "avatar": "", + "email": "" +} +``` + +字段说明： + +- `id`：稳定唯一标识 +- `name`：产品显示名 +- `workerType`：`dw` 或 `adw` +- `role`：岗位职责 +- `department`：归属域 +- `tenant`：租户 +- `environment`：适用环境 +- `owner`：责任团队 +- `version`：当前版本 +- `status`：启用状态 + +## 7.2 bindings + +表示“它接到哪些入口和出口”。 + +```json +{ + "sources": [ + { + "key": "servers", + "connector": "cmdb", + "mode": "read", + "objects": ["server"] + }, + { + "key": "stats", + "connector": "prometheus", + "mode": "read", + "objects": ["cpu", "memory", "disk", "load"] + } + ], + "tools": [ + { + "key": "inspect", + "type": "tool", + "toolRef": "inspect_server_state" + }, + { + "key": "run_script", + "type": "tool", + "toolRef": "run_diagnostic_script" + } + ], + "reports": [ + { + "key": "patrol", + "channel": "console", + "format": "markdown" + } + ] +} +``` + +字段说明： + +- `sources`：信息入口 +- `tools`：执行入口 +- `reports`：输出入口 + +这里必须用结构体，而不能只写字符串数组。 + +## 7.3 capabilities + +表示“它会什么、能做什么”。 + +```json +{ + "skills": [ + { + "key": "diagnostic_skills", + "label": "诊断技能包", + "version": "v1", + "mode": "builtin" + } + ], + "actions": [ + { + "key": "inspect", + "label": "巡视检查", + "risk": "low" + }, + { + "key": "run_script", + "label": "运行诊断脚本", + "risk": "medium" + }, + { + "key": "report", + "label": "生成巡视报告", + "risk": "low" + } + ] +} +``` + +规则： + +- `skills` 是能力包 +- `actions` 是执行动作 +- 不能把两者混为一谈 + +## 7.4 governance + +表示“它被允许做什么、必须如何收敛风险”。 + +```json +{ + "permissions": { + "resourceScope": { + "servers": "all", + "jobs": "read_only", + "alerts": "read_only" + }, + "toolScope": { + "inspect": "allowed", + "run_script": "approval_required", + "report": "allowed" + }, + "writeLevel": "read", + "approvalHint": "高风险诊断需确认" + }, + "rules": { + "delegate": [ + { + "target": "alert-watch", + "when": "new_alert_detected" + } + ], + "escalate": [ + { + "condition": "disk_usage > 90 for 5m", + "to": "ops-oncall", + "severity": "high" + } + ], + "forbid": [ + { + "action": "deploy", + "mode": "deny" + }, + { + "action": "provision", + "mode": "deny" + }, + { + "action": "transfer", + "mode": "deny" + } + ] + }, + "autonomy": { + "level": "semi_autonomous", + "autoExecute": ["inspect", "report"], + "approvalRequired": ["run_script"], + "humanReviewRequired": ["high_risk_diagnosis"] + } +} +``` + +规则： + +- `DW` 可以没有完整 `autonomy` +- `ADW` 必须有完整 `autonomy` +- `forbid` 必须结构化表达，不能只写自然语言 + +## 7.5 runtime + +表示“它在运行时如何工作”。 + +```json +{ + "taskMode": "case_based", + "contextAssembly": { + "includeSources": ["servers", "stats", "history", "alerts"], + "maxHistoryItems": 20 + }, + "execution": { + "timeoutSec": 120, + "retryPolicy": "safe_retry", + "approvalMode": "stepwise" + }, + "audit": { + "logActions": true, + "logDelegation": true, + "logEscalation": true + } +} +``` + +## 7.6 memory + +表示“它记住什么、怎么沉淀经验”。 + +```json +{ + "workingMemory": {}, + "caseMemory": { + "enabled": true, + "window": 30 + }, + "policyMemory": { + "enabled": true + }, + "skillMemory": { + "enabled": true, + "allowSkillGeneration": true + } +} +``` + +规则： + +- `DW` 至少要有 `workingMemory` +- `ADW` 必须有 `caseMemory / policyMemory / skillMemory` + +## 7.7 status + +表示“它当前处于什么状态”。 + +```json +{ + "lifecycle": "active", + "health": "healthy", + "lastRunAt": "", + "lastReportAt": "", + "lastError": "" +} +``` + +## 7.8 presentation + +表示“它如何在 DWP 上被显示与操作”。 + +```json +{ + "tier": "generic", + "summary": "跨服务器巡视、异常发现与风险上报", + "stage": "日常巡检", + "marketTag": "已安装", + "route": "/apps/server-patrol", + "color": "#409eff", + "workbench": { + "showInputsPanel": true, + "showPermissionsPanel": true, + "showActionsPanel": true, + "showResultsPanel": true + } +} +``` + +--- + +## 8. 工作区可见性合同 + +## 8.1 设计目标 + +每个 `DW / ADW` 工作区都必须让业务用户一眼回答下面四个问题： + +1. 这个数字员工现在看了哪些信源 +2. 它当前被允许做什么，不允许做什么 +3. 它正在做什么动作，哪些动作待审批 +4. 它已经产出了什么结果，结果是否已确认或已发布 + +如果用户无法在 5 到 10 秒内回答这四个问题，则工作区设计不合格。 + +## 8.2 四块固定面板 + +每个 `DW / ADW` 工作区应至少包含以下四块固定可见区域： + +1. `信源面板` +2. `权限面板` +3. `动作面板` +4. `结果面板` + +推荐布局： + +- 主区上部：`信源面板 + 权限面板` +- 主区中部：`动作面板` +- 右侧抽屉：`结果面板` +- 底部运行面板：`时间线 / 回放 / 调用链 / 日志` + +## 8.3 信源面板必显字段 + +信源面板不是“信息入口”四个字，而是要显示可追溯信源条目。 + +每条信源至少应展示： + +- `input_name` +- `input_type` +- `connector_name` +- `object_type` +- `object_id` +- `fetched_at` +- `last_sync_status` +- `confidence` +- `citation` + +推荐结构： + +```json +{ + "input_name": "主协议正文", + "input_type": "document", + "connector_name": "dms", + "object_type": "contract", + "object_id": "ct-00192", + "fetched_at": "2026-08-16T10:30:00+08:00", + "last_sync_status": "ok", + "confidence": 0.96, + "citation": "第 12 页，第 3 段" +} +``` + +## 8.4 权限面板必显字段 + +权限面板必须让用户明确知道： + +- 能读什么 +- 能写什么 +- 哪些动作需要审批 +- 哪些动作被禁止 + +每个工作区至少应展示： + +- `resource_scope` +- `tool_scope` +- `access_mode` +- `approval_required` +- `approval_role` +- `approval_reason` +- `forbidden_actions` +- `delegation_allowed` + +推荐结构： + +```json +{ + "resource_scope": ["contracts:read", "oa:read", "approval:create"], + "tool_scope": { + "inspect": "allowed", + "run_script": "approval_required", + "report": "allowed" + }, + "access_mode": "mixed", + "approval_required": ["run_script"], + "approval_role": ["法务经理"], + "approval_reason": "高风险诊断可能触发例外说明", + "forbidden_actions": ["deploy", "provision"], + "delegation_allowed": true +} +``` + +## 8.5 动作面板必显字段 + +动作面板是当前原型最缺失的一层。它必须成为工作区一等对象。 + +每个可执行动作至少应展示： + +- `action_name` +- `action_type` +- `trigger_mode` +- `input_sources` +- `expected_output` +- `risk_level` +- `status` +- `approval_state` +- `operator` +- `started_at` +- `finished_at` + +推荐结构： + +```json +{ + "action_name": "生成红线建议", + "action_type": "analysis", + "trigger_mode": "manual", + "input_sources": ["contract_body", "history_clause_set"], + "expected_output": ["redline_draft", "risk_matrix"], + "risk_level": "medium", + "status": "running", + "approval_state": "not_required", + "operator": "dw", + "started_at": "2026-08-16T10:31:00+08:00", + "finished_at": "" +} +``` + +## 8.6 结果面板必显字段 + +结果面板当前原型已经有基础，但还缺完整链路。 + +每条结果至少应展示： + +- `result_type` +- `result_title` +- `result_status` +- `derived_from_actions` +- `derived_from_sources` +- `artifact_url` +- `published_to` +- `confirmed_by` +- `confirmed_at` +- `version` + +推荐结构： + +```json +{ + "result_type": "artifact", + "result_title": "主协议 redline 包", + "result_status": "pending_review", + "derived_from_actions": ["extract_clause", "compare_policy", "generate_redline"], + "derived_from_sources": ["contract_body", "policy_rule_set"], + "artifact_url": "/artifacts/contract-redline-v2.docx", + "published_to": [], + "confirmed_by": "", + "confirmed_at": "", + "version": "v2" +} +``` + +## 8.7 UI 状态链路要求 + +结果不能只作为静态列表展示，必须可追踪到完整链路： + +`信源 -> 动作 -> 结果 -> 审批/发布状态` + +因此每个工作区至少要支持下面四种视角之间的跳转： + +- 从信源跳到关联动作 +- 从动作跳到输入信源 +- 从结果跳到生成动作 +- 从结果跳到审批/发布状态 + +## 8.8 当前原型 UI 审查结论 + +对当前前端原型的结论如下： + +### 已做到的部分 + +- 已经有 `DW / ADW` 骨架展示 +- 已经有右侧上下文抽屉 +- 已经有底部运行面板 +- 已经有 `Outputs / Artifacts / Evidence / Risks` 基础结果展示 + +### 仍然不足的部分 + +1. `信源` +当前只有 `Evidence` 字符串列表，未展示连接器、对象、抓取时间、置信度、引用位置。 + +2. `权限` +当前只有“资源权限”文本摘要，未展示读写模式、审批要求、禁止动作、授权边界。 + +3. `动作` +当前缺少动作面板。用户无法清晰知道当前可执行动作、正在执行的动作和待审批动作。 + +4. `结果` +当前已有基础结果区，但尚未形成 `信源 -> 动作 -> 结果 -> 审批/发布状态` 的完整链路。 + +### 当前成熟度判断 + +- `信源`：部分可见 +- `权限`：概念已出现，但不够清晰 +- `动作`：尚未成为一等 UI 对象 +- `结果`：当前最成熟，但仍不完整 + +因此，当前原型不能视为已经完成 `DW / ADW` 的正式工作区设计，只能视为“骨架已具备、关键面板未补齐”。 + +--- + +## 9. DW 与 ADW 的正式差异表 + +| 维度 | DW | ADW | +|------|----|-----| +| 身份 | 必须 | 必须 | +| 信息入口 | 必须 | 必须 | +| 技能 | 必须 | 必须 | +| 动作 | 必须 | 必须 | +| 权限 | 必须 | 必须 | +| 禁止动作 | 建议 | 必须 | +| 自治等级 | 可选 | 必须 | +| 委派规则 | 可选 | 必须 | +| 升级规则 | 可选 | 必须 | +| 审批前置 | 建议 | 必须 | +| 技能沉淀 | 可选 | 必须 | +| 策略记忆 | 建议 | 必须 | + +--- + +## 10. 对“服务器巡视专员”示例的正式改写 + +下面是把原始设计稿升级后的正式 `ADW` 合同。 + +```json +{ + "kind": "adw", + "specVersion": "1.0", + "identity": { + "id": "server-patrol", + "name": "服务器巡视专员", + "workerType": "adw", + "role": "巡检与异常发现", + "department": "运维", + "tenant": "default", + "environment": ["linux", "windows"], + "owner": "ops-platform", + "version": "v1.0", + "status": "active", + "avatar": "", + "email": "" + }, + "bindings": { + "sources": [ + { "key": "servers", "connector": "cmdb", "mode": "read", "objects": ["server"] }, + { "key": "stats", "connector": "prometheus", "mode": "read", "objects": ["cpu", "memory", "disk", "load"] }, + { "key": "inventory", "connector": "inventory", "mode": "read", "objects": ["host", "group", "owner"] }, + { "key": "history", "connector": "ops_history", "mode": "read", "objects": ["incident", "change", "patrol_report"] }, + { "key": "alerts", "connector": "alert_center", "mode": "read", "objects": ["alert"] }, + { "key": "jobs", "connector": "job_runner", "mode": "read", "objects": ["job"] } + ], + "tools": [ + { "key": "inspect", "type": "tool", "toolRef": "inspect_server_state" }, + { "key": "run_script", "type": "tool", "toolRef": "run_diagnostic_script" }, + { "key": "report", "type": "tool", "toolRef": "generate_patrol_report" } + ], + "reports": [ + { "key": "patrol", "channel": "console", "format": "markdown" } + ] + }, + "capabilities": { + "skills": [ + { "key": "diagnostic_skills", "label": "诊断技能包", "version": "v1", "mode": "builtin" } + ], + "actions": [ + { "key": "inspect", "label": "巡视检查", "risk": "low" }, + { "key": "run_script", "label": "运行诊断脚本", "risk": "medium" }, + { "key": "report", "label": "生成巡视报告", "risk": "low" } + ] + }, + "governance": { + "permissions": { + "resourceScope": { + "servers": "all", + "alerts": "read_only", + "jobs": "read_only" + }, + "toolScope": { + "inspect": "allowed", + "run_script": "approval_required", + "report": "allowed" + }, + "writeLevel": "read", + "approvalHint": "高风险诊断需确认" + }, + "rules": { + "delegate": [ + { "target": "alert-watch", "when": "new_alert_detected" } + ], + "escalate": [ + { "condition": "disk_usage > 90 for 5m", "to": "ops-oncall", "severity": "high" } + ], + "forbid": [ + { "action": "deploy", "mode": "deny" }, + { "action": "provision", "mode": "deny" }, + { "action": "transfer", "mode": "deny" } + ] + }, + "autonomy": { + "level": "semi_autonomous", + "autoExecute": ["inspect", "report"], + "approvalRequired": ["run_script"], + "humanReviewRequired": ["high_risk_diagnosis"] + } + }, + "runtime": { + "taskMode": "case_based", + "contextAssembly": { + "includeSources": ["servers", "stats", "inventory", "history", "alerts", "jobs"], + "maxHistoryItems": 20 + }, + "execution": { + "timeoutSec": 120, + "retryPolicy": "safe_retry", + "approvalMode": "stepwise" + }, + "audit": { + "logActions": true, + "logDelegation": true, + "logEscalation": true + } + }, + "memory": { + "workingMemory": {}, + "caseMemory": { "enabled": true, "window": 30 }, + "policyMemory": { "enabled": true }, + "skillMemory": { "enabled": true, "allowSkillGeneration": true } + }, + "status": { + "lifecycle": "active", + "health": "healthy", + "lastRunAt": "", + "lastReportAt": "", + "lastError": "" + }, + "presentation": { + "tier": "generic", + "summary": "跨服务器巡视、异常发现与风险上报", + "stage": "日常巡检", + "marketTag": "已安装", + "route": "/apps/server-patrol", + "color": "#409eff" + } +} +``` + +--- + +## 11. 面向 AI 的使用规则 + +如果另一个 AI 要生成 `DW / ADW` 配置，必须遵守以下规则。 + +### 11.1 必填规则 + +以下字段必须完整生成： + +- `kind` +- `specVersion` +- `identity.id` +- `identity.name` +- `identity.workerType` +- `identity.role` +- `bindings.sources` +- `capabilities.skills` +- `capabilities.actions` +- `governance.permissions` +- `presentation.route` + +### 11.2 ADW 额外规则 + +如果 `kind = "adw"`，则以下字段不得缺失： + +- `governance.rules.delegate` +- `governance.rules.escalate` +- `governance.rules.forbid` +- `governance.autonomy` +- `memory.policyMemory` +- `memory.skillMemory` + +### 11.3 禁止写法 + +禁止以下写法： + +1. 只给字符串数组，不给结构体字段 +例如只写： + +```json +"sources": ["servers", "stats"] +``` + +2. 用自然语言替代规则对象 +例如只写： + +```json +"escalate": "磁盘高了就上报" +``` + +3. 同时声明只读权限和高风险写动作，但不写审批规则 + +4. 把 `skills` 和 `actions` 合并成同一层 + +5. `ADW` 不提供自治等级 + +--- + +## 12. 面向本项目的落地映射 + +当前项目中已有的数据与本合同的关系如下： + +| 当前字段 | 新合同映射 | +|----------|------------| +| `worker_type` | `identity.workerType` | +| `permission_scope` | `governance.permissions` | +| `resource_bindings` | `bindings.sources / tools` 的简化表现 | +| `info_sources` | `bindings.sources` | +| `base_skills` | `capabilities.skills` | +| `ai_assistance` | `governance.autonomy` + `runtime.contextAssembly` 的简化表现 | +| `generated_skills` | `memory.skillMemory` + `capabilities.skills` 的派生能力 | +| `route / summary / stage / market_tag / color` | `presentation` | + +因此当前后端 `Specialist` 模型可以看作： + +- 第一阶段：`DW / ADW` 的轻量目录模型 +- 第二阶段：逐步扩展为完整合同模型 + +--- + +## 13. 后续实施建议 + +### 13.1 第一阶段 + +继续沿用当前 `Specialist` 表，但补充结构化 JSON 字段： + +- `identity_json` +- `bindings_json` +- `capabilities_json` +- `governance_json` +- `runtime_json` +- `memory_json` +- `presentation_json` +- `inputs_records_json` +- `permission_records_json` +- `action_records_json` +- `result_records_json` + +### 13.2 第二阶段 + +把当前 `workbench.js` 中与专员相关的工作区元数据逐步下沉到后端，并与 `presentation / runtime` 对齐。 + +### 13.3 第二阶段补充要求 + +把工作区 UI 明确拆成四块正式面板： + +- `InputsPanel` +- `PermissionsPanel` +- `ActionsPanel` +- `ResultsPanel` + +并要求右侧抽屉和底部运行面板与之联动。 + +### 13.4 第三阶段 + +在“专员市场 / 控制台”中支持： + +- 创建 DW +- 升级 DW 为 ADW +- 配置自治等级 +- 配置委派与升级规则 +- 查看技能沉淀记录 + +--- + +## 14. 最终结论 + +本项目正式采用以下判断： + +- `DWP` 是平台 +- `DW` 是数字员工基础形态 +- `ADW` 是高自治数字员工形态 + +本项目正式采用以下设计合同： + +- `DW / ADW` 必须是结构化对象 +- `ADW` 必须比 `DW` 多出自治、委派、升级和学习能力 +- 后续文档、模型、页面和接口，均以本合同为统一基准 diff --git a/docs/01_System_Overall/SY18_Specialist_Minimal_Definition_Model.md b/docs/01_System_Overall/SY18_Specialist_Minimal_Definition_Model.md new file mode 100644 index 0000000..2e875fd --- /dev/null +++ b/docs/01_System_Overall/SY18_Specialist_Minimal_Definition_Model.md @@ -0,0 +1,202 @@ +# SY18 — 专员最小定义模型（信源 / 动作 / 结果 / 权限） + +> **版本：V1.1 | 最后更新：2026-08-16** + +--- + +## 0. 文档目的 + +前端已经能展示「数字员工」，但呈现方式过于零碎——一上来就摆出六层架构、对象层、本体、连接器、工作流画布，业务用户看不懂、也用不起来。 + +本文把「专员」（数字员工）对业务用户的最小呈现定死为四件事： + +> **信源 → 动作 → 结果 → 权限** + +其余（对象层、本体、连接器、工作流运行时、证据、规则）一律属于「芯」，不进入业务前台。 + +本文是 SY04（六层架构）与 SY17（工作台 UI）之上的一层「对外心智模型」：**用户只看信源 / 动作 / 结果 / 权限，平台在后台跑六层内核。** + +--- + +## 1. 一句话模型 + +``` +专员 = 信源 + 动作 + 结果 + 权限 +``` + +| 组成 | 含义 | 业务用户怎么说 | +|------|------|----------------| +| **信源** | 它从哪里拿信息 | 「就一个：邮箱」「简历表」 | +| **动作** | 它对信息做什么（AI 辅助写成结构化步骤） | 「整理简历」「筛选评分」 | +| **结果** | 它产出什么、写回哪里 | 「刷新候选人到简历表」 | +| **权限** | 它能碰哪些数据、谁能碰它 | 「只读 HR 招聘邮箱，只写简历表」 | + +--- + +## 2. 案例：HR 的两个专员（canonical example） + +这是「数字员工平台」最小工作流的基准样例，用来判断任何前台设计是否过度复杂。 + +### 2.1 专员 1：HR 邮件整理专员 + +- **信源**：邮箱（收件箱，就这一个） +- **动作**： + 1. 识别简历邮件（主题 / 正文 / 附件含「简历 / 应聘 / 候选人」） + 2. 提取候选人信息（姓名、电话、应聘岗位、简历附件） + 3. 去重归类（同发件人 / 同附件去重） +- **结果**：刷新候选人 → **「简历表」** +- **权限**：读「HR 招聘邮箱」（非全公司邮箱）；写「简历表」（非「薪资表」）；HR 团队可用 + +### 2.2 专员 2：简历处理专员 + +- **信源**：**简历表**（= 专员 1 的结果） +- **动作**： + 1. 筛选（是否满足岗位要求） + 2. 评分 / 排序 + 3. 标记跟进（待联系 / 已联系 / 淘汰） +- **结果**：→ **「面试安排 / 候选人跟进表」** +- **权限**：读「简历表」（仅本部门候选人）；写「跟进表」；HR 主管可用 + +### 2.3 两个专员首尾相接 = 一条直接的工作流 + +``` +[邮箱] ──HR 邮件整理专员──▶ [简历表] ──简历处理专员──▶ [面试安排 / 跟进表] + 信源=邮箱 结果=简历表 信源=简历表 结果=跟进表 +``` + +--- + +## 3. 关键洞察：工作流 = 「表」在专员之间传递 + +两个专员能接上，靠的是**「简历表」同时是「结果」和「信源」**。 + +由此得出三条简化结论： + +1. **「表」（业务对象）就是专员之间的接口。** 结果和信源天然是同一张表，不存在额外「连线」。 +2. **工作流不需要画布。** 只需要回答「谁的结果喂给谁」，因为上游的「结果」就是下游的「信源」。 +3. **「表」是业务用户本来就有的心智**（「简历表」「候选人表」），比「本体类 / 对象字典」亲切得多。 + +这正把 SY04 / SY17 里那套六层架构一次性收进后台，前台坍缩成三样。 + +--- + +## 4. 权限模型：最小读写范围 + 使用范围 + +权限是专员的第四根柱子，分两层，都遵循**最小权限原则**——多一分都不给。 + +### 4.1 数据权限（专员能碰什么） + +由信源和结果各自界定，专员只能在其声明的范围内读写： + +| 维度 | 界定 | 例 | +|------|------|-----| +| **信源读范围** | 读哪个邮箱 / 哪张表 / 哪个行级范围 | 只读「HR 招聘邮箱」，不是全公司邮箱 | +| **结果写范围** | 写哪张表 / 哪个范围 | 只写「简历表」，不是「薪资表」 | + +一句话：**专员能读的，只有它声明的信源；能写的，只有它声明的结果。** 越界即拒绝。 + +### 4.2 使用权限（谁能碰专员） + +谁可以配置 / 调用 / 查看这个专员，对齐 SY03 §14 的四级角色： + +| 角色 | 能对专员做什么 | +|------|----------------| +| 平台管理员 | 建模板、设底线规则、租户级安全策略 | +| 客户管理员 | 建 / 改 / 发布客户自己的专员，审批 | +| 部门管理员 | 基于模板做部门级配置，调权限范围 | +| 普通用户 | 仅调用被授权可用的专员，收藏 / 复制个人版 | + +### 4.3 权限跟着信源 / 结果走，不跟着「人设」走 + +专员的权限不是单独拍脑袋配的，而是**由信源和结果的访问边界自动导出**： + +- 专员 1 声明了「信源 = HR 招聘邮箱」「结果 = 简历表」，它的数据权限就正好是「读邮箱 + 写简历表」； +- 想扩大权限，只能改信源 / 结果，不能给专员额外开一个「后台万能权限」。 + +这样既极简、又可审计：**看一个专员的信源和结果，就知道它能碰什么。** + +--- + +## 5. 动作的 AI 辅助写法（关键） + +用户只写一句自然语言，AI 把它展开成结构化动作定义，用户**只确认、不画图**。 + +``` +用户写：整理简历 +AI 展开： + · 信源字段：发件人 / 主题 / 正文 / 附件 + · 抽取字段：姓名、电话、应聘岗位、简历附件 + · 规则：同邮箱去重、附件限 pdf/doc + · 写回：候选人表（新增或更新） + · 权限：读「HR 招聘邮箱」，写「简历表」 +[一键确认] +``` + +这把「动作定义」从「画节点」变成「说人话 + AI 补全」，是前台能否保持极简的前提。权限与信源 / 结果一并由 AI 补出，用户只改需要改的边界。 + +--- + +## 6. 前台极简显示 + +### 6.1 专员卡片 = 三行（权限不进卡片） + +``` +┌─────────────────────┐ +│ HR 邮件整理专员 │ +│ 信源：邮箱 │ +│ 动作：整理简历、去重… │ +│ 结果：→ 简历表 │ +└─────────────────────┘ +``` + +权限在配置时声明、后台强制；卡片保持三行，点开专员再在「可访问范围」里看到「读 HR 招聘邮箱 / 写简历表」。 + +### 6.2 专员链 = 卡片 + 箭头 + +``` +┌──────────────┐ ┌──────────────┐ +│ HR 邮件整理专员│ ───▶ │ 简历处理专员 │ +│ 信源：邮箱 │ 简历表 │ 信源：简历表 │ +│ 动作：整理简历 │ │ 动作：筛选评分│ +│ 结果：→ 简历表 │ │ 结果：→ 跟进表│ +└──────────────┘ └──────────────┘ +``` + +- 箭头 = 「结果表 == 下一个信源表」，自动生成，用户不需要手工连线。 +- 点开**专员**才看动作明细与权限范围；点开**箭头**才看「这张表在专员之间怎么流转」。 +- **不要一进来就是六层工作台。** + +### 6.3 不设常驻「上下文抽屉」 + +SY17 早期的右侧「上下文抽屉」（Outputs / Artifacts / Evidence / Risks）**从业务前台移除**——这几个词是「芯」的语言，业务用户听不懂、也用不上： + +- 用户真正关心的「结果」就是那张**共享表**（简历表），已经在卡片和箭头上可见； +- 「证据 / 风险 / 审计 / 回放」**按需进后台 / 控制台**，只有发生人工确认、越权、异常时再打开，不作为常驻栏。 + +一句话：**业务前台只有「卡片 + 箭头 + 表」，没有常驻抽屉。** + +--- + +## 7. 边界清单（「芯」不许暴露给业务用户） + +以下内容属于平台内核，只进后台 / 工坊 / 控制台，绝不进入业务前台的专员卡片与专员链： + +| 内核概念 | 用户看到的是 | 而不是 | +|----------|--------------|--------| +| 对象层 / 本体 | 「简历表」 | 「本体类 / 对象字典」 | +| 连接器 | 「信源 = 邮箱」 | 「IMAP / Exchange 连接器」 | +| 工作流运行时 | 「结果表 = 下一个信源表」 | 「工作流画布 / 节点编排」 | +| 规则 | 动作里已隐含（如「同邮箱去重」） | 单独一栏「规则库」 | +| 权限 | 配置时声明、后台强制 | 前台卡片常驻展示 | +| 证据 / 引用 / 审计 | 需要时再看（后台） | 常驻右侧抽屉 | + +--- + +## 8. 与现有文档的关系 + +- **本文是「壳」**：定义专员对业务用户的最小呈现（信源 / 动作 / 结果 / 权限 + 表传递）。 +- **SY04 是「芯」**：六层架构、本体层、共享对象层、任务系统、工坊装配。 +- **SY17 是「壳」的载体**：工作台 UI；本文把它的一级呈现从「知识库 + 我的应用 + 对象/证据/规则/画布」收窄为「专员卡片 + 专员链」。 +- **SY03 §14 是权限底座**：平台管理员 / 客户管理员 / 部门管理员 / 普通用户四级角色，专员的「使用权限」对齐它。 + +后续做前端时，以本文为「简化验收标准」：**如果一个专员无法用三行（信源 / 动作 / 结果）说清、且权限说不出「能读什么 / 能写什么 / 谁能用」，说明设计过重了。** diff --git a/docs/02_Architecture/AR01_Backend_Arch.md b/docs/02_Architecture/AR01_Backend_Arch.md new file mode 100644 index 0000000..9bec288 --- /dev/null +++ b/docs/02_Architecture/AR01_Backend_Arch.md @@ -0,0 +1,173 @@ +# AR01 — 后端架构设计 + +> **版本：V1.1 | 框架：FastAPI + SQLAlchemy + MySQL 8.0** +> **参考：pj006-zhilianyuan2 的 BE01_backend_arch + main.py 装配模式** +> +> **⚠️ 本文档为 V1.1 设计期历史快照，不再反映当前实现。** 后端已重写为 **Go + Gin + GORM + MySQL 8.0 + FAISS**，以 `docs/changelog.md`（V1.2）、`docs/db_schema.md`、`docs/deploy.md` 为准；下文 FastAPI/Python 结构与 `backend/` 路径仅作设计参考。 + +--- + +## 1. 架构分层 + +``` +┌─────────────────────────────────────────────┐ +│ API 路由层 (routes) │ +│ auth / company_train / product / course │ +│ exam / media / ai_chat / system │ +├─────────────────────────────────────────────┤ +│ Pydantic 模型层 (schemas) │ +│ 请求/响应模型，统一响应格式 Envelope │ +├─────────────────────────────────────────────┤ +│ 服务层 (services) │ +│ exam_service / media_service / ai_service │ +├─────────────────────────────────────────────┤ +│ SQLAlchemy ORM 模型层 (models) │ +│ User / Product / Course / MediaFile / ... │ +├─────────────────────────────────────────────┤ +│ 核心层 (core) │ +│ config / security / deps │ +├─────────────────────────────────────────────┤ +│ MySQL 8.0 + data/media │ +└─────────────────────────────────────────────┘ +``` + +## 2. 目录结构 + +``` +backend/ +├── app/ +│ ├── main.py # FastAPI 应用装配 + CORS + 异常处理 +│ ├── api/ # 路由层 +│ │ ├── auth.py # /api/auth/* — 登录/注册/me +│ │ ├── company_train.py # /api/company-train/* +│ │ ├── product.py # /api/products/* +│ │ ├── sales_train.py # /api/courses/* +│ │ ├── exam.py # /api/exam/* — 题库/组卷/考试/记录 +│ │ ├── media.py # /api/media/* — 上传/预览/审批 +│ │ ├── ai_chat.py # /api/ai-chat/* — PathCoach SSE +│ │ └── system.py # /api/system/* — 用户/成绩/配置 +│ ├── models/ # SQLAlchemy ORM 模型 +│ │ ├── user.py +│ │ ├── product.py +│ │ ├── course.py +│ │ ├── media_file.py +│ │ ├── knowledge_chunk.py +│ │ ├── question.py +│ │ ├── exam_paper.py +│ │ └── exam_record.py +│ ├── schemas/ # Pydantic 请求/响应模型 +│ ├── services/ # 业务逻辑层 +│ │ ├── media_service.py # 上传/转换/提取 +│ │ ├── ai_service.py # LLM 调用 + 知识检索 +│ │ └── exam_service.py # 题库/组卷/判分/记录 +│ ├── core/ # 核心基础设施 +│ │ ├── config.py # .env + 系统参数读取 +│ │ ├── security.py # JWT 签发/校验 + bcrypt +│ │ └── deps.py # FastAPI Depends（get_db / get_current_user） +│ └── utils/ # 工具函数 +├── data/media/ # 文件存储（git忽略） +│ ├── upload/ +│ └── _preview_cache/ +├── requirements.txt +└── .env +``` + +## 3. 应用装配模式（main.py） + +参考 zhilianyuan2 的模式，每个模块的 router 独立注册： + +```python +from fastapi import FastAPI +from app.api import auth, company_train, product, sales_train +from app.api import exam, media, ai_chat, system + +app = FastAPI(title="eaisalestrain_app", version="1.1.0") + +# 异常处理器 +@app.exception_handler(AppError) +def handle_app_error(request, exc): + return JSONResponse(status_code=exc.status_code, content={...}) + +# 路由注册 +app.include_router(auth.router) +app.include_router(company_train.router) +app.include_router(product.router) +app.include_router(sales_train.router) +app.include_router(exam.router) +app.include_router(media.router) +app.include_router(ai_chat.router) +app.include_router(system.router) +``` + +## 4. 依赖注入模式 + +参考 zhilianyuan2 的 `auth/dependencies.py`： + +```python +# core/deps.py +async def get_current_user( + credentials: HTTPAuthorizationCredentials | None = Depends(HTTPBearer(auto_error=False)), + db: Session = Depends(get_db), +) -> User: + """解析 JWT → 校验用户状态 → 返回 User""" + if credentials is None: + raise AuthError("缺少 Authorization Bearer 令牌") + payload = decode_access_token(credentials.credentials, settings) + user = db.query(User).filter(User.username == payload["sub"]).first() + if user is None or user.status != "active": + raise AuthError("用户不存在或已禁用") + return user + +def require_admin(user: User = Depends(get_current_user)) -> User: + """管理员角色守卫""" + if user.role != "admin": + raise ForbiddenError("需要管理员权限") + return user +``` + +## 5. API 路由前缀 + +| 路由前缀 | 模块 | 说明 | +|---------|------|------| +| `/api/auth/*` | auth | 登录/注册/当前用户 | +| `/api/company-train/*` | company_train | 公司介绍内容 | +| `/api/products/*` | product | 产品 CRUD + 导入 | +| `/api/courses/*` | sales_train | 课程 CRUD + 绑定产品 | +| `/api/exam/*` | exam | 题库/组卷/考试/记录 | +| `/api/media/*` | media | 上传/预览/审批/状态 | +| `/api/ai-chat/*` | ai_chat | PathCoach 流式对话 | +| `/api/system/*` | system | 用户/成绩/配置 | +| `/api/health` | — | 健康检查 | + +## 6. 异步任务模式 + +文档转换管线（审批通过后异步执行）： + +```python +# services/media_service.py +import threading + +def _async_convert_and_extract(media_file_id: int): + """审批通过后异步执行：文档转 PDF → 文本提取 → 切片入库""" + with Session() as db: + media = db.query(MediaFile).get(media_file_id) + # 1. 调用 LibreOffice 转 PDF + pdf_path = libreoffice_convert(media.stored_path) + # 2. PyMuPDF 提取文本 + text = pymupdf_extract(pdf_path) + # 3. 按段落切片写入 knowledge_chunk + chunks = split_into_chunks(text) + for i, chunk in enumerate(chunks): + db.add(KnowledgeChunk(media_file_id=media.id, ...)) + media.extracted = True + db.commit() + +def approve_media(media_file_id: int, auditor_id: int): + """审批通过 → 触发异步转换""" + media.status = "approved" + media.audit_by = auditor_id + media.audit_at = datetime.utcnow() + db.commit() + # 启动异步任务 + threading.Thread(target=_async_convert_and_extract, args=(media_file_id,)).start() +``` \ No newline at end of file diff --git a/docs/02_Architecture/AR02_Frontend_Arch.md b/docs/02_Architecture/AR02_Frontend_Arch.md new file mode 100644 index 0000000..373b458 --- /dev/null +++ b/docs/02_Architecture/AR02_Frontend_Arch.md @@ -0,0 +1,175 @@ +# AR02 — 前端架构设计 + +> **版本：V1.1 | 左导航 + 中间工作区 + 右 AI 侧栏 | Vue3 + Vite + Element Plus** +> **参考：pj006-zhilianyuan2 frontend-orgadmin 三栏布局模式** + +--- + +## 1. 目录结构 + +``` +frontend/ +├── public/ +│ └── static-lib/ # 本地 pdf.js（无 CDN） +├── src/ +│ ├── api/ # API 调用层（axios 封装） +│ │ ├── auth.js +│ │ ├── product.js +│ │ ├── course.js +│ │ ├── exam.js +│ │ ├── media.js +│ │ ├── aiChat.js +│ │ └── system.js +│ ├── components/ # 通用组件 +│ │ └── MaterialSuggestUpload.vue # 员工提交素材弹窗 +│ ├── layout/ # 全局布局 +│ │ ├── MainLayout.vue # 三栏布局（左导航 + 内容 + AI 侧栏） +│ │ ├── SideNav.vue # 左边栏导航（含品牌 + 菜单 + 用户信息） +│ │ └── PathCoachPanel.vue # 右侧 AI 聊天框 +│ ├── router/ # 路由 +│ │ ├── index.js # 路由定义 +│ │ └── guards.js # 路由守卫（角色/认证） +│ ├── store/ # 状态管理（Pinia） +│ │ ├── auth.js # 用户认证状态 +│ │ └── aiChat.js # AI 聊天会话 +│ ├── views/ # 页面视图 +│ │ ├── home/ # 首页 +│ │ ├── companyTrain/ # 公司介绍培训 +│ │ ├── product/ # 产品知识 +│ │ ├── salesTrain/ # 产品销售培训 +│ │ ├── exam/ # 考试 +│ │ ├── knowledge/ # 管理员-知识管理 +│ │ └── system/ # 管理员-系统管理 +│ ├── App.vue +│ └── main.js +├── index.html +├── vite.config.js +└── package.json +``` + +## 2. 布局结构 + +``` +┌──────┬───────────────────────────────────────┬────────────────┐ +│ 导航 │ │ │ +│ ───── │ 主工作区 │ AI PathCoach │ +│ 品牌 │ │ ──────────── │ +│ │ │ 消息列表 │ +│ 首页 │ │ │ +│ 公司 │ │ [输入] [发送] │ +│ 产品 │ │ │ +│ 销售 │ │ [情景演练] │ +│ 考试▼ │ │ [查佣金] │ +│ │ │ [产品对比] │ +│ ───── │ │ │ +│ 知识▼ │ ← admin only │ │ +│ 系统▼ │ ← admin only │ │ +│ │ │ │ +│ ───── │ │ │ +│ 用户 │ [退出] │ │ +└──────┴───────────────────────────────────────┴────────────────┘ +``` + +收起 AI 面板状态：左边导航不变，主内容区占满剩余宽度，右下角浮动 [🤖 展开AI] 按钮。 + +## 3. 路由设计 + +| 路径 | 视图 | 角色 | 说明 | +|------|------|------|------| +| `/` | Home | all | 首页 | +| `/company-train` | CompanyTrain | all | 公司介绍培训 | +| `/products` | ProductList | all | 产品列表 | +| `/products/:id` | ProductDetail | all | 产品详情 | +| `/courses` | CourseList | all | 课程列表 | +| `/courses/:id` | CourseDetail | all | 课程详情 | +| `/exam/self-test` | ExamSelfTest | all | 自测练习 | +| `/exam/formal` | ExamFormal | all | 正式结业考试 | +| `/exam/my-records` | ExamMyRecord | all | 我的考试记录 | +| `/exam/questions` | ExamQuestionBank | admin | 题库管理 | +| `/knowledge/materials` | MaterialManage | admin | 课件素材管理 | +| `/knowledge/audit` | MaterialAuditList | admin | 素材审批列表 | +| `/system/users` | UserManage | admin | 用户账号管理 | +| `/system/exam-records` | ExamRecordManage | admin | 全部考试成绩 | +| `/system/config` | SystemConfig | admin | 系统参数配置 | + +## 4. 路由守卫 + +```javascript +// router/guards.js +import { useAuthStore } from '@/store/auth' + +router.beforeEach((to, from, next) => { + if (to.path === '/login') { + next() + return + } + + const authStore = useAuthStore() + + // 未登录 → 跳转登录页 + if (!authStore.isLoggedIn) { + return next('/login') + } + + // 管理员路由校验（前端仅作 UX 隐藏，非安全边界） + if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') { + return next('/') + } + + next() +}) +``` + +## 5. API 调用模式 + +```javascript +// api/http.js — axios 封装 +import axios from 'axios' +import { ElMessage } from 'element-plus' + +const http = axios.create({ baseURL: '/api' }) + +http.interceptors.request.use(config => { + const token = localStorage.getItem('token') + if (token) config.headers.Authorization = `Bearer ${token}` + return config +}) + +http.interceptors.response.use( + res => res.data.data, // 解包 Envelope + err => { + const resp = err.response + if (resp?.status === 401) { + localStorage.removeItem('token') + window.location.href = '/login' + } else if (resp?.status === 501) { + // LLM 未配置等服务器配置错误 + ElMessage.error(resp.data?.message || '服务未配置，请联系管理员') + } + return Promise.reject(resp?.data) + } +) + +export default http +``` + +## 6. AI 聊天状态管理 + +```javascript +// store/aiChat.js +import { defineStore } from 'pinia' + +export const useAiChatStore = defineStore('aiChat', { + state: () => ({ + visible: true, // 是否展开 + messages: [], // 对话历史 + context: null, // 当前页面上下文（productId/courseId） + isStreaming: false, // 是否正在流式响应 + }), + actions: { + toggle() { this.visible = !this.visible }, + setContext(ctx) { this.context = ctx }, + clearMessages() { this.messages = [] }, + } +}) +``` \ No newline at end of file diff --git a/docs/02_Architecture/AR03_Database_Arch.md b/docs/02_Architecture/AR03_Database_Arch.md new file mode 100644 index 0000000..4e7a258 --- /dev/null +++ b/docs/02_Architecture/AR03_Database_Arch.md @@ -0,0 +1,83 @@ +# AR03 — 数据库架构设计 + +> **版本：V1.1 | 引擎：MySQL 8.0 | ORM：SQLAlchemy（现为 GORM）** +> **完整建表 SQL 请见 docs/db_schema.md** +> +> **⚠️ 本文档为 V1.1 设计期历史快照。** 当前实现已切换为 **MySQL 8.0 + FAISS 向量检索**（ORM 由 SQLAlchemy 改为 GORM），并新增岗位/积分/证书/部门/消息等表，以 `docs/db_schema.md` 与 `docs/changelog.md`（V1.4–V1.7）为准。 + +--- + +## 1. ER 关系总图 + +``` +user ──< media_file (submitter_id / audit_by) +user ──< exam_record (user_id) +product ──< course (related_product_id) +course ──< question (course_id, optional) +media_file ──< knowledge_chunk (media_file_id) +exam_paper ──< exam_record (paper_id) +``` + +## 2. 表清单 + +| # | 表名 | 说明 | 核心字段数 | +|---|------|------|-----------| +| 1 | `user` | 用户账号 | 7 | +| 2 | `product` | 产品信息 | 16 | +| 3 | `course` | 课程内容 | 16 | +| 4 | `media_file` | 素材文件元数据 | 16 | +| 5 | `knowledge_chunk` | AI 知识库文本块 | 6 | +| 6 | `question` | 题库题目 | 11 | +| 7 | `exam_paper` | 考试配置/组卷 | 11 | +| 8 | `exam_record` | 考试记录档案 | 12 | +| 9 | `system_config` | 系统参数配置 | 4 | + +## 3. 索引策略 + +| 表 | 索引 | 类型 | 说明 | +|----|------|------|------| +| `user` | `role`, `status` | BTREE | 角色筛选、状态筛选 | +| `product` | `category`, `status` | BTREE | 分类筛选、状态筛选 | +| `course` | `category`, `status`, `related_product_id` | BTREE | 同上 | +| `media_file` | `status`, `submitter_id`, `(bind_type, bind_id)`, `extracted` | BTREE | 审批列表、绑定查询、提取状态 | +| `knowledge_chunk` | `media_file_id` | BTREE | 关联查询 | +| `knowledge_chunk` | `content` | **FULLTEXT** | AI 知识检索（MySQL 全文索引） | +| `question` | `domain`, `course_id`, `status` | BTREE | 知识域筛选、课程筛选 | +| `exam_paper` | `type`, `status` | BTREE | 考试类型筛选 | +| `exam_record` | `user_id`, `paper_id`, `passed`, `submitted_at` | BTREE | 用户查记录、管理员查全部 | +| `system_config` | `config_key` | UNIQUE | 键查值 | + +## 4. AI 知识检索说明 + +V1.1 使用 **MySQL 全文索引**（FULLTEXT）；现已升级为 **MySQL 全文索引（关键词）+ FAISS 向量检索（语义）双路混合召回**： + +```sql +-- knowledge_chunk 表已建全文索引（关键词召回） +FULLTEXT INDEX ft_kc_content (content) + +-- 检索查询 +SELECT * FROM knowledge_chunk +WHERE MATCH(content) AGAINST(:keywords IN NATURAL LANGUAGE MODE) +LIMIT 10 +``` + +**检索流程（当前）：** +1. 用户提问 → 关键词 + embedding 向量 +2. MySQL FULLTEXT 关键词召回 + FAISS 语义向量召回，双路融合排序 +3. 匹配段落作为上下文注入 LLM Prompt +4. LLM 基于上下文生成回答 + +> **演进说明：** V1.1 曾为避免 embedding 依赖而仅用全文索引；平台升级后引入 FAISS 补足语义召回，见 `docs/db_schema.md`。 + +## 5. 文件存储策略 + +- **数据库只存元数据**，不存文件二进制 +- 物理文件存储在 `backend/data/media/` +- 目录结构： + ``` + data/media/ + ├── upload/ # 上传文件存储（UUID 重命名） + └── _preview_cache/ # 预览缓存（LibreOffice 转 PDF 后存放） + ``` +- 文件命名：UUID 重命名，杜绝路径穿越 +- 文件扩展名白名单：ppt / pptx / pdf / doc / docx / mp4 / png / jpg / jpeg \ No newline at end of file diff --git a/docs/02_Architecture/AR04_Deploy_Arch.md b/docs/02_Architecture/AR04_Deploy_Arch.md new file mode 100644 index 0000000..1ff5169 --- /dev/null +++ b/docs/02_Architecture/AR04_Deploy_Arch.md @@ -0,0 +1,140 @@ +# AR04 — 部署架构设计 + +> **版本：V1.1 | 部署模式：纯本地离线** +> **完整部署步骤请见 docs/deploy.md** +> +> **⚠️ 本文档为 V1.1 设计期历史快照（Docker + FastAPI 拓扑），不再反映当前实现。** 当前部署为 **Go 单二进制 + MySQL 8.0 + FAISS + systemd + Clonezilla 整盘克隆**，无 Docker、无 Python 运行时，以 `docs/deploy.md` 为准。 + +--- + +## 1. 部署拓扑 + +``` + ┌──────────────────────┐ + │ 内网员工浏览器 │ + │ http://train.bosun │ + └──────────┬───────────┘ + │ + ┌─────▼──────┐ + │ Nginx │ + │ :80 / :443 │ + │ │ + │ · 前端静态 │ + │ · API 反代 │ + │ · SSE 支持 │ + └──┬──────┬──┘ + │ │ + ┌──────────────┘ └──────────────┐ + │ │ + ┌─────▼──────┐ ┌────────▼────────┐ + │ FastAPI │ │ Vue 静态打包 │ + │ :8000 │ │ nginx html/ │ + │ │ └─────────────────┘ + │ · JWT │ + │ · 业务 │ + └──┬──┬──┬──┘ + │ │ │ + ┌───────────┘ │ └──────────────┐ + │ │ │ +┌──▼─────┐ ┌────▼───────┐ ┌──────▼──────────┐ +│ MySQL │ │ data/media │ │ LibreOffice │ +│ 8.0 │ │ 文件存储 │ │ 预览容器 │ +│ :3306 │ │ │ │ :8100 │ +└────────┘ └────────────┘ └─────────────────┘ + │ + │ (文档转换) + ▼ + ┌──────────────┐ + │ 内网 LLM │ + │ Ollama/ │ + │ vLLM/网关 │ + │ :11434 │ + └──────────────┘ +``` + +## 2. 服务清单 + +| 服务 | 端口 | 基础镜像/依赖 | 说明 | +|------|------|-------------|------| +| Nginx | 80/443 | nginx:alpine | HTTP 反代 + 前端静态资源 | +| FastAPI | 8000 | python:3.10 | 后端 API（uvicorn 启动） | +| MySQL | 3306 | mysql:8.0 | 数据库 | +| LibreOffice | 8100 | 自定义 Docker 镜像 | 文档转 PDF 预览 | +| LLM 服务 | 11434 | ollama/vllm | 内网 AI 推理 | + +## 3. Nginx 关键配置 + +```nginx +# SPA 路由 +location / { + try_files $uri $uri/ /index.html; +} + +# API 反代 + SSE +location /api/ { + proxy_pass http://127.0.0.1:8000; + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 300s; +} + +# 媒体文件预览（仅内部） +location /media/ { + alias /opt/eaisalestrain/backend/data/media/; + internal; +} + +client_max_body_size 2048M; +``` + +## 4. docker-compose 服务拓扑 + +```yaml +version: '3.8' +services: + mysql: + image: mysql:8.0 + environment: + MYSQL_DATABASE: eaisalestrain + MYSQL_USER: eaisalestrain + MYSQL_PASSWORD: ${DB_PASSWORD} + volumes: + - mysql_data:/var/lib/mysql + + backend: + build: ./backend + environment: + DATABASE_URL: mysql+pymysql://eaisalestrain:${DB_PASSWORD}@mysql:3306/eaisalestrain + JWT_SECRET: ${JWT_SECRET} + LLM_BASE_URL: http://llm-server:11434/v1 + volumes: + - ./data/media:/app/data/media + depends_on: + - mysql + + libreoffice: + image: libreoffice-preview:latest + volumes: + - ./data/media:/data/media + + nginx: + image: nginx:alpine + ports: + - "80:80" + volumes: + - ./frontend/dist:/usr/share/nginx/html + - ./nginx.conf:/etc/nginx/conf.d/default.conf + depends_on: + - backend +``` + +## 5. 安全边界 + +| 层级 | 措施 | +|------|------| +| 网络 | 仅监听内网，不暴露公网端口 | +| 认证 | JWT token 校验 + bcrypt 密码 | +| 鉴权 | 后端 API role 校验（非前端） | +| 文件 | 白名单扩展名 + UUID 命名 + 只读预览 | +| 数据库 | 独立用户 + 最小权限 | +| LLM | 仅内网地址，严禁公网 API | \ No newline at end of file diff --git a/docs/02_Architecture/README.md b/docs/02_Architecture/README.md new file mode 100644 index 0000000..a576135 --- /dev/null +++ b/docs/02_Architecture/README.md @@ -0,0 +1,16 @@ +# 02_Architecture — 架构设计 + +> **命名规则：** `AR{NN}_{描述}.md` +> **用途：** 后端架构、前端架构、数据库架构、部署架构 +> +> **⚠️ 本目录 AR 文档为 V1.1 设计期历史快照。** 当前实现已重写为 **Go + Gin + GORM + MySQL 8.0 + FAISS**，以 `docs/changelog.md`、`docs/db_schema.md`、`docs/deploy.md` 为准。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `AR01_Backend_Arch.md` | 后端架构（V1.1 FastAPI 快照；现为 Go + Gin + GORM） | +| `AR02_Frontend_Arch.md` | 前端架构（Vue3 + Element Plus 三栏布局） | +| `AR03_Database_Arch.md` | 数据库架构（MySQL 8.0 + FAISS 向量检索） | +| `AR04_Deploy_Arch.md` | 部署架构（V1.1 Docker 快照；现为单二进制 + systemd） | diff --git a/docs/04_Backend/BE01_Auth_Module.md b/docs/04_Backend/BE01_Auth_Module.md new file mode 100644 index 0000000..301f97a --- /dev/null +++ b/docs/04_Backend/BE01_Auth_Module.md @@ -0,0 +1,155 @@ +# BE01 — 认证模块设计 + +> **版本：V1.1 | 技术：JWT（python-jose）+ bcrypt | 参考：pj006-zhilianyuan2 auth/security.py + dependencies.py** + +--- + +## 1. 模块职责 + +- 用户注册（仅管理员可创建账号） +- 密码登录 → JWT 签发 +- Token 校验 + 用户状态检查 +- 角色守卫（普通用户 / 管理员） + +## 2. 核心流程 + +``` +POST /api/auth/login + → 校验 username + password + → bcrypt verify + → 签发 JWT（含 sub=username, role, exp） + → 返回 { token, expires_in, user } + +GET /api/auth/me + → Authorization: Bearer + → 解码 JWT → 校验用户状态 + → 返回用户信息 +``` + +## 3. 密码哈希（参考 zhilianyuan2 模式） + +```python +# core/security.py +from passlib.context import CryptContext + +pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto") + +def hash_password(password: str) -> str: + return pwd_context.hash(password) + +def verify_password(password: str, hashed: str) -> bool: + return pwd_context.verify(password, hashed) +``` + +## 4. JWT 签发与校验 + +```python +# core/security.py +from jose import jwt, JWTError +from datetime import datetime, timedelta, timezone + +def create_access_token( + *, subject: str, role: str, settings: Settings +) -> str: + issued_at = datetime.now(timezone.utc) + payload = { + "sub": subject, + "role": role, + "iat": issued_at, + "exp": issued_at + timedelta(minutes=settings.jwt_expire_minutes), + } + return jwt.encode(payload, settings.jwt_secret, algorithm="HS256") + +def decode_access_token(token: str, settings: Settings) -> dict: + try: + return jwt.decode(token, settings.jwt_secret, algorithms=["HS256"]) + except JWTError as e: + raise AuthError(f"令牌无效或已过期：{e}") +``` + +## 5. 依赖注入（参考 zhilianyuan2 dependencies.py） + +```python +# core/deps.py +from fastapi import Depends +from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials + +async def get_current_user( + credentials: HTTPAuthorizationCredentials | None = Depends( + HTTPBearer(auto_error=False) + ), + db: Session = Depends(get_db), + settings: Settings = Depends(get_settings), +) -> User: + """解析 JWT + 校验用户状态""" + if credentials is None: + raise AuthError("缺少 Authorization Bearer 令牌") + payload = decode_access_token(credentials.credentials, settings) + username = payload.get("sub") + user = db.query(User).filter(User.username == username).first() + if user is None: + raise AuthError("用户不存在") + if user.status != "active": + raise AuthError("账号已禁用") + return user + +def require_admin(current_user: User = Depends(get_current_user)) -> User: + """管理员角色守卫""" + if current_user.role != "admin": + raise ForbiddenError("需要管理员权限") + return current_user +``` + +## 6. API 路由 + +```python +# api/auth.py +from fastapi import APIRouter, Depends +from pydantic import BaseModel + +router = APIRouter(prefix="/api/auth", tags=["auth"]) + +class LoginRequest(BaseModel): + username: str + password: str + +class TokenResponse(BaseModel): + token: str + expires_in: int + user: UserPublic + +@router.post("/login") +def login(request: LoginRequest, settings: SettingsDep): + user = authenticate(request.username, request.password) + token = create_access_token(subject=user.username, role=user.role, settings=settings) + return {"data": { + "token": token, + "expires_in": settings.jwt_expire_minutes * 60, + "user": UserPublic.from_orm(user), + }} + +@router.get("/me") +def me(current_user: CurrentUser): + return {"data": UserPublic.from_orm(current_user)} +``` + +## 7. 数据表 + +```sql +CREATE TABLE user ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + username VARCHAR(64) NOT NULL UNIQUE, + password_hash VARCHAR(256) NOT NULL, + full_name VARCHAR(64) NOT NULL, + role ENUM('employee','admin') NOT NULL DEFAULT 'employee', + status ENUM('active','disabled') NOT NULL DEFAULT 'active', + created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), + updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) +); +``` + +## 8. 安全约束 + +- 禁用账号即时失效：token 校验时检查 status +- 前端路由守卫仅作 UX 隐藏，不以之为安全边界 +- 所有权限以后端鉴权为准 \ No newline at end of file diff --git a/docs/04_Backend/BE02_Exam_Module.md b/docs/04_Backend/BE02_Exam_Module.md new file mode 100644 index 0000000..942f7d2 --- /dev/null +++ b/docs/04_Backend/BE02_Exam_Module.md @@ -0,0 +1,136 @@ +# BE02 — 考试模块设计 + +> **版本：V1.1 | 参考：pj006-zhilianyuan2 exam/routes.py + exam/service.py** + +--- + +## 1. 模块职责 + +- 题库管理（管理员 CRUD） +- 考试配置/组卷（管理员设置） +- 学员端考试（开始/答题/交卷/判分） +- 考试记录与回溯 + +## 2. 考试流程 + +``` +管理员端： + 录入题目 → 配置考试（名称/类型/题量/总分/合格线/时长/随机） + +员工端： + 考试列表 → 查看封面/说明 → 开始考试 → 答题 → 交卷 + ↓ ↓ + 自测：即时显示对错+答案 正式考：存档（得分/明细/是否通过） +``` + +## 3. 数据表关系 + +``` +question（题库）← exam_paper（考试配置，通过 domain+question_count 抽题） + ↓ + exam_record（每次交卷的记录） +``` + +## 4. 题库 API + +```python +# 管理员 — 题目 CRUD +GET /api/exam/questions?domain=company&status=active # 题目列表 +POST /api/exam/questions # 新增题目 +PUT /api/exam/questions/{id} # 编辑题目 +DELETE /api/exam/questions/{id} # 停用题目 + +# 管理员 — 考试配置 +GET /api/exam/papers # 考试配置列表 +POST /api/exam/papers # 创建考试 +PUT /api/exam/papers/{id} # 编辑考试 +DELETE /api/exam/papers/{id} # 停用考试 +``` + +## 5. 学员端考试 API + +```python +GET /api/exam/list # 我的考试列表 +GET /api/exam/cover?id={paperId} # 考试封面/说明 +POST /api/exam/start # 开始考试 → 下发题目 +POST /api/exam/submit # 交卷判分 +GET /api/exam/record # 我的考试记录 +GET /api/exam/record/{recordId} # 考试记录详情 +``` + +## 6. 判分逻辑（参考 zhilianyuan2 _is_correct） + +```python +# services/exam_service.py + +def _is_correct(qtype: str, correct: list, user: any) -> bool: + """确定性判分""" + if qtype == "multiple": # 多选题：集合相等 + return sorted(correct) == sorted(user) if user else False + elif qtype == "judge": # 判断题：值相等 + return str(correct).lower() == str(user).lower() + else: # 单选题：值相等 + return correct == user + +def grade_paper(questions: list, answers: dict) -> dict: + """批卷：逐题比对 → 统计得分/正确数""" + correct_count = 0 + total = len(questions) + score_per_question = 100 / total if total else 0 + details = [] + + for q in questions: + user_ans = answers.get(str(q["id"])) + is_correct = _is_correct(q["type"], q["answer"], user_ans) + if is_correct: + correct_count += 1 + details.append({ + "question_id": q["id"], + "is_correct": is_correct, + "user_answer": user_ans, + "correct_answer": q["answer"], + }) + + score = round(score_per_question * correct_count) + return { + "score": score, + "correct_count": correct_count, + "wrong_count": total - correct_count, + "passed": score >= paper.pass_score, + "details": details, + } +``` + +## 7. 自测 vs 正式考区别 + +| 维度 | 自测 (self_test) | 正式考 (formal) | +|------|-----------------|----------------| +| 次数限制 | 不限 | 按配置（通常 1 次） | +| 即时反馈 | 每题显示对错+答案 | 交卷后显示成绩 | +| 成绩存档 | 不存 | 永久保存到 exam_record | +| 答题明细 | 不存 | JSON 持久化 | + +## 8. 考试记录设计 + +```json +// exam_record.detail_json 示例 +{ + "questions": [ + { + "question_id": 1, + "stem": "博昇的主营业务包括？", + "type": "single", + "user_answer": "D", + "correct_answer": "D", + "is_correct": true, + "explanation": "博昇双主营业务为资本咨询与AI产业落地" + } + ], + "time_spent_sec": 1200 +} +``` + +## 9. 权限 + +- **员工：** 仅查看自己的考试记录 +- **管理员：** 查看全部考试记录（`/api/system/exam-records`） \ No newline at end of file diff --git a/docs/04_Backend/BE03_Media_Module.md b/docs/04_Backend/BE03_Media_Module.md new file mode 100644 index 0000000..2a40b2a --- /dev/null +++ b/docs/04_Backend/BE03_Media_Module.md @@ -0,0 +1,233 @@ +# BE03 — 素材模块设计 + +> **版本：V1.1 | 技术：分片上传 + LibreOffice + PyMuPDF** + +--- + +## 1. 模块职责 + +- 文件上传（直传 + 分片上传） +- 素材审批流（待审批 → 通过/驳回） +- 审批通过后异步文档转换管线 +- 文件预览 +- 转换状态查询 + +## 2. 素材状态流转 + +``` +员工提交 / 管理员上传 + │ + ▼ + pending（待审批） ──┬─ approve → approved（已通过） + │ │ + │ └─→ 触发异步转换管线 + │ │ + │ ├─ 文档 → LibreOffice 转 PDF → PyMuPDF 提取 + │ │ 文本 → 切片写入 knowledge_chunk + │ └─ 视频/图片 → 仅标记预览可用 + │ + └─ reject → rejected（已驳回，前台不可见） +``` + +## 3. 上传 API + +### 直传（文档 ≤ 200MB） + +```python +POST /api/media/upload +Content-Type: multipart/form-data + +Parameters: + - file: 文件二进制 + - bind_type: company | product | course | none + - bind_id: 绑定实体 ID（可选） + +Response: + { + "media_id": 1, + "status": "pending", + "filename": "原始名称.pptx" + } +``` + +### 分片上传（视频 > 100MB） + +```python +# 1. 初始化 +POST /api/media/upload-init +{ + "filename": "training.mp4", + "file_size": 524288000, + "bind_type": "course", + "bind_id": 1 +} +Response: { "upload_id": "uuid", "chunk_size": 5242880, "chunk_count": 100 } + +# 2. 上传分片（循环调用） +POST /api/media/upload-chunk +Content-Type: multipart/form-data +{ + "upload_id": "uuid", + "chunk_index": 0, + "file": +} + +# 3. 完成合并 +POST /api/media/upload-complete +{ "upload_id": "uuid" } +Response: { "media_id": 1, "status": "pending" } +``` + +## 4. 审批 API + +```python +# 管理员 +GET /api/media/audit-list?status=pending&page=1&size=20 + +POST /api/media/audit/{mediaId} +{ + "action": "approve", # approve | reject + "reject_reason": "..." # 驳回时必填 +} +``` + +## 5. 异步转换管线 + +```python +# services/media_service.py +import threading +from datetime import datetime + +def _async_convert_pipeline(media_id: int): + """审批通过后的异步转换管线""" + try: + media = db.query(MediaFile).get(media_id) + + # 仅文档需要转换（PPT/Word/PDF） + if media.file_ext in ("ppt", "pptx", "doc", "docx"): + # Step 1: LibreOffice 转 PDF + pdf_path = _libreoffice_to_pdf(media.stored_path) + + # Step 2: PyMuPDF 提取文本 + text = _pymupdf_extract(pdf_path) + + # Step 3: 按段落切片入库 + chunks = _split_into_chunks(text) + for i, chunk_text in enumerate(chunks): + db.add(KnowledgeChunk( + media_file_id=media.id, + source_type=media.file_ext, + chunk_index=i, + content=chunk_text, + )) + elif media.file_ext == "pdf": + # PDF 直接 PyMuPDF 提取 + text = _pymupdf_extract(media.stored_path) + chunks = _split_into_chunks(text) + for i, chunk_text in enumerate(chunks): + db.add(KnowledgeChunk(media_file_id=media.id, ...)) + + # 视频/图片：不提取文本 + media.extracted = True + db.commit() + logger.info(f"转换完成: media_id={media_id}") + except Exception as e: + logger.error(f"转换失败: media_id={media_id}, error={e}") + media.extracted = False # 标记失败可重试 + +def approve_media(media_id: int, auditor_id: int): + """审批通过 → 启动异步转换""" + media = db.query(MediaFile).get(media_id) + media.status = "approved" + media.audit_by = auditor_id + media.audit_at = datetime.utcnow() + db.commit() + + thread = threading.Thread(target=_async_convert_pipeline, args=(media_id,)) + thread.start() +``` + +## 6. LibreOffice 转换接口 + +```python +# utils/libreoffice.py +import subprocess +import requests + +def libreoffice_convert(input_path: str, output_dir: str) -> str: + """调用 LibreOffice 容器将文档转 PDF""" + # 方式1：本地安装 libreoffice + subprocess.run([ + "libreoffice", "--headless", "--convert-to", "pdf", + "--outdir", output_dir, input_path + ], check=True) + + # 方式2：Docker 容器 HTTP 接口 + # response = requests.post( + # f"{settings.libreoffice_url}/convert", + # files={"file": open(input_path, "rb")} + # ) + # return response.json()["pdf_path"] +``` + +## 7. PyMuPDF 文本提取 + +```python +# utils/pdf_extractor.py +import fitz # PyMuPDF + +def extract_text(pdf_path: str) -> str: + """提取 PDF 全部文本""" + doc = fitz.open(pdf_path) + text = "" + for page in doc: + text += page.get_text() + doc.close() + return text + +def split_into_chunks(text: str, max_chars: int = 1000) -> list[str]: + """按段落 + 最大字符数切片""" + paragraphs = text.split("\n\n") + chunks = [] + current = "" + for p in paragraphs: + if len(current) + len(p) > max_chars: + if current: + chunks.append(current.strip()) + current = p + else: + current += "\n\n" + p if current else p + if current: + chunks.append(current.strip()) + return chunks +``` + +## 8. 预览 API + +```python +GET /api/media/preview/{mediaId} +# 仅 approved 素材可预览 +Response: +{ + "preview_url": "/media/upload/uuid-filename.pdf", + "file_ext": "pdf", + "can_preview": true +} + +GET /api/media/status/{mediaId} +# 查询素材状态（含提取进度） +Response: +{ + "status": "approved", + "extracted": true, + "chunk_count": 42 +} +``` + +## 9. 安全约束 + +- 扩展名白名单：ppt/pptx/pdf/doc/docx/mp4/png/jpg/jpeg +- 文件名重命名为 UUID，杜绝路径穿越 +- 上传目录对静态预览只读，禁止直接执行 +- 文件大小：文档 ≤ 200MB，视频 ≤ 2GB +- MIME 类型校验 + 扩展名双重校验 \ No newline at end of file diff --git a/docs/04_Backend/BE04_AI_Chat_Module.md b/docs/04_Backend/BE04_AI_Chat_Module.md new file mode 100644 index 0000000..89c7953 --- /dev/null +++ b/docs/04_Backend/BE04_AI_Chat_Module.md @@ -0,0 +1,350 @@ +# BE04 — AI PathCoach 模块设计 + +> **版本：V1.1 | httpx 适配器 + 配置链 + Fail Fast | 参考：pj006-zhilianyuan2 llm/openai_adapter.py** +> **配置优先级：system_config 数据库表 → .env 文件** + +--- + +## 1. 模块职责 + +- 全局 AI 聊天框的后端支持 +- 上下文注入（当前产品/课程信息自动带入） +- 知识检索（MySQL FULLTEXT 召回 → Prompt 注入） +- SSE 流式响应 + 非流式调用（快捷动作） +- 3 个快捷动作（情景演练/查佣金/产品对比） + +## 2. 架构 + +``` +用户消息 + 页面上下文 + │ + ▼ + ┌──────────────────┐ + │ 知识检索 │ + │ MySQL FULLTEXT │ + │ → 匹配段落 │ + └──────┬───────────┘ + │ 上下文片段 + ▼ + ┌──────────────────┐ + │ Prompt 组装 │ + │ System Prompt │ + │ + 知识上下文 │ + │ + 对话历史 │ + └──────┬───────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ build_llm_adapter() 工厂 │ + │ → 读取配置（库→.env） │ + │ → Fail Fast 缺配置抛 501 │ + │ → 返回 OpenAICompatible │ + └──────┬───────────────────────┘ + │ + ▼ + ┌──────────────────┐ + │ httpx 调用 │ + │ /chat/completions│ + │ SSE 流式 / 非流式│ + └──────────────────┘ +``` + +## 3. 配置优先级与 Fail Fast + +```python +# services/ai_service.py +from __future__ import annotations +import httpx +from typing import Generator +from dataclasses import dataclass, field +from app.core.config import Settings +from app.errors import AppError + + +class LLMNotConfiguredError(AppError): + """LLM 未配置（缺 api_key / base_url / model）""" + status_code = 501 + error_code = "llm_not_configured" + + +@dataclass +class LLMConfig: + """LLM 连接所需的三项配置""" + base_url: str + api_key: str + model: str + + +def resolve_llm_config(settings: Settings) -> LLMConfig: + """按优先级链解析 LLM 配置。缺任何一项即抛 LLMNotConfiguredError。 + + 优先级（高 → 低）： + 1. settings.llm_*（来自 system_config 数据库表） + 2. settings 中从 .env 读取的默认值 + """ + base_url = getattr(settings, "llm_base_url", None) or "" + api_key = getattr(settings, "llm_api_key", None) or "" + model = getattr(settings, "llm_model", None) or "" + + missing = [] + if not base_url: + missing.append("llm_base_url") + if not api_key: + missing.append("llm_api_key") + if not model: + missing.append("llm_model") + + if missing: + raise LLMNotConfiguredError( + f"LLM 服务未配置——缺失：{', '.join(missing)}。" + f"请管理员在【系统参数配置】中补充。" + ) + + return LLMConfig(base_url=base_url, api_key=api_key, model=model) +``` + +## 4. LLM 适配器（httpx 实现，参考 zhilianyuan2 openai_adapter.py） + +使用 httpx 替代 OpenAI SDK，减少依赖、更可控、支持 token usage 采集。 + +```python +# services/ai_service.py + +class LLMAdapter: + """OpenAI 兼容接口适配器（httpx 实现，无 openai SDK 依赖）""" + + def __init__(self, *, config: LLMConfig, http_client: httpx.Client | None = None): + self._base_url = config.base_url.rstrip("/") + self._api_key = config.api_key + self._model = config.model + self._client = http_client or httpx.Client(timeout=60.0) + # 最后一次流式调用的 token 用量（供日志埋点） + self.last_stream_usage: dict[str, int] = {} + + def _headers(self) -> dict[str, str]: + return { + "Authorization": f"Bearer {self._api_key}", + "Content-Type": "application/json", + } + + def _payload(self, messages: list[dict], *, stream: bool, **kwargs) -> dict: + payload = { + "model": self._model, + "messages": messages, + "stream": stream, + "temperature": kwargs.get("temperature", 0.7), + "max_tokens": kwargs.get("max_tokens", 2048), + } + if stream: + payload["stream_options"] = {"include_usage": True} + return payload + + def generate(self, messages: list[dict], **kwargs) -> str: + """非流式调用，返回完整正文。用于快捷动作等一次性请求。""" + try: + resp = self._client.post( + f"{self._base_url}/chat/completions", + headers=self._headers(), + json=self._payload(messages, stream=False, **kwargs), + ) + resp.raise_for_status() + data = resp.json() + content = data["choices"][0]["message"]["content"] + if not content or not content.strip(): + raise LLMError("LLM 返回空正文") + return content + except httpx.HTTPError as e: + raise LLMError(f"LLM 调用失败：{e}") from e + except (KeyError, ValueError) as e: + raise LLMError(f"LLM 响应解析失败：{e}") from e + + def generate_stream(self, messages: list[dict], **kwargs) -> Generator[str, None, None]: + """SSE 流式调用。逐 chunk yield 文本，末包采集 usage。""" + self.last_stream_usage = {} + try: + with self._client.stream( + "POST", + f"{self._base_url}/chat/completions", + headers=self._headers(), + json=self._payload(messages, stream=True, **kwargs), + ) as resp: + resp.raise_for_status() + for line in resp.iter_lines(): + if not line or not line.startswith("data: "): + continue + payload = line[6:].strip() + if payload == "[DONE]": + break + chunk = json.loads(payload) + # 末包采集 usage（include_usage=true） + usage = chunk.get("usage") + if usage: + self.last_stream_usage = { + "input_tokens": int(usage.get("prompt_tokens", 0) or 0), + "output_tokens": int(usage.get("completion_tokens", 0) or 0), + } + choices = chunk.get("choices", []) + if not choices: + continue + delta = choices[0].get("delta", {}) + content = delta.get("content", "") + if content: + yield content + except httpx.HTTPError as e: + raise LLMError(f"LLM 流式调用失败：{e}") from e + except (KeyError, ValueError) as e: + raise LLMError(f"LLM 流式响应解析失败：{e}") from e + + +def build_llm_adapter(settings: Settings) -> LLMAdapter: + """工厂方法：解析配置 → 构造适配器。配置不全即 Fail Fast。""" + config = resolve_llm_config(settings) + return LLMAdapter(config=config) +``` + +## 5. 知识检索 + +```python +# services/ai_service.py + +def retrieve_knowledge(keywords: str, db: Session, top_k: int = 5) -> list[str]: + """MySQL 全文索引检索知识块""" + results = db.execute( + text( + "SELECT content FROM knowledge_chunk " + "WHERE MATCH(content) AGAINST(:keywords IN NATURAL LANGUAGE MODE) " + "LIMIT :limit" + ), + {"keywords": keywords, "limit": top_k}, + ).fetchall() + return [r[0] for r in results] +``` + +## 6. System Prompt + +```python +SYSTEM_PROMPT = """你是一个博昇内部培训平台的 AI 助教 PathCoach。 + +你的职责： +1. 解答公司介绍、产品知识、佣金规则、销售话术、业务规则相关的问题 +2. 严格依赖已审批知识库的内容回答 +3. 如果知识库中未找到相关资料，明确回答「未找到相关资料」，不得臆测 + +禁止行为： +1. 禁止闲聊 +2. 禁止编造数据 +3. 禁止回答超出业务范围的问题 +4. 禁止泄露敏感信息 + +当前页面上下文： +{page_context} + +知识库相关片段： +{knowledge_context} +""" +``` + +## 7. API 实现 + +```python +# api/ai_chat.py +from fastapi.responses import StreamingResponse + +router = APIRouter(prefix="/api/ai-chat", tags=["ai_chat"]) + +@router.post("/message") +def chat_message( + request: ChatRequest, + current_user: CurrentUser, + db: Session = Depends(get_db), + settings: Settings = Depends(get_settings), +): + """SSE 流式对话""" + # 1. 检索知识 + knowledge = retrieve_knowledge(request.message, db) + + # 2. 组装 Prompt + system = SYSTEM_PROMPT.format( + page_context=json.dumps(request.context or {}), + knowledge_context="\n\n".join(knowledge), + ) + messages = [ + {"role": "system", "content": system}, + *request.history, + {"role": "user", "content": request.message}, + ] + + # 3. 构建 LLM 适配器（缺配置即抛 501） + llm = build_llm_adapter(settings) + + def generate(): + for chunk in llm.generate_stream(messages): + yield f"data: {json.dumps({'type': 'text', 'content': chunk})}\n\n" + yield "data: {\"type\": \"done\"}\n\n" + + return StreamingResponse( + generate(), media_type="text/event-stream", + headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}, + ) + + +@router.get("/quick-actions") +def get_quick_actions(): + """获取 3 个快捷按钮""" + return {"data": {"actions": [ + {"id": "scenario", "label": "客户情景演练"}, + {"id": "commission", "label": "查询佣金/规则"}, + {"id": "compare", "label": "产品对比"}, + ]}} + + +@router.post("/quick-action") +def trigger_quick_action( + request: QuickActionRequest, + settings: Settings = Depends(get_settings), +): + """触发快捷动作（非流式 LLM 调用）""" + llm = build_llm_adapter(settings) + + if request.action_id == "commission": + # 查佣金：构建 prompt → 非流式调用 + prompt = f"查询产品佣金信息，产品参数：{request.params}" + resp = llm.generate([{"role": "user", "content": prompt}]) + return {"data": {"result": resp}} + + elif request.action_id == "compare": + prompt = f"对比以下产品：{request.params}" + resp = llm.generate([{"role": "user", "content": prompt}]) + return {"data": {"result": resp}} + + elif request.action_id == "scenario": + # 情景演练：返回初始话术，后续走流式对话 + prompt = f"开始销售情景演练，场景参数：{request.params}" + resp = llm.generate([{"role": "user", "content": prompt}]) + return {"data": {"result": resp, "mode": "scenario"}} +``` + +## 8. 上下文注入规则 + +| 页面 | 自动注入上下文 | 说明 | +|------|--------------|------| +| 产品详情 | `product_id`, `product_name`, `product_code` | 自动带入当前产品 | +| 课程详情 | `course_id`, `course_name`, `related_product` | 自动带入当前课程及关联产品 | +| 公司介绍 | `page: "company_intro"` | 提示 AI 当前页为公司介绍 | + +## 9. 配置项 + +| 配置键 | 来源 | 说明 | +|--------|------|------| +| `llm_base_url` | system_config 表 / .env | LLM 服务地址，如 `http://192.168.1.100:11434/v1` | +| `llm_api_key` | system_config 表 / .env | API Key，本地 Ollama 可填 `ollama` | +| `llm_model` | system_config 表 / .env | 模型名，如 `qwen2.5:7b` | + +## 10. 错误处理 + +| 场景 | HTTP 状态 | 响应 | +|------|----------|------| +| LLM 未配置（缺 base_url/key/model） | 501 | `{"error": "llm_not_configured", "message": "请管理员在系统参数配置中补充..."}` | +| LLM 调用超时/网络错误 | 502 | `{"error": "llm_request_failed", "message": "LLM 服务不可达，请检查网络连接"}` | +| LLM 返回空正文 | 502 | `{"error": "llm_empty_response", "message": "LLM 返回空结果"}` | +| LLM 响应格式异常 | 502 | `{"error": "llm_response_error", "message": "LLM 响应异常"}` | \ No newline at end of file diff --git a/docs/04_Backend/BE05_Knowledge_Ingest_Module.md b/docs/04_Backend/BE05_Knowledge_Ingest_Module.md new file mode 100644 index 0000000..bce0a91 --- /dev/null +++ b/docs/04_Backend/BE05_Knowledge_Ingest_Module.md @@ -0,0 +1,226 @@ +# BE05 — 知识入库体系总设计（Knowledge Ingest） + +> **版本：V1.1 | 定稿** +> **定位**：把「素材入库」与「结构化知识入库」统一为一套可复用的知识入库体系，覆盖上传 → 生成 → 审批 → 入库全链路。 +> **配套**：BE03（素材转换管线）、BE04（AI 检索）、`docs/knowledge_source/README.md`（知识源格式契约）。 + +--- + +## 1. 模块职责 + +知识入库体系负责把两类知识源，统一经过「审批前置」流入三张消费表，最终支撑「可浏览 / 可考试 / 可 AI 检索」。 + +| 知识源类型 | 载体 | 审批单元 | 流入表 | +|-----------|------|---------|--------| +| **非结构化素材** | PPT/PDF/Word/视频/图片 | 逐文件 | knowledge_chunk（+ 预览） | +| **结构化知识** | 知识源 md（docs/knowledge_source/） | 逐文档 | product / question / knowledge_chunk | + +**核心原则（与 P02/P04 对齐）**：所有知识只有 `approved` 才生效；`pending` / `rejected` 一律不解析、不进库、前台不可见。 + +--- + +## 2. 完整目录结构（定稿） + +``` +eaisalestrain_app/ +├── docs/ +│ └── knowledge_source/ # 知识源文档（权威源，纳入 git 版本管理） +│ ├── README.md # 格式契约 + 答案契约 + 审批状态机 +│ ├── 01_通用规则.md +│ ├── 02_资本咨询类.md +│ ├── 03_资质认定辅导类.md +│ ├── 04_AI咨询与实施类.md +│ └── 05_企业级AI工具与平台.md +│ +├── backend/ +│ ├── app/ +│ │ ├── api/ +│ │ │ ├── media.py # 【已有】素材上传/审批/预览 +│ │ │ └── knowledge.py # 【新增】知识源扫描/审批/摄入 +│ │ ├── models/ +│ │ │ ├── media_file.py # 【已有】素材表 +│ │ │ ├── knowledge_chunk.py # 【改造】来源扩展（见 §4） +│ │ │ └── knowledge_source.py # 【新增】知识源文档表 +│ │ ├── services/ +│ │ │ ├── media_service.py # 【已有】LibreOffice/PyMuPDF 转换管线 +│ │ │ └── knowledge_service.py # 【新增】md 解析 + 摄入 +│ │ └── scripts/ +│ │ ├── init_db.py # 【已有】建表 + 种子 +│ │ └── ingest_knowledge.py # 【新增】知识源扫描/摄入脚本 +│ └── data/ +│ ├── media/ # 【已有】素材物理文件（git 忽略） +│ │ ├── upload/ +│ │ └── _preview_cache/ +│ └── logs/ # 【已有】special_trace 按天日志 +│ +└── docker-compose.yml # 【待创建】 +``` + +**约定**： +- `docs/knowledge_source/` 是知识源 md 的唯一入库口（权威源，git 管理，可 diff 可回滚）。 +- 运行时摄入**直接读取**该目录，不复制到 backend/data（单一事实源，避免双份漂移）。 +- 素材物理文件仍在 `backend/data/media/`（git 忽略）。 + +--- + +## 3. 两条流程的状态机（定稿） + +### 流程 A：非结构化素材（BE03 已实现） + +``` +员工上传 ──▶ media_file(pending) ──审批──▶ approved ──▶ 异步转换 +管理员上传 ──▶ media_file(approved) ──▶ 立即异步转换 │ + ▼ + ┌──────────────────────────┐ + │ 文档: LibreOffice→PDF→ │ + │ PyMuPDF 提取→切片 │ + │ 视频/图片: 仅预览 │ + └──────────┬───────────────┘ + ▼ + knowledge_chunk +``` + +### 流程 B：结构化知识源（本次新增） + +``` +知识源 md（docs/knowledge_source/） + │ + ▼ +【扫描】ingest_knowledge.py / POST /api/knowledge/scan + │ 解析 front-matter → 为每个 md 建 knowledge_source 记录 + ▼ +knowledge_source(pending) ──审批──▶ approved ──▶ 解析摄入 + │ │ + │ ├─→ product(status=active) + │ ├─→ question(status=active) + │ └─→ knowledge_chunk(source=knowledge_source) + │ + └─驳回──▶ rejected（理由必填，不生效） +``` + +**对称性**：素材「审批通过→转换提取」，知识源「审批通过→解析摄入」。两条通道最终都汇入 `knowledge_chunk` 供 AI 检索。 + +--- + +## 4. 数据模型变更 + +### 4.1 新增 `knowledge_source` 表 + +```sql +CREATE TABLE knowledge_source ( + id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY, + title VARCHAR(256) NOT NULL COMMENT '文档标题', + file_path VARCHAR(512) NOT NULL UNIQUE COMMENT 'md 相对路径（docs/knowledge_source/ 下）', + category VARCHAR(64) NOT NULL COMMENT '分类：general/capital_consulting/qualification_counseling/ai_consulting/ai_tools_platform', + domain ENUM('company','product','sales') NOT NULL DEFAULT 'product', + source_version VARCHAR(32) NOT NULL COMMENT '源版本，如 V1.0', + audit_status ENUM('pending','approved','rejected') NOT NULL DEFAULT 'pending', + audit_by BIGINT UNSIGNED DEFAULT NULL COMMENT '审批人ID', + audit_at DATETIME(6) DEFAULT NULL COMMENT '审批时间', + reject_reason VARCHAR(512) DEFAULT NULL COMMENT '驳回理由', + ingested TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否已摄入', + created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), + updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6), + + INDEX idx_ks_status (audit_status), + INDEX idx_ks_category (category), + CONSTRAINT fk_ks_auditor FOREIGN KEY (audit_by) REFERENCES user(id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; +``` + +### 4.2 改造 `knowledge_chunk` 表（来源扩展） + +现状 `media_file_id BIGINT UNSIGNED NOT NULL` 强绑定素材。改造后： + +```sql +media_file_id BIGINT UNSIGNED DEFAULT NULL, -- 由 NOT NULL 改为可空 +knowledge_source_id BIGINT UNSIGNED DEFAULT NULL, -- 新增 +-- 约束：media_file_id 与 knowledge_source_id 二者必居其一（应用层校验，Fail Fast） +``` + +对应 ORM `models/knowledge_chunk.py`：`media_file_id` 改为可空，新增 `knowledge_source_id` 外键与 relationship。 + +--- + +## 5. 模块清单（8 模块） + +| # | 模块 | 状态 | 职责 | 落点 | +|---|------|------|------|------| +| 1 | 上传模块 | ✅ 已有 | 直传 + 分片（>100MB） | `api/media.py` | +| 2 | 转换模块 | ✅ 已有 | LibreOffice → PDF | `services/media_service.py` | +| 3 | 提取切片模块 | ✅ 已有 | PyMuPDF 提取 + 段落切片 | `services/media_service.py` | +| 4 | **摄入模块** | 🆕 新增 | 解析知识源 md → product/question/chunk | `services/knowledge_service.py` | +| 5 | 审批模块 | 🔧 扩展 | 素材审批（已有）+ 知识源审批（新增） | `api/media.py` + `api/knowledge.py` | +| 6 | 入库模块 | 🔧 扩展 | 写 product/question/knowledge_chunk | `services/knowledge_service.py` | +| 7 | 预览模块 | ✅ 已有 | approved 素材预览 | `api/media.py` | +| 8 | 检索模块 | ✅ 已有 | MySQL FULLTEXT 召回 | `services/ai_service.py` | + +--- + +## 6. 新增 API（knowledge.py） + +```python +router = APIRouter(prefix="/api/knowledge", tags=["knowledge"]) + +# ── 扫描（管理员）── +POST /api/knowledge/scan + # 扫描 docs/knowledge_source/*.md + # 为新增/变更的 md 建 knowledge_source 记录（status=pending） + # 已存在且未摄入的记录跳过；返回扫描结果列表 + +# ── 审批（管理员）── +GET /api/knowledge/audit-list?status=pending +POST /api/knowledge/audit/{source_id} + # { "action": "approve" | "reject", "reject_reason": "..." } + # approve → 触发摄入（同步解析写入 product/question/chunk，标记 ingested=1） + # reject → 必填 reject_reason，不摄入 + +# ── 状态查询 ── +GET /api/knowledge/status/{source_id} + # { "audit_status", "ingested", "reject_reason" } +``` + +--- + +## 7. 摄入脚本（ingest_knowledge.py） + +```python +"""知识源摄入脚本：扫描 md → 建记录 → （审批通过后）解析入库 + +用法： + cd backend && source venv/bin/activate + python -m app.scripts.ingest_knowledge --scan # 仅扫描建 pending 记录 + python -m app.scripts.ingest_knowledge --ingest # 摄入单个已审批源 +""" + +# 解析规则（严格对齐 knowledge_source/README.md 格式契约）： +# 1. 读 YAML front-matter：category / domain / source_version +# 2. 按 "## " 二级标题切块： +# ## 结构化产品数据 → 解析 "### code name" + "key: value" 列表 → product +# ## AI 检索知识 → 每个 "### 标题" 段落 → knowledge_chunk +# ## 考试题目 → 每个 "### Qn" 的字段列表 → question +# 3. 摄入后 product/question 置 status=active +# 4. knowledge_chunk 写入 knowledge_source_id，media_file_id 留空 +``` + +**Fail Fast 约束（G02）**：解析失败（front-matter 缺失、section 缺块、字段缺失）立即抛错并中断该源摄入，不静默跳过、不写半截数据。 + +--- + +## 8. 格式契约（已定，见 knowledge_source/README.md） + +- 每个 md：YAML front-matter（`category` / `domain` / `source_version`）+ 三个固定 `## ` section。 +- 题目答案契约：`judge=[bool]`、`single=[索引]`、`multiple=[索引列表]`。 +- 已生成 5 个知识源：`01_通用规则` + `02/03/04/05` 四大分类，共 28 产品 + 20 题。 + +--- + +## 9. 实现清单（代码侧，已完成） + +- [x] `models/knowledge_source.py` 新建 +- [x] `models/knowledge_chunk.py` 来源扩展（media_file_id 可空 + knowledge_source_id） +- [x] `services/knowledge_service.py`（md 解析 + 摄入） +- [x] `api/knowledge.py`（scan / audit / status） +- [x] `scripts/ingest_knowledge.py` +- [x] `scripts/init_db.py` 追加 knowledge_source 建表 + knowledge_chunk 字段迁移 +- [x] `docs/db_schema.md`、`docs/api.md` 同步更新 diff --git a/docs/04_Backend/BE06_AI_Config_Credits_Module.md b/docs/04_Backend/BE06_AI_Config_Credits_Module.md new file mode 100644 index 0000000..d673d81 --- /dev/null +++ b/docs/04_Backend/BE06_AI_Config_Credits_Module.md @@ -0,0 +1,226 @@ +# BE06 — AI 配置与算力点计费模块设计 + +> **版本：V1.0 | 从 pj034-oeamgt 完整移植 + 精简适配 | 参考：pj034 `core/ai_config.py`、`services/ai/router.py`、`models/ai_call_log.py`、`api/v1/ai_billing.py`** +> **目标：把 pj034 成熟的「AI 路由/Provider/密钥配置 + 算力点计费 + 调用审计」体系，按 pj0231「极致极简、单公司、按用户计点」落地。** + +--- + +## 1. 背景与目标 + +pj034 的 AI 系统已演进为「多层、多公司、多租户」的完整运维平台：平台级路由配置 + 公司级覆盖 + 算力点计费 + 调用审计 + 用量报表。pj0231 是内部培训平台，只需要其中与「AI 助教 PathCoach」相关的子集。 + +**移植范围（保留）**： +1. AI 路由/Provider/密钥配置文件体系（`ai_config.json` + `ai_secrets.json`）——已落地 +2. Agent → 路由映射、默认路由、回退链（fallback） +3. **按用户算力点计费**：每次 AI 调用按能力扣点 + 写调用日志 +4. AI 配置管理 API（读/写/热重载/密钥状态）+ 用量查询 API +5. 前端：AI 配置 UI + AI 用量看板 + 用户剩余点数展示 + +**排除范围（pj034 专属，pj0231 不适用）**： +| pj034 能力 | 排除理由 | +|-----------|---------| +| 图片生成 / 抠图 / 换背景 / AI 模特 / 卖点图 | 电商场景，培训平台无此需求 | +| 多公司覆盖层 `company_ai_config`（AES 加密、billing_mode 分流） | 单公司内网部署 | +| 套餐订阅 `pricing.py` / 配额守护 `quota_guard.py`（tier 阶梯） | 无订阅计费，改为按用户点数 | +| `cost_cny`（人民币成本核算） | 内网，无对外结算 | + +--- + +## 2. 现状盘点（pj0231 已落地部分） + +| 模块 | 文件 | 状态 | +|------|------|------| +| 配置加载器 | `internal/config/json_loader.go` | ✅ 已移植（RouteInfo/RouteConfig/AIConfig/AISecrets/ProviderSecretKey/ProviderDefaultBaseURL） | +| 路由解析 | `GetRoute / GetFallbackRoutes / GetAllRoutes / GetRoutesByCategory` | ✅ | +| 配置文件 | `config/ai_config.json` `ai_secrets.json` `ai_secrets.example.json` `platform.json` | ✅ | +| LLM 客户端 | `internal/ai/llm.go`（NewClient/NewClientLegacy/Generate/GenerateFull/GenerateStream/Embed/GenerateWithFallback） | ✅ | +| 混合检索 | `internal/ai/retrieve.go`（向量 + 关键词，embed 走 `embed_gen` agent） | ✅ | +| 对话/快捷动作 | `internal/api/ai_chat.go`（ChatMessage SSE + QuickAction） | ✅ | +| 路由选择器 | `internal/api/routes.go`（ListChatRoutes/ListEmbedRoutes） | ✅ | + +**待补（本次工作）**： +1. `ai_call_log` 表 + `User.ai_points` 字段（计费与审计） +2. 扣点收口逻辑 `compute_credits` + `log_ai_call` +3. 计费查询 API（按月/能力聚合，管理员全量 + 用户本人） +4. AI 配置管理 API（读/写 `ai_config.json`、热重载、密钥状态） +5. `ChatMessage`/`QuickAction` 接入「扣点 + 日志 + 回退链」 +6. 前端：AI 配置 UI（7.2.4）、AI 用量看板、剩余点数展示 + +--- + +## 3. pj034 计费体系分析（移植蓝本） + +### 3.1 调用日志表 `ai_call_logs`（pj034） + +| 字段 | 类型 | 说明 | pj0231 取舍 | +|------|------|------|------------| +| `id` | PK | | ✅ | +| `company_id` | int | 公司维度 | ❌ 单公司，删除 | +| `user_id` | int | 调用人 | ✅ | +| `provider` | enum | provider | ✅ | +| `capability` | enum | AI 能力 | ✅ | +| `input_asset_id` / `output_asset_id` | int | 电商素材 | ❌ | +| `route_id` | str | 路由 ID | ✅ | +| `model_id` | str | 模型 | ✅ | +| `input_summary` / `output_summary` | text | 摘要 | ❌ 极致极简 | +| `raw_request` / `raw_response` | text | 原始 IO | ❌（审计可后补） | +| `tokens_input` / `tokens_output` | int | token 用量 | ✅ | +| `credits` | numeric | 成本单价 | ❌ | +| `cost_cny` | numeric | 人民币成本 | ❌ | +| `billing_mode` | enum | platform/self_managed | ❌ 单平台 | +| `credits_charged` | int | 实扣点数 | ✅ | +| `status` | enum | success/failed/... | ✅ | +| `error_message` / `error_detail` | text | 错误 | ✅（保留 error_message） | +| `http_status` | int | | ✅ | +| `latency_ms` | int | 耗时 | ✅ | +| `called_at` | datetime | 调用时间 | ✅ | + +### 3.2 扣点收口 `compute_credits`（pj034） + +```python +CAPABILITY_CREDITS = { + AiCapability.TEXT_DIAGNOSE: 1, + AiCapability.BG_REMOVE: 1, + AiCapability.BG_REPLACE: 2, + AiCapability.MODEL_GEN: 5, + AiCapability.TEXT_GEN: 1, + AiCapability.AI_CHAT: 1, # 每轮对话扣 1 点 + AiCapability.IMAGE_VALIDATE: 1, +} + +def compute_credits(capability, billing_mode, status): + if status != SUCCESS or billing_mode != PLATFORM: + return 0 + return CAPABILITY_CREDITS.get(capability, 0) +``` + +**核心规则**：只有「调用成功」才扣点；失败不扣点。扣点决策收口到 service 层，不在各端点散落判断。 + +### 3.3 计费聚合 API（pj034 `ai_billing.py`） + +`GET /data/ai-billing?days=30&group_by=month|capability|provider|month_capability` + +返回 `{ summary: {total_calls, success_calls, failed_calls, total_credits_charged}, buckets: [...] }`。MySQL 下按月聚合走 Go 侧 group（不依赖 `date_trunc`）。 + +--- + +## 4. pj0231 计费模型（精简） + +### 4.1 能力 → 点数（CAPABILITY_CREDITS） + +| capability | 含义 | 点数 | +|-----------|------|------| +| `ai_chat` | PathCoach 对话（每轮） | 1 | +| `text_gen` | 快捷动作（情景演练/查佣金/产品对比） | 1 | +| `embed` | 知识检索内部 embedding | 0（不扣，仅记审计） | + +### 4.2 用户点数 `User.ai_points` + +- `User` 表新增 `ai_points int`（默认 100，管理员可充值）。 +- 新用户默认值走 `system_config.ai_points_default`（默认 `100`）。 +- 管理员账号默认 `999999`（不限，避免管理员自己用没）。 +- 扣点规则：成功调用 → 扣 `compute_credits(...)` 点；失败不扣。 +- **点数不足**：返回 402 `ai_points_exhausted`，前端提示「AI 点数不足，请联系管理员充值」。 + +### 4.3 调用日志 `ai_call_log`（pj0231 精简版） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | uint PK | | +| `user_id` | uint index | 调用人 | +| `capability` | str | ai_chat / text_gen / embed | +| `provider` | str | 实际命中的 provider | +| `route_id` | str | 路由 ID | +| `model` | str | 模型名 | +| `tokens_input` | int | 输入 token | +| `tokens_output` | int | 输出 token | +| `credits_charged` | int | 实扣点数（0 = 未扣） | +| `status` | str | success / failed | +| `error_message` | str | 失败信息 | +| `latency_ms` | int | 耗时 | +| `created_at` | time | 调用时间 | + +--- + +## 5. 后端 API 设计（pj0231） + +### 5.1 AI 配置管理（管理员） + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/ai/config` | 读完整 `ai_config.json`（含 agent_routes + 分类 routes + fallback） | +| PUT | `/api/ai/config` | 写回 `ai_config.json`（原子写 + 清缓存热生效） | +| POST | `/api/ai/reload` | 热重载（清缓存，无需重启） | +| GET | `/api/ai/secrets-status` | 各 provider 密钥是否已配置（仅 `configured: true/false`，不回显明文） | +| GET | `/api/ai/routes/chat` | 现有：chat 路由选择器 | +| GET | `/api/ai/routes/embed` | 现有：embed 路由选择器 | + +### 5.2 算力点计费查询 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/ai/usage?days=30&group_by=month` | 用量聚合（管理员 = 全量；员工 = 本人，后端按角色过滤） | +| GET | `/api/ai/usage/users` | 管理员：按用户聚合的用量 + 剩余点数（充值入口数据源） | +| GET | `/api/ai/me` | 员工：本人剩余点数 + 近 N 天用量 | + +### 5.3 用户点数充值（管理员） + +| 方法 | 路径 | 说明 | +|------|------|------| +| PUT | `/api/system/users/{id}` | 扩展现有接口：`ai_points` 字段可设置（充值/扣减） | + +--- + +## 6. 前端 UI 设计（pj0231） + +### 6.1 参数配置 7.2.4「AI 配置」改造 + +现有 `SystemConfigPage.vue` 的 `aiItems`（llm_base_url/llm_model 等明文 DB 字段）**替换**为 pj034 `PlatformSystem.vue` 的精简版： + +- **Agent → 路由映射**：PathCoach 对话路由（`path_coach`）、快捷动作路由（`title_gen`）、Embedding 路由（`embed_gen`）各一个下拉选择（数据源 `/api/ai/routes/chat|embed`） +- **默认路由 / 默认 Embedding 路由**：下拉选择 +- **密钥状态看板**：每个 provider 显示 `configured: true/false`（数据源 `/api/ai/secrets-status`） +- **原始 JSON 编辑器**：折叠面板编辑完整 `ai_config.json` +- **热重载 + 保存**：`POST /api/ai/reload` + `PUT /api/ai/config`，带脏检查 + +### 6.2 AI 用量看板（新增页面） + +复刻 pj034 `AiUsage.vue` 的精简版： +- 汇总卡：总调用 / 成功 / 失败 / 总消耗点数（去掉「¥ 花费」） +- 时间窗切换：近 30 / 90 / 365 天 +- 分组明细：按月 / 按能力 / 按 provider +- 管理员额外视角：按用户聚合（含剩余点数） + +菜单位置：知识管理下新增「AI 用量」（管理员）；员工入口放在 PathCoach 面板内（本人剩余点数 + 近 30 天用量）。 + +### 6.3 PathCoach 面板剩余点数 + +`PathCoachPanel.vue` 顶部显示「剩余 AI 点数：N」（数据源 `/api/ai/me`），每次对话/快捷动作完成后刷新。 + +--- + +## 7. 实施清单 + +- [x] 配置加载器 + 配置文件（已落地） +- [x] LLM 客户端 + 回退链（`GenerateWithFallback` 已实现，待接入 ChatMessage） +- [x] `model/ai_call_log.go` + `model/user.go` 加 `ai_points` +- [x] `store/db.go` AutoMigrate 加 `AiCallLog` +- [x] `internal/ai/credits.go`：CAPABILITY_CREDITS + compute_credits + log_ai_call +- [x] `internal/api/ai_chat.go`：ChatMessage/QuickAction 接入扣点 + 日志 + 回退链 +- [x] `internal/api/ai_admin.go`：AI 配置读/写/热重载/密钥状态 +- [x] `internal/api/ai_usage.go`：用量聚合 + 按用户聚合 + 本人剩余点数 +- [x] `internal/api/system.go`：UpdateUser 支持 ai_points 充值 +- [x] `internal/api/router.go`：注册新路由 +- [x] 前端 `api/ai.js` + `api/system.js` 扩展 +- [x] `SystemConfigPage.vue` 7.2.4 改路由配置 UI +- [x] 新增 `AiUsage.vue` 用量看板 + 路由/菜单 +- [x] `PathCoachPanel.vue` 剩余点数 +- [x] 重编译 + 重启 + 验证 + +--- + +## 8. 与既有设计的衔接 + +- **配置优先级**：AI 路由走 `ai_config.json`（文件）优先；旧的 `system_config` 表 `llm_base_url/llm_model` 字段**逐步废弃**，`ResolveLLM` 保留为兜底兼容（`NewClientLegacy`），新链路全部走 `GetRoute`。 +- **极致极简**：不引入多公司、订阅、人民币成本、原始 IO 存储；日志只保留审计必需的字段。 +- **审批前置**：AI 问答只检索已审批知识库（`knowledge_chunk`），与计费解耦。 diff --git a/docs/04_Backend/README.md b/docs/04_Backend/README.md new file mode 100644 index 0000000..e65ec84 --- /dev/null +++ b/docs/04_Backend/README.md @@ -0,0 +1,18 @@ +# 04_Backend — 后端设计与 API + +> **命名规则：** `BE{NN}_{描述}.md` +> **用途：** 后端实现细节、API 设计、服务层设计 +> +> **⚠️ 本目录 BE 文档为 V1.1 设计期历史快照（FastAPI/Python）。** 当前后端已重写为 **Go + Gin + GORM + MySQL 8.0 + FAISS**，见 `docs/changelog.md`（V1.2）。V1.4–V1.7 新增的岗位/积分/证书/部门/消息等接口以 `docs/changelog.md` 为准。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `BE01_Auth_Module.md` | 认证模块设计（JWT + bcrypt） | +| `BE02_Exam_Module.md` | 考试模块设计（题库/组卷/判分） | +| `BE03_Media_Module.md` | 素材模块设计（上传/审批/转换管线） | +| `BE04_AI_Chat_Module.md` | AI PathCoach 模块设计（V1 单一助手；智能体矩阵见 SY03） | +| `BE05_Knowledge_Ingest_Module.md` | 知识入库体系设计（上传→生成→审批→入库） | +| `BE06_AI_Config_Credits_Module.md` | AI 配置与算力点计费模块（移植自 pj034） | diff --git a/docs/06_Product_Lines/PL01_Global_Layout.md b/docs/06_Product_Lines/PL01_Global_Layout.md new file mode 100644 index 0000000..fdd2d3e --- /dev/null +++ b/docs/06_Product_Lines/PL01_Global_Layout.md @@ -0,0 +1,379 @@ +# PL01 — 全局布局设计 + +> **版本：V1.1 | 左导航 + 中间工作区 + 右 AI 侧栏 | Vue3 + Element Plus** +> **参考：pj006-zhilianyuan2 frontend-orgadmin 三栏布局模式** + +--- + +## 1. 布局结构 + +全站统一三栏布局： + +``` +┌──────┬───────────────────────────────────────┬────────────────┐ +│ 导航 │ │ │ +│ ───── │ 主工作区 │ AI PathCoach │ +│ 🏠 │ │ ──────────── │ +│ 首页 │ │ 你好，我是 │ +│ │ │ PathCoach... │ +│ 📄 │ │ │ +│ 公司 │ │ ┌──────────┐ │ +│ 介绍 │ │ │ 输入消息 │ │ +│ │ │ └──────────┘ │ +│ 📦 │ │ │ +│ 产品 │ │ [情景演练] │ +│ 知识 │ │ [查佣金] │ +│ │ │ [产品对比] │ +│ 🎯 │ │ │ +│ 销售 │ │ │ +│ 培训 │ │ │ +│ │ │ │ +│ 📝 │ │ │ +│ 考试 │ │ │ +│ ├ 自测│ │ │ +│ ├ 正式│ │ │ +│ ├ 记录│ │ │ +│ ├ 题库│ │ │ ← admin only +│ │ │ │ +│ ⚙️ │ │ │ ← admin only +│ 知识 │ │ │ +│ 管理 │ │ │ +│ ├ 素材│ │ │ +│ ├ 审批│ │ │ +│ │ │ │ +│ 🔧 │ │ │ ← admin only +│ 系统 │ │ │ +│ 管理 │ │ │ +│ ├ 用户│ │ │ +│ ├ 成绩│ │ │ +│ ├ 配置│ │ │ +└──────┴───────────────────────────────────────┴────────────────┘ +``` + +收起 AI 面板状态： + +``` +┌──────┬─────────────────────────────────────────────────────────┐ +│ 导航 │ │ +│ │ 主工作区（占满剩余宽度） │ +│ │ │ +│ │ [🤖 展开AI] │ +└──────┴─────────────────────────────────────────────────────────┘ +``` + +## 2. 组件树 + +``` +App.vue +└── MainLayout.vue + ├── SideNav.vue # 左边导航栏 + │ ├── logo + 品牌名 # 顶部品牌标识 + │ ├── NavMenu.vue # el-menu 纵向导航 + │ │ ├── employee-menus # 员工可见菜单 × 5 + │ │ │ ├── 首页 → / + │ │ │ ├── 公司介绍培训 → /company-train + │ │ │ ├── 产品知识 → /products + │ │ │ ├── 产品销售培训 → /courses + │ │ │ └── 考试（展开项） → /exam/* + │ │ └── admin-menus (v-if) # 管理员专属菜单 × 2 + │ │ ├── 知识管理（展开项） → /knowledge/* + │ │ └── 系统管理（展开项） → /system/* + │ └── user-info # 底部用户信息 + │ ├── full_name + │ └── [退出] + │ + ├── # 中间主内容区 + │ ├── HomeView.vue + │ ├── CompanyTrainView.vue + │ ├── ProductList/Detail.vue + │ ├── CourseList/Detail.vue + │ ├── ExamSelfTest/Formal/MyRecord/QuestionBank.vue + │ ├── MaterialManage/AuditList.vue (admin) + │ ├── UserManage/ExamRecordManage/SystemConfig.vue (admin) + │ └── Login.vue # 独立全屏，不含布局 + │ + └── PathCoachPanel.vue # 右侧 AI 侧栏 + ├── ChatHeader # (标题 + 收起按钮) + ├── ChatMessages # (消息列表，流式渲染) + ├── ChatInput # (输入框 + 发送) + └── QuickActions # (3个快捷按钮) +``` + +## 3. 组件职责与模板 + +### MainLayout.vue + +```vue + +``` + +### SideNav.vue + +```vue + +``` + +### PathCoachPanel.vue + +```vue + +``` + +## 4. 布局样式 + +```css +/* ========== 外层容器 ========== */ +.app-layout { + height: 100vh; + display: flex; +} + +/* ========== 左边导航 ========== */ +.side-nav { + width: 220px; + min-width: 220px; + background: #fff; + border-right: 1px solid #e4e7ed; + display: flex; + flex-direction: column; + overflow-y: auto; +} + +.side-nav__brand { + height: 60px; + display: flex; + align-items: center; + padding: 0 20px; + border-bottom: 1px solid #e4e7ed; +} + +.brand-text { + font-size: 18px; + font-weight: 700; + color: #1677ff; +} + +.side-nav__menu { + flex: 1; + border-right: none !important; +} + +.side-nav__footer { + padding: 12px 16px; +} + +.user-info { + display: flex; + justify-content: space-between; + align-items: center; + font-size: 14px; + color: #606266; +} + +/* ========== 中间容器 ========== */ +.main-container { + flex: 1; + display: flex; + overflow: hidden; +} + +.content-area { + flex: 1; + overflow-y: auto; + padding: 24px; + background: #f5f7fa; +} + +/* ========== AI 面板 ========== */ +.ai-panel { + width: 360px; + min-width: 360px; + border-left: 1px solid #e4e7ed; + display: flex; + flex-direction: column; + background: #fff; +} + +.ai-header { + padding: 14px 16px; + border-bottom: 1px solid #e4e7ed; + display: flex; + justify-content: space-between; + align-items: center; +} + +.ai-title { + font-weight: 600; + font-size: 15px; +} + +.ai-messages { + flex: 1; + overflow-y: auto; + padding: 16px; +} + +.ai-messages .message { + margin-bottom: 12px; +} + +.ai-messages .message.user { + text-align: right; +} + +.ai-messages .message.user .bubble { + display: inline-block; + background: #1677ff; + color: #fff; + border-radius: 8px 8px 0 8px; + padding: 8px 14px; + max-width: 80%; + text-align: left; +} + +.ai-messages .message.assistant .bubble { + display: inline-block; + background: #f5f7fa; + color: #303133; + border-radius: 8px 8px 8px 0; + padding: 8px 14px; + max-width: 80%; +} + +.ai-input { + padding: 12px 16px; + border-top: 1px solid #e4e7ed; + display: flex; + gap: 8px; +} + +.ai-quick-actions { + padding: 8px 16px 12px; + display: flex; + gap: 6px; + flex-wrap: wrap; +} + +.ai-quick-actions .el-button { + font-size: 12px; +} + +/* ========== 展开 AI 按钮（收起时显示） ========== */ +.ai-trigger { + position: fixed; + right: 0; + bottom: 80px; + z-index: 100; + padding: 8px 12px; + background: #1677ff; + color: #fff; + border-radius: 4px 0 0 4px; + cursor: pointer; + font-size: 13px; +} +``` + +## 5. 响应式说明 + +- 左边导航固定 **220px**，不响应 +- AI 面板固定 **360px**，可收起（收起后主内容区占满） +- 主内容区自适应剩余宽度，最小宽度 800px +- 登录页独立全屏，不包含此布局 \ No newline at end of file diff --git a/docs/06_Product_Lines/PL02_Employee_Views.md b/docs/06_Product_Lines/PL02_Employee_Views.md new file mode 100644 index 0000000..f0e631d --- /dev/null +++ b/docs/06_Product_Lines/PL02_Employee_Views.md @@ -0,0 +1,266 @@ +# PL02 — 员工端视图设计 + +> **版本：V1.1 | 框架：Vue3 + Element Plus** + +--- + +## 1. 首页（HomeView.vue） + +``` +┌─────────────────────────────────────────┐ +│ 欢迎回来，张三 │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ 公司介绍 │ │ 产品知识 │ │ 销售培训 │ │ +│ │ 培训 │ │ 手册 │ │ 课程 │ │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 最新培训通知 / 快捷入口 ││ +│ │ • 点击进入公司介绍培训 ││ +│ │ • 查看最新产品手册更新 ││ +│ │ • 进入自测练习 ││ +│ └─────────────────────────────────────┘│ +└─────────────────────────────────────────┘ +``` + +## 2. 公司介绍培训（CompanyTrainView.vue） + +``` +┌─────────────────────────────────────────┐ +│ 公司介绍培训 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ [纯阅读内容区域] ││ +│ │ 企业简介 (HTML/富文本) ││ +│ │ 双主营业务介绍 ││ +│ │ 对外统一口径 ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 相关课件 ││ +│ │ [公司简介.pptx] [公司宣传.mp4] ││ +│ │ [点击预览] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [提交素材建议] │ +└─────────────────────────────────────────┘ +``` + +**素材建议弹窗（MaterialSuggestUpload.vue）：** +```vue + + + + + + + + + + + +``` + +## 3. 产品知识（ProductView.vue） + +### 产品列表 +``` +┌─────────────────────────────────────────┐ +│ 产品知识 │ +│ │ +│ [全部] [资本咨询类] [资质认定] [AI...] │ ← 分类标签页 +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 产品卡片1 ││ +│ │ 编号：ZQ-001 ││ +│ │ 名称：资本运作咨询服务 ││ +│ │ 标签：资本咨询 / 战略 ││ +│ │ [查看详情] [前往培训课程] [向AI提问] ││ +│ ├─────────────────────────────────────┤│ +│ │ 产品卡片2 ││ +│ │ ... ││ +│ └─────────────────────────────────────┘│ +└─────────────────────────────────────────┘ +``` + +### 产品详情 +``` +┌─────────────────────────────────────────┐ +│ 资本运作咨询服务 │ +│ 编号：ZQ-001 分类：资本咨询类 │ +│ 标签：资本咨询 / 战略 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 业务内容说明 ││ +│ │ 为企业提供资本运作全流程咨询服务... ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 收费结构 ││ +│ │ 基础咨询费 ¥XXX + 成功佣金 XX% ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌──────┬──────────────────────────────┐│ +│ │ 佣金 │ 推荐：XX% 谈单参与：XX% ││ +│ │ │ ⚠️ 公开课超额分成：XX% ││ +│ └──────┴──────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 版本风险：... ││ +│ │ 报备规则：... ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [前往对应销售培训课程] [向 AI 提问] │ +└─────────────────────────────────────────┘ +``` + +## 4. 产品销售培训（CourseView.vue） + +### 课程列表 +``` +┌─────────────────────────────────────────┐ +│ 产品销售培训 │ +│ │ +│ [全部] [资本话术] [资质逻辑] [AI技巧] │ ← 分类标签页 +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 课程卡片1：资本产品谈单话术 ││ +│ │ 关联产品：资本运作咨询服务 ││ +│ │ [查看详情] [查看对应产品] ││ +│ ├─────────────────────────────────────┤│ +│ │ 课程卡片2：资质辅导销售逻辑 ││ +│ │ ... ││ +│ └─────────────────────────────────────┘│ +└─────────────────────────────────────────┘ +``` + +### 课程详情 +``` +┌─────────────────────────────────────────┐ +│ 资本产品谈单话术 │ +│ 关联产品：资本运作咨询服务 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 适配客户 & 禁接客户 ││ +│ │ 适配：... 禁接：... ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 标准话术 ││ +│ │ (HTML/富文本内容) ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 谈单流程 ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 异议处理 ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 交付避坑 / 报备规范 ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [查看对应产品] │ +└─────────────────────────────────────────┘ +``` + +## 5. 考试（ExamView.vue） + +### 自测练习（ExamSelfTest.vue） +``` +┌─────────────────────────────────────────┐ +│ 自测练习 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 选择考试配置 → 随机抽题 ││ +│ │ [开始自测] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ （答题界面） │ +│ ┌─────────────────────────────────────┐│ +│ │ 第1题（单选题） ││ +│ │ 博昇的主营业务包括？ ││ +│ │ ○ 资本咨询 ○ AI产业落地 ││ +│ │ ○ 房地产 ○ 以上都是 ││ +│ │ ││ +│ │ ✅ 答案：D ││ ← 即时显示 +│ │ 解析：博昇双主营业务... ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [上一题] [下一题] [交卷] │ +└─────────────────────────────────────────┘ +``` + +### 正式结业考试（ExamFormal.vue） +``` +┌─────────────────────────────────────────┐ +│ 正式结业考试 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 考试封面 ││ +│ │ 考试名称：公司介绍正式考试 ││ +│ │ 题量：20题 时长：30分钟 ││ +│ │ 合格线：60分 ││ +│ │ ││ +│ │ [开始考试] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ （答题界面 — 计时器倒计时） │ +│ ┌─────────────────────────────────────┐│ +│ │ 剩余时间：25:30 ││ +│ │ ││ +│ │ 第1题（判断题） ││ +│ │ 博昇同时从事资本咨询和AI产业落地。 ││ +│ │ ○ 正确 ○ 错误 ││ +│ │ ││ +│ │ 题号导航： ││ +│ │ [1] [2] [3] ... [20] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [上一题] [下一题] [交卷] │ +└─────────────────────────────────────────┘ +``` + +### 交卷结果 +``` +正式考试交卷后： +┌─────────────────────────────────────────┐ +│ 考试结果 │ +│ 考试名称：公司介绍正式考试 │ +│ 得分：85 / 100 是否通过：✅ 通过 │ +│ 答对：17题 答错：3题 │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 答题明细 ││ +│ │ 第1题 ✅ 正确答案：D ││ +│ │ 第2题 ❌ 你的答案：A 正确答案：C ││ +│ │ ... ││ +│ └─────────────────────────────────────┘│ +│ │ +│ [返回考试列表] │ +└─────────────────────────────────────────┘ +``` + +### 我的考试记录（ExamMyRecord.vue） +``` +┌─────────────────────────────────────────┐ +│ 我的考试记录 │ +│ │ +│ ┌─────┬──────┬────┬────┬────┬────────┐│ +│ │ 考试 │ 得分 │ 结果│ 时间│ 操作 │ ││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │公司介│ 85 │ ✅ │2026-│ [查看 ││ +│ │绍正式│ │ 通过│08-10│ 详情] ││ +│ │考试 │ │ │ │ ││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │产品知│ 60 │ ✅ │2026-│ [查看 ││ +│ │识考试│ │ 通过│08-05│ 详情] ││ +│ └─────┴──────┴────┴────┴────┴────────┘│ +└─────────────────────────────────────────┘ +``` \ No newline at end of file diff --git a/docs/06_Product_Lines/PL03_Admin_Views.md b/docs/06_Product_Lines/PL03_Admin_Views.md new file mode 100644 index 0000000..92c878d --- /dev/null +++ b/docs/06_Product_Lines/PL03_Admin_Views.md @@ -0,0 +1,266 @@ +# PL03 — 管理员端视图设计 + +> **版本：V1.1 | 框架：Vue3 + Element Plus** +> **参考：pj006-zhilianyuan2 frontend-orgadmin 的 CRUD 页面模式** + +--- + +## 1. 知识管理 — 课件素材管理（MaterialManage.vue） + +``` +┌─────────────────────────────────────────┐ +│ 课件素材管理 [+新增素材] │ +│ │ +│ ┌─筛选──────────────────────────────┐ │ +│ │ 状态：[全部] [待审批] [已通过] [驳回]│ │ +│ │ 搜索： [输入文件名...] [查询] │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ┌─────┬──────┬────┬────┬────┬────────┐│ +│ │ 文件名│ 类型 │ 状态│ 提交│ 绑定│ 操作 ││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │公司介│ pptx │ ✅ │ 张三│ 公司│ [预览]││ +│ │绍.pptx│ │ 通过│ │ │ [删除]││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │产品知│ mp4 │ ⏳ │ 李四│ 产品│ [审批]││ +│ │识.mp4│ │ 待审│ │ │ ││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │话术文│ doc │ ❌ │ 王五│ 课程│ [编辑]││ +│ │档.docx│ │ 驳回│ │ │ ││ +│ └─────┴──────┴────┴────┴────┴────────┘│ +│ │ +│ 分页：< 1 2 3 ... 10 > │ +└─────────────────────────────────────────┘ +``` + +**新增素材弹窗：** +```vue + + + + + upload +
拖拽或点击上传
+ + + + + + + + + + + + + + + + + + + +``` + +## 2. 知识管理 — 素材审批列表（MaterialAuditList.vue） + +``` +┌─────────────────────────────────────────┐ +│ 素材审批列表 │ +│ │ +│ ┌─────┬──────┬────┬────┬────┬────────┐│ +│ │ 文件名│ 提交人│ 类型│ 时间│ 预览│ 操作 ││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │产品话│ 李四 │ doc │08-15│[查看]│ [通过]││ +│ │术.docx│ │ │ │ │ [驳回]││ +│ ├─────┼──────┼────┼────┼────┼────────┤│ +│ │销售技│ 王五 │ mp4 │08-14│[查看]│ [通过]││ +│ │巧.mp4│ │ │ │ │ [驳回]││ +│ └─────┴──────┴────┴────┴────┴────────┘│ +│ │ +│ 分页：< 1 2 3 > │ +└─────────────────────────────────────────┘ +``` + +**驳回弹窗：** +```vue + + + + + + + + +``` + +## 3. 系统管理 — 用户账号管理（UserManage.vue） + +``` +┌─────────────────────────────────────────┐ +│ 用户账号管理 [+新增用户] │ +│ │ +│ ┌─────┬──────┬──────┬─────┬───────────┐│ +│ │ 用户名│ 姓名 │ 角色 │ 状态 │ 操作 ││ +│ ├─────┼──────┼──────┼─────┼───────────┤│ +│ │ admin│ 管理员│ 管理│ ✅ │ [编辑] [禁用] ││ +│ │ │ │ 员 │ 启用 │ ││ +│ ├─────┼──────┼──────┼─────┼───────────┤│ +│ │ zhangs│ 张三 │ 员工 │ ✅ │ [编辑] [禁用] ││ +│ │ an │ │ │ 启用 │ ││ +│ ├─────┼──────┼──────┼─────┼───────────┤│ +│ │ lisi │ 李四 │ 员工 │ ⛔ │ [编辑] [启用] ││ +│ │ │ │ │ 禁用 │ ││ +│ └─────┴──────┴──────┴─────┴───────────┘│ +└─────────────────────────────────────────┘ +``` + +**新增/编辑用户弹窗：** +```vue + + + + + + + + + + +
初始密码，用户首次登录后自行修改
+ + + + 员工 + 管理员 + + + + + + + + +``` + +## 4. 系统管理 — 全部考试成绩（ExamRecordManage.vue） + +``` +┌─────────────────────────────────────────┐ +│ 全部考试成绩 │ +│ │ +│ ┌─筛选──────────────────────────────┐ │ +│ │ 用户：[全部] 考试：[全部] 结果：[全部]│ │ +│ │ 日期： [开始] ~ [结束] [查询] │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ┌─────┬──────┬──────┬────┬────┬───────┐│ +│ │ 用户 │ 考试 │ 得分 │ 结果│ 时间│ 操作 ││ +│ ├─────┼──────┼──────┼────┼────┼───────┤│ +│ │ 张三 │公司介│ 85 │ ✅ │08-10│ [查看] ││ +│ │ │绍正式│ │ 通过│ │ [详情]││ +│ ├─────┼──────┼──────┼────┼────┼───────┤│ +│ │ 李四 │产品知│ 45 │ ❌ │08-09│ [查看] ││ +│ │ │识考试│ │ 未过│ │ [详情]││ +│ ├─────┼──────┼──────┼────┼────┼───────┤│ +│ │ ... │ ... │ ... │ ...│ ...│ ││ +│ └─────┴──────┴──────┴────┴────┴───────┘│ +│ │ +│ 分页：< 1 2 3 ... 20 > │ +│ 导出： [导出全部] [导出筛选结果] │ +└─────────────────────────────────────────┘ +``` + +## 5. 系统管理 — 系统参数配置（SystemConfig.vue） + +``` +┌─────────────────────────────────────────┐ +│ 系统参数配置 [保存配置] │ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ AI / LLM 配置 ││ +│ │ ││ +│ │ LLM 服务地址：[http://192.168.1.100 ││ +│ │ :11434/v1 ] ││ +│ │ API Key： [sk-xxx ] ││ +│ │ 模型名称： [qwen2.5:7b ] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ JWT 认证配置 ││ +│ │ ││ +│ │ Token 过期时间（分）：[480 ] ││ +│ └─────────────────────────────────────┘│ +│ │ +│ ┌─────────────────────────────────────┐│ +│ │ 文件上传配置 ││ +│ │ ││ +│ │ 文档最大字节（200MB）：[209715200 ]││ +│ │ 视频最大字节（2GB）： [2147483648 ]││ +│ │ 分片阈值（100MB）： [104857600 ]││ +│ └─────────────────────────────────────┘│ +└─────────────────────────────────────────┘ +``` + +## 6. 管理员 — 题库管理（ExamQuestionBank.vue） + +``` +┌─────────────────────────────────────────┐ +│ 题库管理 [+新增题目] │ +│ │ +│ ┌─筛选──────────────────────────────┐ │ +│ │ 知识域：[全部] [公司] [产品] [销售] │ │ +│ │ 题型：[全部] [单选] [多选] [判断] │ │ +│ │ 搜索： [输入题干...] [查询] │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ ┌─────┬──────┬──────┬────┬────────────┐│ +│ │ 题干 │ 类型 │ 知识域│ 状态│ 操作 ││ +│ ├─────┼──────┼──────┼────┼────────────┤│ +│ │博昇的│ 单选 │ 公司 │ 启用│ [编辑] [停用]││ +│ │主营..│ │ │ │ ││ +│ ├─────┼──────┼──────┼────┼────────────┤│ +│ │以下哪│ 多选 │ 产品 │ 启用│ [编辑] [停用]││ +│ │些...│ │ │ │ ││ +│ └─────┴──────┴──────┴────┴────────────┘│ +│ │ +│ 分页：< 1 2 3 ... 15 > │ +│ │ +│ 考试配置： [+新增考试] │ +│ ┌─────────────────────────────────────┐│ +│ │ 考试名称 │ 类型 │ 题量 │ 合格线 │ 操作 ││ +│ ├─────────┼──────┼─────┼───────┼──────┤│ +│ │公司考试 │ 正式 │ 20 │ 60 │ [编辑]││ +│ │自测练习 │ 自测 │ 10 │ -- │ [编辑]││ +│ └─────────┴──────┴─────┴───────┴──────┘│ +└─────────────────────────────────────────┘ +``` + +## 7. 各页面通用 CRUD 模式 + +所有管理员 CRUD 页面遵循统一的模式（参考 zhilianyuan2 frontend-orgadmin）： + +``` +┌─ 页面标题 ───────────── [+ 新增按钮] ─┐ +├─ 筛选栏 (表单) ───────────────────────┤ +├─ 数据表格 (el-table) ─────────────────┤ +│ 操作列: [编辑] [删除/停用] │ +├─ 分页栏 (el-pagination) ─────────────┤ +└──────────────────────────────────────┘ + +弹窗操作： + - 新增/编辑：el-dialog + el-form + - 删除确认：el-message-box.confirm + - 状态变更：el-switch 或 el-select +``` \ No newline at end of file diff --git a/docs/06_Product_Lines/README.md b/docs/06_Product_Lines/README.md new file mode 100644 index 0000000..ee83cd5 --- /dev/null +++ b/docs/06_Product_Lines/README.md @@ -0,0 +1,15 @@ +# 06_Product_Lines — 产品线与前端设计 + +> **命名规则：** `PL{NN}_{描述}.md` +> **用途：** 前端视图设计、页面流程、组件设计 +> +> **⚠️ 本目录 PL 文档为 V1 培训平台视图基线（首页/公司/产品/课程/考试 + 右侧 PathCoach）。** 平台升级后一级导航与工作台形态见 `SY03`（新导航）与 `SY17`（工作台线框图）。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `PL01_Global_Layout.md` | 全局布局设计（顶部导航 + AI 侧栏） | +| `PL02_Employee_Views.md` | 员工端视图（首页/公司/产品/课程/考试） | +| `PL03_Admin_Views.md` | 管理员端视图（知识管理/系统管理） | diff --git a/docs/08_Design_Rules/DR01_Theme_System.md b/docs/08_Design_Rules/DR01_Theme_System.md new file mode 100644 index 0000000..647da08 --- /dev/null +++ b/docs/08_Design_Rules/DR01_Theme_System.md @@ -0,0 +1,257 @@ +# DR01 — 主题系统设计 + +> **版本：V1.1 | UI 框架：Element Plus** +> **参考：pj006-zhilianyuan2 frontend-orgadmin 的主题覆盖模式** + +--- + +## 1. Element Plus 变量覆盖 + +```scss +// styles/element-variables.scss +$--color-primary: #1677ff; // 主色 — 博昇品牌蓝 +$--color-success: #52c41a; +$--color-warning: #faad14; +$--color-danger: #ff4d4f; +$--color-info: #909399; + +$--color-text-primary: #303133; +$--color-text-regular: #606266; +$--color-text-secondary: #909399; +$--color-text-placeholder: #c0c4cc; + +$--border-color-base: #dcdfe6; +$--border-color-light: #e4e7ed; +$--border-color-lighter: #ebeef5; +$--border-color-extra-light: #f2f6fc; + +$--background-color-base: #f5f7fa; + +$--border-radius-base: 4px; +$--border-radius-small: 2px; +$--border-radius-round: 20px; + +$--font-size-base: 14px; +$--font-size-medium: 16px; +$--font-size-small: 13px; +$--font-size-extra-small: 12px; +``` + +## 2. 全局 CSS 变量 + +```css +/* styles/variables.css */ +:root { + /* ===== 左边导航栏 ===== */ + --nav-width: 220px; + --nav-bg: #ffffff; + --nav-border: 1px solid #e4e7ed; + --nav-brand-height: 60px; + --nav-item-active-color: #1677ff; + --nav-item-active-bg: #ecf5ff; + --nav-item-hover-bg: #f5f7fa; + + /* ===== 主内容区 ===== */ + --content-padding: 24px; + --content-max-width: 1200px; + --content-bg: #f5f7fa; + + /* ===== AI 侧栏 ===== */ + --ai-panel-width: 360px; + --ai-panel-bg: #ffffff; + --ai-panel-border: 1px solid #e4e7ed; + + /* ===== 消息气泡 ===== */ + --bubble-user-bg: #1677ff; + --bubble-user-color: #ffffff; + --bubble-ai-bg: #f5f7fa; + --bubble-ai-color: #303133; + + /* ===== 表格 ===== */ + --table-stripe-bg: #fafafa; + --table-hover-bg: #f5f7fa; + + /* ===== 阴影 ===== */ + --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06); + --shadow-base: 0 2px 8px rgba(0, 0, 0, 0.08); + --shadow-lg: 0 4px 16px rgba(0, 0, 0, 0.12); +} +``` + +## 3. 统一页面容器样式 + +```css +/* 所有页面通用的容器样式 */ +.page-container { + max-width: var(--content-max-width); + margin: 0 auto; + padding: 0 var(--content-padding); +} + +.page-header { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 20px; +} + +.page-header h2 { + font-size: 20px; + font-weight: 600; + color: #303133; +} + +/* 筛选栏 */ +.filter-bar { + display: flex; + gap: 12px; + align-items: center; + margin-bottom: 16px; + padding: 16px; + background: #fff; + border-radius: 4px; + border: 1px solid #e4e7ed; +} + +/* 内容卡片 */ +.content-card { + background: #fff; + border-radius: 4px; + border: 1px solid #e4e7ed; + padding: 20px; + margin-bottom: 16px; +} +``` + +## 4. 按钮状态规范 + +| 状态 | 样式 | 色值 | +|------|------|------| +| 可用（主按钮） | 蓝色底白字 | `#1677ff` / `#ffffff` | +| 可用（普通按钮） | 白底灰边框 | `#ffffff` / `#606266` / `#dcdfe6` | +| 可用（文字按钮） | 无底蓝字 | 透明 / `#1677ff` | +| 不可用（禁用） | 灰底灰字 + cursor not-allowed | `#cbd5e1` / `#64748b` | +| 危险（删除） | 红底白字 | `#ff4d4f` / `#ffffff` | + +## 5. 主要组件样式 + +```css +/* ===== 左边导航栏 ===== */ +.side-nav { + width: var(--nav-width); + min-width: var(--nav-width); + background: var(--nav-bg); + border-right: var(--nav-border); + display: flex; + flex-direction: column; + overflow-y: auto; +} + +.side-nav__brand { + height: var(--nav-brand-height); + display: flex; + align-items: center; + padding: 0 20px; + border-bottom: var(--nav-border); + font-size: 18px; + font-weight: 700; + color: #1677ff; +} + +.side-nav__menu { + flex: 1; + border-right: none !important; +} + +.side-nav__menu .el-menu-item.is-active { + background-color: var(--nav-item-active-bg); + color: var(--nav-item-active-color); + border-right: 3px solid var(--nav-item-active-color); +} + +.side-nav__footer { + padding: 12px 16px; +} + +/* ===== AI 侧栏 ===== */ +.ai-panel { + width: var(--ai-panel-width); + min-width: var(--ai-panel-width); + background: var(--ai-panel-bg); + border-left: var(--ai-panel-border); + display: flex; + flex-direction: column; + height: 100%; +} + +.ai-header { + padding: 14px 16px; + border-bottom: var(--ai-panel-border); + display: flex; + justify-content: space-between; + align-items: center; + font-weight: 600; + font-size: 15px; +} + +.ai-messages { + flex: 1; + overflow-y: auto; + padding: 16px; +} + +.ai-messages .message { + margin-bottom: 12px; +} + +.ai-messages .message.user { + text-align: right; +} + +.ai-messages .message.user .bubble { + display: inline-block; + background: var(--bubble-user-bg); + color: var(--bubble-user-color); + border-radius: 8px 8px 0 8px; + padding: 8px 14px; + max-width: 80%; + text-align: left; +} + +.ai-messages .message.assistant .bubble { + display: inline-block; + background: var(--bubble-ai-bg); + color: var(--bubble-ai-color); + border-radius: 8px 8px 8px 0; + padding: 8px 14px; + max-width: 80%; +} + +.ai-input { + padding: 12px 16px; + border-top: var(--ai-panel-border); + display: flex; + gap: 8px; +} + +.ai-quick-actions { + padding: 8px 16px 12px; + display: flex; + gap: 6px; + flex-wrap: wrap; +} + +/* ===== 展开 AI 浮动按钮 ===== */ +.ai-trigger { + position: fixed; + right: 0; + bottom: 80px; + z-index: 100; + padding: 8px 12px; + background: #1677ff; + color: #fff; + border-radius: 4px 0 0 4px; + cursor: pointer; + font-size: 13px; +} +``` \ No newline at end of file diff --git a/docs/08_Design_Rules/DR02_Navigation_Rules.md b/docs/08_Design_Rules/DR02_Navigation_Rules.md new file mode 100644 index 0000000..297e542 --- /dev/null +++ b/docs/08_Design_Rules/DR02_Navigation_Rules.md @@ -0,0 +1,146 @@ +# DR02 — 导航与路由访问规则 + +> **版本：V1.1 | 左导航布局 | Vue3 + Element Plus + Vue Router** +> **参考：pj006-zhilianyuan2 frontend-orgadmin 的路由守卫模式** +> +> **⚠️ 本文为 V1 导航基线。** 管理员导航已拆为「6 组织管理 + 7 系统设置」（见 `00_AI_Context/forai02`）；一级导航将按 SY03 演进为「知识库 / 智能体 / 学习与考试 / 陪练与认证 / 内容运营 / 组织与系统」。本文第 1 节的菜单树为 V1 历史结构。 + +--- + +## 1. 导航菜单可见性规则 + +| 菜单 | 可见角色 | 类型 | 说明 | +|------|---------|------|------| +| 首页 | employee + admin | 一级菜单 | 所有人可见 | +| 公司介绍培训 | employee + admin | 一级菜单 | 所有人可见 | +| 产品知识 | employee + admin | 一级菜单 | 所有人可见 | +| 产品销售培训 | employee + admin | 一级菜单 | 所有人可见 | +| 考试 | employee + admin | 一级展开 | 所有人可见 | +| ├ 自测练习 | employee + admin | 子菜单 | — | +| ├ 正式结业考试 | employee + admin | 子菜单 | — | +| ├ 我的考试记录 | employee + admin | 子菜单 | — | +| └ 题库管理 | **admin only** | 子菜单 | **管理员专属，员工不可见** | +| 知识管理 | **admin only** | 一级展开 | **管理员专属，员工不可见** | +| ├ 课件素材管理 | admin only | 子菜单 | — | +| └ 素材审批列表 | admin only | 子菜单 | — | +| 系统管理 | **admin only** | 一级展开 | **管理员专属，员工不可见** | +| ├ 用户账号管理 | admin only | 子菜单 | — | +| ├ 全部考试成绩 | admin only | 子菜单 | — | +| └ 系统参数配置 | admin only | 子菜单 | — | + +## 2. 路由守卫实现 + +```javascript +// router/index.js +import { createRouter, createWebHistory } from 'vue-router' +import { useAuthStore } from '@/store/auth' + +const routes = [ + { + path: '/login', + component: () => import('@/views/Login.vue'), + meta: { requiresAuth: false }, + }, + { + path: '/', + component: MainLayout, + children: [ + // 员工 + 管理员都能访问 + { path: '', component: () => import('@/views/home/HomeView.vue') }, + { path: 'company-train', component: () => import('@/views/companyTrain/CompanyTrainView.vue') }, + { path: 'products', component: () => import('@/views/product/ProductList.vue') }, + { path: 'products/:id', component: () => import('@/views/product/ProductDetail.vue') }, + { path: 'courses', component: () => import('@/views/salesTrain/CourseList.vue') }, + { path: 'courses/:id', component: () => import('@/views/salesTrain/CourseDetail.vue') }, + { path: 'exam/self-test', component: () => import('@/views/exam/ExamSelfTest.vue') }, + { path: 'exam/formal', component: () => import('@/views/exam/ExamFormal.vue') }, + { path: 'exam/my-records', component: () => import('@/views/exam/ExamMyRecord.vue') }, + + // 管理员专属路由 + { + path: 'exam/questions', + component: () => import('@/views/exam/ExamQuestionBank.vue'), + meta: { requiresAdmin: true }, + }, + { + path: 'knowledge/materials', + component: () => import('@/views/knowledge/MaterialManage.vue'), + meta: { requiresAdmin: true }, + }, + { + path: 'knowledge/audit', + component: () => import('@/views/knowledge/MaterialAuditList.vue'), + meta: { requiresAdmin: true }, + }, + { + path: 'system/users', + component: () => import('@/views/system/UserManage.vue'), + meta: { requiresAdmin: true }, + }, + { + path: 'system/exam-records', + component: () => import('@/views/system/ExamRecordManage.vue'), + meta: { requiresAdmin: true }, + }, + { + path: 'system/config', + component: () => import('@/views/system/SystemConfig.vue'), + meta: { requiresAdmin: true }, + }, + ], + }, +] + +const router = createRouter({ history: createWebHistory(), routes }) + +// 路由守卫 +router.beforeEach((to, from, next) => { + if (to.path === '/login') { + next() + return + } + + const authStore = useAuthStore() + + // 未登录 → 跳转登录页 + if (!authStore.isLoggedIn) { + next('/login') + return + } + + // 管理员路由校验（⚠️ 前端仅作 UX 隐藏，非安全边界） + if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') { + next('/') + return + } + + next() +}) + +export default router +``` + +## 3. 后端鉴权对应规则 + +| 路由 | 后端校验 | 说明 | +|------|---------|------| +| `/api/auth/*` | 仅 login 无需认证 | — | +| `/api/company-train/*` | 需有效 JWT | 员工/管理员均可 | +| `/api/products/*` | 需有效 JWT | 员工/管理员均可 | +| `/api/courses/*` | 需有效 JWT | 员工/管理员均可 | +| `/api/exam/list\|cover\|start\|submit\|record` | 需有效 JWT | 学员端考试 | +| `/api/exam/questions\|papers` | 需 admin 角色 | 题库/考试配置管理 | +| `/api/media/upload\|preview\|status` | 需有效 JWT | 文件操作 | +| `/api/media/audit*` | 需 admin 角色 | 素材审批 | +| `/api/system/*` | 需 admin 角色 | 系统管理全部 | +| `/api/ai-chat/*` | 需有效 JWT | 员工/管理员均可 | +| `/api/health` | 无需认证 | 健康检查 | + +## 4. 安全边界说明 + +> **前端路由守卫仅提供用户体验层面的菜单隐藏和路径拦截，不能作为安全边界。** +> **所有权限校验必须在后端 API 层强制执行。** +> +> 即使员工通过直接输入 URL 访问 `/knowledge/materials`： +> 1. 前端路由守卫会拦截并重定向 → UX 保护 +> 2. 如果前端拦截被绕过，后端 API 返回 403 → 真正安全边界 \ No newline at end of file diff --git a/docs/08_Design_Rules/DR03_Interaction_Rules.md b/docs/08_Design_Rules/DR03_Interaction_Rules.md new file mode 100644 index 0000000..3b55ac1 --- /dev/null +++ b/docs/08_Design_Rules/DR03_Interaction_Rules.md @@ -0,0 +1,113 @@ +# DR03 — 交互规范 + +> **版本：V1.1 | 框架：Element Plus** + +--- + +## 1. 按钮状态规范 + +| 场景 | 样式 | 色值 | 说明 | +|------|------|------|------| +| 主操作（提交/保存/开始） | `el-button type="primary"` | `#1677ff` | 页面中的主要行动点 | +| 次要操作（取消/返回） | `el-button`（默认） | `#ffffff` / `#606266` | 非主要行动点 | +| 危险操作（删除/驳回） | `el-button type="danger"` | `#ff4d4f` | 不可逆操作 | +| 文字操作（编辑/查看） | `el-button text` | `#1677ff` | 表格中操作列 | +| 禁用态 | `el-button disabled` | 灰底 `#cbd5e1` + 灰字 `#64748b` | 不可点击状态 | +| 快捷按钮（AI 侧栏） | `el-button size="small"` | 默认样式 | 3 个快捷入口 | + +**关键规则（CODING_RULES 第 6 条）：** +- 所有可点击的关键交互按钮必须使用蓝色底 `#1677ff` +- `disabled` 状态变化后，底色必须立即同步变化 +- 不可用按钮保持 `cursor: not-allowed` + +## 2. 加载与反馈 + +| 场景 | 组件 | 行为 | +|------|------|------| +| 页面加载 | `v-loading` | 全屏或区域加载遮罩 | +| 表单提交 | `el-button` loading 状态 | 按钮显示转圈，禁止重复点击 | +| 表格查询 | `el-table v-loading` | 表格区域加载 | +| 操作成功 | `ElMessage.success` | 顶部轻提示，2s 自动消失 | +| 操作失败 | `ElMessage.error` | 显示错误信息 | +| 确认操作 | `ElMessageBox.confirm` | 弹窗确认（删除/驳回等） | + +## 3. 弹窗使用规范 + +| 类型 | 组件 | 场景 | +|------|------|------| +| 表单弹窗 | `el-dialog` | 新增/编辑 CRUD | +| 确认弹窗 | `el-message-box` | 删除/禁用确认 + 驳回理由输入 | +| 素材提交 | `el-dialog` | 员工提交素材建议（MaterialSuggestUpload） | +| 预览弹窗 | `el-dialog` + iframe | PDF 预览 / 视频播放 | +| 选择器弹窗 | `el-dialog` + `el-tree` | 绑定产品/课程选择 | + +## 4. 表单交互规则 + +```javascript +// 通用规则 +- 必填字段标红色 * +- 提交前校验（el-form :rules） +- 提交按钮 disable 直到表单合法 +- 提交中按钮 loading，禁止重复点击 +- 成功后关闭弹窗 + 刷新表格 +- 失败后保持弹窗，显示错误信息 +``` + +## 5. 表格交互规则 + +```javascript +// 通用规则 +- 支持分页（el-pagination） +- 支持筛选栏（过滤条件） +- 操作列放最右侧，统一宽度 +- 表格行 hover 高亮 +- 长文本省略显示（show-overflow-tooltip） +- 空数据展示「暂无数据」 +``` + +## 6. AI 聊天框交互规则 + +| 场景 | 行为 | +|------|------| +| 展开/收起 | 点击右上角 ✕ 收起，底部显示 [🤖 展开AI] 按钮 | +| 发送消息 | Enter 键或点击发送按钮 | +| 流式响应 | SSE 实时流式显示，打字机效果 | +| 上下文切换 | 切换页面时自动清理旧上下文，注入新页面上下文 | +| 快捷动作 | 点击快捷按钮触发对应的 API | +| 窗口切换 | 页面路由变化不清空对话历史（全局常驻） | + +## 7. 错误处理交互 + +| HTTP 状态 | 用户看到 | 行为 | +|-----------|---------|------| +| 400 参数错误 | `ElMessage.warning` + 字段标红 | 表单校验错误 | +| 401 未认证 | 跳转到登录页 | 清除 token 并跳转 | +| 403 无权限 | `ElMessage.warning` + 跳转首页 | 前端+后端双重拦截 | +| 404 资源不存在 | `ElMessage.error` + 提示 | — | +| 500 服务器错误 | `ElMessage.error`「系统异常，请稍后重试」| — | +| 网络断开 | `ElMessage.error`「网络连接异常」| — | + +## 8. 页面间跳转逻辑 + +| 来源页面 | 目标页面 | 传递参数 | 方式 | +|---------|---------|---------|------| +| 产品详情 | 对应课程 | `courseId` | `` | +| 课程详情 | 对应产品 | `productId` | `` | +| 产品详情 | 向 AI 提问 | `productId` + `page: "product_detail"` | 展开 AI 侧栏 + 自动注入 | +| 课程详情 | 向 AI 提问 | `courseId` + `page: "course_detail"` | 同上 | +| 考试列表 | 考试封面 | `paperId` | `router.push` | +| 考试封面 | 答题页面 | `paperId` | `router.push` | +| 考试结果 | 考试记录 | `recordId` | `router.push` | + +## 9. 素材提交入口（弹窗而非独立页面） + +``` +素材提交仅在以下页面以弹窗形式出现： +- 公司介绍培训页面 → 点击「提交素材建议」 +- 产品详情页面 → 点击「提交素材建议」 +- 课程详情页面 → 点击「提交素材建议」 + +弹窗内容： + 文件上传 + 备注说明 + 不提供独立页面访问 +``` \ No newline at end of file diff --git a/docs/08_Design_Rules/README.md b/docs/08_Design_Rules/README.md new file mode 100644 index 0000000..4215c77 --- /dev/null +++ b/docs/08_Design_Rules/README.md @@ -0,0 +1,15 @@ +# 08_Design_Rules — UI/UX 设计规范 + +> **命名规则：** `DR{NN}_{描述}.md` +> **用途：** 前端 UI 规范、交互规则、主题系统 +> +> **注：** 导航规则（DR02）需随平台一级导航演进（知识库/智能体/学习与考试/陪练与认证/内容运营/组织与系统）同步，见 SY03。 + +## 文件清单 + +| 文件 | 说明 | +|------|------| +| `README.md` | 本索引文件 | +| `DR01_Theme_System.md` | 主题系统（Element Plus 变量覆盖） | +| `DR02_Navigation_Rules.md` | 导航规则（菜单/权限显示/路由守卫） | +| `DR03_Interaction_Rules.md` | 交互规范（按钮状态/反馈/弹窗） | diff --git a/docs/09_Research/Workflow_Canvas_Interaction_Research.md b/docs/09_Research/Workflow_Canvas_Interaction_Research.md new file mode 100644 index 0000000..b1e0eb9 --- /dev/null +++ b/docs/09_Research/Workflow_Canvas_Interaction_Research.md @@ -0,0 +1,625 @@ +# 工作流画布交互设计调研报告 + +> **版本：V2.0 | 最后更新：2026-08-17** +> **目标产品：eaisalestrain-app · 数字员工平台 · 工坊（Studio）** + +--- + +## 目录 + +1. [调研范围与背景](#1-调研范围与背景) +2. [行业产品全景对比](#2-行业产品全景对比) +3. [节点体系设计](#3-节点体系设计) + - 3.1 三节点 vs 五节点体系 + - 3.2 子类型（SubType）架构 + - 3.3 连接器作为被引用资源 +4. [画布交互模型](#4-画布交互模型) + - 4.1 拖入创建（Drag & Drop） + - 4.2 右键菜单体系 + - 4.3 键盘快捷键体系 + - 4.4 选中与视觉反馈 + - 4.5 Edge 交互（连线） +5. [布局与导航](#5-布局与导航) +6. [技术实现（VueFlow）](#6-技术实现vueflow) + - 6.1 核心事件 + - 6.2 自定义节点 + - 6.3 自定义边 + - 6.4 CSS 主题与样式 +7. [当前实现状态](#7-当前实现状态) +8. [待完成项](#8-待完成项) +9. [参考资料](#9-参考资料) + +--- + +## 1. 调研范围与背景 + +### 1.1 调研目标 + +为数字员工平台的 **工坊（Studio）** 模块设计一套符合行业标准、贴近业务用户心智的工作流画布交互模型。核心需求： + +- 业务用户能通过 **拖拽 + 配置** 的方式定义数字员工的工作流程 +- 画布交互对标 Dify / n8n / Make / Zapier / Coze 等主流产品 +- 节点体系从 SY18（信源/动作/结果/权限）简化为 3 节点体系（开始/动作/结束） + +### 1.2 调研的产品 + +| 产品 | 定位 | 节点体系 | 画布引擎 | 参考版本 | +|------|------|----------|----------|----------| +| **Dify** | AI 工作流编排 | 开始/LLM/工具/结束等 | React Flow | v1.14.0 | +| **n8n** | 自动化工作流 | 触发器/动作 | 自研 | latest | +| **Make** | 可视化自动化 | 触发器/动作/模块 | 自研 | latest | +| **Zapier** | 轻量自动化 | Trigger/Action/Search | 自研 | latest | +| **Coze** | AI Bot 构建 | 开始/LLM/插件/知识库/结束 | 自研 | latest | +| **Langflow** | LLM 流程编排 | Input/LLM/Output | React Flow | latest | +| **VueFlow** | 画布引擎库 | N/A | Vue Flow | v1.44+ | + +--- + +## 2. 行业产品全景对比 + +### 2.1 产品定位对比 + +| 维度 | Dify | n8n | Make | Zapier | Coze | 本产品 | +|------|------|-----|------|--------|------|--------| +| 目标用户 | 开发者/AI 工程师 | 技术运营 | 业务用户 | 业务用户 | 业务用户+开发者 | HR/销售/业务用户 | +| 复杂度 | 中高 | 高 | 中 | 低 | 中 | 中 | +| 拖入创建 | ✅ | ✅ | ✅ | ❌（点击添加） | ✅ | ✅ | +| 右侧检查器 | ✅ | ✅ | ✅ | ✅（弹窗） | ✅ | ✅ | +| 节点右键菜单 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Edge 右键菜单 | ✅（PR#33391） | ✅ | ✅ | ❌ | ❌ | ✅ | +| Delete 键删除 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Ctrl+D 复制 | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | +| Ctrl+Z 撤销 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | +| 连线 "+" 按钮 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | + +### 2.2 画布布局对比 + +| 产品 | 左侧面板 | 右侧面板 | 工具栏 | 布局风格 | +|------|----------|----------|--------|----------| +| Dify | 节点选择（可折叠） | 检查器（选中后出现） | 顶部薄栏 | 左-中-右 | +| n8n | 节点库 | 编辑面板 | 顶部 | 左-中-右 | +| Make | 模块库（浮层） | 配置面板 | 顶部 | 中-右（浮层） | +| Zapier | 无（步骤式） | 弹窗配置 | 顶部 | 步骤向导 | +| Coze | 节点/插件/知识库 | 配置区（底部弹出） | 顶部 | 左-中-右 | +| **本产品** | **节点库+工具区** | **检查器面板** | **顶部 48px** | **左-中-右** | + +--- + +## 3. 节点体系设计 + +### 3.1 三节点 vs 五节点体系 + +**行业共识：主流产品均采用 3~4 种核心节点类型。** +Dify: Start → LLM/Tool → End +n8n: Trigger → Action → No explicit end +Make: Trigger → Module → No explicit end +Zapier: Trigger → Action/Search → No explicit end +Coze: Start → LLM/Plugin/Knowledge → End + +**本产品的演进：** +- **旧（SY18 模型）**：5 种节点（input / connector / action / result / permission） +- **新（Zapier/Dify 对齐）**：3 种节点（start / action / end） + - start（开始节点）：取代旧的 input + connector + - action（动作节点）：保留旧的 action + - end（结束节点）：取代旧的 result + permission + +### 3.2 子类型（SubType）架构 + +三节点通过 **子类型（SubType）** 实现具体的行为分化，避免了节点类型爆炸： + +``` +start (开始节点) + ├── schedule (⏰ 定时触发) + ├── file (📎 文件触发) + ├── connector (🔌 连接器触发) + └── manual (✍️ 手动触发) + +action (动作节点) + ├── ai (🤖 AI 处理) + ├── code (💻 代码处理) + ├── condition (🔀 条件分支) + └── connector (🔌 连接器操作) + +end (结束节点) + ├── data (📊 返回数据) + ├── file (📁 文件输出) + └── connector (🔌 连接器输出) +``` + +**核心设计原则：** +- 每种节点只有一个 **子类型下拉选择**，用户在检查器中切换 +- subType 改变时自动清除不兼容的配置（如从 `connector` 切到 `ai` 时清除 `connectorKey`） +- 子类型的标签包含 emoji 前缀，便于视觉识别（参考 Dify 的节点 icon + label） + +### 3.3 连接器作为被引用资源 + +**关键架构决策：连接器不是画布上的独立节点类型。** + +在旧的 SY18 模型中，"信源"被理解为连接器。经过对 Zapier/Make.com/Coze/Dify 的调研发现： + +| 产品 | 连接器(Connector)的角色 | +|------|------------------------| +| Zapier | Trigger 和 Action 通过下拉选择 APP + 事件/操作，APP 就是连接器 | +| Make | Module 可以选择不同的 Service，Service 就是连接器 | +| Dify | 工具（Tools）是独立节点，但连接器/数据源是 LLM 或知识库的属性 | +| Coze | 插件（Plugin）是独立节点，连接器是 Bot 的配置属性 | + +**本产品的方案：** +- 连接器不是画布节点，而是 **start/action/end 节点通过 subType='connector' 引用的资源** +- 连接器列表在 **工具区** 中管理，由工具栏 `☑ 🔌 连接器` 按钮控制显示/隐藏 +- 用户可以从工具区 **点击添加** 一个 start 节点并自动绑定到选中的连接器 +- 在检查器中，当 subType='connector' 时，显示连接器绑定下拉 + +--- + +## 4. 画布交互模型 + +### 4.1 拖入创建（Drag & Drop） + +**Dify 标准流程：** +1. 从左侧节点列表拖出一个节点类型 +2. 拖到画布上释放 +3. 节点出现在释放位置，自动选中并打开右侧配置面板 + +**本产品实现：** +```vue + +
+ ... +
+ + +
+ ... +
+``` + +**拖放数据流：** +```javascript +dragstart → setData('application/dw-node-kind', kind) +dragover → 显示 drop 提示（drag-over class） +drop → screenToFlowCoordinate → createCanvasNode +dragend → 清理状态 +``` + +### 4.2 右键菜单体系 + +**Dify 标准（PR #34138 + PR #33391）：** +- **节点右键菜单**：编辑节点 / 复制节点 / 删除节点 / 断开所有连线 + - 新版本还支持多选节点时的对齐操作 +- **Edge 右键菜单**：删除连线（PR #33391, 2026-03 合并） + - 右键点击连线弹出删除选项 + - 菜单互斥：同一时间只有一个菜单可见 +- **画布空白右键菜单**：粘贴 / 适配视图 / 重置 + +**本产品实现：** + +**节点右键菜单：** +```vue +
+
✏️ 编辑节点
+
📋 复制节点
+
+
🗑️ 删除节点
+
🔗 断开所有连线
+
+ + +
+
🗑️ 删除连线
+
+``` + +**菜单互斥逻辑：** +```javascript +function handleEdgeContextMenu({ edge, event }) { + event.preventDefault() + closeNodeContextMenu() // 关闭节点菜单 + closeEdgeContextMenu() // 关闭已有边菜单 + edgeContextMenu.edgeId = edge.id + edgeContextMenu.x = event.clientX + edgeContextMenu.y = event.clientY + edgeContextMenu.visible = true +} + +function handlePaneClick() { + selectedNodeId.value = '' + closeNodeContextMenu() + closeEdgeContextMenu() +} +``` + +### 4.3 键盘快捷键体系 + +**Dify 快捷键标准：** +| 快捷键 | 功能 | +|--------|------| +| Delete | 删除选中的节点或边 | +| Backspace | 删除选中节点或边（有争议，用户易误触） | +| Ctrl+D | 复制选中节点 | +| Ctrl+Z | 撤销 | +| Ctrl+Shift+Z / Ctrl+Y | 重做 | +| Shift + 点击 | 多选节点 | +| Arrow keys | 移动选中节点 | +| Ctrl+A | 全选 | + +**本产品实现：** +```javascript +function handleKeyDown(event) { + const tag = event.target.tagName + // 输入框中不触发 + if (tag === 'INPUT' || tag === 'TEXTAREA' || event.target.isContentEditable) return + + if (event.key === 'Delete' || event.key === 'Backspace') { + // 1. 先关菜单（如果有） + if (contextMenu.visible || edgeContextMenu.visible) { + closeNodeContextMenu() + closeEdgeContextMenu() + event.preventDefault() + return + } + // 2. 删选中的边 + const selectedEdges = edges.value.filter(e => e.selected) + if (selectedEdges.length > 0) { + edges.value = edges.value.filter(e => !e.selected) + event.preventDefault() + return + } + // 3. 删选中的节点 + const selectedNodes = nodes.value.filter(n => n.selected) + if (selectedNodes.length > 0) { + const selectedIds = new Set(selectedNodes.map(n => n.id)) + nodes.value = nodes.value.filter(n => !selectedIds.has(n.id)) + edges.value = edges.value.filter(e => !selectedIds.has(e.source) && !selectedIds.has(e.target)) + event.preventDefault() + } + } +} +``` + +### 4.4 选中与视觉反馈 + +**节点选中状态：** +- VueFlow 原生支持 `node.selected` 属性 +- 点击节点 → 节点获得 `.selected` class → 边框变色 + 阴影增强 +- 点击画布空白 → 取消全部选中 + +**本产品的颜色体系：** + +| 节点类型 | 边框色 | 选中色 | +|----------|--------|--------| +| start | `#409eff` (蓝) | 实线蓝色 + 蓝光阴影 | +| action | `#e6a23c` (橙) | 实线橙色 + 橙光阴影 | +| end | `#67c23a` (绿) | 实线绿色 + 绿光阴影 | + +### 4.5 Edge 交互（连线） + +**Dify 标准：** +1. **连接操作**：从一个节点的右侧 handle 拖到另一个节点的左侧 handle +2. **选中**：点击连线 → 连线高亮（变蓝变粗） +3. **右键菜单**：右键点击连线 → 弹出删除选项 +4. **Delete 键删除**：选中连线后按 Delete 键 +5. **Hover "+" 按钮**：鼠标悬停在连线上 → 中点出现 "+" 按钮 → 点击后插入一个新节点（串行） +6. **断开连接**：从 handle 拖出新连线覆盖已有连线，自动替换 + +**本产品实现：** + +**Edge 视觉反馈（CSS）：** +```css +/* 点击区域加宽 */ +:deep(.vue-flow__edge-path) { + stroke-linecap: round; + transition: stroke 0.15s, stroke-width 0.15s; +} + +/* hover 高亮 */ +:deep(.vue-flow__edge:hover .vue-flow__edge-path) { + stroke: #409eff; + stroke-width: 2.5; +} + +/* 选中高亮 */ +:deep(.vue-flow__edge.selected .vue-flow__edge-path) { + stroke: #409eff; + stroke-width: 3; +} +``` + +**Handle hover：** +```css +:deep(.vue-flow__handle) { + transition: transform 0.12s, background 0.12s; +} +:deep(.vue-flow__handle:hover) { + transform: scale(1.3); + background: #409eff; +} +``` + +--- + +## 5. 布局与导航 + +### 5.1 整体布局结构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ [头部 Header · 48px] │ +├────────┬────────────────────────────────────┬───────────────┤ +│ 左侧 │ 画布区域 │ 右侧检查器 │ +│ 节点库 │ Canvas (VueFlow) │ Inspector │ +│ +工具区 │ │ (选中后出现) │ +│ │ ┌────┐ ┌────┐ ┌────┐ │ │ +│ │ │ S │──→│ A │──→│ E │ │ │ +│ │ └────┘ └────┘ └────┘ │ │ +│ │ │ │ +├────────┴────────────────────────────────────┴───────────────┤ +│ [工具栏] ← ☑ 🔌 连接器 | ⚙ 设置 | [保存] │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 5.2 左侧节点库（Toolbox） + +| 区域 | 内容 | 可折叠 | +|------|------|--------| +| 头部 | "节点库" + ◀ 折叠按钮 | ✅ | +| 节点列表 | 开始节点/动作节点/结束节点（可拖拽） | 跟随折叠 | +| 分隔线 | - | - | +| 工具区标题 | "工具区" | - | +| 连接器工具 | 连接器列表（由工具栏按钮控制可见性） | ✅（点击文字折叠） | + +**展开状态宽度：200px** +**折叠状态宽度：52px（只显示图标）** + +### 5.3 右侧检查器（Inspector） + +| 区域 | 内容 | +|------|------| +| 头部 | "节点检查器" | +| 当前节点 | 显示节点标题（只读） | +| 节点类型 | 显示类型标签（只读） | +| 子类型选择 | el-select 下拉（start: 定时/文件/连接器/手动; action: AI/代码/条件/连接器; end: 数据/文件/连接器） | +| 连接器绑定 | 仅 subType='connector' 时显示，el-select 选择连接器 | +| 节点标题 | el-input 可编辑 | +| 节点说明 | el-input textarea 可编辑 | +| 节点位置 | X/Y 坐标（只读） | +| 上下游 | 上游节点 / 下游节点（只读） | + +--- + +## 6. 技术实现（VueFlow） + +### 6.1 核心事件 + +| VueFlow 事件 | 用途 | 当前状态 | +|-------------|------|----------| +| `@node-click` | 点击节点 → 选中 + 显示检查器 | ✅ | +| `@node-context-menu` | 右键节点 → 弹出菜单 | ✅ | +| `@edge-click` | 点击连线 → 选中高亮 | ✅ | +| `@edge-context-menu` | 右键连线 → 删除菜单 | ✅ | +| `@connect` | 建立连线 | ✅ | +| `@pane-click` | 点击画布空白 → 取消选中 + 关菜单 | ✅ | +| `@pane-ready` | 画布初始化 → 绑定键盘事件 | ✅ | +| `@nodes-change` | 节点变化 | ❌（未用） | +| `@edges-change` | 边变化 | ❌（未用） | +| `@node-drag-stop` | 拖拽停止 | ❌（未用） | + +### 6.2 自定义节点 + +```javascript +// 节点定义 +const newNode = { + id: `${kind}-${nodeCounter}`, + type: 'dw', // 自定义节点类型，对应