s2f/README.md

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

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

上传工资/社保/个税表
  ↓
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

目录结构

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（推荐）

# 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

方式二：本地开发

# 后端
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 配置