daoqi/youle_app_ios_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
842ca2b9dcf1dde74e73afcdbda804d478d57acc
youle_app_ios_v2/README.md
T
joywayer 113b4d4960 微信分享去sdk
2026-06-30 17:41:10 +08:00

8.0 KiB
Raw Blame History

ylgamehall

进贤聚友棋牌 iOS 新外壳（greenfield 重写）。原生外壳 + 内置 H5（gamehall.zip 解压到沙盒）+ WebViewJavascriptBridge 桥接，企业签 / 超级签 / TF 渠道分发，不上架 App Store。

同仓库 ../daoqi/ 是已上线多年的旧外壳 msext（Objective-C / MRC / iOS 9.0+），作为本项目的"工作参照实现"。本项目按现代 iOS 标准重写，但 H5 端零修改 是不可妥协的第一准则。

技术栈

项 值
语言 Swift 6.0（SWIFT_APPROACHABLE_CONCURRENCY=YES，SWIFT_DEFAULT_ACTOR_ISOLATION=MainActor）
UI SwiftUI + UIKit 互操作（按需）
最低 iOS 15.6
设备 iPhone + iPad，仅横屏，UIRequiresFullScreen=true
Xcode 26.5+（objectVersion=77，File System Synchronized Group）
工程入口 ylgamehall.xcodeproj（无 CocoaPods，不使用 workspace）
依赖管理 SPM（首选）+ Vendor .xcframework（闭源 SDK）
Bundle ID com.skyapp.ylgamehall
并发模型 Swift async/await + actor 隔离（不使用 Combine）

SPM 依赖

  • ZIPFoundation — H5 zip 解压
  • HappyDNS — 七牛 SDK 配套
  • Qiniu（qiniu/objc-sdk v8.9.x） — 七牛对象存储

Vendor 闭源 SDK

放在 Vendor/<SDKName>/，每个目录附 README.md 记录版本来源：

  • Vendor/WechatSDK/ — 微信开放平台
  • Vendor/AMap/ — 高德定位
  • Vendor/OpenCoreAMR/ — AMR 编解码（libopencore-amrnb.a / libopencore-amrwb.a）

目录结构

ylgamehall/
├── CLAUDE.md                       # AI 助手协作约定（第一权威）
├── README.md                       # 本文件
├── ylgamehall.xcodeproj            # Xcode 工程
├── ylgamehall/                     # App target
│   ├── AppDelegate.swift
│   ├── SceneDelegate.swift
│   ├── Info.plist
│   ├── ylgamehall-Bridging-Header.h
│   ├── Assets.xcassets
│   ├── Base.lproj/                 # LaunchScreen.storyboard
│   ├── Resources/
│   │   ├── gamehall.zip            # 内置 H5 包
│   │   ├── ChannelConfig.plist     # 渠道配置（gameid / channel / agent / market 等）
│   │   ├── AppSecrets.plist        # SDK 凭证（微信 AppID / 高德 Key / 七牛 等）
│   │   └── JS/
│   │       └── WebViewJavascriptBridge.js
│   └── Source/
│       ├── Audio/                  # AMR 编解码、录音 / 播放、录音浮窗
│       ├── Bridge/                 # WebViewJavascriptBridge + 各 Handler
│       │   └── Handlers/           # 39 项 H5↔Native 桥接 handler
│       ├── Coordinator/            # AppCoordinator 启动流水线
│       ├── Location/               # 高德定位封装
│       ├── Login/                  # 微信登录
│       ├── Network/                # RemoteConfig、版本解析、七牛上传
│       ├── Resource/               # 沙盒路径、H5 zip 升级、解压、子游戏下载
│       ├── SDK/                    # 微信 / 高德 SDK 包装
│       ├── Share/                  # 微信 / QQ / 抖音分享 + 分享面板
│       └── WebView/                # WKWebView 容器、Splash、子游戏 VC
├── Vendor/                         # 闭源 SDK
│   ├── WechatSDK/
│   ├── AMap/
│   └── OpenCoreAMR/
└── docs/                           # 项目文档（见下节）
    └── res/                        # 维护者私人素材池（项目代码不感知）

文档体系

所有架构决策、契约定义、执行计划、验收清单都在 docs/ 下。任何代码修改前先读对应文档。

文档 角色 何时读
CLAUDE.md 项目协作约定、契约边界声明、两条核心原则 每次对话先读
docs/H5-Native-Contract.md H5 ↔ 原生 桥接契约（黑盒可观察行为） 涉及桥接接口必读
docs/H5-Native-Implementation-Design.md 新外壳实施蓝图（架构、模块、代码骨架） 实现新外壳必读
docs/Development-Plan.md 开发执行计划（Phase 0–10、依赖图、进度追踪） 排期 / 进度更新必读
docs/Verification-Checklist.md 功能验证清单（统一验收的操作手册） 阶段验收时勾选
docs/SDK-Integration-Guide.md 微信 / 高德 / opencore-amr / 七牛 接入手册 接 SDK 时按章节落地
docs/H5-Debug-Guide.md H5 端调试（Safari Web Inspector） 调试 H5 console / Network / 断点时
../daoqi/ 原项目 msext 工作参照实现 遇到行为差异 / 渠道注入 / SDK 时序等不确定问题时优先参考

文档优先级冲突时：Contract > Design > Plan。

核心原则（两条，原则 A 是第一准则）

原则 A：H5 端零修改（不可妥协）

H5 端 一行代码、一个字符、一个文件名、一个调用时机都不许改。遇到契约边界冲突时，回到原 msext 老路、由原生 Swift 端硬扛，哪怕代码看起来"不现代"。

必须 1:1 与现网一致的五类内容：

  1. 桥接接口名（handler 字符串，含历史驼峰 / 下划线大小写）
  2. 参数字段名（含 "title " 末尾空格、Province 大写 P 等历史包袱）
  3. 参数数据结构（类型、嵌套、fallback）
  4. H5 端注册方式（WebViewJavascriptBridge JS 协议 / 弹层 window.settings.xxx）
  5. 空实现接口也必须保留注册（opensaoma、getGameplay 等）

详见 docs/H5-Native-Contract.md。

原则 B：原生内部自由重构

原生内部一切自由——技术栈、模块结构、状态管理、SDK 选型、并发模型按现代 iOS 标准重新设计，不照搬旧项目实现细节。

冲突时无条件选 A：原生多一层适配 / 一段"看似过时"的代码可接受；契约破裂不可接受。

构建

前置

  • macOS + Xcode 26.5+
  • 项目方提供的 SDK 凭证（按 docs/SDK-Integration-Guide.md 填到 Resources/AppSecrets.plist）
  • Vendor 闭源 SDK 二进制（按 Vendor/<SDK>/README.md 放置）

构建步骤

open ylgamehall.xcodeproj

Xcode → Product → Run（或 ⌘R）。

不要新建 Podfile / .xcworkspace。本项目通过 SPM + Vendor 两层管理依赖，禁止引入 CocoaPods（ADR-006）。

渠道配置

ylgamehall/Resources/ChannelConfig.plist 是渠道注入入口（替代 msext 时代的"空目录名注入"机制）：

key 说明
gameid 游戏 ID
channel / gamedir 渠道标识 / H5 解压子目录名
gamestart H5 启动入口目录名（默认 gamehall）
gameconfig RemoteConfig 拉取地址
market 市场标识
agent 代理标识
appversion 当前外壳版本号（用于 RemoteConfig 升级判断）

提交与协作

  • commit message 使用中文短句，描述"做了什么 + 为什么"
  • 改动通过最小验证（BuildProject / 关键路径手测 / 单测）后可直接 commit，不必每次确认
  • 涉及桥接接口名 / 参数字段名 / 数据结构的改动必须在 commit message 中明示 "契约影响" 并附 docs/H5-Native-Contract.md 对应章节
  • 每完成一个 Phase 子项立即同步勾选 docs/Development-Plan.md §5 / §8
  • 不在未授权情况下执行 git push --force / git reset --hard / git rebase 等不可逆操作

验收

新外壳完成后，在不修改 H5 任何一行代码 的前提下，逐项跑 docs/H5-Native-Contract.md §10 的 26 项验收清单。任意一项 H5 表现与现网（../daoqi/msext）不一致即视为契约违反。

Reference in New Issue View Git Blame Copy Permalink