05ea67144f
- Add .NET 8 backend with Clean Architecture - Add React + Vite + TypeScript frontend - Implement authentication with JWT - Implement Azure Blob Storage client - Implement OCR integration - Implement supplier matching service - Implement voucher generation - Implement Fortnox provider - Add unit and integration tests - Add Docker Compose configuration
497 lines
12 KiB
Markdown
497 lines
12 KiB
Markdown
# 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 | 初始版本 |
|