Skill: allanseven/open-leqi-assistant (version 1.0.0)

--- name: open-leqi-assistant description: | 乐企(open-leqi)项目分析与代码定位助手技能。当用户询问关于乐企发票系统、勾选能力、抵扣功能、用票接口等问题时触发。本技能提供项目架构理解、代码快速定位、业务流程分析和问题诊断建议。 --- # 乐企(open-leqi)项目分析助手 ## 技能概述 本技能基于百望乐企数字开放平台项目，专注于帮助开发者快速理解项目架构、定位代码、解答业务问题。 ## 项目结构 ``` D:/leqi/open-leqi/ ├── open-leqi-api/ # API模块 - Feign客户端定义 │ └── src/main/java/com/baiwang/platform/openleqi/ │ ├── api/ # 29个Feign Client接口 │ ├── model/ # 数据模型(163个) │ └── farm/ # 农业相关API │ ├── open-leqi-service/ # 服务模块 - 核心业务实现 │ └── src/main/java/com/baiwang/platform/openleqi/ │ ├── web/ # 60个Controller控制器 │ ├── service/impl/ # 122个Service实现 │ ├── dao/ # 数据访问层(109个) │ ├── common/ # 公共工具(508个) │ ├── config/ # 配置类 │ ├── job/ # 定时任务(19个) │ └── intergration/ # 外部集成(48个) │ └── startup/ # 启动模块 ``` ## 核心业务模块 ### 发票管理 | 模块 | Controller | Service | Client | 说明 | |------|-----------|---------|--------|------| | 发票主表 | `LqInvoiceMainController` | `LqInvoiceMainService` | `LqInvoiceMainClient` | 全电发票核心数据 | | 发票明细 | `LqInvoiceDetailController` | `LqInvoiceDetailService` | `LqInvoiceDetailClient` | 发票商品明细 | | 发票抵扣 | `LqInvoiceDeductController` | `LqInvoiceDeductService` | `LqInvoiceDeductClient` | 增值税抵扣勾选 | | 发票作废 | - | `LqWarrantPoolService` | `LqWarrantSyncClient` | 发票作废管理 | ### 勾选能力 | 模块 | Controller | Service | 说明 | |------|-----------|---------|------| | 抵扣勾选 | `LqWithholdDeductController` | `LqWithholdDeductService` | 勾选用于抵扣 | | 退税勾选 | `LqWarrantDeductController` | `LqWarrantDeductService` | 勾选用于退税 | | 不抵扣勾选 | `LqNotdeductInitTaskController` | `LqNotdeductInitTaskService` | 不抵扣处理 | | 农产品抵扣 | [REDACTED_SECRET] | [REDACTED_SECRET] | 农产品加计扣除 | ### 用票能力 | 模块 | Controller | Service | 说明 | |------|-----------|---------|------| | 实时用票 | `LqSyncController` | `LqSyncService` | 发票开具 | | 下载发票 | `LqDownloadTaskController` | `LqDownloadTaskService` | 发票下载 | | 发票池 | `LqInvoicePoolTaskController` | `LqInvoicePoolTaskService` | 发票池管理 | ## 代码定位规则 ### 根据功能查询Controller ```java // 发票相关: 搜索 "LqInvoice*Controller" com.baiwang.platform.openleqi.web.LqInvoiceMainController com.baiwang.platform.openleqi.web.LqInvoiceDetailController com.baiwang.platform.openleqi.web.LqInvoiceDeductController // 勾选相关: 搜索 "Lq*DeductController" 或 "Lq*WarrantController" com.baiwang.platform.openleqi.web.LqWithholdDeductController com.baiwang.platform.openleqi.web.LqWarrantDeductController ``` ### 根据功能查询Service ```java // 服务接口: com.baiwang.platform.openleqi.service.Lq*Service // 服务实现: com.baiwang.platform.openleqi.service.impl.Lq*ServiceImpl ``` ### 根据功能查询DAO ```java // Entity: com.baiwang.platform.openleqi.dao.entity.Lq* // Mapper: com.baiwang.platform.openleqi.dao.mapper.Lq*Mapper ``` ## 常用业务场景 ### 场景1: 查询发票信息 1. Controller: `LqInvoiceMainController` → [REDACTED_SECRET] 2. Service: `LqInvoiceMainService` 3. DAO: `LqInvoiceMainMapper` ### 场景2: 抵扣勾选处理 1. Controller: `LqWithholdDeductController` → 抵扣接口 2. Service: `LqWithholdDeductService` 3. 核心方法: `deduct()` / `undoDeduct()` ### 场景3: 发票开具 1. Controller: `LqSyncController` 2. Service: `LqSyncService.syncInvoice()` 3. 调用链: OFS系统 → 乐企 → 返回结果 ## 项目规范 ### Spring Boot规范 - 使用`@RequiredArgsConstructor`代替构造函数注入 - 使用Lombok简化代码 - 分层清晰: Controller → Service → DAO ### 命名规范 - Controller: `Lq{业务}Controller` (例: `LqInvoiceMainController`) - Service: `Lq{业务}Service` (例: `LqInvoiceMainService`) - Entity: `Lq{业务}` (例: `LqInvoiceMain`) - Mapper: `Lq{业务}Mapper` (例: `LqInvoiceMainMapper`) ### API规范 - 使用Swagger `@Api` `@ApiOperation` 注解 - 使用`BWJsonResultDto`统一返回格式 - 使用`@Validated`进行参数校验 ## 外部依赖 - **百望BOP SDK**: `com.baiwang.bop:baiwang-bopsdk:3.4.822` - **父工程**: `com.baiwang.basictools:bw-spring-boot-starter-parent-security:2.7.196` - **数据库**: MyBatis-Plus ## 快速查询 当用户提问时，按以下顺序响应: 1. **理解问题**: 识别用户询问的业务场景 2. **定位代码**: 根据上表找到对应的Controller/Service/DAO 3. **给出路径**: 提供完整的文件路径 4. **分析问题**: 简要说明代码逻辑 5. **建议方案**: 提供问题解决思路 ## 参考文档 - `references/project-architecture.md` - 详细项目架构说明 - `references/business-flows.md` - 业务流程图说明 - `references/api-guide.md` - API接口文档索引

path: assets/architecture-diagrams.md
content: # 乐企系统架构图

## 系统架构总览

```mermaid
graph TB
    subgraph 外部系统
        OFS[OFS系统]
        EPS[电票平台]
        ETS[电子税务局]
        DW[数据仓库]
    end

    subgraph open-leqi项目
        subgraph open-leqi-api
            API[API模块<br/>29个Feign Client]
        end
        
        subgraph open-leqi-service
            WEB[Web层<br/>60个Controller]
            SERVICE[Service层<br/>225个Service]
            DAO[DAO层<br/>109个Mapper]
        end
    end

    subgraph 数据库
        DB[(MySQL<br/>乐企数据库)]
    end

    OFS -->|发票开具/同步| WEB
    EPS -->|发票数据| WEB
    ETS -->|勾选操作| WEB
    WEB --> SERVICE
    SERVICE --> DAO
    DAO --> DB
    SERVICE -->|统计结果| DW
```

## 发票开具流程

```mermaid
sequenceDiagram
    participant 直连单位
    participant Controller as LqSyncController
    participant Service as LqSyncService
    participant OFS as OFS系统
    participant Pool as LqInvoicePoolTaskService
    participant Main as LqInvoiceMainService
    participant DB as 数据库

    直连单位->>Controller: 发票开具请求
    Controller->>Service: syncInvoice()
    Service->>OFS: 调用OFS接口
    OFS-->>Service: 返回结果
    Service->>Pool: 创建发票池任务
    Service->>Main: 保存发票主表
    Main->>DB: INSERT lq_invoice_main
```

## 抵扣勾选流程

```mermaid
sequenceDiagram
    participant 纳税人
    participant Controller as LqWithholdDeductController
    participant Service as LqWithholdDeductService
    participant Main as LqInvoiceMainService
    participant Stat as LqStatResultService
    participant DB as 数据库

    纳税人->>Controller: 抵扣勾选请求
    Controller->>Service: deduct()
    Service->>Main: 更新发票状态
    Main->>DB: UPDATE lq_invoice_main
    Service->>Stat: 统计抵扣金额
    Stat->>DB: INSERT/UPDATE lq_stat_result
```

## 模块依赖关系

```mermaid
graph LR
    subgraph 层级结构
        STARTUP[startup模块]
        API[open-leqi-api]
        SERVICE[open-leqi-service]
        COMMON[百望基础组件]
    end

    STARTUP -->|依赖| SERVICE
    STARTUP -->|依赖| API
    SERVICE -->|依赖| API
    SERVICE -->|依赖| COMMON
    API -->|依赖| COMMON
```

## 业务能力模块

```mermaid
mindmap
  root((乐企能力))
    发票管理
      发票开具
      发票同步
      发票查询
      发票作废
      发票修复
    勾选能力
      抵扣勾选
      退税勾选
      不抵扣处理
      农产品抵扣
      成品油抵扣
    统计能力
      统计结果
      统计查询
      异常处理
    专项能力
      航空客票
      铁路客票
      二手车
      新车销售
```


path: references/api-guide.md
content: # 乐企API接口指南

## 一、API模块说明

API模块位于 `D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/`

### 1.1 Client接口列表 (29个)

| Client类 | 功能说明 |
|----------|----------|
| LqInvoiceMainClient | 发票主表接口 |
| LqInvoiceDetailClient | 发票明细接口 |
| LqInvoiceDeductClient | 发票抵扣接口 |
| LqInvoiceFileRecordClient | 发票文件记录接口 |
| LqInvoicePoolRecordClient | 发票池记录接口 |
| LqInvoicePoolTaskClient | 发票池任务接口 |
| LqInvoicePoolErrorMsgClient | 发票池错误消息接口 |
| LqNotdeductInitTaskClient | 不抵扣初始化任务接口 |
| LqStatResultClient | 统计结果接口 |
| LqSyncClient | 同步接口 |
| LqSyncTaskClient | 同步任务接口 |
| LqTaskClient | 任务接口 |
| LqTaxInfoClient | 税信息接口 |
| LqTaxPeriodClient | 税款属期接口 |
| LqDownReqRecordClient | 下载请求记录接口 |
| LqDownResRecordClient | 下载响应记录接口 |
| LqErrorRetryConfigClient | 错误重试配置接口 |
| LqWarrantAccountClient | 作废账户接口 |
| LqWarrantDeductClient | 作废抵扣接口 |
| LqWarrantDetailClient | 作废明细接口 |
| LqWarrantSyncClient | 作废同步接口 |
| LqWithholdDeductClient | 预扣抵扣接口 |
| LqAviationElemClient | 航空电子客票接口 |
| LqAviationElemDetailClient | 航空电子客票明细接口 |
| LqTrainElemClient | 铁路电子客票接口 |
| LqUsedCarDetailClient | 二手车明细接口 |
| LqVehicleDetailClient | 车辆明细接口 |
| LqFarmAddDeductInvoiceSyncClient | 农产品加计扣除发票同步接口 |

## 二、Web层接口 (60个Controller)

### 2.1 发票管理类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqInvoiceMainController | /web/lqInvoiceMain | 发票主表CRUD |
| LqInvoiceDetailController | /web/lqInvoiceDetail | 发票明细管理 |
| LqInvoiceDeductController | /web/lqInvoiceDeduct | 发票抵扣管理 |
| LqInvoiceFileRecordController | /web/lqInvoiceFileRecord | 发票文件记录 |
| LqInvoicePoolRecordController | /web/lqInvoicePoolRecord | 发票池记录 |
| LqInvoicePoolTaskController | /web/lqInvoicePoolTask | 发票池任务 |
| LqInvoicePoolErrorMsgController | /web/lqInvoicePoolErrorMsg | 发票池错误 |
| LqInvoiceAccountController | /web/lqInvoiceAccount | 发票入账 |
| LqInvoiceConsumePoolController | /web/lqInvoiceConsumePool | 发票消费池 |
| LqInvoiceRepairController | /web/lqInvoiceRepair | 发票修复 |

### 2.2 同步类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqSyncController | /web/lqSync | 发票同步 |
| LqSyncTaskController | /web/lqSyncTask | 同步任务 |
| LqSyncTimestampRecordController | /web/lqSyncTimestampRecord | 同步时间戳 |

### 2.3 勾选类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqWithholdDeductController | /web/lqWithholdDeduct | 抵扣勾选 |
| LqWithholdSyncController | /web/lqWithholdSync | 抵扣同步 |
| LqWarrantDeductController | /web/lqWarrantDeduct | 退税勾选 |
| LqWarrantSyncController | /web/lqWarrantSync | 退税同步 |
| LqWarrantAccountController | /web/lqWarrantAccount | 退税账户 |
| LqWarrantDetailController | /web/lqWarrantDetail | 退税明细 |
| LqWarrantOilSyncController | /web/lqWarrantOilSync | 成品油退税 |
| LqNotdeductInitTaskController | /web/lqNotdeductInitTask | 不抵扣任务 |
| LqCurrentDeductRecordController | /web/lqCurrentDeductRecord | 当期抵扣记录 |
| LqCurrentDeductTaskController | /web/lqCurrentDeductTask | 当期抵扣任务 |
| LqOilInvoiceDeductController | /web/lqOilInvoiceDeduct | 成品油抵扣 |
| LqOilWarrantDeductController | /web/lqOilWarrantDeduct | 成品油退税 |

### 2.4 统计类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqStatResultController | /web/lqStatResult | 统计结果 |
| LqOilStatController | /web/lqOilStat | 成品油统计 |
| StatisticsController | /web/statistics | 统计 |

### 2.5 农产品类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqFarmInvoiceController | /web/lqFarmInvoice | 农产品发票 |
| LqFarmInvoiceSyncController | /web/lqFarmInvoiceSync | 农产品同步 |
| LqFarmInvoiceDeductWeightController | /web/lqFarmInvoiceDeductWeight | 农产品抵扣权重 |
| LqFarmAddDeductInvoiceSyncController | /web/lqFarmAddDeductInvoiceSync | 农产品加计扣除 |

### 2.6 交通运输类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqAviationElemController | /web/lqAviationElem | 航空电子客票 |
| LqAviationElemDetailController | /web/lqAviationElemDetail | 航空明细 |
| LqTrainElemController | /web/lqTrainElem | 铁路电子客票 |
| LqUsedCarDetailController | /web/lqUsedCarDetail | 二手车 |
| LqVehicleDetailController | /web/lqVehicleDetail | 车辆明细 |

### 2.7 任务类

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqTaskController | /web/lqTask | 任务管理 |
| LqDownloadTaskController | /web/lqDownloadTask | 下载任务 |
| LqDownReqRecordController | /web/lqDownReqRecord | 下载请求 |
| LqDownResRecordController | /web/lqDownResRecord | 下载响应 |
| LqRetryOperateController | /web/lqRetryOperate | 重试操作 |
| LqErrorRetryConfigController | /web/lqErrorRetryConfig | 错误重试配置 |

### 2.8 其他

| Controller | 路径前缀 | 主要功能 |
|------------|----------|----------|
| LqTaxInfoController | /web/lqTaxInfo | 税信息 |
| LqTaxPeriodController | /web/lqTaxPeriod | 税款属期 |
| LqOilSyncController | /web/lqOilSync | 成品油同步 |
| LqOilTaxPeriodController | /web/lqOilTaxPeriod | 成品油属期 |
| LqCollectController | /web/lqCollect | 归集 |
| LqMessagePoolController | /web/lqMessagePool | 消息池 |
| LqInitializeStatusMonitorController | /web/lqInitializeStatusMonitor | 初始化状态监控 |

## 三、常用API调用示例

### 3.1 发票分页查询
```
POST /web/lqInvoiceMain/queryPageList
Request: LqInvoiceMainPageQueryDto
Response: BWJsonResultDto<PageData<LqInvoiceMainDto>>
```

### 3.2 发票同步
```
POST /web/lqSync/syncInvoice
Request: LqSyncRequestDto
Response: BWJsonResultDto<LqSyncResultDto>
```

### 3.3 抵扣勾选
```
POST /web/lqWithholdDeduct/deduct
Request: LqWithholdDeductDto
Response: BWJsonResultDto<Boolean>
```

## 四、错误码

错误码定义在 `com.baiwang.platform.openleqi.errorcodes` 包下。


path: references/business-flows.md
content: # 乐企业务流程序列

## 一、发票开具流程

### 1.1 全电发票开具
```
┌─────────┐    ┌──────────────┐    ┌────────────────┐    ┌─────────────┐    ┌──────────┐
│ 直连单位 │ → │ LqSyncController │ → │ LqSyncService   │ → │ OFS系统     │ → │ 乐企平台 │
└─────────┘    └──────────────┘    └────────────────┘    └─────────────┘    └──────────┘
     │                                                                              ↓
     │         ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
     └────────→│ LqInvoicePool  │ ← │ LqInvoiceMain  │ ← │ 数据库写入     │
               │ TaskService    │    │ Service        │    │ LqInvoiceMain  │
               └────────────────┘    └────────────────┘    └────────────────┘
```

### 1.2 核心代码路径
```
Controller: D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqSyncController.java
Service:   D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/service/LqSyncService.java
```

## 二、抵扣勾选流程

### 2.1 增值税抵扣勾选
```
┌─────────┐    ┌──────────────────────┐    ┌───────────────────────┐    ┌──────────────┐
│ 纳税人  │ → │ LqWithholdDeduct     │ → │ LqWithholdDeduct      │ → │ LqInvoiceMain│
│         │    │ Controller           │    │ Service               │    │ 更新状态     │
└─────────┘    └──────────────────────┘    └───────────────────────┘    └──────────────┘
                                                                                  ↓
     ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
     │ LqStatResult   │ ← │ 统计计算        │ ← │ 勾选确认        │
     │ Service        │    │                │    │                │
     └────────────────┘    └────────────────┘    └────────────────┘
```

### 2.2 核心代码路径
```
Controller: D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqWithholdDeductController.java
Service:   D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/service/LqWithholdDeductService.java
```

## 三、退税勾选流程

### 3.1 勾选用于退税
```
┌─────────┐    ┌────────────────────┐    ┌──────────────────────┐    ┌──────────────┐
│ 纳税人  │ → │ LqWarrantDeduct     │ → │ LqWarrantDeduct      │ → │ LqInvoiceMain│
│         │    │ Controller         │    │ Service              │    │ 更新状态     │
└─────────┘    └────────────────────┘    └──────────────────────┘    └──────────────┘
```

## 四、农产品抵扣流程

### 4.1 农产品加计扣除
```
┌─────────────┐    ┌────────────────────────────┐    ┌─────────────────────────────┐
│ 农产品发票  │ → │ LqFarmInvoiceDeductWeight   │ → │ 扣除金额计算                 │
│ 入账        │    │ Controller                │    │                             │
└─────────────┘    └────────────────────────────┘    └─────────────────────────────┘
```

## 五、发票作废流程

### 5.1 作废流程
```
┌─────────┐    ┌────────────────┐    ┌───────────────┐    ┌────────────────┐
│ 直连单位│ → │ LqWarrantSync   │ → │ LqWarrantPool │ → │ 发票状态变更   │
│         │    │ Controller     │    │ Service       │    │                │
└─────────┘    └────────────────┘    └───────────────┘    └────────────────┘
```

## 六、查询统计流程

### 6.1 统计结果查询
```
┌─────────┐    ┌──────────────────┐    ┌────────────────┐    ┌──────────────┐
│ 查询请求│ → │ LqStatResult     │ → │ LqStatResult   │ → │ 返回统计结果 │
│         │    │ Controller       │    │ Service        │    │              │
└─────────┘    └──────────────────┘    └────────────────┘    └──────────────┘
```

## 七、关键接口清单

| 接口 | Controller | 主要方法 | 说明 |
|------|------------|----------|------|
| 发票同步 | LqSyncController | syncInvoice() | 发票开具同步 |
| 发票查询 | LqInvoiceMainController | queryPageList() | 发票分页查询 |
| 抵扣勾选 | LqWithholdDeductController | deduct() | 抵扣勾选 |
| 撤销抵扣 | LqWithholdDeductController | undoDeduct() | 撤销抵扣 |
| 退税勾选 | LqWarrantDeductController | warrantDeduct() | 退税勾选 |
| 发票作废 | LqWarrantSyncController | warrant() | 发票作废 |
| 统计查询 | LqStatResultController | query() | 统计结果查询 |

## 八、数据流向总图

```
                    ┌─────────────────────────────────────────────────────────┐
                    │                    外部系统                              │
                    │  (电票平台/OFS/电子税务局)                               │
                    └───────────────────────┬─────────────────────────────────┘
                                            │
                                            ▼
                    ┌─────────────────────────────────────────────────────────┐
                    │              open-leqi-service                          │
                    │  ┌─────────────────────────────────────────────────────┐ │
                    │  │                   Web Layer (60 Controllers)       │ │
                    │  │   LqSyncController | LqInvoiceMainController ...   │ │
                    │  └─────────────────────────────────────────────────────┘ │
                    │                          │                              │
                    │                          ▼                              │
                    │  ┌─────────────────────────────────────────────────────┐ │
                    │  │               Service Layer (225 Services)          │ │
                    │  │   LqSyncService | LqInvoiceMainService ...          │ │
                    │  └─────────────────────────────────────────────────────┘ │
                    │                          │                              │
                    │                          ▼                              │
                    │  ┌─────────────────────────────────────────────────────┐ │
                    │  │                 DAO Layer (109 Mappers)             │ │
                    │  │   LqInvoiceMainMapper | LqSyncTaskMapper ...        │ │
                    │  └─────────────────────────────────────────────────────┘ │
                    └─────────────────────────────────────────────────────────┘
                                            │
                                            ▼
                    ┌─────────────────────────────────────────────────────────┐
                    │                      数据库                             │
                    │  lq_invoice_main | lq_invoice_detail | lq_stat_result   │
                    └─────────────────────────────────────────────────────────┘
```


path: references/code-index.md
content: # 乐企项目代码位置索引

## 一、源码根目录

```
D:/leqi/open-leqi/
```

## 二、API模块 (open-leqi-api)

### 2.1 包根目录
```
D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/
```

### 2.2 API层 (Feign Client)
```
D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/
```

| 功能 | 文件路径 |
|------|----------|
| 发票主表Client | `D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/LqInvoiceMainClient.java` |
| 发票明细Client | `D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/LqInvoiceDetailClient.java` |
| 抵扣勾选Client | `D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/LqWithholdDeductClient.java` |
| 退税勾选Client | `D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/api/LqWarrantDeductClient.java` |

### 2.3 模型层
```
D:/leqi/open-leqi/open-leqi-api/src/main/java/com/baiwang/platform/openleqi/model/
```
- DTO定义
- 请求/响应模型

## 三、服务模块 (open-leqi-service)

### 3.1 包根目录
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/
```

### 3.2 Web层 (Controller)
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/
```

| 功能 | 文件路径 |
|------|----------|
| 发票主表 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqInvoiceMainController.java` |
| 发票明细 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqInvoiceDetailController.java` |
| 发票同步 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqSyncController.java` |
| 抵扣勾选 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqWithholdDeductController.java` |
| 退税勾选 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqWarrantDeductController.java` |
| 统计结果 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqStatResultController.java` |
| 农产品抵扣 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqFarmInvoiceDeductWeightController.java` |
| 航空客票 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqAviationElemController.java` |
| 铁路客票 | `D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/web/LqTrainElemController.java` |

### 3.3 Service层
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/service/
├── LqInvoiceMainService.java
├── LqInvoiceDetailService.java
├── LqSyncService.java
├── LqWithholdDeductService.java
├── LqWarrantDeductService.java
├── LqStatResultService.java
└── impl/  # Service实现
```

### 3.4 DAO层
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/dao/
├── entity/   # 实体类 (55个)
└── mapper/   # Mapper接口 (54个)
```

### 3.5 公共类
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/common/
```
- 508个公共类
- 工具类、通用组件

### 3.6 配置类
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/config/
```

### 3.7 定时任务
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/job/
```

### 3.8 集成类
```
D:/leqi/open-leqi/open-leqi-service/src/main/java/com/baiwang/platform/openleqi/intergration/
```

## 四、资源文件

```
D:/leqi/open-leqi/open-leqi-service/src/main/resources/com/baiwang/platform/openleqi/dao/mapper/
```
- 47个MyBatis XML映射文件

## 五、快速定位规则

### 按业务功能
| 业务功能 | Controller | Service | DAO Entity |
|----------|------------|---------|------------|
| 发票管理 | LqInvoiceMainController | LqInvoiceMainService | LqInvoiceMain |
| 发票同步 | LqSyncController | LqSyncService | LqSyncTask |
| 抵扣勾选 | LqWithholdDeductController | LqWithholdDeductService | LqInvoiceMain |
| 退税勾选 | LqWarrantDeductController | LqWarrantDeductService | LqInvoiceMain |
| 统计 | LqStatResultController | LqStatResultService | LqStatResult |
| 农产品 | LqFarmInvoiceDeductWeightController | LqFarmInvoiceDeductWeightService | - |

### 按技术层面
| 层面 | 路径模式 |
|------|----------|
| API Client | `open-leqi-api/.../api/*Client.java` |
| Web Controller | `open-leqi-service/.../web/*Controller.java` |
| Service | `open-leqi-service/.../service/*Service.java` |
| Service Impl | `open-leqi-service/.../service/impl/*ServiceImpl.java` |
| Entity | `open-leqi-service/.../dao/entity/*.java` |
| Mapper | `open-leqi-service/.../dao/mapper/*Mapper.java` |
| Mapper XML | `open-leqi-service/src/main/resources/com/.../dao/mapper/*.xml` |


path: references/project-architecture.md
content: # 乐企项目详细架构说明

## 一、项目概述

**open-leqi** 是百望乐企数字开放平台的发票管理系统，基于Spring Boot 2.7.x架构。

### 技术栈
- Java 1.8
- Spring Boot 2.7.196
- MyBatis-Plus
- 百望BOP SDK 3.4.822
- Maven多模块项目

## 二、模块划分

### 2.1 open-leqi-api (API模块)

**职责**: 定义Feign客户端接口，供外部系统调用

**包结构**:
```
com.baiwang.platform.openleqi
├── api/           # 29个Feign Client
│   ├── LqInvoiceMainClient.java
│   ├── LqInvoiceDetailClient.java
│   ├── LqWithholdDeductClient.java
│   └── ... (其他业务Client)
├── model/         # 163个数据模型
│   ├── dto/       # 数据传输对象
│   ├── request/   # 请求模型
│   └── response/  # 响应模型
└── farm/          # 农业相关API
```

### 2.2 open-leqi-service (服务模块)

**职责**: 实现核心业务逻辑

**包结构**:
```
com.baiwang.platform.openleqi
├── web/           # 60个Controller
│   ├── LqInvoiceMainController.java
│   ├── LqSyncController.java
│   ├── LqWithholdDeductController.java
│   └── ...
├── service/       # 业务服务
│   ├── impl/      # 122个Service实现
│   ├── message/   # 消息处理
│   └── nativeAutoFrameWork/ # 自动化框架
├── dao/           # 数据访问
│   ├── entity/    # 55个实体类
│   └── mapper/    # 54个Mapper接口
├── common/        # 508个公共类
├── config/        # 配置类
├── job/           # 19个定时任务
├── intergration/  # 48个集成类
└── deserializer/  # 反序列化器
```

### 2.3 startup (启动模块)

**职责**: 项目启动入口，配置类加载

## 三、核心数据流

### 3.1 发票开具流程
```
外部系统 → LqSyncController
        → LqSyncService.syncInvoice()
        → OFSClient调用乐企接口
        → 发票池(LqInvoicePoolTask)
        → 发票主表(LqInvoiceMain)
```

### 3.2 抵扣勾选流程
```
用户勾选 → LqWithholdDeductController
        → LqWithholdDeductService.deduct()
        → 更新LqInvoiceMain状态
        → LqStatResult统计
```

### 3.3 数据同步流程
```
OFS系统 → LqSyncController
       → LqSyncService.processSync()
       → 各业务Service处理
       → DAO更新数据库
```

## 四、核心数据表

| 表名 | 说明 | Entity |
|------|------|--------|
| lq_invoice_main | 发票主表 | LqInvoiceMain |
| lq_invoice_detail | 发票明细 | LqInvoiceDetail |
| lq_warrant_pool | 作废池 | LqWarrantPool |
| lq_stat_result | 统计结果 | LqStatResult |
| lq_sync_task | 同步任务 | LqSyncTask |

## 五、定时任务

| 任务类 | 功能 | Cron |
|--------|------|------|
| LqSyncTaskJob | 发票同步 | - |
| LqPoolTaskJob | 发票池处理 | - |
| LqStatResultJob | 统计结果 | - |

## 六、配置说明

### 6.1 配置文件位置
```
open-leqi-service/src/main/resources/
├── com/baiwang/platform/openleqi/dao/mapper/  # MyBatis XML
└── application.yml (需配置)
```

### 6.2 主要配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://...
  redis:
    host: ...
```

## 七、API网关

### 7.1 主要端点
```
POST /web/lqInvoiceMain/queryPageList    # 发票分页查询
POST /web/lqSync/invoiceSync             # 发票同步
POST /web/lqWithholdDeduct/deduct        # 抵扣勾选
```

### 7.2 返回格式
```java
BWJsonResultDto<T>
├── code: 状态码
├── message: 消息
├── data: 数据
└── timestamp: 时间戳
```

## 八、扩展能力

### 8.1 农业发票
- `LqFarmInvoiceSyncController` - 农产品发票同步
- `LqFarmInvoiceDeductWeightService` - 农产品抵扣权重

### 8.2 成品油
- `LqOilInvoiceDeductController` - 成品油抵扣
- `LqOilSyncController` - 成品油同步

### 8.3 航空运输
- `LqAviationElemController` - 航空电子客票
- `LqAviationElemDetailController` - 航空明细

### 8.4 铁路运输
- `LqTrainElemController` - 铁路电子客票

### 8.5 二手车/新车
- `LqUsedCarDetailController` - 二手车
- `LqVehicleDetailController` - 新车


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)