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