智学领航

智学领航 是面向中国软件杯金蝶赛道与软件工程课程实验的一体化项目，定位为“基于金蝶云·苍穹低代码平台和苍穹 Agent 平台的智能学业成长闭环平台”。

本仓库当前提供三类交付物：

• 可本地运行的 Java 业务内核与苍穹插件适配骨架，验证学生端、教师端、教务端、AI 按钮和业务闭环。
• 可本地运行的 Java 实体 API 服务，暴露健康检查、实体状态、按钮动作和 Agent 动作接口，便于前端或苍穹插件迁移验证。
• 可本地运行的真实 KDesign 组件版三端闭环前端，覆盖学生端、教师端、教务端、DeepSeek/MiMo 兼容 Agent 写回和 PostgreSQL 实体持久化。
• 可直接用于金蝶复现、PPT、视频和提交材料的产品、系统设计和苍穹部署包文档。

代码量里 JavaScript 较多，是因为当前仓库同时放了 KDesign React 前端、Node 本地 Agent/实体代理和静态演示壳，目的是让作品可以直接打开、演示和连接 PostgreSQL。比赛复现口径仍以 Java 为业务实现主体：src/main/java 承担核心业务规则、闭环逻辑和苍穹插件适配，前端与 Node 服务只作为本地演示和联调壳层。

核心范围

系统固定为三端结构：

• 学生端：学生画像、培养方案、课程地图、学习任务、学习资源、学业规划、预警中心、成长档案。
• 教师端：高风险学生、风险解释、导师批注、干预建议、谈话提纲、干预记录、跟踪复盘。
• 教务端：培养方案维护、课程地图维护、预警规则配置、知识库维护、学习资源维护、教务驾驶舱。

AI 设计采用“统一多技能学业 Agent + 多处表单 AI 按钮”：

• 画像完整度分析
• 能力雷达图生成
• 学分缺口分析
• 课程地图生成
• 薄弱课程分析
• 补强建议生成
• 本周学习计划生成
• 打卡表现总结
• 学业规划生成
• 学习时间轴生成
• 预警原因解释
• 风险改善方案生成
• 干预建议生成
• 谈话提纲生成
• 干预效果总结
• 学期风险报告生成
• 规则调整影响分析

本地运行

另一台电脑从 GitHub 拉取、安装 KDesign、配置 AI API、启动 PostgreSQL、迁移数据库和运行 Java API 的完整步骤，见 docs/development/new-computer-setup.md。

质量门禁脚本位于 scripts/ci-validate.sh，会依次运行 npm run test:entity、npm run build:kdesign 和 npm run test:java；若本机安装了 Maven，会追加执行 mvn -q -DskipTests compile 验证 Java + JDBC 编译边界。本地 Java 脚本会优先使用 JAVA_HOME，也会自动发现项目根目录 .jdk/ 下解压的 JDK，便于在未全局安装 Java 的机器上复现。

运行自动化测试：

powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1

macOS/Linux 可直接运行 Java 验收：

npm run test:java

如果系统没有全局 Java，可把 JDK 解压到项目根目录 .jdk/。该目录已被 .gitignore 忽略，不会随 GitHub 提交；团队其他电脑只需安装系统 JDK 17+，或使用同样的 .jdk/ 目录即可运行 Java 测试、控制台演示和 Java 实体 API。PowerShell 脚本和 macOS/Linux shell 脚本使用同一套发现顺序：JAVA_HOME -> .jdk/ -> 系统 java/javac。

运行控制台演示：

powershell -ExecutionPolicy Bypass -File .\scripts\demo.ps1

macOS/Linux 可直接运行 Java 控制台演示：

npm run demo:java

运行 Java 实体 API 服务：

npm run serve:java-api

默认监听 http://127.0.0.1:8080，提供 /api/entity/health、/api/entity/state、/api/entity/action 和 /api/agent。该服务使用 src/main/java 的业务内核与 CangqiongPluginAdapter，用于证明后端主体可以由 Java 承接；/api/agent 已支持表单短写回、右侧连续对话，以及 Markdown、成绩单Excel、学业计划类结构化产物三种模式。Node 服务仍保留为本地 KDesign 开发阶段的 DeepSeek、MiMo 和通用 OpenAI 兼容模型代理。

Java API 默认使用内存状态。若需要让 Java API 直接连接 PostgreSQL，请先初始化数据库，再用 Maven 启动以加载 PostgreSQL JDBC 驱动；serve:java-api:pg 同样会使用 JAVA_HOME 或 .jdk/ 自动定位 JDK：

docker compose up -d postgres
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zhixuelinghang
npm run db:setup:docker
npm run serve:java-api:pg

连接成功后，Java API 会从 PostgreSQL 统计 29 类核心数据对象，并把画像/成长目标、学习任务、任务打卡、预警反馈、课程评价、成长档案、成长机会、学业规划、对话记录、学习产物、干预、批注、知识文档、教务通知、课堂同步、Agent评测、分析报告和操作审计等关键动作写入数据库；未配置或连接失败时仍回退 Java 内存状态，保证演示不断链。

如需让 KDesign 前端直接调用 Java API，在 .env.local 增加：

VITE_ENTITY_API_BASE=http://127.0.0.1:8080

不配置时前端默认调用同源 /api/*，继续使用 Vite/Node 本地代理和 PostgreSQL 桥接。 也可以直接使用 Java 优先脚本：

npm run serve:java-api
npm run dev:kdesign:java

dev:kdesign:java 会让 KDesign 前端的实体状态、按钮动作和 Agent 动作直接请求 http://127.0.0.1:8080。Java API 已返回 KDesign 可消费的学生、课程、成绩、行为、通知、课堂、课表、考试、座位、规划、风险、档案、知识库、对话记录、学习产物和系统核验数据；右侧 Agent 对话和结构化产物也可由 Java API 返回 provider: "java-core" 的结果。部分前端即时状态会在 Java 成功返回后做页面镜像，保证演示交互不断链。

打开 Web 演示页面：

powershell -ExecutionPolicy Bypass -File .\scripts\serve-web.ps1

运行真实 KDesign 组件版：

npm install
npm run dev:kdesign

运行 Java 后端直连版：

npm run serve:java-api
npm run dev:kdesign:java

验证实体层：

npm run test:entity

Agent 配置文件为项目根目录的 .env.local。前端只调用本地 /api/agent 代理，不会暴露模型 API Key。未填写 Key 时自动回退本地短结果，便于演示不断链。

DeepSeek 推荐配置：

DEEPSEEK_API_KEY=你的DeepSeekKey
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
VITE_ENTITY_API_BASE=http://127.0.0.1:8080

也可以显式指定通用 OpenAI 兼容 Provider：

AGENT_PROVIDER=deepseek
AGENT_API_KEY=你的DeepSeekKey
AGENT_BASE_URL=https://api.deepseek.com
AGENT_MODEL=deepseek-v4-flash

MiMo 兼容配置仍保留：

MIMO_API_KEY=你的Key
MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
MIMO_MODEL=mimo-v2.5-pro
VITE_ENTITY_API_BASE=http://127.0.0.1:8080

AGENT_PROVIDER 显式指定时优先生效；未指定时系统按 DEEPSEEK_API_KEY、MIMO_API_KEY、AGENT_API_KEY 的顺序自动选择 Provider。npm run dev:kdesign 和 npm run serve:entity 都会读取项目根目录的 .env.local。

启用 PostgreSQL 实体持久化：

docker compose up -d postgres
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zhixuelinghang
npm run db:setup:docker
npm run dev:kdesign

如果本机没有安装 psql，直接使用 npm run db:setup:docker 和 npm run db:psql 即可，命令会调用 PostgreSQL 容器内置客户端。

构建后运行实体服务：

npm run build:kdesign
npm run serve:entity

构建后服务同时提供静态页面、/api/entity/* 和 /api/agent。未配置 DATABASE_URL 时，系统使用本地内存实体状态；配置后，任务、打卡、通知、课堂快照、干预、批注、规则、知识库、对话记录和学习产物会写入 PostgreSQL。实体层按产品文档覆盖 29 张核心表，并在“系统核验”抽屉以中文业务对象显示记录数。

目录说明

• src/main/java：纯 Java 业务原型，包含领域模型、三端门户和 Agent 模拟能力。
• src/main/java/com/zhixuelinghang/cangqiong：苍穹 Java 插件适配骨架，将平台按钮动作映射到 Java 业务内核。
• src/main/java/com/zhixuelinghang/api：Java 实体 API 服务边界，暴露健康检查、状态查询、动作执行和 Agent 接口。
• src/test/java：端到端业务验收测试。
• web：本地三端 Web 演示页面。
• kdesign-app：真实 @kdcloudjs/kdesign 组件版三端闭环系统。
• server：实体 API、PostgreSQL 存储和构建后运行服务。
• database：PostgreSQL 表结构、脱敏种子数据和迁移说明。
• compose.yaml：本地 PostgreSQL 容器配置。
• docs/competition/product-specification.md：参赛产品与系统设计总文档。
• docs/competition/implementation-coverage.md：本地实现对总文档、三端、AI按钮、数据对象和测试主线的覆盖矩阵。
• docs/competition/cangqiong-deployment-package.md：金蝶云·苍穹复现部署包说明。
• docs/competition/cangqiong-deployment-manifest.json：苍穹对象、流程、Agent、按钮和验收的结构化清单。
• docs/course：软件工程课程实验材料。
• 资料：赛题、金蝶平台和往届优秀作品参考资料。
• scripts：测试、演示和文档处理脚本。

金蝶复现关系

本地 Java 原型不是最终平台口径，而是用于快速验证优秀作品级别的业务闭环和交互结构。最终参赛复现应以金蝶云·苍穹为主体：

• Java 领域对象对应苍穹基础资料和业务单据。
• CangqiongPluginAdapter 对应苍穹按钮事件、自定义操作或 Java 插件入口。
• JavaEntityApiServer 对应可迁移为苍穹后端服务或 Java API 网关的实体接口层。
• 三端 Portal 对应苍穹应用入口、动态表单和权限范围。
• AI 按钮对应苍穹 Agent 任务流、按钮事件、自定义操作或 Java 插件。
• DashboardMetrics 对应苍穹轻分析和教务驾驶舱。
• product-specification.md 中的核心表结构可直接指导苍穹建模。
• cangqiong-deployment-package.md 和 cangqiong-deployment-manifest.json 可作为苍穹复现时的对象、流程、Agent 和验收清单。