跳到主要内容
AI教程

SoftJL Community 上手教程：用 AI 串联需求、UML、测试与说明书

本文介绍如何部署 SoftJL Community，配置 OpenAI 兼容模型，并以图书馆座位预约系统为例，完成需求确认、可行性分析、UML 建模、测试覆盖和工程说明书生成。

AI我搜编辑部阅读约 11 分钟
SoftJL Community 上手教程：用 AI 串联需求、UML、测试与说明书

SoftJL Community 是什么

SoftJL Community 是一个面向软件类毕业设计、课程设计和 UML 作业的可独立部署 AI 软件工程工作台。它把需求分析、可行性分析、UML 建模、设计、测试、工程文档和变更追踪连接起来，帮助你检查需求是否落实到设计与测试，并为修改、汇报和答辩整理可追溯的依据。

社区版提供完整源码，按 Apache License 2.0 授权。与官网托管版相比，社区版需要自行管理服务、数据库和模型供应商，但保留了需求规则提取、完整需求与设计模型、测试覆盖、说明书生成、来源追踪、项目管理以及 BYOK 模型接入等主要能力。

官网首页 — 桌面首屏

核心工作流程

平台围绕一条从需求到验证的工程链路工作：先输入需求并确认规则，再开展可行性分析，生成需求模型和设计模型，接着生成测试用例与覆盖矩阵，最后生成可编辑和可下载的工程说明书。

  • 需求规则：从自然语言需求中提取规则，进行质量检查、修订、人工确认和验收条件整理。
  • 可行性分析：生成系统环境图、业务与系统流程图，以及实现方案分析。
  • UML 模型：建立功能结构、用例、领域概念、原型界面、部署需求、总体架构、设计类和数据库等模型。
  • 测试与覆盖：生成正常、异常和边界场景的测试用例，并通过覆盖矩阵和追踪矩阵定位缺口。
  • 工程文档：生成可行性研究报告、需求规格说明书和软件设计说明书，并支持版本管理和 DOCX 下载。
  • 变更影响：查看需求、设计、测试和说明书之间的来源关系，判断修改后哪些产物需要更新。
  • 模型接入：配置 OpenAI 兼容的模型服务，调用自己的模型供应商。
生成结果用于定位和整理工程依据，仍需要人工核对模型约束、图表内容、说明书业务一致性，并在实际系统中执行测试。

安装前的环境准备

首次运行需要准备以下环境：

  • Node.js 22
  • npm 10
  • Java 21
  • Graphviz
  • 可选：Docker，用于运行 PostgreSQL 和 OnlyOffice

首次使用渲染服务时，系统可能需要联网下载 PDF 中文字体。Docker 不是核心服务临时体验的必需项，但长期使用建议配置持久化 PostgreSQL；如果需要在线编辑 DOCX，还需要启用 OnlyOffice。

快速启动核心服务

1. 获取源码并安装依赖

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

2. 启动开发环境

npm run dev

该命令会自动构建 contracts 和 prompts 共享包，并并行启动 Web、API 和渲染服务。Web 通常运行在 http://localhost:3000，API 使用 4101 端口，Render Service 使用 4002 端口。

看到 Web 输出 Ready 后，可以打开 http://localhost:3000。同时建议检查健康状态：

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

两个健康检查接口都应返回包含 status: "ok" 的结果。

3. 了解临时内存模式

直接运行 npm run dev 默认使用临时内存模式。服务重启后，账号、项目、模型服务配置和运行历史会丢失；文档文件单独保存在本地目录，也不能替代数据库备份。因此该模式适合快速体验，不适合长期保存项目。

配置持久化数据库和在线编辑

使用开发 PostgreSQL

官网首页 — 桌面首屏

本机安装并启动 Docker 后，可以使用下列命令运行专用开发数据库和核心服务：

npm run dev:postgres

该方式会把数据库保存在 Docker 数据卷中。脚本中的数据库凭据仅用于本机开发，生产环境必须替换，不要把已有完整版数据库直接作为社区版数据库使用。

连接已有 PostgreSQL

如果已经准备好 PostgreSQL，可以复制根目录的 .env.example 为 .env，然后设置 DATABASE_URL 和自行生成的 UML_PROVIDER_CONFIG_SECRET：

cp .env.example .env

配置完成后重新运行 npm run dev。请妥善保管加密密钥，因为随意更换 UML_PROVIDER_CONFIG_SECRET 会导致已保存的模型供应商凭据无法解密。数据库连接信息和密钥也不要提交到 Git。

启用 OnlyOffice

需要在线编辑说明书时，先启动 Docker 引擎，再运行：

npm run dev:full

该脚本会检查本机 8080 端口的 OnlyOffice；如果服务不可用，会创建或启动对应容器，首次运行可能需要下载镜像。只有核心服务也可以生成和下载文档，在线编辑功能需要额外配置 OnlyOffice。

配置 AI 模型服务

  1. 启动 Web 服务并登录账号。
  2. 进入账号设置，新增一个 OpenAI 兼容 Provider。
  3. 填写模型供应商的 HTTPS Base URL 和 API Key。
  4. 执行模型发现和连接测试。
  5. 选择一个可用模型作为默认模型。

自部署环境使用你自己的模型服务，模型调用费用由对应供应商结算。生产环境应使用持久化数据库和凭据加密密钥，并关闭开发访客和 legacy 明文回退入口。

用图书馆座位预约系统完成一次建模

下面以一个简单需求为例：学生登录后查询空闲座位，选择日期和时间段提交预约；同一学生在同一时间段不能重复预约；预约成功后发送通知；管理员可以维护座位、查看预约记录并处理异常取消。

第 1 步：创建项目并确认需求规则

创建项目后，将上述业务描述输入平台，让系统提取需求规则。重点检查用户角色、预约条件、重复预约约束、通知行为和异常取消流程。确认无误后保存规则和验收条件，避免后续模型建立在含糊需求之上。

第 2 步：完成可行性分析

按照项目流程完成三项分析：

  • 系统环境图：明确学生、管理员、通知服务和预约系统之间的边界与交互。
  • 业务与系统流程图：梳理查询座位、提交预约、发送通知和异常取消的处理流程。
  • 实现方案：比较候选方案，记录成本、收益和风险。

分析完成后，先核对系统边界和流程是否符合原始需求，再进入模型生成阶段。

第 3 步：生成需求模型和设计模型

平台可以根据已确认的需求生成完整需求模型，包括功能结构、总体业务流程、用例、领域概念、原型界面关系和部署需求。需求模型确认后，再按前置关系生成设计模型，例如总体架构、用例实现、设计类、页面导航、数据库、组件关系和部署设计。

仪表盘统计与产物生成耗时

生成后打开来源关系，检查每个设计元素是否能够回溯到需求规则。这样在预约规则发生变化时，可以更容易识别受影响的用例、类、数据库设计和测试。

第 4 步：生成测试和覆盖矩阵

围绕预约系统至少检查以下场景：

  • 学生能够查询指定日期和时间段的空闲座位。
  • 学生能够提交有效预约并收到通知。
  • 同一学生在同一时间段重复预约时，系统能够拒绝请求。
  • 没有空闲座位、时间段不合法或预约信息缺失时，系统能够处理异常。
  • 管理员能够维护座位、查看预约记录并处理异常取消。

通过覆盖矩阵和追踪矩阵定位没有设计依据或测试依据的需求。平台生成的测试用例仍需在实际系统中执行，不能仅以生成成功作为验收结果。

第 5 步：生成工程说明书

完成可行性分析、需求模型和设计模型后，可以生成三类工程文档：可行性研究报告、需求规格说明书和软件设计说明书。生成后检查正文与图表是否一致，按学校模板和格式要求修改，再进行版本管理和 DOCX 下载。

仪表盘统计与产物生成耗时

需求变更时的处理方法

例如，项目将规则从“同一学生同一时间段不能重复预约”修改为“同一学生每天最多预约两个时间段”。不要只修改说明书中的一句话，而应沿来源和依赖关系检查：

  1. 保存并确认新的需求规则。
  2. 打开来源关系和变更影响，查看受影响的需求、用例、设计和测试产物。
  3. 按依赖顺序更新需求模型和设计模型。
  4. 重新检查数据库约束、业务流程和异常处理。
  5. 更新测试用例和覆盖矩阵，并在实际系统中执行回归测试。
  6. 重新生成或修订相关说明书，保留版本记录。

来源连线和覆盖数量适合帮助你定位检查范围，但最终仍要打开具体模型，核对约束、输入条件和行为是否完整。

连接外部 Coding Agent

社区版可以由部署者自行启用只读 MCP 接入，让兼容的 Coding Agent 读取项目范围内已保存的设计、验收条件、工程约束和测试信息。MCP 本地体验入口为侧栏“编程助手”或项目设置中的“连接此项目”，使用前需要先完成安装和构建。

npm run dev:mcp

该接入只读提供工程依据，不会替代代码审查、实际运行和测试验收。README 还特别说明，真实 Coding Agent 客户端兼容性和生成代码验收仍在完善，使用时应参考MCP 接入说明。

常用开发命令

  • npm run build:packages：构建 contracts 和 prompts 共享包。
  • npm run build：构建共享包和全部应用。
  • npm run dev:render：单独启动 PlantUML 渲染服务。
  • npm run test:contracts：验证共享契约。
  • npm run test:api：运行 API 测试。
  • npm run test:render：运行渲染服务测试。
  • npm run test:web：运行完整 Web 测试。
  • npm run typecheck:web：检查 Web 类型。
  • npm run lint:web：执行 Web 静态检查。
  • npm audit --audit-level=high：检查依赖安全公告。

共享包发生变化后，单独启动应用或运行测试前，应先执行 npm run build:packages。构建输出、环境配置、私钥、日志和本地运行数据应保持在 Git 忽略范围内。

架构概览

项目采用多应用和共享包结构：

  • apps/web：React、Next.js 工作区和页面。
  • apps/api：Fastify API、认证、生成流水线、运行记录和文档组装。
  • apps/render-service：PlantUML 图形渲染。
  • packages/contracts 和 packages/prompts：共享契约和生成提示。
  • packages/harness-e2e 和 packages/harness-eval：验收与质量评估。

部署和使用注意事项

  • 社区版应使用独立数据库，不要将其作为官网完整版数据库的降级替代。
  • 开发启动脚本中的数据库凭据仅适合本机使用，生产环境必须更换。
  • 模型密钥、数据库连接信息和加密密钥不得提交到代码仓库。
  • 工程说明书可以作为项目报告材料，但不等同于完整毕业论文。
  • 图表、说明书和代码的业务一致性需要人工检查，并通过运行证据验证。
  • 生产部署前应替换服务域名、数据库、邮件和模型配置。

总结

SoftJL Community 适合希望把毕业设计或课程设计按工程流程组织起来的开发者。完成环境安装、数据库和模型配置后，你可以从需求规则出发，逐步生成可行性分析、UML 需求与设计模型、测试覆盖和工程说明书，并在需求变更时追踪影响范围。

它能够减少资料分散和重复整理，但不能替代人工设计判断、代码实现、真实测试和最终答辩准备。建议将平台生成内容作为可追踪的工程草稿和检查依据，结合学校要求与实际系统运行结果完成最终交付。