# 杜康好客 · 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` | 合伙人日志 |