load project
This commit is contained in:
164
README.md
Normal file
164
README.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Document Template Editor
|
||||
|
||||
FastAPI + React application for managing Jinja2-annotated `.docx` document templates.
|
||||
|
||||
## Features
|
||||
|
||||
- **Authentication** with JWT (register/login)
|
||||
- **User roles**: `user` and `admin` with admin user management panel
|
||||
- **Initial admin**: seeded from `.env` on startup
|
||||
- **Template upload**: load a `.docx` file with Jinja2 placeholders
|
||||
- **Auto-detected form fields**: variables become text, textarea, number, date, table cell, or repeating table row fields
|
||||
- **Style preservation**: font, alignment, table cell styles captured from the original document
|
||||
- **Document preview**: render filled template as HTML preview
|
||||
- **Export**: download as `.docx` or `.pdf`
|
||||
- **Reusable templates**: fill the same template multiple times
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
backend/ # FastAPI API
|
||||
frontend/ # React + Vite UI
|
||||
samples/ # Sample .docx templates
|
||||
```
|
||||
|
||||
## Quick Start (Docker)
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
| Service | URL |
|
||||
|----------|-----|
|
||||
| Frontend | http://localhost:5173 |
|
||||
| Backend | http://localhost:8000 |
|
||||
| API docs | http://localhost:8000/docs |
|
||||
|
||||
Default admin: `admin` / `admin123` (configure in `.env`).
|
||||
|
||||
Stop: `docker compose down` · Remove data: `docker compose down -v`
|
||||
|
||||
## Quick Start (Local)
|
||||
|
||||
Requires PostgreSQL running locally (or use Docker only for the database):
|
||||
|
||||
```bash
|
||||
docker compose up db -d
|
||||
```
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env
|
||||
uvicorn app.main:app --reload --port 8000
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open http://localhost:5173
|
||||
|
||||
### Create Sample Template
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
python ../samples/create_sample_template.py
|
||||
```
|
||||
|
||||
## Jinja2 Syntax in .docx
|
||||
|
||||
Use standard Jinja2 in your Word document:
|
||||
|
||||
| Pattern | Purpose |
|
||||
|---------|---------|
|
||||
| `{{ client_name }}` | Simple text variable |
|
||||
| `{{ description }}` | Auto-detected as textarea if name contains "description" |
|
||||
| `{%tr for item in items %}` | Repeating table row (docxtpl syntax) |
|
||||
| `{{ item.product }}` | Field inside table row loop |
|
||||
|
||||
### Example Table Row
|
||||
|
||||
In a Word table row, write:
|
||||
|
||||
```
|
||||
{%tr for item in items %}
|
||||
{{ item.name }} | {{ item.qty }} | {{ item.price }}
|
||||
{%tr endfor %}
|
||||
```
|
||||
|
||||
The parser detects `items` as a `table_row` field and `item.name`, `item.qty`, `item.price` as child `table_cell` fields with preserved table styles.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/api/auth/register` | Register user |
|
||||
| POST | `/api/auth/login` | Login (OAuth2 form) |
|
||||
| GET | `/api/auth/me` | Current user |
|
||||
| GET | `/api/users` | List users (admin) |
|
||||
| POST | `/api/users` | Create user (admin) |
|
||||
| PATCH | `/api/users/{id}` | Update user (admin) |
|
||||
| DELETE | `/api/users/{id}` | Delete user (admin) |
|
||||
| GET | `/api/templates` | List templates |
|
||||
| POST | `/api/templates` | Upload template (.docx) |
|
||||
| GET | `/api/templates/{id}` | Get template with variables |
|
||||
| POST | `/api/documents` | Create filled document |
|
||||
| POST | `/api/documents/preview` | Preview without saving |
|
||||
| GET | `/api/documents/{id}/export/docx` | Export DOCX |
|
||||
| GET | `/api/documents/{id}/export/pdf` | Export PDF |
|
||||
|
||||
## PDF Export
|
||||
|
||||
PDF export uses LibreOffice headless if available:
|
||||
|
||||
```bash
|
||||
# ALT Linux / Fedora
|
||||
sudo apt install libreoffice # or your distro equivalent
|
||||
```
|
||||
|
||||
Without LibreOffice, install `weasyprint` as fallback:
|
||||
|
||||
```bash
|
||||
pip install weasyprint
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create `backend/.env`:
|
||||
|
||||
```env
|
||||
SECRET_KEY=your-secret-key-here
|
||||
DATABASE_URL=postgresql+psycopg2://doceditor:doceditor@localhost:5432/doceditor
|
||||
ADMIN_EMAIL=admin@example.com
|
||||
ADMIN_USERNAME=admin
|
||||
ADMIN_PASSWORD=change-me
|
||||
FRONTEND_URL=http://localhost:5173
|
||||
CORS_ORIGINS=http://localhost:5173,http://localhost:3000
|
||||
```
|
||||
|
||||
The admin user is created automatically on startup if it does not exist.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Login** — use admin credentials from `.env`, or register as a regular user
|
||||
2. **Upload Template** — select `.docx` with Jinja2 variables
|
||||
3. **Fill Form** — dynamic form generated from detected variables
|
||||
4. **Preview** — see rendered document with your data
|
||||
5. **Save & Export** — document saved; export as DOCX or PDF
|
||||
6. **Reuse** — use the same template again from Templates list
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Backend**: FastAPI, SQLAlchemy, docxtpl, python-docx, JWT auth
|
||||
- **Frontend**: React 18, Vite, TypeScript, React Router
|
||||
Reference in New Issue
Block a user