# 杜康好客官网 — Agent 指南

面向后续开发者与 Cursor Agent：快速了解项目定位、改哪里、不能破坏什么。

## 项目定位

杜康好客品牌官网 / 发布会展项**单页**。核心主张「你请客，我买单」：买酒送等价好客权益，到合作门店抵餐。面向城市合伙人、合作门店与用户。

包名：`dukangguanwang`。无后端、无留资表单；联系方式为二维码 + 电话。

## 技术栈

| 层 | 选型 |
|----|------|
| UI | React 19 |
| 构建 | Vite 8 + `@vitejs/plugin-react` |
| 语言 | TypeScript（`tsc -b` 后构建） |
| Lint | Oxlint |
| 路由 / 状态库 / UI 库 | **无** — 保持精简，非必要不新增依赖 |

React Compiler 未启用（见 README）。

## 关键入口

| 文件 | 职责 |
|------|------|
| [`src/App.tsx`](src/App.tsx) | 全部章节 DOM、文案常量、导航、展控逻辑 |
| [`src/App.css`](src/App.css) | 设计 token、章节样式、展控覆盖 |
| [`src/index.css`](src/index.css) | 根排版、scroll-snap、`stage-mode` body |
| [`src/main.tsx`](src/main.tsx) | StrictMode 挂载 |
| [`index.html`](index.html) | `zh-CN`、站点 meta |

产品表面几乎全集中在 `App.tsx` + `App.css`。`src/assets/` 为模板残留，站点图请用 `public/assets/`。

## LP 章节（顺序固定）

`sections`、DOM `id`、`navItems`（及展控 dots/panel）**必须同步**。

| id | 标签 | 视觉族 |
|----|------|--------|
| `hero` | LP-H 首屏 | `poetic-section` |
| `brand` | LP-01 品牌传承 | `poetic-section` |
| `poetry` | LP-02 诗酒文化 | `poetic-section` |
| `qingxiang` | LP-03 清香宝典 | `poetic-section` |
| `haoke` | LP-04 好客模式 | `poetic-section` |
| `system` | LP-05 三端协同 | `poetic-section` |
| `tech` | LP-06 科技驱动 | `tech-section` |
| `subsidy` | LP-07 酒厂实力 | `tech-section` |
| `partner` | LP-08 城市合伙人 | `tech-section` |
| `tech-detail` | LP-09 科技板块 | `tech-section` |
| `contact` | LP-10 联系我们 | `tech-section` |

锚点导航：固定 `.topbar` + hash。普通模式用 IntersectionObserver 更新 `activeIndex`。

## 展控模式

- 入口：`?mode=stage` 或 `?mode=stage#sectionId`
- 行为：键盘翻页、点击区、圆点、可折叠面板、可选自动播放
- 样式：`body.stage-mode`、`.site.is-stage`，以及大量 `.is-stage …` 覆盖

**改布局或章节后，须同时验证普通浏览与展控。**

本地示例：`http://localhost:5173/?mode=stage#hero`

## 视觉语言（摘要）

`:root` 变量在 `App.css`：

- 国风：`--paper` / `--ink` / `--red` / `--gold`
- 科技：`--tech` / `--tech-card` / `--tech-line`
- 内容宽：`--max`

字体：标题偏宋体系（Noto Serif SC / Songti）；正文 Inter + 雅黑/苹方。设计基准约 1920 宽（`html` rem clamp）。章节多为 full-bleed 背景 + 纵向 scroll-snap。

## 静态资源

- 生产图：[`public/assets/`](public/assets/)（`bg-*.png`、T30 瓶身、印章/logo、二维码等）
- 引用路径：`/assets/...`
- [`public/assets/pdf-ref/`](public/assets/pdf-ref/)：PDF/设计参考，**不要挂进生产 UI**

## 常用命令

```bash
npm run dev      # Vite 开发
npm run build    # tsc -b && vite build
npm run preview  # 预览 dist
npm run lint     # oxlint
```

## 合规与文案

- 文案以中文为主，集中在 `App.tsx` 顶部常量与各 section JSX
- 保留页脚合规表述：理性饮酒、未成年人禁止饮酒、不构成收益承诺、细则以合作政策为准、ICP（`晋ICP备2026004970号`）
- 合作/补贴类表述勿写成收益承诺

## 开发约定（速查）

1. 优先改 `App.tsx` / `App.css`，不要为单页硬上路由或组件库。
2. 新增章节：选对 `poetic-section` 或 `tech-section`，并更新 `sections`、`navItems`、DOM `id`、展控 UI。
3. 动效沿用现有 `fadeRise` / `reveal-*` / `.is-entered`，勿堆无关装饰。
4. 更细的 Cursor 规则见 [`.cursor/rules/`](.cursor/rules/)。