feat: 凭证生成、成本分析、AI问答、前端页面、集成测试与E2E测试

- 后端: 凭证生成引擎、金蝶导出器、凭证模板服务 - 后端: 成本分析服务、AI问答服务 - 后端: 科目映射CRUD API、分析API、QA API - 后端: 集成测试(认证/任务/凭证) 49个测试全部通过 - 前端: 凭证管理、成本分析、导出中心、知识库、系统设置页面 - 前端: AuthGuard认证守卫、Dashboard AI聊天功能 - 前端: Playwright E2E测试 16 passed, 1 skipped - 基础设施: Docker Compose、Nginx反向代理、.env.example - 文档: 用户手册、管理员手册、发布检查清单
2026-07-07 21:21:29 +08:00
parent feebbb10ac
commit 5278190750
47 changed files with 6567 additions and 156 deletions
@@ -0,0 +1,160 @@
+# S2F 管理员手册
+
+## 1. 系统部署
+
+### 1.1 Docker 部署（推荐）
+
+```bash
+# 1. 复制环境变量
+cp .env.example .env
+
+# 2. 编辑 .env，配置关键参数
+# - DB_PASSWORD: 数据库密码（生产环境务必修改）
+# - SECRET_KEY: JWT 签名密钥
+# - JWT_SECRET_KEY: JWT 加密密钥
+# - ZHIPU_API_KEY: 智谱 AI API Key
+# - ALLOWED_ORIGINS: 前端访问地址
+
+# 3. 启动所有服务
+docker-compose up -d
+
+# 4. 初始化数据库
+docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
+
+# 5. 验证服务
+curl http://localhost:8000/api/health
+```
+
+### 1.2 本地开发部署
+
+```bash
+# 后端
+cd backend
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+
+# 前端
+cd frontend
+npm install
+npm run dev
+```
+
+## 2. 环境变量说明
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| DB_NAME | 数据库名 | s2f_db |
+| DB_USER | 数据库用户 | s2f_user |
+| DB_PASSWORD | 数据库密码 | s2f_password |
+| SECRET_KEY | 应用密钥 | change-me-in-production |
+| JWT_SECRET_KEY | JWT 密钥 | change-me-in-production |
+| AI_PROVIDER | AI 服务商 | zhipu |
+| ZHIPU_API_KEY | 智谱 API Key | - |
+| OPENAI_API_KEY | OpenAI API Key | - |
+| ALLOWED_ORIGINS | CORS 允许来源 | http://localhost:3000 |
+| DEBUG | 调试模式 | false |
+| LOG_LEVEL | 日志级别 | INFO |
+
+## 3. 数据库管理
+
+### 3.1 初始化
+```bash
+docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"
+```
+
+### 3.2 备份
+```bash
+# 手动备份
+docker-compose exec postgres pg_dump -U s2f_user s2f_db > backup_$(date +%Y%m%d).sql
+
+# 定时备份（crontab）
+0 2 * * * docker-compose exec -T postgres pg_dump -U s2f_user s2f_db > /backups/s2f_$(date +\%Y\%m\%d).sql
+```
+
+### 3.3 恢复
+```bash
+docker-compose exec -T postgres psql -U s2f_user s2f_db < backup_20240101.sql
+```
+
+## 4. 监控与日志
+
+### 4.1 查看日志
+```bash
+# 后端日志
+docker-compose logs -f backend
+
+# 前端日志
+docker-compose logs -f frontend
+
+# Nginx 日志
+docker-compose logs -f nginx
+
+# 数据库日志
+docker-compose logs -f postgres
+```
+
+### 4.2 健康检查
+```bash
+curl http://localhost:8000/api/health
+```
+
+### 4.3 性能监控
+- 后端 API 文档：http://localhost:8000/docs
+- 监控指标：API 响应时间、数据库连接数、Redis 内存
+
+## 5. 安全配置
+
+### 5.1 生产环境检查清单
+- [ ] 修改 DB_PASSWORD
+- [ ] 修改 SECRET_KEY 和 JWT_SECRET_KEY
+- [ ] 配置正确的 ALLOWED_ORIGINS
+- [ ] 设置 DEBUG=false
+- [ ] 配置 HTTPS（通过 Nginx）
+- [ ] 设置防火墙规则
+
+### 5.2 AI API Key 管理
+- API Key 存储在 .env 文件中，不进入 Git
+- 定期轮换 API Key
+- 监控 API 调用量和成本
+
+## 6. 故障排除
+
+### 6.1 服务无法启动
+```bash
+# 检查容器状态
+docker-compose ps
+
+# 查看错误日志
+docker-compose logs backend
+docker-compose logs postgres
+```
+
+### 6.2 数据库连接失败
+- 检查 PostgreSQL 容器是否运行
+- 检查 DATABASE_URL 配置
+- 检查网络连通性
+
+### 6.3 AI 功能不可用
+- 检查 ZHIPU_API_KEY 或 OPENAI_API_KEY 是否配置
+- 检查网络是否能访问 AI API
+- 查看后端日志中的 AI 调用错误
+
+### 6.4 前端无法访问后端
+- 检查 CORS 配置（ALLOWED_ORIGINS）
+- 检查 Nginx 反向代理配置
+- 检查后端服务是否正常运行
+
+## 7. 更新与升级
+
+### 7.1 更新代码
+```bash
+git pull
+docker-compose build
+docker-compose up -d
+```
+
+### 7.2 数据库迁移
+```bash
+docker-compose exec backend alembic upgrade head
+```
@@ -0,0 +1,78 @@
+# S2F 发布检查清单
+
+## 一、代码质量
+
+- [ ] 所有 lint 错误已修复
+- [ ] TypeScript 类型检查通过 (`npm run type-check`)
+- [ ] Python 类型检查通过 (`mypy app/`)
+- [ ] 无 `console.log` / `print` 残留（调试代码）
+- [ ] 无硬编码密钥/密码
+- [ ] 中文 DocString 已添加
+
+## 二、功能验证
+
+- [ ] 用户注册/登录流程正常
+- [ ] 文件上传（工资表/社保表/个税表）正常
+- [ ] AI 字段识别返回结果
+- [ ] 字段映射确认后可执行对账
+- [ ] 对账结果展示正确
+- [ ] 异常列表筛选/处理正常
+- [ ] 成本分析页面数据加载正常
+- [ ] 成本分析 Excel 导出正常
+- [ ] AI 问答功能正常
+- [ ] 凭证生成正常
+- [ ] 凭证确认后可导出
+- [ ] 金蝶 CSV 导出格式正确
+- [ ] 科目映射 CRUD 正常
+
+## 三、安全检查
+
+- [ ] JWT Token 过期时间合理（≤2h）
+- [ ] 密码使用 bcrypt 哈希
+- [ ] API 接口有权限校验
+- [ ] 租户隔离生效（X-Company-ID）
+- [ ] SQL 注入防护（参数化查询）
+- [ ] XSS 防护（前端转义）
+- [ ] CORS 配置正确
+- [ ] 敏感信息不在日志中输出
+- [ ] .env 不在 Git 中
+
+## 四、数据库
+
+- [ ] 数据库迁移脚本已准备
+- [ ] 所有模型字段有注释
+- [ ] 审计字段完整（created_by/updated_by）
+- [ ] 索引已创建（常用查询字段）
+
+## 五、前端
+
+- [ ] 所有页面有 Loading 状态
+- [ ] 所有页面有 Empty 状态
+- [ ] 错误处理有用户提示
+- [ ] 响应式布局（sm/md/lg/xl）
+- [ ] 暗色模式兼容
+- [ ] 无 `alert()/confirm()`
+- [ ] 无硬编码主色 hex
+
+## 六、部署
+
+- [ ] Docker 镜像构建成功
+- [ ] docker-compose up 正常启动
+- [ ] Nginx 反向代理配置正确
+- [ ] 环境变量已通过 .env 配置
+- [ ] 数据库初始化脚本可执行
+- [ ] 健康检查端点 `/api/health` 正常
+
+## 七、文档
+
+- [ ] README 已更新
+- [ ] API 文档（OpenAPI）可访问
+- [ ] .env.example 完整
+- [ ] 部署步骤清晰可复制
+
+## 八、性能
+
+- [ ] API 响应时间 < 500ms（常规接口）
+- [ ] 文件上传超时设置合理
+- [ ] 大数据集分页正常
+- [ ] 前端首屏加载 < 3s
@@ -0,0 +1,87 @@
+# S2F 用户使用手册
+
+## 1. 快速入门
+
+### 1.1 登录系统
+1. 打开浏览器访问系统地址
+2. 输入用户名和密码
+3. 点击「登录」进入 AI 工作台
+
+### 1.2 创建对账任务
+1. 点击侧边栏「对账任务」
+2. 点击「新建对账任务」
+3. 上传工资表 Excel 文件
+4. 上传社保表 Excel 文件（可选）
+5. 上传个税表 Excel 文件（可选）
+6. 点击「开始对账」
+
+### 1.3 AI 字段识别
+1. 文件上传后，系统自动调用 AI 识别字段映射
+2. 在「字段映射」页面查看识别结果
+3. 确认或修改映射关系
+4. 点击「确认映射」继续
+
+## 2. 对账与异常处理
+
+### 2.1 查看对账结果
+1. 在「对账任务」列表点击任务查看结果
+2. 查看匹配率、已匹配数、异常数
+
+### 2.2 处理异常
+1. 点击侧边栏「异常处理」
+2. 按状态、严重程度、类型筛选异常
+3. 点击异常查看详情
+4. 处理异常（标记为处理中 → 已解决）
+
+## 3. 成本分析
+
+### 3.1 查看成本分析
+1. 点击侧边栏「成本分析」
+2. 输入任务ID
+3. 可选：输入上月任务ID进行环比分析
+4. 点击「分析」查看结果
+
+### 3.2 AI 成本问答
+1. 在成本分析页面底部找到「AI 问答」区域
+2. 点击预置问题或输入自定义问题
+3. AI 基于真实数据回答
+
+### 3.3 导出成本分析
+1. 点击页面右上角「导出 Excel」
+2. 系统下载成本分析 Excel 文件
+
+## 4. 凭证管理
+
+### 4.1 生成凭证
+1. 点击侧边栏「凭证管理」
+2. 输入任务ID
+3. 点击「生成凭证」
+4. 系统自动根据科目映射生成借贷分录
+
+### 4.2 确认凭证
+1. 检查凭证分录
+2. 确认无误后点击「确认凭证」
+3. 确认后凭证不可修改
+
+### 4.3 导出金蝶格式
+1. 点击「金蝶CSV」导出金蝶 K3 格式
+2. 或点击「Excel」导出 Excel 格式
+3. 导入金蝶系统
+
+### 4.4 科目映射管理
+1. 在凭证管理页面点击「科目映射」
+2. 新增/编辑/删除标准字段到会计科目的映射
+3. 映射将用于凭证自动生成
+
+## 5. AI 助手
+
+### 5.1 使用 AI 工作台
+1. 在首页「AI 助手」区域
+2. 点击预置问题快速提问
+3. 或输入自定义问题
+4. AI 基于真实对账数据回答
+
+### 5.2 提问技巧
+- 问题越具体，回答越准确
+- 可询问成本分析、异常原因、匹配率等
+- 支持中文自然语言提问