# 快速开始指南

本指南将帮助您在5分钟内快速集成Medical License组件到您的Spring Boot医疗软件系统中。

## 📋 前置条件

- Java 8 或更高版本
- Spring Boot 2.0 或更高版本
- Maven 或 Gradle 构建工具

## 🚀 快速集成

### 步骤1: 添加依赖

在您的 `pom.xml` 中添加依赖：

```xml
<dependency>
    <groupId>com.bskj.license</groupId>
    <artifactId>byjc-spring-boot-starter-license</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 步骤2: 生成密钥对

```bash
# 下载并运行密钥生成工具
java -cp byjc-spring-boot-starter-license-1.0.0.jar com.bskj.framework.license.generator.KeyGenerator private.key public.key
```

这将生成两个文件：
- `private.key` - 私钥（用于签名license，请安全保存）
- `public.key` - 公钥（用于验证license，可随应用分发）

### 步骤3: 生成License文件

```bash
# 生成license文件
java -cp byjc-spring-boot-starter-license-1.0.0.jar com.bskj.framework.license.generator.LicenseGenerator private.key license.json "您的医院名称"
```

### 步骤4: 配置应用

在 `application.yml` 中添加配置：

```yaml
bskj:
  license:
    enabled: true
    file-path: "license.json"
    public-key-path: "public.key"
    default-strategy: "notification_only"  # 推荐从宽松策略开始
```

### 步骤5: 使用注解控制权限

```java
@RestController
public class PatientController {
    
    @LicenseRequired(modules = {"patient_management"})
    @GetMapping("/patients")
    public List<Patient> getPatients() {
        return patientService.getAllPatients();
    }
}
```

### 步骤6: 启动应用

```bash
java -jar your-bskj-app.jar
```

🎉 **恭喜！** 您的应用现在已经集成了License授权功能！

## 🔧 常用配置

### 基础配置

```yaml
bskj:
  license:
    enabled: true                          # 启用license检查
    file-path: "license.json"              # license文件路径
    public-key-path: "public.key"          # 公钥文件路径
    default-strategy: "notification_only"  # 授权策略
    check-interval-seconds: 3600           # 检查间隔（1小时）
    default-warning-days: 30               # 预警天数
```

### 通知配置

```yaml
bskj:
  license:
    notification:
      log-enabled: true                    # 启用日志通知
      email-enabled: false                # 禁用邮件通知（可选）
      jmx-enabled: false                   # 禁用JMX通知（可选）
```

## 📝 常用注解

### @LicenseRequired 注解参数

```java
@LicenseRequired(
    modules = {"billing", "reporting"},     // 需要的模块权限
    checkUserLimit = true,                   // 检查用户数限制
    allowExpired = false,                    // 是否允许过期时执行
    strict = false,                          // 严格模式
    message = "需要计费和报表模块授权"        // 自定义错误消息
)
```

### 常用场景

```java
// 基础权限检查
@LicenseRequired(modules = {"patient_management"})

// 检查用户数限制
@LicenseRequired(checkUserLimit = true)

// 严格模式（任何license问题都阻止执行）
@LicenseRequired(strict = true)

// 允许过期时执行（紧急功能）
@LicenseRequired(modules = {"emergency"}, allowExpired = true)
```

## 🎯 授权策略说明

### 1. NOTIFICATION_ONLY（推荐开始使用）
- ✅ 系统正常运行
- ✅ 仅通过日志/通知提醒
- ✅ 不影响业务功能
- 🎯 适合：对业务连续性要求极高的场景

### 2. PREVENT_RESTART
- ✅ 当前服务继续运行
- ❌ 阻止应用重新启动
- 🎯 适合：平衡业务连续性和授权控制

### 3. GRACEFUL_SHUTDOWN
- ⏰ 提供宽限期
- ❌ 宽限期后停止服务
- ❌ 阻止重新启动
- 🎯 适合：给客户充足续费时间

## 🛠️ 编程式使用

```java
@Service
public class BusinessService {
    
    @Autowired
    private LicenseService licenseService;
    
    public void performOperation() {
        // 检查license状态
        if (!licenseService.isLicenseValid()) {
            throw new BusinessException("License无效");
        }
        
        // 检查模块权限
        if (!licenseService.isModulePermitted("advanced_features")) {
            throw new BusinessException("高级功能未授权");
        }
        
        // 检查用户数限制
        if (!licenseService.isUserCountWithinLimit(getCurrentUserCount())) {
            throw new BusinessException("用户数超过限制");
        }
        
        // 执行业务逻辑
        doBusinessLogic();
    }
}
```

## 📊 监控License状态

### REST API方式

```java
@RestController
public class LicenseController {
    
    @Autowired
    private LicenseService licenseService;
    
    @GetMapping("/api/license/status")
    public Map<String, Object> getLicenseStatus() {
        return Map.of(
            "valid", licenseService.isLicenseValid(),
            "status", licenseService.getLicenseStatus(),
            "remainingDays", licenseService.getRemainingDays(),
            "warning", licenseService.getLicenseWarningMessage()
        );
    }
}
```

### 事件监听方式

```java
@Component
public class LicenseEventListener {
    
    @EventListener
    public void handleStatusChange(LicenseStatusChangeEvent event) {
        logger.info("License状态变化: {} -> {}", 
            event.getPreviousStatus(), event.getCurrentStatus());
    }
}
```

## 🔍 故障排除

### 常见问题

**Q: 应用启动时提示"License文件不存在"**
```yaml
# 检查配置文件中的路径是否正确
bskj:
  license:
    file-path: "license.json"  # 确保文件存在
```

**Q: 提示"签名验证失败"**
```bash
# 确保使用正确的公钥文件
# 检查license文件是否被篡改
```

**Q: 注解不生效**
```java
// 确保启用了AOP
@EnableAspectJAutoProxy
@SpringBootApplication
public class Application {
    // ...
}
```

### 调试模式

```yaml
logging:
  level:
    com.bskj.license: DEBUG  # 启用详细日志
```

## 📈 生产环境建议

### 安全建议
- 🔐 私钥文件安全保存，不要包含在应用中
- 🔐 使用HTTPS传输license文件
- 🔐 定期更换密钥对
- 🔐 监控license文件访问日志

### 部署建议
- 📁 将license和公钥文件放在应用外部目录
- 📁 使用绝对路径配置文件位置
- 📁 设置适当的文件权限

### 监控建议
- 📊 启用邮件通知给管理员
- 📊 监控license状态变化
- 📊 设置合适的检查间隔
- 📊 建立license续费提醒流程

## 🎓 进阶使用

查看完整文档：
- [README.md](README.md) - 完整功能说明
- [example/](example/) - 完整示例代码
- [application-license-example.yml](src/main/resources/application-license-example.yml) - 详细配置示例

## 💬 技术支持

如有问题，请查看：
1. 📖 [完整文档](README.md)
2. 💻 [示例代码](example/)
3. 🐛 [故障排除指南](README.md#故障排除)

---

🎉 **恭喜您完成了快速集成！** 现在您的医疗软件系统已经具备了专业的License授权功能。