zhaoshang_client_ui

青浦区营商智能助手（zhaoshang-llm）

面向青浦区企业的政策匹配与办事指引智能助手前端。用户用自然语言提问，助手检索政策知识库， 以「开场概述 + 政策卡片 + 综合说明 + 参考资料」的形式给出有原文依据的回答；涉及具体企业时， 会先让用户确认公司主体，再结合工商信息给出针对性判断。

项目概述

业务能力

能力	说明
AI 对话	自然语言问答，流式返回；支持普通咨询、政策匹配、办事指引
政策卡片	按匹配度列出政策/服务事项，含支持对象、支持方式与标准、申报条件、原文引用
政策详情	卡片可展开详情，含条件核验、匹配依据、原文引用
参考资料	回答附引用来源，可展开查看来源机构、更新时间与介绍
公司补问	需要企业事实时，引导用户补充/确认公司主体，支持候选选择
语音输入	语音识别转文字后发送（ASR）

技术栈

• 框架：Vue 3（<script setup>）+ TypeScript + Vite 5
• UI：Ant Design Vue 4（经 unplugin-vue-components 按需自动引入）
• 状态：无 Vuex / Pinia。对话状态在 useBusinessAssistantChat 组合式函数内， 会话与消息持久化到 localStorage
• 流式：@microsoft/fetch-event-source（旧协议，保留未用）与原生 fetch + ReadableStream（现行）
• Markdown：marked；3D/语音：Three.js、alloyfinger

对话接口的关键约束

当前使用新接口 POST /api/chat（SSE）。两条最容易踩的规则：

1. 请求体只接受 {thread_id, question} 两个字段，多一个返回 422。 旧协议的 transmission.files / file_pos 发不出去（这是"文件上传"功能待定的原因）。
2. 前端不直接渲染新协议。src/components/api-chat-coordinator.ts 是协议适配层， 把新协议的 SSE 事件翻译成既有渲染组件能识别的内容标记： <scope> / <!-- POLICY_TABLE --> / <ref_links> / <question-cards>。 渲染层（BusinessRecord / PolicyMatch / QuestionCard / ScopeContent）不需要感知新协议。

接口契约与字段释义见 docs/reference/（索引在该目录 README）。 其中 legacy/API.md 是交接时的代码快照，不是规格、不会更新，不要照着它实现新功能。

开发与构建

npm install

npm run dev            # 开发服务器 → https://localhost:8083
npm run build          # 生产构建（提交前必过）
npm run build:test     # 测试环境构建
npm run build:qingpu   # 青浦环境构建 + 打包 zip
npm run test           # jest（可选）
bash harness/init.sh   # 安装依赖 + 基础验证 + 打印启动命令

开发环境注意：

• dev server 为 HTTPS（自签证书），浏览器首次访问会有证书告警，属正常现象
• 聊天接口走同源代理 /chat-api → http://192.168.2.23:8000（见 vite.config.ts）。 代理由服务端发起，因此局域网同事访问也不会有混合内容或跨域问题
• 生产环境 vite 代理不生效，需由 nginx 做等价转发，否则同样会被浏览器拦截

环境变量

变量	用途
VITE_API	主业务 API 网关
VITE_CHAT_API	新对话接口。兼容两种写法：服务前缀（/chat-api、http://host:8000）会自动追加 /api/chat；已是完整地址则原样使用
VITE_MODEL_SERVER	模型服务
VITE_ASR / VITE_STREAM_SERVER	语音识别 / 流媒体

目录结构

src/
├── components/
│   ├── Chat/                    消息渲染、政策卡片、问卷等
│   ├── Common/                  通用组件（MediaViewer、ScrollList、Toast…）
│   ├── business-assistant/      对话编排（useBusinessAssistantChat 等）
│   ├── api-chat-coordinator.ts  ★ 新协议适配层
│   └── stream-message-coordinator.ts  旧协议实现（保留未用，勿改）
├── network/api/                 接口封装（chat-sessions、enterprise、assistant-statistics…）
├── types/                       TypeScript 类型定义
├── utils/                       工具（runtime-config、stream-xml-filter、scope-record-rows…）
└── three-libs/                  Three.js 相关（ASR 等）

harness/                         agent 长时开发的工作流文件（见下）
docs/reference/                  接口契约与参考资料

Agent 工作流（harness）

本仓库用 harness/ 管理长时开发状态，解决多轮会话的上下文断裂、半成品、假完成等问题。 这些文件不会自动维护，规则写在 CLAUDE.md 的「Harness 工作流」一节：

• 开工先读 harness/claude-progress.md 与 harness/feature_list.json
• 同一时间只做一个功能；没有可运行证据不得声称完成
• 每次改动完成后立刻更新记录，不要攒到会话结束

后续新增改动的参考规范

后续新增改动，参考「华新镇产权单位和企业信息采集小程序」20260909 版本的工程实践。 该版本做了如下升级，可作为本仓库后续重构的对照基准：

构建工具与技术栈升级

• 构建从 Vue CLI（vue-cli-service）+ Babel 迁移到 Vite
• 源码从 JavaScript 全量改写为 TypeScript，接入 vue-tsc 类型检查
• 移除 core-js / babel 相关依赖

目录结构分层重构

目录	说明
api	后端接口封装（auth、content）
composables	可复用逻辑（表单、草稿、提示、滚动定位）
constants	集中管理 API 基地址、栏目 id、模型 id 等常量
layouts	页面框架布局（TabBarLayout）
stores	Pinia 状态管理
styles	抽离的全局样式（style.css、form.css）
types	TypeScript 类型定义（property、enterprise 等）
utils	通用工具（request、crypto、format、validators）

状态管理改造

• 引入 Pinia，新增 auth store 统一维护登录态（token / user）
• 登录不再持久化明文密码，并清理历史遗留的 password

路由改造

• 抽出 TabBarLayout 作为主框架，home / property / enterprise / myrecord 改为嵌套子路由
• 页面组件改为按需懒加载
• 新增全局前置守卫：受保护页面（requiresAuth）未登录时跳转登录页并携带 redirect

巨型页面拆分

视图只保留页面骨架，表单逻辑抽离为 composable + 子组件：

• EnterprisePage 由 2586 行精简至 333 行，逻辑抽离到 useEnterpriseForm， 拆出 LocationEditor、YearlyMoneyList 组件
• PropertyPage 由 2144 行精简至 288 行，逻辑抽离到 usePropertyForm， 拆出 BuildingCard、FloorCard、OperatorList 组件

通用组件沉淀

新增 FormField、RadioGroup、CheckboxGroup、SearchSelect、PageHeader、SuccessToast 等通用组件。

通用逻辑沉淀（composables）

composable	作用
useDraft	进入「查看」前保存草稿快照、退出时还原
useSuccessToast	统一的成功提示
useScrollToError	校验失败时滚动定位到错误项

接口层统一封装

• 新增 utils/request 统一 axios 实例（内容平台基地址、urlencoded、请求拦截自动携带 Token）
• api/auth、api/content 统一封装登录与内容平台的增删改查

对照本仓库时的注意：本项目是单模块 Vue 应用，且目前没有引入任何状态管理库 （对话状态在 useBusinessAssistantChat 里）。上文的分层与 Pinia 改造适用于多页面小程序形态， 本项目是否需要照搬，应按实际规模判断，不要为了对齐而引入用不上的依赖。

相关文档

位置	内容
CLAUDE.md	项目架构说明 + agent 工作流规则
docs/reference/	接口契约（现行 api-chat.md、字段对照、legacy 快照）
harness/	进度日志、功能清单、启动脚本、评审表

CHANGE LOG

https://awbm.feishu.cn/docx/O2mVdW5q3oqhLGxzEdbcniIKnYb