# 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 或域名 |