feat: BossAi 老板AI助手初始版本

包含功能: - 法务参谋/经营决策/生活助理/情绪中心四大AI对话模块 - 专家咨询系统(用户选定→专家确认→咨询→回复→评价) - 角色登录(用户/专家/管理员)+ ProtectedRoute 权限控制 - 管理后台(用户管理/专家管理/AI使用统计/专家活跃度) - 专家工作台(待确认服务/待回复咨询/已回复咨询/服务中用户) - 服务关系取消(用户和专家均可取消,需自己确认) - 全页面移动端响应式适配 - 知识库RAG检索 - 对话历史(普通/保密模式) Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-08-29 23:57:26 +08:00
commit 5c21e8fcd0
101 changed files with 25273 additions and 0 deletions
@@ -0,0 +1,272 @@
+# 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
+```