整理开发文档

docs/杜康好客-v3-城市仓库与日志架构.md

@@ -0,0 +1,37 @@
+# 杜康好客 · 城市 / 仓库 / 日志架构
+
+> **2026-07-12** P1 多合伙 + P2 仓库 ✅ · 合伙人管仓日志 ⏳ Wave 3
+
+## 数据模型（摘要）
+
+```
+CommonCity → PartnerAccount(主) → Store(partnerAccountId, settlementRate)
+          → CityWarehouse(HQ|PARTNER 管仓)
+          → CatalogProduct
+PartnerAccount → 子账号(parentAccountId, permissions JSON)
+```
+
+迁移：城市绑定/购酒分佣合并至 `partner_account`；订单快照 `partnerAccountIdAtPay` + `orderCommissionRateAtPay`。
+
+## 日志职责
+
+| 主体 | 表 | 入口 |
+|------|-----|------|
+| HQ 写操作 | `common_event` HQ_OPERATION | `@HqOperation` → `/logs/hq` |
+| 合伙人 | `log_partner_analytics` | `/logs/partners` |
+| 门店 | `log_store_analytics` | `/logs/stores` |
+| C 端 | `log_user_analytics` | `/logs/users` |
+| 权益/订单 | `common_event` BENEFIT_LEDGER / ORDER_STATUS | 领域查询 |
+
+## HQ action（新业务）
+
+`CITY_*` · `WAREHOUSE_*` · `PARTNER_*` · `PARTNER_ACCOUNT_*` · `HQ_ACCOUNT_*` · `HQ_PERMISSION_*`  
+常量：`hq-operation.constants.ts` · 筛选项：`apps/admin-web/src/lib/hq-log.ts`
+
+## 合伙人子账号 eventName
+
+`partner_staff_create|update|permission_update|delete` ✅ · `partner_warehouse_*` ⏳
+
+## DoD
+
+HQ 写接口有 `@HqOperation`；合伙人写走 `trackPartnerOneSafe`；extraJson 脱敏；不跨模块直写他人日志表。