hyapp-server/docs/host-agency-bd-implementation-sequence.md

Host, Agency And BD Implementation Sequence

本文定义主播、Agency、BD、BD Leader 功能的开发顺序。详细 App 架构见 Host Agency BD App Architecture，后台工资和政策架构见 Host Agency BD Admin Architecture。

核心原则：先做关系事实，再做 App 主链路，最后做统计和工资。工资依赖 host、Agency、BD 关系快照和有效上麦/礼物统计；如果先做工资后台，会得到一套没有可靠输入的数据系统。

Phase 1: Host Service Core

先建立 host-service 的核心事实模型。这个阶段不追求完整后台和完整 App，只保证身份、关系、幂等、审计和 outbox 的地基正确。

交付：

• 新增 host-service skeleton：配置、gRPC server、healthcheck、MySQL repository、docker-compose 本地运行入口。
• 新增 protobuf：host profile、Agency、BD profile、Agency membership、application、role invitation 的内部 gRPC 契约。
• 新增 MySQL 表：host_profiles、agencies、bd_profiles、agency_memberships、agency_applications、role_invitations、host_outbox。
• 实现 command id 幂等：申请、邀请、审核、踢出、接受邀请都不能因重试重复创建事实。
• 实现关系锁：涉及用户身份变化时锁 host_profiles、agencies、bd_profiles 和 active membership。

验收：

• 同一用户不能同时存在两个 active Agency membership。
• active host 不能接受成为 Agency 的邀请。
• Agency owner 自动拥有 host profile 和 owner membership。
• go test ./services/host-service/... 通过。
• 修改 protobuf 后必须 make proto && go test ./...。

Phase 2: Minimal Admin For Organization Seed

先做最小后台组织初始化能力，不做完整工资后台。App 需要有 Agency/BD 数据才能跑搜索、申请和邀请主链路。

交付：

• Admin 创建/停用 BD Leader。
• Admin 创建/停用 BD，并绑定 parent_leader_user_id。
• Admin 创建/关闭 Agency，并绑定 parent_bd_user_id 和 owner。
• Admin 设置 Agency join_enabled。
• Admin 关系操作写 admin_audit_logs，保留操作人、原因、前后状态和 command_id。

暂不做：

• 不做 salary policy。
• 不做 salary cycle。
• 不做工资单审批。
• 不做 wallet 入账。

验收：

• Admin 创建的 Agency 可以被同区域用户搜索到。
• 关闭或禁用加入的 Agency 不出现在 App 搜索结果。
• 所有 Admin 关系变更都有审计记录。
• 同一 command_id 重试不会重复创建 BD/Agency。

Phase 3: App Main Flow

这个阶段跑通用户真实路径。完成后，主播身份和组织关系才成为可靠事实。

交付：

• 用户搜索同区域 active、joinable Agency。
• 用户申请加入 Agency。
• Agency owner 或授权管理者审核、拒绝申请。
• Agency 踢出 host：只结束 membership，不删除 host identity。
• Kicked host 可以重新申请其他 Agency。
• BD 邀请用户成为 Agency。
• BD 自己邀请自己成为 Agency：仅限 BD 当前不是 active host 且没有 active Agency。
• BD Leader 邀请用户成为 BD。
• BD Leader 直接邀请用户成为 Agency。
• App 查询：host/me、agency/me、agency/members、agency/applications、bd/me、bd/agencies。

验收：

• 用户只能看到自己区域内的 Agency。
• 申请通过后用户成为 host 且有 active membership。
• Agency 踢人后用户仍是 host，但 current_agency_id 为空。
• active host 接受 Agency 邀请被拒绝。
• BD 加入别的 Agency 成为 host 时，BD 身份仍然保留。
• BD Leader 邀请 BD 时，目标只得到 BD 身份，不自动成为 host。

Phase 4: Stats And Attribution

关系主链路稳定后再消费房间和钱包事件。统计必须使用事件发生时的关系快照，不能从当前 membership 反推历史归属。

交付：

• 消费 RoomMicChanged，只累计 publish_state=publishing 的有效上麦时间。
• 消费礼物/钱包事件，累计 host 收到的礼物积分或等价统计。
• 写入 host_daily_stats，包含 agency_id、bd_user_id、bd_leader_user_id 和非空 relation_scope_key。
• 写入 host_event_dedup，按 event_id 幂等消费。
• 构建 App 读模型：host_me_view、agency_member_view、bd_team_view、earning_summary_view 的基础查询。

验收：

• pending_publish 不计有效工作时长。
• host 一天内换 Agency 时，stats 按 relation snapshot 拆行。
• 同一事件重复消费不会重复累计。
• 迟到事件可以修正未锁定 stats；已结算结果交给 Admin 调整单处理。

Phase 5: Full Admin Salary

最后做完整工资后台。此时输入已经稳定：关系事实、事件统计和归属快照都可用。

交付：

• 配置 host、agency、bd 三类 salary policy。
• 配置 daily、weekly、semi_monthly、monthly cycle cadence。
• 生成 salary cycle 和 salary items。
• Host salary：基于有效上麦时长、礼物积分、有效天数。
• Agency salary：基于下属 host salary item 或明确配置的 agency 指标。
• BD/BD Leader salary：基于 downstream host salary sum，且按 source host salary item 去重。
• 后台审核工资周期。
• 调用 wallet-service 给 USD_BALANCE 入账，幂等键为 salary:{salary_item_id}。
• 支持调整单：迟到事件、人工修正、争议处理都走补差或冲正。

验收：

• 同区域同 policy type 不能同时启用多个 active policy。
• 同一 cycle 重算不会重复生成工资项。
• BD Leader 直接管理 Agency 时，同一 host salary source 只算一次。
• Salary cycle 重复 post 不会重复给钱包入账。
• 已 posted item 不可原地修改，必须通过 adjustment 修正。

Phase 6: Hardening And Operations

主链路和工资链路都跑通后，再补运维和风险能力。不要在前几阶段提前把这些能力做成阻塞项。

交付：

• Admin export：工资周期、工资项、Agency 成员、BD 团队。
• Rebuild job：按事实表重建 App read model。
• Compensation job：扫描 outbox 未投递、钱包 posting 失败、事件消费失败。
• Risk checks：异常高礼物积分、异常上麦时长、重复设备/账号关系。
• Dashboard：cycle 状态、posting 失败数、事件消费延迟、host stats watermark。

验收：

• outbox 消费失败可重放。
• read model 删除后可从事实表重建。
• wallet posting partial failure 可继续重试未 posted item。
• 关键后台动作都有 audit log。

Recommended Milestones

Milestone	Scope	Can Demo
M1	Phase 1	用 gRPC 创建基础关系事实，证明幂等和锁正确
M2	Phase 2	后台创建 BD/Agency，App 可以搜到 Agency
M3	Phase 3	用户申请、审核、踢出、重新申请、邀请链路完整跑通
M4	Phase 4	有效上麦和礼物统计按关系快照落库
M5	Phase 5	后台生成工资单，审批后入账 USD_BALANCE
M6	Phase 6	失败补偿、导出、重建和监控可用

Stop Conditions

• Phase 1 没有完成前，不做工资政策和工资周期。
• Phase 2 没有完成前，不做 App Agency 搜索上线，因为没有可信组织种子数据。
• Phase 3 没有完成前，不做工资发放，因为 host/Agency/BD 归属还不稳定。
• Phase 4 没有完成前，不做真实工资入账，因为缺少可审计统计输入。
• Phase 5 没有完成审批和幂等 posting 前，不允许写 USD_BALANCE。

Verification Commands

文档落地到代码后，按改动范围验证：

make proto
go test ./...
docker compose config

涉及本地启动链路时再运行：

docker compose up -d
docker compose ps
docker compose down