# BXZCPT 保险诉讼追偿案件管理系统 · 部署说明

版本：1.0.0 ｜ 形态：本地客户端（EXE 安装版）+ 多租户服务端（鉴权/模型网关）

---

## 一、交付物清单

| 文件 | 说明 |
|---|---|
| `dist/BXZCPT-Setup-1.0.0.exe` | 客户端安装包（含卸载器），发给使用方双击安装 |
| `dist/BXZCPT.exe` | 客户端主程序（绿色版，可直接运行，无需安装） |
| `dist/BXZCPT-Server-1.0.0.zip` | 多租户服务端源码包（鉴权授权 + 模型网关 + 管理后台） |
| `docs/使用手册.md` | 功能使用说明（转交使用方） |
| `client/` `server/` | 完整源码 + 26 项自动化测试 |

## 二、客户端安装（使用方）

1. 双击 `BXZCPT-Setup-1.0.0.exe`（建议右键「以管理员身份运行」，装入 `C:\Program Files\BXZCPT` 并写入系统卸载列表）。
2. 非管理员运行也可：自动装入 `%LOCALAPPDATA%\Programs\BXZCPT`。
3. 安装器自动创建**数据目录**（用户硬约束）：
   - `D:\BXZCPT`（优先）→ 无 D 盘则 `C:\BXZCPT` → 再不行 `%LOCALAPPDATA%\BXZCPT`
   - 目录结构：`data\bxzcpt.db`（数据库）、`files\`（案件附件）、`backup\`（备份）、`logs\`（运行日志）、`config.json`
4. 桌面 / 开始菜单生成快捷方式「BXZCPT」。
5. 首次启动自动建库并初始化示例数据。

**绿色运行**：不想安装也可直接运行 `BXZCPT.exe`（数据目录规则同上）。

### 卸载
控制面板「卸载程序」或运行安装目录下 `uninstall.exe`。**默认保留数据目录**（防数据丢失），确认删除时才勾选「同时删除数据目录」。

## 三、默认账号（首次登录后请立即修改，系统会强制提示）

| 用户名 | 初始密码 | 角色 | 说明 |
|---|---|---|---|
| `admin` | `Admin@123` | 平台管理员 | 管理机构/用户/全部数据 |
| `manager` | `Manager@123` | 机构管理员 | 本机构用户与数据 |
| `user1` / `user2` | `User@123456` | 经办人 | 案件业务操作 |

安全机制：连续 5 次密码错误锁定 5 分钟（持久化）；修改密码要求 ≥8 位。

## 四、服务端部署（多租户鉴权 + 模型网关）

> 服务端**只做两件事**：①账号/租户/License 授权 ②模型调用网关（API Key 留服务端）。
> 业务数据不上服务端，全部留在各客户本机。

```bash
unzip BXZCPT-Server-1.0.0.zip && cd server
pip install -r requirements.txt      # 仅 fastapi + uvicorn
python run.py 8080                   # 或 PORT=8080 python run.py
```

- 探活：`GET http://<host>:8080/api/v1/ping`
- 管理后台：`http://<host>:8080/admin`
  - 默认管理员：`admin` / `Admin@123`（配置在 `data/config.json`，**部署后立即修改**）
  - 后台可维护：机构、客户端账号（License 到期日/设备数上限/功能位）、模型网关配置、调用统计
- 模型网关配置（管理后台「模型网关」卡片）：
  - `model_base_url`：任意 OpenAI 兼容接口，如 `https://api.deepseek.com/v1`
  - `model_api_key`：服务端持有，客户端永远不接触
  - `model_name`：如 `deepseek-chat`
- 数据目录：默认 `server/data/`（可用环境变量 `BXZCPT_SERVER_DATA` 指定）
- 生产建议：Nginx/Caddy 反代 + HTTPS + 防火墙仅开 443；定期备份 `server/data/`

### 授权发放流程
1. 管理后台 → 新增机构（编码/名称/联系人）
2. 新增客户端账号（选机构、设密码、License 到期日、设备数上限，默认含 `ai` 功能位）
3. 把账号密码给使用方 → 使用方在客户端「系统管理 → 服务器 · 模型授权」填服务器地址并登录
4. 握手成功后客户端解锁 AI 文书生成；到期/设备满员由服务端拒绝并提示

## 五、客户端 ↔ 服务端握手协议（v1）

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/v1/ping` | GET | 探活 |
| `/api/v1/auth/login` | POST | `{username,password,machineId}` → JWT token + 功能位 |
| `/api/v1/me` | GET | 校验 token / 查看授权 |
| `/api/v1/ai/chat` | POST | 模型调用（messages 数组，OpenAI 格式） |

离线行为：业务功能不受影响；AI 面板显示未授权/离线并禁用（不会报错打断）。

## 六、原版数据迁移

原版小程序导出的 JSON 备份（`{app:"ins-subro", cases:[...]}` 格式）可直接在客户端「导入」使用，回款记录随案导入；编号重复自动跳过并汇总提示。

## 七、备份策略

| 方式 | 操作 |
|---|---|
| 手动备份 | 顶栏「导出备份」（JSON 全量）/ 系统管理「立即备份数据库」（整库快照到 `backup\`） |
| 自动建议 | 案件 ≥30 条界面主动提示备份 |
| 灾备 | 定期拷贝整个 `D:\BXZCPT` 目录即可完整迁移/恢复 |

## 八、故障排查

| 现象 | 处理 |
|---|---|
| 启动提示 WebView2 缺失 | 安装微软 Edge WebView2 运行时（Win11 自带；Win10 装一次即可） |
| 端口/服务异常 | 看 `D:\BXZCPT\logs\app.log` |
| 忘记密码 | 服务端管理后台重置客户端账号；本地账号请管理员在「用户管理」重置 |
| 换机器迁移 | 拷贝 `D:\BXZCPT` 到新机同路径，装好客户端即恢复 |