125 lines
5.7 KiB
Markdown
125 lines
5.7 KiB
Markdown
# 杜康好客 · V3 城市 / 仓库 / 日志架构
|
||
|
||
> **版本**：2026-07-12
|
||
> **状态**：P1 城市多合伙 + P2 仓库 **已实现**（2026-07-12）；合伙人端管仓日志仍待 Wave 3
|
||
> **分工**：刘景尧任务暂由 `jacy-dukang` 代管（见 `AGENTS.md`）
|
||
|
||
---
|
||
|
||
## 1. 目标数据模型（城市顶层）
|
||
|
||
```
|
||
CommonCity (开城)
|
||
├── PartnerAccount[] 1:N 主账号（isPrimary=1，含城市绑定 + 购酒/核销佣金）
|
||
├── CityWarehouse[] 1:N 城市仓库（HQ 管 / 合伙人管）
|
||
└── CatalogProduct[] 按城市上架
|
||
|
||
PartnerAccount (主账号 = 城市合伙人主体)
|
||
├── cityId / scopeType / districtCodes / bindingStatus
|
||
├── orderCommissionRate / redeemCommissionRate
|
||
├── companyName / 银行 / 合同等主体信息
|
||
├── managedWarehouseId? 可选管仓
|
||
└── PartnerAccount[] 子账号（parentAccountId，permissions JSON）
|
||
|
||
CityWarehouse
|
||
├── cityId
|
||
├── managerType: HQ | PARTNER
|
||
└── partnerAccountId? 合伙人管仓时绑定主账号
|
||
|
||
Store
|
||
├── partnerAccountId FK → 主账号
|
||
└── settlementRate 门店核销结算比例（默认 0.60）
|
||
```
|
||
|
||
**迁移要点（2026-07）**：删除 `partner_partner`、`common_city_partner`、`common_city_commission_rule`；城市绑定与购酒分佣合并至 `partner_account` 主账号；门店结算比例下沉至 `store_store.settlementRate`；订单快照字段为 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。
|
||
|
||
---
|
||
|
||
## 2. 日志表与职责划分
|
||
|
||
| 操作主体 | 日志表 | eventType / eventName | 查询入口 |
|
||
|----------|--------|----------------------|----------|
|
||
| **HQ WebAdmin** 写操作 | `common_event` | `HQ_OPERATION` + `param1=action` | admin-web `/logs/hq` |
|
||
| **合伙人端** 行为 | `log_partner_analytics` | `partner_*` eventName | admin-web `/logs/partner` |
|
||
| **门店端** 行为 | `log_store_analytics` | `store_*` | admin-web `/logs/store` |
|
||
| **C 端** 行为 | `log_user_analytics` | 埋点 eventName | admin-web `/logs/user` |
|
||
| 权益/订单状态机 | `common_event` | `BENEFIT_LEDGER` / `ORDER_STATUS` | 领域查询 |
|
||
|
||
**原则**：HQ 侧 **CRUD / 审核 / 结算确认** 一律 `@HqOperation` → `common_event`；端侧 **登录 / 业务操作** 走对应 `log_*_analytics`。
|
||
|
||
---
|
||
|
||
## 3. CRUD → 日志映射（新业务）
|
||
|
||
### 3.1 HQ 侧（`common_event.HQ_OPERATION`）
|
||
|
||
| 实体 | refType | action 常量 | 装饰器状态 |
|
||
|------|---------|-------------|------------|
|
||
| 开城城市 | `CITY` | `CITY_CREATE` / `CITY_UPDATE` | ✅ 已接入 |
|
||
| 开城城市 | `CITY` | `CITY_DELETE` | ⏳ 待 API |
|
||
| 城市仓库 | `WAREHOUSE` | `WAREHOUSE_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 |
|
||
| 城市合伙人（主账号） | `PARTNER` | `PARTNER_CREATE` / `PARTNER_UPDATE` | ✅ 已接入 |
|
||
| 合伙人账号（HQ） | `PARTNER_ACCOUNT` | `PARTNER_ACCOUNT_CREATE` / `UPDATE` / `DELETE` | ✅ 已接入 |
|
||
| HQ 管理员 | `HQ_ACCOUNT` | `HQ_ACCOUNT_CREATE` / `UPDATE` | ✅ 已接入 |
|
||
| HQ 权限 | `HQ_PERMISSION` | `HQ_PERMISSION_UPDATE` | ✅ 已接入 |
|
||
|
||
实现约定：
|
||
|
||
- Controller 方法加 `@HqOperation({ action, refType, refIdField|refIdParam, includeBody })`
|
||
- `extraJson` 自动写入 `requestBody`（脱敏 password）+ `response` 摘要
|
||
- 常量定义：`server/.../hq-operation.constants.ts`；admin 筛选项：`apps/admin-web/src/lib/hq-log.ts`
|
||
|
||
### 3.2 合伙人端子账号（`log_partner_analytics`）
|
||
|
||
| 操作 | eventName | refType | 状态 |
|
||
|------|-----------|---------|------|
|
||
| 主账号新增子账号 | `partner_staff_create` | `PARTNER_ACCOUNT` | ✅ `PartnerStaffService` |
|
||
| 编辑子账号 | `partner_staff_update` | `PARTNER_ACCOUNT` | ✅ |
|
||
| 仅改角色/权限 | `partner_staff_permission_update` | `PARTNER_ACCOUNT` | ✅ |
|
||
| 删除子账号 | `partner_staff_delete` | `PARTNER_ACCOUNT` | ✅ |
|
||
| 仓库查看/维护（合伙人管仓） | `partner_warehouse_view` / `partner_warehouse_update` | `WAREHOUSE` | ⏳ Wave 3 |
|
||
|
||
分类：`packages/shared-types/src/partner-log.ts` → `account_ops` / `warehouse_ops`。
|
||
|
||
### 3.3 门店子账号
|
||
|
||
| 操作 | 日志表 | action / eventName | 状态 |
|
||
|------|--------|-------------------|------|
|
||
| HQ 创建/编辑门店账号 | `common_event` | `STORE_ACCOUNT_CREATE` / `UPDATE` | ✅ |
|
||
| 门店端自助（若有） | `log_store_analytics` | 待定义 `store_staff_*` | ⏳ |
|
||
|
||
---
|
||
|
||
## 4. 实现检查清单（DoD）
|
||
|
||
每条 CRUD 合并前确认：
|
||
|
||
- [ ] HQ 写接口有 `@HqOperation`，且 `HqOperationAction` + `hq-log.ts` 标签已同步
|
||
- [ ] 合伙人端写接口调用 `AnalyticsService.trackPartnerOneSafe`，eventName 已登记在 `partner-log.ts`
|
||
- [ ] `extraJson` 不含明文密码/令牌；手机号脱敏
|
||
- [ ] admin-web 日志页可按 action / category 筛选到新事件
|
||
- [ ] 跨模块不直写他人日志表（经 Analytics / HqOperationLogService）
|
||
|
||
---
|
||
|
||
## 5. 分阶段交付
|
||
|
||
| 阶段 | 内容 | 依赖 |
|
||
|------|------|------|
|
||
| **P0 日志补全** | 子账号 CRUD 落 `log_partner_analytics`；扩展 HQ action 常量 | 无 |
|
||
| **P1 城市架构** | `city_partner` 表、迁移 `partner_id`、HQ CRUD + `@HqOperation` | ✅ 2026-07-12 |
|
||
| **P2 仓库** | `city_warehouse` 表、HQ CRUD + 合伙人管仓校验 | ✅ 2026-07-12 |
|
||
| **P3 权限 JSON** | `PartnerAccount.permissions` 替代纯 `staffRole`；权限变更双写 HQ/合伙人日志 | P1 |
|
||
|
||
---
|
||
|
||
## 6. 相关文件
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `server/dukang-api/src/common/hq-operation/` | HQ 审计装饰器 + 拦截器 |
|
||
| `server/dukang-api/src/modules/iam/partner-staff.service.ts` | 合伙人子账号 + 日志 |
|
||
| `packages/shared-types/src/partner-log.ts` | 合伙人日志分类 |
|
||
| `apps/admin-web/src/pages/HqLogsPage.tsx` | HQ 操作日志 |
|
||
| `apps/admin-web/src/pages/PartnerLogsPage.tsx` | 合伙人日志 |
|