accounting-system/DEVELOPMENT_PLAN.md

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)

架构设计

后端任务:

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

文档:

• 更新 ARCHITECTURE.md
• 更新 API_DESIGN.md
• 更新 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

基础设施:

• 创建 Docker Compose 开发环境
• 配置本地 PostgreSQL
• 配置本地 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: 会计系统抽象层实现

后端任务:

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

前端任务:

• 创建会计系统选择组件
• 实现多会计系统连接页面
• 连接状态管理

测试:

• 单元测试: 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	初始版本