# BossAi 运行手册

> 项目运行事实来源。命令可复制执行,标注 `[Docker]`/`[Native]`,危险操作标红。

## 技术栈

| 层 | 技术 | 版本 |
|---|---|---|
| 后端 | Python + FastAPI + Uvicorn | Python 3.12 / FastAPI 0.133 |
| 前端 | React + Vite + TypeScript + Tailwind + shadcn/ui | React 18.3 / Vite 5.4 |
| 数据库 | PostgreSQL | 16.x |
| 模型 | Kimi(Moonshot)云端模型,OpenAI 兼容接口 | moonshot-v1-8k |
| 包管理 | pip(后端)/ npm(前端) | npm 11 |

## 首次准备

```bash
# 后端依赖(Python 3.12+)
cd /Users/freedak/Documents/AIDashboard/BossAi
pip install fastapi uvicorn pydantic python-dotenv psycopg2

# 数据库初始化(建表 + 种子数据,幂等)
python3 db_init.py

# 前端依赖(Node 18+)
cd web
npm install

# 配置密钥(从 .env.example 复制,填入真实 KIMI_API_KEY)
cp .env.example .env
# 编辑 .env 填入 KIMI_API_KEY
```

## 应用启停

### 后端 API(Native)

```bash
# 启动(端口 8000)
cd /Users/freedak/Documents/AIDashboard/BossAi
uvicorn api:app --host 127.0.0.1 --port 8000

# 后台启动
uvicorn api:app --host 127.0.0.1 --port 8000 > /tmp/bossai_uvicorn.log 2>&1 &

# 停止
lsof -ti:8000 | xargs kill
```

### 前端 Dev(Native)

```bash
# 启动(端口 5173,自动代理 /api → 127.0.0.1:8000)
cd /Users/freedak/Documents/AIDashboard/BossAi/web
npm run dev

# 后台启动
npm run dev > /tmp/bossai_vite.log 2>&1 &

# 停止
lsof -ti:5173 | xargs kill
```

### 前端构建

```bash
cd /Users/freedak/Documents/AIDashboard/BossAi/web
npm run build      # 产物在 web/dist/
npm run preview    # 预览构建产物
npm run typecheck  # 仅类型检查
```

## 端口表

| 服务 | 端口 | 说明 |
|---|---|---|
| 后端 API | 8000 | FastAPI,健康检查 /health |
| 前端 Dev | 5173 | Vite,代理 /api → 8000 |

## 测试命令

```bash
# 后端全部测试(74 项:API + 对抗 + 阅后即焚 + 灾难恢复 + 发布检查 + 法规更新)
cd /Users/freedak/Documents/AIDashboard/BossAi
python3 -m unittest test_bossai test_api test_adversarial test_burn_after_reading test_disaster_recovery test_release_checklist test_regulation -v

# 性能测试
python3 test_performance.py

# 法务评测集(296 个问题,分诊器准确率)
python3 run_eval.py

# 生成评测集(如需重新生成)
python3 gen_eval_set.py

# 前端类型检查 + 构建
cd web
npm run typecheck
npm run build
```

## 数据库命令

```bash
# 初始化(建表 + 种子数据,幂等可重复执行)
cd /Users/freedak/Documents/AIDashboard/BossAi
python3 db_init.py

# 连接数据库
psql -h localhost -p 5432 -U postgres -d mcp

# 查看表
\dt

# 数据库连接串(代码默认值)
# host=localhost port=5432 dbname=mcp user=postgres
# 可通过环境变量 DATABASE_URL 覆盖
# 限流:每 IP 每秒请求数(默认 20,生产建议 10)
RATE_LIMIT=20
```

### 数据表

| 表 | 用途 |
|---|---|
| `knowledge_docs` | 法规知识库(法规/案例/模板),RAG 检索源 |
| `user_settings` | 用户设置(key-value 持久化,含权限控制) |
| `expert_rules` | 专家分配规则(风险等级→专家类型+SLA 时长+自动分配) |
| `review_tickets` | 人工复核工单(含 SLA 截止时间/状态/专家类型) |

## 环境变量(.env)

| 变量 | 说明 | 示例 |
|---|---|---|
| `KIMI_API_KEY` | Kimi/Moonshot API 密钥 | sk-xxx |
| `KIMI_MODEL` | 模型名 | moonshot-v1-8k |
| `KIMI_BASE_URL` | 接口地址 | https://api.moonshot.cn/v1 |
| `DATABASE_URL` | PostgreSQL 连接串 | host=localhost port=5432 dbname=mcp user=postgres |
| `RATE_LIMIT` | API 限流(每分钟请求数) | 20 |
| `MESSAGE_ENCRYPTION_KEY` | 保密模式消息加密密钥(Fernet 格式,生产必须设置) | (用 `python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"` 生成) |
| `JWT_SECRET` | JWT 签名密钥(生产必须修改) | bossai-dev-secret-change-in-prod |

> 密钥仅在 .env 中,已加入 .gitignore,绝不进 Git。
> `MESSAGE_ENCRYPTION_KEY` 未设置时使用开发默认密钥,生产环境必须设置;密钥更换后旧保密历史不可解密。

## API 场景参数

`/sessions/{sid}/ask` 支持 `scene` 参数路由不同 system prompt:

| scene | 模块 | system prompt 人设 |
|---|---|---|
| `legal` | 法务参谋 | 风险等级 + 结论 + 行动 + 证据 + 律师复核 |
| `decision` | 经营决策 | 情景推演 + 方案对比 + 收益/风险/现金流/推荐 |
| `life` | 生活助理 | 务实可执行,降低非经营决策负担 |
| `emotion` | 情绪中心 | 三模式(冷静/陪伴/强力)+ 危机干预 |

`emotion` 场景额外支持 `emotion_mode` 参数:`calm` / `companion` / `push`。

法务场景(`scene=legal`)自动注入 RAG 上下文:从 `knowledge_docs` 表检索相关法规,拼入 system prompt,响应中返回 `rag_context` 数组。

## API 端点一览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/health` | 健康检查 |
| POST | `/sessions` | 创建会话 |
| POST | `/sessions/{sid}/ask` | 提问(非流式,完整响应) |
| POST | `/sessions/{sid}/ask-analyze` | 事实追问分析(返回追问问题或标记事实已充分) |
| POST | `/sessions/{sid}/ask-stream` | 提问(SSE 流式,逐 token 返回,支持 fact_answers) |
| POST | `/sessions/{sid}/destroy` | 隐私急停/销毁 |
| POST | `/sessions/{sid}/file` | 文件上传 |
| GET | `/knowledge` | 知识库列表(支持 doc_type 筛选) |
| POST | `/knowledge` | 新增知识库文档 |
| GET | `/knowledge/search` | RAG 检索(中文 2-gram) |
| DELETE | `/knowledge/{id}` | 删除知识库文档 |
| GET | `/settings` | 读取全部设置 |
| PUT | `/settings` | 批量更新设置 |
| POST | `/tickets` | 创建复核工单(red 自动 urgent) |
| GET | `/tickets` | 工单列表(支持 status 筛选) |
| GET | `/tickets/{no}` | 工单详情 |
| PATCH | `/tickets/{no}` | 更新工单状态/分配/结果 |
| GET | `/expert-rules` | 专家分配规则列表 |
| PATCH | `/expert-rules/{risk_level}` | 更新专家规则(SLA/自动分配) |
| GET | `/metrics` | 可观测性指标(请求数/延迟/模型调用量/销毁统计) |
| GET | `/knowledge/vector-search` | 向量检索(TF-IDF 余弦相似度) |
| GET | `/sessions/{sid}/destroy-status` | 销毁状态和日志查询 |
| POST | `/summaries/preview` | 脱敏摘要保存前预览 |
| POST | `/summaries` | 保存脱敏行动摘要 |
| GET | `/summaries` | 列出已保存摘要 |
| GET | `/documents/templates` | 列出可用文书模板 |
| POST | `/documents/generate` | 生成法律文书 DOCX(阅后即焚禁止) |
| GET | `/regulations/check-updates` | 扫描需更新的法规 |
| POST | `/regulations/update` | 更新法规(自动快照) |
| GET | `/regulations/{id}/versions` | 列出版本快照 |
| POST | `/regulations/{id}/rollback` | 回滚到指定版本 |

## 前后端联调

1. 启动后端:`uvicorn api:app --port 8000`
2. 启动前端:`cd web && npm run dev`
3. 访问 http://127.0.0.1:5173
4. 前端通过 Vite 代理 `/api` → `127.0.0.1:8000`,无需 CORS 配置

## 测试账号

> 种子数据由 `db_init.py` 写入,密码已 bcrypt 哈希。普通用户无种子账号,需通过注册接口创建。

### 管理员(密码 `admin123`)

| 手机号 | 姓名 | 角色 |
|---|---|---|
| 13800000000 | 平台管理员 | admin |

### 专家(密码 `expert123`)

> 手机号规则:`139` + 分类码(`10`法务/`20`经营/`30`情绪/`40`生活) + 6位序号

| 手机号 | 姓名 | 分类 | 职称 | 专长 |
|---|---|---|---|---|
| 13910000000 | 张明律师 | 法务(legal) | 高级律师 | 劳动用工,合同审查,股权纠纷,债权债务 |
| 13910000001 | 李华律师 | 法务(legal) | 执业律师 | 公司治理,税务合规,商事诉讼 |
| 13920000000 | 王强顾问 | 经营(decision) | 高级经营顾问 | 战略规划,组织架构,绩效管理,扩张决策 |
| 13920000001 | 赵敏分析师 | 经营(decision) | 财务分析师 | 财务诊断,融资规划,现金流管理 |
| 13930000000 | 陈静咨询师 | 情绪(emotion) | 国家二级心理咨询师 | 焦虑疏导,压力管理,决策疲劳,创业者心理 |
| 13930000001 | 刘阳教练 | 情绪(emotion) | 情绪教练 | 情绪识别,沟通改善,团队氛围 |
| 13940000000 | 周婷顾问 | 生活(life) | 生活规划师 | 时间管理,家庭关系,健康管理 |
| 13940000001 | 吴昊教练 | 生活(life) | 商务礼仪教练 | 商务礼仪,出差规划,形象管理 |

### 普通用户

无种子账号,通过注册接口创建:

```bash
# 注册示例(密码至少 6 位)
curl -X POST http://127.0.0.1:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"phone":"13900000001","password":"user123","name":"测试老板"}'
```

## 排错

| 问题 | 原因 | 修复 |
|---|---|---|
| 前端提问返回 `model: local-triage` | 后端未加载 .env 或 KIMI_API_KEY 无效 | 确认 .env 存在且密钥有效,重启后端 |
| 前端 `model: kimi` 但 answer 为 null | Kimi 调用异常被捕获 | 查后端日志,检查网络/密钥/额度 |
| 前端 5173 无法访问 | Vite 未启动或端口占用 | `lsof -ti:5173 \| xargs kill` 后重启 |
| 前端 health 显示后端不可达 | 后端 8000 未启动 | 启动 uvicorn |
| 销毁后提问返回 410 | 会话已销毁(预期行为) | 重新创建会话 |

## 部署备份

- 前端构建产物 `web/dist/` 为静态包,可由 nginx 或 FastAPI 静态托管
- 生产部署建议:nginx 托管前端静态包 + 反代 `/api` → uvicorn
- 数据库:PostgreSQL(已接入),知识库/设置/工单/摘要持久化
- CI/CD:GitHub Actions(`.github/workflows/ci.yml`),后端测试 + 前端构建

### 数据库备份

```bash
# 手动备份(压缩,可选 GPG 加密)
./backup.sh

# 加密备份(需先配置 GPG key)
./backup.sh ./backups user@example.com

# crontab 每天 2 次备份
0 2,14 * * * cd /Users/freedak/Documents/AIDashboard/BossAi && ./backup.sh >> backups/backup.log 2>&1

# 恢复
gunzip backups/bossai_XXXXXXXX_XXXXXX.sql.gz
psql -h localhost -U postgres -d mcp < backups/bossai_XXXXXXXX_XXXXXX.sql
```