# Invoice Master - 项目目录结构

**版本**: v3.0  
**技术栈**: .NET 8 + React 18

```
invoice-master/
│
├── README.md                          # 项目说明
├── ARCHITECTURE.md                    # 架构文档
├── API_DESIGN.md                      # API 设计文档
├── DATABASE_SCHEMA.md                 # 数据库设计
├── DEVELOPMENT_PLAN.md                # 开发计划
├── DEPLOYMENT_GUIDE.md                # 部署指南
├── .gitignore                         # Git 忽略配置
├── docker-compose.yml                 # 本地开发环境
├── docker-compose.prod.yml            # 生产环境配置
│
├── backend/                           # .NET 后端
│   ├── InvoiceMaster.sln              # Solution 文件
│   ├── Directory.Build.props          # 全局 MSBuild 属性
│   ├── global.json                    # .NET SDK 版本
│   ├── Dockerfile                     # 容器镜像
│   ├── docker-compose.yml             # 本地开发编排
│   │
│   ├── src/                           # 源代码
│   │   ├── InvoiceMaster.API/         # Web API 入口
│   │   │   ├── InvoiceMaster.API.csproj
│   │   │   ├── Program.cs
│   │   │   ├── appsettings.json
│   │   │   ├── appsettings.Development.json
│   │   │   ├── Controllers/           # API 控制器
│   │   │   │   ├── AuthController.cs
│   │   │   │   ├── InvoicesController.cs
│   │   │   │   └── AccountingController.cs
│   │   │   ├── Middleware/            # 中间件
│   │   │   │   ├── ExceptionHandlingMiddleware.cs
│   │   │   │   └── RequestLoggingMiddleware.cs
│   │   │   └── Properties/
│   │   │       └── launchSettings.json
│   │   │
│   │   ├── InvoiceMaster.Core/        # 领域层
│   │   │   ├── InvoiceMaster.Core.csproj
│   │   │   ├── Entities/              # 领域实体
│   │   │   │   ├── Invoice.cs
│   │   │   │   ├── AccountingConnection.cs
│   │   │   │   ├── User.cs
│   │   │   │   └── SupplierCache.cs
│   │   │   ├── Events/                # 领域事件
│   │   │   │   ├── DomainEvent.cs
│   │   │   │   ├── InvoiceImportedEvent.cs
│   │   │   │   └── ConnectionCreatedEvent.cs
│   │   │   ├── Interfaces/            # 领域接口
│   │   │   │   ├── IRepository.cs
│   │   │   │   ├── IUnitOfWork.cs
│   │   │   │   └── IDomainEventDispatcher.cs
│   │   │   └── ValueObjects/          # 值对象
│   │   │       ├── Money.cs
│   │   │       └── OrganizationNumber.cs
│   │   │
│   │   ├── InvoiceMaster.Application/ # 应用层
│   │   │   ├── InvoiceMaster.Application.csproj
│   │   │   ├── Commands/              # CQRS 命令
│   │   │   │   ├── ImportInvoice/
│   │   │   │   │   ├── ImportInvoiceCommand.cs
│   │   │   │   │   └── ImportInvoiceCommandHandler.cs
│   │   │   │   └── CreateConnection/
│   │   │   │       ├── CreateConnectionCommand.cs
│   │   │   │       └── CreateConnectionCommandHandler.cs
│   │   │   ├── Queries/               # CQRS 查询
│   │   │   │   ├── GetInvoice/
│   │   │   │   │   ├── GetInvoiceQuery.cs
│   │   │   │   │   └── GetInvoiceQueryHandler.cs
│   │   │   │   └── ListInvoices/
│   │   │   │       ├── ListInvoicesQuery.cs
│   │   │   │       └── ListInvoicesQueryHandler.cs
│   │   │   ├── DTOs/                  # 数据传输对象
│   │   │   │   ├── InvoiceDto.cs
│   │   │   │   └── ConnectionDto.cs
│   │   │   ├── Mappings/              # AutoMapper 配置
│   │   │   │   └── MappingProfile.cs
│   │   │   └── Behaviors/             # MediatR 行为
│   │   │       ├── ValidationBehavior.cs
│   │   │       └── LoggingBehavior.cs
│   │   │
│   │   ├── InvoiceMaster.Infrastructure/# 基础设施层
│   │   │   ├── InvoiceMaster.Infrastructure.csproj
│   │   │   ├── Data/                  # EF Core
│   │   │   │   ├── ApplicationDbContext.cs
│   │   │   │   ├── Configurations/    # 实体配置
│   │   │   │   │   ├── InvoiceConfiguration.cs
│   │   │   │   │   └── ConnectionConfiguration.cs
│   │   │   │   ├── Migrations/        # 迁移文件
│   │   │   │   └── Interceptors/      # EF 拦截器
│   │   │   │       └── DispatchDomainEventsInterceptor.cs
│   │   │   ├── Repositories/          # 仓储实现
│   │   │   │   ├── InvoiceRepository.cs
│   │   │   │   └── ConnectionRepository.cs
│   │   │   ├── Services/              # 外部服务
│   │   │   │   ├── BlobStorageService.cs
│   │   │   │   └── OCRService.cs
│   │   │   └── Identity/              # Identity 配置
│   │   │       └── ApplicationUser.cs
│   │   │
│   │   └── InvoiceMaster.Integrations/# 集成层
│   │       ├── InvoiceMaster.Integrations.csproj
│   │       ├── Accounting/            # 会计系统集成
│   │       │   ├── IAccountingSystem.cs
│   │       │   ├── IAccountingSystemFactory.cs
│   │       │   ├── AccountingSystemFactory.cs
│   │       │   ├── Models/            # 通用模型
│   │       │   │   ├── Supplier.cs
│   │       │   │   ├── Voucher.cs
│   │       │   │   └── Account.cs
│   │       │   └── Providers/         # Provider 实现
│   │       │       ├── Fortnox/
│   │       │       │   ├── FortnoxProvider.cs
│   │       │       │   ├── FortnoxAuthClient.cs
│   │       │       │   └── FortnoxApiClient.cs
│   │       │       └── Visma/         # Future
│   │       │           └── VismaProvider.cs
│   │       └── Extensions/            # DI 扩展
│   │           └── AccountingServiceExtensions.cs
│   │
│   └── tests/                         # 测试项目
│       ├── InvoiceMaster.UnitTests/
│       │   ├── InvoiceMaster.UnitTests.csproj
│       │   ├── Commands/
│       │   ├── Queries/
│       │   └── Domain/
│       ├── InvoiceMaster.IntegrationTests/
│       │   ├── InvoiceMaster.IntegrationTests.csproj
│       │   ├── Factories/
│       │   │   └── CustomWebApplicationFactory.cs
│       │   └── Controllers/
│       └── InvoiceMaster.ArchitectureTests/
│           └── InvoiceMaster.ArchitectureTests.csproj
│
├── frontend/                          # React 前端
│   ├── package.json                   # 依赖管理
│   ├── tsconfig.json                  # TypeScript 配置
│   ├── vite.config.ts                 # Vite 配置
│   ├── tailwind.config.js             # TailwindCSS 配置
│   ├── index.html                     # 入口 HTML
│   ├── .env.example                   # 环境变量示例
│   │
│   ├── src/
│   │   ├── main.tsx                   # 应用入口
│   │   ├── App.tsx                    # 根组件
│   │   ├── index.css                  # 全局样式
│   │   │
│   │   ├── api/                       # API 客户端
│   │   │   ├── client.ts              # Axios 实例
│   │   │   ├── auth.ts                # 认证相关 API
│   │   │   ├── invoices.ts            # 发票相关 API
│   │   │   ├── suppliers.ts           # 供应商相关 API
│   │   │   ├── accounting.ts          # 会计系统集成 API (多系统)
│   │   │   └── providers/             # Provider 特定 API
│   │   │       ├── fortnox.ts         # Fortnox API
│   │   │       ├── visma.ts           # Visma API (future)
│   │   │       └── index.ts           # Provider 导出
│   │   │
│   │   ├── components/                # 组件
│   │   │   ├── common/                # 通用组件
│   │   │   │   ├── Button.tsx
│   │   │   │   ├── Input.tsx
│   │   │   │   ├── Card.tsx
│   │   │   │   ├── Modal.tsx
│   │   │   │   ├── LoadingSpinner.tsx
│   │   │   │   └── ErrorBoundary.tsx
│   │   │   │
│   │   │   ├── layout/                # 布局组件
│   │   │   │   ├── Layout.tsx         # 主布局
│   │   │   │   ├── Header.tsx         # 顶部导航
│   │   │   │   ├── Sidebar.tsx        # 侧边栏
│   │   │   │   └── Footer.tsx         # 底部
│   │   │   │
│   │   │   ├── auth/                  # 认证组件
│   │   │   │   ├── AccountingProviderSelect.tsx  # 会计系统选择
│   │   │   │   ├── ProviderConnect.tsx           # 通用连接组件
│   │   │   │   ├── LoginForm.tsx
│   │   │   │   └── ProtectedRoute.tsx
│   │   │   │
│   │   │   ├── upload/                # 上传组件
│   │   │   │   ├── FileUpload.tsx     # 文件上传区域
│   │   │   │   ├── UploadProgress.tsx # 上传进度
│   │   │   │   ├── DragDropZone.tsx   # 拖放区域
│   │   │   │   └── ProviderSelector.tsx # 目标会计系统选择
│   │   │   │
│   │   │   ├── invoice/               # 发票组件
│   │   │   │   ├── InvoiceCard.tsx    # 发票卡片
│   │   │   │   ├── InvoiceList.tsx    # 发票列表
│   │   │   │   ├── InvoicePreview.tsx # 发票预览
│   │   │   │   ├── InvoiceForm.tsx    # 发票编辑表单
│   │   │   │   └── InvoiceStatus.tsx  # 状态显示
│   │   │   │
│   │   │   ├── supplier/              # 供应商组件
│   │   │   │   ├── SupplierMatch.tsx  # 供应商匹配
│   │   │   │   ├── SupplierSelect.tsx # 供应商选择
│   │   │   │   └── SupplierCreate.tsx # 创建供应商
│   │   │   │
│   │   │   └── voucher/               # 凭证组件
│   │   │       ├── VoucherPreview.tsx # 凭证预览
│   │   │       ├── AccountSelect.tsx  # 科目选择
│   │   │       └── VoucherRows.tsx    # 凭证行
│   │   │
│   │   ├── hooks/                     # 自定义 Hooks
│   │   │   ├── useAuth.ts             # 认证 Hook
│   │   │   ├── useInvoices.ts         # 发票数据 Hook
│   │   │   ├── useSuppliers.ts        # 供应商数据 Hook
│   │   │   ├── useUpload.ts           # 上传 Hook
│   │   │   ├── useAccounting.ts       # 会计系统连接 Hook (通用)
│   │   │   ├── useProviders.ts        # Provider 列表 Hook
│   │   │   └── useToast.ts            # 通知 Hook
│   │   │
│   │   ├── stores/                    # 状态管理 (Zustand)
│   │   │   ├── authStore.ts           # 认证状态
│   │   │   ├── invoiceStore.ts        # 发票状态
│   │   │   ├── accountingStore.ts     # 会计系统连接状态
│   │   │   └── uiStore.ts             # UI 状态
│   │   │
│   │   ├── types/                     # TypeScript 类型
│   │   │   ├── auth.ts
│   │   │   ├── invoice.ts
│   │   │   ├── supplier.ts
│   │   │   ├── voucher.ts
│   │   │   ├── accounting.ts          # 会计系统类型
│   │   │   └── api.ts
│   │   │
│   │   ├── utils/                     # 工具函数
│   │   │   ├── formatters.ts          # 格式化
│   │   │   ├── validators.ts          # 验证
│   │   │   └── constants.ts           # 常量
│   │   │
│   │   └── pages/                     # 页面组件
│   │       ├── Home.tsx               # 首页/仪表盘
│   │       ├── Login.tsx              # 登录页
│   │       ├── Connect.tsx            # 会计系统连接页
│   │       ├── Upload.tsx             # 上传页
│   │       ├── Review.tsx             # 审核页
│   │       ├── History.tsx            # 历史记录
│   │       ├── Settings.tsx           # 设置页
│   │       └── NotFound.tsx           # 404
│   │
│   └── public/                        # 静态资源
│       ├── logo.svg
│       └── favicon.ico

│
├── infrastructure/                    # 基础设施
│   ├── terraform/                     # Terraform 配置
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── backend.tf
│   │   └── modules/                   # 模块
│   │       ├── database/
│   │       ├── cache/
│   │       ├── storage/
│   │       └── container_apps/
│   │
│   ├── azure/                         # Azure 特定配置
│   │   ├── bicep/                     # Bicep 模板
│   │   └── arm/                       # ARM 模板
│   │
│   └── scripts/                       # 部署脚本
│       ├── deploy.sh
│       ├── setup-local.sh
│       └── migrate.sh
│
├── docs/                              # 文档
│   ├── development/                   # 开发文档
│   ├── api/                           # API 文档
│   ├── deployment/                    # 部署文档
│   └── providers/                     # Provider 开发文档 (新增)
│       ├── README.md                  # Provider 开发指南
│       ├── interface.md               # 接口规范
│       └── examples/                  # 示例代码
│
└── scripts/                           # 实用脚本
    ├── setup.sh                       # 项目初始化
    ├── dev-start.sh                   # 启动开发环境
    ├── test.sh                        # 运行测试
    ├── lint.sh                        # 代码检查
    └── add-provider.sh                # 添加新 Provider 脚手架 (新增)
```

---

## 目录说明

### Frontend

- **api/**: API 客户端封装
  - `accounting.ts`: 通用会计系统 API
  - `providers/`: Provider 特定 API 实现

- **components/**: 按功能分组的 React 组件
  - `auth/AccountingProviderSelect.tsx`: 会计系统选择组件
  - `auth/ProviderConnect.tsx`: 通用连接组件
  - `upload/ProviderSelector.tsx`: 上传时选择目标会计系统

- **hooks/**: 自定义 React Hooks
  - `useAccounting.ts`: 通用会计系统连接 Hook
  - `useProviders.ts`: 获取支持的 Provider 列表

- **stores/**: Zustand 状态管理
  - `accountingStore.ts`: 会计系统连接状态

### Backend (.NET)

- **InvoiceMaster.API/**: Web API 入口
  - `Controllers/`: API 控制器
  - `Middleware/`: 中间件
  - `appsettings.json`: 配置

- **InvoiceMaster.Core/**: 领域层
  - `Entities/`: 领域实体 (Invoice, AccountingConnection)
  - `Events/`: 领域事件 (用于审计)
  - `Interfaces/`: 领域接口
  - `ValueObjects/`: 值对象

- **InvoiceMaster.Application/**: 应用层 (CQRS)
  - `Commands/`: 命令处理器 (MediatR)
  - `Queries/`: 查询处理器
  - `DTOs/`: 数据传输对象
  - `Mappings/`: AutoMapper 配置

- **InvoiceMaster.Infrastructure/**: 基础设施层
  - `Data/`: EF Core DbContext, 配置, 迁移
  - `Repositories/`: 仓储实现
  - `Services/`: 外部服务实现
  - `Identity/`: ASP.NET Core Identity

- **InvoiceMaster.Integrations/**: 集成层
  - `Accounting/`: 会计系统集成
    - `IAccountingSystem.cs`: 接口
    - `AccountingSystemFactory.cs`: 工厂
    - `Providers/`: Provider 实现
      - `Fortnox/`: Fortnox Provider
      - `Visma/`: Visma Provider (future)

### Infrastructure

- **terraform/**: 基础设施即代码
- **scripts/**: 部署和运维脚本

### Docs

- **providers/**: Provider 开发文档 (新增)
  - 如何添加新的会计系统 Provider
  - 接口规范
  - 示例代码

---

## 命名规范

### 文件命名

- **React 组件**: PascalCase (e.g., `InvoiceCard.tsx`)
- **Hooks**: camelCase with `use` prefix (e.g., `useAccounting.ts`)
- **工具函数**: camelCase (e.g., `formatters.ts`)
- **C# 类**: PascalCase (e.g., `InvoiceService.cs`)
- **C# 接口**: PascalCase with `I` prefix (e.g., `IAccountingSystem.cs`)
- **测试文件**: `{ClassName}Tests.cs` (e.g., `InvoiceServiceTests.cs`)
- **Provider 实现**: `{ProviderName}Provider.cs` (e.g., `FortnoxProvider.cs`)

### 代码规范

- **TypeScript**: 严格模式，显式返回类型
- **C#**: C# 12 特性, 使用 `record` 和 `required`, StyleCop 规则
- **CSS**: TailwindCSS 工具类优先
- **Git**: Conventional commits

---

## 添加新 Provider 的目录变更

当添加新的会计系统 Provider 时，需要创建/修改以下文件：

### Backend

```
backend/src/InvoiceMaster.Integrations/Accounting/Providers/
├── {ProviderName}/
│   ├── {ProviderName}Provider.cs      # 新 Provider 实现
│   ├── {ProviderName}AuthClient.cs    # OAuth 客户端
│   └── {ProviderName}ApiClient.cs     # API 客户端

backend/src/InvoiceMaster.API/
├── appsettings.json                    # 添加 Provider 配置
└── Extensions/
    └── AccountingServiceExtensions.cs  # 注册 Provider
```

### Frontend

```
frontend/src/api/providers/
├── index.ts                 # 导出 Provider API
├── {provider}.ts            # 新 Provider API 客户端 (可选)

frontend/src/types/accounting.ts  # 添加 Provider 类型
```

### Docs

```
docs/providers/
├── {provider}.md            # 新 Provider 文档
└── examples/
    └── {provider}_example.py
```

---

**文档历史:**

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