"""Bank marketing analysis and prediction system."""

__version__ = "0.1.0"

"""Bank marketing analysis and prediction system.

Main entry point for Streamlit application.
"""

from pathlib import Path

import streamlit as st

st.set_page_config(
    page_title="Bank Marketing System",
    page_icon="🏦",
    layout="wide",
    initial_sidebar_state="expanded",
)


def main() -> None:
    """Render the home / landing page.

    Navigation between pages is handled by Streamlit's native multipage
    mechanism (files under ``app/pages/``), so this entry point only shows
    the landing content and a dataset snapshot.
    """
    st.title("🏦 Bank Marketing Analysis & Prediction")

    st.markdown(
        """
        ## Welcome

        This system provides:

        - **Data Analysis**: Explore customer demographics and marketing effectiveness
        - **Prediction**: Predict customer subscription likelihood

        Use the sidebar to navigate between pages.
        """
    )

    data_path = Path("data") / "train.csv"
    if data_path.exists():
        import pandas as pd

        df = pd.read_csv(data_path)
        col1, col2 = st.columns(2)
        col1.metric("Total Records", f"{len(df):,}")
        col2.metric("Columns", len(df.columns))


if __name__ == "__main__":
    main()

# 00 · 项目上下文 〔本项目活记忆 · AI 维护〕

> **作用**:这是项目的"身份档案"。AI 接管项目时先读这里,了解项目目标、技术栈、目录、部署取值。
> **更新时机**:架构、技术栈、目录结构、端口、部署目录、重要约束变化时更新。
> **填写方式**:把 `<...>` 替换成真实内容;用不到的行删掉。

---

## 1. 项目是什么

- **项目名称**: `banksys_szai4`
- **一句话目标**: 基于银行营销数据构建可视化分析与认购预测的 Web 应用
- **使用者/受益者**: 银行营销团队、数据分析师、业务决策者
- **核心功能**:
  - 数据分析交互页面：展示客户特征分布、营销效果分析、数据探索
  - 在线预测系统：基于训练模型,通过点选式表单输入客户特征,预测认购意愿
- **输入/数据**: 银行营销数据集（data/train.csv、data/test.csv），包含 21 个特征（年龄、职业、婚姻、教育、联系方式、经济指标等），目标变量为 subscribe（是否认购定期存款）。**数据进 Git，非敏感教学数据**

## 2. 技术栈

| 层 | 选型 | 理由 |
|---|---|---|
| 语言/运行时 | Python 3.11 | 课程指定版本，生态成熟 |
| Web/API 框架 | Streamlit 1.x | 快速构建数据应用，适合数据分析与模型演示 |
| 测试 | pytest | Python 标准测试框架，配合插件强大 |
| 格式/静态检查 | ruff | 极速 Python linter/formatter，一统格式与 lint |
| 打包/运行 | Docker | 标准容器化，CI/CD 友好 |
| CI/CD | GitHub Actions | 通用、可视化、适合教学与团队协作 |
| 机器学习 | scikit-learn、pandas | 离线训练预测模型、数据处理 |

## 3. 目录地图

```text
banksys_szai4/
├── standards/                 # AI 项目记忆与通用规范
├── app/                       # 应用主目录
│   ├── __init__.py
│   ├── main.py               # Streamlit 主入口
│   ├── pages/                # 多页面结构
│   │   ├── __init__.py
│   │   ├── 01_data_analysis.py    # 数据分析页面
│   │   └── 02_prediction.py        # 预测系统页面
│   ├── models/               # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── data_loader.py         # 数据加载
│   │   ├── predictor.py           # 预测逻辑
│   │   └── visualizer.py         # 可视化逻辑
│   ├── ml/                   # 机器学习模块
│   │   ├── __init__.py
│   │   ├── train.py               # 离线训练脚本
│   │   └── model/                 # 模型产物目录（.gitignore）
│   └── utils/                # 工具函数
│       └── __init__.py
├── tests/                     # 测试目录
│   ├── __init__.py
│   ├── test_data_loader.py
│   ├── test_predictor.py
│   ├── test_visualizer.py
│   └── conftest.py
├── data/                      # 数据目录
│   ├── train.csv              # 训练数据
│   └── test.csv               # 测试数据
├── requirements.txt            # 生产运行依赖
├── requirements-dev.txt        # 本地/CI 检查依赖
├── Dockerfile                  # 容器镜像定义
├── .github/workflows/
│   ├── ci.yml                 # 持续集成
│   └── cd.yml                 # 持续交付
├── .gitignore
├── README.md
└── pyproject.toml              # ruff 配置
```

> 新增目录前先更新本节,避免项目越做越散。

## 4. 质量门槛

| 类型 | 本项目标准 |
|---|---|
| 格式检查 | `ruff format --check .` |
| 静态检查 | `ruff check .` |
| 单元测试 | `pytest` |
| 覆盖率 | 核心逻辑 ≥80%；UI 页面无覆盖率要求 |
| 构建 | `docker build` 成功 |
| 业务/模型指标 | 训练脚本输出模型指标（AUC、准确率等），预测服务响应时间 <1s |

## 5. 不变约束

- 密钥、密码、私钥、Token **绝不写进代码或文档**,只进 GitHub Secrets / 环境变量。
- **数据集进 Git**（教学用公开数据），但 **模型产物不进 Git**（ml/model/ 目录加入 .gitignore）。
- `main` 分支受保护,日常开发必须走 feature 分支 + PR。
- CI 红灯不合并。
- 模型训练是离线操作（本地/CI 执行训练脚本），预测服务加载已训练模型。

## 6. 部署/CI 占位符取值

> `guides/` 和 workflow 里的通用占位符,在本项目里的真实值只写这里。

| 占位符 | 本项目取值 | 说明 |
|---|---|---|
| `<APP>` | `banksys` | 应用名/镜像名/容器名 |
| `<DEPLOY_DIR>` | `/opt/banksys` | 服务器部署目录 |
| `<PORT>` | `8004` | 服务端口（Streamlit 默认 8501，映射到主机 8004） |
| `<PORT_MAX>` | `8010` | 端口回退上限 |
| `<PYVER>` | `3.11` | Python 版本 |
| `<HEALTHCHECK>` | `/_stcore/health` | Streamlit 健康检查端点 |
| `<SSH_USER>` | `root` | 部署用户（按实际环境调整） |
| `<SSH_HOST>` | `<待配置>` | 服务器公网 IP 或域名 |

# 01 · 需求 / 活 PRD 〔本项目活记忆 · AI 维护〕

> **作用**:这是本项目唯一的需求文档。所有新功能、缺陷、技术债都追加到这里,不要另起多个 PRD 文件。
> **更新时机**:每次有新需求、需求变更、验收标准变化时更新。

---

## 1. 需求来源

| 类型 | 来源 | 进入方式 |
|---|---|---|
| 功能需求 Feature | 课程作业要求 | 写成用户故事 |
| 缺陷 Bug | 测试 / 线上日志 / 用户反馈 | 写复现步骤和期望结果 |
| 技术债 Tech Debt | 开发 / Review / CI/CD 故障 | 写影响和修复目标 |

---

## 2. Issue 生命周期

| 阶段 | 状态 | 动作 |
|---|---|---|
| 提出 | Open | 写清场景、目标、验收标准 |
| 排期 | Backlog / Todo | 决定优先级和负责人 |
| 开发 | In Progress | 从 main 开 feature 分支 |
| 评审 | In Review | 提 PR,等待 CI 和 Review |
| 合并 | Done | PR 合并 main,自动关闭 Issue |
| 验收 | Verified | 按验收标准确认 |

**追踪规则**:分支名带 Issue 号,PR 描述写 `closes #<编号>`。

---

## 3. 用户故事模板

```text
### US-<编号> <一句话标题> · 状态: Backlog
作为 <角色>,
我想要 <能力>,
以便 <价值>。

验收标准:
- AC1: Given <前提>,When <动作>,Then <可验证结果>。
- AC2: <补充标准>

技术备注:
- <可选:约束、边界、风险>
```

---

## 4. 需求清单

### US-1 初始化项目工程化与 CI/CD · 状态: Backlog

作为 **项目开发者**,
我想要 项目具备基础工程结构、测试、CI 与 CD,
以便 后续每次开发都能自动检查并自动部署。

验收标准:
- AC1: 从 `main` 开 feature 分支完成初始化,不直接 push main。
- AC2: PR 触发 CI,至少包含格式检查(ruff)、静态检查(ruff)、单元测试(pytest)、构建检查(docker build)。
- AC3: CI 全绿后合并 main。
- AC4: 合并 main 自动触发 CD,部署后健康检查通过(端口 8004)。
- AC5: 完成后更新 `standards/PROGRESS.md`。

技术备注:
- 首个 US 必须完整演示六步交付流程。
- 建仓后必须提示配置 GitHub Secrets (SSH_PRIVATE_KEY/SSH_HOST/SSH_USER)。

---

### US-2 数据加载与预处理模块 · 状态: Backlog

作为 **开发者**,
我想要 一个可复用的数据加载模块,
以便 支持数据分析页面和模型训练的数据需求。

验收标准:
- AC1: Given 数据文件存在,When 调用 `load_train_data()` 和 `load_test_data()`,Then 返回 pandas DataFrame。
- AC2: Given 原始数据,When 加载数据,Then 列包含 21 个特征(id/age/job/.../subscribe)。
- AC3: Given 数据加载,When 访问数据,Then 能正确处理中英文列名、缺失值。
- AC4: Given 数据加载模块,When 编写单元测试,Then 覆盖正常加载、文件不存在、空文件场景。
- AC5: Given 数据目录,When 部署,Then data/ 目录在镜像内正确挂载。

技术备注:
- 数据文件是 UTF-8 编码的 CSV。
- 需要处理可能的缺失值标记为 'unknown'/'nonexistent'。

---

### US-3 数据分析交互页面 · 状态: Backlog

作为 **业务分析师**,
我想要 通过可视化界面探索银行营销数据,
以便 快速理解客户特征分布和营销效果。

验收标准:
- AC1: Given 访问应用首页或导航到"数据分析",When 页面加载,Then 显示数据概览(总记录数、认购率)。
- AC2: Given 数据分析页面,When 选择分析维度,Then 展示对应图表(年龄分布饼图、职业认购率柱状图、教育水平热力图等)。
- AC3: Given 数据分析页面,When 进行交互操作(选择/筛选),Then 图表实时更新。
- AC4: Given 页面存在,When 访问非本地环境,Then 页面在 Docker 容器中正常渲染。
- AC5: Given 页面功能,When 编写测试,Then 核心可视化逻辑有单元测试覆盖。

技术备注:
- 使用 Streamlit 的 st.metric/st.pyplot/st.plotly_chart 等组件。
- 图表包括但不限于：年龄分布、职业分布、婚姻状况、教育水平、认购率分析。

---

### US-4 模型训练脚本与流程 · 状态: Backlog

作为 **开发者**,
我想要 一个离线训练脚本,
以便 从历史数据中学习认购预测模型。

验收标准:
- AC1: Given 训练数据,When 执行 `python -m app.ml.train`,Then 在 ml/model/ 目录输出模型文件(model.pkl)。
- AC2: Given 训练过程,When 训练完成,Then 打印关键指标(AUC、准确率、分类报告)到日志。
- AC3: Given 模型文件,When 模型已存在,Then 训练脚本可选择覆盖或跳过(命令行参数)。
- AC4: Given 训练脚本,When 在 CI 环境运行,Then 训练可复现(固定随机种子)。
- AC5: Given 模型产物,When 提交代码,Then ml/model/ 在 .gitignore 中,不进 Git。

技术备注:
- 使用 scikit-learn(LogisticRegression/RandomForest/XGBoost 任选其一)。
- 需要处理类别特征编码(OneHot/LabelEncoding)。
- 固定 random_state 保证可复现性。

---

### US-5 预测服务核心逻辑 · 状态: Backlog

作为 **系统**,
我想要 一个预测服务模块,
以便 根据输入特征返回认购概率。

验收标准:
- AC1: Given 模型文件存在,When 调用 `predict(features_dict)`,Then 返回预测结果(是否认购、概率)。
- AC2: Given 特征输入,When 输入合法特征,Then 正确编码并调用模型。
- AC3: Given 特征输入,When 输入缺失或非法值,Then 返回友好错误或默认处理。
- AC4: Given 预测模块,When 编写测试,Then 覆盖正常预测、模型文件缺失、非法输入场景。
- AC5: Given 预测服务,When 响应请求,Then 单次预测响应时间 <1s。

技术备注:
- 特征编码必须与训练时一致(建议保存 encoder)。
- 返回格式：{"subscribe": bool, "probability": float, "confidence": str}。

---

### US-6 在线预测页面 · 状态: Backlog

作为 **营销人员**,
我想要 通过点选式表单输入客户特征,
以便 快速预测该客户的认购意愿。

验收标准:
- AC1: Given 访问"预测系统"页面,When 页面加载,Then 显示点选式表单(年龄段、职业、婚姻、教育等选择器)。
- AC2: Given 表单填写完成,When 点击"预测"按钮,Then 页面显示预测结果(是否认购、概率、置信度)。
- AC3: Given 预测结果,When 显示结果,Then 提供可视化进度条或仪表盘展示概率。
- AC4: Given 表单,When 用户操作,Then 表单支持重置、重新预测。
- AC5: Given 预测页面,When 在生产环境,Then 预测功能在 Docker 容器中正常工作。

技术备注:
- 使用 Streamlit 的 st.selectbox/st.slider/st.button 组件。
- 特征选项参考训练数据中的唯一值分布。
- 结果展示包括：预测标签、概率进度条、建议文案。

---

### US-7 健康检查与监控 · 状态: Backlog

作为 **运维/CD 流水线**,
我想要 一个健康检查端点,
以便 验证服务是否正常运行。

验收标准:
- AC1: Given 服务运行,When 访问 `/_stcore/health`,Then 返回 200 状态码。
- AC2: Given 模型加载,When 服务启动,Then 模型文件成功加载,预测功能可用。
- AC3: Given 部署脚本,When CD 执行,Then 健康检查失败时 CD 流水线报错。

技术备注:
- Streamlit 默认提供 `/_stcore/health` 端点。
- 可选：添加自定义监控指标(请求计数、模型版本)。

---

### US-8 测试覆盖与质量门禁 · 状态: Backlog

作为 **CI 流水线**,
我想要 完整的测试覆盖,
以便 保证代码质量。

验收标准:
- AC1: Given 核心业务逻辑,When 运行 `pytest --cov`,Then 覆盖率 ≥80%。
- AC2: Given CI 触发,When PR 提交,Then CI 执行格式检查、静态检查、单元测试、构建。
- AC3: Given 任意检查失败,When CI 红灯,Then PR 不能合并。
- AC4: Given 本地开发,When 提交前,Then 开发者本地执行自检并全绿。

---

## 5. 非功能需求

- **安全**:密钥只进 Secrets,不进 Git。
- **可维护**:一需求一小 PR,避免大爆炸式提交。
- **可测试**:核心逻辑必须有单元测试。
- **可部署**:部署后必须有健康检查或等价验证。
- **性能**:单次预测响应 <1s,页面首屏加载 <3s。

# 02 · 代码标准

> **目标**:让人和 AI 写出的代码风格一致、可读、可测、可维护。CI 会自动检查其中可机检的部分。

---

## 1. 格式与静态检查

- Python 项目推荐:`ruff format .` + `ruff check .`。
- 其他语言按项目技术栈替换为对应工具,例如 ESLint/Prettier、Checkstyle、gofmt。
- 行宽默认 100;缩进、import 分组、命名风格由工具强制。
- 提交前本地必须通过格式与 lint;CI 会再卡一道。

## 2. 命名

| 对象 | 推荐规则 | 示例 |
|---|---|---|
| 变量/函数 | `snake_case` | `load_config` |
| 类 | `PascalCase` | `UserService` |
| 常量 | `UPPER_SNAKE` | `DEFAULT_PORT` |
| 私有实现 | 前缀 `_` | `_parse_row` |

命名必须表达意图。禁止 `process2`、`new_func`、`tmp_final` 这类无法审查的名字。

## 3. 函数与模块

- 一个函数只做一件事;超过约 40 行优先拆分。
- 参数过多时使用配置对象/数据类。
- 业务逻辑与 I/O 分离,核心逻辑优先写成纯函数,方便测试。
- 新增目录或模块前,先确认能落进 `00-project-context.md` 的目录地图。

## 4. 注释

- 不写废话注释,例如 `# 调用函数` 配 `call_func()`。
- 注释只解释“为什么”和“权衡”,不重复“代码做了什么”。
- 复杂业务规则、部署坑、兼容性原因必须写清楚。

## 5. 配置与密钥

- 非敏感配置可进 Git,例如 `config.yaml`、`.env.example`。
- 密钥、密码、Token、私钥绝不进 Git,只放 GitHub Secrets / 环境变量。
- 代码读取密钥时使用环境变量,并在 README 写清变量名,不写真实值。

## 6. 错误处理

- 禁止裸 `except: pass`。
- 外部输入必须校验,错误信息要能帮助定位。
- 部署脚本必须失败即停;不能让前一步失败后继续执行后续危险动作。

## 7. 提交前自检

```text
[ ] 格式检查通过
[ ] 静态检查通过
[ ] 新增逻辑有测试
[ ] 没有硬编码密钥
[ ] 没有调试 print / 死代码 / 大段注释代码
[ ] 目录结构仍符合 00-project-context.md
```

# 03 · 测试标准

> **目标**:定义“什么叫测够了”。开发自测是进入 CI 前的第一道防线。

---

## 1. 测试分层

```text
        /\        E2E 测试:少、慢、贵,覆盖真实用户路径
       /  \
      /----\      集成测试:测试模块/服务边界
     /------\
    /        \    单元测试:多、快、稳定,开发者必写
   /__________\
```

- 单元测试优先覆盖核心逻辑。
- 集成测试覆盖接口、数据库、外部服务边界。
- E2E 测试只覆盖关键路径,不要用它替代单元测试。

## 2. 用例写法

推荐 AAA / Given-When-Then:

```python
def test_health_returns_ok():
    # Arrange
    client = app.test_client()

    # Act
    resp = client.get("/health")

    # Assert
    assert resp.status_code == 200
    assert resp.get_json()["status"] == "ok"
```

## 3. 好测试的 5 条铁律

1. 一个用例只测一件事。
2. 覆盖正常值、边界值、异常值。
3. 可重复、无外部网络依赖;有随机性必须固定种子。
4. 测试名能表达场景和预期。
5. 必须有真实断言,禁止 `assert result is not None` 凑数。

## 4. 覆盖率

- 默认建议核心代码覆盖率 ≥ 80%。
- 覆盖率不是目的,关键分支必须被覆盖。
- 如果项目不适合覆盖率门槛,必须在 `00-project-context.md` 说明原因。

## 5. 项目特有质量门禁

不同项目可追加不同质量门禁:

| 项目类型 | 可选门禁示例 |
|---|---|
| Web/API | 健康检查、接口状态码、契约测试 |
| 数据/ML | 数据校验、模型指标(AUC/F1/RMSE 等) |
| 前端 | 组件测试、构建产物检查、可访问性检查 |
| CLI/脚本 | 命令退出码、输入输出快照 |

> 项目特有门禁写进 `00-project-context.md` 第 4 节,再写入 CI。

## 6. flaky test 纪律

- 偶发失败必须根治,不能靠“重跑一次”掩盖。
- 典型原因:时间依赖、随机数、测试顺序依赖、外部网络、共享状态未清理。

## 7. 本地测试由谁执行

默认规则:

| 环境 | 谁执行本地测试 | 怎么做 |
|---|---|---|
| AI 工具有终端权限(Cursor / Claude Code 等) | **AI 执行** | AI 自己运行格式检查、lint、pytest、构建等命令,读取日志,修复问题,把结果写回 `PROGRESS.md` |
| AI 没有终端权限(纯聊天网页) | **学生执行** | 学生复制 AI 给出的命令到终端运行,把完整日志贴回 AI |
| 涉及账号/权限/审批/Secrets | **学生确认** | AI 可指导,但不能代替人输入密码、私钥、审批生产发布 |

AI 能执行命令时,不能只告诉学生“你去运行 pytest”。正确做法是:

```text
AI 写代码 → AI 运行本地自检 → AI 根据日志修复 → AI 再运行 → 全绿后提交/PR → AI 记录结果
```

每次本地自检至少记录:

- 执行的命令。
- 是否通过。
- 失败时的关键错误。
- 修复方式。
- 最终通过结果。

# 04 · Git 工作流与 PR/Review 标准

> **目标**:定义代码如何从本地安全进入 `main`,并触发 CI/CD。课堂第一项功能必须完整演示本文件第 2 节。

---

## 1. 分支模型:GitHub Flow

```text
main 受保护,永远可部署
 ├─ feature/<issue>-<desc>   新功能
 ├─ fix/<issue>-<desc>       普通缺陷
 ├─ docs/<issue>-<desc>      文档
 └─ chore/<issue>-<desc>     杂务/依赖/配置
```

- 只有一条长期分支:`main`。
- 日常开发必须从 `main` 开短分支,不能直接 push `main`。
- feature 分支寿命建议 ≤ 2-3 天。
- 分支命名:`<类型>/<issue号>-<英文短描述>`,例如 `feature/1-hello-api`。

---

## 2. 课堂必演示:从分支到 CD 的完整命令

> 这段是学生必须亲手跑通的一条链。不要省略 PR,不要直接 push main。

```bash
# 1. 确认在 main,并更新主干
git switch main
git pull

# 2. 从 main 开功能分支
git switch -c feature/1-first-feature

# 3. 写代码 + 写测试后,本地自检
ruff format --check .
ruff check .
pytest

# 4. 提交
git status
git add .
git commit -m "feat: add first feature"

# 5. 推送 feature 分支
git push -u origin feature/1-first-feature

# 6. 创建 PR(AI 做到这里为止)
gh pr create --base main --head feature/1-first-feature --title "feat: add first feature" --body "closes #1"

# 7. 查看 CI(AI 汇报 CI 状态后停下,等人类审核)
gh run list --limit 5
gh run watch

# 8. ★ 合并由人类执行 ★ —— 人工 Review 通过后,由人在网页点 "Merge",或人工运行:
#    gh pr merge <PR号> --merge      # 默认保留分支,不加 --delete-branch
#    AI 不得自行合并未获批准的 PR。

# 9. 合并 main 后会触发 CD,查看部署流水线
gh run list --limit 5
```

> 如果课堂暂时没有开启分支保护,也要按这个流程演示 PR。分支保护是“强制执行”,PR 流程是“正确习惯”。

> **合并是人类的动作,不是 AI 的动作。** AI 在第 6/7 步发起 PR、汇报 CI 后必须停下;
> **只有人工 Review 通过,由人合并**,才触发 CD。AI 绝不替人按下 Merge。

> **默认保留分支**(不加 `--delete-branch`),除非人类明确要求删除已合并分支。

> **PR 必须用你本人 GitHub 账号发起**(`gh auth login` 登录的就是你本人),不要借他人账号代提。

> **⚠️ 建仓后第一件事:配置 Secrets,否则 CD 必失败。**
> 新仓库创建后(CD 第一次跑之前)立刻去
> `GitHub → Settings → Secrets and variables → Actions → New repository secret`
> 配好 `SSH_PRIVATE_KEY` / `SSH_HOST` / `SSH_USER`(详见 `05-cicd-standards.md` 第 5 节)。
> 没有数据库等部署目标时可只配 SSH 三件套。配置时机:**在合并到 main 触发 CD 之前**。

---

## 3. 认证不要混

| 动作 | 认证方式 | 说明 |
|---|---|---|
| `git push` / `git clone` | SSH 公钥或 HTTPS 凭证 | 负责搬代码 |
| `gh pr create` / `gh run list` | GitHub CLI 登录 | 负责调 GitHub API |
| CD SSH 到服务器 | GitHub Secrets 里的部署私钥 | 由 Actions runner 自动使用 |

如果 SSH 22 端口卡住,可使用 GitHub SSH 443:

```bash
ssh -T -p 443 git@ssh.github.com
git remote set-url origin ssh://git@ssh.github.com:443/<账号>/<仓库>.git
git push
```

---

## 4. 提交信息规范

采用 Conventional Commits:

| 前缀 | 含义 |
|---|---|
| `feat:` | 新功能 |
| `fix:` | 修 bug |
| `docs:` | 文档 |
| `test:` | 测试 |
| `refactor:` | 重构 |
| `ci:` | CI/CD |
| `build:` | 构建/依赖 |
| `chore:` | 杂务 |

一个 commit 只做一件事。

---

## 5. PR 通过三道闸

| 闸 | 内容 | 不通过怎么办 |
|---|---|---|
| 机器闸 | CI 全绿 | 修代码/测试/配置 |
| 人工闸 | 至少 1 人 Review | 修改并回复评论 |
| 策略闸 | 无冲突、分支保护通过 | 同步 main / 解冲突 |

PR 描述必须写:

```text
## What
这个 PR 做了什么

## Why
为什么需要

## Test
- [ ] 本地检查通过
- [ ] CI 通过

closes #<issue号>
```

---

## 6. 冲突处理

```bash
git switch main
git pull
git switch <你的分支>
git rebase main

# 如果有冲突:手动修改文件,删掉 <<<<<<< ======= >>>>>>> 标记
git add <冲突文件>
git rebase --continue

# rebase 后推送
git push --force-with-lease
```

冲突处理后必须重新跑测试。

# 05 · CI/CD 标准

> **目标**:定义最小可复现 CI/CD。CI 管“代码是否可靠”,CD 管“可靠代码如何自动上线”。

---

## 1. CI 与 CD

| 名称 | 做什么 | 典型触发 |
|---|---|---|
| CI 持续集成 | 格式、lint、测试、覆盖率、构建 | PR / push |
| CD 持续交付 | 构建可部署产物,部署前可人工审批 | main / tag |
| CD 持续部署 | 合并 main 后自动部署上线 | main |

课堂简版采用:

```text
PR → CI 全绿 → 合并 main → CD 自动部署到服务器 → 健康检查
```

---

## 2. 最小 CI 门禁

| 关卡 | 推荐命令 | 本地必跑 | CI 必跑 |
|---|---|:---:|:---:|
| 格式检查 | `ruff format --check .` 或等价工具 | ✅ | ✅ |
| 静态检查 | `ruff check .` 或等价工具 | ✅ | ✅ |
| 单元测试 | `pytest` 或等价工具 | ✅ | ✅ |
| 覆盖率 | `pytest --cov --cov-fail-under=80` | ✅ | ✅ |
| 项目特有门禁 | AUC/F1/接口契约/前端构建等 | ✅ | ✅ |
| 构建 | `docker build ...` 或项目构建命令 | ❌ 不要求 | ✅ |

CI 红灯时禁止合并。不要靠重跑掩盖问题。

> **本地不强制装 Docker**:很多学员/开发机没有 Docker,本地装它只会增加复杂度。
> 约定 **本地只跑前几项门禁,`docker build` 交给 CI(云端 runner 自带 Docker)与服务器(CD)**。
> 这样本地零 Docker 负担,镜像构建仍有 CI 兜底。是否要本地构建,**按机器情况决定或先问开发者**。

---

## 3. 最小 CD 标准

CD 必须满足:

- 由 GitHub Actions runner 自动触发,不是人手动 SSH。
- 只引用 GitHub Secrets,不硬编码密钥。
- 部署脚本可重复执行。
- 部署后必须健康检查。
- 失败时 Actions 红灯,不能假成功。

推荐触发:

```yaml
on:
  push:
    branches: [ main ]
```

---

## 4. 依赖与镜像构建标准

真实教学环境常见失败:服务器 `docker build` 时从 PyPI / npm / Docker Hub 下载依赖很慢或超时。

通用标准:

| 标准 | 做法 |
|---|---|
| 运行依赖与开发依赖拆分 | 生产镜像只安装运行依赖;测试/lint 工具只在 CI 安装 |
| 镜像源可配置 | Dockerfile 支持镜像源参数,国内服务器可使用国内源 |
| 构建失败即停 | 远程部署脚本第一行 `set -e` |
| 健康检查 | 最后执行 `curl -fsS http://localhost:<PORT>/<HEALTHCHECK>` |
| 可选预热 | 课前在服务器预拉基础镜像,减少等待 |

Python 项目推荐:

```text
requirements.txt      # 生产运行依赖
requirements-dev.txt  # CI/本地检查依赖
```

Dockerfile 推荐:

```dockerfile
ARG PIP_INDEX_URL=https://pypi.org/simple
RUN pip install --no-cache-dir --timeout 120 -i "${PIP_INDEX_URL}" -r requirements.txt
```

远程部署脚本推荐(含幂等替换 + 端口自动回退):

```bash
set -e
docker build --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple -t <APP>:latest .

# 端口:容器内端口固定;主机端口优先 <PORT>,被占用就在预留区间自动找空闲端口。
port_in_use() {
  ss -ltnH 2>/dev/null | grep -q ":$1 " && return 0
  docker ps --format "{{.Ports}}" 2>/dev/null | grep -q ":$1->" && return 0
  return 1
}
PORT=""
for p in $(seq <PORT> <PORT_MAX>); do
  if ! port_in_use "$p"; then PORT="$p"; break; fi
done
[ -z "$PORT" ] && { echo "预留端口区间已全部占用,部署中止"; exit 1; }
echo ">> 部署到主机端口 $PORT"

docker rm -f <APP> 2>/dev/null || true   # 一步停删自身旧容器,幂等可重跑
docker run -d --name <APP> --restart unless-stopped -p ${PORT}:<容器内端口> <APP>:latest
sleep 3
curl -fsS "http://localhost:${PORT}/<HEALTHCHECK>"
echo ">> 部署成功:http://<SSH_HOST>:${PORT}/<HEALTHCHECK>"
```

> **端口标准**:容器内端口固定,**主机端口可回退**(预留如 `<PORT>`-`<PORT_MAX>` 一段)。
> 起容器用 `docker rm -f <APP>` 一步停删自身旧容器保证幂等;**不要**盲目删除占用端口的他人容器。
> 防火墙/安全组要放行整段预留端口;最终落在哪个端口由 CD 日志打印。
> 踩坑:`docker run` 报 `port is already allocated`(exit 125)就是主机端口被占用所致。

---

## 5. Secrets 标准

常用 SSH 部署需要三个 GitHub Actions Secrets:

| Secret | 含义 |
|---|---|
| `SSH_PRIVATE_KEY` | Actions runner 用来登录服务器的私钥全文 |
| `SSH_HOST` | 服务器公网 IP 或域名 |
| `SSH_USER` | 服务器登录用户,如 `root` 或 `deploy` |

规则:

- Secret 名大小写必须一致。
- 私钥必须保留 `BEGIN/END` 和换行。
- Secrets 必须在 CD run 开始前配置好;配置后旧 run 可能需要 rerun。

---

## 6. 本地环境准备(一次性)

环境怎么建,**写进标准、可复现**。优先级:`uv` → `uv` 不行用 `conda` → 再不行用系统 `venv`。
本课程学员更熟 `conda`,默认用 conda:

```bash
# 1) 建并激活环境(示例环境名 envproj,Python 版本按项目 00 文档)
conda create -y -n envproj python=3.11
conda activate envproj

# 2) 装依赖(国内用清华源更快)
pip install -r requirements.txt -r requirements-dev.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

> **坑:`CondaToSNonInteractiveError`(新版 conda 默认渠道未接受服务条款)**。
> 解决,对三个渠道各执行一次:
> ```bash
> conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
> conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
> conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/msys2
> ```

---

## 7. 排错顺序

| 现象 | 优先检查 |
|---|---|
| `conda create` 报 ToS 错误 | 执行上面的 `conda tos accept`(main/r/msys2) |
| Windows 控制台 `UnicodeEncodeError('gbk' ... \u25b6)` | 日志/打印含特殊符号;改用纯 ASCII,或 `set PYTHONIOENCODING=utf-8` / `chcp 65001`。注意 pytest 会捕获输出掩盖此坑,必须真跑一次脚本 |
| CI 红:`FileNotFoundError` 找不到数据 | 数据被 `.gitignore` 排除,干净 runner 上没有。公开教学数据可入库;敏感数据则在 CI 里下载/造样本 |
| `docker run` 报 `port is already allocated`(exit 125) | 主机端口被占用;容器内端口固定、主机端口在预留区间自动回退(见第 4 节);`docker rm -f <APP>` 幂等替换自身 |
| `git push` 卡住/`Recv failure`/`Connection reset` | SSH 22 被拦可切 443;HTTPS 偶发抖动则重试几次 |
| Actions 读不到变量 | Secret 名是否拼错、是否在正确仓库 |
| SSH 登录失败 | 私钥/公钥是否匹配、`authorized_keys`、用户权限 |
| rsync 成功但 docker build 失败 | 依赖下载、镜像源、Dockerfile |
| 服务器本机 curl 通,外网打不开 | 安全组/防火墙是否放行端口(含回退端口段) |
| CD 日志二次报错 | 部署脚本是否缺 `set -e` |
| CD `Run Command Timeout`,docker build 卡在 `apt-get` | 国内服务器访问 deb.debian.org 极慢;**避免在 Dockerfile 里 apt 装包**,能用基础镜像已有运行时(如 python)替代就别 apt;非装不可则换国内 apt 源 |

---

## 8. 标准总结

1. CI 红灯不合并。
2. CD 必须由 runner 自动触发,不是人手动 SSH。
3. 密钥进 Secrets,脚本进 Git,环境手动配一次。
4. 生产镜像只放运行依赖,开发工具留在 CI;**本地不强制装 Docker**。
5. 每次真实故障必须写回 `PROGRESS.md` 和本标准。

# 06 · AI 协作协议

> **目标**:让任意 AI 工具都按同一套上下文、规则和闭环工作,避免换工具/换会话就丢上下文。
> **核心**:下面第 1 节的「六步交付流程 + 确认门」是 AI 必须严格遵守的主干,**每到一个确认门必须停下,向人类汇报并等待确认,不得自行越过**。

---

## 1. 六步交付流程(必须逐步确认)★ 主干

AI 驱动开发分为固定六步。**每一步都有一个「✋ 确认门」**:AI 完成该步动作后,先汇报结果,等人类确认/操作后才进入下一步。绝不一口气从头跑到尾。

```text
① 建仓+配Secrets → ② 开feature分支 → ③ 本地模块化开发(逐模块汇报)
     → ④ 本地CI自检(AI执行) → ⑤ 触发PR(CI在PR复检) → ⑥ 人工审核→合并→CD自动部署
   ✋确认1            ✋确认2          ✋确认3(每个模块)
                    ✋确认4           ✋确认5            ✋确认6(审核+部署结果)
```

### 第①步 · 建仓 + 配 Secrets

- **AI 动作**:用 `gh` 创建 GitHub 仓库;`main` 只放最小引导提交(`.gitignore`/占位 README),**不在 main 上做真实开发**。
- **✋ 确认门 1**:AI 报出仓库地址后,**必须提示人类去配置 GitHub Secrets**(新仓库默认为空,不配 CD 必失败):
  - `SSH_PRIVATE_KEY` / `SSH_HOST` / `SSH_USER`(见 `05` 第 5 节)。
  - AI 停下,**等人类确认「Secrets 已配置」**再继续(可用 `gh secret list` 核对)。

### 第②步 · 开 feature 分支

- **AI 动作**:从最新 `main` 切出 `feature/<issue>-<desc>` 分支(类型见 `04`);**严禁直接在 main 上开发**。
- **✋ 确认门 2**:报出分支名,确认后进入开发。

### 第③步 · 本地模块化开发 + 进度汇报

- **AI 动作**:按 `00` 目录地图**一个模块一个模块**实现,每个模块同步写测试;每完成一个模块:
  - 更新 `PROGRESS.md`(已完成/下一步)。
  - 向人类**汇报该模块进度**(做了什么、关键决定、是否有坑)。
- **✋ 确认门 3(每个模块)**:每个模块完成后汇报并确认,再做下一个模块。避免一次性写完全部再回头返工。

### 第④步 · 本地 CI 自检(由 AI 执行)

- **AI 动作**:到「需要 CI」的节点,**AI 主动确认并亲自执行**本地门禁(具备终端权限时):
  - `ruff format --check .` + `ruff check .`
  - `pytest --cov --cov-fail-under=80`
  - 项目特有门禁(如模型 `--check-auc`)
  - **本地不强制 `docker build`**(交给 CI;见 `05` 第 2 节)。
- **✋ 确认门 4**:汇报自检结果(覆盖率、指标);**全绿才进入下一步**,红则就地修复后重跑。

### 第⑤步 · 触发 PR(CI 在 PR 上复检)

- **AI 动作**:`git push` 分支后,**AI 主动 `gh pr create`** 发起 PR(用本人账号);PR 事件触发 CI 在云端再跑一遍同样门禁 + `docker build`。
- **✋ 确认门 5**:报出 PR 链接与 CI 状态(`gh run watch`);CI 绿才推进到审核。

### 第⑥步 · 人工审核 → 合并(人类) → CD 自动部署

- **✋ AI 在此硬停**:AI 发起 PR、汇报 CI 绿之后**就停下**,**不得自己合并**。合并是人类的动作。
- **人类动作**:**PR 必须由人工 Review**;审核通过后**由人类在网页点 Merge 或人工运行 `gh pr merge`**。
- **分支默认保留**:合并不加 `--delete-branch`,除非人类明确要求删除。
- **AI 动作(合并发生后)**:CD 自动触发(SSH→同步→构建→运行→健康检查;端口自愈见 `05`);AI 盯流水线。
- **✋ 确认门 6**:汇报部署结果——**最终落地端口、`/health` 结果、访问地址**;失败则读日志定位根因,修复后回到第②步走一个新分支/PR。

> 一句话:**建仓我做、Secrets 你配;分支我开(默认保留);模块我逐个写并汇报;本地 CI 我跑;PR 我发;
> 审核与合并都由你做,我绝不替你按 Merge;合并后 CD 自动跑,我盯结果。**

---

## 2. AI 开工前必须读

每次新会话,AI 必须按顺序读:

1. `standards/README.md`
2. `standards/00-project-context.md`
3. `standards/01-requirements.md`
4. `standards/PROGRESS.md`
5. `standards/02`~`06`

然后向人类复述:

```text
我理解当前项目是:...
当前阶段是(对应六步流程第几步):...
下一步应该做:...
我将遵守的关键约束是:...
```

---

## 3. 人给 AI 的标准开场 prompt

```prompt
请先读取 standards/README.md,并按顺序读取 00/01/PROGRESS 与 02~06。
读完后先复述你对项目、当前进度(对应 06 的六步流程第几步)、下一步的理解。
然后严格按 06 的「六步交付流程 + 确认门」推进:
- 每到一个确认门必须停下汇报并等我确认,不要一口气跑完。
- 建仓后提示我配置 Secrets;从 main 开 feature 分支,不直接改 main。
- 逐模块开发并汇报;本地 CI 由你执行(本地不强制 docker);CI 绿后你主动发 PR。
- 发完 PR 你就停下,**不要自己合并**;PR 由我审核并由我合并,合并后 CD 自动跑,你盯结果并汇报端口与健康检查。
- 分支默认保留,不要加 --delete-branch,除非我明确要求删。
```

---

## 4. AI 写代码边界

AI 可以:

- 新增/修改代码、测试、CI/CD 配置。
- 在具备终端权限时运行本地测试、lint、构建命令,并根据日志修复。
- 创建仓库、开分支、发起 PR(用本人账号)。
- 更新 `00/01/PROGRESS`;根据真实故障更新 `02~06`(须说明原因)。

AI 不可以:

- 硬编码密钥。
- 绕过 CI 或跳过测试。
- 明明能执行命令,却只让学生手动跑本地测试。
- 为了“看起来通过”删除测试或降低门槛。
- **越过任何确认门**(尤其:未提示配 Secrets 就推进 CD;未经确认大规模重构)。
- **自行合并任何 PR**——合并是人类的专属动作,AI 只发起 PR 并汇报,绝不替人按 Merge。
- 合并时默认 `--delete-branch` 删分支——**默认保留分支**,除非人类明确要求删除。
- 直接把项目特有内容写进通用规范,除非它已沉淀为可复用规则。

---

## 5. 故障反哺铁律

CI/CD 一旦真实跑出问题,修完代码还不算结束,必须同步完成三件事:

1. 写回 `PROGRESS.md`:现象、根因、修复、验证结果。
2. 如是通用规则,写进 `02~06` 对应标准。
3. 更新学生会照着操作的 README/课件/脚本。

判断标准:

```text
换一个学生、换一个 AI 工具,只读 standards + README,是否能避开这次坑并复现?
```

如果不能,说明闭环未完成。

---

## 6. 会话结束 prompt

```prompt
本次会话结束。请更新 standards/PROGRESS.md:
1. 当前状态(对应六步流程第几步)
2. 已完成事项
3. 下一步 TODO
4. 新增 ADR
5. 新增 GOTCHAS
保持时间倒序、简洁、可接力。
```

# PROGRESS · banksys_szai4 〔本项目活记忆 · 状态机〕

> **作用**:这是项目的"存档点"。任意 AI、任意重启会话,读它即可知道当前做到哪、下一步做什么、踩过什么坑。
> **更新时机**:每完成一个有意义步骤、每次会话结束前。
> **格式要求**:时间倒序,最新在上;短、准、可接力。

---

## 当前状态 (最后更新: 2026-06-07 · by AI)

- **阶段**: `PR #4 已合并；首次 CD 因 apt 超时失败（坑-007），已修 Dockerfile，准备发修复 PR`
- **开发策略**: 按用户要求 US-3~US-6 全部本地开发并测试完成后，再统一进 CI/CD（一条大分支一个 PR）
- **上一步完成**: 定位 CD 失败根因（apt-get 装 curl 在国内服务器超时），改为 Python 健康检查移除 apt
- **下一步**: fix/cd-apt-timeout 分支 → 发 PR → 你合并 → CD 重跑 → 验证端口 8004 健康检查
- **PR**: #4 已合并；修复 PR 待建
- **阻塞项**: 无（端口已固定 8004，见坑-005）

---

## 待办清单 (TODO,按优先级)

### 第一批：初始化项目工程化与 CI/CD（US-1）✅ 已完成
- [x] ① 建仓 + 配 Secrets
- [x] ② 开 feature 分支
- [x] ③ 本地模块化开发（8 个模块）
- [x] ④ 本地 CI 自检
- [x] ⑤ 触发 PR（PR #1）
- [x] ⑥ 人工审核 → 合并 → CD 自动部署（端口 8005）

### 第二批：数据加载与预处理模块（US-2）✅ 已完成
- [x] 实现 app/models/data_loader.py（load_train_data、load_test_data、辅助函数）
- [x] 编写 test_data_loader.py（25 个测试，100% 覆盖率）
- [x] 本地自检 + 提 PR（PR #3）
- [x] 修复 ruff 版本锁定问题
- [x] 修复 CD git ownership 问题
- [x] CD 部署成功（端口 8006）

### 第三批：数据分析交互页面（US-3）✅ 已完成（本地）
- [x] 实现数据可视化逻辑（app/models/visualizer.py，10 函数，100% 覆盖）
- [x] 实现 app/pages/01_data_analysis.py（概览/饼图/类别分析/年龄分析/数值分布，交互式）
- [x] 精简 main.py 为首页，改用 Streamlit 原生多页导航
- [x] 编写 test_visualizer.py（24 个测试）+ 真实数据冒烟验证
- [x] 顺手清理 data_loader.py 死代码、对齐 .gitignore 模型路径
- [ ] 提 PR（按策略推迟到 US-6 完成后统一进 CI/CD）

### 第四批：模型训练脚本（US-4）✅ 已完成（本地）
- [x] 实现 app/ml/train.py（ColumnTransformer+OneHot+RandomForest Pipeline，固定种子）
- [x] app/ml/model/ 已在 .gitignore（git check-ignore 验证通过）
- [x] 本地真跑训练：AUC 0.8964 / 准确率 0.8742，产出 model.pkl
- [x] 编写 test_train.py（10 个测试），CLI 支持 --overwrite/--check-auc
- [ ] 提 PR（推迟到统一进 CI/CD）

### 第五批：预测服务核心逻辑（US-5）✅ 已完成（本地）
- [x] 实现 app/models/predictor.py（load_model 带 lru_cache，predict 返回 subscribe/probability/confidence）
- [x] 编写 test_predictor.py（16 个测试，100% 覆盖）：正常/模型缺失/缺失特征/非法数值/未知类别/响应时间
- [x] 真实模型端到端验证：高意愿 0.90/high，低意愿 0.35；预热后单次 <1s
- [ ] 提 PR（推迟到统一进 CI/CD）

### 第六批：在线预测页面（US-6）✅ 已完成（本地）
- [x] 实现 app/pages/02_prediction.py（点选式表单，类别选项从数据动态取值）
- [x] 集成 predictor 模块（结果含标签/概率进度条/置信度/建议文案，含模型缺失友好提示）
- [x] 本地启动 Streamlit 验证：/_stcore/health=200、data_analysis/prediction 页面均 200
- [ ] 提 PR（推迟到统一进 CI/CD）

### 第七批：测试覆盖与质量门禁完善（US-7 & US-8）
- [x] 核心逻辑覆盖率：data_loader/visualizer/predictor 均 100%（UI 页面按规范不计）
- [x] 注册 pytest unit marker，消除测试告警
- [x] 修复 Dockerfile：构建时训练模型 + 装 curl + 健康检查端点 /_stcore/health（坑-006）
- [x] 推分支 + 发 PR（#4），CI 复检全绿（含 docker build）
- [ ] 人工审核 → 合并 → CD 部署 → 验证端口 8004 健康检查

---

## 关键决策记录 (ADR)

| 日期 | 决策 | 理由 |
|---|---|---|
| 2025-06-07 | 选择 Streamlit 作为 Web 框架 | 课程要求；快速构建数据应用；适合数据分析与模型演示场景 |
| 2025-06-07 | 模型训练离线，预测在线 | 训练是重操作不适合实时请求；预测是轻操作需要快速响应 |
| 2025-06-07 | 数据集进 Git，模型产物不进 Git | 教学用公开数据，方便复现；模型产物二进制大文件，不应进版本控制 |
| 2025-06-07 | 端口选择 8004 | 课程指定端口；Streamlit 默认 8501，Docker 映射到主机 8004 |

---

## 已知坑 (GOTCHAS)

- **坑-001**: Dockerfile ARG 作用域问题
  - 现象: CI 构建时 `PIP_INDEX_URL` 为空字符串，pip 安装失败
  - 根因: ARG 在 FROM 之前定义，作用域在 FROM 后结束
  - 解决: 在 FROM 后重新声明 ARG，使用 `--index-url` 替代 `-i`
  - 验证: CI Docker 构建步骤通过

- **坑-002**: CD 部署 git 目录检查
  - 现象: 首次部署时 `/opt/banksys` 存在但不是 git 仓库，`git clone || git pull` 失败
  - 根因: 目录存在非空时 `git clone` 失败；非 git 目录时 `git pull` 失败
  - 解决: 先检查是否为 git 目录（`[ -d .git ]`），是则 pull，否则删除后重新克隆
  - 验证: CD 部署成功，端口 8005，健康检查 ok

- **坑-003**: ruff 版本不一致导致 CI 格式检查失败
  - 现象: 本地 `ruff format --check` 通过，CI 失败（1 file would be reformatted）
  - 根因: CI runner 和本地 ruff 版本不同（0.1.0 vs 0.6.4）
  - 解决: 固定 requirements-dev.txt 中 ruff 版本为 `==0.6.4`，CI 中显式安装相同版本
  - 验证: CI 格式检查通过

- **坑-004**: CD git ownership 错误
  - 现象: `fatal: detected dubious ownership in repository at '/opt/banksys'`
  - 根因: Docker 容器操作后目录所有权变化，git 检测到可疑所有权
  - 解决: CD 脚本开头添加 `git config --global --add safe.directory /opt/banksys`
  - 验证: CD 部署成功

- **坑-008**: Streamlit 多页应用容器内 `ModuleNotFoundError: No module named 'app'`（已修复）
  - 现象: 部署后页面报 `from app.models import visualizer` → No module named 'app'（/app/app/pages/01_data_analysis.py）
  - 根因: 容器 `CMD streamlit run app/main.py` 只把主脚本目录 /app/app 加进 sys.path，而 `import app.*` 需要父目录 /app 在路径上；本地用 `python -m streamlit` 会把 cwd 加进路径所以没暴露
  - 隐蔽点: 本地只验了 HTTP 200，但 Streamlit 页面脚本在 websocket 连接时才执行，200 不代表页面渲染成功
  - 解决: Dockerfile 增加 `ENV PYTHONPATH=/app`；本地复现验证：无 PYTHONPATH 报同样错，设置后三模块导入 OK
  - 教训: 验证 Streamlit 多页应用要真正打开每个页面触发脚本执行，不能只看健康检查/HTTP 200
  - 验证: 待 PR #5 合并后 CD 确认

- **坑-007**: Docker 内 apt-get 装 curl 在国内服务器超时导致 CD 失败（已修复）
  - 现象: CD "Deploy to server" 跑 10 分钟后 `Run Command Timeout`；日志 `Fetched 9975 kB in 8min 6s (20.5 kB/s)`
  - 根因: 为容器 HEALTHCHECK 装 curl 加了 `apt-get update/install`，服务器访问 deb.debian.org 极慢（20.5 kB/s），超过 appleboy/ssh-action 默认 10 分钟命令超时。CI 在国外 runner 上 apt 快所以没暴露
  - 解决: Dockerfile 彻底移除 apt-get/curl，容器 HEALTHCHECK 改用镜像自带 Python（urllib）访问 /_stcore/health，完全绕开 apt
  - 教训: 国内服务器构建镜像要避免走 Debian 官方源；能用镜像已有运行时（python）就别额外 apt 装包
  - 验证: 待新 PR 合并后 CD 确认

- **坑-006**: 模型产物不进镜像导致生产预测失效（已修复）
  - 现象: model.pkl 被 .gitignore 排除，CD 克隆代码后镜像内无模型，预测页报"模型未找到"
  - 根因: 模型是离线产物不进 Git，但 Dockerfile 未在构建时训练
  - 解决: Dockerfile 在 COPY app/ 与 data/ 后增加 `RUN python -m app.ml.train --overwrite`，把模型烤进镜像；同时 slim 镜像补装 curl、HEALTHCHECK 端点改为 /_stcore/health
  - 验证: 待 CI docker build 与 CD 部署确认

- **坑-005**: 端口回退问题（已修复）
  - 现象: 每次部署端口不同（8004→8005→8006），端口递增
  - 根因: 端口检查在容器删除之前；多个旧容器占用不同端口
  - 解决: 先停止所有占用 8000-8010 端口的容器，等待释放，固定使用 8004
  - 验证: CD 成功，固定部署在端口 8004

---

## 里程碑 (DONE)

- [x] 2025-06-07：填写项目规范文档（00/01/PROGRESS）
- [x] 2025-06-07：创建 GitHub 仓库（banksys_szai4）
- [x] 2025-06-07：US-1 完成 - 初始化项目工程化与 CI/CD
  - 完整跑通六步交付流程
  - CI/CD 流水线配置完成
  - CD 成功部署到服务器（端口 8005）
- [x] 2025-06-07：US-2 完成 - 数据加载与预处理模块
  - 实现 data_loader.py 模块（4 个函数，100% 覆盖率）
  - 编写 25 个测试用例
  - 修复 ruff 版本锁定问题
  - 修复 CD git ownership 问题
  - CD 部署成功（端口 8006）

> 反臃肿:里程碑超过 15 条时,把更早内容合并成一行摘要,保持本文件可快速阅读。

# standards-template · 学生项目可复制模板

> **用途**:每个新项目复制一份本目录,改名为项目根目录下的 `standards/`。任意 AI 工具进入项目后,先读 `standards/README.md`,即可按统一规则继续开发、提交、PR、CI/CD 与存档。

---

## 1. 学生怎么用

```bash
# 在你的项目根目录执行
cp -r <课件目录>/standards-template ./standards
```

Windows 可手动复制文件夹,复制后目录应是:

```text
你的项目/
├── standards/
│   ├── README.md
│   ├── 00-project-context.md
│   ├── 01-requirements.md
│   ├── PROGRESS.md
│   ├── 02-coding-standards.md
│   ├── 03-testing-standards.md
│   ├── 04-git-workflow.md
│   ├── 05-cicd-standards.md
│   ├── 06-ai-collab-protocol.md
│   └── templates/
└── <你的代码>
```

---

## 2. 两类文件,不要混

| 类型 | 文件 | 是否每个项目要改 | 谁维护 |
|---|---|---|---|
| **项目活记忆** | `00-project-context.md`、`01-requirements.md`、`PROGRESS.md` | 必须按项目重填 | AI 写,人审 |
| **通用规范** | `02`~`06`、`templates/` | 默认不改 | 团队维护 |

> 简单说:`00/01/PROGRESS` 记录“这个项目是什么、要做什么、做到哪了”;`02~06` 规定“怎么写代码、怎么测试、怎么走 Git/PR/CI/CD”。

---

## 3. AI 每次会话读取顺序

1. `00-project-context.md` — 项目身份、技术栈、目录地图、部署取值。
2. `01-requirements.md` — 活 PRD,所有需求与验收标准。
3. `PROGRESS.md` — 当前状态、下一步、决策、踩坑。
4. `02`~`06` — 通用工程规范。
5. `templates/` — Issue / PR 模板。

---

## 4. 第一次开工 prompt

```prompt
请先读取 standards/README.md,并按它的顺序读取 00/01/PROGRESS 与 02~06。
这是一个新项目。我的项目需求是:
<在这里写项目目标、技术栈、希望实现的功能、部署方式>

请先做三件事:
1. 填写 standards/00-project-context.md。
2. 把需求整理进 standards/01-requirements.md,写成用户故事和验收标准。
3. 初始化 standards/PROGRESS.md,列出第一批 TODO。

完成后先停下让我确认,不要直接写代码。
```

---

## 5. 标准开发闭环 · 固定六步(每步确认)

AI 严格按 `06-ai-collab-protocol.md` 的「六步交付流程 + 确认门」推进,**每到确认门停下汇报、等人确认**:

```text
① 建仓 + 配 Secrets    AI 建仓 → ✋提示人类配 SSH_PRIVATE_KEY/HOST/USER(新仓库默认没有)
② 开 feature 分支       从 main 切分支,严禁直接改 main         ✋报分支名
③ 本地模块化开发        逐模块写代码+测试,每模块更新 PROGRESS  ✋每个模块汇报进度
④ 本地 CI 自检(AI 跑)  ruff + pytest + 覆盖率 + 项目门禁;本地不强制 docker  ✋全绿才继续
⑤ 触发 PR              push + AI 主动建 PR,CI 在 PR 上复检    ✋报 PR 链接 + CI 状态
⑥ 人工审核 →(人)合并 → CD  ✋AI 发完 PR 即停;Review 与 Merge 都由人做;合并触发 CD → ✋报端口/健康检查
```

**课堂第一项功能必须完整演示一次这条链**,不能直接 push main;
**合并是人类的动作——AI 绝不自行合并 PR;分支默认保留(不自动删)。**

---

## 6. 反臃肿纪律

1. 需求只写进 `01-requirements.md`,不要到处新建 PRD。
2. 进度、决策、坑只写进 `PROGRESS.md`。
3. 一需求一分支一 PR,PR 尽量小于 400 行。
4. CI 红灯不合并;flaky test 必须根治。
5. 新增目录前先更新 `00-project-context.md` 的目录地图。

"""Test suite."""

"""Pytest configuration and fixtures."""

import sys
from pathlib import Path

import pytest

# Add app directory to path
sys.path.insert(0, str(Path(__file__).parent.parent))


@pytest.fixture
def sample_data():
    """Sample bank marketing data for testing."""
    return {
        "age": 45,
        "job": "admin.",
        "marital": "married",
        "education": "university.degree",
        "default": "no",
        "housing": "yes",
        "loan": "no",
        "contact": "cellular",
    }

"""Tests for data_loader module."""

import pandas as pd
import pytest

from app.models.data_loader import (
    FEATURE_COLUMNS,
    TRAIN_COLUMNS,
    get_column_statistics,
    get_missing_value_mask,
    load_test_data,
    load_train_data,
)


class TestLoadTrainData:
    """Test suite for load_train_data function."""

    def test_load_train_data_returns_dataframe(self):
        """Test that load_train_data returns a pandas DataFrame."""
        df = load_train_data()
        assert isinstance(df, pd.DataFrame)

    def test_load_train_data_has_expected_columns(self):
        """Test that loaded data has all expected columns."""
        df = load_train_data()
        assert list(df.columns) == TRAIN_COLUMNS

    def test_load_train_data_not_empty(self):
        """Test that loaded data is not empty."""
        df = load_train_data()
        assert len(df) > 0

    def test_load_train_data_has_target_column(self):
        """Test that 'subscribe' column exists."""
        df = load_train_data()
        assert "subscribe" in df.columns

    def test_load_train_data_from_custom_dir(self, tmp_path):
        """Test loading from custom data directory."""
        # Create temporary train.csv
        train_data = pd.DataFrame({col: ["test"] for col in TRAIN_COLUMNS})
        train_path = tmp_path / "train.csv"
        train_data.to_csv(train_path, index=False)

        df = load_train_data(data_dir=tmp_path)
        assert len(df) == 1
        assert df.iloc[0]["age"] == "test"


class TestLoadTestData:
    """Test suite for load_test_data function."""

    def test_load_test_data_returns_dataframe(self):
        """Test that load_test_data returns a pandas DataFrame."""
        df = load_test_data()
        assert isinstance(df, pd.DataFrame)

    def test_load_test_data_has_feature_columns(self):
        """Test that loaded data has feature columns only (no target)."""
        df = load_test_data()
        assert list(df.columns) == FEATURE_COLUMNS
        assert "subscribe" not in df.columns

    def test_load_test_data_not_empty(self):
        """Test that loaded data is not empty."""
        df = load_test_data()
        assert len(df) > 0


class TestErrorHandling:
    """Test suite for error handling."""

    def test_load_train_data_file_not_found(self, tmp_path):
        """Test that FileNotFoundError is raised when file doesn't exist."""
        with pytest.raises(FileNotFoundError, match="Data file not found"):
            load_train_data(data_dir=tmp_path)

    def test_load_test_data_file_not_found(self, tmp_path):
        """Test that FileNotFoundError is raised when file doesn't exist."""
        with pytest.raises(FileNotFoundError, match="Data file not found"):
            load_test_data(data_dir=tmp_path)

    def test_load_empty_file_raises_error(self, tmp_path):
        """Test that ValueError is raised for empty file."""
        empty_path = tmp_path / "train.csv"
        empty_path.write_text("id,age\n")  # Header only

        with pytest.raises(ValueError, match="Data file is empty"):
            load_train_data(data_dir=tmp_path)

    def test_load_invalid_columns_raises_error(self, tmp_path):
        """Test that ValueError is raised for invalid columns."""
        invalid_path = tmp_path / "train.csv"
        invalid_path.write_text("wrong,columns\n1,2\n")

        with pytest.raises(ValueError, match="Missing expected columns"):
            load_train_data(data_dir=tmp_path)


class TestMissingValueMask:
    """Test suite for get_missing_value_mask function."""

    def test_returns_boolean_series(self):
        """Test that function returns boolean Series."""
        df = load_train_data()
        mask = get_missing_value_mask(df, "education")
        assert mask.dtype == bool

    def test_invalid_column_raises_error(self):
        """Test that ValueError is raised for invalid column."""
        df = load_train_data()
        with pytest.raises(ValueError, match="Column not found"):
            get_missing_value_mask(df, "nonexistent_column")

    def test_detects_missing_values(self):
        """Test that missing values are correctly detected."""
        df = pd.DataFrame({"col": ["known", "unknown", "nonexistent", ""]})
        mask = get_missing_value_mask(df, "col")
        # First value should not be marked as missing
        assert not mask.iloc[0]
        # Rest should be marked as missing
        assert mask.iloc[1:].all()
        assert mask.sum() == 3


class TestColumnStatistics:
    """Test suite for get_column_statistics function."""

    @pytest.fixture
    def sample_df(self):
        """Create sample DataFrame for testing."""
        return pd.DataFrame(
            {
                "age": [25, 30, 35, 40, 45],
                "job": ["admin.", "blue-collar", "unknown", "admin.", "blue-collar"],
            }
        )

    def test_returns_statistics_for_numeric_column(self, sample_df):
        """Test that statistics are returned for numeric columns."""
        stats = get_column_statistics(sample_df, "age")
        assert "mean" in stats
        assert "std" in stats
        assert "min" in stats
        assert "max" in stats
        assert stats["mean"] == 35.0

    def test_returns_statistics_for_categorical_column(self, sample_df):
        """Test that statistics are returned for categorical columns."""
        stats = get_column_statistics(sample_df, "job")
        assert "count" in stats
        assert "unique" in stats
        assert "value_counts" in stats
        assert stats["unique"] == 3

    def test_invalid_column_raises_error(self):
        """Test that ValueError is raised for invalid column."""
        df = load_train_data()
        with pytest.raises(ValueError, match="Column not found"):
            get_column_statistics(df, "nonexistent_column")

    def test_real_data_age_statistics(self):
        """Test statistics on real age data."""
        df = load_train_data()
        stats = get_column_statistics(df, "age")
        assert stats["min"] >= 0
        assert stats["max"] <= 120
        assert stats["count"] == len(df)


class TestIntegration:
    """Integration tests for data loader."""

    def test_train_has_more_columns_than_test(self):
        """Test that train data has target column while test data does not."""
        train_df = load_train_data()
        test_df = load_test_data()
        # Train has subscribe column
        assert "subscribe" in train_df.columns
        # Test does not have subscribe column
        assert "subscribe" not in test_df.columns
        # Test has all feature columns
        assert set(test_df.columns) == set(FEATURE_COLUMNS)

    def test_data_dimensions_reasonable(self):
        """Test that data dimensions are reasonable."""
        train_df = load_train_data()
        test_df = load_test_data()
        # Both should have at least 1000 rows
        assert len(train_df) > 1000
        assert len(test_df) > 1000
        # Train has 22 columns, test has 21 columns
        assert len(train_df.columns) == 22
        assert len(test_df.columns) == 21

"""Basic health tests."""

import pytest


def test_python_version():
    """Verify Python version is 3.11+."""
    import sys

    major, minor = sys.version_info[:2]
    assert major == 3 and minor >= 11, f"Python 3.11+ required, got {major}.{minor}"


def test_app_imports():
    """Verify app modules can be imported."""
    import app
    import app.models
    import app.pages
    import app.utils

    assert app.__version__ is not None


def test_data_files_exist():
    """Verify data files exist."""
    from pathlib import Path

    data_dir = Path(__file__).parent.parent / "data"
    assert (data_dir / "train.csv").exists()
    assert (data_dir / "test.csv").exists()


@pytest.mark.unit
def test_placeholder():
    """Placeholder test to verify pytest runs."""
    assert True

"""Tests for the predictor module.

A small model is trained on synthetic data and saved to a temp path, so tests
never depend on the real (gitignored) model artifact.
"""

import time

import pandas as pd
import pytest

from app.ml import train
from app.models import predictor
from app.models.data_loader import MODEL_FEATURES


def _make_features(positive: bool = True) -> dict:
    """Build a complete, valid feature dict for one customer."""
    return {
        "job": "student" if positive else "admin.",
        "marital": "single" if positive else "married",
        "education": "university.degree",
        "default": "no",
        "housing": "yes",
        "loan": "no",
        "contact": "cellular",
        "month": "may",
        "day_of_week": "mon",
        "poutcome": "success" if positive else "failure",
        "age": 25 if positive else 50,
        "duration": 800 if positive else 100,
        "campaign": 1,
        "pdays": 5 if positive else 999,
        "previous": 2 if positive else 0,
        "emp_var_rate": -1.8 if positive else 1.4,
        "cons_price_index": 92.0,
        "cons_conf_index": -40.0,
        "lending_rate3m": 1.0,
        "nr_employed": 5000.0,
    }


@pytest.fixture
def model_path(tmp_path):
    """Train a tiny model on synthetic data and return its file path as str."""
    rows = [_make_features(positive=(i % 3 == 0)) for i in range(60)]
    df = pd.DataFrame(rows)
    df["subscribe"] = ["yes" if i % 3 == 0 else "no" for i in range(60)]
    pipeline, _ = train.train_model(df)
    out = tmp_path / "model.pkl"
    train.save_model(pipeline, path=out)
    return str(out)


class TestLoadModel:
    def test_missing_model_raises(self, tmp_path):
        missing = str(tmp_path / "nope.pkl")
        with pytest.raises(predictor.ModelNotFoundError):
            predictor.load_model(missing)

    def test_load_returns_payload(self, model_path):
        payload = predictor.load_model(model_path)
        assert "pipeline" in payload
        assert payload["feature_columns"] == MODEL_FEATURES


class TestPredict:
    def test_returns_expected_keys(self, model_path):
        result = predictor.predict(_make_features(), model_path=model_path)
        assert set(result.keys()) == {"subscribe", "probability", "confidence"}

    def test_types(self, model_path):
        result = predictor.predict(_make_features(), model_path=model_path)
        assert isinstance(result["subscribe"], bool)
        assert isinstance(result["probability"], float)
        assert isinstance(result["confidence"], str)

    def test_probability_in_range(self, model_path):
        result = predictor.predict(_make_features(), model_path=model_path)
        assert 0.0 <= result["probability"] <= 1.0

    def test_subscribe_consistent_with_probability(self, model_path):
        result = predictor.predict(_make_features(), model_path=model_path)
        assert result["subscribe"] == (result["probability"] >= 0.5)

    def test_missing_feature_raises(self, model_path):
        features = _make_features()
        del features["age"]
        with pytest.raises(ValueError, match="Missing required features"):
            predictor.predict(features, model_path=model_path)

    def test_invalid_numeric_raises(self, model_path):
        features = _make_features()
        features["age"] = "not-a-number"
        with pytest.raises(ValueError, match="must be numeric"):
            predictor.predict(features, model_path=model_path)

    def test_unknown_category_handled(self, model_path):
        features = _make_features()
        features["job"] = "astronaut"  # unseen category
        result = predictor.predict(features, model_path=model_path)
        assert 0.0 <= result["probability"] <= 1.0

    def test_response_under_one_second(self, model_path):
        predictor.predict(_make_features(), model_path=model_path)  # warm cache
        start = time.perf_counter()
        predictor.predict(_make_features(), model_path=model_path)
        assert (time.perf_counter() - start) < 1.0


class TestConfidenceLabel:
    @pytest.mark.parametrize(
        "prob,expected",
        [
            (0.95, "high"),
            (0.05, "high"),
            (0.7, "medium"),
            (0.3, "medium"),
            (0.5, "low"),
            (0.55, "low"),
        ],
    )
    def test_confidence_labels(self, prob, expected):
        assert predictor._confidence_label(prob) == expected

"""Tests for the model training module.

Uses a small synthetic dataset to keep tests fast and avoid depending on the
full data file. Verifies pipeline construction, X/y preparation, end-to-end
training metrics, and model persistence (with feature schema).
"""

import joblib
import pandas as pd
import pytest
from sklearn.pipeline import Pipeline

from app.ml import train
from app.models.data_loader import CATEGORICAL_FEATURES, MODEL_FEATURES, NUMERIC_FEATURES


@pytest.fixture
def synthetic_df():
    """Synthetic dataset with a learnable signal and both target classes."""
    rows = []
    for i in range(60):
        positive = i % 3 == 0
        rows.append(
            {
                "job": "student" if positive else "admin.",
                "marital": "single" if positive else "married",
                "education": "university.degree",
                "default": "no",
                "housing": "yes" if positive else "no",
                "loan": "no",
                "contact": "cellular",
                "month": "may",
                "day_of_week": "mon",
                "poutcome": "success" if positive else "failure",
                "age": 25 if positive else 50,
                "duration": 800 if positive else 100,
                "campaign": 1 if positive else 3,
                "pdays": 5 if positive else 999,
                "previous": 2 if positive else 0,
                "emp_var_rate": -1.8 if positive else 1.4,
                "cons_price_index": 92.0,
                "cons_conf_index": -40.0,
                "lending_rate3m": 1.0,
                "nr_employed": 5000.0,
                "subscribe": "yes" if positive else "no",
            }
        )
    return pd.DataFrame(rows)


class TestBuildPipeline:
    def test_returns_pipeline(self):
        assert isinstance(train.build_pipeline(), Pipeline)

    def test_pipeline_has_expected_steps(self):
        pipeline = train.build_pipeline()
        assert "preprocess" in pipeline.named_steps
        assert "model" in pipeline.named_steps


class TestPrepareXy:
    def test_x_has_model_features(self, synthetic_df):
        x, _ = train._prepare_xy(synthetic_df)
        assert list(x.columns) == MODEL_FEATURES

    def test_y_is_binary(self, synthetic_df):
        _, y = train._prepare_xy(synthetic_df)
        assert set(y.unique()).issubset({0, 1})

    def test_y_positive_count(self, synthetic_df):
        _, y = train._prepare_xy(synthetic_df)
        assert int(y.sum()) == 20


class TestTrainModel:
    def test_returns_fitted_pipeline_and_metrics(self, synthetic_df):
        pipeline, metrics = train.train_model(synthetic_df)
        assert isinstance(pipeline, Pipeline)
        assert "auc" in metrics and "accuracy" in metrics

    def test_metrics_within_range(self, synthetic_df):
        _, metrics = train.train_model(synthetic_df)
        assert 0.0 <= metrics["auc"] <= 1.0
        assert 0.0 <= metrics["accuracy"] <= 1.0

    def test_reproducible(self, synthetic_df):
        _, metrics_a = train.train_model(synthetic_df)
        _, metrics_b = train.train_model(synthetic_df)
        assert metrics_a["auc"] == metrics_b["auc"]


class TestSaveModel:
    def test_save_creates_file(self, synthetic_df, tmp_path):
        pipeline, _ = train.train_model(synthetic_df)
        out = tmp_path / "model.pkl"
        saved = train.save_model(pipeline, path=out)
        assert saved.exists()

    def test_saved_payload_schema(self, synthetic_df, tmp_path):
        pipeline, _ = train.train_model(synthetic_df)
        out = tmp_path / "model.pkl"
        train.save_model(pipeline, path=out)
        payload = joblib.load(out)
        assert payload["categorical_features"] == CATEGORICAL_FEATURES
        assert payload["numeric_features"] == NUMERIC_FEATURES
        assert isinstance(payload["pipeline"], Pipeline)

"""Tests for the visualizer module.

Computation helpers are tested with a small in-memory DataFrame (no dependency
on the real data files). Figure builders are smoke-tested to confirm they
return Plotly figures without raising.
"""

import pandas as pd
import plotly.graph_objects as go
import pytest

from app.models import visualizer


@pytest.fixture
def sample_df():
    """Small, hand-built dataset with a known subscribe distribution."""
    return pd.DataFrame(
        {
            "age": [23, 30, 41, 52, 67, 38, 29, 45],
            "job": [
                "admin.",
                "admin.",
                "services",
                "services",
                "retired",
                "admin.",
                "blue-collar",
                "services",
            ],
            "duration": [100, 200, 300, 400, 500, 150, 250, 350],
            "subscribe": ["no", "yes", "no", "yes", "yes", "no", "no", "no"],
        }
    )


class TestComputeOverview:
    def test_overview_counts_and_rate(self, sample_df):
        result = visualizer.compute_overview(sample_df)
        assert result["total_records"] == 8
        assert result["subscribed"] == 3
        assert result["not_subscribed"] == 5
        assert result["subscribe_rate"] == pytest.approx(3 / 8)

    def test_overview_feature_count(self, sample_df):
        result = visualizer.compute_overview(sample_df)
        assert result["feature_count"] == 4

    def test_overview_missing_target_raises(self):
        df = pd.DataFrame({"age": [1, 2]})
        with pytest.raises(ValueError, match="Target column"):
            visualizer.compute_overview(df)


class TestComputeValueCounts:
    def test_value_counts_sums_to_total(self, sample_df):
        result = visualizer.compute_value_counts(sample_df, "job")
        assert result["count"].sum() == len(sample_df)

    def test_value_counts_columns(self, sample_df):
        result = visualizer.compute_value_counts(sample_df, "job")
        assert list(result.columns) == ["job", "count"]

    def test_value_counts_admin_count(self, sample_df):
        result = visualizer.compute_value_counts(sample_df, "job")
        admin_row = result[result["job"] == "admin."]
        assert int(admin_row["count"].iloc[0]) == 3

    def test_value_counts_missing_column_raises(self, sample_df):
        with pytest.raises(ValueError, match="Column not found"):
            visualizer.compute_value_counts(sample_df, "nonexistent")


class TestSubscribeRateByCategory:
    def test_rate_values(self, sample_df):
        result = visualizer.compute_subscribe_rate_by_category(sample_df, "job")
        retired = result[result["job"] == "retired"]
        assert retired["rate"].iloc[0] == pytest.approx(1.0)
        admin = result[result["job"] == "admin."]
        assert admin["rate"].iloc[0] == pytest.approx(1 / 3)

    def test_rate_sorted_descending(self, sample_df):
        result = visualizer.compute_subscribe_rate_by_category(sample_df, "job")
        rates = result["rate"].tolist()
        assert rates == sorted(rates, reverse=True)

    def test_totals_match(self, sample_df):
        result = visualizer.compute_subscribe_rate_by_category(sample_df, "job")
        assert result["total"].sum() == len(sample_df)

    def test_missing_target_raises(self):
        df = pd.DataFrame({"job": ["a", "b"]})
        with pytest.raises(ValueError, match="Target column"):
            visualizer.compute_subscribe_rate_by_category(df, "job")


class TestComputeAgeGroups:
    def test_age_group_counts_sum(self, sample_df):
        result = visualizer.compute_age_groups(sample_df)
        assert result["count"].sum() == len(sample_df)

    def test_age_group_has_rate_column(self, sample_df):
        result = visualizer.compute_age_groups(sample_df)
        assert "rate" in result.columns
        assert (result["rate"] >= 0).all() and (result["rate"] <= 1).all()

    def test_age_group_custom_bins(self, sample_df):
        result = visualizer.compute_age_groups(
            sample_df, bins=[0, 40, 120], labels=["young", "old"]
        )
        assert set(result["age_group"]) == {"young", "old"}

    def test_age_group_invalid_labels_raises(self, sample_df):
        with pytest.raises(ValueError, match="labels length"):
            visualizer.compute_age_groups(sample_df, bins=[0, 50, 120], labels=["only_one"])


class TestNumericSummary:
    def test_summary_keys(self, sample_df):
        result = visualizer.compute_numeric_summary(sample_df, "age")
        for key in ["count", "mean", "std", "min", "q25", "median", "q75", "max"]:
            assert key in result

    def test_summary_values(self, sample_df):
        result = visualizer.compute_numeric_summary(sample_df, "duration")
        assert result["min"] == 100.0
        assert result["max"] == 500.0
        assert result["count"] == 8

    def test_summary_non_numeric_raises(self, sample_df):
        with pytest.raises(ValueError, match="not numeric"):
            visualizer.compute_numeric_summary(sample_df, "job")

    def test_summary_missing_column_raises(self, sample_df):
        with pytest.raises(ValueError, match="Column not found"):
            visualizer.compute_numeric_summary(sample_df, "nope")


class TestFigureBuilders:
    def test_build_subscribe_pie(self, sample_df):
        assert isinstance(visualizer.build_subscribe_pie(sample_df), go.Figure)

    def test_build_category_bar(self, sample_df):
        assert isinstance(visualizer.build_category_bar(sample_df, "job"), go.Figure)

    def test_build_subscribe_rate_bar(self, sample_df):
        assert isinstance(visualizer.build_subscribe_rate_bar(sample_df, "job"), go.Figure)

    def test_build_age_histogram(self, sample_df):
        assert isinstance(visualizer.build_age_histogram(sample_df), go.Figure)

    def test_build_numeric_histogram(self, sample_df):
        assert isinstance(visualizer.build_numeric_histogram(sample_df, "duration"), go.Figure)

name: CD

on:
  push:
    branches: [main]

jobs:
  cd:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build Docker image
        run: |
          docker build \
            --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
            -t hello-flask-sz:latest .

      - name: Deploy to server
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          SSH_HOST: ${{ secrets.SSH_HOST }}
          SSH_USER: ${{ secrets.SSH_USER }}
        run: |
          # Setup SSH
          mkdir -p ~/.ssh
          echo "$SSH_PRIVATE_KEY" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          ssh-keyscan -H "$SSH_HOST" >> ~/.ssh/known_hosts

          # Deploy directory
          DEPLOY_DIR="/opt/hello-flask-sz"
          APP="hello-flask-sz"
          PORT=8003
          PORT_MAX=8020

          # Create deploy directory
          ssh -i ~/.ssh/deploy_key "${SSH_USER}@${SSH_HOST}" "mkdir -p ${DEPLOY_DIR}"

          # Sync files
          rsync -avz -e "ssh -i ~/.ssh/deploy_key" \
            --exclude='.git/' \
            --exclude='standards/' \
            --exclude='__pycache__/' \
            --exclude='*.pyc' \
            ./ "${SSH_USER}@${SSH_HOST}:${DEPLOY_DIR}/"

          # Remote deployment script
          ssh -i ~/.ssh/deploy_key "${SSH_USER}@${SSH_HOST}" << 'ENDSSH'
          set -e
          cd /opt/hello-flask-sz

          # Build on server
          docker build \
            --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
            -t hello-flask-sz:latest .

          # Port fallback logic
          port_in_use() {
            ss -ltnH 2>/dev/null | grep -q ":$1 " && return 0
            docker ps --format "{{.Ports}}" 2>/dev/null | grep -q ":$1->" && return 0
            return 1
          }

          PORT=""
          for p in $(seq 8003 8020); do
            if ! port_in_use "$p"; then PORT="$p"; break; fi
          done

          if [ -z "$PORT" ]; then
            echo "预留端口区间已全部占用,部署中止"
            exit 1
          fi

          echo ">> 部署到主机端口 $PORT"

          # Stop and remove old container (idempotent)
          docker rm -f hello-flask-sz 2>/dev/null || true

          # Run new container
          docker run -d \
            --name hello-flask-sz \
            --restart unless-stopped \
            -p ${PORT}:8003 \
            hello-flask-sz:latest

          # Wait for startup
          sleep 3

          # Health check
          curl -fsS "http://localhost:${PORT}/health"
          echo ">> 部署成功: http://localhost:${PORT}/health"
          ENDSSH

name: CI

on:
  push:
    branches: [main, feature/**]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Cache pip packages
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}

      - name: Install dependencies
        run: |
          pip install -r requirements-dev.txt

      - name: Format check
        run: ruff format --check .

      - name: Lint
        run: ruff check .

      - name: Run tests with coverage
        run: pytest --cov=. --cov-fail-under=80 --cov-report=term-missing

      - name: Build Docker image
        run: docker build -t hello-flask-sz:latest .

# Issue 模板

## 类型

- [ ] Feature 功能
- [ ] Bug 缺陷
- [ ] Tech Debt 技术债
- [ ] Docs 文档
- [ ] CI/CD 流水线

## 背景 / 场景

<谁在什么场景下遇到什么问题>

## 目标

<这次希望达成什么>

## 验收标准

- [ ] Given <前提>,When <动作>,Then <可验证结果>
- [ ] <补充标准>

## 技术备注

<可选:边界、风险、约束、参考资料>

## 优先级

P0 / P1 / P2

# Pull Request 模板

## What

<这个 PR 做了什么>

## Why

关联 Issue:`closes #<编号>`

## How to Test

- [ ] 本地格式检查通过
- [ ] 本地静态检查通过
- [ ] 本地测试通过
- [ ] CI 通过
- [ ] CD / 部署验证通过(如适用)

## 风险与回滚

<风险点;如果失败如何回滚>

## 自检清单

- [ ] 没有硬编码密钥/密码
- [ ] 没有调试 print / 死代码
- [ ] PR 体积可控
- [ ] commit message 符合规范
- [ ] 已同步最新 main,无冲突
- [ ] 已更新 standards/PROGRESS.md

---

通过标准:CI 全绿 + Review 通过 + 分支保护通过。