# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

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

关键事实（避免误判）：

- **对话走新接口** `POST /api/chat`（SSE）。前端不直接渲染新协议，而是经适配层
  `src/components/api-chat-coordinator.ts` 翻译成既有渲染组件可识别的内容标记。
  详见下方「Core Systems」与根 README 的「对话接口的关键约束」。
- **没有 3D 虚拟人渲染**。`three` 仅用于粒子背景（`business-assistant-particle.ts`）；
  `src/three-libs/asr` 用于**语音识别**；`src/three-libs/metamaker` 是一份未被引用的 SDK 包。
- **没有状态管理库**（无 Vuex / Pinia）。对话状态在 `useBusinessAssistantChat` 内，
  会话与消息持久化到 `localStorage`。
- 接口契约见 `docs/reference/`（现行 `api-chat.md`；`legacy/API.md` 仅为交接快照）。

## Common Commands

```bash
# Development
npm run dev                    # Start dev server on port 8083 (HTTPS, self-signed)
npm run preview                # Preview production build

# Building
npm run build                  # Production build
npm run build:test             # Test environment build
npm run build:qingpu           # Qingpu environment build
npm run zip                    # Create ZIP for Qingpu deployment

# Testing
npm run test                   # Run Jest tests

# Linting (use VSCode or external tools)
# ESLint config at .eslintrc.js
```

## Architecture

### Main Entry
- `src/main.ts` - Application entry point, creates Vue app
- `src/App.vue` - Root component, renders the 招商助手
- `src/components/BusinessAssistant.vue` - 只做 PC / 移动端切换，不是主壳
- `src/components/BusinessAssistantPC.vue` / `BusinessAssistantMobile.vue` - 真正的页面主壳
  （输入区、消息列表、滚动与打字机联动都在这里）

### Key Directories
- `src/components/Chat/` - 消息渲染与政策卡片（BusinessRecord、PolicyMatch、QuestionCard…）
- `src/components/Common/` - 通用 UI 组件（MediaViewer、ScrollList、Toast…）
- `src/components/business-assistant/` - 对话编排（`useBusinessAssistantChat`、上传、滚动等）
- `src/network/api/` - 接口封装：`chat-sessions.ts`、`enterprise.ts`、
  `assistant-statistics.ts`、`card/`（**没有** chat / faq / finance / group / human / project 这些文件）
- `src/types/` - TypeScript 类型定义
- `src/utils/` - 工具（`runtime-config`、`stream-xml-filter`、`scope-record-rows`…）
- `src/three-libs/asr/` - 语音识别（Three.js 相关代码只在这里和粒子背景中用到）

> 注意：**没有 `src/hooks/` 目录。**

### Core Systems
- **对话协议适配（现行）**: `src/components/api-chat-coordinator.ts` —— 新接口 `POST /api/chat`
  的客户端。把 SSE 事件翻译成 `<scope>` / `<!-- POLICY_TABLE -->` / `<ref_links>` /
  `<question-cards>` 等标记，交给既有渲染组件；渲染层不感知新协议。
- **旧协议实现（保留未用，勿改）**: `src/components/stream-message-coordinator.ts`。
  **没有 `stream-message-coordinator-v2.ts` 这个文件。**
- **State Management**: 无状态管理库（无 Vuex / Pinia）；状态在组合式函数 + `localStorage`
- **UI Library**: Ant Design Vue 4.x
- **Three.js**: 0.143.0（粒子背景 + 语音识别相关，非 3D 虚拟人）

### Build Configuration
- Vite build config: `vite.config.ts`
- Environment files: `.env.development`, `.env.production`, `.env.test`, `.env.qingpu`
- Uses unplugin-vue-components for auto-importing Ant Design Vue components

### CI/CD
仓库内**没有** `.gitlab-ci.yml` 等流水线配置文件；构建入口就是上面的 npm scripts。
若存在服务端流水线（GitLab / Gitea 后台配置），其规则请在服务端查看，不要以旧描述为准。

### API Proxies (dev mode)
- `/api/*` → `http://aixq.shqp.gov.cn`
- `/chat-api/*` → `http://192.168.2.23:8000`（**新对话接口**；`rewrite` 去掉 `/chat-api` 前缀，
  最终请求 `…/api/chat`。仅 dev server 生效，生产需 nginx 等价转发）
- `/asr/*` → `https://human-screen-v3.metamaker.cn`
- `/stream/*` → `https://flv-enc.metamaker.cn`

## Notes

- Uses `@` alias for `src/` in imports
- Three.js has special alias to `three/build/three.cjs`
- SCSS API set to "modern-compiler" in vite.config.ts
- No ESLint run in CI (build only)

## Harness 工作流（必须遵守）

本仓库用 `harness/` 目录管理长时开发的状态。**这些文件不会自动维护——你必须按下面的要求读和写。**
详见 `harness/README.md`。

### 每轮开工时

1. `pwd` 确认在仓库根目录
2. 读取 `harness/claude-progress.md`（当前已验证状态 + 上一轮记录）
3. 读取 `harness/feature_list.json`（功能清单与状态）
4. `git log --oneline -5` 查看最近提交（若仓库尚无提交，跳过即可）
5. 运行 `bash harness/init.sh`
6. 然后**只选择一个**未完成功能，围绕它工作，直到它验证通过、或被明确记录为 `blocked`

### 规则

- **每次改动完成后立刻更新记录，不要攒到会话结束。** 一轮会话常含多次改动，
  攒到最后必然漏记、并让已写下的描述过期（真实发生过：一次改动没记，
  记录里还留着后来被推翻的旧结论）。改动完当场追加 session 记录 / 更新功能状态。
- 同一时间只能有一个 `in_progress` 功能
- 没有可运行证据（构建或测试的实际输出）时，不要声称完成
- 不要通过重写功能清单来隐藏未完成的工作
- 不要为了让状态好看而删除或削弱验证步骤
- **仓库内文件是唯一事实来源**——不要把结论只留在聊天里

### 完成门槛

只有在要求的验证成功、且结果被记录进 `harness/feature_list.json` 的 `evidence`
与 `harness/claude-progress.md` 之后，功能状态才可以切到 `passing`。

### 结束前

- 更新 `harness/claude-progress.md`（追加一条 session 记录）
- 更新 `harness/feature_list.json` 的状态与证据
- 记录仍然损坏或未验证的内容
- 过一遍 `harness/clean-state-checklist.md`
- 给下一轮会话留下干净的重启路径

### 本项目的额外约束

- **界面样式必须与原版一致。** 新协议能力通过 `src/components/api-chat-coordinator.ts`
  翻译成既有渲染组件能识别的内容标记（`<scope>` / `<!-- POLICY_TABLE -->` /
  `<ref_links>` / `<question-cards>`），不要新建带自有样式的 UI 组件。
- **既有 UI 的可选项、文案、筛选逻辑不要擅自改动**——确需变更先取得确认。
- `src/components/stream-message-coordinator.ts` 是保留的旧协议实现，当前未被使用，**不要改动**。
- 需要确认"原来是怎么做的"时，diff 备份目录 `F:\yysk\AI_zhaoshang\备份\zhaoshang-llm`
  （早于所有改动），不要凭记忆断言。

### 接口文档在哪

- **改任何聊天相关代码之前，先读 `docs/reference/api-chat.md`（现行契约）** 与
  `docs/reference/api-chat-fields-zh.md`（字段中英对照）。索引见 `docs/reference/README.md`。
- `docs/reference/legacy/API.md` 是**交接时根据当时的源码生成的快照**，不是规格、不会更新。
  **不要照着它实现新功能**（现行契约看 `api-chat.md`），
  **也不要拿它当"原来行为是什么"的判据**——它是二手整理可能失真；
  判断原行为请直接 diff 备份目录里的源码。