471 lines
26 KiB
Python
471 lines
26 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""
|
||
【已废弃】曾配合 clear_body 生成软设，会破坏 xxx 模板版式。
|
||
|
||
请改用：python build_spec_documents.py
|
||
"""
|
||
|
||
from docx import Document
|
||
from docx.enum.text import WD_ALIGN_PARAGRAPH
|
||
from spec_srs_builder import _add_table
|
||
|
||
|
||
def _h(doc, text, level=1):
|
||
doc.add_heading(text, level=level)
|
||
|
||
|
||
def _p(doc, text, bold=False):
|
||
p = doc.add_paragraph()
|
||
r = p.add_run(text)
|
||
r.bold = bold
|
||
return p
|
||
|
||
|
||
def _long_para(doc, *parts):
|
||
for part in parts:
|
||
doc.add_paragraph(part)
|
||
|
||
|
||
def build_sdd_document(doc):
|
||
"""向已清空正文的 Document 写入软件设计说明。"""
|
||
t = doc.add_paragraph("方案自动化生成系统")
|
||
t.alignment = WD_ALIGN_PARAGRAPH.CENTER
|
||
doc.add_paragraph("软件设计说明").alignment = WD_ALIGN_PARAGRAPH.CENTER
|
||
doc.add_paragraph("")
|
||
|
||
_h(doc, "1 CSCI 体系结构设计", 1)
|
||
_h(doc, "1.1 系统 CSCI 层次", 2)
|
||
_long_para(
|
||
doc,
|
||
"本系统为单进程多模块 Maven 工程，版本 3.9.1，根描述名「方案自动化生成」。CSCI 在运行期体现为："
|
||
"一个 Spring Boot 可执行 JAR（管理端服务子系统，模块名对应 auto-solution-admin）作为 HTTP 服务入口，"
|
||
"在类路径上装配核心框架子模块、系统管理子模块、行为树子模块、场景子模块、规则子模块、算法子模块、"
|
||
"定时任务子模块、代码生成子模块与通用基础子模块。持久化使用关系型数据库（以 Druid + MySQL 为典型部署），"
|
||
"缓存与会话可依赖 Redis。建模器为独立 Vite+Vue 前端，开发态通过 /api 代理至后端 1777 端口；"
|
||
"与后端属于浏览器—服务器架构。",
|
||
)
|
||
|
||
_h(doc, "1.1.1 主要 CSCI/模块划分", 2)
|
||
_add_table(
|
||
doc,
|
||
["名称（中文）", "工程目录/构件", "职责概述"],
|
||
[
|
||
["管理端服务子系统", "auto-solution-admin", "提供 REST 控制器、应用主类 SolutionApplication、Swagger 等"],
|
||
["核心框架子模块", "auto-solution-framework", "安全、Token、MyBatis/数据源/Redis/切面/异常"],
|
||
["通用基础子模块", "auto-solution-common", "实体/工具/统一返回/异常体系"],
|
||
["系统管理子模块", "auto-solution-system", "组织用户、角色菜单、系统参数、日志等"],
|
||
["行为树业务子模块", "auto-solution-behaviour", "行为树、节点、边、参数、命令字典"],
|
||
["仿真场景子模块", "auto-solution-scene", "场景、平台通信、与行为树/规则联动"],
|
||
["规则与火力业务子模块", "auto-solution-rule", "Drools、规则配置、火力元数据、执行服务"],
|
||
["算法脚本子模块", "auto-solution-algo", "算法、参数、与外部脚本执行"],
|
||
["定时任务子模块", "auto-solution-quartz", "Quartz 任务与执行日志"],
|
||
["代码生成子模块", "auto-solution-generator", "库表扫描与代码生成"],
|
||
],
|
||
)
|
||
|
||
_h(doc, "1.1.2 执行方案与部署视图", 2)
|
||
_long_para(
|
||
doc,
|
||
"逻辑执行路径（典型）：浏览器加载建模器静态资源→用户 /login 获取 Token→在 axios 请求头中附带 Token→"
|
||
"调用 /api/... 业务接口→经 JwtAuthenticationTokenFilter 与 SecurityFilterChain 鉴权后进入各 Controller→"
|
||
"由 Service/Mapper 访问 MySQL/Redis。规则计算在规则与火力子模块中实现，可调用资源目录下 JSON/规则 DRL 等。",
|
||
"物理部署上：可单机部署于 Windows/Linux；后端监听端口在 application.yml 中配置，默认 1777；"
|
||
"Redis 默认 127.0.0.1:6379；业务库为 MyBatis 映射的库表（behaviortree、scene/afsim 相关、rule、algorithm、sys_* 等）。"
|
||
"与软需中 A/B 类能力划分一致，不在此重复追踪表。",
|
||
)
|
||
try:
|
||
doc.add_paragraph("图1 方案自动化生成系统执行方案与模块依赖（与软需图1 含义一致，可自绘为逻辑框图）", style="Caption")
|
||
except Exception:
|
||
doc.add_paragraph("图1 方案自动化生成系统执行方案与模块依赖。")
|
||
|
||
_h(doc, "1.2 与外部/内部接口", 2)
|
||
_long_para(
|
||
doc,
|
||
"对建模器：外部接口即浏览器通过 HTTP/HTTPS 访问的 REST 集合，建模器在 src/views/decision 下以 HttpRequestClient 组织；"
|
||
"以 /api 为业务前缀的接口与 Spring @RequestMapping(\"/api/...\") 对齐。",
|
||
"对操作系统：通过 ProcessBuilder/Runtime 在 AlgorithmController 中可调用本机 Python 可执行文件（以代码中配置路径为准，当前实现含固定盘符时须部署环境保持可用）。",
|
||
"内部接口为 Spring 的 Service 与 Mapper 依赖注入关系；规则子模块为场景、火力接口提供 findPlatformComponents、execute 等能力。",
|
||
)
|
||
|
||
_h(doc, "1.2.1 接口控制说明（方自-设计-EIF-01）", 2)
|
||
_add_table(
|
||
doc,
|
||
["接口标识", "方向", "说明", "类"],
|
||
[
|
||
["EIF-WEB-01", "外部→本系统", "建模器/浏览器 REST 调用", "A 为主、B 为管理扩展"],
|
||
["EIF-DB-01", "本系统↔库", "MyBatis 访问表", "全类"],
|
||
["EIF-REDIS-01", "本系统↔缓存", "Token 等", "A/B"],
|
||
["EIF-OS-01", "本系统→OS", "可选子进程", "A（算法 run）"],
|
||
],
|
||
)
|
||
|
||
# --- 分模块详设（拉长篇幅）---
|
||
_h(doc, "2 子系统/模块详细设计", 1)
|
||
|
||
def module_block(name, key, text_blocks, table_rows):
|
||
_h(doc, f"2.{key} {name}", 2)
|
||
for blk in text_blocks:
|
||
_long_para(doc, blk)
|
||
if table_rows:
|
||
_add_table(
|
||
doc,
|
||
["方自-设计-要素", "说明"],
|
||
table_rows,
|
||
)
|
||
|
||
module_block(
|
||
"管理端服务子系统（方自-设计-0200）",
|
||
1,
|
||
[
|
||
"管理端子系统承载所有对外 Controller，包路径 com.solution.web.controller，下分 system、behaviour、scene、rule、algo、monitor、common 等。",
|
||
"统一基类为 com.solution.common.core.controller.BaseController，成功与失败返回与 AjaxResult、TableDataInfo 一致；权限注解以 @PreAuthorize 为主（以实际代码为准）。",
|
||
"Swagger 通过 auto-solution-admin 的 SwaggerConfig 与 springfox-boot-starter 暴露，便于 B 类接口的联调。",
|
||
"应用主类 SolutionApplication 以 @SpringBootApplication 启动并排除 DataSource 自动配置，配合自定义 Druid/MyBatis 配置。",
|
||
],
|
||
[
|
||
["主类", "com.solution.SolutionApplication"],
|
||
["静态资源/跨域", "com.solution.framework.config.ResourcesConfig 等"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"核心框架子模块（方自-设计-0210）",
|
||
2,
|
||
[
|
||
"该模块聚合横切与基础设施：com.solution.framework.config 包内 SecurityConfig 定义 JWT 与登录退出链；Druid 数据源与 druid 监控页；"
|
||
"Redis 序列化、MyBatis 映射扫描、I18n、Kaptcha 等。",
|
||
"com.solution.framework.web.service 提供 SysLoginService、TokenService、UserDetailsService，与登录控制器协作。",
|
||
"com.solution.framework.security 提供 JwtAuthenticationTokenFilter、各 AuthenticationEntryPoint/Logout 扩展。",
|
||
"日志与防重复等通过 aspectj 包中 LogAspect、RepeatSubmitInterceptor 等实现（以实际类为准）。",
|
||
],
|
||
[
|
||
["安全过滤", "JwtAuthenticationTokenFilter"],
|
||
["密码服务", "SysPasswordService"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"系统管理子模块与通用基础子模块（方自-设计-0211）",
|
||
3,
|
||
[
|
||
"系统管理子模块为典型组织权限模型，对应 sys_user、sys_role、sys_menu、sys_dept 等表与 ISys*Service 实现。",
|
||
"该部分接口路径多为 /system/...，在建模器侧除登录/会话外多数未用，设计为 B 类能力，供后台管理或未来接入。",
|
||
"通用基础子模块提供核心实体、分页、Excel、异常与注解，为所有子模块所依赖。",
|
||
],
|
||
[
|
||
["用户服务", "SysUserServiceImpl 等"],
|
||
["字典服务", "SysDictType/ Data"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"行为树业务子模块（方自-设计-0212）",
|
||
4,
|
||
[
|
||
"领域对象包括行为树、节点实例、边（父子顺序）、参数值、节点模板、模板参数定义、节点命令字典等；"
|
||
"Mapper 位于 auto-solution-behaviour 的 resources/mapper/system，表名如 behaviortree、treenodeinstance、nodeconnection、nodeparameter、nodetemplate、templateparameterdef。",
|
||
"IBehaviortreeService 实现复制、按平台/场景查询、更新平台 id 等；Treenodeinstance 支持 list/saveOrUpdate/批量。",
|
||
"与建模器设计器、通信视图的 A 类接口一一对应，见接口汇总表。",
|
||
],
|
||
[
|
||
["树表", "behaviortree"],
|
||
["节点实例", "treenodeinstance"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"仿真场景子模块（方自-设计-0213）",
|
||
5,
|
||
[
|
||
"SceneService 提供 insert、update、saveOrUpdate、selectSceneList、findOneById、getAllTree、getAllRelation；"
|
||
"控制层 SceneController 映射在 /api/system/scene 下。",
|
||
"AfsimScenario 等域对象承载场景 JSON/通信图等，与 modeler 侧 Scenario 类型对齐。",
|
||
"与规则子模块共同支撑「场景 id 下平台+组件」的火力/通信视角。",
|
||
],
|
||
[
|
||
["场景", "AfsimScenario/Form"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"规则与火力业务子模块（方自-设计-0214）",
|
||
6,
|
||
[
|
||
"规则子模块包含 RuleMapper、RuleDrl 同步、规则配置、火力输入输出 DTO、Drools 工作内存装配等。",
|
||
"RuleController 中 **规则主数据** 的 list/get/post/put/delete 映射在源码中为块注释，当前仅 **规则聚合（config）** 相关 REST 生效；"
|
||
"规则配置包括 /config/list、/config/graph、/config/graph/four-blocks、/config/{ruleCode}、/config 的 POST/PUT、/config/{ruleCodes} DELETE、/config/dict、/config/param-meta。",
|
||
"FireRuleController 对规则执行、武器/通信元数据、平台-组件、component 子查询及 POST /rule 等暴露；与建模器对接情况见接口表 A/B。",
|
||
"资源目录下 JSON 规则样例为工程内可交付资产（如 auto-solution-rule/src/main/resources/json/）。",
|
||
],
|
||
[
|
||
["规则主表", "rule"],
|
||
["配置", "规则 config 与 DB/JSON 协同，以实现为准"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"算法脚本子模块（方自-设计-0215）",
|
||
7,
|
||
[
|
||
"Algorithm 实体、AlgorithmParam 与 typeHandler 对 algo_config 进行映射；IAlgorithmService 与 AlgorithmController 提供 /api/algo/algorithm 的 CRUD、export、GET id、/run。",
|
||
"/run 中通过 Process 调用 Python 并回写输出，部署时需保证可执行文件路径、权限与参数 JSON 与前端一致。",
|
||
],
|
||
[
|
||
["主表", "algorithm"],
|
||
],
|
||
)
|
||
|
||
module_block(
|
||
"定时任务子模块、代码生成子模块（方自-设计-0216）",
|
||
8,
|
||
[
|
||
"定时任务子模块在 /monitor/job、/monitor/jobLog 暴露任务与日志 CRUD/导出，与 Quartz 调度器协同；配置见 ScheduleConfig。",
|
||
"代码生成子模块在 /tool/gen 下提供表、列、预览、下载生成代码；为 B 类能力。",
|
||
],
|
||
[
|
||
["Quartz 域", "SysJob、SysJobLog"],
|
||
],
|
||
)
|
||
|
||
doc.add_page_break()
|
||
|
||
_h(doc, "2.9 接口设计汇总（摘录）", 1)
|
||
_long_para(
|
||
doc,
|
||
"下表以 Controller 映射为主键整理，A/B 含义同软需；{id} 等为路径参数。",
|
||
"完整与最新列表可在运行态通过 Swagger 与各 *Controller 源码核对。",
|
||
)
|
||
|
||
iface = [
|
||
["管理端", "POST", "/login", "登录", "A"],
|
||
["管理端", "GET", "/getInfo", "当前用户", "A"],
|
||
["管理端", "POST", "/logout", "登出", "A"],
|
||
["验证码", "GET", "/captchaImage", "验证码", "B"],
|
||
["系统管理", "GET/POST/...", "/system/user/...", "用户", "B"],
|
||
["系统管理", "*", "/system/role/...", "角色", "B"],
|
||
["系统管理", "*", "/system/menu/...", "菜单", "B"],
|
||
["系统管理", "*", "/system/dept/...", "部门", "B"],
|
||
["系统管理", "*", "/system/dict/...", "字典", "B"],
|
||
["系统管理", "*", "/system/config/...", "参数", "B"],
|
||
["系统管理", "*", "/system/notice/...", "通知", "B"],
|
||
["监控", "*", "/monitor/online/...", "在线", "B"],
|
||
["监控", "*", "/monitor/operlog/...", "操作日志", "B"],
|
||
["监控", "*", "/monitor/logininfor/...", "登录日志", "B"],
|
||
["监控", "*", "/monitor/server", "服务信息", "B"],
|
||
["监控", "*", "/monitor/cache/...", "缓存", "B"],
|
||
["任务", "*", "/monitor/job/...", "任务", "B"],
|
||
["任务", "*", "/monitor/jobLog/...", "任务日志", "B"],
|
||
["公共", "*", "/common/...", "上传下载", "B"],
|
||
["代码生成", "*", "/tool/gen/...", "生成", "B"],
|
||
["行为树", "GET/POST/PUT/DELETE", "/api/system/behaviortree/...", "树", "A"],
|
||
["行为树", "GET/POST/PUT/DELETE", "/api/system/treenodeinstance/...", "树节点实例", "A+CRUD+saveOrUpdate"],
|
||
["行为树", "*", "/api/system/nodeconnection/...", "边", "A"],
|
||
["行为树", "*", "/api/system/nodeparameter/...", "参数", "A"],
|
||
["行为树", "*", "/api/system/nodetemplate/...", "模板", "A"],
|
||
["行为树", "*", "/api/system/templateparameterdef/...", "模板参数", "A"],
|
||
["行为树", "GET", "/api/node/command/all", "节点命令", "A"],
|
||
["场景", "GET/POST", "/api/system/scene/...", "场景", "A"],
|
||
["规则", "—", "/api/system/rule 根路径 CRUD", "RuleController 中块注释，当前未启用", "—"],
|
||
["规则", "GET/POST/PUT/DELETE", "/api/system/rule/config/...", "规则聚合（配置）", "A 已启用"],
|
||
["火力", "GET/POST", "/api/system/firerule/...", "元数据/执行", "A+B 混合"],
|
||
["算法", "GET/POST/PUT/DELETE/POST", "/api/algo/algorithm/...", "算法", "A"],
|
||
]
|
||
_add_table(
|
||
doc,
|
||
["子域", "HTTP", "路径特征", "说明", "A/B"],
|
||
iface,
|
||
)
|
||
|
||
# 大表2：分路径明细（再占篇幅）
|
||
detail = [
|
||
(m, pth, a) for m, pth, a in [
|
||
("行为树", "/api/system/behaviortree/list", "A"),
|
||
("行为树", "/api/system/behaviortree/{id}", "A"),
|
||
("行为树", "/api/system/behaviortree", "A POST/PUT"),
|
||
("行为树", "/api/system/behaviortree/copy", "A"),
|
||
("行为树", "/api/system/behaviortree/platform/{id}", "A"),
|
||
("行为树", "/api/system/behaviortree/underling/{platformId}", "A"),
|
||
("行为树", "/api/system/behaviortree/commander/{scenarioId}", "B"),
|
||
("行为树", "/api/system/behaviortree/behaviortreeId", "A"),
|
||
("场景", "/api/system/scene/list", "A"),
|
||
("场景", "/api/system/scene/saveSceneConfig", "A"),
|
||
("规则", "/api/system/rule/config/graph/four-blocks", "A"),
|
||
("火力", "/api/system/firerule/start", "B"),
|
||
("火力", "/api/system/firerule/rule", "B"),
|
||
]
|
||
]
|
||
doc.add_paragraph("表2 关键路径补充说明（方自-设计-API-02）")
|
||
_add_table(
|
||
doc,
|
||
["子域", "相对路径", "A/B 备注"],
|
||
[[a[0], a[1], a[2]] for a in detail],
|
||
)
|
||
|
||
_h(doc, "2.9.1 管理端主要 HTTP 端点细目（方自-设计-API-03，按 Controller 归纳）", 2)
|
||
_long_para(
|
||
doc,
|
||
"下列列表用于设计评审时与 Swagger 及源码双核；**规则主表**根路径行标注「未启用」以与 RuleController 块注释状态一致。",
|
||
)
|
||
fine = [
|
||
["POST", "/login", "用户登录，返回 Token 等", "A"],
|
||
["GET", "/getInfo", "当前登录用户/权限/角色", "A"],
|
||
["GET", "/getRouters", "侧栏路由，若启用", "B 典型为管理端"],
|
||
["POST", "/logout", "登出", "A"],
|
||
["GET", "/captchaImage", "数学/字符验证码", "B"],
|
||
["POST", "/register", "若开放注册", "B"],
|
||
["GET", "/system/user/list", "用户列表", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/user/**", "用户 CRUD 等", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/role/**", "角色", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/menu/**", "菜单", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/dept/**", "部门", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/dict/**", "字典", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/config/**", "系统参数", "B"],
|
||
["GET/POST/PUT/DELETE", "/system/notice/**", "通知", "B"],
|
||
["GET/PUT/POST", "/system/user/profile**", "个人中心", "B"],
|
||
["GET/POST/DELETE", "/monitor/operlog**", "操作日志", "B"],
|
||
["GET/POST/DELETE", "/monitor/logininfor**", "登录日志", "B"],
|
||
["GET/DELETE", "/monitor/online**", "在线用户", "B"],
|
||
["GET", "/monitor/server", "服务器信息", "B"],
|
||
["GET/DELETE", "/monitor/cache**", "缓存", "B"],
|
||
["GET/POST/PUT/DELETE", "/monitor/job**", "Quartz 任务", "B"],
|
||
["GET/POST/DELETE", "/monitor/jobLog**", "任务执行日志", "B"],
|
||
["GET/POST", "/common/**", "上传/下载/资源", "B"],
|
||
["GET/POST/PUT/DELETE", "/test/user/**", "TestController 调试", "B"],
|
||
["GET/POST/PUT/DELETE", "/api/system/behaviortree**", "行为树全族", "A（建模器用）"],
|
||
["GET/POST/PUT/DELETE", "/api/system/treenodeinstance**", "节点实例", "A"],
|
||
["GET/POST/PUT/DELETE", "/api/system/nodeconnection**", "连接", "A"],
|
||
["GET/POST/PUT/DELETE", "/api/system/nodeparameter**", "参数", "A"],
|
||
["GET/POST/PUT/DELETE", "/api/system/nodetemplate**", "模板", "A"],
|
||
["GET/POST/PUT/DELETE", "/api/system/templateparameterdef**", "模板参数", "A"],
|
||
["GET", "/api/node/command/all", "Hb 节点命令", "A"],
|
||
["GET/POST", "/api/system/scene**", "场景", "A"],
|
||
["GET/POST/…", "/api/system/rule 根下 list、POST、PUT、DELETE", "RuleController 块注释，未启用", "—"],
|
||
["GET/POST/PUT/DELETE", "/api/system/rule/config**", "规则聚合与图谱", "A 已启用"],
|
||
["GET/POST", "/api/system/firerule/**", "火力/平台/执行", "A+B 视路径"],
|
||
["GET/POST/PUT/DELETE+run", "/api/algo/algorithm**", "算法", "A"],
|
||
["GET/POST/PUT/DELETE", "/tool/gen**", "代码生成", "B"],
|
||
]
|
||
_add_table(doc, ["方法族", "路径/说明", "含义", "类"], fine)
|
||
|
||
doc.add_paragraph("表3 行为树/场景/火力部分路径展开（方自-设计-API-04）")
|
||
fine2 = [
|
||
["GET", "/api/system/behaviortree/list", "分页/条件查询", "A"],
|
||
["GET", "/api/system/behaviortree/{id}", "单条", "A"],
|
||
["POST", "/api/system/behaviortree", "更新（实例）", "A"],
|
||
["PUT", "/api/system/behaviortree", "新增/更新", "A"],
|
||
["DELETE", "/api/system/behaviortree/{ids}", "删除", "A"],
|
||
["POST", "/api/system/behaviortree/copy", "复制", "A"],
|
||
["GET", "/api/system/behaviortree/platform/{id}", "按平台", "A"],
|
||
["GET", "/api/system/behaviortree/underling/{platformId}", "下属平台", "A"],
|
||
["GET", "/api/system/behaviortree/commander/{scenarioId}", "指挥关系", "B"],
|
||
["PUT", "/api/system/behaviortree/behaviortreeId", "更新树 id", "A"],
|
||
["GET", "/api/system/scene/list", "场景列表", "A"],
|
||
["GET", "/api/system/scene/{id}", "场景详情", "A"],
|
||
["POST", "/api/system/scene/saveSceneConfig", "保存/更新", "A"],
|
||
["GET", "/api/system/scene/getAllTree/{id}", "场景下所有树", "A"],
|
||
["GET", "/api/system/scene/getAllRelation/{id}", "平台通信关系", "A"],
|
||
["GET", "/api/system/firerule/platforms", "全量平台+组件", "A"],
|
||
["GET", "/api/system/firerule/platforms/{scenarioId}", "按场景", "A"],
|
||
["GET", "/api/system/firerule/platforms/basic", "基础平台列表", "A"],
|
||
["GET", "/api/system/firerule/component/{platformId}", "按平台组件", "A"],
|
||
["POST", "/api/system/firerule/start", "执行规则匹配", "B"],
|
||
["GET", "/api/system/firerule/weapon", "武器", "B"],
|
||
["GET", "/api/system/firerule/comm", "通信", "B"],
|
||
["POST", "/api/system/firerule/rule", "任务型规则", "B"],
|
||
]
|
||
_add_table(doc, ["方法", "完整路径", "说明", "A/B"], fine2)
|
||
|
||
_h(doc, "2.10 数据与持久化设计要点", 1)
|
||
_long_para(
|
||
doc,
|
||
"库表以 MyBatis XML 与实体为准：行为树与节点相关、场景与通信关系、规则/算法/系统表分离在不同子模块的 mapper 目录。",
|
||
"重要表（摘录）：behaviortree、platform 相关、afsims 场景、rule 与 config、algorithm/algorithm_param、quartz 任务表、"
|
||
"sys_* 组织权限表、gen_table 等。建表与索引策略遵循各自 Mapper 与实体字段。",
|
||
"规则资源 JSON 位于规则子模块 resources/json/，在部署时随 JAR 打包。",
|
||
)
|
||
|
||
_h(doc, "2.11 安全、配置与与建模器联调", 1)
|
||
_long_para(
|
||
doc,
|
||
"认证：无 Token 的登录与验证码、静态资源等按 SecurityConfig 放行；业务接口需已认证。",
|
||
"服务端口：application.yml 中 server.port=1777，servlet.context-path 为 /。",
|
||
"Redis：spring.redis 中 host、port、password 与项目实际一致。",
|
||
"文件上传：solution.profile 等定义上传根路径。",
|
||
"建模器：Vite 开发态 proxy 将 /api、/login、/getInfo 转发到 127.0.0.1:1777，与本文一致；"
|
||
"生产可改为同域 Nginx 反向代理。",
|
||
)
|
||
|
||
# 再补充若干长段落以充实软设（论文式展开）
|
||
for k in range(1, 9):
|
||
_h(doc, f"2.12.{k} 设计说明补充（方自-设计-EXT-0{k}）", 2)
|
||
_long_para(
|
||
doc,
|
||
f"本小节对 2.1—2.8 中模块的接口粒度和错误处理作补充性说明。",
|
||
"异常时统一经 com.solution.framework.web.exception.GlobalExceptionHandler 等全局处理输出 AjaxResult 结构，前端以 code/msg 进行提示；"
|
||
"鉴权失败等由 Security 与入口配置决定；",
|
||
"业务上行为树、场景、规则、算法在事务边界上以各 Service/Mapper 实现为准。",
|
||
)
|
||
|
||
_h(doc, "2.13 典型用例文字说明（与建模器页面）", 1)
|
||
use_cases = [
|
||
(
|
||
"用例 UC-01：建模器用户登录并拉取行为树列表",
|
||
"用户在建模器登录页输入账号口令→POST /login→获得令牌→设计器页 GET /api/system/behaviortree/list 分页查询→"
|
||
"将结果展示为卡片或列表。异常：口令错误、账户锁定、网络超时；前端应提示 code/msg。",
|
||
),
|
||
(
|
||
"用例 UC-02：在场景下编辑通信并保存",
|
||
"用户从设计器带 scenario 进入通信页→GET /api/system/scene/{id} 与 getAllRelation→在画布上编辑关系→"
|
||
"saveSceneConfig 提交 JSON 字符串字段；若需平台详情则 GET /api/system/firerule/platforms/{scenarioId}。",
|
||
),
|
||
(
|
||
"用例 UC-03：配置规则聚合与查看知识图谱",
|
||
"用户打开规则配置管理页→/config/list 分页→/config/{ruleCode} 看详情→/config/graph 与 four-blocks 获取可视化数据→"
|
||
"新增/修改时 POST/PUT /config。权限由 @PreAuthorize 与 system:rule:* 权限字控制。",
|
||
),
|
||
(
|
||
"用例 UC-04：运行算法脚本",
|
||
"用户维护 algorithm 行→POST /run 将 Algorithm 实例序列化 JSON 作为子进程标准输入，读取输出写回展示；"
|
||
"部署时须校验 codePath 指向的 Python/脚本存在。",
|
||
),
|
||
(
|
||
"用例 UC-05：管理员操作定时任务/代码生成（B 类）",
|
||
"通过 /monitor/job* 与 /tool/gen* 在具备权限时维护任务与生成物；不经过建模器菜单，属于运维/研发工具链。",
|
||
),
|
||
]
|
||
for title, body in use_cases:
|
||
_h(doc, title, 2)
|
||
for para in body.split("。"):
|
||
p = para.strip()
|
||
if p:
|
||
doc.add_paragraph(p + "。")
|
||
|
||
_h(doc, "2.14 附：工程目录与可维护性", 1)
|
||
_long_para(
|
||
doc,
|
||
"代码按 Maven 模块分目录：auto-solution-* 与 modeler 前端解耦。后端单测位于各模块 `src/test`；"
|
||
"若需扩展新 REST，应在管理端子系统增 Controller 并视需要暴露 Swagger。",
|
||
"建议：规则主数据接口若与建模器火力规则页强依赖，应取消 RuleController 内块注释并同步权限、菜单与联调。",
|
||
)
|
||
|
||
_h(doc, "2.15 附：环境变量与端口一览", 1)
|
||
_add_table(
|
||
doc,
|
||
["项", "默认/说明", "备注"],
|
||
[
|
||
["HTTP 端口", "1777（application.yml server.port）", "可改"],
|
||
["context-path", "/", "可改"],
|
||
["Redis", "127.0.0.1:6379，密码以配置为准", "缓存/会话"],
|
||
["Modeler 开发端口", "8888（Vite）", "proxy 到 1777"],
|
||
["上传根路径", "solution.profile", "Windows 示例为盘符路径"],
|
||
],
|
||
)
|
||
|
||
doc.add_page_break()
|
||
_h(doc, "3 设计追溯", 1)
|
||
_p(
|
||
doc,
|
||
"本设计说明与《软件需求说明》使用同一批业务表述与方自-需求-xxx/方自-设计-xxx 标识在文字中对应，本版不另附正逆向追踪矩阵。",
|
||
)
|
||
_p(doc, "（完）")
|