# zdxmtb_python

**Repository Path**: eviltoday/zdxmtb_python

## Basic Information

- **Project Name**: zdxmtb_python
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 惠阳区重点项目月度通报生成工具（Python）

将 WPS VBA "重点项目月度通报生成工具"迁移为 Python 命令行应用。5 类输出与 VBA 内容一致、展示品质化，全部业务参数由 `config.yaml` 驱动（零硬编码）。

## 环境要求

- Python ≥ 3.11
- 依赖：pandas / openpyxl / docxtpl / matplotlib / pyyaml / pydantic v2 / typer / pytest

安装（已存在虚拟环境 `.venv` 时可跳过）：

```powershell
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## 基本用法

```powershell
.venv\Scripts\python.exe main.py generate --month 8
```

生成 2026 年 8 月（1-8月）通报，产出到 `outputs/202608/`：

| 产物 | 路径 |
|---|---|
| 统计结果表 | `outputs/202608/excel/统计结果表.xlsx` |
| 项目清单表 | `outputs/202608/excel/项目清单表.xlsx` |
| 图表 | `outputs/202608/chart/投资进展.png` |
| Word 通报 | `outputs/202608/word/惠阳区重点项目2026年第8期通报.docx` |
| 分离附件 | `outputs/202608/attachment/附件_未开工项目.xlsx`、`附件_进展偏慢项目.xlsx` |

## 参数

| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
| `--month` | 是 | — | 月份档，如 `8` 或 `8.5`（对应 `month_desc` 的"1-8月中旬"） |
| `--input` | 否 | `data/本月.xlsx` | 月度数据文件 |
| `--config` | 否 | `config.yaml` | 配置文件 |
| `--output` | 否 | `outputs` | 输出根目录 |
| `--level` | 否 | 按配置 | 临时覆盖日志级别（DEBUG/INFO/WARN/ERROR） |

## 日常执行流程

1. **更新数据**：每月将最新项目表另存为 `data/本月.xlsx`（表头在第 1 行，数据自第 2 行起；列序需与 `config.yaml` 的 `fields` 映射一致，当前 41 列全对准）
2. **核对配置**：更新 `config.yaml` 中 `basic.total_project_count`（项目数）、`month_desc` 档位、`unit_map`/`UnitSort` 简称等
3. **生成**：执行基本命令
4. **检查日志**：`logs/` 下为旋转日志；运行结束会输出结算行"项目数 / 未开工 / 偏慢 / 输出失败块"
5. **发布产物**：取 `outputs/202608/` 下 6 个文件

## 数据口径说明

- 数据列 6/8/9 的单位已是"万元"，`analysis.convert_investment_wan: false`（若源数据为"元"则置 `true` 以 ÷10000）
- 程序完成比例 = 当前完成投资（col9）÷ 总投资（col6）× 100（PRD 4.2 基线）
- "进展偏慢"= 已开工 且 完成比例 < 时序进度（月份 ÷ 12 × 100）
- "未开工"判定：状态列命中 `未开工` 关键字；空值降级为已开工并记 WARN

## 配置

一切可变参数（基础信息、列映射、统计维度、排序、月份描述、输出开关与表头、日志、LLM 文案生成）均在 `config.yaml`，修改即可调整行为，无需改代码。权威核对表见 `docs/config-check-table.md`。

## 可选：LLM 叙述文案生成

通报中的**数字一律由代码精确计算**（不进 LLM）；叙述文字（问题小标题、未动工原因段、进展偏慢典型、工作建议）默认使用 `config.yaml` 中的兜底文案，也可开启 LLM 生成，失败/超时/密钥缺失时**自动降级为兜底文案，不中断生成**。

**1. 设置 API 密钥（环境变量，绝不写入 `config.yaml`）**

密钥只从环境变量读取（变量名见 `config.yaml` 的 `llm.api_key_env`）：

```powershell
# 临时（仅当前终端窗口有效，须与运行命令同一窗口）
$env:SILICONFLOW_API_KEY = "sk-你的密钥"
# 永久（设置后需新开终端或重启 IDE 才生效）
setx SILICONFLOW_API_KEY "sk-你的密钥"
```

**2. 修改 `config.yaml` 的 `llm` 段**

```yaml
llm:
  enabled: true                # 由 false 改为 true 才启用 LLM
  base_url: https://api.siliconflow.cn/v1   # 提供商端点;通义千问为 …/compatible-mode/v1
  model: Qwen/Qwen3.5-4B      # 以平台实际可用模型为准(平台会定期下线旧模型)
  api_key_env: SILICONFLOW_API_KEY          # 与第 1 步设置的变量名一致
  timeout: 120                 # 推理模型长文生成较慢,超时过短会报 read timeout
```

**3. 运行并检查日志**

- 成功：`LLM 生成成功(model=...),已覆盖 7/7 个叙述键`
- 密钥未设置：`LLM 密钥未设置(...),降级为兜底文案`
- 调用失败/超时：`LLM 生成失败(...),已降级为兜底文案`（可调大 `timeout`）

日志同时输出到控制台和 `logs/app.log`。若运行后没有任何 LLM 相关提示，说明 `enabled` 仍为 `false`（未走 LLM 路径）。

## 工程技能：Gitee issue 追踪令牌

本仓库的 issue / 规格通过 Gitee 远程追踪（细节见 `docs/agents/issue-tracker.md`），使用私有令牌 `GITEE_TOKEN`。令牌只从环境变量读取，绝不写入配置文件或提交到仓库。

**获取令牌**：登录 Gitee → 头像 → 设置 → 私人令牌 → 生成，需勾选 `projects` 权限。

**1. 查看当前是否已设置**

```powershell
if ($env:GITEE_TOKEN) { "已设置，前缀=$($env:GITEE_TOKEN.Substring(0,4))..." } else { "未设置" }
```

**2. 设置令牌**

```powershell
# 临时（仅当前终端窗口有效，须与运行命令同一窗口）
$env:GITEE_TOKEN = "你的令牌"

# 永久（写入用户级环境变量，新开终端或重启 IDE 后生效）
setx GITEE_TOKEN "你的令牌"
```

> 永久设置后，当前窗口需重新手动 `$env:GITEE_TOKEN = "...";` 一次才立即可用（`setx` 只影响后续新窗口）。

**3. 清理令牌**

```powershell
# 清理当前会话（当前窗口立即失效）
Remove-Item Env:GITEE_TOKEN -ErrorAction SilentlyContinue

# 永久清理（删除用户级环境变量，新窗口起不再自动加载）
[Environment]::SetEnvironmentVariable("GITEE_TOKEN", $null, "User")
```

## 测试

```powershell
.venv\Scripts\python.exe -m pytest -q
```

全量 52 个测试通过（退出码 0）。

## 目录结构

```
main.py               CLI 入口
app/
  config.py           pydantic 配置模型
  loader.py           数据装载（列映射）
  analyzer.py         分析核心（状态/完成比例/分组统计）
  outputs_excel.py    Excel 输出（主题化）
  outputs_chart.py    图表（300dpi PNG）
  llm_writer.py       文案写入（LLM 生成叙述,失败降级兜底）
  outputs_word.py     Word 渲染（docxtpl）
  theme.py            视觉主题集中定义
  logger.py           双输出日志（控制台 + 旋转文件）
  paths.py            输出路径
data/                 月度数据
templates/            Word 通报模板
tests/                单元测试
docs/                 需求与计划文档
```