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, MapLocationPicker } 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. 地图定位组件

```vue
<template>
  <div class="location-picker">
    <!-- 基础使用 - 默认北京坐标 -->
    <MapLocationPicker 
      @location-selected="handleLocationSelected"
    />
    
    <!-- 指定初始坐标 -->
    <MapLocationPicker 
      :lat="39.9377"
      :lng="116.4647" 
      @location-selected="handleLocationSelected"
    />
  </div>
</template>

<script setup>
import { MapLocationPicker } from 'bjchy-auth-sdk'

const handleLocationSelected = (location) => {
  console.log('选择的位置:', location)
  // location: { lat: Number, lng: Number, address?: String }
  
  // 处理位置数据
  saveLocation(location)
}

const saveLocation = (location) => {
  // 保存位置到后端或本地存储
  localStorage.setItem('selectedLocation', JSON.stringify(location))
}
</script>
```

### 3. 使用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)
  }
}
```

### 4. 街道自动检测

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

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

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

### 5. 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',
  roule:'user',  //权限要求
})

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' |

### MapLocationPicker 组件

高德地图位置选择组件，提供直观的地图界面进行位置选择。

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| lat | Number | 39.921489 | 初始纬度坐标（北京默认） |
| lng | Number | 116.486409 | 初始经度坐标（北京默认） |

#### 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| location-selected | `{ lat, lng, address? }` | 位置选择完成，包含坐标和地址信息 |

#### 功能特性

- **🗺️ 地图交互**: 支持拖拽地图进行位置选择
- **🔍 地点搜索**: 集成高德地点搜索，支持关键词查找
- **📍 实时定位**: 显示中心点位置标记和地址信息
- **📱 响应式设计**: 适配桌面端和移动端
- **🎨 现代UI**: 美观的弹窗界面和流畅动画效果

#### 使用示例

```vue
<!-- 基础使用 -->
<MapLocationPicker @location-selected="onLocationSelected" />

<!-- 指定初始位置 -->
<MapLocationPicker 
  :lat="39.9377" 
  :lng="116.4647"
  @location-selected="onLocationSelected" 
/>

<!-- 处理选择结果 -->
<script setup>
const onLocationSelected = (location) => {
  console.log(`位置: ${location.lat}, ${location.lng}`)
  console.log(`地址: ${location.address}`)
}
</script>
```

#### 技术要点

- **高德地图API**: 使用高德地图JavaScript API v2.0
- **插件集成**: 自动加载地理编码和地点搜索插件
- **错误处理**: 完善的网络异常和API失败处理
- **性能优化**: 懒加载地图API，组件销毁时自动清理资源

### 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.1.0

- 🗺️ **新增地图组件** - 高德地图位置选择组件 `MapLocationPicker`
- 🔍 **智能搜索** - 集成高德地点搜索API，支持全国地点查找
- 📍 **实时定位** - 拖拽地图实时更新位置和地址信息
- 📱 **响应式设计** - 完美适配桌面端和移动端设备
- 🎨 **现代UI** - 流畅动画和美观的用户界面

### v2.0.0

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

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 👥 维护者

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

---

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