bjchy-auth-sdk/README.md

朝阳区认证SDK - 简洁易用的扫码登录和请求工具包

# bjchy-auth-sdk
git add . && git commit -m "你的提交信息" && git push origin master

# 发布补丁版本
npm run release:patch

# 或者使用其他版本类型
npm run release:minor
npm run release:major



🔐 **朝阳区认证SDK** - 简洁、易用的扫码登录和请求工具包

## ✨ 核心功能

- **扫码登录** - 完整的微信扫码登录流程
- **请求工具** - 自动处理token和街道信息的HTTP请求
- **动态街道** - 自动从URL检测街道信息
- **CORS处理** - 自动处理localhost开发环境跨域问题

## 📦 安装

```bash
npm install bjchy-auth-sdk
```

## 🚀 快速开始

### 1. 组件方式使用（推荐）

```vue
<template>
  <div class="login-page">
    <QrCodeLogin 
      street-key="blz"
      title="朝阳区管理系统"
      @login-success="handleLoginSuccess"
      @login-error="handleLoginError"
    />
  </div>
</template>

<script setup>
import { QrCodeLogin } from 'bjchy-auth-sdk'
import { useRouter } from 'vue-router'

const router = useRouter()

const handleLoginSuccess = (userData) => {
  console.log('登录成功:', userData)
  // token已自动保存到localStorage
  router.push('/dashboard')
}

const handleLoginError = (error) => {
  console.error('登录失败:', error)
}
</script>
```

### 2. 使用request工具发送API请求

```javascript
import { request } from 'bjchy-auth-sdk'

// 自动附带token和街道信息的请求
const getUserData = async () => {
  try {
    const response = await request.get('/api/user/info')
    console.log('用户信息:', response)
  } catch (error) {
    console.error('请求失败:', error)
  }
}

// POST请求
const saveData = async (data) => {
  try {
    const response = await request.post('/api/data', data)
    console.log('保存成功:', response)
  } catch (error) {
    console.error('保存失败:', error)
  }
}
```

### 3. 街道自动检测

```javascript
import { detectStreetKey, setCurrentStreet } from 'bjchy-auth-sdk'

// 自动从URL检测街道
const streetKey = detectStreetKey()
console.log('当前街道:', streetKey) // 'blz', 'yyc', 'hjl' 或 null

// 手动设置街道
setCurrentStreet('blz')
```

### 4. Vue插件方式使用

```javascript
// main.js
import { createApp } from 'vue'
import BjchyAuth from 'bjchy-auth-sdk'
import App from './App.vue'

const app = createApp(App)

app.use(BjchyAuth, {
  baseURL: 'https://your-api-domain.com/webapi',
  streetKey: 'blz'
})

app.mount('#app')
```

## 📖 API 文档

### QrCodeLogin 组件

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| streetKey | String | 自动检测 | 街道标识：'blz', 'yyc', 'hjl' |
| title | String | '朝阳区认证系统' | 登录页标题 |
| subtitle | String | '请使用微信扫码登录' | 登录页副标题 |

#### 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| login-success | `{ token, userInfo, ... }` | 登录成功，token已自动保存 |
| login-error | `{ type, error }` | 登录失败 |
| status-change | `{ status }` | 状态变化：'generated', 'scanned', 'expired' |

### request 请求工具

```javascript
import { request, createRequest } from 'bjchy-auth-sdk'

// 使用默认实例
await request.get('/api/path')
await request.post('/api/path', data)
await request.put('/api/path', data)
await request.delete('/api/path')

// 创建自定义实例
const customRequest = createRequest({
  baseURL: 'https://custom-api.com',
  timeout: 15000
})
```

### 街道工具

```javascript
import { detectStreetKey, getStreetConfig, setCurrentStreet } from 'bjchy-auth-sdk'

// 检测街道（从URL、localStorage等）
const streetKey = detectStreetKey()

// 获取街道信息
const streetInfo = getStreetConfig('blz')
// { key: 'blz', name: '八里庄街道' }

// 设置当前街道
setCurrentStreet('blz')
```

## ⚙️ 街道配置

支持的街道：
- `blz` - 八里庄街道
- `yyc` - 亚运村街道  
- `hjl` - 呼家楼街道

街道自动检测顺序：
1. URL参数：`?street=blz`
2. URL路径：`/blz/login`
3. 域名：`blz.example.com`
4. localStorage缓存

## 🛠️ 开发环境

### CORS问题自动处理

在localhost开发环境下，SDK会自动：
- 使用生产API地址避免跨域
- 设置正确的CORS头部
- 禁用credentials避免预检请求

### 本地调试

```bash
# 安装依赖
npm install

# 运行测试
npm test

# 构建
npm run build
```

## 🔧 高级配置

### 自定义请求配置

```javascript
import { createRequest } from 'bjchy-auth-sdk'

const customRequest = createRequest({
  baseURL: 'https://your-api.com/webapi',
  timeout: 10000,
  tokenKey: 'custom_token_key'
})
```

### 监听认证事件

```javascript
// 监听token过期事件
window.addEventListener('bjchy-token-expired', (event) => {
  console.log('Token已过期:', event.detail)
  // 跳转到登录页
  window.location.href = '/login'
})
```

## 📝 更新日志

### v2.0.0

- 🎯 **简化架构** - 移除复杂的状态管理，专注核心功能
- 🔧 **修复CORS** - 自动处理localhost开发环境跨域问题
- ⚡ **动态街道** - 智能检测URL中的街道信息
- 📦 **体积优化** - 减少70%的包体积
- 🛠️ **易用性** - 简化API，开箱即用

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 👥 维护者

- [@wangzhongsheng](https://github.com/wangzhongsheng)

---

**朝阳区认证SDK** - 让登录变得简单 🚀