# YGChatCS 项目速览

本文档面向接手本仓库的 AI 编程助手。开始改代码前请先读这里，再按需深入具体文件。

## 项目定位

YGChatCS 是一个基于 uni-app + Vue 3 的多端应用，当前配置重点面向微信小程序。业务上以酒店/文旅场景的 AI 聊天助手为主，包含首页聊天、发现内容、商品/房型详情、订单、工单服务、快捷预订、WebView 桥接等模块。

## 技术栈

- 框架：uni-app 3、Vue 3、Vite 5。
- 状态管理：Pinia 3，使用 `pinia-plugin-unistorage` 做持久化。
- 样式：SCSS，公共工具类在 `src/static/scss/`，全局变量在 `src/uni.scss`。
- 多端：保留 H5、App、各类小程序脚本；当前微信小程序配置最完整。
- 组件生态：`src/uni_modules/` 中包含 DCloud 插件和第三方插件，如 `uni-popup`、`uni-icons`、`z-paging`、`zero-markdown-view`。

## 常用命令

包管理器字段声明为 Yarn 1：

```bash
yarn install
yarn dev:mp-weixin
yarn build:mp-weixin
yarn dev:h5
yarn build:h5
yarn switch-client zhinian
```

`package-lock.json` 和 `yarn.lock` 同时存在。除非任务明确要求，不要随意重生成或混改锁文件；优先遵循 `package.json` 的 `packageManager`。

## 关键入口

- `src/main.js`：创建 Vue/uni-app 应用，注册 Pinia；微信小程序环境注册 `utils/share`。
- `src/App.vue`：应用生命周期入口，`onLaunch` 会调用 `getEvnUrl()` 获取/设置服务地址，并调用 `refreshToken()` 刷新登录态。
- `src/pages.json`：页面与分包路由。主页面是 `pages/index/index`，分包包括 `pages-order`、`pages-service`、`pages-quick`、`pages-booking`、`pages-bridge`。
- `src/manifest.json`：uni-app 多端配置；微信小程序 `appid`、隐私权限、插件配置在这里。
- `project.config.json`：微信开发者工具项目配置，根级 `appid` 需要与 `src/manifest.json` 保持一致。
- `vite.config.js`：配置 `@` 指向 `src`，启用 `@dcloudio/vite-plugin-uni`，并对构建资源名做 md5/hash 处理。

## 目录地图

- `src/pages/`：主包页面和聊天相关组件。`pages/index/index.vue` 是首页壳，组合聊天主列表、日历、更多服务和抽屉。
- `src/pages/ChatMain/`：聊天主体验，包括顶部导航、欢迎区、输入区、消息卡片、长回答页、通知消息等。
- `src/pages/ChatModule/`：AI 工具调用渲染模块，例如快捷预订、发现卡片、地图、活动、推荐内容、长答案、图片/商品卡等。
- `src/pages/Discovery/`：发现页内容流和快捷问题。
- `src/pages/goods/`：商品/房型详情、相册、套餐、设施、日期选择和确认组件。
- `src/pages-order/`：订单列表、订单详情及订单卡片、二维码、状态、用户信息等组件。
- `src/pages-service/`：服务/工单订单列表。
- `src/pages-quick/`：快捷入口列表及卡片。
- `src/pages-booking/`：预订页面。
- `src/pages-bridge/`：上传图片、保存图片等桥接页面。
- `src/pages/webview/`：内嵌 WebView 页面及桥接脚本，`src/router/index.js` 会把外部 URL 包装到这里。
- `src/components/`：跨页面通用组件，如 `TopNavBar`、`Calender`、`ImageSwiper`、`TagsGroup`、`Stepper`、`CreateServiceOrder`、`Feedback` 等。
- `src/request/`：请求封装和 API 分组。
- `src/store/`：Pinia store，模块包括 `app`、`location`、`picture`、`selectedDate`。
- `src/constant/`：客户端配置、token key、事件常量、业务类型常量。
- `src/utils/`：WebSocket、流式/打字机、URL 参数、分享、更新等工具。
- `scripts/`：客户配置切换脚本。

## 请求、环境与登录

- `src/request/base/request.js` 是统一请求封装。相对 URL 会拼接 `useAppStore().serverConfig.baseUrl`，请求头会带 `clientId`、token 和位置信息。
- `src/request/base/baseUrl.js` 定义生产/测试 HTTP 和 WSS 地址。
- `src/request/base/config.js` 控制环境地址。`developVersion = true` 时直接使用测试地址；发布前需关注 `versionValue` 和 `developVersion`。
- `src/request/api/` 按业务拆分 API：登录、主页面数据、会话、商品、订单、工单、反馈、服务地址、文件上传、AI 流式接口等。
- 登录与 token 逻辑在 `src/hooks/useGoLogin.js`、`src/manager/LoginManager.js`、`src/constant/token.js`。token key 会按当前客户端类型隔离。
- HTTP 返回 `424` 时请求层会移除 token、发出登出事件，并跳转登录。

## AI 聊天与实时通信

- 主聊天列表在 `src/pages/ChatMain/ChatMainList/index.vue`，文件较大，是聊天状态、消息渲染、WebSocket 初始化和发送的核心。
- `src/utils/WebSocketManager.js` 是跨端 WebSocket 管理器，负责连接、重连、队列、发送和销毁。
- `src/request/api/AgentChatStream.js` 是微信小程序端的分块/流式请求封装，使用 `uni.request({ enableChunked: true })` 解析 SSE 风格数据；也提供 `stopAbortTask()` 终止当前请求。
- AI 返回的 `toolCall.componentName` 会在聊天列表中映射到 `ChatModule` 或通用组件。新增工具卡片时，通常需要同时改组件、渲染分支和数据结构处理。

## 多客户端配置

根目录 `client-configs.json` 保存多客户端配置：`zhinian`、`nianhelper`、`duohua`、`tianmu`。当前 `src/constant/base.js` 的 `getCurrentConfig()` 返回 `CLIENT_CONFIGS.zhinian`。

切换客户配置请使用：

```bash
yarn switch-client <client-name>
```

脚本 `scripts/update-appid.js` 会更新：

- `src/constant/base.js` 的当前客户端。
- `src/manifest.json` 的 `mp-weixin.appid`。
- `project.config.json` 的根级 `appid`。
- `src/uni.scss` 的主题色变量。

改配置时要保证这些文件同步，尤其是微信小程序 appid 与主题色。

## 样式约定

- `.editorconfig` 要求 2 空格、LF、UTF-8、去尾随空格；Markdown 不强制去尾随空格且不强制最终换行。
- 公共 SCSS 工具类集中在 `src/static/scss/index.scss` 及其拆分文件，很多页面依赖 `flex-*`、`w-*`、`h-*`、`px-*` 等类。
- 主题色变量在 `src/uni.scss`，会被 `switch-client` 自动改写。不要手工改一处忘记同步配置。
- 页面基本使用 `navigationStyle: "custom"`，导航栏通常由自定义组件实现。

## 编码与文本注意事项

当前终端读取部分中文注释、README 和字符串时显示为乱码，但项目文件声明为 UTF-8。修改这些文件时：

- 不要因为显示乱码就大面积重写注释或中文文案。
- 尽量只改任务相关代码块。
- 涉及中文展示文案时，在编辑器中确认真实编码和页面效果。

## 开发注意事项

- 优先使用 `@/` 别名引入 `src` 下模块。
- 不要直接改 `dist/`，它是构建产物。
- 不要随意改 `src/uni_modules/` 中第三方插件源码，除非任务就是修补插件行为。
- 新增页面必须同步 `src/pages.json`；新增分包页面要放入对应 `subPackages`。
- 需要持久化的全局状态优先放在 Pinia store，并按现有模块风格使用 `unistorage: true`。
- 网络请求优先新增到 `src/request/api/`，复用 `src/request/base/request.js`，不要在页面里散落裸 `uni.request`，流式/分块场景除外。
- 跳转外部 H5 优先使用 `src/router/index.js` 的 WebView 包装方式。
- 需要登录态的交互参考 `checkToken()`、`goLogin()` 和现有事件常量。

## 验证建议

仓库当前没有明确的测试脚本。完成修改后至少做对应平台构建或运行：

```bash
yarn build:mp-weixin
```

如果只改 H5 可补充：

```bash
yarn build:h5
```

涉及客户切换时，运行 `yarn switch-client <client-name>` 后检查 `src/manifest.json`、`project.config.json`、`src/constant/base.js`、`src/uni.scss` 的同步变化。