freedak/s2f
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
18c889e2a75b9db11484351febfd7f2e86f8456d
s2f/run.md
T
freedakgmail 6833106829 chore: 初始化项目与后端基础工程
2026-07-06 22:03:22 +08:00

11 KiB
Raw Blame History

财务 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

# API 地址
NEXT_PUBLIC_API_URL=http://localhost:8000

# 应用配置
NEXT_PUBLIC_APP_NAME="财务 AI 助手（薪财通 AI）"
NEXT_PUBLIC_APP_VERSION=1.0.0

后端 .env

# 应用配置
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（推荐）

# 克隆项目
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. 数据库初始化

# 安装 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. 后端初始化

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. 前端初始化

cd frontend

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 填入 API 地址

开发命令

前端开发

cd frontend

# 启动开发服务器 (http://localhost:3000)
npm run dev

# 类型检查
npm run type-check

# Lint 检查
npm run lint

# 代码格式化
npm run format

后端开发

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)

构建命令

前端构建

cd frontend

# 生产构建
npm run build

# 启动生产服务器
npm run start

后端构建

cd backend

# FastAPI 不需要构建，直接运行
uvicorn app.main:app --host 0.0.0.0 --port 8000

测试命令

前端测试

cd frontend

# 运行所有测试
npm run test

# 监听模式
npm run test:watch

# 覆盖率报告
npm run test:coverage

后端测试

cd backend
source venv/bin/activate

# 运行所有测试
pytest

# 监听模式
pytest-watch

# 覆盖率报告
pytest --cov=app --cov-report=html

端到端测试

cd frontend

# 运行 E2E 测试 (Playwright)
npm run test:e2e

# 打开 Playwright UI
npm run test:e2e:ui

数据库命令

Alembic 迁移

cd backend
source venv/bin/activate

# 创建迁移
alembic revision --autogenerate -m "描述变更"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 查看当前版本
alembic current

数据库管理

# 连接数据库
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

代码质量

前端

cd frontend

# ESLint 检查
npm run lint

# 自动修复
npm run lint:fix

# Prettier 格式化
npm run format

# TypeScript 类型检查
npm run type-check

后端

cd backend
source venv/bin/activate

# Ruff Lint 检查
ruff check app/

# 自动修复
ruff check --fix app/

# Black 格式化
black app/

# MyPy 类型检查
mypy app/

Docker 命令

# 构建镜像
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. 前端无法连接后端

问题：前端显示网络错误

解决：

# 确认后端正在运行
curl http://localhost:8000/api/health

# 检查 CORS 配置
# backend/app/core/config.py 中 ALLOWED_ORIGINS 需包含前端地址

2. 数据库连接失败

问题：sqlalchemy.exc.OperationalError: could not connect to server

解决：

# 确认 PostgreSQL 正在运行
pg_isready -h localhost -p 5432

# 确认数据库存在
psql -U s2f_user -l | grep s2f_db

# 检查 DATABASE_URL 配置
echo $DATABASE_URL

3. AI 字段识别失败

问题：上传文件后识别超时或失败

解决：

# 检查 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 错误

解决：

# 检查文件大小限制
# backend/.env 中 MAX_UPLOAD_SIZE=10485760 (10MB)

# 确认上传目录权限
ls -la backend/uploads/
chmod 755 backend/uploads/

# 检查磁盘空间
df -h

5. 前端构建失败

问题：npm run build 报错

解决：

# 清理缓存
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 保护
  • 限制文件上传类型和大小
  • 定期更新依赖
  • 启用日志审计
  • 配置防火墙规则
  • 数据库使用强密码并限制访问

监控与日志

日志位置

# 前端日志
frontend/.next/

# 后端日志
backend/logs/

# Docker 日志
docker-compose logs

推荐监控指标

  • API 响应时间
  • 数据库查询时间
  • AI 识别准确率
  • 文件上传成功率
  • 错误率和异常日志
  • 磁盘使用率
  • 内存使用率

更新记录

日期 版本 变更内容
2026-07-06 v1.0 初始版本，MVP 技术栈和运行命令

下一步: 参考 pmdocs/2-task-S2F.md 开始开发任务

Reference in New Issue View Git Blame Copy Permalink