# 杜康好客 · AGENTS.md

> AI 编码入口。人类读 [`agent.md`](./agent.md)。启动、端口、测试账号见 [`README.md`](./README.md)。

杜康酒业 O2O：**购酒 → 发券 → 门店核销**。Monorepo + NestJS 单体（`/api/v1`，`{ code, message, data }`）。

| 路径 | 说明 |
|------|------|
| `apps/` | `h5-user` · `h5-shop` · `h5-partner` · `admin-web` · `mini-user` |
| `packages/` | `shared-types`（枚举/DTO）· `domain`（纯规则，无 IO）· `shared-ui` |
| `server/dukang-api/` | 唯一 API |
| `pages/` | UI 原型，只读 |

前端：[`apps/AGENTS.md`](./apps/AGENTS.md)。后端模块/表 OWNER：[`server/dukang-api/AGENTS.md`](./server/dukang-api/AGENTS.md)。

## 文档（冲突时）

1. `杜康好客-v3-PRD.md` — **唯一需求事实源**（编码时禁止改业务规则；需求变更只改它）
2. `杜康好客-v3-现状对照.md` — 进度
3. `杜康好客-v3编码手册.md` — 验收、核销、分工
4. `conventions.md` — 协作边界
5. V2 手册 §四–§六 — 架构/DB/API **参考**（与 V3 冲突则忽略）
6. `pages/{user,shop,partner,hq}/` — UI 参照

**禁止**：臆造 PRD 未定义规则；依赖 `doc/` 过时文档；`apps/*` import `server/*`；跨模块 `prisma` 写他人表。V2 / preV1 手册不再作需求依据。

## OWNER（2026-07 起暂由 jacy 代管全部）

`jacy-dukang` 可改 `apps/*`、`packages/*`、全部后端模块。逻辑边界仍按 A/B/C/D，便于子 Agent 隔离。Prisma 迁移由 jacy 主导。

- 跨模块只 inject 对方 **exported Service**
- Mock 只在 `integrations/*`；微信/配送回调只进 `callbacks/`

## 不可偏离

```
权益额 = benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；Redis 码 3 分钟
C 端门店仅 status=OPEN
订单 Tab：待付款 | 已付款 | 已完成
```

微信：iOS H5 登录后禁止仅 SPA 跳转再扫码（`packages/weixin-sdk/GOTCHAS.md`）。小程序 `open-type` 按钮祖先禁止 `stopPropagation`；weapp 标题只用 `navigationBarTitleText`。`h5-partner` 与 `admin-web` 同端口 5175，勿同时开。

## 按需加载

- 编码 `/dukang-coding` · V3 需求 `/dukang-v3` · 发版 `/dukang-release`（只说「发版」= 生产）
- 子 Agent：`/owner-a-user-trade` 等（见 `.cursor/agents/`）
- DoD：验收项满足；不跨模块直写表；类型在 `shared-types`、规则在 `domain`；相关 lint/单测过