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

pmdocs/0-req-S2F.md

@@ -0,0 +1,547 @@
+# 财务 AI 助手需求文档（第一模块：薪酬财务对账）
+
+**项目编号**: S2F  
+**文档版本**: v1.0  
+**创建日期**: 2026-07-06  
+**状态**: 已确认
+
+## 1. 引言与目标
+
+### 1.1 产品概述
+
+本项目定位为面向金蝶中小企业客户的财务 AI 助手。产品不替代金蝶账套，而是作为金蝶财务系统前置的 AI 中间层，帮助财务人员把分散在 Excel、业务系统、HR、发票、报销、银行流水等来源中的数据，整理成可核对、可解释、可导入金蝶的结构化结果。
+
+第一阶段先建设“薪酬财务对账模块”（第一模块，内部产品名：薪财通 AI），解决"HR 数据到财务凭证之间"的整理、核对、解释和转换工作。后续阶段再扩展发票报销、预算执行、现金流异常、往来对账和经营分析等财务 AI 助手能力。
+
+### 1.2 核心价值主张
+
+**总体价值：把分散财务数据整理成可核对、可解释、可入账的结构化结果。**
+
+**第一模块价值：将薪酬对账工作从 3 天压缩到 30 分钟。**
+
+使用金蝶的中小企业财务人员，第一阶段每月只需上传工资、社保、个税等表格，AI 自动完成薪酬对账、异常识别、成本分析和凭证生成。
+
+### 1.3 业务目标
+
+**总项目目标**：
+- 建设面向金蝶中小企业客户的财务 AI 助手
+- 帮助财务人员完成数据整理、对账、解释、凭证生成和经营分析辅助
+- 在不替代金蝶的前提下，补齐“业务数据/Excel 到财务系统”之间的 AI 中间层能力
+
+**第一模块目标**：
+- 帮助财务人员节省 90% 以上的薪酬对账时间
+- 降低人工对账错误率（目标准确率 > 90%）
+- 提升财务与 HR 数据口径一致性
+- 为企业节省人力成本（100人企业年节省 3.6-5.4 万元）
+
+### 1.4 产品定位与边界
+
+**总项目定位**：
+- 财务 AI 助手，服务金蝶中小企业客户
+- 金蝶财务软件的增效工具，而非替代品
+- 连接业务数据、Excel 数据、HR 数据、发票/报销数据、银行流水与金蝶财务系统
+- AI 辅助决策，不替代财务人员的专业判断
+
+**第一阶段定位**：
+- 第一模块为薪酬财务对账，不是项目的全部边界
+- 第一阶段专注工资、社保、公积金、个税、人工成本分析和金蝶凭证生成
+- 先验证一个高频财务场景，再扩展为完整财务 AI 助手
+
+**明确不做**（避免与金蝶竞争）：
+- ❌ 账套管理
+- ❌ 正式凭证入账
+- ❌ 法定财务报表生成
+- ❌ ERP 和进销存主流程
+- ❌ 银行支付和资金调拨
+
+## 2. 术语表
+
+| 术语 | 定义 |
+|---|---|
+| 薪酬对账 | 核对工资表、社保表、个税表、银行回单等多源数据的一致性 |
+| 金蝶凭证 | 符合金蝶财务软件导入格式的会计凭证模板 |
+| 字段映射 | AI 识别不同企业表格中相同含义但命名不同的字段 |
+| 异常检测 | 自动识别离职未停社保、个税不匹配等常见错误 |
+| 部门成本分摊 | 将人工成本按部门或费用科目拆分 |
+| 多租户 | 不同企业数据严格隔离，互不可见 |
+| 私有化部署 | 企业在自己的服务器上部署系统 |
+
+## 3. 角色定义
+
+### 3.1 核心用户
+
+**财务主管**
+- 职责：审核薪酬对账结果、人工成本分析、凭证生成
+- 痛点：每月对账耗时长、异常难追溯、老板经常追问成本变化
+- 使用场景：查看异常清单、审核凭证、生成成本分析报告
+
+**总账会计**
+- 职责：执行薪酬对账、生成凭证、导入金蝶
+- 痛点：表格来源多、格式不统一、重复性工作多
+- 使用场景：上传表格、处理异常、导出凭证模板
+
+**出纳兼会计**（中小企业常见）
+- 职责：工资发放、社保缴纳、凭证入账
+- 痛点：身兼多职、时间紧、容易出错
+- 使用场景：快速完成对账和凭证生成
+
+### 3.2 相关用户
+
+**HR 薪酬专员**
+- 职责：提供工资表、社保表、考勤数据
+- 使用场景：可选上传权限，协助财务核对
+
+**企业老板/管理层**
+- 职责：关注人工成本变化
+- 使用场景：查看人工成本分析报告（第二阶段移动端）
+
+**外包记账公司**（潜在客群）
+- 职责：代理多家企业的财务工作
+- 使用场景：批量处理多个企业的薪酬对账（企业版）
+
+## 4. 功能性需求
+
+### 4.0 财务 AI 助手模块规划
+
+| 阶段 | 模块 | 目标 | 状态 |
+|---|---|---|---|
+| 第一阶段 | 薪酬财务对账助手 | 工资、社保、个税、公积金对账，人工成本分析，金蝶凭证生成 | 本需求文档详细定义 |
+| 第二阶段 | 薪酬模块自动化增强 | 历史对比、企业规则沉淀、自动文件夹监控、完整自然语言问答 | 规划中 |
+| 第三阶段 | 金蝶生态连接 | 金蝶 API、多账套、行业模板、代账公司批量处理 | 规划中 |
+| 第四阶段 | 财务 AI 助手扩展 | 发票报销、预算执行、现金流异常、往来对账、经营分析看板 | 路线规划 |
+
+### 4.1 MVP 核心功能（第一阶段：薪酬财务对账模块）
+
+#### REQ-001: 薪酬数据上传
+
+**WHEN** 财务人员需要进行月度薪酬对账  
+**THE system SHALL** 支持通过 Web 界面拖拽上传 Excel 文件（.xls / .xlsx / .csv）
+
+**输入要求**：
+- 工资表（必需）
+- 社保表（必需）
+- 个税表（必需）
+
+**约束条件**：
+- 单次上传文件大小 < 10MB
+- 支持 50-500 人规模数据
+- 文件格式自动识别
+
+#### REQ-002: AI 字段智能识别
+
+**WHEN** 用户上传 Excel 文件  
+**THE system SHALL** 使用 AI 自动识别字段含义并生成映射建议
+
+**识别字段**：
+- 员工姓名、工号、部门、岗位
+- 应发工资、实发工资、个税
+- 社保个人部分、社保公司部分
+- 公积金个人部分、公积金公司部分
+- 奖金、提成、扣款
+
+**要求**：
+- 识别准确率 > 90%
+- 支持用户手动修正
+- 记住企业历史映射规则，下次自动应用
+
+#### REQ-003: 薪酬对账与异常检测
+
+**WHEN** 字段映射完成  
+**THE system SHALL** 自动执行多维度对账并输出异常清单
+
+**检测规则**：
+- 离职员工仍有工资发放
+- 入职员工未缴社保
+- 已离职员工社保未停缴
+- 个税金额与工资数据不匹配
+- 社保基数异常波动（环比变化 > 30%）
+- 公积金缴纳比例异常（超出合理范围 5%-12% 或与历史月份差异 > 2%）
+- 部门归属为空或与上月不一致
+- 银行实发金额与工资表实发金额不一致（第二阶段）
+
+**输出**：
+- 异常清单 Excel（异常类型、员工姓名、详细说明、建议处理方式）
+
+#### REQ-004: 人工成本分析
+
+**WHEN** 对账完成  
+**THE system SHALL** 自动生成月度人工成本分析报告
+
+**分析维度**：
+- 本月人工成本总额（工资 + 社保 + 公积金）
+- 与上月环比变化（金额、比例）
+- 按部门拆分的人工成本明细
+- 按费用科目拆分（管理费用、销售费用、研发费用）
+- 新增/离职员工带来的成本变化
+- 奖金、提成等特殊项目影响
+
+**输出格式**：
+- Excel 报表
+- 支持复制到月度经营分析
+
+#### REQ-005: 金蝶凭证模板生成
+
+**WHEN** 用户确认对账结果  
+**THE system SHALL** 根据企业配置生成可导入金蝶的凭证模板
+
+**凭证类型**：
+- 工资计提凭证
+- 工资发放凭证
+- 个税计提/代扣凭证
+- 社保凭证（公司部分 + 个人部分）
+- 公积金凭证（公司部分 + 个人部分）
+- 部门费用分摊凭证
+
+**要求**：
+- 支持自定义科目映射
+- 记住企业规则配置
+- Excel 格式符合金蝶导入规范
+
+#### REQ-006: 预置问题问答
+
+**WHEN** 用户在 AI 工作台、成本分析页面查看数据  
+**THE system SHALL** 提供预置问题列表，用户点击后基于当前数据返回答案
+
+**预置问题示例**：
+- 本月还缺哪些文件？
+- 哪些字段需要人工确认？
+- 哪些异常最严重？
+- 为什么本月人工成本上涨/下降？
+- 哪些部门变化最大？
+- 现在可以生成金蝶凭证吗？
+
+**要求**：
+- 不做开放式对话，仅支持预置问题
+- 答案基于当前任务数据生成
+- 响应时间 < 3 秒
+- 答案包含关键数据点（金额、比例、员工名单）
+
+**AI Native 价值**：
+- 降低用户查找信息成本
+- 主动提示关键问题
+- 提升"AI 助手"体验
+
+### 4.2 第二阶段功能（暂不实现）
+
+- 自动文件夹监控（本地 + 网盘同步）
+- 可选输入文件支持（公积金表、考勤表、银行回单）
+- 历史数据对比（12个月环比/同比）
+- **完整自然语言问答**（开放式对话，不限于预置问题）
+- 金蝶 API 直接对接
+- 移动端支持
+
+## 5. 非功能性需求
+
+### 5.1 性能要求
+
+**NFR-001: 数据处理性能**
+- WHEN 处理 200 人企业的薪酬数据  
+- THE system SHALL 在 30 秒内完成从上传到结果输出
+
+**NFR-002: AI 识别性能**
+- WHEN 执行 AI 字段识别  
+- THE system SHALL 在 5 秒内返回映射结果
+
+**NFR-003: 凭证生成性能**
+- WHEN 生成金蝶凭证模板  
+- THE system SHALL 在 3 秒内完成生成和下载准备
+
+**NFR-004: 并发支持**
+- WHEN 多个用户同时使用系统  
+- THE system SHALL 支持至少 50 个并发用户
+
+### 5.2 安全要求
+
+**NFR-005: 数据传输安全**
+- THE system SHALL 使用 HTTPS 加密传输所有数据
+- THE system SHALL 对文件上传进行加密处理
+
+**NFR-006: 数据存储安全**
+- THE system SHALL 使用 AES-256 加密存储敏感数据
+- THE system SHALL 对员工姓名进行脱敏展示（张**、李**）
+- THE system SHALL 支持定期数据库备份
+
+**NFR-007: 访问控制**
+- THE system SHALL 实现多租户严格隔离（企业 A 无法访问企业 B 数据）
+- THE system SHALL 支持按角色权限控制：
+  - 财务主管：全部权限
+  - 总账会计：查看和编辑权限
+  - 出纳：仅查看权限
+  - HR：可选上传权限
+
+**NFR-008: 审计日志**
+- THE system SHALL 记录所有数据访问和操作日志
+- THE system SHALL 保留审计日志 3 年
+
+**NFR-009: 数据删除机制**
+- THE system SHALL 支持用户主动删除历史数据
+- THE system SHALL 在企业注销后 30 天内自动删除所有数据
+- THE system SHALL 符合《个人信息保护法》要求
+
+### 5.3 可用性要求
+
+**NFR-010: 界面友好性**
+- THE system SHALL 提供直观的拖拽上传界面
+- THE system SHALL 在每个关键步骤提供操作指引
+- THE system SHALL 支持"一键修正"异常字段映射
+
+**NFR-011: 错误提示**
+- THE system SHALL 在操作失败时提供明确的错误原因和解决建议
+- THE system SHALL 在数据异常时提供上下文说明
+
+**NFR-012: 新手引导**
+- THE system SHALL 为首次使用的用户提供完整操作演示
+- THE system SHALL 提供示例数据供用户快速体验
+
+### 5.4 兼容性要求
+
+**NFR-013: 浏览器兼容**
+- THE system SHALL 支持 Chrome、Edge、Safari、Firefox 最新两个版本
+- THE system SHALL 优先优化 Chrome 体验
+
+**NFR-014: 文件格式兼容**
+- THE system SHALL 支持 .xls、.xlsx、.csv 格式
+- THE system SHALL 兼容 Excel 2007 及以上版本
+
+**NFR-015: 金蝶版本兼容**
+- THE system SHALL 生成的凭证模板兼容金蝶云星辰、精斗云、K/3
+
+### 5.5 可扩展性要求
+
+**NFR-016: 数据规模扩展**
+- THE system SHALL 支持从 50 人扩展到 1000 人企业
+- THE system SHALL 在不重构的前提下支持数据量线性增长
+
+**NFR-017: 功能扩展**
+- THE system SHALL 设计模块化架构，便于后续增加新功能
+- THE system SHALL 预留 API 接口，便于第三方集成
+
+### 5.6 可维护性要求
+
+**NFR-018: 代码质量**
+- THE system SHALL 使用 TypeScript 提供类型安全
+- THE system SHALL 保持核心模块测试覆盖率 > 80%
+- THE system SHALL 遵循 RESTful API 设计规范
+
+**NFR-019: 部署要求**
+- THE system SHALL 支持 Docker 容器化部署
+- THE system SHALL 支持私有化部署（Docker Compose）
+- THE system SHALL 提供完整的部署文档和脚本
+
+**NFR-020: 监控与日志**
+- THE system SHALL 记录所有 API 调用和性能指标
+- THE system SHALL 在异常发生时自动记录堆栈信息
+
+### 5.7 合规性要求
+
+**NFR-021: 数据合规**
+- THE system SHALL 符合《个人信息保护法》
+- THE system SHALL 符合《数据安全法》
+- THE system SHALL 提供数据处理协议模板
+
+**NFR-022: 财务合规**
+- THE system SHALL 生成的凭证符合企业会计准则
+- THE system SHALL 在界面明确标注"最终决策权在财务人员"
+
+### 5.8 数据保留策略
+
+**NFR-023: 历史数据保留**
+- 免费版：仅保留当月数据
+- 基础版：保留 12 个月历史数据
+- 专业版：保留 36 个月历史数据
+- 企业版：无限制保留（可配置）
+
+## 6. 范围边界
+
+### 6.1 包含（In Scope）
+
+✅ 手动上传 Excel 表格  
+✅ AI 字段识别和映射  
+✅ 工资、社保、个税对账  
+✅ 异常检测与清单生成  
+✅ 人工成本分析  
+✅ 金蝶凭证模板导出  
+✅ 多租户数据隔离  
+✅ 基础安全（加密、访问控制、审计）  
+✅ Docker 私有化部署  
+
+### 6.2 不包含（Out of Scope - 第一阶段）
+
+❌ 自动文件夹监控  
+❌ 金蝶 API 直接对接  
+❌ 移动端应用  
+❌ 复杂审批流  
+❌ 完整 HR 系统功能  
+❌ 银行支付系统对接  
+❌ 个税/社保直接申报  
+❌ 等保三级认证  
+❌ **预算管理与预算执行跟踪**  
+❌ **发票真伪核验**  
+❌ **现金流监控与银行账户余额管理**  
+
+**说明**：
+- 预算管理、发票核验、现金流监控也是财务 AI 助手的目标场景，但不进入第一阶段薪酬财务对账 MVP
+- 这些功能进入第四阶段“财务 AI 助手扩展”，不应提前挤占第一模块的开发范围
+
+### 6.3 未来可能包含（Future Scope）
+
+⏰ 历史数据环比/同比分析（第二阶段）  
+⏰ 完整自然语言问答（第二阶段）  
+⏰ 自动文件夹监控（第二阶段）  
+⏰ 多账套支持（第三阶段）  
+⏰ 行业化模板（第三阶段）  
+⏰ 金蝶 API 对接（第三阶段）  
+⏰ **发票与报销 AI 助手**（第四阶段）  
+⏰ **预算执行 AI 分析**（第四阶段）  
+⏰ **现金流异常 AI 监控**（第四阶段）  
+⏰ **往来对账 AI 助手**（第四阶段）  
+⏰ **经营分析 AI 看板**（第四阶段）  
+
+## 7. 关键约束与假设
+
+### 7.1 技术约束
+
+- 前端：Next.js (React) + TypeScript + Tailwind CSS
+- 后端：Python (FastAPI) + Pydantic
+- 数据库：PostgreSQL
+- AI：LLM API（GPT-4 或国产大模型）
+- 部署：Docker + Docker Compose
+
+### 7.2 业务约束
+
+- 目标客群：50-500 人规模企业
+- 数据来源：Excel 手动上传（第一阶段）
+- 输出格式：Excel 凭证模板
+- 金蝶版本：兼容主流版本（云星辰、精斗云、K/3）
+
+### 7.3 资源约束
+
+- 开发周期：MVP 需在 3 个月内完成
+- 团队配置：产品经理 × 1，全栈工程师 × 2，AI 工程师 × 1
+- 初始预算：控制在合理范围（云服务、AI API 成本）
+
+### 7.4 关键假设
+
+- ✓ 假设目标用户已使用金蝶财务软件
+- ✓ 假设用户可以从 HR 或行政获取 Excel 表格
+- ✓ 假设用户有基本的 Excel 和财务知识
+- ✓ 假设不同企业的薪酬结构可以通过 AI 识别标准化
+- ✓ 假设异常检测规则可以覆盖 80% 以上的常见错误
+
+## 8. 验收标准
+
+### 8.1 功能验收
+
+- [ ] 可以成功上传工资表、社保表、个税表
+- [ ] AI 字段识别准确率 > 90%
+- [ ] 异常检测能覆盖 MVP 7 类异常，并保留第二阶段银行实发对账规则
+- [ ] 人工成本分析报告包含所有必需维度
+- [ ] 金蝶凭证模板可以被金蝶软件成功导入
+- [ ] 多租户数据严格隔离，无数据泄露
+
+### 8.2 性能验收
+
+- [ ] 200 人企业数据处理时间 < 30 秒
+- [ ] AI 字段识别响应时间 < 5 秒
+- [ ] 凭证生成时间 < 3 秒
+- [ ] 支持 50 个并发用户
+
+### 8.3 安全验收
+
+- [ ] 数据传输使用 HTTPS
+- [ ] 敏感数据已加密存储
+- [ ] 审计日志完整记录
+- [ ] 多租户隔离通过安全测试
+
+### 8.4 用户体验验收
+
+- [ ] 首次使用用户能在 15 分钟内完成一次完整流程
+- [ ] 新手引导清晰易懂
+- [ ] 错误提示明确具体
+- [ ] 异常处理流程顺畅
+
+### 8.5 商业验收（MVP 阶段）
+
+- [ ] 获得 10 个付费客户（或深度参与的种子用户）
+- [ ] 首月留存率 > 60%
+- [ ] NPS > 40
+- [ ] 用户平均完成时间 < 30 分钟
+
+## 9. 风险与依赖
+
+### 9.1 技术风险
+
+**RISK-001: AI 识别准确率不足**
+- 影响：用户需要大量修正，降低使用体验
+- 缓解措施：积累行业标准模板、记住企业规则、持续训练模型
+
+**RISK-002: 异常检测误报率高**
+- 影响：增加用户工作量，降低信任度
+- 缓解措施：规则可配置、提供"忽略"功能、基于反馈优化
+
+**RISK-003: 数据安全事故**
+- 影响：数据泄露导致法律责任和信任崩塌
+- 缓解措施：从第一天就做安全设计、购买网络安全保险、定期安全审计
+
+### 9.2 业务风险
+
+**RISK-004: 金蝶推出类似功能**
+- 影响：最大威胁，可能导致竞争失败
+- 缓解措施：快速获客建立先发优势、与代理商深度绑定、专注体验
+
+**RISK-005: 市场需求不足**
+- 影响：获客困难、用户流失高
+- 缓解措施：MVP 快速验证、深度访谈调整方向、灵活调整定价
+
+### 9.3 外部依赖
+
+- LLM API 稳定性和成本（GPT-4 或国产大模型）
+- 金蝶凭证导入格式兼容性
+- 用户提供的数据质量（表格格式、字段完整性）
+
+## 10. 需求优先级（MoSCoW）
+
+### Must Have（MVP 必须）
+- REQ-001: 薪酬数据上传
+- REQ-002: AI 字段智能识别
+- REQ-003: 薪酬对账与异常检测
+- REQ-004: 人工成本分析
+- REQ-005: 金蝶凭证模板生成
+- NFR-005 ~ NFR-009: 核心安全要求
+- NFR-010 ~ NFR-012: 可用性要求
+- NFR-019: Docker 部署支持
+
+### Should Have（第二阶段优先）
+- 历史数据保存（12 个月）
+- 环比变化分析
+- 自定义科目映射界面
+- 自然语言问答
+- 自动文件夹监控
+
+### Could Have（第二阶段可选）
+- 可选输入文件支持（公积金、考勤、银行回单）
+- 移动端查看
+- 金蝶 API 对接
+
+### Won't Have（第一阶段不做）
+- 完整 HR 系统
+- 银行支付对接
+- 个税/社保直接申报
+- 等保三级认证
+
+## 11. 关联文档
+
+- 产品方向建议：`../薪财通AI_产品方向建议.md`
+- PRD 文档：`pmdocs/1-prd-S2F.md`
+- 任务文档：`pmdocs/2-task-S2F.md`
+- 运行手册：`run.md`
+
+## 12. 变更历史
+
+| 版本 | 日期 | 变更内容 | 变更人 |
+|---|---|---|---|
+| v1.0 | 2026-07-06 | 初始版本，基于产品方向建议生成 | AI |
+
+---
+
+**当前状态**: 需求、PRD、任务文档与运行手册已生成，可进入开发执行阶段。