@hupan56/wlkj 2.6.0 → 2.7.0

package/templates/qoder/scripts/archive_prd.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+archive_prd.py - PRD 按时间归档到个人工作区
+
+把刚生成的 PRD 复制一份到当前成员的个人归档区，按"天"分文件夹：
+    workspace/members/{name}/archive/{YYYY-MM-DD}/REQ-{编号}-{中文标题}.md
+并在 archive/_index.md 汇总成"周/月"视图，方便人翻查"我那天做了啥"。
+
+设计原则（非侵入）：
+    - 只**复制**，不移动；drafts/ 原件保留，data/docs/prd/ 完全不碰
+    - 归属看当前操作者（.developer），不依赖 PRD 的"产品负责人"字段 → 开发/测试/产品都能用
+    - 全程 try/except，失败只 print 一句提示，绝不阻塞 PRD 生成
+    - 用户没用 PRD 命令就完全不触发（本脚本只在 prd-generator 调用时跑）
+
+Usage:
+    python .qoder/scripts/archive_prd.py <prd 文件路径>
+    python .qoder/scripts/archive_prd.py <prd1> <prd2> ...   # 批量
+"""
+
+import os
+import re
+import sys
+from datetime import datetime, date, timedelta
+from pathlib import Path
+
+# UTF-8 stdio（防御性：Windows cmd 默认 GBK，stdout 被捕获时不崩）
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, TypeError, OSError, IOError):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+# 让 common/ 可被 import（直接当脚本跑时）
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+_COMMON = os.path.join(_THIS_DIR, "common")
+if _COMMON not in sys.path:
+    sys.path.insert(0, _COMMON)
+
+try:
+    from paths import get_repo_root, get_developer, MEMBERS_DIR
+except ImportError:
+    # 极端兜底：直接算路径
+    def get_repo_root():
+        current = Path(_THIS_DIR).resolve()
+        for _ in range(10):
+            if (current / ".qoder").is_dir():
+                return current
+            parent = current.parent
+            if parent == current:
+                break
+            current = parent
+        return Path(_THIS_DIR).parent.parent
+
+    def get_developer(repo_root=None):
+        dev = (repo_root or get_repo_root()) / ".qoder" / ".developer"
+        if not dev.is_file():
+            return None
+        for enc in ("utf-8", "gbk"):
+            try:
+                for line in dev.read_text(encoding=enc).splitlines():
+                    line = line.strip()
+                    if "=" in line and line.split("=")[0].strip() == "name":
+                        return line.split("=", 1)[1].strip() or None
+                    if ":" in line and line.split(":")[0].strip() == "name":
+                        return line.split(":", 1)[1].strip() or None
+            except (OSError, IOError, UnicodeDecodeError):
+                continue
+        return None
+
+    MEMBERS_DIR = None  # 下面用 repo_root 拼
+
+
+# ============================================================
+# 解析：中文标题 + 日期（带 fallback 链，健壮）
+# ============================================================
+
+# REQ-2026-005（标准）/ REQ-012（老格式单段）都能匹配
+_REQ_RE = re.compile(r"REQ-(\d{2,4})(?:-(\d{2,4}))?", re.IGNORECASE)
+# 创建日期: 2026-06-12 / 2026.06.12 / 2026/06/12
+_DATE_RE = re.compile(
+    r"(20\d{2})[./\-年](\d{1,2})[./\-月](\d{1,2})"
+)
+
+
+def _read_text_safe(path: Path) -> str:
+    """读文件，UTF-8 优先，GBK 兜底。"""
+    for enc in ("utf-8", "utf-8-sig", "gbk"):
+        try:
+            return path.read_text(encoding=enc)
+        except (OSError, IOError, UnicodeDecodeError):
+            continue
+    return ""
+
+
+def extract_title(content: str, fallback_name: str) -> str:
+    """提取 PRD 中文标题。fallback 链：
+       ① H1 标题（去掉 REQ-xxxx 前缀）
+       ② 正文「需求名称」「需求标题」
+       ③ 文件名 slug
+       ④ "未命名"
+    """
+    # ① H1：# REQ-2026-005 异常中心全国看板  →  取「异常中心全国看板」
+    for line in content.splitlines():
+        s = line.strip()
+        if s.startswith("# "):
+            title = s[2:].strip()
+            # 去掉开头的 REQ-xxxx-xxx 编号前缀
+            title = _REQ_RE.sub("", title).strip(" -—|")
+            if title:
+                return _clean_title(title)
+            break  # H1 存在但没正文，走下一条 fallback
+    # ② 正文 - **需求名称**: xxx / **需求标题**: xxx
+    m = re.search(r"\*{0,2}\s*(?:需求名称|需求标题|标题)\s*\*{0,2}\s*[:：]\s*(.+)", content)
+    if m:
+        return _clean_title(m.group(1).strip())
+    # ③ 文件名 slug
+    return fallback_name
+
+
+def _clean_title(title: str) -> str:
+    """清理标题：去尾部 markdown / 标点 / 多余空白。"""
+    title = title.splitlines()[0].strip()
+    title = re.sub(r"\s+", " ", title)
+    # 去掉行尾的 | 或多余修饰
+    title = title.rstrip("| -—·•")
+    return title or "未命名"
+
+
+def extract_date(content: str, file_mtime: float) -> str:
+    """提取 PRD 创建日期 (YYYY-MM-DD)。fallback 链：
+       ① 正文「创建日期 / 创建时间」
+       ② 正文任意 2026-06-12 格式日期
+       ③ 文件 mtime
+       ④ 今天
+    """
+    # ① 显式「创建日期」/「创建时间」
+    m = re.search(
+        r"(?:创建日期|创建时间|创建日期)\s*[:：]\s*" + _DATE_RE.pattern, content
+    )
+    if m:
+        d = _normalize_date(m.group(1), m.group(2), m.group(3))
+        if d:
+            return d
+    # ② 任意日期（取第一个）
+    m = _DATE_RE.search(content)
+    if m:
+        d = _normalize_date(m.group(1), m.group(2), m.group(3))
+        if d:
+            return d
+    # ③ mtime
+    try:
+        return datetime.fromtimestamp(file_mtime).strftime("%Y-%m-%d")
+    except (OSError, ValueError, OverflowError):
+        pass
+    # ④ 今天
+    return date.today().strftime("%Y-%m-%d")
+
+
+def _normalize_date(y: str, m: str, d: str) -> str:
+    try:
+        return "%s-%02d-%02d" % (y.zfill(4), int(m), int(d))
+    except (ValueError, TypeError):
+        return ""
+
+
+def extract_reqno(filename: str) -> str:
+    """从文件名提取 REQ 编号段，如 'REQ-2026-005'。取不到则用文件名去扩展名。
+    兼容标准格式 REQ-2026-005 和老格式 REQ-012（单段）。
+    """
+    m = _REQ_RE.search(filename)
+    if m:
+        year = m.group(1).zfill(4)
+        if m.group(2):  # 标准格式 REQ-2026-005
+            return "REQ-%s-%s" % (year, m.group(2))
+        return "REQ-%s" % year  # 老格式 REQ-012
+    base = os.path.splitext(filename)[0]
+    return base[:40]
+
+
+# ============================================================
+# 文件名安全化（中文保留，去掉文件系统非法字符）
+# ============================================================
+
+_UNSAFE_FS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+
+def _sanitize_filename(name: str, max_len: int = 60) -> str:
+    """文件名安全化：保留中文/字母/数字/连字符，去掉非法字符，限长。"""
+    name = _UNSAFE_FS.sub("", name).strip()
+    name = re.sub(r"\s+", "-", name)  # 空格转连字符
+    if len(name) > max_len:
+        name = name[:max_len].rstrip("-")
+    return name or "未命名"
+
+
+# ============================================================
+# 核心：归档单个 PRD
+# ============================================================
+
+def archive_one(prd_path: str, repo_root: Path) -> bool:
+    """把一个 PRD 归档到当前成员的个人区。返回是否成功。"""
+    src = Path(prd_path)
+    if not src.is_absolute():
+        src = (Path.cwd() / src).resolve()
+    if not src.is_file():
+        print("[archive] 跳过: 文件不存在 %s" % prd_path)
+        return False
+
+    developer = get_developer(repo_root)
+    if not developer:
+        print("[archive] 跳过: 未初始化开发者身份 (跑 /wl-init)")
+        return False
+
+    members = MEMBERS_DIR if MEMBERS_DIR else (repo_root / "workspace" / "members")
+    archive_root = Path(members) / developer / "archive"
+
+    content = _read_text_safe(src)
+    fname = src.name
+    reqno = extract_reqno(fname)
+    # 文件名里的 slug（REQ-2026-005-xxx.md 的 xxx 部分）作为最后兜底标题
+    slug_fallback = _REQ_RE.sub("", os.path.splitext(fname)[0]).lstrip("-_") or "未命名"
+    title = extract_title(content, slug_fallback)
+    prd_date = extract_date(content, src.stat().st_mtime)
+
+    # 目标：members/{dev}/archive/{YYYY-MM-DD}/REQ-{编号}-{中文标题}.md
+    day_dir = archive_root / prd_date
+    day_dir.mkdir(parents=True, exist_ok=True)
+    safe_title = _sanitize_filename(title)
+    dst_name = "%s-%s.md" % (reqno, safe_title)
+    dst = day_dir / dst_name
+
+    import shutil
+    shutil.copy2(src, dst)
+
+    # 更新当天 _index.md
+    _write_day_index(day_dir, prd_date)
+    # 更新 archive 根的 _index.md（周/月汇总）
+    _write_overview_index(archive_root, developer)
+
+    rel = dst.relative_to(repo_root) if str(dst).startswith(str(repo_root)) else dst
+    print("[archive] 已归档: %s" % rel)
+    return True
+
+
+def _collect_day_prds(day_dir: Path):
+    """收集某天文件夹里的 PRD（.md 且不是 _index）。返回 [(reqno, title, fname), ...]"""
+    items = []
+    for f in sorted(day_dir.iterdir()):
+        if not f.is_file() or not f.name.lower().endswith(".md"):
+            continue
+        if f.name.startswith("_"):
+            continue
+        stem = f.stem  # REQ-2026-005-异常中心全国看板
+        m = _REQ_RE.search(stem)
+        reqno = "REQ-%s-%s" % (m.group(1).zfill(4), m.group(2)) if m else stem
+        title = _REQ_RE.sub("", stem).lstrip("-_ ") or stem
+        items.append((reqno, title, f.name))
+    return items
+
+
+def _write_day_index(day_dir: Path, prd_date: str):
+    """写当天的 _index.md：一个清爽的当天需求清单。"""
+    items = _collect_day_prds(day_dir)
+    lines = ["# %s 的需求产出\n" % prd_date, "> 共 %d 个需求\n" % len(items)]
+    if items:
+        for reqno, title, fname in items:
+            lines.append("- **%s** %s — [`%s`](./%s)" % (reqno, title, fname, fname))
+    else:
+        lines.append("（无）")
+    (day_dir / "_index.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _iso_week_range(d: date):
+    """返回 d 所在自然周的 周一~周日（ISO 周，周一为起点）。"""
+    monday = d - timedelta(days=d.weekday())  # weekday() 周一=0
+    sunday = monday + timedelta(days=6)
+    return monday, sunday
+
+
+def _write_overview_index(archive_root: Path, developer: str):
+    """写 archive 根的 _index.md：按 周 / 月 汇总，给「我这阵子做了啥」一个总览。"""
+    if not archive_root.is_dir():
+        return
+    # 扫所有日期文件夹
+    days = []
+    for d in sorted(archive_root.iterdir()):
+        if not d.is_dir():
+            continue
+        try:
+            day = date.fromisoformat(d.name)  # 只认 YYYY-MM-DD
+        except ValueError:
+            continue
+        items = _collect_day_prds(d)
+        if items:
+            days.append((day, items))
+    if not days:
+        return
+
+    lines = ["# %s 的需求归档\n" % developer, "> 按时间翻查你的需求产出。物理按天归档，下面是周/月汇总。\n"]
+
+    # ---- 周视图（按自然周聚合）----
+    lines.append("## 按周\n")
+    # 把连续的天聚到同一周
+    weeks = {}  # week_key(周一) -> [(day, items)]
+    order = []
+    for day, items in days:
+        monday, _ = _iso_week_range(day)
+        if monday not in weeks:
+            weeks[monday] = []
+            order.append(monday)
+        weeks[monday].append((day, items))
+    for monday in sorted(order, reverse=True):
+        sunday = monday + timedelta(days=6)
+        week_items = weeks[monday]
+        total = sum(len(it) for _, it in week_items)
+        lines.append(
+            "### %s 第 %d 周（%s ~ %s）— %d 个需求\n"
+            % (monday.year, monday.isocalendar()[1], monday.isoformat(), sunday.isoformat(), total)
+        )
+        for day, items in sorted(week_items, reverse=True):
+            summary = "、".join("%s %s" % (r, t) for r, t, _ in items)
+            lines.append("- **%s**：%s" % (day.isoformat(), summary))
+        lines.append("")
+
+    # ---- 月视图 ----
+    lines.append("## 按月\n")
+    months = {}
+    morder = []
+    for day, items in days:
+        mk = (day.year, day.month)
+        if mk not in months:
+            months[mk] = []
+            morder.append(mk)
+        months[mk].append((day, items))
+    for mk in sorted(morder, reverse=True):
+        m_items = months[mk]
+        total = sum(len(it) for _, it in m_items)
+        lines.append("### %d年%d月 — %d 个需求" % (mk[0], mk[1], total))
+        for day, items in sorted(m_items, reverse=True):
+            summary = "、".join("%s" % t for _, t, _ in items)
+            lines.append("  - %s：%s" % (day.isoformat(), summary))
+        lines.append("")
+
+    (archive_root / "_index.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+# ============================================================
+# main
+# ============================================================
+
+def main():
+    args = sys.argv[1:]
+    # 过滤 flag
+    prd_args = [a for a in args if not a.startswith("-")]
+    if not prd_args:
+        print("Usage: python .qoder/scripts/archive_prd.py <prd 文件路径> [<prd2> ...]")
+        print("把 PRD 归档到当前成员的 workspace/members/{name}/archive/{日期}/")
+        sys.exit(1)
+
+    repo_root = get_repo_root()
+    ok = 0
+    for p in prd_args:
+        try:
+            if archive_one(p, repo_root):
+                ok += 1
+        except Exception as e:
+            # 非侵入：归档失败绝不影响 PRD 生成
+            print("[archive] 跳过 %s: %s" % (p, str(e)[:120]))
+    print("[archive] 完成: %d/%d 已归档" % (ok, len(prd_args)))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()