feat:新增数据库初始文件与更新README.md文件

README.md

@@ -28,60 +28,49 @@
 - 前端：Vue 3、TypeScript、Vite、pnpm workspace。
 - 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。
 
-第二阶段使用独立的 `insurance_s2_*` 数据库，并通过阶段继承脚本延续第一阶段真实业务数据。
+第二阶段使用独立的 `insurance_s2_*` 数据库。压缩包内的第二阶段 SQL 已包含从第一阶段继承后的业务数据，但只会重建第二阶段数据库。
 
 ## 首次初始化
 
-先启动本地 MySQL 8 和 Redis，并准备 Python 3.12、uv、Node.js 22、pnpm。
+第二阶段的数据库快照、Milvus 初始化入口和完整启动说明统一保存在：
 
-项目读取 `backend/.env`。确认其中的 MySQL、Redis、DeepSeek、LangSmith 和本地安全密钥后，先在项目根目录导入第一、二阶段完整 MySQL 快照：
+[database/项目启动文档与数据准备.zip](database/项目启动文档与数据准备.zip)
 
-```powershell
-mysql --host=127.0.0.1 --port=3306 --user=root --password --default-character-set=utf8mb4 --execute="source database/zhibaotong-stage1-stage2-mysql.sql"
-.\scripts\seed-knowledge.ps1
+首次运行时，将该压缩包解压到三个阶段项目的共同父目录。解压后应形成以下结构：
 
-Set-Location frontend
-pnpm install --frozen-lockfile
-Set-Location ..
+```text
+new_harness/
+├── 01-zhibaotong-smart-enrollment/
+├── 02-zhibaotong-knowledge-services-analytics/
+├── 03-zhibaotong-lifecycle-workflow/
+└── 项目启动文档与数据准备/
 ```
 
-macOS：
-
-```bash
-mysql --host=127.0.0.1 --port=3306 --user=root --password --default-character-set=utf8mb4 < database/zhibaotong-stage1-stage2-mysql.sql
+随后打开压缩包内的 `项目启动文档与数据准备/智保通第一、二、三阶段启动指南.md`，按照“第二阶段：知识服务与运营分析”一节完成：
 
-cd backend
-uv run python -m zbt.commands.seed_knowledge
+1. 公共运行环境准备。
+2. 第二阶段 MySQL 快照导入。
+3. 后端与前端依赖安装。
+4. 第二阶段 Milvus 知识库初始化。
+5. 第二阶段统一启动。
 
-cd ../frontend
-pnpm install --frozen-lockfile
-cd ..
-```
+压缩包中的第二阶段 `mysql.sql` 只重建 `insurance_s2_core`、`insurance_s2_agent` 和 `insurance_s2_analytics`，并已包含从第一阶段继承后的业务数据。
 
-SQL 快照已包含管理员、角色、产品、业务员、推广码，以及多状态、多时间、
-多人员归因的订单、支付、保单和 Agent 运行数据。Milvus 向量集合仍通过
-`seed-knowledge.ps1` 单独初始化。
 
 ## 启动
 
 在项目根目录运行：
 
+Windows PowerShell：
+
 ```powershell
 .\scripts\dev.ps1
 ```
 
-macOS（两个终端）：
+macOS / Linux：
 
 ```bash
-# 终端一
-cd backend
-uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
-```
-
-```bash
-# 终端二
-cd frontend
-pnpm dev
+./scripts/dev.sh
 ```
 
 - H5：http://127.0.0.1:5173
@@ -106,12 +95,14 @@ LANGSMITH_PROJECT=智保通-第二阶段-知识服务与数据分析
 
 先启动整个项目，再在 `backend` 目录执行：
 
+Windows PowerShell：
+
 ```powershell
 uv run python -m zbt.commands.evaluate_agents --suite smoke
 uv run python -m zbt.commands.evaluate_agents --suite full
 ```
 
-macOS：
+macOS / Linux：
 
 ```bash
 uv run python -m zbt.commands.evaluate_agents --suite smoke
@@ -122,23 +113,18 @@ uv run python -m zbt.commands.evaluate_agents --suite full
 
 ## 质量门禁
 
+Windows PowerShell：
+
 ```powershell
 .\scripts\test.ps1
 ```
 
-macOS：
+macOS / Linux：
 
 ```bash
-cd backend
-uv sync --locked
-uv run pytest
-uv run ruff check .
-uv run mypy src/zbt
-
-cd ../frontend
-pnpm install --frozen-lockfile
-pnpm typecheck
-pnpm build
+./scripts/test.sh
 ```
 
 该脚本执行后端测试、Ruff、mypy、前端类型检查与双端生产构建。真实 MySQL/Redis 集成测试以及真实模型评测单独执行，避免普通代码检查意外消耗模型额度。
+
+所有 `scripts/*.ps1` 均提供同名的 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。

backend/README.md

@@ -1,150 +1,289 @@
-# 智保通后端
+# 智保通第二阶段后端
 
-本目录是智保通的统一后端，使用 Python 3.12 和 FastAPI 开发，负责 API、
-业务规则、身份认证及数据库访问。
+本目录是智保通第二阶段“知识服务与数据分析”的统一后端。项目完整继承第一阶段的智能投保、订单、支付、保单、推广归因和后台治理能力，并在同一个 Agent Kernel 上增加 **Agentic RAG、客户长期记忆、多模态材料识别、保单服务和运营趋势分析**。
 
-## 技术栈
+后端采用 Python 3.12、FastAPI 和 `src/zbt` 可安装包布局，通过 uv 管理依赖和虚拟环境。
 
-- Python 3.12
-- FastAPI、Pydantic
-- SQLAlchemy、Alembic
-- LangChain 1.x、DeepSeek、LangSmith
-- MySQL 8、Redis
-- uv（依赖与虚拟环境管理）
-- pytest、Ruff、mypy（测试与代码检查）
+## 1. 第二阶段新增能力
+
+### H5 客户端
+
+- Agentic RAG 保险咨询：复杂问题拆分、查询改写、多轮检索和证据聚合。
+- 有依据时展示知识来源；知识库未明确时拒绝推测。
+- 客户长期记忆：保存明确表达的保障偏好，在新会话中召回并支持删除。
+- 敏感信息保护：手机号、身份证号、银行卡号等内容禁止写入长期记忆。
+- 保单服务：从保障中的保单发起申请，上传图片并使用多模态模型识别材料。
+- 服务记录：查看申请状态和运营处理结果。
+
+### 运营管理端
+
+- 知识中心：`上传/创建 → 索引 → 检索测试 → 发布`。
+- 检索测试记录持久化；发布前必须存在有效的检索测试记录。
+- 服务申请中心：查看原始材料、识别字段和识别可信度，并进行受理或不受理处理。
+- 运营智能体：分析订单量、订单保费、有效保单量和有效保单保费。
+- 趋势分析：支持最近 7、30、90 天，并按日期或产品生成图表数据。
+- Agent 历史会话和运行记录按用户、人格与权限范围隔离。
 
-项目使用 `pyproject.toml` 和 `uv.lock` 管理依赖，不使用
-`requirements.txt`、Poetry 或 Conda。
+## 2. Agent 技术架构
 
-## 目录结构
+项目保留“一个内核、两种人格”的设计：
+
+- `customer`：客户保障顾问，负责保险咨询、投保引导、知识问答和客户记忆。
+- `operation`：运营数据助手，负责业务指标、趋势和推广归因分析。
+- Agent Kernel：统一管理 Persona、Skill、Tool 白名单、策略校验、结构化 UI Block、运行事件和异常边界。
+
+主要调用链：
+
+```text
+HTTP 请求
+  → AgentThreadService
+  → Agent Kernel
+  → Persona + Skill + Policy
+  → LangChain create_agent
+  → DeepSeek
+  → 受控业务 Tool / 知识检索 Tool
+  → 结构化响应
+  → MySQL 运行记录 + Redis 热状态 + LangSmith Trace
+```
+
+知识检索链路：
+
+```text
+问题拆分与改写
+  → BGE-M3 向量化
+  → Milvus 向量召回 + 关键词召回
+  → BGE Reranker 重排
+  → 证据聚合与去重
+  → 带来源回答或拒绝推测
+```
+
+医疗材料识别通过阿里云百炼兼容接口调用 `qwen3.5-plus`，识别结果作为候选字段保存，不能替代用户确认和运营处理。
+
+## 3. 目录结构
 
 ```text
 backend/
-├── src/
-│   └── zbt/               # 可安装的智保通 Python 包
-│       ├── api/           # HTTP 路由、请求参数和响应格式
-│       ├── commands/      # 初始化数据等命令行工具
-│       ├── core/          # 配置、安全、密码和公共错误
-│       ├── domains/       # 业务模型、仓储接口和业务服务
-│       ├── harness/       # Agent 内核、策略和资源
-│       ├── infrastructure/# MySQL、Redis、Milvus 等基础设施实现
-│       └── main.py        # FastAPI 应用入口
-├── migrations/            # 三个数据库的 Alembic 迁移
-├── tests/                 # 自动化测试
+├── src/zbt/
+│   ├── api/                 # FastAPI 路由、鉴权和响应封装
+│   ├── commands/            # 数据、知识库和评测命令
+│   ├── core/                # 配置、安全、错误和公共能力
+│   ├── domains/             # 投保、Agent、知识、记忆、服务申请等领域
+│   ├── harness/             # Agent 内核、Persona、Skill、Policy 和结构协议
+│   ├── infrastructure/      # MySQL、Redis、Milvus 和外部模型适配器
+│   └── main.py              # FastAPI 应用装配入口
+├── migrations/              # Core、Agent、Analytics 三库迁移
+├── evals/                   # 真实模型评测数据
+├── tests/                   # 自动化测试
+├── var/                     # 本地服务材料等运行文件
 ├── alembic.ini
 ├── pyproject.toml
 └── uv.lock
 ```
 
-项目采用 `src` 布局，`uv sync` 会以可编辑模式安装 `zbt` 包；执行
-`uv build` 可以生成 wheel 和源码包。
+## 4. 运行环境
 
-代码主要调用方向：
+需要提前安装并启动：
 
-```text
-HTTP 请求 → api 路由 → domain service → repository → MySQL
+- Python 3.12
+- uv
+- MySQL 8
+- Redis
+- Milvus
+- Node.js 22 和 pnpm（启动前端时需要）
+
+后端读取 `backend/.env`。主要配置包括：
+
+| 配置类别 | 环境变量 |
+|---|---|
+| MySQL | `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、三个 `MYSQL_*_DATABASE` |
+| Redis | `REDIS_URL`、`REDIS_PREFIX` |
+| Milvus | `MILVUS_URI`、`MILVUS_TOKEN`、`MILVUS_COLLECTION_PREFIX` |
+| 向量模型 | `BGE_M3_MODEL_PATH`、`BGE_M3_DEVICE`、`BGE_RERANKER_MODEL_PATH`、`BGE_RERANKER_DEVICE` |
+| 文本模型 | `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL` |
+| 多模态模型 | `DASHSCOPE_API_KEY`、`DASHSCOPE_BASE_URL`、`DASHSCOPE_VISION_MODEL` |
+| 可观测性 | `LANGSMITH_TRACING`、`LANGSMITH_API_KEY`、`LANGSMITH_ENDPOINT`、`LANGSMITH_PROJECT` |
+| 安全配置 | `JWT_ACCESS_SECRET`、`JWT_REFRESH_SECRET`、`FIELD_ENCRYPTION_KEY` |
+
+如尚未创建 `.env`：
+
+Windows PowerShell：
+
+```powershell
+Set-Location backend
+New-Item -ItemType File -Path .env -ErrorAction SilentlyContinue
+notepad .env
 ```
 
-AI Agent 的主要调用方向：
+macOS：
 
-```text
-Agent API → Agent service → LangChain create_agent
-          → DeepSeek（OpenAI 兼容接口）→ 产品目录 Tool
-          → Agent MySQL 持久化 + LangSmith Trace
+```bash
+cd backend
+touch .env
+open -e .env
 ```
 
-## 环境配置
+不要将包含真实数据库密码和模型密钥的 `.env` 提交到 Git。
+
+## 5. 首次初始化
+
+第二阶段首次运行所需的数据库快照、Milvus 初始化脚本和启动说明统一保存在：
 
-后端读取当前 `backend` 目录中的 `.env`。
+[../database/项目启动文档与数据准备.zip](../database/项目启动文档与数据准备.zip)
 
-首次使用时，在 `backend` 目录创建并配置 `.env`：
+请将压缩包解压到三个阶段项目的共同父目录，并按照其中 `智保通第一、二、三阶段启动指南.md` 的“第二阶段：知识服务与运营分析”一节执行。该指南统一说明 Windows PowerShell 与 macOS/Linux 的依赖安装、MySQL 导入、Milvus 初始化和启动方式。
+
+压缩包中的第二阶段 `mysql.sql` 只初始化 `insurance_s2_core`、`insurance_s2_agent` 和 `insurance_s2_analytics`，并已包含第一阶段继承数据。不要再使用项目内旧 SQL，也不要额外执行 Alembic、`seed`、`inherit_stage_one` 或 `build_analytics`。
+
+## 6. 启动项目
+
+### 6.1 Windows 一次启动
+
+在项目根目录执行：
 
 ```powershell
-notepad .env
+powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1
 ```
 
-常用配置包括：
+该脚本同时启动 FastAPI、H5 和运营管理后台。
 
-- `MYSQL_HOST`、`MYSQL_PORT`：MySQL 地址和端口
-- `MYSQL_USER`、`MYSQL_PASSWORD`：后端数据库账号
-- `REDIS_URL`：Redis 连接地址
-- `JWT_ACCESS_SECRET`、`JWT_REFRESH_SECRET`：登录令牌密钥
-- `DEV_FIXED_OTP`：开发环境固定验证码
-- `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODEL`：模型配置
-- `LANGSMITH_API_KEY`、`LANGSMITH_ENDPOINT`、`LANGSMITH_PROJECT`、
-  `LANGSMITH_TRACING`：Agent 链路追踪配置
-- `MOCK_PAYMENT_CALLBACK_SECRET`：本地模拟支付回调的 HMAC 签名密钥
+### 6.2 Windows 分别启动
 
-不要把包含真实密码和密钥的 `.env` 提交到 Git。
-
-## 安装后端依赖
+后端：
 
 ```powershell
 Set-Location backend
-uv sync --locked
+uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
 ```
 
-`uv sync --locked` 会按照 `uv.lock` 创建或更新 `.venv`，确保每台电脑安装
-相同版本的依赖。
+H5：
 
-## 初始化数据库
+```powershell
+Set-Location frontend
+pnpm dev:h5
+```
 
-请先启动 MySQL 8 和 Redis，然后在项目根目录执行：
+管理后台：
 
 ```powershell
-.\scripts\check-env.ps1
-.\scripts\init-databases.ps1
-.\scripts\migrate.ps1
-.\scripts\inherit-stage-one.ps1
-.\scripts\seed.ps1
-.\scripts\build-analytics.ps1
-.\scripts\verify-seed.ps1
+Set-Location frontend
+pnpm dev:admin
 ```
 
-这些脚本依次完成环境检查、创建数据库、建表、继承第一阶段持久化数据、
-写入第二阶段初始数据、构建分析数据和验证初始化结果。
+### 6.3 macOS / Linux 一次启动
 
-## 单独启动后端
+```bash
+./scripts/dev.sh
+```
+
+不要在 `frontend/apps/h5` 或 `frontend/apps/admin` 目录执行 `pnpm dev:h5`、`pnpm dev:admin`；这两个命令属于前端 workspace 根目录。
+
+### 6.4 运行地址
+
+- H5：<http://127.0.0.1:5173>
+- 管理后台：<http://127.0.0.1:5174>
+- Swagger：<http://127.0.0.1:8000/docs>
+- OpenAPI JSON：<http://127.0.0.1:8000/openapi.json>
+- 健康检查：<http://127.0.0.1:8000/api/v1/system/health/live>
+
+测试账号：
+
+- H5：`18800000001`，验证码 `147258`
+- 管理员：`admin / zaq1XSW@`
+- 运营人员：`operator01 / zaq1XSW@`
+- 审核人员：`reviewer01 / zaq1XSW@`
+
+## 7. 单独启动后端
+
+如果只调试 API，可只运行 FastAPI。
+
+Windows PowerShell：
 
 ```powershell
 Set-Location backend
-uv run uvicorn zbt.main:app --reload --host 127.0.0.1 --port 8000
+uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
 ```
 
-启动后访问：
+macOS：
 
-- API 文档：<http://127.0.0.1:8000/docs>
-- OpenAPI JSON：<http://127.0.0.1:8000/openapi.json>
-- 健康检查：<http://127.0.0.1:8000/api/v1/system/health/live>
+```bash
+cd backend
+uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
+```
 
-按 `Ctrl + C` 停止后端。
+后端启动时会预加载 BGE-M3 和 BGE Reranker。首次下载或首次载入模型时，终端可能长时间显示 Hugging Face 下载和权重加载信息；出现 `Application startup complete` 后再测试知识问答。
 
-## 测试和代码检查
+## 8. 真实模型评测
 
-在 `backend` 目录执行：
+先启动项目，再在 `backend` 目录执行。
+
+Windows PowerShell：
 
 ```powershell
-uv run pytest
-uv run ruff check .
-uv run mypy src/zbt
+uv run python -m zbt.commands.evaluate_agents --suite smoke
+uv run python -m zbt.commands.evaluate_agents --suite full
 ```
 
-也可以在项目根目录执行 `.\scripts\test.ps1`，同时检查前端和后端。
+macOS：
 
-## 数据库迁移
+```bash
+uv run python -m zbt.commands.evaluate_agents --suite smoke
+uv run python -m zbt.commands.evaluate_agents --suite full
+```
 
-项目使用三个相互独立的数据库：
+评测会调用真实文本模型、真实业务 Tool 和真实 HTTP 接口。启用 LangSmith 后，可在对应项目中查看运行 Trace 和评测记录。
 
-- `insurance_s2_core`
-- `insurance_s2_agent`
-- `insurance_s2_analytics`
+## 9. 测试和代码检查
 
-需要手动执行迁移时，在 `backend` 目录运行：
+Windows PowerShell（在项目根目录执行）：
 
 ```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1
+```
+
+macOS / Linux（在项目根目录执行）：
+
+```bash
+./scripts/test.sh
+```
+
+普通代码检查不会替代真实模型评测。涉及 Agent 决策、知识引用和 Tool 调用顺序的行为，应另外运行第 8 节的评测命令。
+
+## 10. 数据库迁移命令
+
+当前推荐使用完整 SQL 快照进行首次初始化。只有在开发新的表结构变更时，才需要手动执行 Alembic。
+
+Windows PowerShell 与 macOS 均在 `backend` 目录执行：
+
+```bash
 uv run alembic -c alembic.ini --name alembic_core upgrade head
 uv run alembic -c alembic.ini --name alembic_agent upgrade head
 uv run alembic -c alembic.ini --name alembic_analytics upgrade head
 ```
 
-已经发布的迁移文件不要直接修改；表结构发生变化时应新增 revision。
+已经发布的迁移文件不要直接修改；表结构发生变化时应创建新的 revision。
+
+## 11. 构建后端安装包
+
+Windows PowerShell：
+
+```powershell
+Set-Location backend
+uv build
+```
+
+macOS：
+
+```bash
+cd backend
+uv build
+```
+
+构建结果生成在 `backend/dist`，包括 wheel 和源码包。日常开发继续使用 `uv sync --locked` 和 `uv run`，无需手工安装构建产物。
+
+## 12. 相关文档
+
+- `../README.md`：第二阶段项目总览和快速启动。
+- `../docs/第二阶段新增能力与测试.md`：第二阶段新增业务及建议测试场景。
+- `../docs/智保通第一、二阶段启动指南.md`：两个阶段的完整启动说明。
+
+项目根目录中的每个 `scripts/*.ps1` 均提供同名 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。