216 lines
13 KiB
Python
216 lines
13 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""
|
||
【已废弃】曾用 python-docx 清空正文再写入，会破坏与 xxx 模板一致的版式与目录域。
|
||
|
||
请改用：python build_spec_documents.py（基于 OOXML 仅改 w:t，保留块级结构）。
|
||
本文件保留仅为历史参考，不再被 build_spec_documents 引用。
|
||
"""
|
||
|
||
from docx import Document
|
||
from docx.enum.text import WD_ALIGN_PARAGRAPH
|
||
from docx.oxml.ns import qn
|
||
from docx.oxml import OxmlElement
|
||
|
||
|
||
def _set_cell_shade(cell, fill="D9D9D9"):
|
||
"""表头灰底（可选）"""
|
||
tc = cell._tc
|
||
tcPr = tc.get_or_add_tcPr()
|
||
shd = OxmlElement("w:shd")
|
||
shd.set(qn("w:fill"), fill)
|
||
tcPr.append(shd)
|
||
|
||
|
||
def _add_table(doc, headers, rows):
|
||
t = doc.add_table(rows=1 + len(rows), cols=len(headers))
|
||
t.style = "Table Grid"
|
||
for j, h in enumerate(headers):
|
||
t.rows[0].cells[j].text = h
|
||
_set_cell_shade(t.rows[0].cells[j])
|
||
for i, row in enumerate(rows):
|
||
for j, val in enumerate(row):
|
||
t.rows[i + 1].cells[j].text = str(val)
|
||
doc.add_paragraph("")
|
||
|
||
|
||
def clear_body(doc):
|
||
body = doc._body._body
|
||
for child in list(body):
|
||
if "sectPr" in child.tag:
|
||
continue
|
||
body.remove(child)
|
||
|
||
|
||
def build_srs_document(doc):
|
||
"""向已清空正文的 Document 中写入软件需求（方案自动化生成）。"""
|
||
t = doc.add_paragraph("方案自动化生成系统")
|
||
t.alignment = WD_ALIGN_PARAGRAPH.CENTER
|
||
try:
|
||
t.runs[0].font.size = t.runs[0].font.size
|
||
except Exception:
|
||
pass
|
||
|
||
doc.add_paragraph("软件需求说明").alignment = WD_ALIGN_PARAGRAPH.CENTER
|
||
doc.add_paragraph("")
|
||
|
||
doc.add_heading("1 方案自动化生成系统软件需求", level=1)
|
||
doc.add_heading("1.1 方案自动化生成系统CSCI能力需求", level=2)
|
||
|
||
intro = (
|
||
"方案自动化生成系统（软件版本 3.9.1，Maven 工程名 auto-solution）由管理端服务子系统、"
|
||
"核心框架子模块、通用基础子模块、系统管理子模块、行为树业务子模块、仿真场景子模块、"
|
||
"规则与火力业务子模块、算法脚本子模块、定时任务子模块、代码生成子模块等共同组成；"
|
||
"其中业务数据访问基于 MyBatis，服务入口为 Spring Boot 应用，默认 HTTP 服务端口 1777（以 application.yml 为准）。\n"
|
||
"系统能力分为两类：A 类为「建模器（modeler 目录）已调用的 HTTP 接口」所支撑的功能；"
|
||
"B 类为「管理端/扩展或运维向接口，当前在建模器中未作为页面功能接入」所支撑的能力，仍由同一后端提供。"
|
||
"本需求说明中凡涉及具体 URL 的，均与 com.solution.web.controller 及 modeler 下实际请求一致。"
|
||
)
|
||
doc.add_paragraph(intro)
|
||
|
||
doc.add_paragraph("系统逻辑范围示意如下（与软设中体系结构一致）：")
|
||
doc.add_paragraph("图1 方案自动化生成系统软件组成及能力范围（A/B 类划分）", style="Caption")
|
||
|
||
cap = (
|
||
"（1）行为树与节点建模：提供行为树、节点实例、节点连接、节点参数、节点模板、模板参数定义等维护与查询，"
|
||
"支撑建模器行为树设计页；对应 A 类接口 /api/system/behaviortree、/api/system/treenodeinstance 等。\n"
|
||
"（2）仿真场景与平台通信：提供仿真场景（Afsim 场景）维护、场景下行为树列表、平台间通信关系、"
|
||
"场景下带组件的平台信息查询；对应 A 类接口 /api/system/scene、/api/system/firerule/platforms 等。\n"
|
||
"（3）规则与火力：提供火力类规则主数据及规则配置（含图谱、四块图、字典与参数元数据）；"
|
||
"对应 A 类 /api/system/rule 及 /api/system/rule/config 等。\n"
|
||
"（4）算法脚本：提供算法登记、运行外部 Python 进程（具体解释器路径以系统实现为准）；"
|
||
"对应 A 类 /api/algo/algorithm。\n"
|
||
"（5）身份与系统管理：提供登录、会话、菜单路由与完整后台用户/角色/部门/岗位/字典/通知/参数/监控等；"
|
||
"其中登录与 /getInfo 为 modeling 所依赖，其余管理项多为 B 类。"
|
||
)
|
||
doc.add_paragraph(cap)
|
||
|
||
doc.add_paragraph("方案自动化生成系统软件 CSCI 能力如表1 归纳。")
|
||
doc.add_paragraph("表1 方案自动化生成系统软件CSCI 能力表", style="Caption")
|
||
|
||
_add_table(
|
||
doc,
|
||
["子系统/模块（中文名）", "主要能力", "A/B 类", "说明"],
|
||
[
|
||
["管理端服务子系统", "统一发布 REST 接口、Swagger 文档、全局异常与权限控制", "A/B", "依赖核心框架、聚合各子模块"],
|
||
["核心框架子模块", "Spring Security、JWT、Redis、MyBatis、数据源、切面日志等", "B", "为全部接口提供横切能力"],
|
||
["系统管理子模块", "组织与用户、角色菜单、日志与在线用户等", "A（登录/会话）+B", "建模器主要使用登录、取用户信息"],
|
||
["行为树业务子模块", "行为树、节点、连接、参数、命令字典等", "A", "与 designer 等页面深度对接"],
|
||
["仿真场景子模块", "场景 CRUD、场景-树、场景-通信关系", "A", "与 communication 场景页对接"],
|
||
["规则与火力业务子模块", "Drools/规则配置、火力规则、平台/组件元数据", "A+B", "A 为规则与配置；B 为规则执行/武器等未接建模器接口"],
|
||
["算法脚本子模块", "算法配置、脚本路径、执行 Python", "A", "algorithm 管理页"],
|
||
["定时任务子模块", "Quartz 任务、任务日志", "B", "接口位于 /monitor/job、/monitor/jobLog"],
|
||
["代码生成子模块", "库表元数据、Velocity 代码生成", "B", "接口 /tool/gen"],
|
||
],
|
||
)
|
||
|
||
# 1.1.1
|
||
doc.add_heading("1.1.1 身份、会话与基础访问（方自-需求-0101）", level=3)
|
||
doc.add_paragraph("功能描述")
|
||
doc.add_paragraph(
|
||
"为建模器提供用户登录、会话与权限所需的基础能力：POST /login 提交账密；"
|
||
"GET /getInfo 在携带令牌时返回用户、角色、权限等；POST /logout 登出（与 Spring Security 实现一致）。"
|
||
)
|
||
doc.add_paragraph("执行逻辑")
|
||
doc.add_paragraph("（1）功能输入\n用户名/密码、令牌（请求头中携带）。")
|
||
doc.add_paragraph("（2）功能输出\n令牌、用户基本信息、角色权限集合、路由/菜单类数据由后端服务返回。")
|
||
doc.add_paragraph("（3）主要步骤\n用户在前端输入凭证→后端认证→建立会话/签发令牌→后续 /api 与 /getInfo 携带令牌访问。")
|
||
_add_table(doc, ["序号", "数据项", "类型", "约束"], [["1", "用户登录表单", "JSON", "A 类"]])
|
||
|
||
# 1.1.2
|
||
doc.add_heading("1.1.2 行为树与节点全量数据访问（方自-需求-0102）", level=3)
|
||
doc.add_paragraph("功能描述")
|
||
doc.add_paragraph(
|
||
"按树标识分页或条件查询行为树；按平台查询树；查询下属平台列表；新增、更新、删除、复制行为树；"
|
||
"查询节点实例、节点连接、节点参数、节点模板、模板参数定义。对应 GET/POST/PUT/DELETE 与 /api/system/behaviortree、"
|
||
"/api/system/treenodeinstance、/api/system/nodeconnection、/api/system/nodeparameter、/api/system/nodetemplate、"
|
||
"/api/system/templateparameterdef 等路径（以 Controller 映射为准，建模器以 designer/api 调用）。"
|
||
)
|
||
doc.add_paragraph("数据需求：行为树主键、平台标识、树名称、根实例信息、边表顺序、参数字段等，均来自各业务表，字段名与实体类/Mapper 一致；建模器以分页参数 pageNum、pageSize 拉取列表与明细。")
|
||
_add_table(doc, ["序号", "关键数据", "类型", "说明"], [
|
||
["1", "树主键 id", "Long", "A"],
|
||
["2", "树 platformId", "Number", "与场景、平台选择联动"],
|
||
])
|
||
|
||
# 1.1.3
|
||
doc.add_heading("1.1.3 仿真场景与平台通信关系（方自-需求-0103）", level=3)
|
||
doc.add_paragraph("功能描述")
|
||
doc.add_paragraph(
|
||
"提供场景列表与详情、保存场景配置、查询某场景下全部行为树、某场景下平台通信关系、"
|
||
"为指定场景 id 拉取带组件的平台信息（GET /api/system/firerule/platforms/{scenarioId}），"
|
||
"并支持在保存场景时写入通信图 JSON 等（以 SceneService、Scene 实体与前端字段为准）。"
|
||
)
|
||
doc.add_paragraph(
|
||
"重要说明：当前 modeler 中“删除”操作实现为 DELETE 调用 /api/system/behaviortree/{id}，与按场景删场景语义在字面上可能不一致，"
|
||
"本需求以当前代码与软设注记为准，由实施时统一修正或保留。"
|
||
)
|
||
_add_table(doc, ["序号", "路径", "HTTP 方法", "A/B"], [
|
||
["1", "/api/system/scene/list", "GET", "A"],
|
||
["2", "/api/system/scene/{id}", "GET", "A"],
|
||
["3", "/api/system/scene/saveSceneConfig", "POST", "A"],
|
||
["4", "/api/system/scene/getAllTree/{id}", "GET", "A"],
|
||
["5", "/api/system/scene/getAllRelation/{id}", "GET", "A"],
|
||
])
|
||
|
||
# 1.1.4
|
||
doc.add_heading("1.1.4 规则、火力与规则配置（方自-需求-0104）", level=3)
|
||
doc.add_paragraph("功能描述")
|
||
doc.add_paragraph(
|
||
"规则聚合（规则配置）能力：分页列表、按 ruleCode 查询、知识图谱、四块图、字典、参数元数据、增删改规则聚合等。"
|
||
"对应 **当前已启用** 的后端路径为 /api/system/rule/config 及其子路径（见 RuleController 未注释部分）。"
|
||
)
|
||
doc.add_paragraph(
|
||
"重要说明：火力规则「主表」CRUD 映射（如 GET /api/system/rule/list、POST/PUT /api/system/rule、DELETE /api/system/rule/{ids}）"
|
||
"在 RuleController 源码中处于块注释内，**当前版本未作为有效接口发布**。建模器 rule/api 若仍请求上述路径，需以取消注释后的代码或分支为准；"
|
||
"本需求对「规则配置」类接口按已启用代码描述。"
|
||
)
|
||
doc.add_paragraph(
|
||
"B 类：POST /api/system/firerule/start、GET /api/system/firerule/weapon、GET /api/system/firerule/comm、POST /api/system/firerule/rule、"
|
||
"以及平台列表等由 FireRuleController 提供；其中建模器已调用部分 platforms 路径，其余为扩展。"
|
||
)
|
||
|
||
# 1.1.5
|
||
doc.add_heading("1.1.5 算法与扩展运维（方自-需求-0105）", level=3)
|
||
doc.add_paragraph("功能描述")
|
||
doc.add_paragraph(
|
||
"A 类：/api/algo/algorithm 的列表、导出、单条、增删改及 /run 运行脚本。"
|
||
"B 类：系统内用户/角色/菜单/部门/岗位/字典/参数/通知、在线、登录/操作日志、服务与缓存监控、"
|
||
"定时任务与任务日志、代码生成、文件上传/下载、开发用 Test 接口、验证码等。"
|
||
)
|
||
|
||
doc.add_heading("1.2 非功能需求（与实现一致）", level=2)
|
||
doc.add_paragraph("安全性")
|
||
doc.add_paragraph(
|
||
"采用 Spring Security 与 JWT 过滤器；敏感操作可结合 @PreAuthorize 与权限字；"
|
||
"密码错误次数与锁定时长由 application.yml 中 user.password 控制；"
|
||
"XSS/重复提交等可依赖 common 与 framework 中已有过滤器/切面（以实际启用类为准）。"
|
||
)
|
||
doc.add_paragraph("性能与可扩展性")
|
||
doc.add_paragraph(
|
||
"服务使用内嵌 Tomcat，线程与连接数可在 application.yml 的 server.tomcat 中调优；"
|
||
"数据库连接池为 Druid，详细见 application-druid.yml 与 druid 监控；"
|
||
"业务列表接口使用 PageHelper 分页，前端传 pageNum、pageSize。"
|
||
)
|
||
doc.add_paragraph("可维护性与运行环境")
|
||
doc.add_paragraph(
|
||
"运行需 JDK 8+（工程编译配置以根 pom 为准）、MySQL 与 Redis 可连；"
|
||
"建模器为 Vite+Vue 独立工程，与后端分开发布；开发态通过代理对接后端 1777 端口。",
|
||
)
|
||
doc.add_paragraph("日志与审计")
|
||
doc.add_paragraph(
|
||
"可启用操作日志、登录日志等（对应 /monitor/operlog、/monitor/logininfor），为 B 类能力；"
|
||
"与若依系实现一致。",
|
||
)
|
||
|
||
doc.add_heading("2 合格性规定", level=1)
|
||
doc.add_paragraph(
|
||
"以本系统源代码与可运行环境为准：A 类需求以建模器联调能完整走通对应接口为合格；"
|
||
"B 类需求以 Swagger/接口测试可访问、服务启动无错误、与数据库和 Redis 配置一致为合格；"
|
||
"安全上须满足本系统所采用的 Spring Security、JWT 与配置项的约束。"
|
||
)
|
||
|
||
doc.add_heading("3 需求追溯", level=1)
|
||
doc.add_paragraph(
|
||
"本版本不展开《正向/逆向需求追溯表》细化填写；在工程上会采用需求标识（方自-需求-xxxx）与软设中设计标识一一在文字中对应说明。"
|
||
)
|
||
doc.add_page_break()
|