# 财务 AI 助手（S2F / 薪财通 AI）

面向金蝶中小企业客户的财务 AI 助手。当前第一模块为 **薪财通 AI / 薪酬财务对账 MVP**，通过 Excel 上传与导出完成闭环：

```text
上传工资/社保/个税表
  ↓
AI 字段识别与用户确认
  ↓
薪酬、社保、个税、公积金对账
  ↓
异常清单与人工成本分析
  ↓
AI 问答（基于真实数据）
  ↓
生成会计凭证 → 导出金蝶格式
```

## 核心功能

- **AI 工作台**：首页集成 AI 助手，支持预置问题问答和自由提问，基于真实对账数据回答
- **文件上传与解析**：支持工资表、社保表、个税表 Excel 上传，自动解析
- **AI 字段识别**：自动识别源字段到标准字段的映射，支持人工确认和规则沉淀
- **智能对账**：多表交叉对账，自动检测金额不一致、记录缺失等异常
- **异常处理**：异常列表、详情、批量处理，支持按状态/严重程度/类型筛选
- **人工成本分析**：总额、部门拆分、费用科目拆分、环比变化，AI 生成分析摘要
- **凭证生成**：根据科目映射自动生成会计凭证，支持借贷分录预览
- **金蝶导出**：支持金蝶 K3 CSV 格式和 Excel 格式导出
- **科目映射管理**：可自定义标准字段到会计科目的映射关系

## 项目边界

- 不替代金蝶账套
- 不做完整财务软件
- 不做完整 HR SaaS
- 第一阶段只实现薪酬财务对账 MVP

## 技术栈

| 层级 | 技术 |
|---|---|
| 前端 | Next.js 15 + TypeScript + Tailwind CSS + Shadcn/ui + Recharts |
| 后端 | Python FastAPI + Pydantic + SQLAlchemy (async) |
| 数据库 | PostgreSQL 15+ |
| 缓存 | Redis 7+ |
| AI | 智谱 GLM-4 / OpenAI GPT-4 |
| 部署 | Docker + Docker Compose + Nginx |

## 目录结构

```text
s2f/
├── frontend/              # Next.js 前端
│   ├── app/(dashboard)/   # 仪表板页面（工作台/任务/异常/分析/凭证）
│   ├── app/(auth)/        # 认证页面（登录/注册）
│   ├── components/        # UI 组件库
│   └── lib/               # API 客户端、状态管理、Hooks
├── backend/               # FastAPI 后端
│   ├── app/models/        # 数据模型
│   ├── app/services/      # 业务服务（对账/分析/凭证/AI）
│   ├── app/api/           # API 路由
│   └── app/core/          # 配置/数据库/认证/日志
├── nginx/                 # Nginx 反向代理配置
├── pmdocs/                # 需求、PRD、任务文档
├── docker-compose.yml     # Docker 编排
├── .env.example           # 环境变量模板
└── README.md
```

## 文档入口

- 需求文档：`pmdocs/0-req-S2F.md`
- PRD 文档：`pmdocs/1-prd-S2F.md`
- 任务文档：`pmdocs/2-task-S2F.md`

## 快速启动

### 方式一：Docker Compose（推荐）

```bash
# 1. 复制环境变量
cp .env.example .env
# 编辑 .env，填入 AI API Key 等配置

# 2. 启动所有服务
docker-compose up -d

# 3. 初始化数据库
docker-compose exec backend python -c "from app.core.database import init_db; import asyncio; asyncio.run(init_db())"

# 4. 访问
# 前端: http://localhost:3000
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs
```

### 方式二：本地开发

```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
```

## API 端点概览

| 模块 | 路径 | 说明 |
|---|---|---|
| 认证 | `/api/auth/*` | 登录/注册/刷新 Token |
| 任务 | `/api/tasks/*` | 对账任务 CRUD |
| 文件 | `/api/files/*` | 文件上传/下载 |
| 字段映射 | `/api/mappings/*` | AI 识别/确认/规则 |
| 对账 | `/api/reconciliation/*` | 执行对账/查看结果 |
| 异常 | `/api/exceptions/*` | 异常列表/处理 |
| 成本分析 | `/api/analysis/*` | 成本计算/导出 |
| 问答 | `/api/qa/*` | AI 问答 |
| 凭证 | `/api/vouchers/*` | 生成/确认/导出/科目映射 |

## 开发顺序

按 `pmdocs/2-task-S2F.md` 执行：

1. ✅ 项目初始化
2. ✅ 后端基础设施
3. ✅ 前端基础设施
4. ✅ 认证与权限
5. ✅ 文件上传与解析
6. ✅ AI 字段识别
7. ✅ 对账与异常检测
8. ✅ 人工成本分析
9. ✅ 凭证生成与金蝶导出
10. ✅ AI 工作台与 UI 页面
11. ✅ Docker 部署与 Nginx 配置