Local official-document review, formatting repair, preview, and compliant .docx export in an Electron desktop workspace.

The application combines an Electron 39 + React 19 + TypeScript interface with a Python 3.12+ FastAPI backend. It imports Word-family documents, converts them into a structured DocumentModel, applies YAML-backed review and repair rules, previews A4 output, and exports a new Word document. Chinese and English application interfaces are included, and project data stays on the local device by default.

• Import .docx, .doc, and .wps documents and select the intended official-document type.
• Review typography, paragraph spacing, margins, headings, tables, page fields, and other rule-backed formatting details.
• Apply selected repairs through the document modifier instead of editing the source file in place.
• Use official, custom, user, or uploaded .docx/.dotx templates as formatting sources.
• Preview pages in an A4-oriented workspace and export the reviewed result as .docx.
• Optionally request AI-assisted analysis. Offline builds expose local Ollama only; online-mode packages can use explicitly configured provider endpoints.
• Use the Word VBA bridge for format checking, repair, and template actions while the local backend is running.
• Switch the application UI between Chinese and English; the preference is stored locally.

Automated checks help find and repair formatting issues, but they do not replace human review, organizational policy, or an authoritative interpretation of an official-document standard.

Electron / React UI
        |
        | local HTTP
        v
FastAPI on 127.0.0.1:8765
        |
        v
parser -> DocumentModel -> RuleEngine / Modifier -> generator -> .docx
              |                    |
              |                    +-- rules/official/*.yaml
              +-- templates and uploaded formatting bases

Rule sources are merged with official < custom < user precedence. Writable runtime data belongs under APP_DATA_DIR; the versioned official rule and template directories are not runtime storage.

• Python 3.12 or newer.
• Node.js 20 or newer and npm.
• Windows for 启动应用.bat and Windows NSIS/MSI packaging.
• LibreOffice only when conversion of legacy .doc or .wps files is needed. It is not a main application package dependency.
• A locally installed Ollama service for optional AI analysis in offline mode.
• Microsoft Word 2010 or newer, including Microsoft 365, only for the optional VBA plugin.

The repository does not include third-party TTF, OTF, or TTC font binaries. Document styles can retain required font family names, but users must obtain and install fonts from properly licensed sources.

Clone the repository and start the backend in the first terminal:

git clone https://github.com/NextWeb4/official-document-ai-assistant
cd official-document-ai-assistant
cd backend
python -m pip install -r requirements.txt
python main.py

Start the Electron development application in a second terminal:

cd official-document-ai-assistant\frontend
npm ci
npm run electron:dev

Windows users can also run 启动应用.bat from the repository root. The backend binds to 127.0.0.1 and uses port 8765 by default; the Electron/Vite development path uses the local origins allowed by the backend configuration.

1. Open Process, import a supported Word-family document, and select its document type.
2. Open Review to inspect grouped rule findings and choose the changes to apply.
3. Optionally run AI analysis after configuring an allowed provider for the current package mode.
4. Select an official template, define a custom rule/template, or import a .docx/.dotx formatting base.
5. Inspect paragraphs, tables, fonts, margins, headers, footers, and page fields in the preview.
6. Export a new .docx and review the generated file in Word before distribution.

Uploaded templates are formatting bases: source document content and table data remain the content source, while approved template formatting is applied during generation. The uploaded original is not intended to be overwritten.

Official YAML rules and templates cover the document types tracked under rules/official/ and templates/official/. Runtime rule management distinguishes official, custom, and user sources, and official files remain read-only from the application.

The optional Word integration communicates only with the local service at http://127.0.0.1:8765. Installation requires importing the supplied VBA modules and Ribbon XML into a trusted Word template. See the Word plugin guide for files, endpoints, installation steps, and macro-security considerations.

• The backend listens on loopback rather than a LAN-facing address.
• Application data, uploaded templates, databases, logs, and the device-level encryption key belong under the runtime application-data directory, not in source control.
• Offline mode accepts local Ollama and loopback base URLs only. Online-mode network access occurs only through endpoints configured for that mode.
• Legacy .doc/.wps conversion can invoke a user-installed local LibreOffice executable.
• The source and release workflows reject bundled third-party font files; no font download interface is part of the application.
• Never commit API keys, tokens, cookies, .env files, private keys, runtime databases, build output, or release assets.
• README status badges request images from img.shields.io when the GitHub page is viewed; this does not add application runtime traffic or a package dependency.
• Dependency security keeps react-router-dom at 7.18.1, which fixes the older client-routing advisories. GHSA-qwww-vcr4-c8h2 affects React Router server/RSC action handling; the CI exception is limited to this Electron HashRouter application and fails if server/RSC APIs appear. npm overrides fix brace-expansion at 5.0.8, beyond GHSA-mh99-v99m-4gvg's affected <=5.0.7 range, and PostCSS at 8.5.23, beyond GHSA-r28c-9q8g-f849's affected <=8.5.17 range. These MIT-licensed controls add no runtime request; remove them only after raw audit review, lint, both type checks, the frontend build, and packaging verification pass with an upstream-safe graph.

Review generated documents before relying on them. Input files, custom rules, templates, fonts, Office macro policy, provider configuration, and local software versions can all affect results.

Run backend, document, rule, and regression tests from the repository root:

python -m pytest tests/ -v --tb=short
python -m pytest tests/rules/ -v

Run the frontend checks from frontend/:

npm audit --audit-level=high
npm run lint
npx tsc --noEmit
npx tsc -p tsconfig.electron.json --noEmit
npm run build
node --test scripts/verify-debian-validation.test.mjs

The GitHub CI workflow runs the Python suite plus the npm audit, ESLint, both TypeScript checks, and the frontend build on Windows. There is no separately configured backend lint or format command, and no React component unit-test command was found in the audited repository.

Prepare the standalone backend resources or build the frontend directly:

python build_backend.py
cd frontend
npm run build
npm run package:win
npm run verify:packages

package:win creates offline and online Windows NSIS .exe and MSI packages. The release workflow also creates portable ZIP archives and SHA256SUMS.txt, verifies package metadata, and publishes assets only when the release tag matches the version in frontend/package.json.

Debian packaging is a separate, architecture-aware path:

cd frontend
npm run package:debian:docker:sh
npm run verify:packages -- --skip-windows --require-debian --debian-modes=offline,online --debian-arch=x64,arm64

Current Debian workflows target x64 and arm64 with Debian 10 compatibility and native-architecture runtime verification. ARMv7 remains blocked until compatible native wheels and real GUI validation are available. Windows cannot cross-compile the PyInstaller backend for Linux/ARM without the documented Docker, WSL, or portable packaging path.

• Formatting rules and templates are only as complete as the tracked YAML definitions and test coverage.
• Legacy .doc/.wps conversion depends on an external LibreOffice installation and may vary by platform or document.
• Required fonts are not distributed, so preview and exported layout can differ on machines without matching fonts.
• AI analysis availability depends on the selected package mode, provider configuration, model service, and network state.
• The Word plugin depends on a running local backend and the user's Microsoft Office macro/trust settings.
• Package structure checks do not replace opening the Electron GUI and generated documents on the target operating system and CPU architecture.
• The audited project contains Chinese and English application resources; Japanese in this repository is documentation, not a claim of a Japanese application UI.

• Contributing guide
• Engineering constraints
• Changelog
• Release notes
• Word plugin guide

Keep changes inside the existing module boundaries, add focused regression tests for behavior changes, and run the checks that match the affected backend, frontend, document, rule, packaging, or Office integration path.

The tracked LICENSE file contains the MIT License and preserves copyright attribution for Jose AI and HaoXiang Huang. NOTICE records the original-source and maintainer attribution. Third-party dependencies and bundled materials remain subject to their own notices and license terms.

Maintainer: HaoXiang Huang
Contact: Rays688888@Gmail.com
Repository: https://github.com/NextWeb4/official-document-ai-assistant
Releases: https://github.com/NextWeb4/official-document-ai-assistant/releases