chore: initial baseline with P0-safety .gitignore

docs/安全审计报告.md

@@ -0,0 +1,220 @@
+# IT智能服务台 — 安全审计报告
+
+> **编制日期**: 2026-06-14
+> **版本**: v1.0
+
+---
+
+## 1. 系统概述
+
+| 项目 | 说明 |
+|------|------|
+| 系统名称 | IT智能服务台 |
+| 部署环境 | 企业内网 (10.90.5.110) |
+| 访问方式 | 企微工作台应用 / HTTPS |
+| 用户规模 | ~6000人 |
+
+---
+
+## 2. 安全架构
+
+### 2.1 认证与授权
+
+| 特性 | 实现方式 | 状态 |
+|------|----------|------|
+| **身份认证** | 企微OAuth2 + JWT Token | ✅ 已实现 |
+| **OTP双因素** | TOTP (Google Authenticator) | ✅ 已实现 |
+| **角色权限** | RBAC (user/agent/admin) | ✅ 已实现 |
+| **会话管理** | Redis Token + 过期时间 | ✅ 已实现 |
+| **密码策略** | 企微账户策略 | ✅ 依赖企微 |
+
+### 2.2 网络安全
+
+| 特性 | 实现方式 | 状态 |
+|------|----------|------|
+| **HTTPS** | Nginx SSL终止 | ✅ 已配置 |
+| **CORS** | 白名单域名 | ✅ 已配置 |
+| **IP白名单** | Nginx allow/deny | ⚠️ 待配置 |
+| **API限流** | Nginx rate_limit | ⚠️ 待配置 |
+| **WAF** | 腾讯WAF | ✅ 已接入 |
+
+### 2.3 数据安全
+
+| 特性 | 实现方式 | 状态 |
+|------|----------|------|
+| **数据库** | PostgreSQL (内网) | ✅ 已实现 |
+| **传输加密** | TLS 1.2+ | ✅ 已配置 |
+| **敏感脱敏** | 日志脱敏 | ⚠️ 待实现 |
+| **备份策略** | 定时备份 | ⚠️ 待配置 |
+| **加密存储** | 字段加密 | ❌ MVP不考虑 |
+
+### 2.4 应用安全
+
+| 特性 | 实现方式 | 状态 |
+|------|----------|------|
+| **SQL注入** | SQLAlchemy ORM | ✅ 已防护 |
+| **XSS** | 前端转义 | ✅ 已实现 |
+| **CSRF** | JWT Token | ✅ 已防护 |
+| **文件上传** | 类型限制 + 存储隔离 | ✅ 已实现 |
+| **API认证** | Token验证 | ✅ 已实现 |
+
+---
+
+## 3. 审计日志
+
+### 3.1 已记录事件
+
+| 事件 | 记录位置 | 状态 |
+|------|----------|------|
+| 登录/登出 | 日志 | ✅ |
+| 消息发送 | 数据库 + 日志 | ✅ |
+| 会话创建/关闭 | 数据库 + 日志 | ✅ |
+| 管理员操作 | 日志 | ✅ |
+| 配置变更 | 数据库 | ✅ |
+
+### 3.2 待记录事件
+
+| 事件 | 优先级 | 说明 |
+|------|--------|------|
+| **敏感数据查询** | P1 | 查询用户信息、联系方式 |
+| **角色变更** | P1 | 管理员分配权限 |
+| **系统配置变更** | P1 | 功能开关、集成配置 |
+| **API调用统计** | P2 | 接口调用频率 |
+| **异常登录** | P1 | 异地登录、频繁失败 |
+
+---
+
+## 4. 安全检查项
+
+### 4.1 MVP必须通过
+
+| # | 检查项 | 当前状态 | 建议 |
+|---|--------|----------|------|
+| 1 | 企微OAuth2认证 | ✅ | - |
+| 2 | JWT Token有效期 | ✅ 2小时 | - |
+| 3 | OTP绑定/验证 | ✅ | - |
+| 4 | 角色权限控制 | ✅ | - |
+| 5 | 数据库内网访问 | ✅ | - |
+| 6 | HTTPS全站加密 | ✅ | - |
+| 7 | 日志脱敏 | ⚠️ | 上线前完成 |
+| 8 | IP访问限制 | ⚠️ | 上线前完成 |
+
+### 4.2 生产建议项
+
+| # | 检查项 | 优先级 | 说明 |
+|---|--------|--------|------|
+| 9 | API限流 | P2 | 防DDoS |
+| 10 | 操作审计日志 | P2 | 合规要求 |
+| 11 | 数据库定时备份 | P2 | 灾备 |
+| 12 | 入侵检测 | P3 | 长期 |
+
+---
+
+## 5. 消息状态功能（待实现）
+
+### 5.1 需求
+
+| 功能 | 说明 | 优先级 |
+|------|------|--------|
+| 已读未读状态 | 每条消息独立跟踪已读/未读 | P2 |
+| 已读时间戳 | 记录何时已读 | P2 |
+| 已读回执推送 | WS实时推送已读状态 | P2 |
+| 未读计数 | 会话未读消息数 | P2 |
+
+### 5.2 现有代码
+
+```python
+# 当前 Message 模型
+is_read: bool  # 单字段，只能记录"是否已读"
+```
+
+问题：多用户场景下无法区分用户独立已读状态
+
+### 5.3 实现方案
+
+```python
+# 新增 MessageStatus 表
+class MessageStatus(Base):
+    message_id: str
+    user_id: str      # 读取者ID
+    user_type: str   # employee/agent
+    status: Enum    # sent/delivered/read
+    read_at: datetime
+```
+
+### 5.4 API设计
+
+| API | 方法 | 说明 |
+|-----|------|------|
+| `/api/messages/{id}/read` | PUT | 标记消息已读 |
+| `/api/messages/{id}/status` | GET | 获取消息状态 |
+| `/api/conversations/{id}/unread-count` | GET | 未读计数 |
+
+---
+
+## 6. 风险评估
+
+| 风险 | 等级 | 缓解措施 |
+|------|------|----------|
+| 企微API限制 | 中 | 保持降级通道 |
+| 内网暴露面 | 中 | IP白名单 |
+| 社工攻击 | 低 | OTP + 安全培训 |
+| 数据泄露 | 低 | 内网 + HTTPS |
+
+---
+
+## 7. 架构优化（2026-06-14 讨论）
+
+### 7.1 高可用方案
+
+| 特性 | 状态 | 说明 |
+|------|------|------|
+| restart: unless-stopped | ✅ 已配置 | 容器崩溃自动重启 |
+| healthcheck 后端 | ✅ 已配置 | curl /health |
+| healthcheck nginx | ✅ 已配置 | curl /itdesk/health |
+| healthcheck postgres | ✅ 已配置 | pg_isready |
+| healthcheck redis | ✅ 已配置 | redis-cli ping |
+
+### 7.2 AI Gateway 设计
+
+| 特性 | 状态 | 说明 |
+|------|------|------|
+| 内部抽象 | ⚠️ 待实现 | 抽离 AI 层为 Gateway |
+| 多模型支持 | ⚠️ 待实现 | dify/wingman/其他 |
+| 热切换 | ⚠️ 待实现 | 配置化切换 |
+| 降级机制 | ⚠️ 待实现 | 失败自动切换 |
+
+设计目标：
+- 统一入口，支持 dify/wingman/其他模型
+- 配置化启用/禁用，无需改代码
+- 失败自动降级到备用模型
+
+---
+
+## 8. 结论
+
+### 8.1 MVP可上线条件
+
+- [x] 企微OAuth2认证
+- [x] OTP双因素
+- [x] 角色权限
+- [x] HTTPS
+- [x] Docker健康检查+自动重启
+- [ ] 日志脱敏（上线前完成）
+- [ ] IP访问限制（上线前完成）
+- [ ] AI Gateway（V2前完成）
+
+### 8.2 下一步行动
+
+| 行动 | 负责人 | 截止 | 状态 |
+|------|--------|------|------|
+| 日志脱敏 | 开发 | 上线前 | pending |
+| IP白名单 | 运维 | 上线前 | pending |
+| AI Gateway | 开发 | V2前 | pending |
+| 消息状态功能 | 开发 | V2 | pending |
+
+---
+
+> **编制人**: 宋献
+> **审核人**: 待定
+> **更新日期**: 2026-06-14