# drone-knowledge-base

**Repository Path**: yl19951422/drone-knowledge-base

## Basic Information

- **Project Name**: drone-knowledge-base
- **Description**: 软件部门内部知识管理系统，用于管理无人机型号、设备类型、软件模块及设计文档
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 无人机开发知识库 (Drone Knowledge Base)

软件部门内部知识管理系统，用于管理无人机型号、设备类型、软件模块及设计文档。

## 数据模型

```
┌─────────────────┐       ┌─────────────────────┐
│   DroneModel    │       │   EquipmentType     │
│   (型号)         │       │   (设备类型)         │
│   xc25, xc15    │       │   相机, 飞控, 载荷   │
└────────┬────────┘       └──────────┬──────────┘
         │                           │
         │ ModelEquipment            │
         │ (型号设备关联)             │
         └───────────────────────────┘
                     │
                     ▼
         ┌─────────────────────┐
         │   Document          │
         │   (文档)             │
         │   通过DocumentRelation │
         │   关联到型号或设备类型  │
         └─────────────────────┘

┌──────────────────────┐
│  SoftwareArchitecture │──── 软件架构
│  └─ ArchitectureVersion│──── 版本 (draft/released/voided)
│      └─ ArchitectureLayer│─── 分层 (含依赖DAG、环检测)
│          └─ ArchitectureModule │─ 模块 (含版本、文档关联)
└──────────────────────┘
         │
         ▼ ModelArchitectureReference (型号引用架构版本)
┌──────────────────────┐
│  ModelSoftwareConfig  │──── 型号软件配置 (可冻结)
│  └─ SoftwareModule    │──── 配置中的模块实例
│  └─ ConfigAttachment  │──── 配置附件
└──────────────────────┘

┌──────────────────────┐
│  SoftwareModuleTemplate│─── 软件模块模板 (可复用)
│  └─ TemplateConfigVersion│─ 模板配置版本
└──────────────────────┘
```

**核心实体：**
- **DroneModel**: 无人机型号（如 xc25, xc15）
- **EquipmentType**: 设备类型（如相机、飞控、载荷）
- **ModelEquipment**: 型号与设备类型的关联
- **SoftwareArchitecture / ArchitectureVersion / ArchitectureLayer / ArchitectureModule**: 软件架构分层体系，支持版本管理和层间依赖 DAG
- **SoftwareModuleTemplate**: 可复用的软件模块模板
- **ModelSoftwareConfig**: 型号软件配置，绑定架构版本，支持模块覆盖和冻结
- **Document**: 文档管理，支持版本控制、审核工作流和实体关联（含继承）

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | Vue 3 + TypeScript + Ant Design Vue |
| 后端 | FastAPI + SQLAlchemy (async) + Alembic |
| 数据库 | PostgreSQL 16 |
| 对象存储 | MinIO |
| 文档转换 | LibreOffice (Office转PDF) |
| 部署 | Docker Compose + Nginx |

## 环境部署

### 系统架构

```
┌──────────────────────────────────────────────────────────────────┐
│  客户端浏览器 (内网电脑)                                           │
│  http://192.168.x.x                                              │
└────────────────────────┬─────────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────────┐
│  Nginx (:80)                                                     │
│  ┌──────────┬────────────┬────────────────────────┐              │
│  │  /api/*  │  /minio/*  │  /* (前端静态文件)       │              │
│  └────┬─────┴─────┬──────┴──────────┬─────────────┘              │
│       │           │                 │                             │
│       ▼           ▼                 ▼                             │
│  ┌─────────┐ ┌─────────┐   ┌──────────────┐                     │
│  │ Backend │ │  MinIO  │   │  Frontend    │                     │
│  │ (:8000) │ │(:9000)  │   │  (Vue SPA)   │                     │
│  │ FastAPI │ │对象存储  │   │  dist/       │                     │
│  └────┬────┘ └─────────┘   └──────────────┘                     │
│       │                                                          │
│       ▼                                                          │
│  ┌──────────────┐                                                │
│  │  PostgreSQL  │                                                │
│  │  (:5432)     │                                                │
│  └──────────────┘                                                │
│                                                                  │
│  Docker Compose 编排，所有服务运行在 dronekb-network 桥接网络         │
└──────────────────────────────────────────────────────────────────┘
```

### 前置要求

| 部署方式 | 需要安装 |
|---------|---------|
| 本地开发 | Docker Desktop + Node.js 18+ + Python 3.11+ |
| Docker 部署 | Docker Desktop（含 Docker Compose） |
| 内网离线部署 | Docker Desktop（需提前在联网机器准备安装包） |

---

### 方式一：本地开发环境

**1. 启动基础服务（数据库和MinIO）**

```bash
# 启动 Docker Desktop 后
docker-compose -f docker-compose.dev.yml up -d
```

**2. 启动后端**

> **重要**：必须在 backend 目录下创建并激活虚拟环境，避免使用全局 Python 环境

```powershell
cd backend

# 检查 Python 版本（需要 3.11+）
python --version

# 安装 uv（推荐，比 pip 快很多）
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv .venv

# 激活虚拟环境（Windows PowerShell）
.\.venv\Scripts\activate

# 激活虚拟环境（Windows CMD）
.venv\Scripts\activate.bat

# 激活虚拟环境（Linux/Mac）
source .venv/bin/activate

# 确认使用虚拟环境（应显示 .venv 路径）
where python   # Windows
which python   # Linux/Mac

# 安装依赖
pip install -r requirements.txt

# 运行数据库迁移
alembic upgrade head

# 启动后端服务
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**3. 启动前端**

```powershell
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

**4. 访问系统**
- 前端: http://localhost:3000
- 后端API文档: http://localhost:8000/docs
- MinIO控制台: http://localhost:9001

**5. 安装LibreOffice（可选，用于Office文档预览）**

如需在本地预览Word/Excel/PPT文档，需安装LibreOffice：

```powershell
# Windows: 从官网下载安装
# https://www.libreoffice.org/download/download/

# macOS
brew install --cask libreoffice

# Linux (Debian/Ubuntu)
sudo apt install libreoffice-writer libreoffice-calc libreoffice-impress
```

> 如果不安装LibreOffice，Office文档预览会提示"不支持预览，请下载查看"，其他功能不受影响。

---

### 方式二：Docker Compose 一键部署（有网络环境）

适用于服务器有网络或已手动加载镜像的场景。

```powershell
# 1. 复制环境配置
copy .env.example .env

# 2. 启动所有服务
docker compose up -d

# 3. 查看服务状态
docker compose ps

# 4. 访问系统
# 前端:    http://localhost
# API文档: http://localhost/api/docs
# MinIO:   http://localhost:9001 (minioadmin / minioadmin123)
```

---

### 方式三：内网离线部署（推荐生产环境）

适用于目标服务器完全无法联网的内网环境。分为 **打包** 和 **部署** 两步，分别在联网机器和内网机器上执行。

#### 整体流程

```
联网 Windows 机器                              内网 Windows Server
───────────────                                ───────────────────
1. 运行打包脚本
   package-offline.ps1
         │
         ▼
2. 生成部署包                                   3. 拷贝到内网服务器
   *.zip (约4-5GB)          ──── USB/SCP ────►  4. 解压
                                                5. 修改 .env 密码
                                                6. 运行部署脚本
                                                   deploy-offline.ps1
                                                      │
                                                      ▼
                                                7. 服务启动完成
                                                8. 内网电脑访问
```

#### 步骤一：在联网机器上打包

```powershell
# 进入项目目录
cd drone-knowledge-base

# 方式 A: 完整打包（构建镜像 + 保存 + 打包配置）
.\scripts\package-offline.ps1

# 方式 B: 跳过构建（镜像已存在）
.\scripts\package-offline.ps1 -SkipBuild

# 方式 C: 指定输出目录
.\scripts\package-offline.ps1 -OutputDir D:\deploy-pkg
```

打包完成后会在项目目录下生成：
```
drone-knowledge-base-offline-20260412_143000.zip   (约 4-5 GB)
```

打包产物内部结构：
```
offline-package/
├── images/                        # Docker 镜像 tar 文件
│   ├── manifest.txt               # 镜像清单（文件名|镜像标签）
│   ├── python-3.11-slim.tar       # Python 运行时
│   ├── node-20-alpine.tar         # Node.js 构建环境
│   ├── nginx-1.25-alpine.tar      # Nginx 反向代理
│   ├── postgres-16-alpine.tar     # PostgreSQL 数据库
│   ├── minio-latest.tar           # MinIO 对象存储
│   ├── backend.tar                # 后端应用（含 LibreOffice + 中文字体）
│   └── frontend.tar               # 前端应用（Vue 构建产物）
├── config/                        # 配置文件
│   ├── docker-compose.prod.yml    # 生产环境 Docker 编排
│   ├── .env.production            # 环境变量模板（需修改密码）
│   └── nginx/                     # Nginx 配置
│       ├── nginx.conf
│       └── ssl/                   # SSL 证书目录（可选）
├── scripts/                       # 部署和初始化脚本
│   ├── deploy-offline.ps1         # 一键部署脚本
│   ├── init-db.py                 # 数据库初始化
│   └── init-minio.py              # MinIO 初始化
├── backend/                       # 后端源码（用于调试）
│   ├── app/
│   ├── alembic/
│   ├── requirements.txt
│   └── Dockerfile
└── frontend/                      # 前端构建产物
    └── dist/
```

#### 步骤二：传输到内网服务器

通过以下任一方式将 `.zip` 文件传输到内网 Windows Server：

| 方式 | 说明 |
|------|------|
| U盘 | 直接拷贝，最简单 |
| 内网共享文件夹 | `\\server\share\` |
| SCP/SFTP | 使用 WinSCP 等工具 |

#### 步骤三：准备内网服务器环境

内网服务器需要安装 **Docker Desktop for Windows**。如无法联网，需提前准备：

**1. 下载 Docker Desktop 安装包**（在联网机器上）

下载地址：https://www.docker.com/products/docker-desktop/

选择 `Docker Desktop Installer.exe`（约 500MB）。

**2. 在内网服务器上安装**

```powershell
# 以管理员身份运行 PowerShell
# 双击安装或命令行安装：
Docker Desktop Installer.exe install
```

**3. 启动 Docker Desktop**

安装完成后启动 Docker Desktop，确保左下角显示绿色 "Engine running"。

**4. 验证 Docker 可用**

```powershell
docker version
docker compose version
```

> **注意**：Docker Desktop 依赖 WSL2 或 Hyper-V。Windows Server 需要：
> - Windows Server 2019+ 或 Windows 10/11 Pro+
> - 启用 WSL2：`wsl --install`
> - 或启用 Hyper-V 角色（服务器管理器中添加）

#### 步骤四：修改生产环境配置

解压部署包后，**必须**修改配置文件中的密码和地址：

```powershell
# 解压
Expand-Archive -Path .\drone-knowledge-base-offline-*.zip -DestinationPath .\deploy

cd deploy\offline-package

# 编辑配置文件
notepad config\.env.production
```

**必须修改的配置项**（所有标有 `CHANGE_ME` 的值）：

```ini
# ---- 数据库密码（改为你自己的强密码）----
POSTGRES_PASSWORD=MyStr0ng!Pass2026

# ---- 后端连接数据库（密码与上面一致）----
APP_DATABASE_URL=postgresql+asyncpg://postgres:MyStr0ng!Pass2026@postgres:5432/dronekb

# ---- MinIO 密码 ----
APP_MINIO_SECRET_KEY=MyMin10!Secret2026
MINIO_ROOT_PASSWORD=MyMin10!Secret2026

# ---- JWT 密钥（随机32位以上字符串）----
APP_JWT_SECRET=xK9mP2vN8qR4wT6yB1cF5gH0jL3sA7dE

# ---- CORS（填入服务器实际 IP 或域名）----
# 其他内网电脑通过这个地址访问系统
APP_CORS_ORIGINS=http://192.168.1.100
```

> **服务器 IP 查看方式**：在服务器上运行 `ipconfig`，找到内网 IPv4 地址。

**可选修改的端口**（默认不用改）：

```ini
# 如果 80 端口被占用，可以改为其他端口
NGINX_HTTP_PORT=8080
NGINX_HTTPS_PORT=443
```

#### 步骤五：一键部署

```powershell
# 以管理员身份运行 PowerShell
cd deploy\offline-package

# 全量部署（加载镜像 + 启动 + 初始化）
.\scripts\deploy-offline.ps1 -Force

# 或者分步执行：
.\scripts\deploy-offline.ps1 -LoadOnly          # 第1步: 仅加载镜像
.\scripts\deploy-offline.ps1 -StartOnly          # 第2步: 仅启动服务
.\scripts\deploy-offline.ps1 -InitOnly           # 第3步: 仅初始化数据库
```

部署成功后显示：
```
============================================
  Deployed Successfully!
============================================

  Application:    http://192.168.1.100
  API Docs:       http://192.168.1.100/api/docs
  MinIO Console:  http://192.168.1.100:9001

  Other computers on the network can access:
    http://192.168.1.100

  Default credentials:
    Username: admin
    Password: admin123

  IMPORTANT: Change the default password after first login!
============================================
```

#### 步骤六：内网其他电脑访问

其他内网电脑打开浏览器，输入服务器 IP 地址即可访问：

```
http://192.168.1.100
```

> 如果修改了 `NGINX_HTTP_PORT`，访问地址为 `http://192.168.1.100:端口号`

**访问所需的网络条件**：

| 检查项 | 说明 |
|--------|------|
| 服务器防火墙 | 需开放 80 端口（HTTP）。Windows Server: 控制面板 > Windows Defender 防火墙 > 高级设置 > 入站规则 > 新建规则 > TCP 80 |
| 网络连通 | 客户端与服务器在同一网段，或路由可达 |
| Docker 运行 | Docker Desktop 必须保持运行状态 |

**Windows Server 防火墙放行端口**：

```powershell
# 以管理员身份运行
# 放行 HTTP 80
New-NetFirewallRule -DisplayName "DroneKB HTTP" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow

# 如果需要 HTTPS
New-NetFirewallRule -DisplayName "DroneKB HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow

# 如果需要从外部访问 MinIO 管理控制台（可选）
New-NetFirewallRule -DisplayName "DroneKB MinIO" -Direction Inbound -Protocol TCP -LocalPort 9001 -Action Allow
```

---

### 部署后运维

#### 查看服务状态

```powershell
.\scripts\deploy-offline.ps1 -Status
```

输出示例：
```
Container Status:
-----------------
NAME               STATUS              PORTS
dronekb-nginx      Up 2 minutes        0.0.0.0:80->80/tcp
dronekb-backend    Up 2 minutes        0.0.0.0:8000->8000/tcp
dronekb-frontend   Up 2 minutes        80/tcp
dronekb-postgres   Up 2 minutes        0.0.0.0:5432->5432/tcp
dronekb-minio      Up 2 minutes        0.0.0.0:9000->9000/tcp, 0.0.0.0:9001->9001/tcp

Quick Health Check:
-------------------
[OK]    Backend API: OK (HTTP 200)
[OK]    Frontend:    OK (HTTP 200)
[OK]    MinIO:       OK (HTTP 200)
```

#### 查看日志

```powershell
# 查看所有服务日志
docker compose -f config\docker-compose.prod.yml logs

# 查看某个服务日志
docker compose -f config\docker-compose.prod.yml logs backend
docker compose -f config\docker-compose.prod.yml logs nginx

# 实时跟踪日志
docker compose -f config\docker-compose.prod.yml logs -f backend
```

#### 数据备份

```powershell
.\scripts\deploy-offline.ps1 -Backup
```

备份内容包括：
- PostgreSQL 数据库完整 dump（`database.sql`）
- MinIO 文件存储数据（`minio-data.tar.gz`）

备份文件保存在 `backups\` 目录，文件名格式：`dronekb-backup-20260412_143000.zip`

#### 数据恢复

```powershell
.\scripts\deploy-offline.ps1 -RestoreFile .\backups\dronekb-backup-20260412_143000.zip
```

> 恢复操作会停止后端服务、覆盖数据库和文件存储，完成后自动重启。

#### 停止服务

```powershell
.\scripts\deploy-offline.ps1 -Stop
```

#### 重启服务

```powershell
docker compose -f config\docker-compose.prod.yml restart
```

---

### 生产环境安全检查清单

| 检查项 | 说明 | 状态 |
|--------|------|------|
| 修改 `POSTGRES_PASSWORD` | 数据库密码不能是默认值 | ☐ |
| 修改 `APP_MINIO_SECRET_KEY` | MinIO 密钥不能是默认值 | ☐ |
| 修改 `MINIO_ROOT_PASSWORD` | 与 APP_MINIO_SECRET_KEY 保持一致 | ☐ |
| 修改 `APP_JWT_SECRET` | JWT 密钥至少 32 位随机字符串 | ☐ |
| 设置 `APP_CORS_ORIGINS` | 填入服务器实际 IP 地址 | ☐ |
| 设置 `APP_ENV=production` | 确认生产环境模式 | ☐ |
| 设置 `APP_DEBUG=false` | 关闭调试模式 | ☐ |
| 首次登录后修改 admin 密码 | 系统内修改管理员密码 | ☐ |
| 关闭 5432/9000/9001 对外端口 | 仅开放 80/443 | ☐ |
| 配置 HTTPS（可选） | 将证书放入 `nginx\ssl\` 目录 | ☐ |

---

### 环境变量完整参考

后端支持以下环境变量（前缀 `APP_`），通过 `.env` 文件或 `docker compose` 环境变量传入：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_DATABASE_URL` | `postgresql+asyncpg://postgres:postgres@localhost:5432/dronekb` | 数据库连接字符串 |
| `APP_MINIO_ENDPOINT` | `localhost:9000` | MinIO 端点地址 |
| `APP_MINIO_ACCESS_KEY` | `minioadmin` | MinIO 访问密钥 |
| `APP_MINIO_SECRET_KEY` | `minioadmin123` | MinIO 密钥 |
| `APP_MINIO_BUCKET` | `dronekb-documents` | MinIO 存储桶名称 |
| `APP_MINIO_SECURE` | `false` | 是否使用 HTTPS 连接 MinIO |
| `APP_JWT_SECRET` | 自动生成 | JWT 签名密钥（生产环境必须设置） |
| `APP_JWT_ALGORITHM` | `HS256` | JWT 算法 |
| `APP_JWT_EXPIRE_MINUTES` | `480` | Token 过期时间（分钟），默认 8 小时 |
| `APP_ADMIN_INITIAL_PASSWORD` | 空 | 初始管理员密码（空则自动生成） |
| `APP_CORS_ORIGINS` | `http://localhost,...` | CORS 允许的来源，逗号分隔 |
| `APP_NAME` | `Drone Knowledge Base` | 应用名称 |
| `APP_ENV` | `development` | 环境（development/production） |
| `APP_DEBUG` | `false` | 调试模式 |

Docker Compose 层面额外支持：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `POSTGRES_USER` | `postgres` | PostgreSQL 用户名 |
| `POSTGRES_PASSWORD` | `postgres` | PostgreSQL 密码 |
| `POSTGRES_DB` | `dronekb` | PostgreSQL 数据库名 |
| `MINIO_ROOT_USER` | `minioadmin` | MinIO 管理员用户名 |
| `MINIO_ROOT_PASSWORD` | `minioadmin123` | MinIO 管理员密码 |
| `NGINX_HTTP_PORT` | `80` | Nginx HTTP 端口 |
| `NGINX_HTTPS_PORT` | `443` | Nginx HTTPS 端口 |
| `BACKEND_PORT` | `8000` | 后端 API 端口 |
| `POSTGRES_PORT` | `5432` | PostgreSQL 端口 |
| `MINIO_API_PORT` | `9000` | MinIO API 端口 |
| `MINIO_CONSOLE_PORT` | `9001` | MinIO 控制台端口 |

---

### 常见问题

**Q: Docker Desktop 无法启动**

确保已启用 WSL2：
```powershell
wsl --install
wsl --update
```

**Q: 端口 80 被占用**

修改 `.env` 中的 `NGINX_HTTP_PORT=8080`，然后通过 `http://IP:8080` 访问。

**Q: 内网电脑无法访问**

1. 确认服务器 Docker 正在运行：`docker ps`
2. 确认服务器防火墙已放行 80 端口
3. 确认客户端和服务器网络连通：`ping 服务器IP`
4. 确认 `.env` 中 `APP_CORS_ORIGINS` 包含服务器实际 IP

**Q: 镜像加载失败**

确保 Docker Desktop 正在运行，且有足够磁盘空间（至少 10GB 可用空间）。

**Q: 数据库连接失败**

检查 `.env` 中 `APP_DATABASE_URL` 的密码是否与 `POSTGRES_PASSWORD` 一致。

## 默认账号

| 服务 | 用户名 | 密码 |
|------|--------|------|
| 系统登录 | admin | admin123 |
| PostgreSQL | postgres | postgres |
| MinIO | minioadmin | minioadmin123 |

## 项目结构

```
drone-knowledge-base/
├── docker-compose.yml          # Docker 编排配置
├── docker-compose.dev.yml      # 开发环境配置
├── backend/                    # FastAPI 后端
│   ├── main.py                # 启动入口（uvicorn app.main:app）
│   ├── app/
│   │   ├── main.py            # 应用入口、CORS、路由注册、生命周期
│   │   ├── config.py          # pydantic-settings 配置管理
│   │   ├── database.py        # 异步数据库引擎 & 会话工厂
│   │   ├── models/            # SQLAlchemy ORM 模型
│   │   │   ├── user.py             # 用户 & 审计日志
│   │   │   ├── drone_model.py      # 无人机型号
│   │   │   ├── equipment.py        # 设备类型、型号设备、配置版本
│   │   │   ├── software.py         # 软件模块模板、型号软件配置、配置附件
│   │   │   ├── architecture.py     # 软件架构、版本、分层、模块、依赖、引用
│   │   │   ├── document.py         # 文档、版本、关联
│   │   │   └── mixins.py           # SoftDeleteMixin (软删除混入)
│   │   ├── schemas/           # Pydantic 请求/响应模型
│   │   │   ├── user.py             # 用户注册/登录/更新
│   │   │   ├── drone_model.py      # 型号相关
│   │   │   ├── equipment.py        # 设备类型相关
│   │   │   ├── software.py         # 软件模块相关
│   │   │   ├── architecture.py     # 架构/分层/模块相关
│   │   │   ├── document.py         # 文档/版本/审核相关
│   │   │   └── excel.py            # Excel 导入导出响应
│   │   ├── routers/           # API 路由（按业务域划分）
│   │   │   ├── auth.py              # 认证：登录/注册/用户管理
│   │   │   ├── drone_models.py      # 型号管理：CRUD、Excel导入导出
│   │   │   ├── equipment_types.py   # 设备类型管理：CRUD、Excel导入导出
│   │   │   ├── model_equipments.py  # 型号设备关联：增删改、批量操作
│   │   │   ├── software_modules.py  # 软件模块模板：CRUD、配置版本
│   │   │   ├── model_software_configs.py # 型号软件配置：CRUD、模块管理、附件、冻结
│   │   │   ├── software_architectures.py  # 软件架构：版本管理、Excel导入导出
│   │   │   ├── architecture_layers.py     # 架构分层：CRUD、依赖管理、排序
│   │   │   ├── architecture_modules.py    # 架构模块：CRUD、版本、文档关联
│   │   │   ├── model_architecture_refs.py # 型号架构引用
│   │   │   ├── documents.py          # 文档管理：上传、版本、审核、关联
│   │   │   └── stats.py              # 统计：概览、活动日志、拓扑图
│   │   ├── services/          # 业务逻辑层（Excel处理）
│   │   │   ├── excel_engine.py            # Excel读写引擎
│   │   │   ├── excel_schemas.py           # Excel数据结构定义
│   │   │   ├── architecture_excel.py      # 架构导入导出
│   │   │   ├── equipment_excel.py         # 设备导入导出
│   │   │   └── model_excel.py             # 型号导入导出
│   │   └── utils/             # 工具函数
│   │       ├── auth.py             # JWT令牌、密码哈希、角色校验
│   │       ├── storage.py          # MinIO对象存储客户端
│   │       ├── document_converter.py # LibreOffice文档转PDF
│   │       └── audit.py            # 审计日志创建
│   ├── alembic/               # 数据库迁移
│   │   └── versions/          # 迁移版本文件
│   ├── scripts/               # 运维脚本
│   ├── tests/                 # 测试
│   └── requirements.txt       # Python 依赖
├── frontend/                   # Vue 3 前端
│   └── src/
│       ├── views/             # 页面组件
│       │   ├── ModelList.vue        # 型号列表
│       │   ├── ModelDetail.vue      # 型号详情（设备+软件配置）
│       │   ├── EquipmentTypeList.vue
│       │   ├── DocumentCenter.vue
│       │   └── ...
│       ├── components/        # 通用组件
│       ├── api/               # API 请求封装
│       ├── stores/            # Pinia 状态管理
│       └── router/            # 路由配置
└── nginx/                      # Nginx 配置
```

## API 概览

所有接口挂载在 `/api` 前缀下，采用 JWT Bearer Token 认证，基于角色的四级权限控制（admin / engineer / reviewer / viewer）。

### 认证与用户 `/api/auth`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| POST | `/login` | 公开 | 用户登录，返回 JWT |
| POST | `/register` | 公开 | 自注册（viewer 角色） |
| POST | `/logout` | 已登录 | 登出（写审计日志） |
| GET | `/me` | 已登录 | 获取当前用户信息 |
| GET | `/` | admin | 用户列表（分页） |
| POST | `/` | admin | 创建用户 |
| PUT | `/{user_id}` | 自己或admin | 更新用户信息 |
| GET | `/reviewers` | 已登录 | 获取所有审核人 |

### 无人机型号 `/api/models`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET | `/` | 已登录 | 型号列表（分页、筛选） |
| POST | `/` | engineer+ | 创建型号 |
| GET | `/export` | 已登录 | 导出 Excel |
| POST | `/import` | engineer+ | 导入 Excel |
| GET | `/template` | 已登录 | 下载导入模板 |
| GET | `/{model_id}` | 已登录 | 型号详情 |
| PUT | `/{model_id}` | engineer+ | 更新型号 |
| DELETE | `/{model_id}` | engineer+ | 软删除 |
| POST | `/{model_id}/restore` | admin | 恢复已删除 |

### 设备类型 `/api/equipment-types`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET | `/` | 已登录 | 设备类型列表 |
| POST | `/` | engineer+ | 创建设备类型 |
| GET/POST | `/export` `/import` | 已登录/engineer+ | Excel导入导出 |
| GET | `/{id}/used-models` | 已登录 | 查看关联型号 |

### 型号设备关联 `/api/models/{model_id}/equipments`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET | `/` | 已登录 | 型号下的设备列表 |
| POST | `/` | engineer+ | 添加设备 |
| PUT | `/{eid}` | engineer+ | 更新设备 |
| DELETE | `/{eid}` | engineer+ | 软删除 |
| POST | `/batch` | engineer+ | 批量添加 |

### 软件模块模板 `/api/software-module-templates`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET/POST | `/` | 已登录/engineer+ | 列表 / 创建 |
| GET/PUT/DELETE | `/{id}` | 已登录/engineer+ | 详情 / 更新 / 删除 |
| GET | `/{id}/used-models` | 已登录 | 关联型号 |
| GET/POST | `/{id}/config-versions` | 已登录/engineer+ | 配置版本管理 |
| GET/POST/DELETE | `/{id}/documents` | 已登录/engineer+ | 文档关联 |

### 软件架构 `/api/software-architectures`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET/POST | `/` | 已登录/engineer+ | 列表 / 创建（自动创建 v1.0 草稿） |
| GET/POST | `/export` `/import` | 已登录/engineer+ | Excel导入导出 |
| GET | `/{id}` | 已登录 | 架构详情（含分层、模块、版本） |
| GET/POST | `/{id}/versions` | 已登录/engineer+ | 版本列表 / 创建新版本（复制分层） |
| POST | `/versions/{vid}/release` | engineer+ | 发布版本（冻结） |
| POST | `/versions/{vid}/void` | admin | 作废版本 |

### 架构分层 `/api/software-architectures/{arch_id}/layers`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET/POST | `/` | 已登录/engineer+ | 分层列表 / 创建 |
| PUT/DELETE | `/../layers/{lid}` | engineer+ | 更新 / 删除 |
| PUT | `/reorder` | engineer+ | 重排分层顺序 |
| GET/PUT | `/../layers/{lid}/dependencies` | 已登录/engineer+ | 依赖管理（环检测） |

### 架构模块 `/api/architecture-modules`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET/POST | `/../layers/{lid}/modules` | 已登录/engineer+ | 模块列表 / 创建 |
| GET/PUT/DELETE | `/{mid}` | 已登录/engineer+ | 详情 / 更新 / 软删除 |
| GET/POST | `/{mid}/versions` | 已登录/engineer+ | 模块版本管理 |
| GET/POST/DELETE | `/{mid}/documents` | 已登录/engineer+ | 文档关联 |

### 型号软件配置 `/api/models/{model_id}/software-configs`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET/POST | `/` | 已登录/engineer+ | 配置列表 / 创建 |
| GET/PUT/DELETE | `/{cid}` | 已登录/engineer+ | 详情 / 更新 / 软删除 |
| POST | `/{cid}/set-current` | engineer+ | 设为当前配置 |
| GET/POST | `/{cid}/modules` | 已登录/engineer+ | 模块列表 / 添加模块 |
| GET | `/{cid}/modules-grouped` | 已登录 | 按分层分组查看模块 |
| GET/POST/DELETE | `/{cid}/attachments` | 已登录/engineer+ | 附件上传 / 下载 / 删除 |
| GET | `/{cid}/attachments/{aid}/convert` | 已登录 | 附件转 PDF |
| POST | `/{cid}/freeze` | admin | 冻结配置 |
| POST | `/{cid}/unfreeze` | admin | 解冻配置 |

### 文档管理 `/api/documents`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET | `/` | 已登录 | 文档列表（筛选、分页） |
| POST | `/` | engineer+ | 创建文档元数据 |
| POST | `/upload` | engineer+ | 上传文件（multipart） |
| GET/PUT/DELETE | `/{id}` | 已登录/engineer+ | 详情 / 更新 / 软删除 |
| DELETE | `/{id}/permanent` | admin | 永久删除（含 MinIO 清理） |
| GET/POST | `/{id}/versions` | 已登录/engineer+ | 版本列表 / 创建版本 |
| GET | `/versions/{vid}/download` | 已登录 | 下载文件 |
| GET | `/versions/{vid}/preview` | 已登录 | 预签名预览 URL |
| GET | `/versions/{vid}/convert` | 已登录 | 转 PDF |
| POST | `/versions/{vid}/review` | reviewer | 审核通过/驳回 |
| GET/POST/DELETE | `/{id}/relations` | 已登录/engineer+ | 实体关联管理 |
| GET | `/pending-reviews` | viewer+ | 待审核列表 |

### 系统统计 `/api/stats`

| 方法 | 端点 | 权限 | 说明 |
|------|------|------|------|
| GET | `/overview` | 已登录 | 仪表盘概览统计 |
| GET | `/recent-activities` | 已登录 | 最近活动日志 |
| GET | `/topology` | 已登录 | G6 拓扑图数据（型号-设备关系） |
| GET | `/audit-logs` | admin | 审计日志（分页） |

## 文档预览

系统支持多种文档格式的在线预览：

| 文件类型 | 格式 | 预览方式 |
|---------|------|---------|
| PDF | `.pdf` | 浏览器直接预览 |
| 图片 | `.jpg` `.png` `.gif` | 图片组件预览 |
| Markdown | `.md` | 渲染预览（支持表格、Mermaid流程图） |
| 文本 | `.txt` `.json` `.xml` | 代码高亮显示 |
| Word | `.doc` `.docx` | 转换为PDF预览 |
| Excel | `.xls` `.xlsx` | 转换为PDF预览 |
| PPT | `.ppt` `.pptx` | 转换为PDF预览 |

### Office文档转换

Office文档预览依赖LibreOffice，Docker镜像已包含：

- `libreoffice-writer` - Word文档
- `libreoffice-calc` - Excel表格
- `libreoffice-impress` - PPT演示
- `fonts-wqy-zenhei` / `fonts-wqy-microhei` - 中文字体

## 环境变量

后端支持以下环境变量（前缀 `APP_`）：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_DATABASE_URL` | `postgresql+asyncpg://postgres:postgres@localhost:5432/dronekb` | 数据库连接 |
| `APP_MINIO_ENDPOINT` | `localhost:9000` | MinIO 端点 |
| `APP_MINIO_ACCESS_KEY` | `minioadmin` | MinIO 访问密钥 |
| `APP_MINIO_SECRET_KEY` | `minioadmin123` | MinIO 密钥 |
| `APP_JWT_SECRET` | `your-super-secret-key...` | JWT 密钥 |

## 多机协作规范

在两台电脑间开发时，务必遵循以下原则，避免数据库与代码不同步：

| 做 | 不做 |
|---|---|
| `alembic upgrade head` 同步数据库 | 手动加列/建表 |
| 迁移文件随代码一起提交到 Git | 只提交 Model 不提交迁移文件 |
| 启动前确认 `alembic current` | 假设数据库和代码天然一致 |

**换电脑后的标准流程：**

```bash
git pull
alembic upgrade head
```

## 版本升级与数据库迁移

### 全新部署

全新部署不需要手动迁移。后端启动时 `app/main.py` 的 lifespan 会通过 `Base.metadata.create_all()` 自动创建所有表（包含最新的 `layout_row`/`layout_col` 字段）。直接运行部署脚本即可。

### 从旧版本升级

如果目标服务器已有数据（如从依赖版本升级到行列布局版本），需要手动执行数据库迁移：

**本地开发环境：**

```bash
cd backend
alembic upgrade head
```

**Docker 部署环境：**

```powershell
# 在部署目录下执行
docker compose -f config\docker-compose.prod.yml exec backend alembic upgrade head

# 迁移完成后重启后端
docker compose -f config\docker-compose.prod.yml restart backend
```

迁移会自动完成：

- 给 `architecture_layers` 表新增 `layout_row`、`layout_col` 两个字段
- 将现有数据的 `layout_row` 设为 `order_index`（保持原有排列），`layout_col` 设为 `0`
- 删除 `layer_dependencies` 表（依赖关系功能已移除）

> **注意：** 迁移不可逆，`layer_dependencies` 表会被删除。建议先备份数据库。

## 许可证

MIT