对接牦牛资产档案

doc/产业数据模型及服务/牦牛存栏数据填报/牦牛存栏数据填报功能需求.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | 模块名称 | 牦牛存栏数据填报 |
 | 目标 | 按**乡镇 × 所属年份**填报、导入、维护县域牦牛存栏结构统计数据，支撑养殖产业看板、监管报表及历史年度对比 |
-| 关联系统 | 业务后台（增删改查、Excel 导入）；组织机构 `sys_dept`（乡镇字典） |
+| 关联系统 | 业务后台（增删改查、Excel 导入/导出）；组织机构 `sys_dept`（乡镇字典） |
 | 修订依据 | 业务模板 `2026年.xlsx`（农业农村和科技水利局-业务办-畜群结构）；用户填报诉求 |
 
 本文档仅描述**功能需求与业务规则**，不涉及库表字段命名、接口路径、技术栈选型及实现细节（见同目录技术方案）。
@@ -27,7 +27,7 @@
 | --- | --- |
 | 可选范围 | **当前自然年**起向前共 **6 个自然年**（含当年），即「当年、前 1 年 … 前 5 年」 |
 | 示例 | 若统计日为 2026 年，可选：2026、2025、2024、2023、2022、2021 |
-| 展示 | 列表、表单、导入时均以**四位年份**展示与存储 |
+| 展示 | 列表、表单、导入、导出时均以**四位年份**展示与存储 |
 
 ### 2.3 所属乡镇
 
@@ -83,12 +83,12 @@
 | 删除 | 逻辑删除；见 **§5.4** |
 | 详情 | 查看全部字段；见 **§5.5** |
 | Excel 导入 | 按模板批量导入**指定填报年份**下所有乡镇数据；见 **§5.6** |
+| Excel 导出 | 按**指定所属年份**导出巴青县**全部乡镇**存栏数据；见 **§5.7** |
 | 乡镇下拉 | 从 `sys_dept` 动态加载合法乡镇；见 **§5.2** |
 
 **本期不实现：**
 
 - 按村居维度的多行填报、审批流、版本对比、自动从生物资产台账汇总  
-- 导出 Excel（若需要可单独立项）  
 - 所属村居下钻维护（字段预留）
 
 ---
@@ -100,6 +100,7 @@ flowchart TD
     A[选择所属年份] --> B{录入方式}
     B -->|手工| C[选择乡镇并填写指标]
     B -->|导入| D[上传 Excel 模板]
+    B -->|导出| X[下载全县乡镇 Excel]
     C --> E[保存]
     D --> F[解析并匹配乡镇]
     F --> G{同年同乡镇是否存在}
@@ -108,6 +109,7 @@ flowchart TD
     E --> J[列表查询/详情]
     H --> J
     I --> J
+    X --> J
 ```
 
 ---
@@ -220,6 +222,23 @@ flowchart TD
 
 ---
 
+### 5.7 Excel 导出
+
+| 项 | 要求 |
+| --- | --- |
+| 入口 | 列表页「按年份导出」 |
+| 导出年份 | 用户**必须选择**筛选条件中的「所属年份」（范围 **§2.2**）；未选择时前端提示 |
+| 导出范围 | **巴青县全部乡镇**（**§2.3** 合法乡镇，按 `order_num` 排序），**不受**「所属乡镇」筛选限制 |
+| 模板 | 与导入共用：`baqing-admin/src/main/resources/templates/yak_herd_inventory_import_template.xlsx`（业务源文件 `2026年.xlsx` 第一个 Sheet） |
+| 填充规则 | 表头标题中的年份替换为所选年份；每个乡镇一行；有填报数据的乡镇填入全部指标；未填报乡镇仅保留乡镇名称，指标为空 |
+| 合计行 | 数据区末行输出「合计」，对**已填报乡镇**的数值列求和 |
+| 文件格式 | `.xlsx`；文件名示例：`2026年牦牛存栏数据.xlsx` |
+| 与导入关系 | 导出文件列结构与导入模板一致，可再次导入（同年将 upsert） |
+
+**与「下载模板」区别**：「下载模板」为空白模板；「按年份导出」为按库内数据填充后的全县报表。
+
+---
+
 ## 6. 权限矩阵
 
 | 操作 | 建议权限 |
@@ -230,6 +249,7 @@ flowchart TD
 | 修改 | `dataModel:yakHerdInventory:edit` |
 | 删除 | `dataModel:yakHerdInventory:remove` |
 | 导入 | `dataModel:yakHerdInventory:import` |
+| 导出 | `dataModel:yakHerdInventory:export` |
 
 数据权限：县级管理员可见全县；乡镇账号仅可见本乡镇数据（若启用部门数据权限，按 `town_dept_id` 与登录用户 `dept_id` 过滤）。
 
@@ -239,6 +259,7 @@ flowchart TD
 
 - 必填项未填、年份/乡镇不合法、同年同乡镇重复  
 - 导入：文件格式错误、乡镇无法匹配、数字非整数、行为空  
+- 导出：未选年份、年份不在可选范围  
 - 删除成功/失败、导入部分失败（展示明细）  
 
 采用项目统一 `AjaxResult` 文案风格，**不约定** HTTP 状态码细节。
@@ -252,7 +273,7 @@ flowchart TD
 | 性能 | 列表分页；导入单次 ≤ 50 行（10 乡镇 × 多年份分批） |
 | 审计 | 记录创建人、创建时间、更新人、更新时间 |
 | 口径 | 母牛分龄边界若有县级红头文件，以业务口径覆盖本文档示例说明 |
-| 扩展 | 所属村居（`village_dept_id`）下钻、导出、与「养殖产业数据」看板联动 |
+| 扩展 | 所属村居（`village_dept_id`）下钻、与「养殖产业数据」看板联动 |
 
 ---
 
@@ -265,5 +286,16 @@ flowchart TD
 | 乡镇 sys_dept | §2.3 |
 | 增删改查 | §5.1～5.5 |
 | Excel 导入 | §5.6 |
+| Excel 导出 | §5.7 |
 | 列表/详情字段 | §5.1 列表 7 列；§5.5 详情全字段 |
 | 预留村居 `village_dept_id` | §2.4、§5.2、§5.5 |
+
+---
+
+## 10. 修订记录
+
+| 版本 | 说明 |
+| --- | --- |
+| 1.0 | 初稿 |
+| 1.1 | 增加 `village_dept_id` 预留字段；列表列「乡镇」「存栏数」 |
+| 1.2 | 增加 **§5.7 按年份导出** 全县乡镇 Excel；权限 `export` |

doc/产业数据模型及服务/牦牛存栏数据填报/牦牛存栏数据填报技术方案.md

@@ -14,9 +14,11 @@
 | **Excel** | Apache POI 或项目已有 EasyExcel（与若依导入规范一致） |
 | **组织** | `sys_dept` 乡镇字典；`SysDeptMapper` 查询二级节点 |
 
-**分层**：`BizYakHerdInventoryController` → `IBizYakHerdInventoryService` / `BizYakHerdInventoryImportService` → `BizYakHerdInventoryMapper` → `domain`。
+**分层**：`BizYakHerdInventoryController` → `IBizYakHerdInventoryService` → `BizYakHerdInventoryMapper` → `domain`；Excel 由 `YakHerdInventoryExcelParser`（导入解析）、`YakHerdInventoryExcelExporter`（按年导出）承担。
 
-**代码位置（建议）**：`baqing-admin` → `com.ruoyi.web.modules.industryservice`（与产业数据模型同包）。
+**代码位置**：`baqing-admin` → `com.ruoyi.web.modules.industryservice`（与产业数据模型同包）。
+
+**模板文件**：`baqing-admin/src/main/resources/templates/yak_herd_inventory_import_template.xlsx`（导入、导出、下载模板共用）。
 
 ---
 
@@ -50,10 +52,10 @@
 
 **索引与约束**
 
-- `UNIQUE uk_year_town (stat_year, town_dept_id, del_flag)` — 仅对有效记录唯一；逻辑删除后 `del_flag=2` 可再插（或采用 `uk_year_town (stat_year, town_dept_id)` + 应用层校验，推荐后者并配合查询 `del_flag=0` 唯一校验）。  
-- **推荐**：`UNIQUE uk_year_town_active (stat_year, town_dept_id)` 且删除时物理保留单行、仅改 `del_flag`；新增前校验无 `del_flag=0` 重复。  
+- 应用层校验：同年同乡镇仅一条 `del_flag='0'` 有效记录（`countActiveByYearAndTownExcludeId`）。  
 - `KEY idx_stat_year (stat_year)`  
-- `KEY idx_town_dept_id (town_dept_id)`
+- `KEY idx_town_dept_id (town_dept_id)`  
+- `KEY idx_del_flag (del_flag)`
 
 **DDL 文件**：`sql/biz_yak_herd_inventory.sql`
 
@@ -98,6 +100,7 @@ for (int y = current; y >= current - 5; y--) { ... }
 | 3.7 | 年份下拉 | GET | `/yearOptions` | `list` |
 | 3.8 | 导入 | POST | `/importData` | `import` |
 | 3.9 | 下载导入模板 | GET | `/importTemplate` | `import` |
+| 3.10 | 按年份导出 | GET | `/export` | `export` |
 
 #### 3.1.1 列表 Query
 
@@ -164,25 +167,46 @@ for (int y = current; y >= current - 5; y--) { ... }
 | 数据行 | `headerRow + 1` 起至「乡镇」列为空 |
 | 列映射（默认，实施对照模板微调） | |
 
-| 列号 | 表头关键字 | 实体字段 |
+| 列号（0-based） | Excel 列 | 实体字段 |
+| --- | --- | --- |
+| 1 | B | 乡镇（按 `dept_name` 解析 `townDeptId`） |
+| 2 | C | `villageCount` |
+| 3 | D | `herdsmanHouseholdCount` |
+| 4 | E | `yakTotal`（存栏数） |
+| 5 | F | 与 E 同值（模板镜像列，导出时同步写入） |
+| 6 | G | `bullTotal` |
+| 9 | J | `breedingBullCount` |
+| 10 | K | `bullCastratedCount` |
+| 11 | L | `cowTotal` |
+| 12 | M | `cowUnder1Count` |
+| 13 | N | `cow13Count` |
+| 14 | O | `cow312Count` |
+| 15 | P | `cowOver12Count` |
+| 16 | Q | `remark` |
+
+> 数据区起始行：`headerRow + 3`（表头行由「序号」「乡镇」自动识别）。模板存在合并单元格，列号以代码常量为准。
+
+**导入事务**：逐乡镇独立处理，单乡镇失败不影响其余。
+
+#### 3.10 按年份导出
+
+**请求**：`GET /export?statYear=2026`
+
+| 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| B | 乡镇 | `townDeptId`（按名称解析） |
-| C | 村居数 | `villageCount` |
-| D | 牧户数 | `herdsmanHouseholdCount` |
-| E | 总合计 / 牦牛 | `yakTotal` |
-| F | 公牛-合计 | `bullTotal` |
-| G | 种公牛 | `breedingBullCount` |
-| H | 公牛/阉畜 | `bullCastratedCount` |
-| I | 母牛-合计 | `cowTotal` |
-| J | 1岁以下 | `cowUnder1Count` |
-| K | 1-3岁 | `cow13Count` |
-| L | 3-12岁 | `cow312Count` |
-| M | 12岁以上 | `cowOver12Count` |
-| N | 备注 | `remark` |
-
-> 模板存在合并单元格时，以**数据区实际列字母**在代码中常量配置；导入单测使用 `2026年.xlsx` 快照校验 10 个乡镇行。
-
-**导入事务**：逐乡镇 `REQUIRES_NEW` 或整批单事务；推荐**逐条独立事务**，单乡镇失败不影响其余（与牧场同步模式一致）。
+| `statYear` | Y | 导出年份，须在 `yearOptions` 范围内 |
+
+**响应**：`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` 文件流；文件名 `{statYear}年牦牛存栏数据.xlsx`。
+
+**实现**：`BizYakHerdInventoryServiceImpl.exportByYear` → `YakHerdInventoryExcelExporter.export`：
+
+1. 加载 classpath 模板 `YakHerdInventoryExcelExporter.TEMPLATE_CLASSPATH`  
+2. 替换表头中的四位年份为 `statYear`  
+3. 查询 `stat_year = statYear` 且 `del_flag='0'` 的全部记录，按 `town_dept_id` 建 Map  
+4. 遍历 `TownDeptSupport.listReportTowns()`，逐乡镇写行；无数据则仅写乡镇名  
+5. 末行写「合计」，对已填报乡镇数值列求和  
+
+**与 3.9 区别**：`/importTemplate` 返回空白模板；`/export` 返回填充后的全县报表。
 
 ---
 
@@ -196,7 +220,8 @@ for (int y = current; y >= current - 5; y--) { ... }
 | **详情** | 抽屉/对话框只读展示全部字段 |
 | **表单** | 抽屉或对话框；年份/乡镇下拉；数字 `el-input-number` `:min="0"` `:precision="0"` |
 | **导入** | 先选「填报年份」→ 上传 → 展示导入结果摘要 |
-| **模板下载** | 可提供静态模板副本 `doc/.../templates/2026年-牦牛存栏导入模板.xlsx`（从业务文件复制） |
+| **模板下载** | `GET /importTemplate`；空白模板 |
+| **按年份导出** | 列表先选「所属年份」→ `GET /export`；`download('dataModel/yakHerdInventory/export', { statYear })` |
 
 ---
 
@@ -210,8 +235,9 @@ for (int y = current; y >= current - 5; y--) { ... }
 | 按钮 | 修改 | `dataModel:yakHerdInventory:edit` |
 | 按钮 | 删除 | `dataModel:yakHerdInventory:remove` |
 | 按钮 | 导入 | `dataModel:yakHerdInventory:import` |
+| 按钮 | 导出 | `dataModel:yakHerdInventory:export` |
 
-挂载目录：**产业数据模型及服务**。
+挂载目录：**产业数据模型及服务**。菜单 SQL 见 `sql/biz_sys_menu_yak_herd_inventory.sql`。
 
 ---
 
@@ -223,12 +249,12 @@ for (int y = current; y >= current - 5; y--) { ... }
 
 ## 7. 交付清单
 
-- [ ] `sql/biz_yak_herd_inventory.sql`  
-- [ ] `BizYakHerdInventory` Domain / Mapper / XML / Service / Controller  
-- [ ] `BizYakHerdInventoryImportService` + 列映射配置  
-- [ ] `TownDeptSupport` 乡镇字典  
-- [ ] 前端列表/表单/导入  
-- [ ] 单元测试 + 导入集成测试（`2026年.xlsx`）  
+- [x] `sql/biz_yak_herd_inventory.sql`  
+- [x] `BizYakHerdInventory` Domain / Mapper / XML / Service / Controller  
+- [x] `YakHerdInventoryExcelParser` + `YakHerdInventoryExcelExporter`  
+- [x] `TownDeptSupport` 乡镇字典  
+- [x] 前端列表/表单/导入/导出  
+- [x] 单元测试 + 导入/导出集成测试（`yak_herd_inventory_2026.xlsx`）  
 
 ---
 
@@ -238,3 +264,4 @@ for (int y = current; y >= current - 5; y--) { ... }
 | --- | --- |
 | 1.0 | 初稿：表结构、CRUD、导入、sys_dept 乡镇、年份前推 5 年 |
 | 1.1 | 增加预留字段 `village_dept_id`（非必填） |
+| 1.2 | 实现按年份导出全县乡镇 Excel；列映射与代码对齐；交付清单勾选 |

doc/产业数据模型及服务/牦牛存栏数据填报/牦牛存栏数据填报测试用例.md

@@ -30,6 +30,8 @@
 | ZCZX-MYCLTB-UT-015 | 数据权限 | 乡镇账号过滤 | 单元测试 | JUnit5+Mockito | §6 | 用户 dept=杂色镇 | `selectList` | 仅本乡镇 |
 | ZCZX-MYCLTB-UT-016 | 预留字段 | village_dept_id 可空 | 单元测试 | JUnit5 | §2.4 | 无 | `insert` 不传 `villageDeptId` | 成功 |
 | ZCZX-MYCLTB-UT-017 | 预留字段 | village_dept_id 父子校验 | 单元测试 | JUnit5+Mockito | §2.4 | 乡镇 A、村居 B 非子节点 | `insert` 带错误 `villageDeptId` | 失败（若启用校验）或成功仅存 id |
+| ZCZX-MYCLTB-UT-018 | 导出 | 按年填充模板 | 单元测试 | JUnit5 | §5.7 | 模板+1 乡镇样本 | `YakHerdInventoryExcelExporter.export` | 返回 xlsx；解析含对应存栏数 |
+| ZCZX-MYCLTB-UT-019 | 导出 | 全县乡镇行数 | 单元测试 | JUnit5 | §5.7 | 10 乡镇字典 | `export(2026, towns, map)` | 解析数据行 + 合计行 |
 
 ---
 
@@ -57,6 +59,11 @@
 | ZCZX-MYCLTB-API-018 | 权限 | 无 add | 接口测试 | Postman | §6 | 仅 list 角色 | `POST /` | 403 |
 | ZCZX-MYCLTB-API-019 | 权限 | 无 import | 接口测试 | Postman | §6 | 无 import | `POST /importData` | 403 |
 | ZCZX-MYCLTB-API-020 | 端到端 | 导入-查-详情 | 接口测试 | Postman | §4 | 空库 | 导入 2026→list→detail | 数据一致 |
+| ZCZX-MYCLTB-API-021 | 导出 | 按年份导出 | 接口测试 | Postman/MockMvc | §5.7 | 有 2026 数据 | `GET /export?statYear=2026` | `200`；`Content-Type` 为 xlsx |
+| ZCZX-MYCLTB-API-022 | 导出 | 缺 statYear | 接口测试 | Postman | §5.7 | 已登录 | `GET /export` 无参 | 失败 |
+| ZCZX-MYCLTB-API-023 | 导出 | 非法年份 | 接口测试 | Postman | §5.7 | 已登录 | `statYear=1999` | 失败 |
+| ZCZX-MYCLTB-API-024 | 权限 | 无 export | 接口测试 | Postman | §6 | 无 export | `GET /export?statYear=2026` | 403 |
+| ZCZX-MYCLTB-API-025 | 端到端 | 导出-再导入 | 接口测试 | Postman | §5.7 | 有 2026 全量 | 导出→改一行→导入 | upsert 成功 |
 
 ---
 
@@ -79,6 +86,9 @@
 | ZCZX-MYCLTB-UI-011 | 导入 | 未选年份 | UI 测试 | Playwright | §5.6 | 有 import 权限 | 直接上传 | 前端拦截或后端失败提示 |
 | ZCZX-MYCLTB-UI-012 | 权限 | 无导入按钮 | UI 测试 | Playwright | §6 | 无 import | 进入页面 | 无导入入口 |
 | ZCZX-MYCLTB-UI-013 | 端到端 | 导入后列表 | UI 集成 | Playwright | §4 | 空库 | 导入→筛选 2026 | 10 行乡镇数据 |
+| ZCZX-MYCLTB-UI-014 | 导出 | 按年份导出 | UI 测试 | Playwright | §5.7 | 有 export 权限；已选年份 | 点「按年份导出」 | 下载 `{年}年牦牛存栏数据.xlsx` |
+| ZCZX-MYCLTB-UI-015 | 导出 | 未选年份 | UI 测试 | Playwright | §5.7 | 有 export 权限 | 未选年份点导出 | 提示先选择所属年份 |
+| ZCZX-MYCLTB-UI-016 | 权限 | 无导出按钮 | UI 测试 | Playwright | §6 | 无 export | 进入页面 | 无「按年份导出」入口 |
 
 ---
 
@@ -92,7 +102,8 @@
 | §5.2～5.4 CRUD | 必填、唯一、删除 | UT-003～006；API-006～011 |
 | §5.5 详情 | 全字段 | API-005；UI-009 |
 | §5.6 导入 | 2026年.xlsx | UT-007～012；API-014～017；UI-010～011 |
-| §6 权限 | 按钮级 | API-018～019；UI-012 |
+| §5.7 导出 | 按年全县乡镇 | UT-018～019；API-021～025；UI-014～015 |
+| §6 权限 | 按钮级 | API-018～019、024；UI-012、016 |
 
 ---
 
@@ -101,4 +112,5 @@
 | 版本 | 说明 |
 | --- | --- |
 | 1.0 | 初版：单元 15、接口 20、UI 13；编号前缀 **ZCZX-MYCLTB** |
-| 1.1 | 补充 `village_dept_id` 预留字段用例 UT-016～017；单元用例共 17 条 |
+| 1.1 | 补充 `village_dept_id` 预留字段用例 UT-016～017 |
+| 1.2 | 补充按年份导出用例 UT-018～019、API-021～025、UI-014～016 |