chore: initial baseline with P0-safety .gitignore

.workbuddy/memory/2026-06-12.md

@@ -0,0 +1,272 @@
+# 2026-06-12 工作记录
+
+## H5端邀请功能WebSocket事件实现
+
+### 后端改动
+1. **ws_manager.py** — 扩展 ConnectionManager 支持H5员工连接：
+   - 新增 `employee_connections: Dict[str, WebSocket]` 员工连接映射表
+   - 新增 `connect_employee()` / `disconnect_employee()` 员工连接注册/注销
+   - 新增 `send_to_employee()` / `broadcast_to_employees()` 员工定向/批量推送
+   - 新增 `is_employee_online()` 在线状态检查
+
+2. **session_service.py** — 邀请相关事件广播：
+   - `_broadcast_participant_change()` 广播给坐席 + 推送给相关H5员工
+   - 事件类型：participant_invited / joined / removed / left / new_message
+
+3. **H5前端 composable** — 新增 `useH5WebSocket.ts`：
+   - 与坐席端 `useWebSocket.ts` 对齐
+   - 端点：`/ws/h5/{employee_id}?token=xxx`
+   - 认证：Redis `employee:token:{token}` → employee_id 一致性校验
+   - 降级策略：WS断连→3秒轮询；WS重连→停止轮询
+
+4. **后端 OAuth2 接口** — 支持 code 换身份流程：
+   - `GET /api/h5/oauth/authorize` — 获取授权URL
+   - `POST /api/h5/oauth/callback` — code 换 token + 员工信息
+   - Token 存入 Redis（8小时TTL）
+
+---
+
+## 企微环境限制部署 — 方案B验证通过（21:46-21:54）
+
+### 部署过程
+- 5个部署包通过堡垒机上传到 `/tmp/`：deploy-h5.tar / deploy-agent.tar / deploy-admin.tar / deploy-backend.tar / deploy.sh
+- 执行 `bash /tmp/deploy.sh`，完整流程：备份 → 解压前端 → 更新后端 → 关闭Mock登录 → 重建镜像 → 重启容器 → 健康检查
+- Mock登录已关闭：`MOCK_LOGIN_ENABLED=false` ✅
+
+### 验证结果
+- ✅ 外部浏览器访问 `https://itsupport.servyou.com.cn/itdesk/` → 拦截页面「请在企业微信中打开」
+- ✅ 企微桌面端工作台 → IT支持服务 → 自动进入H5页面，显示「IT智能服务台」+「坐席在线」
+- ✅ 后端OAuth2接口UA校验（authorize/callback）已生效
+- ✅ localhost开发环境自动豁免检测
+
+### 涉及文件
+- 新增：`frontend-h5/src/views/WeworkOnly.vue`（拦截页面）
+- 修改：`frontend-h5/src/router/index.ts`（路由守卫UA检测）
+- 修改：`backend/app/api/h5.py`（OAuth2接口UA校验）
+- 新增：`deploy-server/deploy.sh`（一键部署脚本）
+
+---
+
+## 安全风险评估与修复（21:00-22:00）
+
+### 安全审计结果
+对项目进行全面安全审计，发现 17 项安全风险（3严重/5高/5中/4低）。
+
+### 已完成的修复（严重+高风险）
+1. **C-1**: `.env.example` 替换为占位符值
+2. **C-2**: `config.py` 移除硬编码 Dify API Key（默认值改为空字符串）
+3. **H-1**: `deploy-server/docker-compose.yml` Mock 登录默认值 `true` → `false`
+4. **H-2**: 坐席企微验证降级放行修复（新注册必须验证，已注册才允许降级）
+5. **H-3**: H5 端 `X-Employee-Id` 明文头仅在 `mock_login_enabled=true` 时允许
+6. **H-4**: WebSocket 认证 Redis 降级放行修复（故障时拒绝连接）
+7. **H-5**: 添加 slowapi 速率限制（登录10/min，Mock登录5/min，OAuth回调20/min）
+
+### 遇到的问题
+- Windows `python` 命令指向 Microsoft Store 占位符，实际 Python 路径：`C:\Users\simon\AppData\Local\Programs\Python\Python312\python.exe`
+- slowapi 的 `Limiter()` 会尝试读取 `.env` 文件，Windows GBK 编码无法解码中文注释，需加 `env_file=None` 参数
+
+### 待处理（中/低风险）
+- Redis 设置密码、PostgreSQL 强密码、CORS 收紧、Nginx CSP/HSTS 安全头等
+
+---
+
+## 统一入口架构设计（22:00-22:40）
+
+### 设计决策
+- **统一入口**：所有用户必须通过企微工作台 → IT智能服务台应用进入
+- **路由选择页**：独立页面 `/itportal/`，卡片选择 UI
+- **角色体系**：user（默认）/ agent（企微标签映射）/ admin（手动绑定）
+- **Token 统一**：合并为 `user:token:{token}`，包含角色信息
+- **管理端访问控制**：仅限内网/VPN 访问，Nginx IP 白名单
+- **坐席端改造**：支持企微桌面端 + 独立浏览器扫码登录
+- **API 认证**：保留独立 API Key 通道，与用户认证分离
+
+### 技术设计文档
+已创建 `docs/统一入口技术设计文档.md`，包含：
+- 系统架构图、角色路由逻辑
+- 数据库设计（roles/user_roles/role_mapping_rules 表）
+- API 设计（Portal API、角色管理 API、认证中间件）
+- 前端设计（Portal Vue 应用、角色选择 UI、坐席端改造）
+- 安全设计（认证安全、角色安全、API 安全）
+- 实施计划（4阶段，约66工时）
+
+### 用户确认的关键决策
+- 企微标签配置：用户是企微超管，可直接创建标签组
+- eHR 对接：先用企微标签映射，eHR 后续补充
+- 管理端紧急通道：保留管理员密码登录，仅内网/VPN 访问，需二次验证（待设计）
+- 坐席端使用场景：支持企微桌面端 + 独立浏览器扫码登录
+
+---
+
+## 统一入口 Phase 1 实施（23:00-00:00）
+
+### 已完成的工作
+1. **数据库模型** — 创建角色系统三张表：
+   - `roles` — 角色定义表（user/agent/admin）
+   - `user_roles` — 用户角色关联表（支持多角色）
+   - `role_mapping_rules` — 角色映射规则表（企微标签/eHR字段 → 角色）
+   - Alembic 迁移脚本：`007_role_system.py`（含预置数据）
+
+2. **Pydantic Schema** — `schemas/role.py`，包含：
+   - RoleResponse / UserRoleResponse
+   - RoleAssignRequest / RoleRevokeRequest
+   - RoleMappingRuleRequest / RoleMappingRuleResponse
+   - PortalUserInfo / SwitchRoleRequest / SwitchRoleResponse
+
+3. **API 端点**：
+   - `portal.py` — Portal 统一入口 API（获取角色、切换角色、获取入口URL）
+   - `admin_roles.py` — 管理后台角色管理 API（CRUD、分配/撤销、映射规则管理）
+   - `router.py` — 注册新路由
+
+4. **服务层**：
+   - `role_mapping_service.py` — 角色映射服务（企微标签 → 角色）
+   - `token_service.py` — 统一 Token 服务（创建、验证、切换角色、兼容旧格式）
+
+5. **认证中间件** — `dependencies.py`，包含：
+   - `get_current_user` — 统一认证依赖（支持新旧 Token 格式）
+   - `require_role` — 角色验证装饰器
+   - `require_admin` — 管理员权限验证装饰器
+
+6. **坐席认证改造** — `agents.py`：
+   - `get_current_agent` 支持新旧两种 Token 格式
+   - 坐席登录使用统一 Token 服务创建 Token
+
+### 文件清单
+**新增文件**：
+- `backend/app/models/role.py`
+- `backend/app/models/user_role.py`
+- `backend/app/models/role_mapping_rule.py`
+- `backend/app/schemas/role.py`
+- `backend/app/services/role_mapping_service.py`
+- `backend/app/services/token_service.py`
+- `backend/app/api/portal.py`
+- `backend/app/api/admin_roles.py`
+- `backend/alembic/versions/007_role_system.py`
+
+**修改文件**：
+- `backend/app/models/__init__.py` — 注册新模型
+- `backend/app/api/router.py` — 注册新路由
+- `backend/app/api/agents.py` — 认证改造
+- `backend/app/dependencies.py` — 统一认证中间件
+
+### 下一步
+- 运行 Alembic 迁移创建表
+- 测试新 API 端点
+- 开始 Phase 2：路由选择页前端开发
+
+---
+
+## 安全风险修复（08:00-08:30）
+
+### 安全审计结果
+对项目进行安全风险评估，发现 22 项安全风险（4严重/6高/7中/5低）。
+
+### 已完成的修复（Phase 1）
+
+1. **CR-1**: 验证 `dependencies.py` 完整性 → 文件完整，无需修复
+2. **CR-2**: 统一 Token 格式并确保向后兼容 → 修改 `token_service.py`
+3. **CR-3**: Portal API 改用新认证中间件 → 修改 `portal.py`、`admin_roles.py`
+4. **CR-4**: 修复坐席登录 Redis 连接管理 → 修改 `agents.py`
+5. **H-8**: 添加映射规则输入验证 → 修改 `schemas/role.py`
+
+### 创建的文档
+- `docs/风险跟踪表.md` — 风险跟踪管理文档，包含 22 项风险的详细信息和处理计划
+
+### 风险关联开发任务
+已建立风险与开发任务的关联关系，后续开发涉及风险项目时，与风险项目一并处理并更新状态。
+
+### 待处理风险
+- **高风险**: H-7（角色分配权限验证）、H-9（Token绑定IP）、H-10（管理端IP白名单）、H-11（WS Token头传递）
+- **中风险**: M-6~M-12（Token迁移、缓存、速率限制、异常处理、日志脱敏、密码强度等）
+- **低风险**: L-5~L-9（CSP/HSTS、CORS、API认证、Nginx配置、前端配置）
+
+---
+
+## Phase 2：Portal 前端应用（08:44-09:00）
+
+### 已完成的工作
+1. **创建 frontend-portal Vue 应用**：
+   - 基于 Element Plus（与坐席端/管理端一致）
+   - 基础路径：`/itportal/`
+   - 开发端口：5176
+   - 状态管理：Pinia
+   - 路由：vue-router 4
+
+2. **目录结构**：
+   ```
+   frontend-portal/
+   ├── package.json
+   ├── vite.config.ts
+   ├── tsconfig.json
+   ├── index.html
+   ├── .env / .env.development / .env.production
+   └── src/
+       ├── main.ts
+       ├── App.vue
+       ├── api/
+       │   ├── index.ts (axios 实例)
+       │   └── portal.ts (Portal API)
+       ├── router/
+       │   └── index.ts
+       ├── stores/
+       │   └── portal.ts (Pinia Store)
+       └── views/
+           ├── PortalSelect.vue (角色选择页)
+           └── PortalLoading.vue (加载中页)
+   ```
+
+3. **核心功能**：
+   - 角色选择页面（卡片选择 UI）
+   - 用户信息展示
+   - Token 管理（localStorage）
+   - 角色切换（跳转到对应端）
+   - 响应式布局（支持移动端）
+
+### 下一步
+- 安装依赖并测试前端应用
+- 集成到 Docker 构建
+- 部署到服务器
+
+---
+
+## 重要提醒（10:15）
+
+### 测试环境限制
+- **本地开发环境无法完成企微 OAuth2 认证**
+- 所有登录相关验证必须在生产服务器 `10.90.5.110` 上进行
+- 前端都通过企微认证，不支持独立登录页面
+
+---
+
+## 部署清单（10:51）
+
+### 本次更新成果（可部署）
+- **后端**：角色系统（3张表+迁移脚本）、统一Token服务、角色管理API、安全修复
+- **前端**：Portal 统一入口应用（`frontend-portal/`）
+- **部署脚本**：已包含 Portal 部署逻辑
+
+### 待部署验证
+- Portal 角色选择页
+- OAuth2 认证流程
+- Token 传递和验证
+- 角色切换功能
+- 数据库迁移
+
+---
+
+## 安全风险修复（15:20）
+
+### 本次修复的 6 项风险
+1. **H-7**: 角色分配权限验证（禁止给自己分配）→ `admin_roles.py`
+2. **H-10**: 管理端 Nginx IP 白名单配置 → `nginx.conf`
+3. **M-11**: PostgreSQL 更换强密码 → `.env.example`
+4. **M-12**: Redis 设置密码 → `docker-compose.yml` + `.env.example`
+5. **L-5**: Nginx 添加 CSP/HSTS 安全头 → `nginx.conf`
+6. **L-6**: 收紧 CORS 配置 → `main.py`
+
+### 风险处理进度
+- 严重风险：4/4 已处理（100%）
+- 高风险：4/6 已处理（67%）
+- 中风险：2/7 已处理（29%）
+- 低风险：2/5 已处理（40%）
+- **总处理率：55%**