# Tushare 报表呈现优化任务 (Report Presentation Refactor)

## 1. 背景与问题
目前的 Tushare 数据以 `metric_name` + `period_date` 的长表形式存储和展示。
问题：
- **可读性差**：无法直观对比同一时间点下的不同指标，也无法直观对比同一指标的历史趋势。
- **缺乏语义**：原始字段如 `c_pay_acq_const_fiolta` 对普通用户极其晦涩。
- **精度冗余**：`1420023169.52` 这样的数字难以快速阅读。

## 2. 设计目标 (Design Goal)
生成一份结构化、人类可读的 Markdown 报告，必须**包含所有原始数据**，无损且清晰。

### 2.1 核心转换逻辑 (Pivot)
- **全量保留**：所有原始数据中的 `metric_name` 都必须展示，不可遗漏。
- **行 (Rows)**: 财务指标 (Metrics)，需映射为中文名称，并进行逻辑分组（如利润表、资产负债表）。未匹配到字典的指标显示原始 Key。
- **列 (Columns)**: 报告期 (Period Date)，按时间倒序排列。
- **值 (Values)**: 格式化后的数值 (e.g., 亿元、万元、百分比)。

### 2.2 展示结构 (Sectioning)
采用**“按年份分组”+“指标分组”**的嵌套结构，利用 Markdown 标题层级进行索引。
- **Data Provider 仅负责数据格式化，不涉及 LLM 摘要生成。**
- **纯数据展示**：不生成任何自然语言评论或摘要。

**结构示例：**

```markdown
# 600521.SS 财务数据明细

## 2025年度
### 关键指标
| 指标 | 2025-09-30 | ... |
| :--- | :--- | :--- |
| 总市值 | 14.20 亿 | ... |

### 资产负债表
...

## 2024年度
### 关键指标
| 指标 | 2024-12-31 | 2024-09-30 | 2024-06-30 | 2024-03-31 |
| :--- | :--- | :--- | :--- | :--- |
| ... | ... | ... | ... | ... |

### 资产负债表
...
```

*分段策略：按**年份**（Year）进行一级切分。每年包含该年所有已披露的报告期。这种方式索引最清晰，且单表列数固定（通常最多4列），完美适配阅读。*

## 3. 实施步骤 (Implementation Plan)

### Step 1: 数据字典完善 (Data Dictionary)
- 完善 `docs/5_data_dictionary/` 下的定义。
- 建立 `metric_name` -> `Display Name (CN)` 的全量映射表。

### Step 2: 数据转换逻辑 (Transformation)
- **分组算法**: 
    - 解析 `period_date` 提取年份。
    - 按年份将数据归类到不同的 `YearBlock`。
    - 年份倒序排列（2025 -> 2024 -> ...）。
    - 年份内部按日期倒序排列（12-31 -> 09-30 ...）。
- **行分类算法**: 将 Metrics 分为 `Snapshot`, `Income`, `Balance`, `CashFlow`, `Ratios`, `Misc`。
- **格式化**: 
    - 金额: 除以 10^8 保留 2 位小数 (e.g., "14.20 亿")。
    - 比例: 乘 100 保留 2 位小数 (e.g., "15.30%").
    - 人数/户数: 整数或“万”单位。

### Step 3: Markdown 渲染 (Rendering)
- 实现分层渲染：
    1.  Level 2 Title: `## 2024年度`
    2.  Level 3 Title: `### 资产负债表`
    3.  Table: 渲染该年份内的该类指标。

## 4. 详细设计与映射 (Detailed Design)

### 4.1 字段映射表 (Field Mapping Dictionary)

**A. 摘要与市场 (Snapshot & Market)**
| Metric Key | 中文显示 | 单位策略 |
| :--- | :--- | :--- |
| `total_mv` | 总市值 | 亿 (保留2位) |
| `employees` | 员工人数 | 整数 |
| `holder_num` | 股东户数 | 万 (保留2位) |
| `close` | 收盘价 | 原始值 |
| `pe` | 市盈率 | 原始值 |
| `pb` | 市净率 | 原始值 |

**B. 利润表 (Income Statement)**
| Metric Key | 中文显示 | 单位策略 |
| :--- | :--- | :--- |
| `revenue` | 营业收入 | 亿 |
| `n_income` | 净利润 | 亿 |
| `rd_exp` | 研发费用 | 亿 |
| `sell_exp` | 销售费用 | 亿 |
| `admin_exp` | 管理费用 | 亿 |
| `fin_exp` | 财务费用 | 亿 |
| `total_cogs` | 营业成本 | 亿 |
| `tax_to_ebt` | 实际税率 | % |
| `__tax_rate` | 所得税率(计算) | % |

**C. 资产负债表 (Balance Sheet)**
| Metric Key | 中文显示 | 单位策略 |
| :--- | :--- | :--- |
| `total_assets` | 总资产 | 亿 |
| `fix_assets` | 固定资产 | 亿 |
| `inventories` | 存货 | 亿 |
| `accounts_receiv`| 应收账款 | 亿 |
| `accounts_pay` | 应付账款 | 亿 |
| `prepayment` | 预付款项 | 亿 |
| `adv_receipts` | 预收款项 | 亿 |
| `contract_liab` | 合同负债 | 亿 |
| `money_cap` | 货币资金 | 亿 |
| `lt_eqt_invest` | 长期股权投资 | 亿 |
| `goodwill` | 商誉 | 亿 |
| `st_borr` | 短期借款 | 亿 |
| `lt_borr` | 长期借款 | 亿 |

**D. 现金流量表 (Cash Flow)**
| Metric Key | 中文显示 | 单位策略 |
| :--- | :--- | :--- |
| `n_cashflow_act` | 经营净现金流 | 亿 |
| `c_paid_to_for_empl` | 支付职工现金 | 亿 |
| `c_pay_acq_const_fiolta` | 购建资产支付 | 亿 |
| `dividend_amount`| 分红总额 | 亿 |

**E. 运营与比率 (Ratios)**
| Metric Key | 中文显示 | 单位策略 |
| :--- | :--- | :--- |
| `arturn_days` | 应收周转天数 | 天 |
| `invturn_days` | 存货周转天数 | 天 |
| `__gross_margin` | 毛利率 | % |
| `__net_margin` | 净利率 | % |
| `__money_cap_ratio` | 现金占比 | % |
| `__fix_assets_ratio` | 固定资产占比 | % |
| `__lt_invest_ratio` | 长投占比 | % |
| `__goodwill_ratio` | 商誉占比 | % |
| `__ar_ratio` | 应收占比 | % |
| `__ap_ratio` | 应付占比 | % |
| `__st_borr_ratio` | 短贷占比 | % |
| `__lt_borr_ratio` | 长贷占比 | % |
| `__rd_rate` | 研发费率 | % |
| `__sell_rate` | 销售费率 | % |
| `__admin_rate` | 管理费率 | % |

**F. 其他 (Misc)**
*未匹配上述任何字段的 Key，将直接显示原始 Key，并保留原始数值精度。*

### 4.2 Markdown 结构全貌 (Structure Preview)

```markdown
# Tushare 财务数据明细

## 2025年度
### 关键指标
| 指标 | 2025-09-30 | ... |
| :--- | :--- | :--- |
| 总市值 | 14.20 亿 | ... |

### 利润表
| 指标 | 2025-09-30 | ... |
| :--- | :--- | ... |
| 营业收入 | 64.09 亿 | ... |

... (资产负债、现金流) ...

## 2024年度
### 关键指标
...
```

