zhifu-platform/frontend

智服前端

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

运行

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

.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 指定默认开发店铺范围。

身份与数据

消费者、商家使用真实账户认证，平台使用独立平台身份接口。令牌只保存在内存，刷新后需要重新登录；两个后台退出相互独立。服务端每次检查账户状态及权限。会话过期后未提交表单只恢复给重新验证的同一账户，写操作需要用户重新检查并提交。

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

开发账户脚本只允许 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各类视口。

通过 FRONTEND_URL 指定地址，通过 PLAYWRIGHT_CHROMIUM_EXECUTABLE 指定 Chromium。验证结果见 验收记录。生成模型调用与本地向量验证分别记录。

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

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

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

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

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秒。