urpool 0.1.1

Build and serve an interactive requirements bubble frontend

UserRequirements - 需求池前端展示

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

本项目提供一个纯静态的前端页面，将每个需求显示为一个在屏幕中“跳动”的球体：

• credits 越大，球体越大
• 点击球体可在右侧（或移动端抽屉）查看需求详情
• 顶部支持搜索筛选（标题/描述/文档），并显示当前数量与 credits 汇总

目录结构

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

使用方式（macOS / zsh）

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

安装：

python3 -m pip install urpool

python3 -m build
python3 -m twine upload dist/urpool-0.1.0-py3-none-any.whl

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

python3 -m pip install "urpool[extractors]"

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

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

多人协同时，负责人手动锁定状态通过内置 /api/locks 同步（服务端 locks.json 持久化）。 请使用 urpool run/serve，不要用 python -m http.server 直接托管静态文件。

仅构建前端产物：

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

仅启动已有前端目录：

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

---

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

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

可选端口：

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

---

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

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

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

1. 生成前端所需数据：

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

会生成：frontend/requirements.json

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

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

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

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

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

• http://localhost:5173/

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

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（更真实但引入依赖）