# 杜康好客 · 前端 Apps AGENTS.md

> 父级：[`../AGENTS.md`](../AGENTS.md) · 路由映射：[`../pages/ROUTE_MAP.md`](../pages/ROUTE_MAP.md)

## App 一览（preV1）

| App | 端口 | X-Client-App | 负责人 | 原型 |
|-----|------|--------------|--------|------|
| `h5-user` | 5173 | `USER_H5` | jacy-dukang | `pages/user/` |
| `mini-user` | 5177 / weapp | `USER_MINI` | jacy-dukang | `pages/user/`（V3 目标形态） |
| `h5-shop` | 5174 | `SHOP_H5` | 刘景尧 | `pages/shop/` |
| `h5-partner` | 5175 | `PARTNER_H5` | 刘景尧 | `pages/partner/` |
| `admin-web` | — | （Admin JWT） | jacy-dukang | preV1 内部 HQ 替代 |

V3 目标：C 端交付为微信小程序 `apps/mini-user`（当前与 `h5-user` 并行；功能以 H5 为过渡参考）。
V2 规划中的 `mini-partner` / `mini-hq` 非 V3 主交付。

## 前端硬规则

- 请求基址 `/api/v1`；Header：`Authorization` + `X-Client-App`
- 类型从 `@dukang/shared-types` import，禁止复制枚举字符串
- 禁止 import `server/` 或另一个 `apps/*` 的源码
- UI 共享组件优先 `@dukang/shared-ui`
- C 端订单列表 **3 Tab**：`待付款 | 已付款 | 已完成`（Tab key: `pending_pay` / `paid` / `completed`）

## 新页面 workflow

1. 在 `pages/ROUTE_MAP.md` 查 Stitch screen ↔ route
2. 对照 `pages/{端}/*/code.html` + `screen.png`（只读参照）
3. 在对应 App 的 `src/pages/` 实现；API 封装放 `src/lib/api.ts`
4. 登录态：各 App 自有 Context/Storage，不跨 App 共享

## 各 App 职责边界

### h5-user（jacy-dukang）

主链路：登录 → 首页/详情 → 下单 Mock 支付 → **3 Tab** 订单 → 权益 → 核销码 → 门店列表

**勿改**：门店核销确认 UI（属 h5-shop）、合伙人录店（属 h5-partner）

### h5-shop（刘景尧）

主链路：门店登录 → 首页 → 扫码/输入核销 → 确认 → 记录 → 营业状态

**勿改**：C 端出码页面（属 h5-user）

### h5-partner（刘景尧）

主链路：登录 → 工作台 → 录店 → 门店列表 → 辖区订单 → Mock 推进配送（preV1）

**勿改**：C 端商品/订单页、总部报表（admin-web / V2 mini-hq）

### admin-web（jacy-dukang，preV1 限定）

内部 Web 管理：开城、商品、订单、门店审核、结算查看。**不是** V2 总部小程序规格。

变更 admin-web 时勿假设与 `pages/hq/` 原型 1:1；V2 需另建 `mini-hq`。

## 启动

```bash
pnpm dev:user | dev:shop | dev:partner | dev:admin
pnpm dev:mini-user          # C 端小程序 H5 预览 :5177
pnpm dev:mini-user:weapp    # 微信开发者工具打开 apps/mini-user/dist
```