app_store_dev_api 0.1.9 → 0.3.0

data/README.md

@@ -1,39 +1,231 @@
-# AppStoreDevApi
+# App Store Connect API Ruby SDK
 
-TODO: Delete this and the text below, and describe your gem
+一个用于与 Apple App Store Connect API 交互的 Ruby 客户端库。
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/app_store_dev_api`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![API Version](https://img.shields.io/badge/App%20Store%20Connect%20API-v4.2-blue)](https://developer.apple.com/documentation/appstoreconnectapi)
+[![Ruby](https://img.shields.io/badge/Ruby-2.7+-red)](https://www.ruby-lang.org)
 
-## Installation
+## 简介
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+AppStoreDevApi 是一个功能完整的 Ruby gem，提供了对 Apple App Store Connect API 的便捷访问。该库基于官方 API 文档自动生成代码，确保 API 覆盖的完整性和准确性。
 
-Install the gem and add to the application's Gemfile by executing:
+**🎉 最新更新**：已完全兼容 Apple App Store Connect API v4.2 规范，所有 241 个接口已验证通过（100% 一致性）。
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+## 主要特性
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+- 🔐 **JWT 认证** - 自动处理 JWT token 生成和认证
+- 🚀 **自动代码生成** - 基于官方 API 规范自动生成客户端代码
+- 📦 **完整 API 覆盖** - 完整支持 App Store Connect API v4.2（v1/v2 API）
+- 🛠️ **简单易用** - 提供直观的 Ruby 接口调用 API
+- ✅ **完全验证** - 所有 Request 类已通过 OpenAPI 规范验证
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+## 🚀 最近更新
 
-## Usage
+### API v4.2 完全兼容 (2026-01)
 
-TODO: Write usage instructions here
+我们对整个库进行了全面升级，以完全兼容 Apple App Store Connect API v4.2：
 
-## Development
+**核心改进：**
+- ✅ **68 个接口修复** - 修复所有不一致问题，一致性从 72.2% 提升到 100%
+- ✅ **160+ 新增接口** - 新增大量 API v4.2 功能支持
+- ✅ **命名规范化** - 统一使用驼峰命名（camelCase）
+- ✅ **Bug 修复** - 修复核心对象类中的布尔值验证问题
+- ✅ **完整测试** - 所有 241 个接口通过验证
 
-After checking out the repo, run `bin/console` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+**新增功能模块：**
+- 🆕 Accessibility Declarations（无障碍声明）
+- 🆕 Webhooks（事件通知）
+- 🆕 Marketplace Search（市场搜索）
+- 🆕 Alternative Distribution（替代分发）
+- 🆕 Background Assets（后台资源）
+- 🆕 Win Back Offers（用户召回优惠）
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+**详细更新日志请查看** [CHANGELOG.md](CHANGELOG.md)
 
-## Contributing
+## 支持的 API 模块
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/app_store_dev_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/app_store_dev_api/blob/main/CODE_OF_CONDUCT.md).
+### ✅ 应用管理
+- Apps 基础信息管理
+- App Store Versions 版本管理
+- App Store Version Submissions 提交审核
+- App Store Review Details 审核详情
+- Build 构建管理
 
-## License
+### ✅ 媒体资源
+- App Screenshots 应用截图
+- App Previews 应用预览
+- App Event Video Clips 活动视频
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+### ✅ 元数据管理
+- App Info & Localizations 应用信息本地化
+- App Store Version Localizations 版本本地化
+- App Categories 应用分类
+- Age Rating Declarations 年龄分级
+
+### ✅ 测试与分发
+- TestFlight Beta Testing 测试版管理
+- Beta Testers 测试人员管理
+- Beta Groups 测试组管理
+- Pre-Release Versions 预发布版本
 
-## Code of Conduct
+### ✅ 内购与订阅
+- In-App Purchases 应用内购买
+- Subscriptions 订阅管理
+- Promotional Offers 促销优惠
 
-Everyone interacting in the AppStoreDevApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/app_store_dev_api/blob/main/CODE_OF_CONDUCT.md).
+### ✅ 证书与配置
+- Bundle IDs 包标识符
+- Certificates 证书管理
+- Profiles 配置文件
+- Devices 设备管理
+
+### ✅ 用户与权限
+- Users 用户管理
+- User Invitations 用户邀请
+- User Roles 角色权限
+
+### ✅ 报告与分析
+- Sales Reports 销售报告
+- Finance Reports 财务报告
+- Power and Performance Metrics 性能指标
+
+## 安装
+
+添加到你的 Gemfile：
+
+```ruby
+gem 'app_store_dev_api'
+```
+
+然后执行：
+
+```bash
+bundle install
+```
+
+或者直接安装：
+
+```bash
+gem install app_store_dev_api
+```
+
+## 快速开始
+
+### 1. 配置认证
+
+```ruby
+require 'app_store_dev_api'
+
+client = AppStoreDevApi::Client.new(
+  key_id: 'YOUR_KEY_ID',
+  issuer_id: 'YOUR_ISSUER_ID',
+  private_key: File.read('path/to/AuthKey_YOUR_KEY_ID.p8')
+)
+```
+
+### 2. 使用示例
+
+```ruby
+# 获取所有应用
+apps = client.apps
+
+# 获取特定应用信息
+app = client.app(id: 'APP_ID')
+
+# 创建新版本
+version = client.create_app_store_version(
+  attributes: {
+    platform: 'IOS',
+    versionString: '1.0.1'
+  },
+  relationships: {
+    app: { data: { type: 'apps', id: 'APP_ID' } }
+  }
+)
+
+# 上传截图
+screenshot = client.create_app_screenshot(
+  attributes: {
+    fileName: 'screenshot.png',
+    fileSize: 102400
+  },
+  relationships: {
+    appScreenshotSet: { data: { type: 'appScreenshotSets', id: 'SET_ID' } }
+  }
+)
+```
+
+## 获取 API 密钥
+
+1. 登录 [App Store Connect](https://appstoreconnect.apple.com)
+2. 前往「用户和访问」
+3. 选择「密钥」标签
+4. 点击「生成 API 密钥」或「+」按钮
+5. 输入密钥名称并选择访问权限
+6. 下载 .p8 私钥文件（只能下载一次）
+7. 记录密钥 ID 和发行者 ID
+
+## 系统要求
+
+- Ruby 2.7 或更高版本
+- 有效的 App Store Connect 账号
+- API 访问权限
+
+## 项目结构
+
+```
+lib/
+├── app_store_dev_api/
+│   ├── client.rb           # 主客户端类（自动生成）
+│   ├── base.rb             # 基础请求处理
+│   ├── client/
+│   │   ├── authorization.rb # JWT 认证实现
+│   │   └── builder.rb      # 代码生成器
+│   ├── requests/           # API 请求定义
+│   │   ├── v1/            # v1 API 请求
+│   │   └── v2/            # v2 API 请求
+│   └── object/            # 数据模型定义
+└── config/
+    └── schema.json        # API 端点配置
+```
+
+## 开发
+
+本项目使用自动代码生成系统，基于 `schema.json` 配置文件生成 API 客户端方法。
+
+### 重新生成客户端代码
+
+```bash
+ruby -r ./lib/app_store_dev_api/client/builder.rb -e "AppStoreDevApi::Client::Builder.new.write"
+```
+
+### 运行测试
+
+```bash
+bundle exec rspec
+```
+
+### 代码检查
+
+```bash
+bundle exec rubocop
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License
+
+## 相关链接
+
+- [官方 API 文档](https://developer.apple.com/documentation/appstoreconnectapi)
+- [App Store Connect](https://appstoreconnect.apple.com)
+- [GitHub 仓库](https://github.com/wade0317/app_store_dev_api)
+- [Gitee 镜像](https://gitee.com/goodtools/AppStoreApi-Ruby)
+
+---
+
+⚡ 由 Ruby 驱动 | 基于 App Store Connect API 构建

data/Rakefile

@@ -1,4 +1,102 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require_relative "lib/app_store_dev_api/version"
+
+desc "构建并安装 gem 到本地"
+task :install_local do
+  version = AppStoreDevApi::VERSION
+  gem_name = "app_store_dev_api"
+  gem_file = "#{gem_name}-#{version}.gem"
+
+  puts "=" * 50
+  puts "本地构建和安装"
+  puts "=" * 50
+  puts "项目: #{gem_name}"
+  puts "版本: #{version}"
+  puts
+
+  # 清理旧的 gem 文件
+  puts "清理旧的 gem 文件..."
+  FileList["*.gem"].each { |f| rm f }
+
+  # 构建 gem
+  puts "构建 gem..."
+  sh "gem build #{gem_name}.gemspec"
+
+  # 安装到本地
+  if File.exist?(gem_file)
+    puts "安装到本地..."
+    sh "gem install #{gem_file}"
+    puts
+    puts "✅ 安装成功！"
+    puts
+    puts "使用方法:"
+    puts "  require 'app_store_dev_api'"
+    puts "  client = AppStoreDevApi::Client.new(...)"
+  else
+    puts "❌ 错误: 未找到构建的 gem 文件: #{gem_file}"
+    exit 1
+  end
+end
+
+desc "清理构建的 gem 文件"
+task :clean_gems do
+  puts "清理所有 .gem 文件..."
+  FileList["*.gem"].each do |f|
+    rm f
+    puts "  删除: #{f}"
+  end
+  puts "✅ 清理完成"
+end
+
+desc "运行所有验证脚本"
+task :validate do
+  puts "=" * 50
+  puts "运行验证脚本"
+  puts "=" * 50
+  puts
+
+  puts "1. API 一致性验证..."
+  sh "ruby scripts/validate_requests.rb"
+
+  puts
+  puts "2. 功能测试..."
+  sh "ruby scripts/test_request_body_classes.rb"
+
+  puts
+  puts "3. 三方交叉验证..."
+  sh "ruby scripts/comprehensive_validation.rb"
+
+  puts
+  puts "4. 检查废弃接口..."
+  sh "ruby scripts/find_deprecated_requests.rb"
+end
+
+desc "生成最终验证报告"
+task :report do
+  sh "ruby scripts/final_validation_report.rb"
+end
+
+desc "显示帮助信息"
+task :help do
+  puts
+  puts "可用的 Rake 任务:"
+  puts
+  puts "  rake build           - 构建 gem 包"
+  puts "  rake install         - 构建并安装到系统（Bundler 默认）"
+  puts "  rake install_local   - 构建并安装到本地"
+  puts "  rake release         - 发布到 RubyGems（需要凭据）"
+  puts "  rake clean_gems      - 清理构建的 gem 文件"
+  puts "  rake validate        - 运行所有验证脚本"
+  puts "  rake report          - 生成最终验证报告"
+  puts "  rake help            - 显示此帮助"
+  puts
+  puts "示例:"
+  puts "  bundle exec rake build"
+  puts "  bundle exec rake install_local"
+  puts "  bundle exec rake validate"
+  puts
+end
+
+task default: :help

data/SCRIPTS_ANALYSIS.md

@@ -0,0 +1,261 @@
+# 发布脚本分析报告
+
+## 📋 脚本概览
+
+| 脚本 | 用途 | 状态 |
+|------|------|------|
+| `install_local.sh` | 本地构建和安装 gem | ⚠️ 有问题 |
+| `install_local.bat` | Windows 本地安装 | ⚠️ 有问题 |
+| `release_remote.sh` | 发布到 RubyGems | ⚠️ 有问题 |
+| `release.sh` | （已删除） | - |
+
+---
+
+## 🔍 详细分析
+
+### 1. `install_local.sh` - 本地安装脚本
+
+**✅ 正确的部分：**
+- 自动检测项目名称（从 .gemspec 文件）
+- 自动检测版本号（从 version.rb）
+- 清理旧的 gem 文件
+- 构建 gem
+- 本地安装 gem
+
+**❌ 存在的问题：**
+
+#### 问题 1: 假设 gem 有可执行文件
+```bash
+# 第 78 行
+gem install --local "$GEM_FILE"
+
+# 第 158 行 - ❌ 错误
+%PROJECT_NAME% --version  # 假设有可执行文件
+```
+
+**实际情况**：`app_store_dev_api` 是一个**库 gem**，没有可执行文件（gemspec 中没有定义 `spec.executables`）。
+
+**问题**：脚本会在第 158 行失败，因为没有 `app_store_dev_api` 命令。
+
+#### 问题 2: 不必要的权限修改
+```bash
+# 第 14-18 行
+/bin/chmod -R a+rwx $CURRENT_DIR  # ❌ 危险：给所有用户读写执行权限
+/usr/sbin/chown $(whoami) $CURRENT_DIR
+/usr/bin/chgrp admin $CURRENT_DIR
+```
+
+**问题**：
+- `chmod -R a+rwx` 过于宽松，安全风险
+- 大多数项目不需要这些权限修改
+- 不适用于所有 gem 项目
+
+#### 问题 3: macOS 特定代码
+```bash
+# 第 4-8 行
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  CURRENT_DIR=$(dirname $(greadlink -f $0 2>/dev/null || readlink -f $0))
+```
+
+**改进建议**：可以简化为 `cd "$(dirname "$0")" && pwd`
+
+---
+
+### 2. `install_local.bat` - Windows 安装脚本
+
+**✅ 正确的部分：**
+- 自动检测项目和版本
+- 构建和安装逻辑正确
+
+**❌ 存在的问题：**
+
+#### 问题 1: 同样假设有可执行文件
+```batch
+rem 第 158-162 行 - ❌ 错误
+%PROJECT_NAME% --version
+%PROJECT_NAME% --help
+```
+
+**问题**：库 gem 没有可执行文件，这些命令会失败。
+
+#### 问题 2: 强制安装参数
+```batch
+rem 第 146 行
+gem install --local --force "%GEM_FILE%"
+```
+
+**问题**：`--force` 会忽略依赖检查，可能导致依赖问题。
+
+---
+
+### 3. `release_remote.sh` - 远程发布脚本
+
+**❌ 严重问题：**
+
+#### 问题 1: 自动提交所有更改
+```bash
+# 第 55-59 行
+if [ -z "$COMMIT_FILE_LIST" ]; then
+  echo "没有需要提交的文件！"
+else
+  git -C $CURRENT_DIR add -A
+  git -C $CURRENT_DIR commit -m "res ${VERSION_TAG_NAME}"  # ❌ 糟糕的 commit message
+```
+
+**问题**：
+- 自动 `add -A` 可能提交不应该提交的文件
+- commit message "res 0.1.0" 没有任何描述性
+- 不符合良好的 Git 实践
+
+#### 问题 2: 自动分支合并
+```bash
+# 第 64-79 行
+if [[ "$CODING_BRANCH" == "$RELEASE_BRANCH" ]]; then
+  echo "在master分支不需要处理"
+else
+  git checkout $RELEASE_BRANCH
+  git merge $CODING_BRANCH  # ❌ 自动合并可能有冲突
+  git push
+  git checkout $CODING_BRANCH
+  git merge $RELEASE_BRANCH
+  git push
+fi
+```
+
+**问题**：
+- 自动合并可能产生冲突
+- 没有处理合并失败的情况
+- 可能破坏分支历史
+
+#### 问题 3: 自动删除远程 tag
+```bash
+# 第 108-123 行
+read -p "存在远程分支,确认要删除远程分支吗？[Y/n]: " DELETE_REMOTE_TAG
+```
+
+**问题**：删除远程 tag 需要非常小心，可能影响其他开发者。
+
+#### 问题 4: 自动推送到 RubyGems
+```bash
+# 第 131 行
+gem push $CURRENT_DIR/${PROJECT_NAME}-${VERSION_TAG_NAME}.gem
+```
+
+**问题**：
+- 没有检查是否配置了 RubyGems 凭据
+- 没有最终确认步骤
+- 一旦推送无法撤销
+
+---
+
+## 🎯 是否适用于所有 Ruby gem 项目？
+
+### ❌ 不通用，原因：
+
+1. **假设有可执行文件** - 只适用于 CLI 工具类 gem，不适用于库 gem
+2. **权限修改逻辑** - 不是所有项目都需要
+3. **自动化程度过高** - release_remote.sh 自动执行太多操作，缺少安全检查
+4. **分支合并策略** - 假设特定的 Git 工作流
+5. **commit message 质量差** - "res 0.1.0" 不够描述性
+
+---
+
+## ✅ 推荐方案
+
+### 方案 A: 使用 Rake 任务（标准 Ruby 实践）
+
+创建 `Rakefile` 任务：
+
+```ruby
+# Rakefile
+require "bundler/gem_tasks"
+
+desc "Build and install gem locally"
+task :install_local do
+  sh "gem build app_store_dev_api.gemspec"
+  version = AppStoreDevApi::VERSION
+  sh "gem install app_store_dev_api-#{version}.gem"
+end
+
+desc "Clean built gems"
+task :clean do
+  sh "rm -f *.gem"
+end
+```
+
+**使用方法**：
+```bash
+bundle exec rake build        # 构建 gem
+bundle exec rake install      # 安装到本地
+bundle exec rake release      # 发布到 RubyGems（需要凭据）
+```
+
+### 方案 B: 简化脚本（针对库 gem）
+
+创建简单的 `install_local_simple.sh`：
+
+```bash
+#!/bin/bash
+
+set -e  # 遇到错误立即退出
+
+# 检测项目信息
+GEMSPEC=$(ls *.gemspec | head -n 1)
+PROJECT_NAME=$(basename "$GEMSPEC" .gemspec)
+VERSION=$(ruby -r "./lib/${PROJECT_NAME}/version.rb" -e "puts ${PROJECT_NAME^}::VERSION" 2>/dev/null)
+
+echo "项目: $PROJECT_NAME"
+echo "版本: $VERSION"
+
+# 清理旧 gem
+rm -f *.gem
+
+# 构建
+echo "构建 gem..."
+gem build "$GEMSPEC"
+
+# 安装
+echo "安装到本地..."
+gem install "${PROJECT_NAME}-${VERSION}.gem"
+
+echo "✅ 安装成功！"
+echo
+echo "使用方法:"
+echo "  require 'app_store_dev_api'"
+echo "  client = AppStoreDevApi::Client.new(...)"
+```
+
+### 方案 C: 修复现有脚本
+
+只需修复验证部分，移除假设有可执行文件的代码。
+
+---
+
+## 💡 建议
+
+### 推荐方案：**方案 A + 方案 B**
+
+1. **优先使用 Rake 任务**（标准做法）
+   - `bundle exec rake build` - 构建
+   - `bundle exec rake install` - 本地安装
+   - `bundle exec rake release` - 发布
+
+2. **保留简化的 shell 脚本**（便利性）
+   - 创建简单的 `install_local_simple.sh`
+   - 删除复杂的 `release_remote.sh`
+
+3. **删除有问题的脚本**
+   - 删除 `install_local.bat`（Windows 用户可以用 PowerShell + Rake）
+   - 删除 `release_remote.sh`（太复杂且不安全）
+
+---
+
+## 🚨 关键问题总结
+
+| 脚本 | 主要问题 | 严重程度 | 通用性 |
+|------|----------|----------|--------|
+| `install_local.sh` | 假设有可执行文件、过度权限修改 | 中 | ❌ 低 |
+| `install_local.bat` | 假设有可执行文件、强制安装 | 中 | ❌ 低 |
+| `release_remote.sh` | 自动提交、自动合并、糟糕的 commit message | 高 | ❌ 很低 |
+
+**结论**：这些脚本**不适合**作为通用的 Ruby gem 工具，需要重构或替换。