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

README.md

@@ -1,100 +1,174 @@
 # 智保通（第三阶段：生命周期工作流）
 
-本项目完整包含前两个阶段的智能投保、知识服务、多模态材料识别、服务申请和运营分析，并新增退保试算、风险分流、人工审批、Worker 自动退款、技术失败重试、补偿和保单终止。
+第三阶段完整继承前两个阶段的智能投保、Agentic RAG、长期记忆、多模态材料识别、服务申请和运营分析能力，并新增退保试算、风险分流、人工审批、退款 Worker、失败重试、异常干预和保单终止。
 
 系统由本地 H5 公众号模拟器、PC 运营管理端和统一 FastAPI 后端组成。普通咨询继续使用 LangChain Agent；需要暂停、审批和恢复的长流程由 LangGraph 编排。
 
-## 主要能力
-
-- 一个 Agent 内核，客户保障顾问与运营数据助手两种人格。
-- H5 完成咨询、投保、支付、保单、服务申请和退保退款进度查询。
-- PC 端完成业务运营、知识管理、服务受理、退保审批和退款异常处理。
-- 退保金额与风险由确定性规则计算；低风险自动通过，高风险强制人工审批。
-- LangGraph 使用并行风险检查、条件分支、子图、Interrupt、Resume 和 MySQL Checkpoint。
-- 退款 Outbox Worker 使用租约、幂等、退避重试、死任务恢复和补偿。
-- 退款结算在单个 MySQL 事务中同步收口退款尝试、退保申请、保单和审计时间线。
-- Worker 抢锁失败后进入轻量待命，原实例退出或租约过期后自动接管。
-- 本地 MCP 服务只读提供合作医疗服务资源；异常时返回空结果，Agent 不得编造。
-- LangSmith 与 OpenTelemetry 记录 Agent、LangGraph、工具、审批和恢复轨迹。
-
 ## 项目结构
 
 ```text
 03-zhibaotong-lifecycle-workflow/
-├── backend/          # FastAPI、LangChain、LangGraph、Agent Harness
+├── backend/          # FastAPI、LangChain、LangGraph、Agent Harness、退款 Worker
 ├── frontend/
 │   └── apps/
 │       ├── h5/       # 本地 H5 公众号模拟器
 │       └── admin/    # PC 运营管理端
 ├── database/         # 第一至第三阶段完整 MySQL 初始化脚本
 ├── knowledge/        # 知识库初始化内容
-├── scripts/          # 启动、知识初始化、退款工作器和质量门禁
-└── docs/             # 业务、技术和使用说明
+├── scripts/          # 初始化、启动、知识入库和质量门禁
+├── docs/             # 业务、技术和测试说明
+└── README.md
 ```
 
-## 快速启动
+## 核心技术
+
+- Agent Harness：一个统一内核，客户顾问与运营助手两种人格。
+- Agent 运行时：LangChain `create_agent`、DeepSeek、Persona、Skill、Tool Registry、Policy Engine 和结构化协议。
+- 知识服务：Agentic RAG、BGE-M3、BGE Reranker、Milvus、知识引用聚合和拒绝推测。
+- 生命周期编排：LangGraph 条件分支、并行风险检查、子图、Interrupt、Resume 和 MySQL Checkpoint。
+- 退款执行：独立 Worker、Redis 单实例锁、任务租约、幂等、退避重试和异常恢复。
+- 多模态：阿里云百炼 `qwen3.5-plus` 识别服务申请材料。
+- 可观测性：MySQL Run 持久化、Redis 热状态、LangSmith Trace 和 OpenTelemetry。
+- 业务后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic。
+- 前端：Vue 3、TypeScript、Vite、pnpm workspace。
+- 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。
+
+## 第三阶段新增业务
+
+- H5 对保障中的保单进行退保试算并提交退保申请。
+- 确定性规则计算可退金额，Agent/工作流进行风险分析与流程分流。
+- 低风险申请自动进入退款流程，高风险申请暂停并等待运营人员审批。
+- 运营管理端查看退保申请、风险原因、流程时间线、退款尝试和 Worker 状态。
+- 审批不通过时处理意见必填；审批完成或流程结束后控制区不可重复操作。
+- 退款 Worker 自动领取任务，执行退款、记录尝试，并在达到重试阈值后转入人工干预。
+- 退款成功后终止保单；退款异常时保持可恢复状态，避免错误终止保障。
+- 本地 MCP 服务以只读方式向 Agent 提供合作医疗服务资源。
+
+## 首次初始化
+
+第三阶段的数据库快照、Milvus 初始化入口和完整启动说明统一保存在第二阶段项目提供的公共压缩包中：
 
-首次运行先按 [第一、二、三阶段启动指南](docs/智保通第一、二、三阶段启动指南.md) 完成依赖、MySQL 和 Milvus 初始化。
+[项目启动文档与数据准备.zip](../02-zhibaotong-knowledge-services-analytics/database/项目启动文档与数据准备.zip)
 
-日常可在项目根目录一次启动后端、H5、管理端和退款工作器：
+首次运行时，将压缩包解压到三个阶段项目的共同父目录，然后打开其中的 `项目启动文档与数据准备/智保通第一、二、三阶段启动指南.md`，按照“第三阶段：全生命周期工作流”一节完成环境准备、依赖安装、第三阶段 MySQL 导入、Milvus 初始化和统一启动。
+
+压缩包中的第三阶段 `mysql.sql` 只重建 `insurance_s3_core`、`insurance_s3_agent` 和 `insurance_s3_analytics`，并已包含前两个阶段继承后的业务数据。
+
+不要再执行项目内旧 SQL、迁移脚本、种子脚本或阶段继承脚本。数据库和 Milvus 的首次初始化以压缩包内指南为唯一入口。
+
+## 启动
+
+### Windows PowerShell
+
+在项目根目录运行：
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1
 ```
 
-macOS（两个终端）：
+### macOS / Linux
 
 ```bash
-# 终端一
-cd backend
-uv run zbt-serve
+./scripts/dev.sh
 ```
 
+`zbt-serve` 是跨平台后端主管进程，会分别启动 FastAPI 和退款 Worker。正常情况下不需要再执行 `zbt-refund-worker`。
+
+运行地址：
+
+- H5：<http://127.0.0.1:5173>
+- 管理后台：<http://127.0.0.1:5174>
+- API 文档：<http://127.0.0.1:8000/docs>
+
+测试账号：
+
+- H5：`18800000001`，验证码 `147258`
+- 管理员：`admin / zaq1XSW@`
+- 运营人员：`operator01 / zaq1XSW@`
+- 审核人员：`reviewer01 / zaq1XSW@`
+
+## 退款 Worker
+
+退款涉及资金副作用，因此 Worker 默认启用 Redis 单实例锁，避免本地误启动多个主动执行者。`zbt-serve` 启动后会同时监管 API 和 Worker；任一进程异常退出时，主管进程会停止另一个进程，避免后端处于部分可用状态。
+
+只有调试 Worker 时才单独运行：
+
+Windows PowerShell：
+
+```powershell
+.\scripts\run-refund-worker.ps1
+```
+
+macOS / Linux：
+
 ```bash
-# 终端二
-cd frontend
-pnpm dev
+./scripts/run-refund-worker.sh
 ```
 
-- H5：http://127.0.0.1:5173
-- 管理后台：http://127.0.0.1:5174
-- API 文档：http://127.0.0.1:8000/docs
+如果已有 Worker 持有单实例锁，新进程会进入待命或退出，不能同时领取退款任务。管理端“退保工作台”可以查看 Worker 在线状态、退款尝试和失败原因。
 
-H5 验证码为 `147258`；后台账号及完整操作路径见启动指南。
+## LangSmith
+
+在 `backend/.env` 中配置：
+
+```dotenv
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=你的密钥
+LANGSMITH_PROJECT=智保通-第三阶段-智能保全与退款编排
+LANGSMITH_OTEL_ENABLED=true
+```
+
+LangSmith 用于查看 Agent、Tool 和 LangGraph 执行链路；MySQL 中的 Run、工作流时间线和退款尝试仍是业务审计记录。
+
+## 真实模型评测
+
+先启动整个项目，再在 `backend` 目录执行。Windows PowerShell 和 macOS 使用相同命令：
+
+```bash
+uv run python -m zbt.commands.evaluate_agents --suite smoke
+uv run python -m zbt.commands.evaluate_agents --suite full
+```
+
+评测会调用真实模型、真实业务 Tool 和真实 HTTP 接口，并检查回答、工具覆盖、工作流行为和 Trace 关联。
 
 ## 质量门禁
 
+Windows PowerShell：
+
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\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、前端类型和双端生产构建。真实模型评测单独执行，避免普通代码检查意外消耗模型额度。
+
+## 构建后端安装包
+
+Windows PowerShell：
 
 ```powershell
-cd backend
-uv run python -m zbt.commands.evaluate_agents --suite smoke
-uv run python -m zbt.commands.evaluate_agents --suite full
+Set-Location backend
+uv build
 ```
 
 macOS：
 
 ```bash
 cd backend
-uv run python -m zbt.commands.evaluate_agents --suite smoke
-uv run python -m zbt.commands.evaluate_agents --suite full
+uv build
 ```
+
+构建结果生成在 `backend/dist`，包括 wheel 和源码包。
+
+## 相关文档
+
+- `docs/第三阶段新增业务与测试.md`：第三阶段新增功能和测试场景。
+- `docs/智保通三阶段业务与ProcessOn技术.md`：三个阶段的业务与技术映射。
+- `docs/项目启动与使用指南.md`：项目运行和使用说明。
+
+所有 `scripts/*.ps1` 均提供同名的 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。

backend/README.md

@@ -1,150 +1,290 @@
-# 智保通后端
+# 智保通第三阶段后端
 
-本目录是智保通的统一后端，使用 Python 3.12 和 FastAPI 开发，负责 API、
-业务规则、身份认证及数据库访问。
+本目录是智保通第三阶段“生命周期工作流”的统一后端。项目在第二阶段 Agentic RAG、长期记忆、知识治理、多模态识别和运营分析能力之上，新增基于 LangGraph 的退保审批工作流，以及独立运行的退款 Worker。
 
-## 技术栈
+后端采用 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. 第三阶段核心能力
 
-项目使用 `pyproject.toml` 和 `uv.lock` 管理依赖，不使用
-`requirements.txt`、Poetry 或 Conda。
+- 退保资格与可退金额试算。
+- LangGraph 风险检查、条件分支、Interrupt、人工审批和 Resume。
+- 低风险自动流转，高风险暂停等待运营人员处理。
+- 退款 Worker 自动领取任务、执行退款、记录尝试并处理重试。
+- Redis 单实例锁、任务租约和幂等约束，避免重复退款。
+- 退款成功后在事务中同步收口申请、保单和时间线状态。
+- 管理端查看工作流状态、风险依据、审批记录、Worker 状态和退款失败原因。
+- 本地只读 MCP 合作医疗服务资源。
+- LangSmith 与 OpenTelemetry 记录 Agent、Tool 和 LangGraph 轨迹。
 
-## 目录结构
+## 2. 运行架构
+
+第三阶段后端包含两个独立进程：
+
+```text
+zbt-serve（主管进程）
+  ├── FastAPI API 进程
+  │     ├── LangChain Agent Kernel
+  │     ├── Agentic RAG / 客户长期记忆 / 多模态识别
+  │     └── LangGraph 生命周期工作流
+  └── Refund Worker 进程
+        ├── Redis 单实例锁与心跳
+        ├── 退款任务领取与租约
+        ├── 幂等退款适配器
+        └── 重试、异常记录与人工干预
+```
+
+API 与 Worker 独立运行，是为了隔离 HTTP 请求处理和后台资金任务；`zbt-serve` 负责统一启动、监控和停止两个进程。
+
+## 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/            # serve、Worker、初始化和评测命令
+│   ├── core/                # 配置、安全、错误和公共能力
+│   ├── domains/
+│   │   ├── agent/           # Agent 会话、工具与运行记录
+│   │   ├── knowledge/       # Agentic RAG 与知识治理
+│   │   ├── service_request/ # 保单服务申请
+│   │   └── surrender/       # 退保、LangGraph、退款与审计时间线
+│   ├── harness/             # Persona、Skill、Policy 和结构化协议
+│   ├── infrastructure/      # MySQL、Redis、Milvus、MCP 和模型适配器
+│   └── main.py              # FastAPI 应用装配入口
+├── migrations/              # S3 Core、Agent、Analytics 三库迁移
+├── evals/                   # 真实模型评测数据
+├── tests/                   # 自动化测试
+├── var/                     # 本地材料和运行文件
 ├── alembic.ini
 ├── pyproject.toml
 └── uv.lock
 ```
 
-项目采用 `src` 布局，`uv sync` 会以可编辑模式安装 `zbt` 包；执行
-`uv build` 可以生成 wheel 和源码包。
+## 4. 环境配置
 
-代码主要调用方向：
+后端读取当前 `backend/.env`。除第二阶段的 MySQL、Redis、Milvus、BGE、DeepSeek、百炼和 LangSmith 配置外，第三阶段重点增加：
 
-```text
-HTTP 请求 → api 路由 → domain service → repository → MySQL
-```
+| 环境变量 | 作用 |
+|---|---|
+| `REFUND_WORKER_SINGLETON` | 是否启用退款 Worker 单实例运行策略 |
+| `REFUND_WORKER_HEARTBEAT_SECONDS` | Worker 心跳上报间隔 |
+| `REFUND_WORKER_INSTANCE_TTL_SECONDS` | Worker 实例状态过期时间 |
+| `LANGSMITH_OTEL_ENABLED` | 是否启用 OpenTelemetry 链路导出 |
 
-AI Agent 的主要调用方向：
+数据库和集合应使用第三阶段命名：
 
-```text
-Agent API → Agent service → LangChain create_agent
-          → DeepSeek（OpenAI 兼容接口）→ 产品目录 Tool
-          → Agent MySQL 持久化 + LangSmith Trace
+```dotenv
+MYSQL_CORE_DATABASE=insurance_s3_core
+MYSQL_AGENT_DATABASE=insurance_s3_agent
+MYSQL_ANALYTICS_DATABASE=insurance_s3_analytics
+REDIS_PREFIX=ins:s3:
+MILVUS_COLLECTION_PREFIX=ins_s3_
 ```
 
-## 环境配置
-
-后端读取当前 `backend` 目录中的 `.env`。
+如尚未创建 `.env`：
 
-首次使用时，在 `backend` 目录创建并配置 `.env`：
+Windows PowerShell：
 
 ```powershell
+Set-Location backend
+New-Item -ItemType File -Path .env -ErrorAction SilentlyContinue
 notepad .env
 ```
 
-常用配置包括：
+macOS：
+
+```bash
+cd backend
+touch .env
+open -e .env
+```
 
-- `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 签名密钥
+不要将包含真实数据库密码和模型密钥的 `.env` 提交到 Git。
 
-不要把包含真实密码和密钥的 `.env` 提交到 Git。
+## 5. 安装依赖
 
-## 安装后端依赖
+Windows PowerShell：
 
 ```powershell
 Set-Location backend
 uv sync --locked
 ```
 
-`uv sync --locked` 会按照 `uv.lock` 创建或更新 `.venv`，确保每台电脑安装
-相同版本的依赖。
+macOS：
 
-## 初始化数据库
+```bash
+cd backend
+uv sync --locked
+```
 
-请先启动 MySQL 8 和 Redis，然后在项目根目录执行：
+`uv sync --locked` 会根据 `uv.lock` 创建或更新本项目自己的 `.venv`。不需要提前激活其他阶段的虚拟环境。
 
-```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
-```
+## 6. 首次初始化数据
+
+第三阶段首次运行所需的数据库快照、Milvus 初始化脚本和启动说明统一保存在：
+
+[项目启动文档与数据准备.zip](../../02-zhibaotong-knowledge-services-analytics/database/项目启动文档与数据准备.zip)
 
-这些脚本依次完成环境检查、创建数据库、建表、继承第一阶段持久化数据、
-写入第二阶段初始数据、构建分析数据和验证初始化结果。
+请将压缩包解压到三个阶段项目的共同父目录，并按照其中 `智保通第一、二、三阶段启动指南.md` 的“第三阶段：全生命周期工作流”一节执行。该指南统一说明 Windows PowerShell 与 macOS/Linux 的依赖安装、第三阶段 MySQL 导入、Milvus 初始化和启动方式。
 
-## 单独启动后端
+压缩包中的第三阶段 `mysql.sql` 只初始化 `insurance_s3_core`、`insurance_s3_agent` 和 `insurance_s3_analytics`，并已包含前两个阶段继承数据。不要再使用项目内旧 SQL，也不要额外执行 Alembic、`seed`、阶段继承或分析快照构建。
+
+## 7. 启动后端
+
+### 推荐方式：同时启动 API 与 Worker
+
+Windows PowerShell：
 
 ```powershell
 Set-Location backend
-uv run uvicorn zbt.main:app --reload --host 127.0.0.1 --port 8000
+uv run zbt-serve
+```
+
+macOS：
+
+```bash
+cd backend
+uv run zbt-serve
+```
+
+启动成功后会看到类似输出：
+
+```text
+智保通后端已启动：FastAPI 与退款工作器正在独立运行。
+退款工作器已取得单实例锁：...
+退款工作器初始化完成，开始轮询任务。
 ```
 
-启动后访问：
+访问地址：
 
-- API 文档：<http://127.0.0.1:8000/docs>
+- 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>
 
-按 `Ctrl + C` 停止后端。
+### 仅启动 API
 
-## 测试和代码检查
+只进行接口或页面调试、不处理退款任务时可以运行：
 
-在 `backend` 目录执行：
+Windows PowerShell：
 
 ```powershell
-uv run pytest
-uv run ruff check .
-uv run mypy src/zbt
+Set-Location backend
+uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
 ```
 
-也可以在项目根目录执行 `.\scripts\test.ps1`，同时检查前端和后端。
+macOS：
+
+```bash
+cd backend
+uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload
+```
 
-## 数据库迁移
+此方式不会启动退款 Worker，管理端会显示 Worker 未在线，待退款任务也不会被自动领取。
 
-项目使用三个相互独立的数据库：
+### 仅启动 Worker
 
-- `insurance_s2_core`
-- `insurance_s2_agent`
-- `insurance_s2_analytics`
+只有调试后台退款执行时才单独运行：
 
-需要手动执行迁移时，在 `backend` 目录运行：
+Windows PowerShell：
 
 ```powershell
+Set-Location backend
+uv run zbt-refund-worker
+```
+
+macOS：
+
+```bash
+cd backend
+uv run zbt-refund-worker
+```
+
+不要在 `zbt-serve` 正常运行时再次启动 Worker。默认单实例锁会阻止多个主动 Worker 同时领取任务。
+
+## 8. Worker 单实例与多实例边界
+
+退款属于外部资金副作用。默认单实例策略可以降低本地误启动、重复请求支付渠道和状态竞争的风险，也便于在管理端观察唯一的执行者。
+
+单实例并不代表系统架构只能支持一个 Worker。任务领取仍使用租约和幂等约束；在生产环境完成支付渠道幂等、监控告警和容量评估后，可以关闭单实例运行策略并部署多个 Worker 并行消费。
+
+如果本地同时启动多个 Worker，可能出现：
+
+- 多个实例竞争同一批任务，日志和状态更难排查。
+- 支付渠道调用频率增加。
+- 配置或幂等实现有缺陷时，重复退款风险被放大。
+- 心跳记录和故障接管过程更难解释。
+
+## 9. 真实模型评测
+
+先启动完整后端，再在 `backend` 目录执行。Windows PowerShell 和 macOS 命令相同：
+
+```bash
+uv run python -m zbt.commands.evaluate_agents --suite smoke
+uv run python -m zbt.commands.evaluate_agents --suite full
+```
+
+评测会调用真实模型、真实业务 Tool 和真实 HTTP 接口，并检查 Agent、RAG、LangGraph 和 Trace 关联。
+
+## 10. 测试和代码检查
+
+Windows PowerShell（在项目根目录执行）：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1
+```
+
+macOS / Linux（在项目根目录执行）：
+
+```bash
+./scripts/test.sh
+```
+
+## 11. 数据库迁移
+
+当前推荐使用完整 SQL 快照进行首次初始化。开发新的表结构变更时，在 `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。
+三个命令在 Windows PowerShell 和 macOS 中相同。已发布的迁移文件不要直接修改，表结构变化应新增 revision。
+
+## 12. 命令行入口
+
+| 命令 | 用途 |
+|---|---|
+| `uv run zbt-serve` | 统一启动并监管 FastAPI 与退款 Worker |
+| `uv run zbt-refund-worker` | 单独启动退款 Worker |
+| `uv run zbt-seed-surrenders` | 生成退保流程测试场景 |
+| `uv run zbt-seed-surrender-policies` | 生成可用于退保测试的保障中保单 |
+| `uv run zbt-settle-pending-refunds` | 处理历史待结算退款数据 |
+
+后三个命令用于专项测试或历史数据处理，不属于每次启动项目的必执行步骤。
+
+## 13. 构建安装包
+
+Windows PowerShell：
+
+```powershell
+Set-Location backend
+uv build
+```
+
+macOS：
+
+```bash
+cd backend
+uv build
+```
+
+构建结果生成在 `backend/dist`，包括 wheel 和源码包。
+
+## 14. 相关文档
+
+- `../README.md`：第三阶段项目总览和快速启动。
+- `../docs/第三阶段新增业务与测试.md`：第三阶段功能与测试场景。
+- `../docs/智保通三阶段业务与ProcessOn技术.md`：三个阶段的业务与技术映射。
+
+项目根目录中的每个 `scripts/*.ps1` 均提供同名 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。