| --- |
| title: 肆带贰球队系统 |
| emoji: ⚽ |
| colorFrom: blue |
| colorTo: indigo |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # 肆带贰 · 球队管理系统 |
|
|
| 深圳「肆带贰」足球俱乐部（SHENZHEN SI DAI ER FC）的内部球队管理系统，基于 [Shiny for Python](https://shiny.posit.co/py/) 构建。 |
|
|
| ## 功能 |
|
|
| - **登录鉴权**：队员/管理员分级，密码哈希存储，支持改密、管理员重置 |
| - **名单管理**：队员资料、球衣号、赛季信息 |
| - **数据展示**：按赛季查看球队数据 |
| - **图片导出**：将名单/数据渲染为图片便于分享 |
|
|
| ## 技术栈 |
|
|
| | 层 | 选型 | |
| |----|------| |
| | Web 框架 | Shiny for Python | |
| | 数据层 | SQLAlchemy ORM | |
| | 存储 | 默认 SQLite，可切 Postgres（环境变量切换，代码零改动） | |
| | 数据处理 | pandas / openpyxl | |
| | 图片 | Pillow | |
| | 测试 | Playwright | |
|
|
| ## 快速开始 |
|
|
| 依赖管理使用 [uv](https://github.com/astral-sh/uv)： |
|
|
| ```bash |
| # 安装依赖 |
| uv sync |
| |
| # 本地运行（热重载） |
| uv run shiny run app.py --reload |
| ``` |
|
|
| 首次运行会自动初始化数据库并写入名单与示例数据，浏览器打开 <http://127.0.0.1:8000>。 |
|
|
| ## 配置 |
|
|
| 通过环境变量配置，无需改动代码： |
|
|
| | 变量 | 作用 | 默认 | |
| |------|------|------| |
| | `DATABASE_URL` | 数据库连接串，部署时指向云端 Postgres | 本地 `data/team.db`（SQLite） | |
| | `SDE_DEFAULT_PASSWORD` | 队员初始密码 | 内置兜底（仅限本地开发，生产务必覆盖） | |
|
|
| > ⚠️ 正式部署请设置 `SDE_DEFAULT_PASSWORD`，并提醒队员首次登录后立即修改密码。 |
|
|
| ## 项目结构 |
|
|
| ``` |
| monsoon-app/ |
| ├── app.py # 入口：UI 装配 + 服务端逻辑 |
| ├── src/ |
| │ ├── config.py # 全局配置（球队信息、品牌色、数据库连接） |
| │ ├── db.py # 数据库引擎 |
| │ ├── models.py # ORM 模型 |
| │ ├── repo.py # 数据访问层 |
| │ ├── security.py # 密码哈希 |
| │ ├── seed.py # 初始数据 |
| │ ├── theme.py # 样式 |
| │ ├── export_img.py # 图片导出 |
| │ └── view_*.py # 各页面视图（登录 / 主页 / 个人 / 管理） |
| ├── data/ # 本地数据库（不入库） |
| ├── www/ # 静态资源 |
| └── tests/ # Playwright 测试 |
| ``` |
|
|
| ## 数据隐私 |
|
|
| 真实队员数据（含姓名、密码哈希）仅存于本地 `data/` 目录，已通过 `.gitignore` 排除，**不会进入版本库**。 |
|
|
