Metadata-Version: 2.4
Name: urpool
Version: 0.1.0
Summary: Build and serve an interactive requirements bubble frontend
Author: urpool maintainers
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: extractors
Requires-Dist: pypdf>=4.0.0; extra == "extractors"
Requires-Dist: openpyxl>=3.1.0; extra == "extractors"
Requires-Dist: xlrd>=2.0.1; extra == "extractors"

# UserRequirements - 需求池前端展示

本仓库在 `user_requirements/` 下存放各业务需求（每个需求一个文件夹，包含 `info.json` 和 `需求文档`）。

本项目提供一个**纯静态**的前端页面，将每个需求显示为一个在屏幕中“跳动”的球体：
- `credits` 越大，球体越大
- 点击球体可在右侧（或移动端抽屉）查看需求详情
- 顶部支持搜索筛选（标题/描述/文档），并显示当前数量与 credits 汇总

## 目录结构

- `user_requirements/`：需求数据源
- `scripts/build_requirements_index.py`：将数据源汇总成前端可读取的 JSON
- `frontend/`：静态前端（Canvas 动画）

## 使用方式（macOS / zsh）

## 作为 PyPI 包使用（推荐给外部用户）

安装：

```bash
python3 -m pip install urpool
```

如果需要抽取 PDF / Excel 文本：

```bash
python3 -m pip install "urpool[extractors]"
```

一条命令完成“构建 + 启动服务”（只需提供 `members.json` 和 `user_requirements`）：

```bash
urpool run --requirements-dir /path/to/user_requirements --members /path/to/members.json --port 5173
```

仅构建前端产物：

```bash
urpool build --requirements-dir /path/to/user_requirements --members /path/to/members.json --output-dir /path/to/frontend
```

仅启动已有前端目录：

```bash
urpool serve --output-dir /path/to/frontend --port 5173
```

---

推荐：使用一条命令启动（每次启动前都会更新 `user_requirements` 构建产物）

```bash
/Users/alex/PycharmProjects/UserRequirements/scripts/start_frontend.sh
```

可选端口：

```bash
/Users/alex/PycharmProjects/UserRequirements/scripts/start_frontend.sh 5173
```

---

可选：若 `需求文档` 包含 PDF / Excel，建议先安装抽取依赖：

```bash
python3 -m pip install -r /Users/alex/PycharmProjects/UserRequirements/requirements-extractors.txt
```

> 未安装时不会中断构建，但 PDF/XLSX/XLS 文本将被跳过并输出 Warning。

1) 生成前端所需数据：

```bash
python3 /Users/alex/PycharmProjects/UserRequirements/scripts/build_requirements_index.py
```

会生成：`frontend/requirements.json`

并同步：`members.json` -> `frontend/members.json`（用于前端负责人推荐加载）。

> 更新成员技能后，请重新执行一次该脚本。

2) 启动一个本地静态服务器（必须使用 HTTP 方式打开，直接双击 `index.html` 会因为浏览器限制无法 fetch 本地文件）：

```bash
cd /Users/alex/PycharmProjects/UserRequirements/frontend
python3 -m http.server 5173
```

如果终端显示 `Serving HTTP on :: port 5173 ...`（IPv6），浏览器请优先打开：

- http://localhost:5173/

若你的浏览器/网络环境对 IPv6 访问不友好，可以强制绑定 IPv4：

```bash
cd /Users/alex/PycharmProjects/UserRequirements/frontend
python3 -m http.server 5173 --bind 127.0.0.1
```

3) 浏览器访问：

- http://localhost:5173

打不开时也可以直接试：

- http://127.0.0.1:5173/
- http://localhost:5173/index.html

## 数据约定

每个需求文件夹：

- `info.json`（示例字段）：
  - `credits`（数字）
  - `start_date` / `end_date`（字符串，允许不规范，前端会原样展示）
  - `description`（字符串）
- `需求文档`
  - 可以是**文件**或**目录**
  - 若是目录，会递归读取其中所有文本文件并合并

## 可选改进

- 需求数量很大时可加入缩放/拖拽、或按标签筛选
- 可把碰撞物理替换为 Matter.js（更真实但引入依赖）

