# 智服前端

Vue 3 与 Vite 工程，提供消费者 H5、商家后台和平台后台，页面功能与视觉遵循 `docs/design/wireframes` 已确认设计。后台使用 Element Plus，H5 使用 Vant，图标通过 `@lucide/vue` 具名导入。

## 运行

在项目根目录执行数据库迁移和数据准备：

```powershell
.venv/Scripts/python.exe -m alembic upgrade head
.venv/Scripts/python.exe scripts/prepare_frontend_accounts.py
.venv/Scripts/python.exe scripts/prepare_storefront_data.py
.venv/Scripts/python.exe scripts/prepare_platform_data.py
$env:DEEPSEEK_API_KEY = [Environment]::GetEnvironmentVariable('DEEPSEEK_API_KEY', 'User')
.venv/Scripts/python.exe -m uvicorn zhifu.app:create_app --factory --host 127.0.0.1 --port 18000
```

在 `frontend` 目录执行 `npm ci`、`npm run dev`，访问 `http://127.0.0.1:18762`。`npm run build` 生成生产文件；`npm run preview` 在18763端口预览。

环境配置参考 `.env.example`，本地覆盖使用 `.env.local`。`API_TARGET` 为后端地址，默认18000端口；Vite 转发 `/openapi` 和 `/admin`。发布环境也需转发这两个路径。`VITE_TENANT_ID` 和 `VITE_STORE_ID` 指定默认开发店铺范围。

## 身份与数据

消费者、商家使用真实账户认证，平台使用独立平台身份接口。三个入口在当前标签页的 `sessionStorage` 中分别保存令牌、到期时间和展示用账户名称；刷新后通过各自的 `auth/me` 接口重新验证身份和权限，再显示原有授权页面。恢复期间不显示业务内容，网络失败时可以点击“重新验证登录”。会话到期、被撤销或主动退出时清除对应入口的凭据，其他入口保持独立。密码、角色、权限和业务数据不写入存储。会话过期后，当前页面内存中的未提交表单只恢复给重新验证的同一账户，写操作需要用户重新检查并提交。

数据范围见 [前端数据来源](data-sources.md)。服务端保存商品、规则草稿、发布配置、员工邀请、渠道配置、通知、身份验证和平台管理记录。订单、工单、审批、知识和费用继续使用相同业务服务。

开发账户脚本只允许 development 或 test 环境，将凭据保存到 `.work/frontend-accounts.json`，账户为 customer01、staff01、supervisor01、admin01、finance02。平台账户保存到 `.work/platform-accounts.json`，渠道 SERVICE 账户保存到 `.work/storefront-channel.json`。密码不写入日志、URL或浏览器存储。售后验证要求订单观察时间在最近五分钟内，验证前再次执行开发账户准备命令。

## 验证

页面完成后统一执行真实浏览器黑盒与功能测试，通过点击、输入、URL、公开 DOM 和 HTTP 响应验证功能，不读取 Vue 内部状态，不使用截图。

`npm run test:functional` 执行消费者、平台、全部页面布局、会话、组件及商家业务检查，同时验证入口数据隔离、平台草稿恢复和真实登录限流。也可分别执行 `test:customer`、`test:merchant`、`test:business`、`test:sessions`、`test:platform`、`test:layout` 和 `test:components`。`test:responsive` 验证H5各类视口。

`npm run test:session-refresh` 使用真实身份接口验证三个入口刷新后恢复原页面、独立保存会话、主动退出、服务端撤销、网络连接中断后的手动恢复，以及浏览器缓存中的身份和权限字段不生效。只创建并撤销测试登录会话，不修改业务数据，不调用生成模型；总时限180秒，API请求最多500次，全部资源请求最多3000次，结果写入 `.work/frontend-verification/session-refresh.json`。

通过 `FRONTEND_URL` 指定地址，通过 `PLAYWRIGHT_CHROMIUM_EXECUTABLE` 指定 Chromium。验证结果见 [验收记录](../docs/verification/frontend-backend.md)。生成模型调用与本地向量验证分别记录。

`node tests/merchant-release.mjs` 通过真实知识发布和Agent配置发布验证成功流程，要求API进程读取有效的模型配置与凭据。该专项保留已发布的开发店铺服务资料和配置版本，不执行生成模型请求。

`node tests/merchant-conversation.mjs` 验证客服读取关联订单与工单、接管、回复、修订方案、客户确认、释放接管及主管决定。`node tests/merchant-configuration.mjs` 验证知识与规则保存、发布和撤回。这些业务用例顺序运行，执行前更新开发订单观察时间。

`node tests/customer-model.mjs` 单独验证真实模型答复返回浏览器，最多进行三次供应商尝试。运行条件、输出与时间限制见 [浏览器真实模型专项](../docs/verification/frontend-model-check.md)。

`node tests/customer-sse.mjs` 验证真实 SSE 接管与回复、50秒自动续传、断网与手动恢复、页面切换释放、410状态恢复、三条账户连接额度以及令牌撤销。410场景通过运维命令推进本会话续传窗口，并仅提交一次过期请求游标，响应来自真实服务。总时限240秒，使用真实客服回复，不调用生成模型；结果写入 `.work/frontend-verification/customer-sse.json`。应与其他修改同一开发客户会话的测试顺序执行。接口及恢复规则见 [H5 消息连接与补充输入](data-sources.md#h5-消息连接与补充输入)。

`node tests/customer-waiting.mjs` 使用 `.work/frontend-waiting.json` 中的独立客户和真实等待运行，验证登录恢复、补充资料提交原运行、SSE本人消息及停止回复。准备过程需要执行 `request_clarification` 工具节点，运行时停止生成工作进程；脚本总限90秒，生成请求为零，结果保存到 `.work/frontend-verification/customer-waiting.json`。

`node tests/customer-stream-connect.mjs` 检查空闲会话建立订阅时立即收到响应，以及令牌撤销后的页面行为，总时限30秒。以上专项及现有消费者回归结果见 [H5会话事件验证](../docs/verification/h5-events.md)。

`node tests/customer-business-waiting.mjs` 使用 `.work/frontend-business-waiting.json` 的真实方案等待运行，验证普通聊天禁用、原方案页面本人确认、原运行等待审批、主管决定后的SSE状态和工单卡片更新。项目根目录运行 `scripts/prepare_browser_waiting.py --business` 准备资料，完成后运行同脚本的 `--business --cleanup` 停用专项账户并删除临时凭据。浏览器脚本通过 `python -m zhifu.modules.agent_runtime.business_wait --once` 处理持久业务事件，不启动生成工作进程；总时限120秒。