XNSim/XNSimPortal/README.md

# XNSim 门户网站

一个基于 Node.js 的现代化门户系统，集成了 C++ 动态库认证功能，专为 XNSim 项目设计。

## 📋 目录

- [功能特点](#功能特点)
- [系统架构](#系统架构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [权限管理](#权限管理)
- [技术栈](#技术栈)
- [常见问题](#常见问题)

## ✨ 功能特点

### 🔐 认证系统

- 美观的响应式登录界面
- 跨平台动态库支持（Windows/Linux）
- 基于权限级别的用户角色管理
- 记住登录状态功能

### 🔧 接口配置管理

- 完整的 CRUD 操作支持
- Excel 文件批量导入功能
- 多维度筛选（构型、ATA 章节、结构体名等）
- 分页显示和批量操作
- 数据验证和错误处理

### 📊 系统监控

- 实时数据监控
- 系统日志管理
- 用户行为追踪
- 性能指标展示

## 🏗️ 系统架构

```
XNSimPortal/
├── assets/          # 静态资源文件
├── components/      # 前端组件
├── routes/          # API 路由
├── utils/           # 工具函数
├── server.js        # 主服务器文件
└── main.html        # 主页面
```

## 📋 环境要求

### 必需软件

- **Node.js**: 14.x 或更高版本
- **SQLite**: 5.7 或更高版本
- **操作系统**: Windows 10+ / Linux / macOS

### 环境变量

必须设置 `XNCore` 环境变量，指向 XNSim 安装根目录：

```bash
# Linux/macOS
export XNCore=/path/to/xncore/directory

# Windows (CMD)
set XNCore=C:\path\to\xncore\directory

# Windows (PowerShell)
$env:XNCore = "C:\path\to\xncore\directory"
```

### 动态库文件

确保在 `$XNCore/lib` 目录下存在相应动态库：

| 操作系统 | 文件名        | 说明               |
| -------- | ------------- | ------------------ |
| Windows  | `login.dll`   | Windows 动态链接库 |
| Linux    | `liblogin.so` | Linux 共享对象库   |

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd XNSimPortal
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置数据库

创建 `.env` 文件并配置数据库连接：

```env
DB_HOST=localhost
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=xnsim_db
DB_PORT=3306
```

### 4. 启动服务

```bash
npm start
```

### 5. 访问应用

打开浏览器访问：http://localhost:3000

## 📚 API 文档

### 认证 API

#### 用户登录

```http
POST /api/login
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "remember": boolean
}
```

**响应示例：**

```json
{
  "success": true,
  "message": "登录成功",
  "permissionLevel": 3,
  "role": "管理员"
}
```

### 接口配置 API

#### 获取接口列表

```http
GET /api/interface/list?page=1&limit=10&filter=...
```

#### 添加接口

```http
POST /api/interface/add
Content-Type: application/json

{
  "configuration": "string",
  "ataChapter": "string",
  "structName": "string",
  "interfaceName": "string",
  "dataType": "string",
  "arraySize": "string",
  "description": "string"
}
```

#### 更新接口

```http
PUT /api/interface/update
Content-Type: application/json

{
  "currentData": {...},
  "originalData": {...}
}
```

#### 删除接口

```http
DELETE /api/interface/delete?id=123
```

#### 导入接口配置

```http
POST /api/interface/import
Content-Type: application/json

{
  "data": [...]
}
```

#### 下载导入模板

```http
GET /api/interface/template
```

## 🔐 权限管理

系统采用五级权限体系：

| 级别 | 角色       | 权限描述         |
| ---- | ---------- | ---------------- |
| 0    | 访客       | 仅可查看公开信息 |
| 1    | 普通用户   | 基础功能访问权限 |
| 2    | 高级用户   | 扩展功能访问权限 |
| 3    | 管理员     | 系统管理权限     |
| 4    | 超级管理员 | 完全系统控制权限 |

## 🛠️ 技术栈

### 前端

- **HTML5** - 语义化标记
- **CSS3** - 样式和动画
- **JavaScript ES6+** - 交互逻辑
- **Web Components** - 组件化开发

### 后端

- **Node.js** - 运行时环境
- **Express.js** - Web 框架
- **MySQL** - 关系型数据库

### 核心库

- **ffi-napi** - C++ 动态库调用
- **xlsx** - Excel 文件处理
- **mysql2** - 数据库驱动

## ❓ 常见问题

### Q: 动态库加载失败怎么办？

A: 请检查：

1. `XNCore` 环境变量是否正确设置
2. 动态库文件是否存在于 `$XNCore/lib` 目录
3. 动态库是否包含 `Login_validateUser` 导出函数

### Q: 数据库连接失败？

A: 请确认：

1. MySQL 服务是否正在运行
2. `.env` 文件中的数据库配置是否正确
3. 数据库用户是否有足够权限

### Q: 接口配置导入失败？

A: 请检查：

1. Excel 文件格式是否符合模板要求
2. 必填字段是否完整
3. 数据格式是否符合验证规则

## 📝 开发规范

### 代码风格

- 使用 ES6+ 语法
- 遵循 JavaScript 标准规范
- 添加适当的注释和文档

### 数据验证

- 接口名称必须符合 C++ 命名规范
- 数组大小必须大于 1
- 必填字段不能为空

## 🔄 更新日志

### v0.31.0.250619_alpha (当前版本)

- ✅ 基础登录认证功能
- ✅ 接口配置管理
- ✅ Excel 导入导出
- ✅ 权限管理系统

### 计划功能

- 🔄 IDL 文件导入支持
- 🔄 实时数据监控
- 🔄 用户行为分析
- 🔄 API 文档自动生成

## 📞 支持

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件至技术支持
- 查看项目 Wiki

---

**注意**: 本系统需要正确配置 C++ 动态库才能正常工作。确保动态库包含 `Login_validateUser` 函数，该函数接受用户名和密码参数，返回权限级别（负值表示失败）。