177 lines
7.7 KiB
Markdown
177 lines
7.7 KiB
Markdown
# 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
|
||
```
|