7.7 KiB
7.7 KiB
简易 DOCX 规范分析 Web 应用开发计划
1. 目标与范围
开发一个部署在离线内网环境的简易 Web 应用，用户上传 .docx 文档后，系统读取 GJB438C-2021_prd_skills/ 下的技能规范集合，判断文档是否符合相关规范，并生成可下载的分析报告。应用默认使用 configs/api_config.yaml 中 intranet 配置的内网模型 qwen3-coder。
本计划聚焦最小可用版本：上传 DOCX、抽取文本与章节结构、选择或自动匹配技能、调用内网模型分析、生成报告并下载。
2. 当前仓库基础
GJB438C-2021_prd_skills/：核心规范知识库，目前包含 39 个SKILL.md。GJB438C-2021_prd_skills/index.md：技能索引，包含技能名称、用途和分类导航。configs/api_config.yaml：模型供应商配置，默认default_provider: intranet，内网接口为http://10.30.10.1:8000/v1。test/：可存放人工验证用的 DOCX 样例。AGENTS.md：说明该仓库是文档与技能包工作区，无现有构建系统。
3. 推荐总体架构
建议采用 Python Web 后端为主的单体应用：
浏览器
-> 上传 DOCX
-> Python Web 服务
-> DOCX 解析
-> 技能索引加载
-> 技能相关性匹配
-> 内网模型分析
-> 报告生成
-> 下载分析报告
推荐目录结构：
app/
main.py # Web 入口
config.py # 读取 configs/api_config.yaml
docx_parser.py # DOCX 文本、标题、表格抽取
skill_loader.py # 加载 index.md 与 SKILL.md
analyzer.py # 规则匹配与模型调用
report_generator.py # 生成 Markdown/DOCX 报告
templates/
static/
outputs/ # 临时分析结果，需加入 .gitignore
uploads/ # 临时上传文件，需加入 .gitignore
4. 核心处理流程
- 用户在页面上传
.docx文件。 - 后端校验文件类型、大小和文件名，保存到
uploads/临时目录。 - 使用 DOCX 解析库抽取正文、标题层级、表格文本、页眉页脚和可识别编号。
- 加载
GJB438C-2021_prd_skills/index.md，获得技能清单、描述和适用场景。 - 根据文档标题、关键词和用户可选文档类型，筛选候选技能。
- 读取候选技能的
SKILL.md，构造分析提示词。 - 调用
configs/api_config.yaml中intranet的 OpenAI 兼容接口。 - 输出结构化分析结果：符合项、不符合项、缺失章节、风险等级、修改建议、引用技能。
- 生成可下载报告，优先支持
.docx，同时保留.md便于审计。 - 清理过期上传文件和分析结果。
5. 技能使用策略
技能集不应一次性全部塞入模型上下文。建议分两阶段使用：
- 预筛选阶段：读取
index.md中的 Skill、Description、Use When，按关键词匹配文档类型，例如 SRS、接口设计、测试计划、配置管理、交付准备等。 - 深度分析阶段：只加载命中的 3 到 8 个
SKILL.md，逐项检查文档是否包含技能要求的章节、要素、约束和输出。
如果用户明确选择文档类型，应优先使用对应技能；如果未选择，则自动匹配并在报告中说明匹配依据。
6. 报告内容设计
报告建议包含以下章节：
- 基本信息：文件名、分析时间、使用模型、命中技能。
- 总体结论：通过、部分通过、不通过或需人工复核。
- 技能符合性矩阵：技能名称、检查项、符合状态、证据位置、问题说明。
- 缺失与风险：缺少的章节、不可验证需求、追溯性不足、接口描述不完整等。
- 修改建议：按优先级给出可执行改进项。
- 附录：解析到的文档目录、模型提示摘要、版本信息。
7. Python 技术路线分析
候选技术：
- Web 框架：FastAPI 或 Flask。
- DOCX 解析：
python-docx。 - 配置读取：
PyYAML。 - 模型调用：
requests或 OpenAI 兼容 SDK。 - 报告生成：
python-docx生成 DOCX，或markdown先生成 Markdown。
优点：
- 后端可直接读取本仓库的
SKILL.md和api_config.yaml。 - DOCX 解析和 DOCX 报告生成库成熟。
- 更适合调用内网模型接口，避免浏览器跨域和接口暴露问题。
- 离线部署清晰，可用虚拟环境、wheelhouse 或 PyInstaller 打包。
缺点：
- 需要在内网服务器安装 Python 运行环境和依赖。
- 前端交互能力较弱时，需要额外编写模板或少量静态资源。
8. HTML + CSS + JavaScript 技术路线分析
候选技术：
- 纯前端页面：HTML、CSS、JavaScript。
- DOCX 读取：浏览器端可用 Mammoth.js 提取文本。
- 报告生成：前端生成 Markdown、HTML 或借助 docx.js 生成 DOCX。
优点：
- 部署简单，静态文件可直接由 Nginx 或文件服务器提供。
- 用户界面响应快，适合做上传进度、结果预览、筛选技能等交互。
- 若只做本地规则检查，可减少服务端复杂度。
缺点：
- 纯前端无法安全读取服务器上的
GJB438C-2021_prd_skills/全量文件，除非预先打包为 JSON。 - 调用内网模型会暴露接口地址和凭据，并可能遇到 CORS 限制。
- DOCX 结构、表格、页眉页脚和复杂格式解析能力通常弱于 Python。
- 大文件分析、报告生成和审计留痕不如后端集中处理可靠。
9. 推荐方案
建议采用 Python FastAPI + 简洁 HTML/CSS/JavaScript 前端的混合方案。
FastAPI 负责文件上传、DOCX 解析、技能加载、模型调用和报告生成；前端只负责上传、展示进度、显示结果摘要和下载报告。该方案在离线内网环境中更稳健，也能最大化复用当前仓库中的 Markdown 技能文件和 YAML 配置。
10. 离线部署方案
- 在联网环境准备依赖：
fastapiuvicornpython-docxpyyamlrequestsjinja2python-multipart
- 整个项目使用python的库管理器uv，然后使用
pip download -d wheelhouse -r requirements.txt准备离线依赖包。 - 将代码、
wheelhouse/、GJB438C-2021_prd_skills/、configs/一并拷贝到内网服务器。 - 在内网执行
pip install --no-index --find-links wheelhouse -r requirements.txt。 - 启动服务：
uvicorn app.main:app --host 0.0.0.0 --port 8000。 - 确认服务器可访问
http://10.30.10.1:8000/v1模型接口。
11. 安全与配置要求
- 上传文件和生成报告默认保存在临时目录，定期清理。
- 限制上传类型为
.docx，限制单文件大小。 - 不在前端暴露模型 API 配置。
configs/api_config.yaml中的真实密钥和内网地址不应进入公开仓库。- 报告中应标注“模型分析结果需人工复核”，避免将自动分析当作正式审查结论。
12. 开发里程碑
阶段一：原型
- 搭建 FastAPI 上传页面。
- 实现 DOCX 文本与标题提取。
- 加载技能索引并支持手动选择技能。
- 生成 Markdown 分析报告。
阶段二：可用版本
- 实现自动技能匹配。
- 接入内网
qwen3-coder模型。 - 生成 DOCX 下载报告。
- 增加错误处理、文件大小限制和日志。
阶段三：增强版本
- 增加符合性矩阵和证据定位。
- 支持批量文档分析。
- 增加任务状态页面和历史记录。
- 增加离线安装脚本和部署说明。
13. 验证方式
- 使用
test/下样例 DOCX 进行上传验证。 - 用不同文档类型验证技能匹配准确性。
- 断开公网，仅保留内网模型接口，验证离线可运行。
- 检查生成报告是否包含命中技能、问题列表、证据摘要和修改建议。
- 使用
git diff --check检查文档格式。