# 财务 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` 开始开发任务