BeeX 当前系统架构
1. 架构边界
BeeX 是面向东南亚市场的多平台联盟返现产品。用户通过 App 或 WhatsApp 提交 TikTok Shop、Shopee、Lazada 商品链接，BeeX 生成可归因链接，同步平台订单，并在平台佣金确认后向用户和其直接邀请人分配收益。
| 边界 | 当前规则 |
|---|---|
| 业务用户角色 | 只有 USER；所有用户都可以邀请用户，按一层直接邀请关系发放推广奖励。 |
| 邀请关系 | 只保留一层直接邀请关系。订单收益可包含买家返现、直接邀请人奖励、优惠券及活动奖励。 |
| 国家隔离 | 印尼、马来等国家使用彼此独立的数据中心、服务、数据库、Redis 和三方平台账号。不同国家的数据不会进入同一业务库。 |
| 代码复用 | 同一套代码按国家和环境发布；运行时数据与凭证按国家物理隔离。 |
| 平台术语 | TikTok Partner、TAP、CAP、Campaign 是三方平台能力，不是 BeeX 用户角色。 |
2. 仓库与服务
| 仓库 | 职责 | 部署形态 |
|---|---|---|
beex-app | Flutter Native 壳：WebView、登录桥、设备能力、Push、本地日志、离线包管理。 | iOS / Android 应用包 |
beex-app-h5 | App 内业务 UI 与用户流程。 | H5 离线包 + OSS/CDN |
beex-service | 用户业务服务代码；按 api、wa、worker、webhook 四种 profile 独立运行。 | Spring Boot 独立进程 |
beex-admin-service | 管理后台 API、运营配置、发布管理、审计。 | Spring Boot 独立服务 |
beex-admin-page | 统一管理后台页面，可在界面切换所管理的后端环境。 | OSS/CDN 静态站 |
beex-sso | 管理后台与文档站统一登录。 | Spring Boot 独立服务 |
ai-ops-worker | AI 运维、Git 监听、文案同步、内部自动化；使用自己的数据库。 | 独立服务 + 独立库 |
beex-doc | 当前 PRD、架构、运维与操作文档。 | prd.beexofficial.com |
beex-release-tools | BeeX 项目专用发布技能和脚本。 | 工程工具，不是业务服务 |
仓库到运行服务的边界
flowchart LR
APP["beex-app\nNative 壳"] --> H5["beex-app-h5\n业务页面"]
APP --> API["beex-service\napi :7002"]
H5 --> API
WA["WhatsApp Cloud API"] --> WAH["beex-service\nwa :7010"]
THIRD["TikTok / Shopee / Lazada / Xendit"] --> WH["beex-service\nwebhook :7030"]
WK["beex-service\nworker :7020"] --> THIRD
ADMINUI["beex-admin-page"] --> ADMIN["beex-admin-service\n:7003"]
ADMINUI --> SSO["beex-sso\n:7004"]
OPS["ai-ops-worker"] --> GIT["Git / 飞书 / 运维 API"]
3. 运行拓扑
生产服务按职责拆进程，API 与 worker 分开，WhatsApp 与 webhook 使用独立 jar。生产跨可用区部署用户主链路；管理后台后端独立部署。测试环境可在一台 ECS 上运行多个独立进程，但不能合并调度职责。
印尼单环境逻辑拓扑；具体 ECS、内网 IP 和流水线以部署总览为准
flowchart TB
subgraph CLIENT["客户端与运营端"]
APP2["BeeX App / H5"]
ADMIN2["管理后台"]
WA2["WhatsApp 用户"]
end
subgraph EDGE["入口与静态资源"]
CDN["OSS + CDN\nH5 / Admin / Docs"]
ALB["ALB / HTTPS"]
end
subgraph SERVICES["独立运行服务"]
API2["api :7002"]
WAS["wa :7010"]
WORKER["worker :7020"]
WEBHOOK["webhook :7030"]
ADMINS["admin :7003"]
SSOS["sso :7004"]
AIOPS["ai-ops-worker"]
end
subgraph DATA["国家内独立数据资源"]
MYSQL[("RDS MySQL")]
REDIS[("Redis")]
OSS[("OSS")]
MQ["消息队列\n按监控信号启用/扩容"]
end
APP2 --> CDN
ADMIN2 --> CDN
APP2 --> ALB --> API2
WA2 --> ALB --> WAS
ADMIN2 --> ADMINS
ADMIN2 --> SSOS
API2 --> MYSQL
API2 --> REDIS
WAS --> MYSQL
WEBHOOK --> MYSQL
WORKER --> MYSQL
WORKER --> REDIS
WORKER -.-> MQ
ADMINS --> MYSQL
AIOPS --> OSS
调度唯一归属：订单同步、佣金计算、结算、通知、发券和平台数据同步只允许由 worker 执行，API/WA/webhook 进程不得重复启动定时任务。
4. 数据与三方平台
| 对象 | 职责 | 约束 |
|---|---|---|
| RDS MySQL | 用户、直接邀请关系、点击、订单、佣金、钱包、活动、优惠券和配置。 | 资金状态变化必须事务化、幂等并保留规则快照。 |
| Redis | 登录意图、会话、短时缓存、锁和幂等辅助。 | 不得作为资金事实源。 |
| OSS/CDN | H5 包、图片、用户反馈日志、管理后台、官网和文档站。 | 删除业务图片时同步清理对象；私有对象通过签名 URL 下载。 |
| TikTok Shop | Creator 商品/转链、Partner Campaign、CAP/Creator 订单。 | Partner/CAP 是平台授权，不映射 BeeX 用户角色。 |
| Shopee Affiliate | 商品、短链、conversionReport 订单归因。 | 使用短 tracking key 关联点击，避免 subIds 截断。 |
| Lazada Affiliate | 商品、转链、订单同步。 | 详情字段不足时按 productId 补全，订单同步保持游标与回溯窗口。 |
| Xendit | 收款、Payout/Disbursement、银行渠道与 webhook。 | KYC、支付密码、余额冻结及 webhook 幂等必须在 BeeX 完成。 |
| WhatsApp Cloud API | 登录、商品转链、订单/钱包查询、客服与运营消息。 | 按 Phone Number ID 路由测试/生产号码和环境。 |
5. 发布模型
服务端
测试和生产均使用按服务拆分的云效流水线。测试通过后，以同一个 Git commit 发布生产；生产流水线按 ECS 标签找到对应角色并滚动更新，任一实例健康检查失败即停止并回滚该实例。
H5 离线包
正常流程只构建一次测试制品：流水线 4987658 生成测试 DRAFT。验证通过后，在管理后台把同一个 ZIP 和 SHA256 转移到生产版本池，再执行生产灰度和全量发布。禁止为了晋级生产而重新构建另一份内容不同的包。
Native App
iOS/Android 包内必须带一份稳定 H5 bootstrap 包。App 启动先渲染本地包，界面可用后再异步检查更新；下载完成后提示刷新。新 App 构建前应把当前稳定 H5 包更新到内置资源。
统一发布路径
flowchart LR
COMMIT["Git commit"] --> TEST["测试环境构建/部署"]
TEST --> VERIFY["自动检查 + 人工验收"]
VERIFY -->|"服务端"| PROD["同一 commit\n生产流水线"]
VERIFY -->|"H5"| PROMOTE["同一 ZIP / SHA256\n转移生产版本池"]
PROMOTE --> GRAY["生产灰度"] --> FULL["生产全量"]
VERIFY -->|"Native"| BUNDLE["嵌入稳定 H5\n构建 iOS / Android"]
6. 安全与运维
- 云效部署凭证通过加密变量组注入；仓库、文档和流水线脚本不得出现 AK/SK、Token、数据库密码明文。
- 服务配置保存在目标环境安全配置中，测试和生产不得共用业务数据库或三方生产凭证。
- 管理后台写操作必须鉴权并记录操作人、时间、旧值、新值和发布环境。
- 资金、订单同步和 webhook 必须有幂等键；定时任务需有运行游标、回溯窗口、锁和告警。
- SLS、Uptime、飞书告警和 App 用户反馈用于发现问题，但不能阻塞 App 主界面渲染。
禁止推断：本页只描述稳定边界。ECS IP、实例数量、流水线 ID、域名健康状态等运行事实必须以部署总览和运维手册为准，不能从旧截图或历史记录推断。