# 杜康好客 V3 交付版

四端 H5/WebAdmin + NestJS 单体 API。**V3 交付验收**以 [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) 为准；V2 为完整蓝图参考；preV1 为 Mock 联调历史参考。

## 快速启动

### 1. 基础设施

```bash
cd deploy
docker compose up -d
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 数据库

```bash
cp server/dukang-api/.env.example server/dukang-api/.env
pnpm db:generate
cd server/dukang-api
npx prisma db push    # v3.1 首次切换加 --accept-data-loss
pnpm prisma:seed      # seed-v31.ts
```

### 4. 启动服务

```bash
# 终端 1 - API
pnpm dev:api

# 终端 2~4 - 三端 H5
pnpm dev:user    # http://localhost:5173
pnpm dev:shop    # http://localhost:5174
pnpm dev:partner # http://localhost:5175


改动测试
```

## 测试账号（验证码均为 123456）

| 端 | 手机号 |
|----|--------|
| C端用户 | 13800000001 |
| 门店 | 13900000001 |
| 合伙人 | 13700000001 |

## 主链路冒烟

```bash
node scripts/smoke-v3.mjs      # V3 交付验收
node scripts/smoke-prev1.mjs   # preV1 历史回归
```

验收清单见 [`V3_ACCEPTANCE_CHECKLIST.md`](./V3_ACCEPTANCE_CHECKLIST.md)。

## 目录结构

- `apps/h5-user` · `apps/h5-shop` · `apps/h5-partner` — 三端 H5（Vite + React）
- `packages/shared-types` · `packages/domain` — 共享契约与纯函数
- `server/dukang-api` — NestJS 单体 API
- `pages/` — UI 原型（从 Stitch「4端1.0版本」同步）
  - `pages/user/` · `pages/shop/` · `pages/partner/` — 各端 screen 的 `code.html` + `screen.png`
  - `pages/ROUTE_MAP.md` — screen ↔ 路由对照
  - `pages/stitch_4_1.0/DESIGN.md` — 设计系统
- `packages/shared-ui` — 三端共享设计令牌与组件

## 同步 Stitch 原型

从 Google Stitch 共享项目「4端1.0版本」拉取最新 HTML/截图：

```bash
# 设置 API Key（或使用 ~/.cursor/mcp.json 中的 stitch 配置）
set STITCH_API_KEY=your-key
pnpm sync:stitch
# 强制重新下载
pnpm sync:stitch -- --force
```

## Mock 开关（`.env`）

- `MOCK_SMS=true` — 固定验证码 123456
- `MOCK_PAY=true` — 同步支付成功并发券
- `MOCK_DELIVERY_AUTO=true` — BullMQ 自动推进配送状态
- `AUTO_APPROVE_STORE=true` — 合伙人录店自动审核通过