chore: 初始化项目与后端基础工程

2026-07-06 22:03:22 +08:00
commit 6833106829
34 changed files with 8398 additions and 0 deletions
@@ -0,0 +1,587 @@
+# 财务 AI 助手运行手册（第一模块：薪财通 AI）
+
+**项目**: 财务 AI 助手（项目编号：S2F，第一模块：薪财通 AI）  
+**产品定位**: 面向金蝶中小企业客户的财务 AI 助手  
+**当前运行模块**: 第一阶段薪酬财务对账 MVP  
+**范围说明**: 本运行手册对应第一模块 Excel 闭环；发票报销、预算执行、现金流异常、往来对账、经营分析属于后续模块  
+**更新日期**: 2026-07-06
+
+## 技术栈
+
+### 前端
+- **框架**: Next.js 14+ (React 18+)
+- **语言**: TypeScript 5+
+- **样式**: Tailwind CSS 3+
+- **UI 组件**: Shadcn/ui (基于 Radix UI)
+- **状态管理**: React Context + Zustand
+- **HTTP 客户端**: Axios
+- **表单**: React Hook Form + Zod
+- **图表**: Recharts
+- **图标**: Lucide Icons
+- **文件上传**: React Dropzone
+- **Excel 处理**: SheetJS (xlsx)
+
+### 后端
+- **框架**: FastAPI 0.110+
+- **语言**: Python 3.11+
+- **验证**: Pydantic 2+
+- **ORM**: SQLAlchemy 2+ with asyncio
+- **数据库驱动**: asyncpg (PostgreSQL)
+- **认证**: JWT (python-jose)
+- **密码**: bcrypt
+- **文件处理**: openpyxl, pandas
+- **AI**: OpenAI SDK / 国产大模型 SDK
+- **任务队列**: Celery + Redis (第二阶段)
+- **日志**: structlog
+
+### 数据库
+- **主库**: PostgreSQL 15+
+- **缓存**: Redis 7+ (第二阶段)
+
+### 部署
+- **容器**: Docker + Docker Compose
+- **Web 服务器**: Nginx (反向代理)
+- **进程管理**: Uvicorn (FastAPI ASGI)
+
+## 本地环境要求
+
+### 必需
+- Node.js 20+ 和 npm 10+
+- Python 3.11+
+- PostgreSQL 15+
+- Docker 和 Docker Compose (推荐)
+
+### 可选
+- Redis 7+ (第二阶段)
+
+## 环境变量
+
+### 前端 `.env.local`
+
+```bash
+# API 地址
+NEXT_PUBLIC_API_URL=http://localhost:8000
+
+# 应用配置
+NEXT_PUBLIC_APP_NAME="财务 AI 助手（薪财通 AI）"
+NEXT_PUBLIC_APP_VERSION=1.0.0
+```
+
+### 后端 `.env`
+
+```bash
+# 应用配置
+APP_NAME="财务 AI 助手 API"
+APP_VERSION=1.0.0
+DEBUG=true
+SECRET_KEY=your-secret-key-change-in-production
+ALLOWED_ORIGINS=http://localhost:3000
+
+# 数据库
+DATABASE_URL=postgresql+asyncpg://s2f_user:s2f_password@localhost:5432/s2f_db
+
+# JWT
+JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
+JWT_ALGORITHM=HS256
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+# AI 模型
+OPENAI_API_KEY=your-openai-api-key
+OPENAI_MODEL=gpt-4-turbo-preview
+# 默认使用智谱，也可切换 openai / qwen / baidu
+AI_PROVIDER=zhipu
+ZHIPU_API_KEY=your-zhipu-api-key
+AI_API_KEY=your-ai-api-key
+
+# 文件存储
+UPLOAD_DIR=./uploads
+MAX_UPLOAD_SIZE=10485760  # 10MB
+
+# 日志
+LOG_LEVEL=INFO
+```
+
+## 项目结构
+
+```
+s2f/
+├── frontend/                # Next.js 前端
+│   ├── src/
+│   │   ├── app/            # App Router 页面
+│   │   ├── components/     # React 组件
+│   │   ├── lib/            # 工具函数、API 客户端
+│   │   ├── hooks/          # 自定义 Hooks
+│   │   ├── types/          # TypeScript 类型
+│   │   └── styles/         # 全局样式
+│   ├── public/             # 静态资源
+│   ├── package.json
+│   └── tsconfig.json
+├── backend/                 # FastAPI 后端
+│   ├── app/
+│   │   ├── api/            # API 路由
+│   │   ├── core/           # 核心配置
+│   │   ├── models/         # SQLAlchemy 模型
+│   │   ├── schemas/        # Pydantic 模式
+│   │   ├── services/       # 业务逻辑
+│   │   ├── utils/          # 工具函数
+│   │   └── main.py         # 应用入口
+│   ├── migrations/         # Alembic 迁移
+│   ├── tests/              # 测试
+│   ├── requirements.txt
+│   └── pyproject.toml
+├── pmdocs/                  # 项目管理文档
+│   ├── 0-req-S2F.md
+│   ├── 1-prd-S2F.md
+│   └── 2-task-S2F.md
+├── docker-compose.yml       # Docker Compose 配置
+├── .gitignore
+├── README.md
+└── run.md                   # 本文件
+```
+
+## 安装与初始化
+
+### 方式 1：使用 Docker Compose（推荐）
+
+```bash
+# 克隆项目
+cd /Users/freedak/Documents/AIDashboard/s2f
+
+# 启动所有服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 前端: http://localhost:3000
+# 后端 API: http://localhost:8000
+# API 文档: http://localhost:8000/docs
+```
+
+### 方式 2：本地开发
+
+#### 1. 数据库初始化
+
+```bash
+# 安装 PostgreSQL (macOS)
+brew install postgresql@15
+brew services start postgresql@15
+
+# 创建数据库和用户
+psql postgres
+CREATE DATABASE s2f_db;
+CREATE USER s2f_user WITH PASSWORD 's2f_password';
+GRANT ALL PRIVILEGES ON DATABASE s2f_db TO s2f_user;
+\q
+```
+
+#### 2. 后端初始化
+
+```bash
+cd backend
+
+# 创建虚拟环境
+python3.11 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 配置环境变量
+cp .env.example .env
+# 编辑 .env 填入真实配置
+
+# 数据库迁移
+alembic upgrade head
+
+# 创建初始管理员账号
+python scripts/create_admin.py
+```
+
+#### 3. 前端初始化
+
+```bash
+cd frontend
+
+# 安装依赖
+npm install
+
+# 配置环境变量
+cp .env.example .env.local
+# 编辑 .env.local 填入 API 地址
+```
+
+## 开发命令
+
+### 前端开发
+
+```bash
+cd frontend
+
+# 启动开发服务器 (http://localhost:3000)
+npm run dev
+
+# 类型检查
+npm run type-check
+
+# Lint 检查
+npm run lint
+
+# 代码格式化
+npm run format
+```
+
+### 后端开发
+
+```bash
+cd backend
+source venv/bin/activate
+
+# 启动开发服务器 (http://localhost:8000)
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# 或使用 FastAPI CLI
+fastapi dev app/main.py
+
+# 查看 API 文档
+# http://localhost:8000/docs (Swagger UI)
+# http://localhost:8000/redoc (ReDoc)
+```
+
+## 构建命令
+
+### 前端构建
+
+```bash
+cd frontend
+
+# 生产构建
+npm run build
+
+# 启动生产服务器
+npm run start
+```
+
+### 后端构建
+
+```bash
+cd backend
+
+# FastAPI 不需要构建，直接运行
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## 测试命令
+
+### 前端测试
+
+```bash
+cd frontend
+
+# 运行所有测试
+npm run test
+
+# 监听模式
+npm run test:watch
+
+# 覆盖率报告
+npm run test:coverage
+```
+
+### 后端测试
+
+```bash
+cd backend
+source venv/bin/activate
+
+# 运行所有测试
+pytest
+
+# 监听模式
+pytest-watch
+
+# 覆盖率报告
+pytest --cov=app --cov-report=html
+```
+
+### 端到端测试
+
+```bash
+cd frontend
+
+# 运行 E2E 测试 (Playwright)
+npm run test:e2e
+
+# 打开 Playwright UI
+npm run test:e2e:ui
+```
+
+## 数据库命令
+
+### Alembic 迁移
+
+```bash
+cd backend
+source venv/bin/activate
+
+# 创建迁移
+alembic revision --autogenerate -m "描述变更"
+
+# 执行迁移
+alembic upgrade head
+
+# 回滚迁移
+alembic downgrade -1
+
+# 查看迁移历史
+alembic history
+
+# 查看当前版本
+alembic current
+```
+
+### 数据库管理
+
+```bash
+# 连接数据库
+psql -U s2f_user -d s2f_db
+
+# 备份数据库
+pg_dump -U s2f_user s2f_db > backup.sql
+
+# 恢复数据库
+psql -U s2f_user s2f_db < backup.sql
+
+# 重置数据库（危险！）
+psql -U s2f_user
+DROP DATABASE s2f_db;
+CREATE DATABASE s2f_db;
+\q
+cd backend && alembic upgrade head
+```
+
+## 代码质量
+
+### 前端
+
+```bash
+cd frontend
+
+# ESLint 检查
+npm run lint
+
+# 自动修复
+npm run lint:fix
+
+# Prettier 格式化
+npm run format
+
+# TypeScript 类型检查
+npm run type-check
+```
+
+### 后端
+
+```bash
+cd backend
+source venv/bin/activate
+
+# Ruff Lint 检查
+ruff check app/
+
+# 自动修复
+ruff check --fix app/
+
+# Black 格式化
+black app/
+
+# MyPy 类型检查
+mypy app/
+```
+
+## Docker 命令
+
+```bash
+# 构建镜像
+docker-compose build
+
+# 启动服务
+docker-compose up -d
+
+# 停止服务
+docker-compose down
+
+# 查看日志
+docker-compose logs -f [service_name]
+
+# 进入容器
+docker-compose exec backend bash
+docker-compose exec frontend sh
+
+# 重建并重启
+docker-compose up -d --build
+
+# 清理所有数据（危险！）
+docker-compose down -v
+```
+
+## 常见问题
+
+### 1. 前端无法连接后端
+
+**问题**：前端显示网络错误
+
+**解决**：
+```bash
+# 确认后端正在运行
+curl http://localhost:8000/api/health
+
+# 检查 CORS 配置
+# backend/app/core/config.py 中 ALLOWED_ORIGINS 需包含前端地址
+```
+
+### 2. 数据库连接失败
+
+**问题**：`sqlalchemy.exc.OperationalError: could not connect to server`
+
+**解决**：
+```bash
+# 确认 PostgreSQL 正在运行
+pg_isready -h localhost -p 5432
+
+# 确认数据库存在
+psql -U s2f_user -l | grep s2f_db
+
+# 检查 DATABASE_URL 配置
+echo $DATABASE_URL
+```
+
+### 3. AI 字段识别失败
+
+**问题**：上传文件后识别超时或失败
+
+**解决**：
+```bash
+# 检查 AI API Key
+echo $OPENAI_API_KEY
+
+# 测试 API 连接
+curl https://api.openai.com/v1/models \
+  -H "Authorization: Bearer $OPENAI_API_KEY"
+
+# 查看后端日志
+docker-compose logs backend | grep -i "openai\|error"
+```
+
+### 4. 文件上传失败
+
+**问题**：上传文件时显示 413 或 500 错误
+
+**解决**：
+```bash
+# 检查文件大小限制
+# backend/.env 中 MAX_UPLOAD_SIZE=10485760 (10MB)
+
+# 确认上传目录权限
+ls -la backend/uploads/
+chmod 755 backend/uploads/
+
+# 检查磁盘空间
+df -h
+```
+
+### 5. 前端构建失败
+
+**问题**：`npm run build` 报错
+
+**解决**：
+```bash
+# 清理缓存
+rm -rf frontend/.next frontend/node_modules
+cd frontend && npm install
+
+# 检查 TypeScript 错误
+npm run type-check
+
+# 检查环境变量
+cat frontend/.env.local
+```
+
+## 部署检查清单
+
+部署前确认：
+
+- [ ] 环境变量已配置（生产环境不使用默认密钥）
+- [ ] 数据库迁移已执行
+- [ ] 前端已构建 (`npm run build`)
+- [ ] HTTPS 已配置
+- [ ] CORS 已正确配置生产域名
+- [ ] 文件上传目录有正确权限
+- [ ] 日志目录可写
+- [ ] 备份策略已配置
+- [ ] 监控和告警已配置
+
+## 性能优化建议
+
+### 前端
+- 使用 Next.js 的 Image 组件优化图片
+- 启用 React Server Components 减少客户端 JS
+- 使用动态导入按需加载组件
+- 配置合理的缓存策略
+
+### 后端
+- 为频繁查询添加数据库索引
+- 使用连接池优化数据库连接
+- 对 AI 请求添加缓存（第二阶段）
+- 启用 Gzip 压缩
+
+### 数据库
+- 定期 VACUUM 和 ANALYZE
+- 监控慢查询日志
+- 合理设置连接池大小
+
+## 安全建议
+
+- 生产环境必须更改所有默认密钥
+- 使用 HTTPS
+- 启用 CSRF 保护
+- 限制文件上传类型和大小
+- 定期更新依赖
+- 启用日志审计
+- 配置防火墙规则
+- 数据库使用强密码并限制访问
+
+## 监控与日志
+
+### 日志位置
+
+```bash
+# 前端日志
+frontend/.next/
+
+# 后端日志
+backend/logs/
+
+# Docker 日志
+docker-compose logs
+```
+
+### 推荐监控指标
+
+- API 响应时间
+- 数据库查询时间
+- AI 识别准确率
+- 文件上传成功率
+- 错误率和异常日志
+- 磁盘使用率
+- 内存使用率
+
+## 更新记录
+
+| 日期 | 版本 | 变更内容 |
+|---|---|---|
+| 2026-07-06 | v1.0 | 初始版本，MVP 技术栈和运行命令 |
+
+---
+
+**下一步**: 参考 `pmdocs/2-task-S2F.md` 开始开发任务