fe5dd78632
- Implemented RecommendationListCard component for displaying a list of recommendations with titles, descriptions, and badges. - Created RoutePlanCard component to show route details, including nodes and tips, with a detailed view toggle. - Added ScenicImageCard component for showcasing images with optional captions. - Developed SharedVisual components: CardShell, BadgePill, MediaFrame, ActionRow, and DetailShell for reusable UI elements. - Introduced SCSS styles for all new components and updated existing styles for consistency. - Created test page to preview and interact with all components using mock data. - Added new utility classes for background colors, borders, colors, display, flex, font sizes, font weights, heights, positions, rounded corners, and widths.
137 lines
7.7 KiB
Markdown
137 lines
7.7 KiB
Markdown
# 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` 的同步变化。
|