agents 和 skills 上传

2026-07-01 17:12:46 +08:00
parent aeb4ecfc84
commit 9cbd65f8d7
23 changed files with 1276 additions and 34 deletions
@@ -0,0 +1,85 @@
+# 后端速查（杜康好客 v3.1）
+
+> 完整 DDL/API 以 V2 手册 §五/§六 为准。
+
+## API Base
+
+- Prefix: `/api/v1`
+- Response: `{ code: 0, message: 'ok', data }`
+- JWT: `actorType` + `actorId` + `clientApp`
+
+## clientApp → actorType → 表
+
+| preV1 clientApp | V2 clientApp | actorType | 账号表 |
+|-----------------|--------------|-----------|--------|
+| USER_H5 | USER_MINI | USER | user_user |
+| SHOP_H5 | SHOP_H5 | STORE | store_account |
+| PARTNER_H5 | PARTNER_MINI | PARTNER | partner_account |
+| — | HQ_MINI | HQ | hq_account |
+
+## Module → API 前缀
+
+| Module | 前缀示例 | OWNER |
+|--------|----------|-------|
+| iam | `/auth`, `/user` | A |
+| catalog | `/catalog`, `/admin/cities`, `/admin/products` | C |
+| trade | `/trade`, `/partner/orders`, `/admin/orders` | A |
+| benefit | `/benefit` | A |
+| store | `/stores`, `/partner/stores`, `/admin/store-audits` | B |
+| redeem | `/redeem`, `/shop/redeem` | D |
+| settlement | `/settlement`, `/partner/settlement`, `/admin/settlement` | C |
+| ops | `/admin/dashboard`, `/admin/reports` | C |
+| analytics | `/analytics`, `/promo/touch` | A |
+| callbacks | `/callbacks/wechat/pay`, `/callbacks/xfx/delivery` | Lead |
+
+## 表前缀 → Module 写 OWNER
+
+| 前缀 | 示例表 | OWNER Module |
+|------|--------|--------------|
+| user_ | user_user, user_order, user_benefit_coupon | iam / trade / benefit |
+| store_ | store_store, store_account, store_payout | store / iam / settlement |
+| partner_ | partner_partner, partner_bill | store(B) / settlement(C) |
+| hq_ | hq_account | iam |
+| common_ | common_product_item, common_event, common_city | catalog / common |
+| log_ | log_third_party, log_user_analytics | 写入方 Module |
+
+**无以下 V1 表**：payments、user_order_item、redeem_tokens（DB）。
+
+## 关键跨模块调用链
+
+**Mock/真实支付成功**
+
+```
+PayProvider → TradeService.handlePaySuccess()
+  → BenefitService.grantOnOrderPaid(orderId)
+  → OrderDelivery 预创建
+  → common_event(ORDER_STATUS)
+```
+
+**核销确认**
+
+```
+RedeemService.confirm()
+  → BenefitService.deduct(couponId)
+  → SettlementService.createStorePayout(redeemRecordId)
+```
+
+## 禁止依赖（PR 拒绝）
+
+| # | 禁止 |
+|---|------|
+| F1 | redeem 直写 order |
+| F2 | store → trade/benefit |
+| F3 | benefit → trade/redeem |
+| F4 | trade → redeem |
+| F5 | benefit → redeem |
+| F6 | catalog → trade/settlement |
+| F9 | apps import server 源码 |
+
+## integrations（preV1）
+
+| Flag | Provider | 行为 |
+|------|----------|------|
+| MOCK_SMS=true | sms.mock | 固定码 123456 |
+| MOCK_PAY=true | pay.mock | 同步 PAID + 发券 |
+| MOCK_DELIVERY_AUTO=true | delivery.mock | BullMQ 自动推进状态 |