# Host, Agency And BD Implementation Sequence 本文定义主播、Agency、BD、BD Leader 功能的开发顺序。详细 App 架构见 [Host Agency BD App Architecture](./host-agency-bd-architecture.md)，后台工资和政策架构见 [Host Agency BD Admin Architecture](./host-agency-bd-admin-architecture.md)。 核心原则：先做关系事实，再做 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 文档落地到代码后，按改动范围验证： ```bash make proto go test ./... docker compose config ``` 涉及本地启动链路时再运行： ```bash docker compose up -d docker compose ps docker compose down ```