hailin
2f17266455
## Overview
完整实现 IT0 推荐裂变系统，涵盖后端微服务、基础设施、Flutter 移动端、Next.js Web Admin。
## Backend — referral-service (packages/services/referral-service/)
### 架构设计
- 遵循 billing-service 模式：DataSource 直接访问 public schema（非 TenantAwareRepository）
- 推荐单元为租户级别（tenant-level），不区分租户内用户
- 最大 2 层推荐深度（L1 直接推荐 / L2 间接推荐）
- 推荐码格式：`IT0-{tenantPrefix3}-{random4}` 例：`IT0-ACM-X9K2`
### 领域实体（5个，均在 public schema）
- `referral_codes`：每个租户唯一推荐码，记录点击量
- `referral_relationships`：推荐关系，状态流转 PENDING→ACTIVE→REWARDED→EXPIRED
- `referral_rewards`：积分奖励记录，支持 PENDING/APPLIED/EXPIRED
- `referral_stats`：每租户聚合统计（直推数、积分总量等）
- `referral_processed_events`：Redis Stream 幂等性去重表
### 奖励规则
- Pro 套餐首次付款：推荐人 $15（1500分）/ 被推荐人 $5（500分）
- Enterprise 套餐首次付款：推荐人 $50（5000分）/ 被推荐人 $20（2000分）
- 续订奖励：付款金额 10%，最多持续 12 个月
- 奖励触发：监听 Redis Stream `events:payment.received`，消费者组 `referral-service`
### Use Cases（6个）
- `GetMyReferralInfoUseCase`：获取/自动创建推荐码，返回分享链接
- `ValidateReferralCodeUseCase`：验证码格式 + 存在性（公开接口，注册前使用）
- `RegisterWithCodeUseCase`：注册时绑定推荐关系，防止自推荐/重复注册
- `ConsumePaymentReceivedUseCase`：消费支付事件，发放首次/续订奖励，含幂等保护
- `GetReferralListUseCase`：分页查询推荐列表和奖励记录
- `GetPendingCreditsUseCase`：供 billing-service 查询待抵扣积分并标记已使用
### REST Controllers（3个）
- `ReferralController` (/api/v1/referral)：用户端，JWT 验证
- GET /me — 我的推荐码与统计
- GET /me/referrals — 我的推荐列表（分页）
- GET /me/rewards — 我的奖励记录（分页）
- GET /validate?code=xxx — 公开验证推荐码（注册页使用）
- `ReferralInternalController` (/api/v1/referral/internal)：服务间调用，X-Internal-Api-Key 验证
- POST /register — auth-service 注册后回调，绑定推荐关系
- GET /:tenantId/pending-credits — billing-service 查询待抵扣金额
- POST /:tenantId/apply-credits — billing-service 账单生成后标记积分已使用
- `ReferralAdminController` (/api/v1/referral/admin)：管理员端，JWT + platform_admin 角色
- GET /relationships — 全量推荐关系（可按状态过滤，分页）
- GET /rewards — 全量奖励记录（可按状态过滤，分页）
- GET /stats — 平台汇总统计
## Infrastructure
### database migration (packages/shared/database/migrations/006-create-referral-tables.sql)
创建 5 张表，含必要索引（tenantId、code、status、createdAt）
### docker-compose.yml
新增 referral-service 服务定义（port 13012:3012），healthcheck 基于 HTTP 200，
api-gateway depends_on 中添加 referral-service healthy 条件
### kong.yml (packages/gateway/config/kong.yml)
新增 3 组路由：
- `referral-routes`：/api/v1/referral（JWT 插件，转发用户请求）
- `referral-admin-routes`：/api/v1/referral/admin（JWT 插件，管理员）
- `referral-validate-public`：/api/v1/referral/validate（无 JWT，注册页调用）
注：internal 路由不暴露到 Kong，仅服务间直接调用
## auth-service 集成 (packages/services/auth-service/src/application/services/auth.service.ts)
注册成功后（register + registerWithNewTenant 两个路径）fire-and-forget 调用
referral-service 内部接口 POST /api/v1/referral/internal/register，
传入 tenantId + referralCode（可选），使用 Node.js 内置 http 模块（无新依赖）
## Flutter 移动端 (it0_app/lib/features/referral/)
### 数据层
- `referral_info.dart`：ReferralInfo / ReferralItem / RewardItem 模型，含格式化 getter
- `referral_repository.dart`：Dio HTTP 请求 + Riverpod referralRepositoryProvider
### 状态管理（Riverpod FutureProvider）
- referralInfoProvider — 推荐码信息
- referralListProvider — 直推列表首页
- pendingRewardsProvider — 待抵扣奖励
- allRewardsProvider — 完整奖励历史
### UI（referral_screen.dart，630行）
- _ReferralCodeCard：推荐码展示 + 一键复制 + 系统分享（Share.share）
- _StatsRow：3格统计卡（直推数 / 已激活 / 待抵扣积分）
- _RewardRulesCard：奖励规则说明卡片
- _ReferralPreviewList + _RewardPreviewList：首页预览 + "查看全部"导航
- _ReferralListPage + _RewardListPage：完整分页列表子页面
### 入口集成
- profile_page.dart：Billing 分组新增"邀请有礼"设置行（Gift 图标）
- app_router.dart：ShellRoute 内新增 /referral 路由 → ReferralScreen
## Web Admin (it0-web-admin/)
### 数据层
- `src/domain/entities/referral.ts`：TypeScript 接口定义（ReferralRelationship / ReferralReward / ReferralAdminStats / PaginatedResult<T>）
- `src/infrastructure/repositories/api-referral.repository.ts`：React Query 数据获取函数（getAdminReferralStats / listAdminRelationships / listAdminRewards）
### 管理页面 (src/app/(admin)/referral/page.tsx)
3 Tab 布局（概览 / 推荐关系 / 积分奖励）：
- StatsOverview：3张统计卡（总推荐数 / 已激活 / 待领积分记录）
- RelationshipsTable：状态筛选下拉 + 分页表格（推荐人、被推荐人租户ID、推荐码、层级、状态、时间）
- RewardsTable：状态筛选下拉 + 分页表格（受益租户、金额、触发类型、状态、来源账单、时间）
- StatusBadge：彩色状态标签组件（PENDING/ACTIVE/REWARDED/EXPIRED/APPLIED）
### 导航集成
- sidebar.tsx：platformAdminItems 新增"推荐管理"（Gift 图标，/referral 路由）
- i18n/locales/zh/sidebar.json：新增 "referral": "推荐管理"
- i18n/locales/en/sidebar.json：新增 "referral": "Referrals"
## 部署说明
1. 服务器执行数据库迁移：
psql -U it0 -d it0 -f packages/shared/database/migrations/006-create-referral-tables.sql
2. 重建并启动新服务：
docker compose build referral-service api-gateway && docker compose up -d
3. 确认 .env 中设置 INTERNAL_API_KEY（服务间认证密钥）
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
||
|---|---|---|
| deploy | ||
| docs | ||
| it0-web-admin | ||
| it0_app | ||
| packages | ||
| scripts | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| Dockerfile.service | ||
| OPENCLAW_INTEGRATION_PLAN.md | ||
| README.md | ||
| entrypoint.sh | ||
| logo.svg | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| tsconfig.base.json | ||
| turbo.json | ||
README.md
IT0 — AI-Powered Server Cluster Operations Platform
Intelligent operations platform that combines AI agents with human oversight for managing server clusters.
Architecture
- Backend: NestJS microservices (TypeScript) with DDD + Clean Architecture
- Mobile: Flutter app with Riverpod state management
- Web Admin: Next.js dashboard with Zustand + React Query
- Voice: Python service for voice-based interaction (STT/TTS/VAD)
Services
| Service | Description |
|---|---|
| auth-service | Authentication, RBAC, API key management |
| agent-service | AI agent orchestration (Claude CLI + API) |
| inventory-service | Server, cluster, credential management |
| monitor-service | Metrics collection, alerting, health checks |
| ops-service | Task execution, approvals, standing orders |
| comm-service | Multi-channel notifications, escalation |
| audit-service | Audit logging, compliance trail |
| voice-service | Voice pipeline (Python) |
Quick Start
# Backend
pnpm install
pnpm dev
# Flutter
cd it0_app && flutter pub get && flutter run
# Web Admin
cd it0-web-admin && pnpm install && pnpm dev
Tech Stack
- Runtime: Node.js 20+, Dart 3.x, Python 3.11+
- Database: PostgreSQL (schema-per-tenant)
- Cache/Events: Redis Streams
- AI: Anthropic Claude (CLI + API)
- Build: pnpm workspaces + Turborepo