# 青浦区营商智能助手（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/`](docs/reference/)**（索引在该目录 README）。
其中 `legacy/API.md` 是**交接时的代码快照，不是规格、不会更新**，不要照着它实现新功能。

## 开发与构建

```bash
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`](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`](CLAUDE.md) | 项目架构说明 + agent 工作流规则 |
| [`docs/reference/`](docs/reference/) | 接口契约（现行 `api-chat.md`、字段对照、legacy 快照） |
| [`harness/`](harness/) | 进度日志、功能清单、启动脚本、评审表 |

## CHANGE LOG

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