# @vlian/framework

Secra Framework - 一个现代化的低代码前端应用框架

## 简介

Secra Framework 是一个低门槛、高可扩展、面向团队的前端应用启动框架，让开发者一行配置即可快速启动完整基础设施，同时保持长期可演进与插件生态自由。

## 特性

- 🚀 **开箱即用**：一行配置即可启动完整基础设施
- 🔌 **插件化架构**：支持中间件和插件系统，灵活扩展
- 🌍 **国际化支持**：基于 i18next 的多语言支持
- 🎨 **主题系统**：支持浅色/深色/自动主题切换
- 🔄 **状态管理**：统一的状态管理抽象，支持多种适配器
- 🛣️ **路由系统**：配置驱动的路由系统，支持权限控制
- 📡 **请求库**：企业级请求库，支持多种 HTTP 适配器
- 🔒 **安全防护**：XSS 防护、配置验证、输入清理等安全功能
- 📊 **性能监控**：Web Vitals 收集和性能指标监控
- 🐛 **错误处理**：完整的错误类型体系和错误边界

## 安装

```bash
# 使用 pnpm
pnpm add @vlian/framework

# 使用 npm
npm install @vlian/framework

# 使用 yarn
yarn add @vlian/framework
```

## 快速开始

### 基本使用

```typescript
import { startApp } from '@vlian/framework';
import App from './App';

// 启动应用
await startApp({
  app: <App />,
});
```

### 完整配置示例

```typescript
import { startApp, LogLevel } from '@vlian/framework';
import App from './App';

await startApp({
  app: <App />,
  loggerLevel: LogLevel.DEBUG,
  theme: {
    mode: 'dark',
    primaryColor: '#1890ff',
  },
  locale: {
    'zh-CN': {
      common: {
        confirm: '确认',
        cancel: '取消',
      },
    },
    'en-US': {
      common: {
        confirm: 'Confirm',
        cancel: 'Cancel',
      },
    },
  },
  router: {
    enabled: true,
    mode: 'browser',
    routes: [
      {
        path: '/',
        component: './pages/Home',
        meta: { title: '首页' },
      },
    ],
  },
});
```

## 按需导入

框架支持按需导入（Tree Shaking），可以显著减少打包体积。你可以使用子路径导入来只导入需要的模块：

```typescript
// 只导入核心启动功能
import { startApp } from '@vlian/framework/core';

// 只导入工具函数
import { logger, LogLevel } from '@vlian/framework/utils';

// 只导入状态管理
import { StateManager } from '@vlian/framework/state';

// 只导入请求库
import { createRequestClient } from '@vlian/framework/request';

// 只导入国际化
import { setupI18n, $t } from '@vlian/framework/library';
```

### 可用的子路径

- `@vlian/framework/core` - 核心模块（启动、上下文、路由等）
- `@vlian/framework/utils` - 工具模块（日志、验证、安全等）
- `@vlian/framework/state` - 状态管理模块
- `@vlian/framework/library` - 基础库模块（国际化、存储等）
- `@vlian/framework/request` - 请求库模块
- `@vlian/framework/components` - 组件模块（当前为空）

### 打包体积优化

使用按需导入可以减少 30-50% 的打包体积，具体取决于你使用的功能。详细说明请查看 [按需导入使用指南](./docs/general/按需导入使用指南.md)。

## 核心模块

### Core 模块

框架的核心模块，提供启动、上下文管理、初始化、错误边界等功能。

### Utils 模块

工具模块，提供日志、错误处理、验证、安全、监控等功能。

### Library 模块

基础库模块，提供国际化、存储等功能。

### State 模块

状态管理模块，提供统一的状态管理抽象，支持多种适配器。

### Request 模块

请求库模块，提供企业级请求能力，支持多种 HTTP 适配器和插件系统。

## 文档

详细文档请查看 [docs/README.md](./docs/README.md)

## 依赖要求

- React: ^18.0.0 || ^19.0.0
- React DOM: ^18.0.0 || ^19.0.0
- Ant Design: ^5.0.0
- React Router DOM: ^6.0.0 || ^7.0.0

## 许可证

Apache-2.0

## 相关链接

- [文档](./docs/README.md)
- [变更日志](./CHANGELOG.md)
