# Invoice Master - 开发计划

**版本**: v3.0  
**技术栈**: .NET 8 + ASP.NET Core + EF Core  
**开始日期**: 2026-02-03  
**预计周期**: 14 周（含 .NET 重构 + 多会计系统架构）

---

## 1. 里程碑总览

| 阶段 | 时间 | 目标 | 交付物 |
|------|------|------|--------|
| **M0** | Pre-Phase | 架构重构 | 多会计系统抽象层、数据库迁移 |
| **M1** | Week 1-2 | 基础架构 | 项目框架、数据库、认证模块 |
| **M2** | Week 3-4 | 核心功能 | OCR 集成、文件上传、供应商匹配 |
| **M3** | Week 5-6 | 会计系统集成 | 抽象层实现、Fortnox Provider |
| **M4** | Week 7-8 | UI 开发 | 前端界面、用户流程 |
| **M5** | Week 9-10 | 测试优化 | 单元测试、集成测试、性能优化 |
| **M6** | Week 11-12 | 上线准备 | 文档、审核、部署 |
| **M7** | Week 13-14 | 扩展准备 | Provider SDK、文档、示例 |

---

## 2. 详细任务分解

### Pre-Phase: 多会计系统架构重构 (Week 0)

#### 架构设计

**后端任务:**
- [x] 设计会计系统抽象层接口 (AccountingSystem ABC)
- [x] 创建通用数据模型 (Supplier, Voucher, Account)
- [x] 实现 Factory 模式注册机制
- [x] 重构数据库模型支持多会计系统
  - [x] `accounting_connections` 表 (通用连接表)
  - [x] `invoices` 表 (通用发票表)
  - [x] `supplier_cache` 表 (通用供应商缓存)
- [x] 迁移脚本更新
- [ ] API 路由重构为通用接口
- [ ] 更新依赖注入支持多 Provider

**文档:**
- [x] 更新 ARCHITECTURE.md
- [ ] 更新 API_DESIGN.md
- [x] 更新 DATABASE_SCHEMA.md

---

### Phase 1: 基础架构 (Week 1-2)

#### Week 1: 项目初始化 (.NET)

**后端任务:**
- [ ] 创建 .NET Solution 结构
  - [ ] `dotnet new sln -n InvoiceMaster`
  - [ ] 创建 5 个项目: API, Core, Application, Infrastructure, Integrations
  - [ ] 配置项目引用关系
- [ ] 配置 ASP.NET Core Web API
  - [ ] Program.cs 配置
  - [ ] appsettings.json 配置
  - [ ] Swagger/OpenAPI 配置
- [ ] 设置 Docker 开发环境 (mcr.microsoft.com/dotnet/sdk:8.0)
- [ ] 配置 EF Core + PostgreSQL
  - [ ] 安装 Npgsql.EntityFrameworkCore.PostgreSQL
  - [ ] 配置 DbContext
  - [ ] 配置连接字符串
- [ ] 配置依赖注入容器
- [ ] 设置 Serilog 结构化日志
- [ ] 配置代码质量工具 (EditorConfig, StyleCop)

**前端任务:**
- [ ] 初始化 React + Vite 项目
- [ ] 配置 TypeScript
- [ ] 配置 TailwindCSS
- [ ] 设置 ESLint + Prettier
- [ ] 配置 React Router
- [ ] 设置 Zustand 状态管理
- [ ] 配置 React Query

**基础设施:**
- [x] 创建 Docker Compose 开发环境
- [x] 配置本地 PostgreSQL
- [x] 配置本地 Redis

#### Week 2: 认证模块 (.NET Identity)

**后端任务:**
- [ ] 配置 ASP.NET Core Identity
  - [ ] 安装 Microsoft.AspNetCore.Identity.EntityFrameworkCore
  - [ ] 配置 IdentityDbContext
  - [ ] 配置 IdentityOptions (密码策略、锁定等)
- [ ] 实现 JWT 认证
  - [ ] 配置 JWT Bearer 认证
  - [ ] 实现 Token 生成服务
  - [ ] 实现 Token 刷新机制
- [ ] 实现认证 API (Minimal API 或 Controllers)
  - [ ] POST /auth/register
  - [ ] POST /auth/login
  - [ ] POST /auth/refresh
  - [ ] POST /auth/logout
- [ ] 配置授权策略
- [ ] 创建 EF Core 迁移

**前端任务:**
- [ ] 创建登录页面
- [ ] 创建注册页面
- [ ] 实现认证 API 客户端
- [ ] 实现认证状态管理
- [ ] 创建受保护路由组件
- [ ] 实现 Token 自动刷新

**测试:**
- [ ] 单元测试: 认证服务 (xUnit + Moq)
- [ ] 单元测试: JWT 工具
- [ ] 集成测试: 认证流程 (WebApplicationFactory)

---

### Phase 2: 核心功能 (Week 3-4)

#### Week 3: OCR 集成与文件处理

**后端任务:**
- [ ] 设计发票模型
- [ ] 实现 Azure Blob Storage 客户端
- [ ] 实现文件上传 API
- [ ] 集成 Invoice Master OCR API
  - [ ] 创建 OCR 客户端
  - [ ] 实现异步 OCR 调用
  - [ ] 解析 OCR 响应
- [ ] 实现文件验证 (类型、大小)
- [ ] 实现文件去重 (hash 检查)
- [ ] 创建发票处理队列

**前端任务:**
- [ ] 创建文件上传组件
  - [ ] 拖放上传
  - [ ] 进度显示
  - [ ] 文件预览
- [ ] 实现上传 API 集成
- [ ] 创建处理状态显示
- [ ] 实现发票列表页面

**测试:**
- [ ] 单元测试: 文件服务
- [ ] 单元测试: OCR 客户端
- [ ] 集成测试: 上传流程

#### Week 4: 供应商匹配

**后端任务:**
- [ ] 设计供应商缓存模型
- [ ] 实现供应商匹配算法
  - [ ] 组织号精确匹配
  - [ ] 名称模糊匹配 (fuzzywuzzy)
- [ ] 实现供应商缓存服务
- [ ] 创建供应商 API 端点
  - [ ] 获取供应商列表
  - [ ] 刷新缓存
- [ ] 实现匹配结果存储

**前端任务:**
- [ ] 创建供应商匹配组件
  - [ ] 匹配结果显示
  - [ ] 置信度指示器
  - [ ] 手动选择供应商
- [ ] 实现供应商 API 集成
- [ ] 创建供应商选择弹窗

**测试:**
- [ ] 单元测试: 供应商匹配算法
- [ ] 单元测试: 缓存服务
- [ ] 集成测试: 匹配流程

---

### Phase 3: 会计系统集成 (Week 5-6)

#### Week 5: 会计系统抽象层实现

**后端任务:**
- [x] 创建抽象基类 `AccountingSystem`
- [x] 实现通用数据模型
  - [x] `AccountingSupplier`
  - [x] `AccountingVoucher`
  - [x] `AccountingAccount`
  - [x] `CompanyInfo`
- [x] 实现 Factory 模式
  - [x] `AccountingSystemFactory`
  - [x] Provider 注册机制
- [x] 创建 Fortnox Provider
  - [x] OAuth2 认证实现
  - [x] Token 刷新机制
  - [x] 供应商 API 实现
  - [x] 凭证 API 实现
  - [x] 文件上传实现
- [ ] 抽象层单元测试

**前端任务:**
- [ ] 创建会计系统选择组件
- [ ] 实现多会计系统连接页面
- [ ] 连接状态管理

**测试:**
- [ ] 单元测试: Fortnox Provider
- [ ] 单元测试: Factory 模式
- [ ] Mock 测试: 外部 API

#### Week 6: 凭证生成与导入

**后端任务:**
- [ ] 实现会计科目选择逻辑
- [ ] 实现 VAT 计算
- [ ] 实现凭证生成服务
  - [ ] 构建凭证行
  - [ ] 科目分配
- [ ] 实现凭证创建 API (通过抽象层)
- [ ] 实现文件附件上传 (通过抽象层)
- [ ] 实现导入状态跟踪
- [ ] 错误处理和重试机制

**前端任务:**
- [ ] 创建凭证预览组件
  - [ ] 凭证行显示
  - [ ] 科目选择
  - [ ] 金额编辑
- [ ] 创建审核页面
  - [ ] OCR 结果编辑
  - [ ] 供应商确认
  - [ ] 凭证预览
- [ ] 实现导入 API 集成

**测试:**
- [ ] 单元测试: 凭证生成
- [ ] 单元测试: VAT 计算
- [ ] 集成测试: 导入流程

---

### Phase 4: UI 开发 (Week 7-8)

#### Week 7: 核心页面开发

**前端任务:**
- [ ] 仪表盘页面
  - [ ] 统计卡片
  - [ ] 最近发票列表
  - [ ] 快速上传入口
  - [ ] 会计系统连接状态
- [ ] 发票详情页面
  - [ ] PDF 预览
  - [ ] 提取数据显示
  - [ ] 操作按钮
- [ ] 历史记录页面
  - [ ] 筛选和搜索
  - [ ] 分页
  - [ ] 状态标签
- [ ] 响应式布局优化

**设计:**
- [ ] 完善 UI 组件库
- [ ] 统一颜色和字体
- [ ] 动画和过渡效果

#### Week 8: 用户体验优化

**前端任务:**
- [ ] 错误处理
  - [ ] 错误提示组件
  - [ ] 重试机制
- [ ] 加载状态
  - [ ] 骨架屏
  - [ ] 加载动画
- [ ] 空状态设计
- [ ] 确认对话框
- [ ] Toast 通知系统
- [ ] 键盘快捷键

**后端任务:**
- [ ] 优化 API 响应时间
- [ ] 实现请求缓存
- [ ] 添加 API 文档 (Swagger)

---

### Phase 5: 测试优化 (Week 9-10)

#### Week 9: 测试覆盖

**后端测试:**
- [ ] 单元测试覆盖 > 80%
  - [ ] 服务层测试
  - [ ] 抽象层测试
  - [ ] Provider 测试
  - [ ] 工具函数测试
- [ ] 集成测试
  - [ ] API 端点测试
  - [ ] 数据库操作测试
- [ ] Mock 外部服务
  - [ ] Fortnox API Mock
  - [ ] OCR API Mock

**前端测试:**
- [ ] 组件单元测试 (Vitest)
- [ ] 集成测试 (React Testing Library)
- [ ] E2E 测试 (Playwright)
  - [ ] 登录流程
  - [ ] 上传流程
  - [ ] 导入流程

#### Week 10: 性能优化

**后端优化:**
- [ ] 数据库查询优化
  - [ ] 添加必要索引
  - [ ] 查询优化
- [ ] 缓存策略
  - [ ] Redis 缓存
  - [ ] 响应缓存
- [ ] 连接池优化
- [ ] 异步任务优化

**前端优化:**
- [ ] 代码分割
- [ ] 懒加载
- [ ] 图片优化
- [ ] 缓存策略

**安全审计:**
- [ ] 依赖漏洞扫描
- [ ] 代码安全审查
- [ ] OWASP 检查

---

### Phase 6: 上线准备 (Week 11-12)

#### Week 11: 文档与审核

**文档:**
- [ ] API 文档完善
- [ ] 用户手册
- [ ] 部署文档
- [ ] 运维手册
- [ ] 代码注释
- [ ] Provider 开发指南 (SDK 文档)

**Fortnox 审核:**
- [ ] 创建 Fortnox 开发者账号
- [ ] 提交应用审核
- [ ] 准备审核材料
  - [ ] 应用描述
  - [ ] 隐私政策
  - [ ] 使用条款
- [ ] 处理审核反馈

**监控:**
- [ ] 配置 Azure Monitor
- [ ] 设置告警规则
- [ ] 配置日志聚合

#### Week 12: 部署上线

**基础设施:**
- [ ] 生产环境部署
  - [ ] Azure Container Apps
  - [ ] PostgreSQL
  - [ ] Redis
  - [ ] Blob Storage
- [ ] 域名配置
- [ ] SSL 证书
- [ ] CDN 配置

**上线检查:**
- [ ] 功能测试
- [ ] 性能测试
- [ ] 安全测试
- [ ] 备份策略验证
- [ ] 回滚计划

**发布:**
- [ ] 软发布 (Beta)
- [ ] 收集反馈
- [ ] 正式发布

---

### Phase 7: 扩展准备 (Week 13-14)

#### Week 13: Provider SDK 开发

**后端任务:**
- [ ] 创建 Provider 开发模板
- [ ] 实现基础 Provider 类
- [ ] 创建 Provider 脚手架工具
- [ ] 编写 Provider 测试模板
- [ ] 实现 Provider 验证工具

**文档:**
- [ ] Provider 开发指南
- [ ] API 差异对比文档
- [ ] 最佳实践指南
- [ ] 故障排查指南

#### Week 14: 示例与工具

**后端任务:**
- [ ] 创建 Mock Provider 示例
- [ ] 实现 Provider 调试工具
- [ ] 创建 Provider 性能测试工具
- [ ] 实现 Provider 文档生成器

**文档:**
- [ ] 架构决策记录 (ADR)
- [ ] 技术规范文档
- [ ] 维护手册

---

## 3. 技术债务管理

| 优先级 | 任务 | 计划解决时间 |
|--------|------|-------------|
| P0 | 多会计系统架构重构 | Pre-Phase |
| P1 | 添加数据库连接池监控 | Week 9 |
| P1 | 实现分布式锁 (Redis) | Week 10 |
| P2 | 添加 API 版本控制 | Week 11 |
| P2 | 实现事件溯源 | Phase 2 |
| P3 | 多语言支持 | Phase 2 |
| P3 | 添加第二个会计系统 (Visma) | Phase 2 |

---

## 4. 风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 架构重构延期 | 高 | 优先完成核心抽象层，细节后续迭代 |
| 不同会计系统 API 差异大 | 中 | 抽象层设计预留扩展点，文档化差异 |
| Fortnox API 限流 | 高 | 实现缓存、队列、退避策略 |
| OCR 准确率不足 | 高 | 用户审核流程、置信度阈值 |
| Token 过期处理 | 中 | 自动刷新、用户提示重连 |
| 供应商匹配失败 | 中 | 模糊匹配、手动选择 |
| 文件存储成本 | 中 | 压缩、生命周期策略 |

---

## 5. 团队分工

| 角色 | 职责 | 主要任务 |
|------|------|----------|
| **架构师** | 系统设计 | 抽象层设计、架构评审、技术决策 |
| **后端开发** | API 开发 | 认证、业务逻辑、抽象层、Provider |
| **前端开发** | UI 开发 | 组件、页面、状态管理 |
| **DevOps** | 基础设施 | 部署、监控、CI/CD |
| **QA** | 测试 | 测试用例、自动化测试 |
| **技术写作** | 文档 | Provider SDK 文档、开发指南 |

---

## 6. 代码审查清单

- [ ] 代码符合项目规范
- [ ] 抽象层接口设计合理
- [ ] Provider 实现符合接口规范
- [ ] 有适当的单元测试
- [ ] 没有安全漏洞
- [ ] 性能考虑
- [ ] 文档已更新
- [ ] 数据库迁移已包含 (如需要)
- [ ] Provider 注册正确

---

## 7. 发布检查清单

- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 架构文档已更新
- [ ] Provider SDK 文档完成
- [ ] 数据库迁移已测试
- [ ] 环境变量已配置
- [ ] 监控和告警已配置
- [ ] 回滚计划已准备
- [ ] 团队成员已通知

---

**文档历史:**

| 版本 | 日期 | 作者 | 变更 |
|------|------|------|------|
| 3.0 | 2026-02-03 | Claude Code | 重构为 .NET 8 + 轻量级 DDD + 审计支持 |
| 2.0 | 2026-02-03 | Claude Code | 添加多会计系统架构重构计划 |
| 1.0 | 2026-02-03 | Claude Code | 初始版本 |