185 lines
7.7 KiB
Markdown
185 lines
7.7 KiB
Markdown
# 简易 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 后端为主的单体应用：
|
||
|
||
```text
|
||
浏览器
|
||
-> 上传 DOCX
|
||
-> Python Web 服务
|
||
-> DOCX 解析
|
||
-> 技能索引加载
|
||
-> 技能相关性匹配
|
||
-> 内网模型分析
|
||
-> 报告生成
|
||
-> 下载分析报告
|
||
```
|
||
|
||
推荐目录结构：
|
||
|
||
```text
|
||
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. 核心处理流程
|
||
|
||
1. 用户在页面上传 `.docx` 文件。
|
||
2. 后端校验文件类型、大小和文件名，保存到 `uploads/` 临时目录。
|
||
3. 使用 DOCX 解析库抽取正文、标题层级、表格文本、页眉页脚和可识别编号。
|
||
4. 加载 `GJB438C-2021_prd_skills/index.md`，获得技能清单、描述和适用场景。
|
||
5. 根据文档标题、关键词和用户可选文档类型，筛选候选技能。
|
||
6. 读取候选技能的 `SKILL.md`，构造分析提示词。
|
||
7. 调用 `configs/api_config.yaml` 中 `intranet` 的 OpenAI 兼容接口。
|
||
8. 输出结构化分析结果：符合项、不符合项、缺失章节、风险等级、修改建议、引用技能。
|
||
9. 生成可下载报告，优先支持 `.docx`，同时保留 `.md` 便于审计。
|
||
10. 清理过期上传文件和分析结果。
|
||
|
||
## 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. 离线部署方案
|
||
|
||
1. 在联网环境准备依赖：
|
||
- `fastapi`
|
||
- `uvicorn`
|
||
- `python-docx`
|
||
- `pyyaml`
|
||
- `requests`
|
||
- `jinja2`
|
||
- `python-multipart`
|
||
2. 整个项目使用python的库管理器uv，然后使用 `pip download -d wheelhouse -r requirements.txt` 准备离线依赖包。
|
||
3. 将代码、`wheelhouse/`、`GJB438C-2021_prd_skills/`、`configs/` 一并拷贝到内网服务器。
|
||
4. 在内网执行 `pip install --no-index --find-links wheelhouse -r requirements.txt`。
|
||
5. 启动服务：`uvicorn app.main:app --host 0.0.0.0 --port 8000`。
|
||
6. 确认服务器可访问 `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` 检查文档格式。
|