# react-Tour-guide

**Repository Path**: xiazhui_k/react-tour-guide

## Basic Information

- **Project Name**: react-Tour-guide
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-28
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 山猫导游 - BellaTravel

<img src="android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png" alt="山猫导游" width="120" height="120">

**一个基于 React Native 的智能旅游导览应用**

[![React Native](https://img.shields.io/badge/React%20Native-0.81.4-blue.svg)](https://reactnative.dev/)
[![Node](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS-lightgrey.svg)](https://github.com/yourusername/BellaTravel)

集成了地图导航、景点推荐、智能语音导览等功能

**开发者**：新疆指南针文化发展有限公司  
**版本**：v1.0.1  
**更新时间**：2025-01-08

[功能特点](#核心功能) • [快速开始](#-快速开始) • [打包上架](#-应用打包与上架指南中国大陆版) • [开发文档](#-开发指南)

</div>

---

## 📑 目录

- [🎯 项目简介](#-项目简介)
- [🚀 快速开始](#-快速开始)
  - [环境要求](#环境要求)
  - [安装步骤](#安装步骤)
  - [高德地图密钥申请](#高德地图密钥申请详细步骤)
  - [常用命令](#常用命令)
- [📦 应用打包与上架](#-应用打包与上架指南中国大陆版)
  - [📱 Android 打包上架](#-android-打包上架完整流程)
  - [🌍 Google Play 上架](#-google-play-上架完整流程)
  - [🍎 iOS 打包上架](#-ios-打包上架完整流程)
  - [🧾 上架资料清单](#-上架资料清单)
  - [📋 打包前检查清单](#-打包前检查清单)
  - [🚀 一键打包命令](#-一键打包命令汇总)
- [🔧 开发指南](#-开发指南)
- [📝 更新日志](#-更新日志)
- [❓ 常见问题](#-常见问题)
- [👥 团队信息](#-团队信息)

---

## 🎯 项目简介

### 核心功能

- 🗺️ **实时定位** - 高德地图精准定位，误差小于50米
- 🎤 **智能语音导览** - 讯飞语音识别 + 百度自然语音播报
- 🏞️ **景点推荐** - 基于位置的个性化景点推荐
- 🍜 **美食文化** - 挖掘地道美食与文化体验
- 📍 **地图导航** - 高德地图导航，轻松到达目的地
- 🚀 **启动屏** - 专业启动页面，无白屏闪烁

### 技术栈

- **框架**: React Native 0.81.4
- **语音服务**: 百度 TTS + 讯飞 ASR
- **地图定位**: 高德地图 SDK
- **状态管理**: Context API
- **UI 组件**: React Native 原生组件

---

## 🚀 快速开始

### 环境要求

| 工具             | 版本要求                |
|----------------|---------------------|
| Node.js        | >= 20               |
| Yarn           | 最新版                 |
| React Native   | 0.81.4              |
| Android Studio | 最新版（Android 开发）     |
| Xcode          | 14+（iOS 开发，仅 macOS） |

### 安装步骤

#### 1. 安装依赖

```bash
# 安装 Node.js 依赖
yarn install

# 安装 iOS 依赖（仅 macOS）
cd ios && pod install && cd ..
```

#### 2. 配置环境变量

**复制环境变量模板：**

```bash
cp .env.example .env
```

**编辑 `.env` 文件：**

```bash
# 语音服务配置
BAIDU_API_KEY=你的百度API_Key
BAIDU_SECRET_KEY=你的百度Secret_Key
IFLYTEK_APP_ID=你的讯飞APPID
IFLYTEK_API_KEY=你的讯飞API_Key
IFLYTEK_API_SECRET=你的讯飞API_Secret

# 高德地图配置（必须配置）
AMAP_IOS_KEY=你的iOS密钥
AMAP_ANDROID_KEY=你的Android密钥
AMAP_WEB_KEY=你的Web密钥

# API 服务器配置
API_BASE_URL=https://lvyou.bellaedu.cn/prod-trip
```

**获取 API 密钥：**

| 服务    | 获取地址                           | 用途   |
|-------|--------------------------------|------|
| 高德地图  | https://console.amap.com/      | 地图定位 |
| 百度智能云 | https://console.bce.baidu.com/ | 语音播报 |
| 科大讯飞  | https://www.xfyun.cn/          | 语音识别 |

#### 高德地图密钥申请详细步骤

高德地图 Key 是应用正常运行的**必需配置**，用于地图显示、定位、搜索等功能。

##### 第 1 步：注册高德开放平台账号

1. 访问 **高德开放平台**：https://lbs.amap.com/
2. 点击右上角 **"注册/登录"**
3. 使用手机号或邮箱完成注册
4. 完成实名认证（个人或企业，建议选择个人）

##### 第 2 步：成为开发者

1. 登录后，点击 **"控制台"** 进入开发者控制台
2. 首次进入会提示成为开发者，点击 **"成为开发者"**
3. 填写基本信息：
    - 开发者类型：个人开发者
    - 真实姓名：填写真实姓名
    - 手机号码：填写手机号
    - 验证码：获取并填写
4. 提交后即成为开发者

##### 第 3 步：创建应用

1. 在控制台首页，点击 **"应用管理"** → **"我的应用"**
2. 点击 **"创建新应用"** 按钮
3. 填写应用信息：
   ```
   应用名称：山猫导游（或您自己的应用名称）
   应用类型：移动应用
   ```
4. 点击 **"提交"** 创建应用

##### 第 4 步：添加 Key（重要）

创建应用后，需要为不同平台分别添加 Key：

**4.1 添加 iOS Key**

1. 在应用详情页，点击 **"添加 Key"**
2. 选择服务平台：**iOS**
3. 填写信息：
   ```
   Key 名称：BellaTravel-iOS（随意命名）
   Bundle ID：com.lynxTravel（必须与项目一致）
   ```
4. 点击 **"提交"**
5. 复制生成的 **Key**（格式：xxxxxxxxxxxxxxxxxxxxxxxxxxxx）
6. 将此 Key 填入 `.env` 文件的 `AMAP_IOS_KEY`

**4.2 添加 Android Key**

1. 再次点击 **"添加 Key"**
2. 选择服务平台：**Android**
3. 填写信息：
   ```
   Key 名称：BellaTravel-Android（随意命名）
   PackageName：com.lynxTravel（必须与项目一致）
   发布版 SHA1：<需要获取，见下方>
   调试版 SHA1：<需要获取，见下方>
   ```

**获取 SHA1 指纹（重要）：**

```bash
# 调试版 SHA1（用于开发测试）
cd android
keytool -list -v -keystore app/debug.keystore -storepass android -alias androiddebugkey

# 发布版 SHA1（用于正式发布）
keytool -list -v -keystore app.jks -storepass bellarn -alias mykey
```

在输出结果中找到 `SHA1` 行，复制后面的值（格式：`XX:XX:XX:...`）

4. 将 SHA1 填入对应的输入框（去掉冒号或保留都可以）
5. 点击 **"提交"**
6. 复制生成的 **Key**
7. 将此 Key 填入 `.env` 文件的 `AMAP_ANDROID_KEY`

**4.3 添加 Web Key（可选）**

1. 再次点击 **"添加 Key"**
2. 选择服务平台：**Web 端（JS API）**
3. 填写信息：
   ```
   Key 名称：BellaTravel-Web
   ```
4. 点击 **"提交"**
5. 复制生成的 **Key**
6. 将此 Key 填入 `.env` 文件的 `AMAP_WEB_KEY`

##### 第 5 步：配置白名单（可选）

如果使用了 Web Key，需要配置域名白名单：

1. 在 Web Key 详情页，找到 **"域名白名单"**
2. 添加允许的域名，例如：
   ```
   localhost
   127.0.0.1
   yourdomain.com
   ```

##### 第 6 步：验证配置

1. 将获取的 3 个 Key 填入 `.env` 文件：
   ```bash
   AMAP_IOS_KEY=你的iOS密钥
   AMAP_ANDROID_KEY=你的Android密钥
   AMAP_WEB_KEY=你的Web密钥
   ```

2. 重启应用并测试：
   ```bash
   # 清除缓存
   yarn start --reset-cache
   
   # 重新运行
   yarn android
   # 或
   yarn ios
   ```

3. 检查定位功能是否正常

##### 常见问题

**Q1: Key 无效或定位失败**

**原因和解决方案：**

- ✅ 检查 Bundle ID / Package Name 是否与项目一致
- ✅ 检查 SHA1 是否正确配置（Android）
- ✅ 确认使用的是对应平台的 Key（iOS Key 不能用于 Android）
- ✅ Key 配置后需要等待 3-5 分钟生效
- ✅ 清除应用缓存并重启

**Q2: Android 定位不准确**

**解决：**

- 必须配置正确的 SHA1 指纹
- 调试版和发布版使用不同的 keystore，SHA1 也不同
- 确保已将两个 SHA1 都添加到控制台

**Q3: SHA1 获取失败**

**解决：**

```bash
# 如果 keytool 命令找不到，需要配置 Java 环境
# macOS/Linux
export PATH="$JAVA_HOME/bin:$PATH"

# 或使用 Android Studio 查看
# Build → Generate Signed Bundle/APK → 选择 keystore 文件
```

**Q4: 超过配额限制**

高德地图有免费配额限制：

- 个人认证：30 万次/天
- 企业认证：100 万次/天
- 超过需要付费

对于大部分应用，个人配额已足够使用。

##### 配额使用建议

- ✅ 使用缓存减少重复请求
- ✅ 避免频繁调用定位接口（建议间隔 > 1 秒）
- ✅ 在控制台监控每日用量
- ✅ 必要时升级为企业认证

##### 相关链接

- 📚 [高德开放平台控制台](https://console.amap.com/)
- 📖 [高德地图 Key 申请指南](https://lbs.amap.com/api/android-sdk/guide/create-project/get-key)
- 💡 [SHA1 获取教程](https://lbs.amap.com/api/android-sdk/guide/create-project/get-key#get-key)
- 📊 [配额说明](https://lbs.amap.com/api/webservice/guide/tools/flowlevel)

---

#### 3. 运行应用

```bash
# Android
yarn android:hot

# iOS
yarn ios:hot

# iOS 模拟器
yarn ios:simulator
```

#### 4. 启用自然语音播报（重要）

**首次运行需要重新编译原生代码：**

```bash
# Android
cd android && ./gradlew clean && cd .. && npx react-native run-android

# iOS
cd ios && pod install && cd .. && npx react-native run-ios
```

### 常用命令

```bash
# 开发
yarn start                # 启动 Metro 服务器
yarn android              # 运行 Android
yarn ios                  # 运行 iOS

# 清理
yarn clean:cache          # 清除缓存
yarn clean:all            # 清除并重装所有依赖

# 打包
yarn build:android        # Android 打包
cd ios && xcodebuild ...  # iOS 打包（使用 Xcode Archive）
```

---

## 🎨 应用图标生成指南

> **重要**：应用图标是用户对 App 的第一印象，必须精心设计且符合平台规范。

### 📝 设计规范和要求

#### 基础要求

| 项目 | 要求 | 说明 |
|------|------|------|
| **尺寸** | 1024x1024 px | 最高质量，用于各平台 |
| **格式** | PNG / JPG | PNG 推荐，支持透明通道 |
| **背景** | 不透明 | iOS/Android 会自动添加白色背景 |
| **圆角** | 不要添加 | 系统会自动处理 |
| **内边距** | 10-20% | 图标主体占 80%，留安全边距 |
| **颜色** | 品牌色 | 避免纯白/纯黑，深浅背景均清晰 |

#### 平台特定规范

**iOS 设计规范：**
- ✅ 扁平化设计，使用渐变和阴影
- ✅ 图标应清晰识别，避免文字过小
- ✅ 适配所有 iOS 设备尺寸

**Android 设计规范：**
- ✅ Material Design 风格
- ✅ 使用品牌色，图标有层次感
- ✅ 适配自适应图标（Adaptive Icons）

---

### 🚀 方法一：使用 Icon Kitchen（推荐）

Icon Kitchen 是最简单的方式，可一键生成所有平台所需的图标尺寸。

#### 步骤 1：准备原始图标

**设计工具推荐：**
- [Figma](https://www.figma.com/) - 免费，在线使用
- [Canva](https://www.canva.com/) - 免费，模板丰富
- Adobe Illustrator - 专业矢量工具
- Sketch - macOS 专用

**设计步骤：**
1. 创建 1024x1024 px 画布
2. 设计图标主体，居中放置
3. 四周留 10-20% 的安全边距
4. 导出为 PNG 格式（建议无透明背景）

**设计提示：**
```
✅ 使用品牌主色调
✅ 图标简洁易识别
✅ 在小尺寸下仍然清晰
✅ 与应用名称和功能相关
❌ 避免太多细节和文字
❌ 不要直接使用照片
```

#### 步骤 2：使用 Icon Kitchen 生成

1. **访问 Icon Kitchen**
   ```
   https://icon.kitchen/
   ```

2. **上传图标**
   - 点击 **"Upload Image"** 按钮
   - 选择你的 1024x1024 PNG 图标

3. **调整预览效果**
   - **Padding**：调整内边距（建议 10-20%）
   - **Background**：选择背景色（如果有透明区域）
   - **Shape**：选择 **None**，让系统自动处理

4. **预览检查**
   - 查看 iOS 和 Android 的预览效果
   - 确保图标在各种尺寸下都清晰可见

5. **下载图标包**
   - 点击 **"Download"** 按钮
   - 下载生成的 zip 文件

#### 步骤 3：替换 Android 图标

```bash
# 1. 解压下载的 zip 文件
cd ~/Downloads
unzip icon-kitchen-output.zip -d icon-output

# 2. 备份原有图标（可选）
mkdir ~/Desktop/backup-icons
cp -r android/app/src/main/res/mipmap-* ~/Desktop/backup-icons/

# 3. 替换 Android 图标
cp -r ~/Downloads/icon-output/android/res/mipmap-* \
  android/app/src/main/res/

# 4. 验证图标已替换
ls -lh android/app/src/main/res/mipmap-*/ic_launcher.png
```

**生成的 Android 图标尺寸：**
```
mipmap-mdpi/       48x48 px
mipmap-hdpi/       72x72 px
mipmap-xhdpi/      96x96 px
mipmap-xxhdpi/     144x144 px
mipmap-xxxhdpi/    192x192 px
```

#### 步骤 4：替换 iOS 图标

**方法 1：命令行（快速）**

```bash
# 1. 备份原有图标
mkdir ~/Desktop/backup-ios-icons
cp ios/BellaTravel/Images.xcassets/AppIcon.appiconset/*.png \
  ~/Desktop/backup-ios-icons/

# 2. 替换图标
cp ~/Downloads/icon-output/ios/Assets.xcassets/AppIcon.appiconset/*.png \
  ios/BellaTravel/Images.xcassets/AppIcon.appiconset/

# 3. 验证
ls -lh ios/BellaTravel/Images.xcassets/AppIcon.appiconset/
```

**方法 2：使用 Xcode（推荐，更安全）**

```bash
# 1. 打开 Xcode
open ios/BellaTravel.xcworkspace

# 2. 在 Xcode 中操作：
# - 左侧导航栏找到 "Images.xcassets"
# - 点击 "AppIcon"
# - 拖拽对应尺寸的图标到对应位置
# - Xcode 会自动校验尺寸是否正确
```

**iOS 图标尺寸列表：**
```
iPhone App:
- 20pt   (20x20, 40x40, 60x60)
- 29pt   (29x29, 58x58, 87x87)
- 40pt   (40x40, 80x80, 120x120)
- 60pt   (120x120, 180x180)

iPad App:
- 20pt, 29pt, 40pt, 76pt, 83.5pt

App Store:
- 1024x1024 px
```

#### 步骤 5：验证图标

**Android 验证：**

```bash
# 1. 清理并重新构建
cd android
./gradlew clean
cd ..

# 2. 运行应用
yarn android

# 3. 检查：
# - 查看桌面图标是否正常显示
# - 检查多任务切换界面的图标
```

**iOS 验证：**

```bash
# 1. 清理并重新构建
cd ios
rm -rf build
cd ..

# 2. 运行应用
yarn ios

# 3. 检查 Xcode 中是否有警告：
# - 打开 ios/BellaTravel.xcworkspace
# - 查看 Images.xcassets → AppIcon
# - 确保没有黄色警告图标
```

---

### 🛠️ 方法二：手动生成（进阶）

如果需要更精细的控制，可以使用 ImageMagick 手动生成。

#### 安装 ImageMagick

```bash
# macOS
brew install imagemagick

# 验证安装
convert --version
```

#### 创建生成脚本

创建 `scripts/generate-app-icons.sh`：

```bash
#!/bin/bash

set -e

ORIGINAL_ICON="$1"  # 原始 1024x1024 图标路径
PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"

if [ -z "$ORIGINAL_ICON" ]; then
    echo "❌ 错误：请提供原始图标路径"
    echo "使用方法： ./scripts/generate-app-icons.sh path/to/icon-1024.png"
    exit 1
fi

if [ ! -f "$ORIGINAL_ICON" ]; then
    echo "❌ 错误：图标文件不存在：$ORIGINAL_ICON"
    exit 1
fi

echo "🎨 开始生成应用图标..."
echo ""

# Android 图标
echo "🤖 生成 Android 图标..."
ANDROID_RES="$PROJECT_ROOT/android/app/src/main/res"

declare -A ANDROID_SIZES=(
    ["mdpi"]=48
    ["hdpi"]=72
    ["xhdpi"]=96
    ["xxhdpi"]=144
    ["xxxhdpi"]=192
)

for density in "${!ANDROID_SIZES[@]}"; do
    size=${ANDROID_SIZES[$density]}
    output_dir="$ANDROID_RES/mipmap-$density"
    mkdir -p "$output_dir"
    convert "$ORIGINAL_ICON" -resize ${size}x${size} "$output_dir/ic_launcher.png"
    echo "  ✅ mipmap-$density: ${size}x${size}"
done

echo ""
echo "🍎 生成 iOS 图标..."

iOS_ICONSET="$PROJECT_ROOT/ios/BellaTravel/Images.xcassets/AppIcon.appiconset"
mkdir -p "$iOS_ICONSET"

# iOS 图标尺寸
declare -a iOS_SIZES=(
    "20:1" "20:2" "20:3"
    "29:1" "29:2" "29:3"
    "40:1" "40:2" "40:3"
    "60:2" "60:3"
    "76:1" "76:2"
    "83.5:2"
    "1024:1"
)

for size_info in "${iOS_SIZES[@]}"; do
    IFS=':' read -r base scale <<< "$size_info"
    actual_size=$(echo "$base * $scale" | bc)
    filename="icon-${base}@${scale}x.png"
    convert "$ORIGINAL_ICON" -resize ${actual_size}x${actual_size} "$iOS_ICONSET/$filename"
    echo "  ✅ $filename: ${actual_size}x${actual_size}"
done

echo ""
echo "✨ 图标生成完成！"
echo "📝 请检查以下目录："
echo "   Android: $ANDROID_RES/mipmap-*/ic_launcher.png"
echo "   iOS: $iOS_ICONSET/"
```

#### 使用生成脚本

```bash
# 1. 添加执行权限
chmod +x scripts/generate-app-icons.sh

# 2. 运行脚本
./scripts/generate-app-icons.sh path/to/your/icon-1024.png

# 3. 验证生成的图标
yarn android  # 或 yarn ios
```

---

### ❓ 常见问题

**Q1: 图标模糊或失真？**

**解决：**
- ✅ 使用至少 1024x1024 的高清图标
- ✅ 使用矢量图设计（AI、SVG）后导出为 PNG
- ❌ 避免从小图放大

**Q2: Android 图标显示白色背景？**

**解决：**
```xml
<!-- android/app/src/main/res/values/colors.xml -->
<resources>
  <color name="ic_launcher_background">#FFFFFF</color>
</resources>
```

**Q3: iOS 图标缺失某些尺寸？**

**解决：**
1. 打开 Xcode
2. 检查 AppIcon 设置
3. 确保勾选了所有需要的设备类型：iPhone、iPad、App Store

**Q4: 打包后图标没有更新？**

**解决：**
```bash
# Android
cd android && ./gradlew clean && cd .. && yarn android

# iOS
cd ios && rm -rf build && cd .. && yarn ios
```

---

### 📚 更多资源

**在线工具：**
- [Icon Kitchen](https://icon.kitchen/) - 推荐，免费一键生成
- [App Icon Generator](https://www.appicon.co/)
- [MakeAppIcon](https://makeappicon.com/)

**设计工具：**
- [Figma](https://www.figma.com/) - 免费，在线使用
- [Canva](https://www.canva.com/) - 免费模板
- [Adobe Illustrator](https://www.adobe.com/products/illustrator.html)

**参考文档：**
- [iOS Human Interface Guidelines - App Icon](https://developer.apple.com/design/human-interface-guidelines/app-icons)
- [Android Material Design - Product Icons](https://material.io/design/iconography/product-icons.html)

---

## 📦 应用打包与上架指南（中国大陆版）

本指南专门针对**中国大陆开发者**，包含完整的打包、签名、上架流程。

---

## 📱 Android 打包上架完整流程

### 第一步：生成签名密钥（首次必做）

Android 应用必须使用数字证书签名才能发布。**签名密钥非常重要，丢失后无法更新应用！**

#### 1.1 生成 Keystore 文件

```bash
# 进入项目根目录
cd /Users/xiazhui/Desktop/code/bella/BellaTravel

# 生成签名密钥（已有 app.jks 可跳过）
keytool -genkeypair -v -storetype PKCS12 \
  -keystore app.jks \
  -alias mykey \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000
```

**按提示输入以下信息：**

```
密钥库口令: bellarn
再次输入新口令: bellarn
您的名字与姓氏是什么?: 山猫导游
您的组织单位名称是什么?: 新疆指南针文化发展有限公司
您的组织名称是什么?: 新疆指南针
您所在的城市或区域名称是什么?: 乌鲁木齐
您所在的省/市/自治区名称是什么?: 新疆
该单位的双字母国家/地区代码是什么?: CN
正确吗？[否]: y

输入 <mykey> 的密钥口令（如果和密钥库口令相同, 按回车）: 
```

#### 1.2 获取签名信息

```bash
# 查看签名信息（用于应用市场填写）
keytool -list -v -keystore app.jks -storepass bellarn
```

**记录以下信息（上架时需要）：**

- **MD5**: 形如 `A1:B2:C3:D4:...`
- **SHA1**: 形如 `E5:F6:G7:H8:...`
- **SHA256**: 形如 `I9:J0:K1:L2:...`

#### 1.3 配置签名（已完成，仅供参考）

您的项目已在 `android/gradle.properties` 中配置好：

```properties
MYAPP_UPLOAD_STORE_FILE=/Users/xiazhui/Desktop/code/bella/BellaTravel/app.jks
MYAPP_UPLOAD_KEY_ALIAS=mykey
MYAPP_UPLOAD_STORE_PASSWORD=bellarn
MYAPP_UPLOAD_KEY_PASSWORD=bellarn
```

⚠️ **务必备份 `app.jks` 文件！建议存储在：**

- 云盘（百度网盘、阿里云盘）
- U盘
- 密码管理器（1Password、Bitwarden）

---

### 第二步：打包 APK/AAB

#### 2.1 更新版本号

**编辑 `android/app/build.gradle`：**

```gradle
defaultConfig {
    applicationId "com.lynxTravel"
    versionCode 2          // 每次发布 +1（整数）
    versionName "1.0.1"    // 显示给用户的版本号
}
```

**同步更新 `package.json`：**

```json
{
  "version": "1.0.1"
}
```

**同步更新 `ios/BellaTravel/Info.plist`：**

```xml

<key>CFBundleShortVersionString</key>
<string>1.0.1</string>
<key>CFBundleVersion</key>
<string>2</string>
```

#### 2.2 打包 APK（通用格式）

```bash
# 1. 确保代码已保存
git status

# 2. 清理缓存
yarn clean:cache

# 3. 进入 Android 目录
cd android

# 4. 清理旧构建
./gradlew clean

# 5. 打包 Release APK
./gradlew assembleRelease

# 6. 返回根目录
cd ..

# 7. 复制 APK 到桌面（方便查找）
cp android/app/build/outputs/apk/release/app-release.apk ~/Desktop/山猫导游-v1.0.1.apk
```

**APK 文件位置：**

```
android/app/build/outputs/apk/release/app-release.apk
```

**APK 大小：** 约 35-50 MB（已启用混淆和压缩）

#### 2.3 打包 AAB（Google Play 专用）

```bash
cd android
./gradlew clean
./gradlew bundleRelease
cd ..

# AAB 文件位置
# android/app/build/outputs/bundle/release/app-release.aab
```

#### 2.4 验证打包

```bash
# 查看 APK 信息
aapt dump badging android/app/build/outputs/apk/release/app-release.apk

# 安装到手机测试
adb install -r android/app/build/outputs/apk/release/app-release.apk

# 查看 APK 大小
ls -lh android/app/build/outputs/apk/release/app-release.apk
```

#### 2.5 Android 打包常见问题详解

##### 问题 1：打包失败 - "babel-plugin-transform-remove-console" 找不到

**错误信息：**
```
Error: Cannot find module 'babel-plugin-transform-remove-console'
```

**原因：** 依赖未正确安装或 node_modules 损坏

**解决方案：**

```bash
# 方案1：重新安装依赖
rm -rf node_modules
yarn install

# 方案2：清理缓存后重装
yarn cache clean
rm -rf node_modules yarn.lock
yarn install

# 方案3：如果还不行，检查 package.json 是否包含该插件
grep "transform-remove-console" package.json

# 如果没有，手动安装
yarn add -D babel-plugin-transform-remove-console
```

##### 问题 2：打包失败 - "createBundleReleaseJsAndAssets" 错误

**错误信息：**
```
Execution failed for task ':app:createBundleReleaseJsAndAssets'
> Process 'command 'node'' finished with non-zero exit value 1
```

**原因：** Metro bundler 缓存问题或 JavaScript 代码有语法错误

**解决方案：**

```bash
# 步骤1：清理所有缓存
yarn clean:cache

# 或手动清理
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-*
watchman watch-del-all  # 如果安装了 watchman

# 步骤2：清理 Android 构建缓存
cd android
./gradlew clean
./gradlew cleanBuildCache
rm -rf .gradle
cd ..

# 步骤3：重新打包
cd android
./gradlew assembleRelease --stacktrace
```

**如果仍然失败，查看详细错误：**

```bash
cd android
./gradlew assembleRelease --stacktrace --info
```

查看输出中的具体 JavaScript 错误，修复代码后重试。

##### 问题 3：签名失败 - Keystore 文件找不到

**错误信息：**
```
Keystore file '/path/to/app.jks' not found for signing config 'release'
```

**解决方案：**

```bash
# 步骤1：检查 keystore 文件是否存在
ls -la app.jks

# 步骤2：检查 gradle.properties 中的路径
cat android/gradle.properties | grep MYAPP_UPLOAD_STORE_FILE

# 步骤3：确保路径是绝对路径
# 编辑 android/gradle.properties
MYAPP_UPLOAD_STORE_FILE=/Users/xiazhui/Desktop/code/bella/BellaTravel/app.jks

# 步骤4：验证路径正确
ls -la $(cat android/gradle.properties | grep MYAPP_UPLOAD_STORE_FILE | cut -d'=' -f2)
```

##### 问题 4：内存不足 - "Java heap space" 错误

**错误信息：**
```
java.lang.OutOfMemoryError: Java heap space
```

**解决方案：**

编辑 `android/gradle.properties`，增加内存限制：

```properties
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError
org.gradle.parallel=true
org.gradle.daemon=true
```

重新打包：

```bash
cd android
./gradlew clean
./gradlew assembleRelease
```

##### 问题 5：高德地图 Key 无效

**现象：** 打包成功但地图不显示或定位失败

**原因：** 发布版 APK 的 SHA1 未配置到高德地图控制台

**解决方案：**

```bash
# 步骤1：获取发布版 SHA1
keytool -list -v -keystore app.jks -storepass bellarn

# 步骤2：记录 SHA1（格式：XX:XX:XX:...）

# 步骤3：登录高德地图控制台
# https://console.amap.com/

# 步骤4：找到 Android Key → 编辑
# 添加或更新"发布版 SHA1"字段

# 步骤5：等待 3-5 分钟生效

# 步骤6：重新安装测试
adb install -r android/app/build/outputs/apk/release/app-release.apk
```

##### 问题 6：APK 体积过大

**现象：** APK 超过 100MB

**解决方案：**

检查 `android/app/build.gradle` 是否启用了以下优化：

```gradle
android {
    buildTypes {
        release {
            // 启用代码混淆和压缩
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            
            // 启用资源压缩
            crunchPngs true
        }
    }
    
    // 分包配置（如果需要）
    splits {
        abi {
            enable true
            reset()
            include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
            universalApk true
        }
    }
}
```

分包后会生成多个 APK，选择 `app-universal-release.apk` 上传到应用商店。

##### 问题 7：应用安装后崩溃

**调试步骤：**

```bash
# 步骤1：连接设备并安装 APK
adb install -r android/app/build/outputs/apk/release/app-release.apk

# 步骤2：启动应用
adb shell monkey -p com.lynxTravel -c android.intent.category.LAUNCHER 1

# 步骤3：查看崩溃日志
adb logcat | grep -E "AndroidRuntime|ReactNative|FATAL"

# 步骤4：保存日志到文件
adb logcat > crash.log

# 步骤5：查找错误关键字
grep -i "error\|exception\|fatal" crash.log
```

**常见崩溃原因：**

1. **Proguard 混淆规则错误**
   - 检查 `android/app/proguard-rules.pro`
   - 添加第三方库的混淆规则

2. **权限未在 Manifest 中声明**
   - 检查 `android/app/src/main/AndroidManifest.xml`

3. **.env 环境变量未加载**
   - 确保 `.env` 文件存在
   - 检查 `babel.config.js` 中的 `react-native-dotenv` 配置

##### 问题 8：打包速度太慢

**优化方案：**

编辑 `android/gradle.properties`：

```properties
# 启用守护进程
org.gradle.daemon=true

# 启用并行构建
org.gradle.parallel=true

# 启用按需配置
org.gradle.configureondemand=true

# 增加内存
org.gradle.jvmargs=-Xmx4096m

# 启用增量编译
kotlin.incremental=true
```

**使用增量构建：**

```bash
# 不清理缓存，直接构建（适用于小改动）
cd android
./gradlew assembleRelease
```

##### 问题 9：无法连接到 adb 设备

```bash
# 重启 adb 服务
adb kill-server
adb start-server

# 查看已连接设备
adb devices

# 如果显示 "unauthorized"，手机端重新授权

# 如果没有设备，检查 USB 调试是否开启
# 设置 → 开发者选项 → USB 调试
```

##### 问题 10：签名不一致，无法覆盖安装

**错误信息：**
```
FAILURE: INSTALL_FAILED_UPDATE_INCOMPATIBLE
```

**解决方案：**

```bash
# 方案1：卸载旧版本
adb uninstall com.lynxTravel
adb install android/app/build/outputs/apk/release/app-release.apk

# 方案2：使用 -r 参数强制重装（仅适用于相同签名）
adb install -r android/app/build/outputs/apk/release/app-release.apk
```

**注意：** 发布版和调试版使用不同的签名，无法直接覆盖安装。

##### 完整打包验证清单

```bash
# ===== Android 打包完整验证流程 =====

# 1. 清理环境
cd /Users/xiazhui/Desktop/code/bella/BellaTravel
rm -rf node_modules
yarn install

# 2. 更新版本号
# 编辑 android/app/build.gradle
# versionCode 2
# versionName "1.0.1"

# 3. 清理缓存
yarn clean:cache
cd android
./gradlew clean
cd ..

# 4. 验证签名配置
cat android/gradle.properties | grep MYAPP_UPLOAD
ls -la app.jks

# 5. 验证高德地图 Key
# 确保 .env 文件存在且配置正确
cat .env | grep AMAP

# 6. 打包
cd android
./gradlew assembleRelease
cd ..

# 7. 验证 APK
ls -lh android/app/build/outputs/apk/release/app-release.apk
aapt dump badging android/app/build/outputs/apk/release/app-release.apk | grep version

# 8. 获取签名指纹
keytool -printcert -jarfile android/app/build/outputs/apk/release/app-release.apk

# 9. 测试安装
adb devices
adb uninstall com.lynxTravel
adb install android/app/build/outputs/apk/release/app-release.apk

# 10. 启动应用
adb shell monkey -p com.lynxTravel -c android.intent.category.LAUNCHER 1

# 11. 查看日志
adb logcat | grep -E "ReactNative|BellaTravel"

# 12. 测试核心功能
# - 启动应用（无崩溃）
# - 授权位置和麦克风权限
# - 地图正常加载和定位
# - 语音识别和播报功能
# - 景点推荐和详情页

# 13. 复制到桌面
cp android/app/build/outputs/apk/release/app-release.apk ~/Desktop/山猫导游-v1.0.1.apk

echo "✅ Android 打包验证完成！"
```

---

### 第三步：上架到中国应用商店

中国大陆主流应用商店（无需 Google Play）：

#### 3.1 华为应用市场（推荐，市场份额最大）

**注册开发者账号：**

1. 访问：https://developer.huawei.com/consumer/cn/
2. 点击 "注册" → 选择 "个人开发者" 或 "企业开发者"
3. 完成实名认证（个人需身份证，企业需营业执照）
4. 个人开发者免费，企业开发者 ¥99/年

**上传应用：**

1. 登录 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)
2. 我的应用 → 新建 → 填写应用信息
   ```
   应用名称：山猫导游
   应用包名：com.lynxTravel
   应用分类：旅游与出行
   ```
3. 上传 APK 文件
4. 填写应用信息：
    - **应用简介**：（见下方"应用商店通用信息"）
    - **应用截图**：至少 3 张（1080x1920 或 1080x2340）
    - **应用图标**：512x512 px
    - **隐私政策**：必须提供 URL
    - **版本说明**：本次更新内容
5. 填写签名信息：
    - **包名**：com.lynxTravel
    - **MD5**：从 keytool 输出复制
    - **SHA256**：从 keytool 输出复制
6. 提交审核（通常 1-3 个工作日）

**审核要点：**

- ✅ 必须有隐私政策页面
- ✅ 必须正确配置权限说明
- ✅ 不能有闪退、崩溃
- ✅ 不能含有违规内容

#### 3.2 应用宝（腾讯，推荐）

**注册开发者：**

1. 访问：https://open.qq.com/
2. 注册并完成实名认证（免费）

**上传应用：**

1. 登录 [腾讯开放平台](https://open.qq.com/)
2. 管理中心 → 应用管理 → 创建应用 → 移动应用
3. 填写应用信息并上传 APK
4. 填写软著登记号（可选，但建议申请）
5. 提交审核（通常 2-5 个工作日）

**特殊要求：**

- 建议有软件著作权登记证书
- 需要提供应用介绍视频（可选）

#### 3.3 小米应用商店

**注册开发者：**

1. 访问：https://dev.mi.com/console/
2. 使用小米账号登录并完成认证（免费）

**上传应用：**

1. 登录开发者平台 → 管理控制台
2. 应用管理 → 创建应用
3. 上传 APK 并填写信息
4. 提交审核（通常 1-2 个工作日）

#### 3.4 OPPO 软件商店

- 注册：https://open.oppomobile.com/
- 个人开发者免费
- 审核时间：1-3 个工作日

#### 3.5 vivo 应用商店

- 注册：https://dev.vivo.com.cn/
- 个人开发者免费
- 审核时间：1-3 个工作日

#### 3.6 其他应用商店

| 应用商店     | 注册地址                            | 费用 | 审核时间  |
|----------|---------------------------------|----|-------|
| 百度手机助手   | https://app.baidu.com/          | 免费 | 2-3 天 |
| 360 手机助手 | https://dev.360.cn/             | 免费 | 1-2 天 |
| 豌豆荚      | http://developer.wandoujia.com/ | 免费 | 2-3 天 |
| 魅族应用商店   | https://open.flyme.cn/          | 免费 | 1-2 天 |

---

### 第四步：应用商店通用信息

以下信息可复制用于各个应用商店：

#### 应用名称

```
山猫导游
```

#### 一句话简介（20字以内）

```
智能语音导览，发现身边精彩景点
```

#### 应用简介（500字以内）

```
【山猫导游 - 您的智能旅游助手】

山猫导游是一款专为旅游爱好者打造的智能导览应用，让您的每一次旅行都更加精彩。

✨ 核心功能

• 智能定位 - 自动获取当前位置，实时推荐周边景点
• 语音导览 - AI语音识别与播报，解放双手，边走边听
• 景点推荐 - 基于位置的个性化景点推荐，发现身边美景
• 美食文化 - 挖掘地道美食与文化体验，品味地方特色
• 地图导航 - 高德地图精准导航，轻松到达目的地
• 自动播报 - 到达景区自动讲解，沉浸式游览体验

🎯 产品特色

• 高精度定位：采用高德地图SDK，定位精准，误差小于50米
• 智能语音：集成讯飞语音识别和百度自然语音播报
• 海量景点：覆盖全国各地景区景点，持续更新中
• 文化深度：不仅是导游，更是文化传播者
• 简洁易用：界面清爽，操作简单，老少皆宜

🌟 适用场景

• 自由行游客 - 随时随地获取景点信息
• 跟团旅游 - 补充了解更多文化知识  
• 本地居民 - 发现身边被忽略的美景
• 文化爱好者 - 深度了解地域文化

让山猫导游陪伴您的每一次旅行，发现更多精彩！
```

#### 版本更新说明

```
v1.0.1 更新内容：
1. 优化语音播报响应速度
2. 修复定位偶尔不准确的问题
3. 提升应用稳定性和性能
4. 优化用户界面体验
```

#### 应用分类

```
主分类：旅游与出行
子分类：旅游攻略 / 导游导览
```

#### 应用关键词

```
旅游,导游,语音导览,景点推荐,地图导航,美食,智能导游,新疆旅游
```

#### 权限说明

```
• 位置权限：用于获取用户位置，推荐周边景点和导航
• 麦克风权限：用于语音识别功能，实现语音交互
• 网络权限：用于加载景点数据和地图信息
• 存储权限：用于缓存地图数据，节省流量
```

#### 联系方式

```
开发者：新疆指南针文化发展有限公司
联系邮箱：kudduss@foxmail.com
客服 QQ：3249696828
```

---

### 第五步：准备应用资源

#### 5.1 应用图标生成完整指南

应用图标是用户对 App 的第一印象，必须设计精美且符合平台规范。

##### 设计要求

**基础要求：**

- **尺寸**：1024x1024 px（最高质量，用于各平台）
- **格式**：PNG（带透明通道）或 JPG
- **背景**：不建议透明背景（iOS 和部分 Android 商店会自动添加白色背景）
- **圆角**：不要自己添加圆角（系统会自动处理）
- **内边距**：建议图标主体占 80%，留 10% 的安全边距

**设计规范：**

```
iOS 规范：
- 扁平化设计
- 使用渐变和阴影
- 图标应清晰识别
- 避免文字过小

Android 规范：
- Material Design 风格
- 使用品牌色
- 图标有层次感
- 适配自适应图标（Adaptive Icons）
```

**颜色建议：**

- 使用品牌主色调
- 避免纯白色或纯黑色背景
- 确保在浅色和深色背景下都清晰可见
- 建议使用渐变色增加质感

##### 方法一：使用 Icon Kitchen 生成（推荐）

Icon Kitchen 是最简单的方式，可一键生成所有平台所需的图标尺寸。

**步骤 1：准备原始图标**

1. 设计 1024x1024 px 的图标（使用 Figma、Sketch、Photoshop 等）
2. 导出为 PNG 格式（建议无透明背景）
3. 确保图标主体居中，四周留有适当边距

**步骤 2：使用 Icon Kitchen 生成**

1. 访问：https://icon.kitchen/
2. 点击 **"Upload Image"** 上传您的 1024x1024 图标
3. 调整预览效果：
    - **Padding**：调整内边距（建议 10-20%）
    - **Background**：选择背景色（如果图标有透明区域）
    - **Shape**：选择形状（建议选择 None，让系统自动处理）
4. 预览效果：
    - 查看 iOS 和 Android 的预览效果
    - 确保图标在各种尺寸下都清晰可见
5. 点击 **"Download"** 下载生成的图标包（zip 文件）

**步骤 3：解压并应用图标**

下载的 zip 文件包含以下结构：

```
icon-kitchen-output.zip
├── android/
│   └── res/
│       ├── mipmap-hdpi/        # 72x72
│       ├── mipmap-mdpi/        # 48x48
│       ├── mipmap-xhdpi/       # 96x96
│       ├── mipmap-xxhdpi/      # 144x144
│       └── mipmap-xxxhdpi/     # 192x192
└── ios/
    └── Assets.xcassets/
        └── AppIcon.appiconset/
            ├── icon-20@1x.png
            ├── icon-20@2x.png
            ├── icon-20@3x.png
            ├── icon-29@1x.png
            ├── icon-29@2x.png
            ├── icon-29@3x.png
            ├── icon-40@1x.png
            ├── icon-40@2x.png
            ├── icon-40@3x.png
            ├── icon-60@2x.png
            ├── icon-60@3x.png
            ├── icon-76@1x.png
            ├── icon-76@2x.png
            ├── icon-83.5@2x.png
            └── icon-1024@1x.png
```

**步骤 4：替换 Android 图标**

```bash
# 解压下载的 zip 文件
unzip icon-kitchen-output.zip -d icon-output

# 进入项目 Android 资源目录
cd /Users/xiazhui/Desktop/code/bella/BellaTravel/android/app/src/main/res

# 备份原有图标（可选）
mkdir ~/Desktop/old-icons
cp -r mipmap-* ~/Desktop/old-icons/

# 复制新图标（覆盖所有尺寸）
cp -r ~/Downloads/icon-output/android/res/mipmap-* .

# 返回项目根目录
cd /Users/xiazhui/Desktop/code/bella/BellaTravel
```

**步骤 5：替换 iOS 图标**

```bash
# 方法 1: 使用命令行（快速）
cd /Users/xiazhui/Desktop/code/bella/BellaTravel/ios/BellaTravel/Images.xcassets/AppIcon.appiconset

# 备份原有图标
mkdir ~/Desktop/old-ios-icons
cp *.png ~/Desktop/old-ios-icons/

# 复制新图标
cp ~/Downloads/icon-output/ios/Assets.xcassets/AppIcon.appiconset/*.png .

# 返回项目根目录
cd /Users/xiazhui/Desktop/code/bella/BellaTravel
```

```bash
# 方法 2: 使用 Xcode（推荐，更安全）
# 1. 打开 Xcode
open ios/BellaTravel.xcworkspace

# 2. 在左侧导航栏找到 Images.xcassets
# 3. 点击 AppIcon
# 4. 拖拽对应尺寸的图标到对应位置
# 5. Xcode 会自动校验尺寸是否正确
```

##### 方法二：手动生成所有尺寸（进阶）

如果需要更精细的控制，可以手动生成所有尺寸。

**步骤 1：安装 ImageMagick**

```bash
# macOS
brew install imagemagick

# 验证安装
convert --version
```

**步骤 2：使用脚本批量生成**

创建脚本 `generate-icons.sh`：

```bash
#!/bin/bash

# 原始图标路径（1024x1024）
ORIGINAL_ICON="path/to/your/icon-1024.png"
PROJECT_ROOT="/Users/xiazhui/Desktop/code/bella/BellaTravel"

# Android 图标尺寸
ANDROID_SIZES=(
    "48:mdpi"
    "72:hdpi"
    "96:xhdpi"
    "144:xxhdpi"
    "192:xxxhdpi"
)

# 生成 Android 图标
echo "生成 Android 图标..."
for size_info in "${ANDROID_SIZES[@]}"; do
    IFS=: read size folder <<< "$size_info"
    output_dir="$PROJECT_ROOT/android/app/src/main/res/mipmap-$folder"
    mkdir -p "$output_dir"
    convert "$ORIGINAL_ICON" -resize ${size}x${size} "$output_dir/ic_launcher.png"
    echo "✓ 生成 mipmap-$folder/ic_launcher.png (${size}x${size})"
done

# iOS 图标尺寸
IOS_SIZES=(
    "20:1x"
    "40:2x"
    "60:3x"
    "29:1x"
    "58:2x"
    "87:3x"
    "40:1x"
    "80:2x"
    "120:3x"
    "120:2x"
    "180:3x"
    "76:1x"
    "152:2x"
    "167:2x"
    "1024:1x"
)

# 生成 iOS 图标
echo "生成 iOS 图标..."
IOS_OUTPUT="$PROJECT_ROOT/ios/BellaTravel/Images.xcassets/AppIcon.appiconset"
for size_info in "${IOS_SIZES[@]}"; do
    IFS=: read size scale <<< "$size_info"
    filename="icon-${size}@${scale}.png"
    convert "$ORIGINAL_ICON" -resize ${size}x${size} "$IOS_OUTPUT/$filename"
    echo "✓ 生成 $filename (${size}x${size})"
done

echo "✅ 图标生成完成！"
```

运行脚本：

```bash
chmod +x generate-icons.sh
./generate-icons.sh
```

##### 方法三：在线工具对比

| 工具名称                   | 网址                                 | 优点         | 缺点     |
|------------------------|------------------------------------|------------|--------|
| **Icon Kitchen**       | https://icon.kitchen/              | 免费、简单、一键生成 | 自定义选项少 |
| **App Icon Generator** | https://www.appicon.co/            | 支持更多平台     | 需要注册   |
| **MakeAppIcon**        | https://makeappicon.com/           | 界面友好       | 部分功能收费 |
| **Ape Tools**          | https://apetools.webprofusion.com/ | 功能全面       | 界面较复杂  |

##### 验证图标是否正确

**Android 验证：**

```bash
# 检查所有图标是否存在
cd android/app/src/main/res
ls -lh mipmap-*/ic_launcher.png

# 验证图标尺寸
file mipmap-mdpi/ic_launcher.png      # 应该是 48x48
file mipmap-hdpi/ic_launcher.png      # 应该是 72x72
file mipmap-xhdpi/ic_launcher.png     # 应该是 96x96
file mipmap-xxhdpi/ic_launcher.png    # 应该是 144x144
file mipmap-xxxhdpi/ic_launcher.png   # 应该是 192x192

# 运行应用查看效果
cd ../../../..
yarn android
```

**iOS 验证：**

```bash
# 打开 Xcode 检查
open ios/BellaTravel.xcworkspace

# 1. 左侧导航栏 → Images.xcassets → AppIcon
# 2. 检查所有尺寸是否都有图标
# 3. 确保没有黄色警告图标

# 运行应用查看效果
yarn ios
```

##### 常见问题

**Q1: 图标模糊或失真**

**原因**：原始图标分辨率太低

**解决**：

- 使用至少 1024x1024 的高清图标
- 使用矢量图设计（AI、SVG）后导出为 PNG
- 避免从小图放大

**Q2: Android 图标显示白色背景**

**原因**：图标有透明背景但未指定背景色

**解决**：

```xml
<!-- android/app/src/main/res/values/colors.xml -->
<resources>
  <color name="ic_launcher_background">#FFFFFF</color>
</resources>
```

或在 Icon Kitchen 生成时选择背景色。

**Q3: iOS 图标缺失某些尺寸**

**解决**：

1. 打开 Xcode
2. 检查 AppIcon 设置
3. 确保勾选了所有需要的设备类型：
    - iPhone
    - iPad
    - App Store

**Q4: 打包后图标没有更新**

**解决**：

```bash
# Android
cd android
./gradlew clean
cd ..
yarn android

# iOS
cd ios
rm -rf build
cd ..
yarn ios
```

##### 自适应图标（Android）

从 Android 8.0 开始支持自适应图标，可以适配不同的系统主题形状。

**创建自适应图标：**

1. 准备两张图片：
    - **前景图**（foreground）：1024x1024，主图标内容，透明背景
    - **背景图**（background）：1024x1024，纯色或渐变

2. 使用 Icon Kitchen 时选择 "Adaptive Icon"

3. 或手动配置：

```xml
<!-- android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml -->
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
  <background android:drawable="@mipmap/ic_launcher_background"/>
  <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
</adaptive-icon>
```

##### 快速命令汇总

```bash
# 1. 下载并解压 Icon Kitchen 生成的图标
cd ~/Downloads
unzip icon-kitchen-output.zip -d icon-output

# 2. 一键替换所有图标
cd /Users/xiazhui/Desktop/code/bella/BellaTravel

# 替换 Android 图标
cp -r ~/Downloads/icon-output/android/res/mipmap-* android/app/src/main/res/

# 替换 iOS 图标
cp ~/Downloads/icon-output/ios/Assets.xcassets/AppIcon.appiconset/*.png ios/BellaTravel/Images.xcassets/AppIcon.appiconset/

# 3. 清理并重新运行
yarn clean:cache
yarn android  # 或 yarn ios

echo "✅ 图标替换完成！"
```

##### 图标设计建议

**好的图标特点：**

- ✅ 简洁清晰，一眼能认出
- ✅ 使用品牌色，保持风格统一
- ✅ 在小尺寸下仍然清晰可辨
- ✅ 与应用名称和功能相关
- ✅ 在深色和浅色背景下都好看

**避免：**

- ❌ 太多细节和文字
- ❌ 使用位图放大（会模糊）
- ❌ 直接使用照片
- ❌ 过于复杂的渐变
- ❌ 与其他应用雷同

**设计工具推荐：**

- **Figma**（免费）：https://www.figma.com/
- **Canva**（免费）：https://www.canva.com/
- **Adobe Illustrator**（付费）：专业矢量图工具
- **Sketch**（付费，仅 macOS）：UI 设计工具

#### 5.2 应用截图

**尺寸要求：**

- 华为：1080x1920 或 1080x2340（至少 3 张）
- 应用宝：至少 3 张，最多 5 张
- 小米：至少 3 张截图

**截图建议：**

1. 首页（展示地图和景点列表）
2. 语音导览界面
3. 景点详情页
4. 美食文化页
5. 个人中心

**如何截图：**

```bash
# 方法1: 使用 Android Studio 自带工具
# Run app → Logcat 窗口右侧相机图标

# 方法2: 使用 adb 命令
adb shell screencap -p /sdcard/screenshot.png
adb pull /sdcard/screenshot.png ~/Desktop/

# 方法3: 使用模拟器直接截图（Cmd+S 或工具栏相机按钮）
```

#### 5.3 隐私政策（必需）

**示例隐私政策：**

创建文件 `privacy.html` 并上传到您的服务器，或使用免费托管：

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>山猫导游隐私政策</title>
</head>
<body>
<h1>山猫导游隐私政策</h1>
<p>更新日期：2025年1月8日</p>

<h2>1. 信息收集</h2>
<p>我们会收集以下信息：</p>
<ul>
  <li>位置信息：用于推荐周边景点和导航</li>
  <li>设备信息：用于优化应用性能</li>
  <li>使用数据：用于改进产品体验</li>
</ul>

<h2>2. 信息使用</h2>
<p>我们使用收集的信息来：</p>
<ul>
  <li>提供核心功能（定位、导航、推荐）</li>
  <li>改进产品和服务</li>
  <li>提供技术支持</li>
</ul>

<h2>3. 信息安全</h2>
<p>我们采取适当的安全措施保护您的个人信息。</p>

<h2>4. 第三方服务</h2>
<p>我们使用以下第三方服务：</p>
<ul>
  <li>高德地图：提供地图和定位服务</li>
  <li>百度语音：提供语音播报服务</li>
  <li>科大讯飞：提供语音识别服务</li>
</ul>

<h2>5. 联系我们</h2>
<p>如有疑问，请联系：kudduss@foxmail.com</p>
</body>
</html>
```

**免费托管服务：**

- GitHub Pages：https://pages.github.com/
- Gitee Pages：https://gitee.com/help/articles/4136
- Vercel：https://vercel.com/

---

### 第六步：应用软著登记（建议）

虽然不是必须，但软件著作权有以下好处：

- 部分应用商店（如应用宝）会优先审核
- 可以更好地保护知识产权
- 遇到版权纠纷时有法律依据

**申请流程：**

1. 访问：https://www.ccopyright.com.cn/
2. 准备材料：
    - 软件源代码（前后各连续 30 页，共60页）
    - 软件说明文档（用户手册或设计文档）
    - 申请表
3. 提交申请（可找代理机构，费用约 ¥300-800）
4. 等待审核（通常 2-3 个月）

---

## 🌍 Google Play 上架完整流程

### 前置条件

- 已生成并测试 AAB：`android/app/build/outputs/bundle/release/app-release.aab`
- `applicationId` 与包名一致：`com.lynxTravel`，且 `versionCode`/`versionName` 已递增
- 使用 App Signing（推荐）或自主管理签名，妥善保管 keystore
- 准备好商店素材：图标 512x512、Feature Graphic 1024x500、截图≥2、隐私政策 URL、联系邮箱

### 步骤 1：开通开发者账号

1. 前往 https://play.google.com/console/ 注册开发者账号  
2. 一次性注册费用：$25，完成身份与支付方式验证

### 步骤 2：在 Play Console 创建应用

1. 选择“创建应用”
2. 填写基础信息：
   ```
   默认语言：简体中文（zh-CN）
   应用名称：山猫导游
   应用/游戏：应用
   免费/付费：免费
   ```
3. 勾选相关政策与出口合规声明

### 步骤 3：启用 Play App Signing（推荐）

- 选择“使用 Google Play 应用签名”
- 使用当前 `app.jks` 作为上传密钥（Upload key），妥善保存 keystore 与密码
- 若后续更换上传密钥，可在“应用签名”中提交证书更换请求

### 步骤 4：创建“内部测试”发行

1. 发布管理 → 测试 → 内部测试 → 新建发行
2. 上传 `app-release.aab`
3. 填写发行说明（简要变更点）
4. 添加测试者（邮箱列表或 Google 组）并发送邀请
5. 提交审核并等待“预发布报告”（自动设备兼容性测试）

### 步骤 5：完成“应用内容”表单（必填）

- 数据安全（Data safety）：
  - 收集数据：精确位置、音频（麦克风）、设备标识（如用于功能/分析）
  - 目的：应用功能、分析；不用于广告个性化（如无广告）
  - 传输：加密传输；数据保留：仅为实现功能所需时长
  - 共享：不与第三方共享（除服务提供商，如地图/语音）
- 广告声明：如无广告，选择“否”
- 目标受众与内容：13 岁及以上（如覆盖未成年人，按实际填写）
- 内容分级：完成问卷获取分级结果
- 新闻应用声明：通常选择“否”
- 政府应用声明：通常选择“否”
- 隐私政策 URL：必须可访问且与应用功能一致

### 步骤 6：商店展示（Store listing）

- 图标：512×512 PNG（32-bit，含透明通道）
- Feature Graphic：1024×500 PNG/JPG（推荐必填）
- 截图（手机）：至少 2 张，建议 1080×1920 或 1242×2688，最多 8 张
- 简短描述：≤ 80 字符；完整描述：≤ 4000 字符
- 应用类型与分类；联系方式（邮箱必填，网站/电话可选）

### 步骤 7：国家/地区分发与设备

- 选择上架国家/地区（可先小范围）
- 检查设备与最低 Android 版本要求

### 步骤 8：发布到“生产”

- 将通过测试的构建“推广到生产”
- 建议使用分阶段发布（如 10% → 50% → 100%）以控制风险

### 审核与常见问题

- 审核时间：首次 3-7 天，更新通常更快
- 常见驳回：数据安全与实际采集不一致、崩溃/ANR、隐私政策不可访问或不匹配、敏感权限用途不清

---

## 🍎 iOS 打包上架完整流程

### 第一步：注册 Apple Developer（必需）

#### 1.1 注册 Apple ID

如果还没有 Apple ID：

1. 访问：https://appleid.apple.com/
2. 点击"创建您的 Apple ID"
3. 填写信息并验证邮箱

#### 1.2 加入 Apple Developer Program

**费用：** ¥688/年（个人）或 ¥688/年（公司）

**注册步骤：**

1. 访问：https://developer.apple.com/programs/
2. 点击 "Enroll" 注册
3. 使用 Apple ID 登录
4. 选择账户类型：
    - **Individual（个人）**：使用个人身份，审核快
    - **Organization（公司）**：需要邓白氏编码，审核慢
5. 填写信息并支付费用（支持支付宝）
6. 等待审核（个人通常 24 小时内，公司可能需要 1-2 周）

**注意事项：**

- 个人账号无法转为公司账号
- 建议用常用邮箱注册
- 每年需续费，否则应用会下架

---

### 第二步：配置证书和描述文件

#### 2.1 创建 App ID

1. 登录 [Apple Developer](https://developer.apple.com/account/)
2. 进入 "Certificates, Identifiers & Profiles"
3. 点击 "Identifiers" → "+" 创建
4. 选择 "App IDs" → "App"
5. 填写信息：
   ```
   Description: BellaTravel
   Bundle ID: com.lynxTravel（必须与项目一致，已注册则跳过）
   ```
6. 勾选需要的 Capabilities：
    - ✅ Location（位置服务）
    - ✅ Push Notifications（推送通知，可选）
7. 点击 "Continue" → "Register"

#### 2.2 创建证书

**创建 CSR 文件（首次需要）：**

1. 打开 Mac 的"钥匙串访问"（Keychain Access）
2. 菜单栏：钥匙串访问 → 证书助理 → 从证书颁发机构请求证书
3. 填写信息：
   ```
   用户电子邮件地址：你的邮箱
   常用名称：你的名字
   请求：存储到磁盘
   ```
4. 保存 `CertificateSigningRequest.certSigningRequest` 文件

**上传 CSR 创建证书：**

1. 回到 Apple Developer → Certificates → "+"
2. 选择证书类型：
    - **开发证书**：Apple Development
    - **发布证书**：Apple Distribution（用于上架）
3. 上传刚才保存的 CSR 文件
4. 下载生成的证书（.cer 文件）
5. 双击安装到钥匙串

#### 2.3 注册设备（开发测试用）

1. Devices → "+" 添加设备
2. 填写设备信息：
   ```
   Device Name: iPhone 测试机
   Device ID (UDID): <从 Xcode 获取>
   ```

**获取 UDID：**

- 连接 iPhone 到 Mac
- 打开 Xcode → Window → Devices and Simulators
- 选择设备，复制 "Identifier"

#### 2.4 创建 Provisioning Profile

**Development Profile（开发用）：**

1. Profiles → "+" 创建
2. 选择 "iOS App Development"
3. 选择 App ID: com.lynxTravel
4. 选择证书
5. 选择测试设备
6. 下载并双击安装

**Distribution Profile（上架用）：**

1. Profiles → "+" 创建
2. 选择 "App Store"
3. 选择 App ID: com.lynxTravel
4. 选择 Distribution 证书
5. 下载并双击安装

---

### 第三步：Xcode 配置签名

#### 3.1 打开项目

```bash
cd /Users/xiazhui/Desktop/code/bella/BellaTravel
open ios/BellaTravel.xcworkspace
```

⚠️ **必须打开 .xcworkspace 文件，不是 .xcodeproj！**

#### 3.2 配置签名

1. 在 Xcode 左侧选择项目 "BellaTravel"
2. 选择 Target "BellaTravel"
3. 切换到 "Signing & Capabilities" 标签
4. **Debug 配置：**
    - ✅ Automatically manage signing
    - Team: 选择你的开发团队
    - Provisioning Profile: 自动选择 Development Profile
5. **Release 配置：**
    - ✅ Automatically manage signing
    - Team: 选择你的开发团队
    - Provisioning Profile: 自动选择 Distribution Profile

#### 3.3 更新版本号

编辑 `ios/BellaTravel/Info.plist`：

```xml

<key>CFBundleShortVersionString</key>
<string>1.0.1</string>
<key>CFBundleVersion</key>
<string>2</string>
```

或在 Xcode 中：

1. 选择 Target → General
2. Version: 1.0.1
3. Build: 2

---

### 第四步：打包 IPA

#### 4.1 清理项目

```bash
cd ios
rm -rf build
rm -rf Pods
pod install
cd ..
```

#### 4.2 Archive 打包

**方法1：使用 Xcode（推荐）**

1. 在 Xcode 顶部设备选择器，选择 "Any iOS Device (arm64)"
2. 菜单栏：Product → Scheme → Edit Scheme
3. 左侧选择 "Run" → Build Configuration 改为 "Release"
4. 关闭 Scheme 编辑器
5. 菜单栏：Product → Clean Build Folder（Shift+Cmd+K）
6. 菜单栏：Product → Archive
7. 等待打包完成（首次约 5-15 分钟）

**方法2：使用命令行**

```bash
cd ios

# Archive
xcodebuild archive \
  -workspace BellaTravel.xcworkspace \
  -scheme BellaTravel \
  -configuration Release \
  -archivePath build/BellaTravel.xcarchive \
  -destination generic/platform=iOS \
  -allowProvisioningUpdates

# Export IPA
xcodebuild -exportArchive \
  -archivePath build/BellaTravel.xcarchive \
  -exportPath build \
  -exportOptionsPlist exportOptions.plist \
  -allowProvisioningUpdates

cd ..
```

**创建 `ios/exportOptions.plist`（如果不存在）：**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>method</key>
    <string>app-store</string>
    <key>teamID</key>
    <string>ANXFB32XYV</string>
    <key>uploadBitcode</key>
    <false/>
    <key>compileBitcode</key>
    <false/>
    <key>uploadSymbols</key>
    <true/>
    <key>signingStyle</key>
    <string>automatic</string>
  </dict>
</plist>
```

#### 4.3 iOS 打包常见问题详解

##### 问题 1：Archive 失败 - "No such module" 错误

**错误信息：**
```
No such module 'RNScreens'
No such module 'RCTTypeSafety'
```

**原因：** CocoaPods 依赖未正确安装

**解决方案：**

```bash
# 步骤1：清理 Pods
cd ios
rm -rf Pods
rm -rf build
rm Podfile.lock

# 步骤2：重新安装
pod deintegrate  # 如果安装了 cocoapods-deintegrate
pod install

# 步骤3：清理 Xcode 缓存
# Xcode 菜单 → Product → Clean Build Folder (Shift+Cmd+K)

# 步骤4：重新 Archive
cd ..
open ios/BellaTravel.xcworkspace
# Product → Archive
```

##### 问题 2：签名失败 - "Signing certificate is invalid"

**错误信息：**
```
The code signing identity "Apple Distribution: XXX" is no longer valid
```

**原因：** 证书过期或被撤销

**解决方案：**

```bash
# 步骤1：检查证书状态
# 打开 "钥匙串访问"
# 查看 "我的证书" → 找到 "Apple Distribution"
# 检查是否已过期或无效

# 步骤2：如果证书无效，需要重新生成
# 1. 打开 Apple Developer 网站
# 2. Certificates → 撤销旧证书
# 3. 重新创建 Distribution 证书
# 4. 下载并双击安装

# 步骤3：更新 Provisioning Profile
# 1. Apple Developer → Profiles
# 2. 编辑或重新创建 App Store Profile
# 3. 选择新证书
# 4. 下载并双击安装

# 步骤4：在 Xcode 中刷新
# Xcode → Preferences → Accounts
# 选择账号 → Download Manual Profiles

# 步骤5：重新配置签名
# Project → Target → Signing & Capabilities
# 取消勾选 "Automatically manage signing"
# 重新勾选
```

##### 问题 3：Build 失败 - "Command PhaseScriptExecution failed"

**错误信息：**
```
Command PhaseScriptExecution failed with a nonzero exit code
```

**可能原因和解决方案：**

**原因 1：Node 脚本执行失败**

```bash
# 清理 Metro 缓存
yarn clean:cache

# 或手动清理
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*

# 重新 Build
```

**原因 2：CocoaPods 脚本失败**

```bash
cd ios
pod install

# 如果还有问题，尝试更新 Pod
pod update

# 或删除并重装
rm -rf Pods Podfile.lock
pod install
```

**原因 3：权限问题**

```bash
# 给脚本添加执行权限
chmod +x ios/Pods/Target\ Support\ Files/Pods-BellaTravel/Pods-BellaTravel-resources.sh
```

##### 问题 4：上传 App Store 失败 - "Invalid bundle"

**错误信息：**
```
ERROR ITMS-90057: "The app icon set named 'AppIcon' did not have any applicable content."
```

**原因：** App Icon 缺失或尺寸不正确

**解决方案：**

```bash
# 步骤1：检查图标
open ios/BellaTravel.xcworkspace
# 左侧导航 → Images.xcassets → AppIcon

# 步骤2：确保所有尺寸都有图标
# - 20pt @2x, @3x
# - 29pt @2x, @3x
# - 40pt @2x, @3x
# - 60pt @2x, @3x
# - 1024pt @1x (App Store)

# 步骤3：使用 Icon Kitchen 重新生成
# https://icon.kitchen/

# 步骤4：清理并重新打包
# Product → Clean Build Folder
# Product → Archive
```

##### 问题 5：真机调试失败 - "untrusted developer"

**错误信息：** 设备显示"未受信任的企业级开发者"

**解决方案：**

```bash
# 在 iPhone 上操作：
# 设置 → 通用 → VPN与设备管理 → 开发者App
# 点击你的开发者账号 → 信任
```

##### 问题 6：定位不工作 - 权限未授权

**原因：** Info.plist 缺少权限描述

**解决方案：**

编辑 `ios/BellaTravel/Info.plist`，确保包含：

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>用于为您推荐周边景点并提供导航服务</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>用于在行走过程中持续定位，自动播报附近景点</string>

<key>NSMicrophoneUsageDescription</key>
<string>用于语音识别，实现免手动操作的语音导览</string>
```

##### 问题 7：Archive 找不到 - "No archives"

**原因：** 选择的设备不正确

**解决方案：**

```bash
# 步骤1：确保选择 "Any iOS Device (arm64)"
# Xcode 顶部设备选择器 → 选择 "Any iOS Device"

# 步骤2：不要选择模拟器
# 模拟器无法创建 Archive

# 步骤3：确保 Scheme 是 Release
# Product → Scheme → Edit Scheme
# Run → Build Configuration → Release

# 步骤4：重新 Archive
# Product → Archive
```

##### 问题 8：高德地图不显示

**原因：** iOS Key 未配置或配置错误

**解决方案：**

```bash
# 步骤1：检查 .env 文件
cat .env | grep AMAP_IOS_KEY

# 步骤2：检查高德地图控制台
# 1. 登录 https://console.amap.com/
# 2. 找到 iOS Key
# 3. 确认 Bundle ID 是 com.lynxTravel
# 4. 确认 Key 已启用

# 步骤3：重新编译
cd ios
rm -rf build
cd ..
yarn ios
```

##### 问题 9：上传太慢或上传失败

**解决方案：**

**方法 1：使用国内网络优化**

```bash
# 如果在中国大陆，可能需要配置代理
# 或使用 VPN 连接

# 也可以尝试：
# - 下载 Transporter App（Mac App Store）
# - 使用 Transporter 上传 IPA（支持断点续传）
```

**方法 2：减小 IPA 体积**

检查 `ios/BellaTravel.xcodeproj/project.pbxproj`：

```
ENABLE_BITCODE = NO;  // 关闭 Bitcode 可以减小体积
```

##### 问题 10：App Store 审核被拒 - 2.1 Performance: App Completeness

**拒绝原因：** 应用在审核时崩溃或无法使用

**解决方案：**

```bash
# 步骤1：使用 TestFlight 内测
# 1. 上传到 App Store Connect
# 2. 创建 TestFlight 测试组
# 3. 添加内部测试员
# 4. 充分测试所有功能

# 步骤2：检查崩溃日志
# Xcode → Window → Organizer → Crashes
# 修复所有崩溃问题

# 步骤3：确保 API Key 有效
# - 检查 .env 文件中的所有 Key
# - 确保高德/百度/讯飞的 Key 都正确配置
# - 确保 API 配额充足

# 步骤4：提供测试账号（如果需要）
# 在提交审核时，提供可用的测试账号

# 步骤5：添加演示视频
# 录制应用使用视频，展示核心功能
```

##### 问题 11：App Store 审核被拒 - 5.1.1 Data Collection and Storage

**拒绝原因：** 隐私政策不完整或不可访问

**解决方案：**

```bash
# 步骤1：确保隐私政策 URL 可访问
# - 在浏览器中测试 URL
# - 确保服务器稳定
# - 确保 HTTPS 证书有效

# 步骤2：隐私政策必须包含
# - 收集哪些数据（位置、音频、设备ID）
# - 数据如何使用（导航、语音识别、分析）
# - 是否与第三方共享
# - 如何联系开发者

# 步骤3：在应用内提供隐私政策链接
# 通常在"设置"或"关于"页面

# 步骤4：重新提交
# 在 Resolution Center 回复审核团队
```

##### 问题 12：构建号（Build Number）冲突

**错误信息：**
```
An app bundle with version number 1.0.1 and build number 1 has already been uploaded.
```

**解决方案：**

```bash
# 步骤1：增加 Build Number
# 编辑 ios/BellaTravel/Info.plist
# CFBundleVersion: 1 → 2

# 或在 Xcode 中：
# Target → General → Identity → Build: 1 → 2

# 步骤2：重新 Archive 和上传
# Product → Clean Build Folder
# Product → Archive
# Distribute App
```

##### 完整 iOS 打包验证清单

```bash
# ===== iOS 打包完整验证流程 =====

# 1. 环境检查
xcode-select --install  # 确保 Xcode 命令行工具已安装
pod --version           # 确保 CocoaPods 已安装

# 2. 清理环境
cd /Users/xiazhui/Desktop/code/bella/BellaTravel
rm -rf node_modules
yarn install

cd ios
rm -rf Pods build
rm Podfile.lock
pod install
cd ..

# 3. 更新版本号
# 编辑 ios/BellaTravel/Info.plist
# CFBundleShortVersionString: 1.0.1
# CFBundleVersion: 2

# 4. 验证高德地图 Key
cat .env | grep AMAP_IOS_KEY

# 5. 验证权限描述
grep -A 1 "NSLocationWhenInUseUsageDescription" ios/BellaTravel/Info.plist
grep -A 1 "NSMicrophoneUsageDescription" ios/BellaTravel/Info.plist

# 6. 打开 Xcode
open ios/BellaTravel.xcworkspace

# 7. 在 Xcode 中检查
# - 顶部选择 "Any iOS Device (arm64)"
# - Product → Scheme → 确认是 BellaTravel
# - Signing & Capabilities → 确认签名正确

# 8. 清理构建
# Product → Clean Build Folder (Shift+Cmd+K)

# 9. Archive
# Product → Archive
# 等待完成（首次约 5-15 分钟）

# 10. 验证 Archive
# Archive 成功后，Organizer 会自动打开
# 检查版本号和构建号是否正确

# 11. 上传到 App Store Connect
# Distribute App → App Store Connect → Upload
# 选择自动签名
# 等待上传完成

# 12. 等待处理
# 上传后等待 5-30 分钟
# App Store Connect → 我的 App → 活动
# 查看处理状态

# 13. 填写应用信息并提交审核
# - 添加截图（至少 3 张）
# - 填写描述和关键词
# - 提供隐私政策 URL
# - 提交以供审核

echo "✅ iOS 打包验证完成！"
```

##### iOS 真机测试步骤

```bash
# 1. 连接 iPhone 到 Mac
# 使用 Lightning/USB-C 数据线连接

# 2. 信任设备
# iPhone 弹出 "要信任此电脑吗？" → 点击 "信任"
# 输入 iPhone 密码

# 3. 在 Xcode 中选择设备
open ios/BellaTravel.xcworkspace
# 顶部设备选择器 → 选择你的 iPhone

# 4. 运行应用
# Product → Run (Cmd+R)

# 5. 如果提示签名问题
# Project → Target → Signing & Capabilities
# Team: 选择你的开发团队
# 勾选 "Automatically manage signing"

# 6. 如果提示 "untrusted developer"
# iPhone: 设置 → 通用 → VPN与设备管理 → 信任开发者

# 7. 测试核心功能
# - 启动应用（无崩溃）
# - 授权位置和麦克风权限
# - 地图正常加载和定位
# - 语音识别和播报功能
# - 景点推荐和详情页
```

---

### 第五步：上传到 App Store Connect

#### 5.1 创建应用

1. 登录 [App Store Connect](https://appstoreconnect.apple.com/)
2. 点击 "我的 App" → "+" → "新建 App"
3. 填写信息：
   ```
   平台：iOS
   名称：山猫导游
   主要语言：简体中文
   Bundle ID：com.lynxTravel
   SKU：bellatravel001（唯一标识，自定义）
   用户访问权限：完全访问权限
   ```
4. 点击 "创建"

#### 5.2 上传构建版本

**方法1：使用 Xcode Organizer（推荐）**

1. Archive 完成后，Xcode 会自动打开 Organizer
2. 选择刚才的 Archive
3. 点击 "Distribute App"
4. 选择 "App Store Connect"
5. 选择 "Upload"
6. 保持默认选项，点击 "Next"
7. 选择签名方式：Automatically manage signing
8. 点击 "Upload"
9. 等待上传完成（取决于网速，通常 5-15 分钟）

**方法2：使用 Transporter（备选）**

1. 从 Mac App Store 下载 "Transporter"
2. 打开 Transporter 并登录 Apple ID
3. 将 IPA 文件拖入窗口
4. 点击 "交付"

上传完成后，需要等待 5-30 分钟处理。

#### 5.3 填写应用信息

**App 信息：**

1. App Store Connect → 我的 App → 山猫导游
2. "App 信息" 标签页：
   ```
   名称：山猫导游
   副标题：智能语音导览旅游助手（30字以内）
   类别：
     主要类别：旅游
     次要类别：导航

```

**定价和销售范围：**
1. "定价和销售范围" 标签页
2. 价格：免费
3. 销售范围：中国大陆（可选其他国家/地区）

**App 隐私：**
1. "App 隐私" 标签页
2. 点击 "开始"，填写隐私问卷：
   ```

是否收集位置数据？是

- 精确位置
- 用途：App 功能、分析

是否收集音频数据？是

- 用途：App 功能（语音识别）

是否收集设备 ID？是

- 用途：App 功能、分析

   ```

#### 5.4 准备提交资料

**1. App 截图（必需）**

**尺寸要求（至少提供一种）：**

- iPhone 6.7"（iPhone 15 Pro Max）: 1290x2796
- iPhone 6.5"（iPhone 11 Pro Max）: 1242x2688
- iPhone 5.5"（iPhone 8 Plus）: 1242x2208

至少 3 张，最多 10 张

**如何截图：**

```bash
# 使用 iOS 模拟器
# 打开 Xcode → 选择对应模拟器 → 运行应用
# Cmd+S 保存截图（自动匹配尺寸）

# 推荐设备：
# iPhone 15 Pro Max（1290x2796）
# iPhone 11 Pro Max（1242x2688）
```

**2. App 预览视频（可选）**

- 时长：15-30 秒
- 格式：M4V、MP4、MOV
- 分辨率：与截图尺寸一致

**3. 描述文本**

**推广文本（170字以内）：**

```
探索精彩，从这里开始！山猫导游为您提供智能语音导览服务，自动识别景点位置，智能推荐周边美食与文化体验。解放双手，边走边听，让每次旅行都充满惊喜！
```

**描述（4000字以内）：**

```
【山猫导游 - 您的智能旅游助手】

山猫导游是一款专为旅游爱好者打造的智能导览应用，集成了语音识别、智能播报、地图导航等功能，让您的每一次旅行都更加精彩。

✨ 核心功能

• 智能定位
  - 采用高德地图 SDK，定位精准，误差小于 50 米
  - 自动获取当前位置，实时推荐周边景点
  - 支持室内外无缝切换

• 语音导览
  - AI 语音识别技术，说话即可控制
  - 自然流畅的语音播报，如同真人导游
  - 支持多种方言识别
  - 解放双手，边走边听

• 景点推荐
  - 基于位置的智能推荐算法
  - 覆盖全国数千个景区景点
  - 详细的景点介绍和历史文化背景
  - 实时更新，持续扩充

• 美食文化
  - 挖掘地道特色美食
  - 介绍当地文化习俗
  - 推荐网红打卡地
  - 品味地方特色

• 地图导航
  - 高德地图精准导航
  - 实时路况提示
  - 多种出行方式（步行、公交、自驾）
  - 轻松到达目的地

• 自动播报
  - 到达景区自动识别
  - 自动开启讲解
  - 沉浸式游览体验
  - 无需手动操作

🎯 产品特色

• 智能化：AI 语音识别和播报，交互自然流畅
• 专业性：专业团队编写景点讲解词，内容权威准确
• 便捷性：操作简单，老少皆宜，一键即用
• 全面性：覆盖景点、美食、文化等多个维度
• 免费使用：核心功能完全免费，无广告打扰

🌟 适用场景

• 自由行游客 - 随时随地获取景点信息，规划最佳路线
• 跟团旅游 - 补充了解更多文化知识，丰富旅行体验
• 本地居民 - 发现身边被忽略的美景，周末出游好帮手
• 文化爱好者 - 深度了解地域文化，探索历史故事
• 摄影爱好者 - 发现最佳拍摄地点，记录美好瞬间

💡 使用技巧

1. 开启位置权限，获得最佳推荐效果
2. 连接耳机使用，更好的语音体验
3. 提前下载离线地图，节省流量
4. 收藏喜欢的景点，方便下次查找

让山猫导游陪伴您的每一次旅行，发现更多精彩！

📞 联系我们

遇到问题或有建议？欢迎联系我们：
• 邮箱：kudduss@foxmail.com
• QQ：3249696828

我们会持续改进产品，为您提供更好的服务！
```

**关键词（100字符以内，用逗号分隔）：**

```
旅游,导游,语音导览,景点,地图,导航,美食,文化,智能,推荐
```

**支持 URL：**

```
https://你的网站.com/support
```

**隐私政策 URL（必需）：**

```
https://你的网站.com/privacy
```

#### 5.5 提交审核

1. 回到版本页面
2. 点击 "+" 添加构建版本
3. 选择刚上传的构建版本
4. 填写"此版本的新增内容"：
   ```
   v1.0.1 更新内容：
   • 优化语音播报响应速度
   • 修复定位偶尔不准确的问题
   • 提升应用稳定性和性能
   • 优化用户界面体验
   ```
5. 填写审核信息：
    - 联系信息（姓名、电话、邮箱）
    - 演示账号（如果需要登录）
    - 备注（可选）
6. 勾选"我已阅读并同意 Apple 开发者协议"
7. 点击 "提交以供审核"

---

### 第六步：等待审核

**审核时间：**

- 首次提交：通常 1-7 天
- 更新版本：通常 1-3 天
- 被拒后重新提交：通常 1-2 天

**审核状态：**

- **等待审核**：已提交，排队中
- **正在审核**：审核团队正在检查
- **被拒绝**：不符合要求，查看拒绝原因并修改
- **准备好销售**：审核通过，应用已上线！

**常见拒绝原因和解决方案：**

1. **崩溃或闪退**
    - 充分测试所有功能
    - 使用 TestFlight 内测
    - 检查崩溃日志

2. **缺少隐私政策**
    - 必须提供隐私政策 URL
    - 隐私政策必须可访问

3. **未正确处理权限**
    - Info.plist 中必须说明权限用途
    - 权限申请时机要合理

4. **界面问题**
    - 适配所有 iPhone 尺寸
    - 不能有明显 UI 错误
    - 启动屏不能有"loading"等字样

5. **功能不完整**
    - 所有展示的功能必须可用
    - 不能有"即将推出"的功能

**被拒后的处理：**

1. 查看拒绝原因（邮件和 App Store Connect）
2. 修改代码或资源
3. 重新打包上传
4. 在"解决方案中心"回复审核团队
5. 重新提交

---

### 第七步：应用上线后维护

**监控数据：**

- App Store Connect → 分析
- 下载量、活跃用户、崩溃率等

**版本更新：**

1. 更新版本号（versionCode +1）
2. 重新打包上传
3. 填写更新说明
4. 提交审核

**用户反馈：**

- 及时回复用户评价
- 收集改进建议
- 修复用户反馈的 Bug

---

## 🧾 上架资料清单

### 账号与资质

- Apple Developer Program（个人或公司）与 App Store Connect 访问权限
- Google Play Console 开发者账号（$25 一次性）
- 国内应用商店账号（华为/应用宝/小米/OPPO/vivo 等，按需）
- 公司信息与对外联系邮箱、客服电话（可选）

### 技术与签名

- 包名（Android）：`com.lynxTravel`；Bundle ID（iOS）：`com.lynxTravel`
- 版本号：Android `versionCode`/`versionName`，iOS `CFBundleVersion`/`CFBundleShortVersionString`
- 签名：Android `app.jks`（含别名与口令）；iOS 证书与 Provisioning Profiles
- 指纹：MD5 / SHA1 / SHA256（国内商店常要求）
- 第三方 Key：高德/百度 TTS/讯飞 ASR 等
- 隐私政策 URL、支持/联系页面 URL

### 商店素材与规范

- App 图标：
  - iOS：1024×1024 PNG（无透明）
  - Android（Play）：512×512 PNG（32-bit，含透明）
- Feature Graphic（Play）：1024×500 PNG/JPG（推荐）
- 截图：
  - iOS：6.7"、5.5" 至少各 3 张，最多 10 张
  - Android：手机至少 2 张，最多 8 张，建议 1080×1920 或 1242×2688
- 文案：名称、副标题/简短描述、完整描述、关键词（iOS）、版本更新说明
- 品牌：应用 Logo 源文件（SVG/AI/1024 PNG）、品牌主色、启动图（如需）
- 可选：预览视频（15-30 秒，分辨率与截图一致）

### 审核账号与说明（模板）

```
测试账号：test_user / ******（或免登录流程说明）
测试设备：iPhone 14 / Pixel 7（任选）
复现路径：
1. 打开 App → 授权位置与麦克风
2. 首页点击“开始导览” → 自动定位并播报
3. 进入“景点详情” → 播放讲解 → 返回主页
其他说明：应用仅使用位置与麦克风实现导览功能，无广告与第三方跟踪
```

---

## 📋 打包前检查清单

### 通用检查

- [ ] 版本号已更新（package.json、build.gradle、Info.plist）
- [ ] 移除所有 console.log 和调试代码
- [ ] 测试所有核心功能（定位、语音、导航）
- [ ] 检查权限描述文案
- [ ] 准备好应用截图（至少 3 张）
- [ ] 准备好应用图标（512x512 px）
- [ ] 准备好隐私政策页面
- [ ] 准备好应用描述文字

### Android 专项检查

- [ ] 签名文件（app.jks）已备份
- [ ] 签名配置正确（gradle.properties）
- [ ] 获取了 MD5、SHA1、SHA256
- [ ] Proguard 混淆规则正确
- [ ] 测试 Release 版本无崩溃
- [ ] APK 大小合理（< 100MB）
- [ ] 高德地图 Android Key 已配置发布版 SHA1

### iOS 专项检查

- [ ] Apple Developer 账号已激活
- [ ] 证书和 Provisioning Profile 配置正确
- [ ] App Icon 所有尺寸已配置
- [ ] Launch Screen 正常显示
- [ ] Info.plist 权限说明完整
- [ ] 支持的设备和 iOS 版本正确
- [ ] Archive 可以成功生成
- [ ] 测试 Release 配置无问题

---

## 🔐 权限与合规文案模板

### iOS（Info.plist）

将以下键与文案添加至 `ios/BellaTravel/Info.plist`：

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>用于为您推荐周边景点并提供导航服务</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>用于在行走过程中持续定位，自动播报附近景点</string>
<key>NSMicrophoneUsageDescription</key>
<string>用于语音识别，实现免手动操作的语音导览</string>
```

- 出口合规：仅使用标准 HTTPS（ATS），上架问答选择“使用加密，是，但符合豁免”
- ATT（跟踪透明度）：若无跨应用跟踪，不需要展示 ATT 弹窗

### Android（Manifest 与运行时）

在 `android/app/src/main/AndroidManifest.xml` 确保：

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

运行时请求权限时的提示文案（示例）：

- 位置：用于为您推荐周边景点并提供导航
- 麦克风：用于语音识别，实现语音导览

### 数据安全与隐私（表单参考）

- 收集数据：精确位置、音频（麦克风）、设备标识（如用于稳定性/分析）
- 目的：应用功能与基础分析；不用于个性化广告
- 处理：加密传输，保留时间仅限实现功能所需
- 共享：不与第三方共享，除必要服务提供商（地图/语音）
- 用户控制：可在系统设置中关闭权限，或通过应用内设置停止采集相关功能

---

## 🚀 一键打包命令汇总

### Android

```bash
# 完整打包流程（复制粘贴即可）
cd /Users/xiazhui/Desktop/code/bella/BellaTravel && \
yarn clean:cache && \
cd android && \
./gradlew clean && \
./gradlew assembleRelease && \
cd .. && \
cp android/app/build/outputs/apk/release/app-release.apk ~/Desktop/山猫导游-v1.0.1.apk && \
echo "✅ APK 已生成到桌面！" && \
ls -lh ~/Desktop/山猫导游-v1.0.1.apk
```

### iOS

```bash
# 清理并安装依赖
cd /Users/xiazhui/Desktop/code/bella/BellaTravel && \
cd ios && \
rm -rf build Pods && \
pod install && \
cd ..

# 然后使用 Xcode Archive（建议）
open ios/BellaTravel.xcworkspace
# Product → Archive
```

---

## 📞 技术支持

如遇到问题，欢迎联系：

- 📧 邮箱：kudduss@foxmail.com
- 💬 QQ：3249696828
- 🌐 GitHub：提交 Issue

---

**✅ 祝您打包顺利，应用上架成功！**

## 🔧 开发指南

### 项目结构

```
BellaTravel/
├── src/
│   ├── api/              # API 请求模块
│   ├── components/       # 通用组件
│   │   ├── AutoVoiceGuide.js
│   │   ├── VoiceGuideModalBaidu.js
│   │   ├── SplashScreen.js
│   │   └── HomeContent.js
│   ├── config/           # 配置文件
│   ├── context/          # Context
│   ├── hooks/            # 自定义 Hooks
│   ├── screens/          # 页面组件
│   ├── services/         # 服务模块
│   │   ├── voiceService.js
│   │   ├── baiduTtsService.js
│   │   └── iflytekRealtimeAsrService.js
│   └── utils/            # 工具函数
│       ├── locationUtils.js
│       └── voiceKeywords.js
├── ios/                  # iOS 原生代码
├── android/              # Android 原生代码
├── .env                  # 环境变量（不提交）
├── .env.example          # 环境变量模板
└── README.md             # 项目文档
```

### 后台音频播放与通知栏控制

应用已集成完整的后台播放功能，像音乐软件一样支持后台播放和通知栏控制。

#### 核心特性

- ✅ **后台播放** - 退出 App 后音频继续播放
- ✅ **通知栏控制** - Android 通知栏显示播放信息和控制按钮
- ✅ **控制中心** - iOS 控制中心和锁屏界面控制
- ✅ **智能恢复** - 返回 App 时从上次位置继续播放
- ✅ **完整元数据** - 显示景区名称、音频标题、封面图、播放进度

#### 通知栏控制按钮

**Android 通知栏 & iOS 控制中心：**

1. **播放/暂停** - 切换播放状态
2. **上一段/下一段** - 切换音频内容
3. **快退 15 秒** - 向后跳转 15 秒
4. **快进 15 秒** - 向前跳转 15 秒
5. **关闭** - 停止播放并清除通知

#### 技术实现

**使用的库：**

- `react-native-track-player` - 专业的音频播放库，支持后台播放

**核心服务：**

```javascript
// src/services/trackPlayerService.js - TrackPlayer 封装
// src/services/playbackService.js - 后台播放服务
// src/context/AudioPlayerContext.js - 全局状态管理
```

**配置文件：**

- iOS: `ios/BellaTravel/Info.plist` - UIBackgroundModes
- Android: `android/app/src/main/AndroidManifest.xml` - FOREGROUND_SERVICE

#### 首次安装步骤

如果是首次克隆项目，需要重新安装原生依赖：

```bash
# 1. 安装 npm 依赖
npm install
# 或
yarn install

# 2. iOS 安装（如果开发 iOS）
cd ios
pod install
cd ..

# 3. 清理缓存并运行
npm run start:hot

# 在另一个终端
npm run android  # Android
npm run ios      # iOS
```

#### 测试后台播放

**Android：**

1. 打开 App，播放音频
2. 按 Home 键返回桌面 → 音频继续播放
3. 下拉通知栏 → 看到播放信息和控制按钮
4. 点击通知栏按钮测试控制功能

**iOS：**

1. 打开 App，播放音频
2. 按 Home 键返回桌面 → 音频继续播放
3. 上滑控制中心 → 看到播放信息
4. 锁定屏幕 → 锁屏界面显示播放控制
5. 测试 AirPods 等蓝牙耳机控制

#### 常见问题

**Q: 通知栏不显示怎么办？**

**Android:**

- 检查应用通知权限是否开启
- 某些手机需要在设置中允许"后台弹出通知"

**iOS:**

- 确保在真机上测试（模拟器不完全支持）
- 检查系统设置是否允许该 App 的通知

**Q: 音频在后台停止了？**

- Android: 检查电池优化设置，将 App 加入白名单
- iOS: 确保 Info.plist 中已配置 UIBackgroundModes

**Q: 快进/快退按钮不显示？**

这是正常的，快进/快退功能通过长按播放器中的按钮或通知栏的专用按钮触发。

---

### 智能语音导览

#### 自动语音导览流程

1. 进入首页：定位完成后自动播报当前景区
2. 语音询问："您好，您现在的位置是XX，是否需要为您讲解？"
3. 语音回答：说"需要"或"不需要"
4. 自动跳转：识别到"需要"后自动跳转到景区详情页

#### 百度TTS实时音频生成功能

**功能简介：**

在景区/景点详情页面中，如果后端没有返回音频文件，会自动使用百度TTS（Text-to-Speech）实时生成语音音频，确保用户总能听到语音讲解。

**工作原理：**

```
1. 用户进入景区详情页
   ↓
2. 从后端获取音频数据
   ↓
3. 判断：是否有音频URL？
   ├─ 有 → 直接使用音频URL播放
   └─ 无 → 触发TTS生成流程
      ↓
4. TTS生成流程：
   a. 显示"正在生成语音..."提示
   b. 调用百度TTS API合成语音
   c. 保存到本地缓存（.mp3格式）
   d. 设置本地音频路径为播放源
   e. 隐藏生成提示
   f. 如开启自动播放则开始播放
```

**技术实现：**

```javascript
// 核心代码：src/screens/AttractionDetailScreen.js
const generateTtsAudio = useCallback(async (text) => {
  // 1. 调用百度TTS API合成语音
  const audioData = await baiduTtsService.synthesize(text, {
    voiceName: '4',  // 情感女声
    speed: '5',      // 中等语速
    volume: '9',     // 较高音量
    pitch: '5',      // 中等音调
  });

  // 2. 将ArrayBuffer转换为Base64并保存到本地
  const audioPath = `${RNFS.CachesDirectoryPath}/tts_${itemId}_${Date.now()}.mp3`;
  await RNFS.writeFile(audioPath, base64Audio, 'base64');

  // 3. 设置本地音频文件路径为播放源
  setAudioUrl(localAudioUrl);
}, [itemId]);
```

**平台兼容性：**

- ✅ **iOS** - 完全支持，使用绝对路径
- ✅ **Android** - 完全支持，使用 `file://` 协议前缀

**UI交互：**

- TTS生成期间，播放按钮显示沙漏图标且不可点击
- 播放器下方显示"正在生成语音..."提示
- 生成完成后提示消失，自动开始播放

**依赖配置：**

确保 `.env` 文件中配置了百度API密钥：
```bash
BAIDU_API_KEY=你的百度API_Key
BAIDU_SECRET_KEY=你的百度Secret_Key
```

**优化建议：**

1. **缓存机制**：避免同一文本重复生成
2. **文本限制**：百度TTS单次请求最套2048字符，超长文本需截断
3. **清理缓存**：定期清理过期TTS音频文件节省存储空间

---

#### 在代码中使用语音服务

```javascript
import voiceService from './src/services/voiceService';

// 语音播报
await voiceService.speak('您好，欢迎使用语音服务');

// 语音识别
await voiceService.startListening({
  onStart: () => console.log('开始录音'),
  onResults: (text, { isFinal }) => {
    if (isFinal) {
      console.log('识别结果:', text);
    }
  },
  onError: (error) => console.error('识别错误:', error)
});

// 停止识别
await voiceService.stopListening();
```

### 高德定位实现

#### 技术方案

使用 **高德原生定位 SDK**（`react-native-amap-geolocation`）：

```
高德原生SDK → 直接返回 GCJ-02 坐标 → 地图显示/API调用
                    ↓
              包含完整地址信息
```

**效果：**

- ✅ 定位精度：< 50 米（室外开阔环境）
- ✅ 坐标系：直接返回 GCJ-02，无需转换
- ✅ 速度快：原生定位，1-3秒完成
- ✅ 包含地址：自动返回省市区街道等信息

#### 三级定位降级策略

```
1️⃣ 高德原生定位（推荐）
   ↓ 失败
2️⃣ GPS定位 + 坐标转换
   ↓ 失败  
3️⃣ 默认位置（乌鲁木齐国际大巴扎）
```

**定位成功率：** 综合 > 99%

#### 核心代码

定位核心逻辑在 `src/utils/locationUtils.js`：

```javascript
import { init, Geolocation as AMapGeolocation } from 'react-native-amap-geolocation';
import { AMAP_IOS_KEY, AMAP_ANDROID_KEY } from '@env';

// 1. 初始化高德 SDK
await init({
  ios: AMAP_IOS_KEY,
  android: AMAP_ANDROID_KEY
});

// 2. 获取定位（GCJ-02 坐标）
AMapGeolocation.getCurrentPosition((position) => {
  const { coords, location } = position;

  // 经纬度（GCJ-02，可直接用于 API 调用）
  const latitude = coords.latitude;
  const longitude = coords.longitude;

  // 地址信息（高德自动解析）
  const city = location.city;
  const district = location.district;
  const address = location.address;
});
```

#### 坐标系说明

中国常用的三种坐标系：

1. **WGS84**（GPS 原始坐标）
    - 国际标准，GPS 设备直接输出
    - 在中国不能直接使用（偏差 50-500 米）

2. **GCJ-02**（国测局坐标/火星坐标）✅ **本项目使用**
    - 中国强制标准
    - 高德地图、腾讯地图、Google 中国地图使用

3. **BD-09**（百度坐标）
    - 百度地图私有坐标系
    - 在 GCJ-02 基础上再次加密

### 启动屏配置

应用已配置专业的启动页面，启动时无白屏闪烁！

**Android 启动屏：**

- 白色背景 + 原生文字（山猫导游欢迎你）
- 启动瞬间显示，无白屏闪烁
- 自动过渡到 React Native 自定义启动屏

**iOS 启动屏：**

- 白色背景 + 原生文字（山猫导游欢迎你）
- 居中布局，适配所有 iPhone 设备
- 自动过渡到 React Native 自定义启动屏

**配置文件：**

- Android: `android/app/src/main/res/layout/splash_screen.xml`
- iOS: `ios/BellaTravel/SplashScreen.storyboard`

### 安全注意事项

**❌ 不要提交 .env 到 Git**

`.env` 文件已被 `.gitignore` 排除，**切勿提交到代码仓库！**

**✅ 使用 .env.example**

`.env.example` 是公开的模板文件，可以提交到 Git：

- ✅ 包含所有配置项的名称
- ✅ 包含配置说明
- ❌ 不包含真实的密钥

**🔑 密钥管理建议**

1. **开发环境**：每个开发者使用自己的 `.env` 文件
2. **生产环境**：使用 CI/CD 工具注入环境变量
3. **团队协作**：通过安全渠道（如密码管理器）分享密钥

---

## 📝 更新日志

### v1.0.1 (2025-01-08)

#### 🎯 生产环境优化

**代码清理**

- ✅ 删除所有调试用 console.log（52处）
- ✅ 删除测试文件和目录
- ✅ 删除无用的 Ruby 相关文件

**依赖优化**

- ✅ 移除 4 个未使用的依赖包
    - react-native-nitro-modules
    - react-native-iphone-x-helper
    - react-native-navigation-bar-color
    - react-native-status-bar-height
- ✅ 减少 node_modules 体积

**性能优化**

- ✅ 播报弹窗响应速度优化（从30秒降至接口返回后150ms内）
- ✅ 修复 NativeEventEmitter 警告
- ✅ 优化定位和数据加载流程

**版本更新**

- ✅ 版本号更新为 1.0.1 (Build 2)
- ✅ 代码库已清理，可直接打包发布

#### 📊 优化效果

- **代码体积**：减少约 60+ 行调试代码
- **依赖体积**：移除 4 个未使用的包
- **响应速度**：播报弹窗速度提升 95%+
- **打包就绪**：代码干净，符合生产环境标准

---

### v3.0.0 (2024-10-20)

#### ✨ 新功能

**打包优化**

- ✅ 启用 Android APK 代码混淆（minifyEnabled）
- ✅ 启用资源压缩（shrinkResources）
- ✅ 启用代码优化（proguard-android-optimize.txt）
- ✅ 自动移除调试日志（Log.d/v/i）
- ✅ 配置完整的 Proguard 保护规则
- 🎯 APK 体积减少 30-50%

**定位优化**

- ✅ 定位失败时自动使用乌鲁木齐国际大巴扎作为默认位置
- ✅ 确保语音播报在所有情况下都能正常启动
- ✅ 优化定位权限被拒绝时的用户体验

**UI 优化**

- ✅ 优化地图定位权限提示横幅样式
- ✅ 横幅点击直接弹出系统定位权限弹窗
- ✅ 允许定位后横幅自动消失

#### 📚 文档优化

**合并文档**

- ✅ 将所有独立 .md 文件合并到 README.md
- ✅ 删除冗余的启动屏配置教程
- ✅ 删除冗余的应用图标替换教程
- ✅ 精简 iOS 打包流程说明
- ✅ 精简常见问题解决方案

**新增内容**

- ✅ 添加文档目录导航
- ✅ 添加打包优化详细说明
- ✅ 添加应用市场上架信息
- ✅ 重新组织相关链接
- ✅ 更新团队信息

#### 📊 优化效果

**代码优化**

- 移除所有调试日志
- 代码混淆保护
- 资源自动压缩

**文档优化**

- 所有文档统一在 README.md 中
- 内容更加精简和结构化
- 添加目录导航，查找更方便

**打包优化**

- APK 体积减少 30-50%
- 代码安全性提升
- 保留崩溃堆栈还原能力

#### ⚠️ 重要提示

1. **首次优化打包**需要 5-10 分钟
2. **务必充分测试**所有功能
3. **保存 mapping.txt** 文件用于崩溃分析
4. **备份签名密钥**文件

---

### v1.0.0 (2024-10 初始版本)

#### 核心功能

- 🗺️ 实时定位与景点推荐
- 🎤 智能语音导览（语音识别 + 语音播报）
- 🍜 美食文化介绍
- 🏞️ 景区详细信息
- 📍 地图导航
- 🚀 自定义启动屏
- 🔐 完整的权限管理

---

## ❓ 常见问题

### 环境问题

**Q1: 环境变量读取不到**

**症状**：提示 `IFLYTEK_API_SECRET 未配置` 或找不到 `@env` 模块

**解决**：

```bash
# 1. 确认 .env 文件存在
ls -la | grep .env

# 2. 清除缓存并重启
watchman watch-del-all
rm -rf node_modules/.cache/metro
yarn start --reset-cache
```

**Q2: 修改 .env 不生效**

**解决**：

```bash
# 完全重启 Metro（必须清除缓存）
yarn start --reset-cache
```

### 构建问题

**Q3: iOS Pod 安装失败**

**解决**：

```bash
cd ios
pod deintegrate
pod install
cd ..
```

**Q4: Android 构建失败**

**解决**：

```bash
cd android
./gradlew clean
cd ..
yarn android:hot
```

### 功能问题

**Q5: 语音播报声音不自然**

**原因**：未重新编译，使用的是系统 TTS

**解决**：

```bash
# Android
cd android && ./gradlew clean && cd .. && npx react-native run-android

# iOS
cd ios && pod install && cd .. && npx react-native run-ios
```

重新编译后将使用百度 TTS，音质自然。

**Q6: 定位失败或不准确**

**原因**：

1. 未配置高德地图密钥
2. Android 密钥未绑定 SHA1
3. 定位权限未授予

**解决**：

```bash
# 1. 获取 SHA1（Android）
cd android
keytool -list -v -keystore app/debug.keystore -storepass android

# 2. 登录高德控制台添加 SHA1 和包名
# https://console.amap.com/dev/key/app
# 包名：com.lynxTravel

# 3. 等待 3-5 分钟生效后重启应用
```

### 权限问题

**Q7: Android 录音权限被拒绝**

**解决**：

- 首次运行会自动弹出权限请求，必须允许
- 如果已拒绝，去手机设置 → 应用 → 山猫导游 → 权限 → 开启麦克风权限

**Q8: iOS 麦克风权限问题**

**解决**：

1. 确认 `Info.plist` 已添加 `NSMicrophoneUsageDescription`
2. 重新编译：`cd ios && pod install && cd .. && yarn ios`
3. 首次运行会弹出权限请求

---

## 🚀 性能优化指南

> **注意**：本节专门针对生产环境上架前的性能优化，强烈建议在打包发布前完成。

### 已实施的优化

#### ✅ 1. 生产环境 Console 移除

**问题**：代码中存在 150+ 处 `console.log` 语句，在生产环境会严重影响性能。

**解决方案**：已配置 `babel-plugin-transform-remove-console`，打包时自动移除所有 console.log。

```bash
# 已自动配置，打包时生效
# 开发环境不受影响，仍可正常使用 console.log
```

**效果**：
- JS 线程执行速度提升 15-20%
- 减少不必要的性能开销
- console.error 和 console.warn 保留用于错误追踪

#### ✅ 2. Android 代码混淆和资源压缩

已在 `android/app/build.gradle` 中启用：

```gradle
release {
    minifyEnabled true           // 代码混淆
    shrinkResources true         // 资源压缩
    proguardFiles ...           // 混淆规则
}
```

**效果**：APK 体积减少 30-50%

---

### ⚡ 关键性能优化（必须实施）

#### 🔥 1. 启用 Hermes 引擎（最重要！）

**Hermes** 是 Meta 专为 React Native 优化的 JavaScript 引擎，可以显著提升性能。

**Android 配置：**

编辑 `android/gradle.properties`，添加或修改：

```properties
hermesEnabled=true
```

**iOS 配置：**

编辑 `ios/Podfile`，找到 `use_react_native!` 这一行，修改为：

```ruby
use_react_native!(
  :path => config[:reactNativePath],
  :hermes_enabled => true  # 改为 true
)
```

然后重新安装依赖：

```bash
# iOS 重新安装
cd ios && pod install && cd ..

# 清理缓存并重新运行
yarn clean:cache
yarn android  # 或 yarn ios
```

**预期效果：**
- 🚀 启动速度提升 **50%**
- 📉 内存占用减少 **30%**
- 📦 包体积减少 **20%**
- ⚡ 整体性能显著提升

#### 🎯 2. FlatList 性能优化

在所有 FlatList 组件中添加性能优化配置（特别是 HomeScreen.js）：

```javascript
<FlatList
  data={data}
  renderItem={renderItem}
  keyExtractor={(item) => item.id.toString()}
  
  // 性能优化配置
  removeClippedSubviews={Platform.OS === 'android'}
  maxToRenderPerBatch={10}
  updateCellsBatchingPeriod={50}
  initialNumToRender={6}
  windowSize={5}
  
  // 如果列表项高度固定，添加此项可大幅提升性能
  getItemLayout={(data, index) => ({
    length: 88,  // 根据实际卡片高度调整
    offset: 88 * index,
    index,
  })}
/>
```

**效果**：列表滚动流畅度提升至 60 FPS

#### 📦 3. Android Gradle 构建优化

在 `android/gradle.properties` 中添加：

```properties
# Gradle 构建优化
org.gradle.caching=true
org.gradle.parallel=true
org.gradle.configureondemand=true
android.enableR8.fullMode=true

# 内存优化
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m
```

**效果**：构建速度提升 30-40%

---

### 🎨 图片性能优化（强烈推荐）

#### 使用 react-native-fast-image

React Native 自带的 Image 组件性能较差，建议替换为 `react-native-fast-image`。

**安装：**

```bash
yarn add react-native-fast-image
cd ios && pod install && cd ..
```

**使用示例：**

```javascript
// 替换前
import { Image } from 'react-native';
<Image source={{ uri: imageUrl }} style={styles.image} />

// 替换后
import FastImage from 'react-native-fast-image';
<FastImage
  source={{
    uri: imageUrl,
    priority: FastImage.priority.normal,
    cache: FastImage.cacheControl.immutable,
  }}
  style={styles.image}
  resizeMode={FastImage.resizeMode.cover}
/>
```

**优先替换的组件：**
- `src/components/AttractionCard.js`
- `src/components/PlaceCard.js`
- `src/components/MasonryCarousel.js`
- `src/components/HomeContent.js`

**效果：**
- iOS 使用 SDWebImage（专业图片缓存库）
- Android 使用 Glide（Google 推荐）
- 内存占用减少 50%+
- 图片加载速度提升 3-5 倍

---

### 💾 API 请求缓存优化

创建 `src/utils/apiCache.js`：

```javascript
const cache = new Map();
const CACHE_DURATION = 5 * 60 * 1000; // 5分钟缓存

export const cachedFetch = async (key, fetchFn, duration = CACHE_DURATION) => {
  const now = Date.now();
  const cached = cache.get(key);
  
  // 如果缓存未过期，直接返回
  if (cached && (now - cached.timestamp < duration)) {
    return cached.data;
  }
  
  // 否则重新获取
  const data = await fetchFn();
  cache.set(key, { data, timestamp: now });
  return data;
};

// 清除缓存
export const clearCache = (key) => {
  if (key) {
    cache.delete(key);
  } else {
    cache.clear();
  }
};
```

**使用示例（HomeScreen.js）：**

```javascript
import { cachedFetch } from '../utils/apiCache';

const loadCityData = async (adcode, lat, lon) => {
  const cacheKey = `city_${adcode}_${lat}_${lon}`;
  const data = await cachedFetch(cacheKey, () =>
    locationAPI.getScenicAreas({ adcode, latitude: lat, longitude: lon })
  );
  setScenicAreasWithSpots(data);
};
```

**效果**：减少重复网络请求，提升响应速度

---

### 📱 平台特定优化

#### Android 特定优化

**1. 限制 ABI 架构（减小包体积）**

在 `android/app/build.gradle` 中添加：

```gradle
android {
    defaultConfig {
        // 只打包常用架构
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
    
    // 可选：分架构打包
    splits {
        abi {
            enable true
            reset()
            include "armeabi-v7a", "arm64-v8a"
            universalApk true  // 同时生成通用APK
        }
    }
}
```

**效果**：APK 体积减少 15-20 MB

#### iOS 特定优化

**在 Xcode 中设置（Release 配置）：**

1. 打开 `ios/BellaTravel.xcworkspace`
2. 选择项目 → Build Settings
3. 设置以下选项：
   - **Optimization Level**: Fastest, Smallest [-Os]
   - **Dead Code Stripping**: YES
   - **Strip Linked Product**: YES
   - **Strip Debug Symbols During Copy**: YES

**效果**：IPA 体积减少 10-15 MB

---

### 🧪 性能测试和验证

#### 打包前性能测试清单

```bash
# 1. 清理缓存
yarn clean:cache
cd android && ./gradlew clean && cd ..
cd ios && rm -rf build && cd ..

# 2. 构建 Release 包
# Android
cd android && ./gradlew assembleRelease && cd ..

# iOS (使用 Xcode Archive)
open ios/BellaTravel.xcworkspace
# Product → Archive

# 3. 测试启动时间 (Android)
adb install -r android/app/build/outputs/apk/release/app-release.apk
adb shell am start -W com.lynxTravel
# 查看 TotalTime，应该 < 1500ms

# 4. 查看包体积
ls -lh android/app/build/outputs/apk/release/app-release.apk
# 应该 < 40MB
```

#### 关键性能指标

| 测试项 | 优化前 | 优化后 | 目标 |
|--------|--------|--------|------|
| 冷启动时间 (Android) | ~2.5s | ~1.3s | < 1.5s |
| 冷启动时间 (iOS) | ~2.0s | ~1.2s | < 1.5s |
| APK 大小 | ~50MB | ~33MB | < 40MB |
| IPA 大小 | ~45MB | ~30MB | < 35MB |
| 首屏渲染时间 | ~800ms | ~450ms | < 500ms |
| 内存占用 (运行中) | ~200MB | ~135MB | < 150MB |
| 列表滚动 FPS | ~54fps | 60fps | 60fps |

---

### 🛠️ 快速优化脚本

已提供一键优化脚本：

```bash
# 运行优化脚本
chmod +x scripts/optimize-performance.sh
./scripts/optimize-performance.sh
```

脚本会自动：
- ✅ 检查 Hermes 配置
- ✅ 添加 Gradle 优化配置
- ✅ 清理缓存
- ✅ 统计 console 语句数量

---

### 📊 预期性能提升总览

完成所有优化后，预期效果：

**Android Release：**
- 启动速度提升 **48%**
- 包体积减少 **34%**
- 内存占用减少 **33%**
- 滚动性能达到 **60 FPS**

**iOS Release：**
- 启动速度提升 **40%**
- 包体积减少 **33%**
- 内存占用减少 **28%**
- 滚动性能达到 **60 FPS**

---

### ⚠️ 优化实施优先级

**立即实施（必须）：**
1. ✅ 移除生产环境 console.log（已完成）
2. ⚡ 启用 Hermes 引擎
3. 📋 添加 FlatList 优化配置

**近期实施（强烈推荐）：**
4. 🖼️ 集成 react-native-fast-image
5. 💾 添加 API 请求缓存
6. 🔧 应用 Gradle 构建优化

**长期优化（可选）：**
7. 📱 实施 ABI 分割打包
8. 📊 添加性能监控
9. 🎯 代码分割和懒加载

---

### 🔍 性能监控工具

**Android：**
```bash
# 使用 Android Studio Profiler
# View → Tool Windows → Profiler

# 或使用命令行
adb shell dumpsys meminfo com.lynxTravel
```

**iOS：**
```bash
# 使用 Xcode Instruments
# Xcode → Open Developer Tool → Instruments
# 选择 "Time Profiler" 或 "Allocations"
```

---

## 🔗 相关链接

### 开发平台

- [百度智能云](https://cloud.baidu.com/) - 语音播报 TTS
- [科大讯飞](https://www.xfyun.cn/) - 语音识别 ASR
- [高德开放平台](https://lbs.amap.com/) - 地图定位服务
- [React Native 官网](https://reactnative.dev) - 框架文档

### 发布平台

- [Google Play Console](https://play.google.com/console/) - Android 发布
- [App Store Connect](https://appstoreconnect.apple.com/) - iOS 发布
- [应用宝](https://open.qq.com/) - 国内 Android 发布
- [蒲公英](https://www.pgyer.com/) - 内测分发平台

### 工具

- [Icon Kitchen](https://icon.kitchen/) - 应用图标生成
- [BIRME](https://www.birme.net/) - 批量图片处理

---

## 📄 License

MIT

---

## 👥 团队信息

**开发公司**：新疆指南针文化发展有限公司

<details>
<summary>📞 联系方式（点击展开）</summary>

<br>

**技术支持**：下坠同学

- 📧 **邮箱**：kudduss@foxmail.com
- 💬 **QQ**：3249696828
- 🌐 **Gitee**：[提交 Issue 获取支持](https://gitee.com/bella2024/electronic_tourist)

**工作时间**：周一至周五 9:00-18:00（北京时间）

**响应时间**：

- 紧急问题：24小时内
- 一般问题：48小时内
- 功能建议：3-5个工作日内

</details>

<details>
<summary>🤝 贡献指南（点击展开）</summary>

<br>

欢迎为项目做出贡献！以下是参与方式：

**报告问题**

1. 在 GitHub 上创建 Issue
2. 详细描述问题（包括截图、错误日志）
3. 说明您的设备和系统版本

**提交代码**

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

**代码规范**

- 遵循 ESLint 配置
- 提交前运行 `yarn lint` 检查代码
- 编写清晰的提交信息
- 添加必要的注释和文档

**测试要求**

- 充分测试您的更改
- 确保在 Android 和 iOS 上都能正常运行
- 不引入新的警告或错误

</details>

---

## ⚠️ 安全提示

- ⚠️ **切勿**将 `.env` 文件提交到 Git 仓库
- 🔐 **定期备份**签名密钥文件（app.jks）到云盘或 U 盘
- 🔑 **妥善保管**各平台的 API 密钥和证书
- 📦 **保存** Gradle mapping.txt 文件（用于崩溃分析）
- 🔒 **使用**密码管理器（如 1Password）管理所有密钥

---

<div align="center">

**📝 文档版本**：v1.0.1  
**最后更新**：2025-01-08

**⭐ 如果这个项目对您有帮助，请给我们一个 Star！**

Made with ❤️ by 新疆指南针文化发展有限公司

</div>