@adonis0123/weekly-report 1.0.5

package/references/WEEKLY_REPORT_FORMAT.md

@@ -0,0 +1,116 @@
+# 周报格式规范
+
+## 角色定义
+
+你是一位专业的技术周报总结专家，擅长从 Git commit 记录或文字描述中提炼关键工作内容，生成简洁、结构化的周报摘要。
+
+## 任务目标
+
+将一周的工作内容（Git commit 记录截图或文字描述）提炼为结构化的周报总结。
+
+## 输入来源
+
+- **文字输入**：直接提供的工作内容描述
+- **Git 提交**：一周的 Git commit 提交记录
+
+## 输出格式
+
+使用 Markdown 格式，按项目分组，采用层级列表结构：
+
+```
+项目名称
+  - 主要工作点（必须，10 字以内，最长不超过 20 字）
+    - 补充说明（可选）
+      - 更详细的补充（可选）
+
+其他
+  - 不属于特定项目的工作内容
+```
+
+## 总结原则
+
+### 必须遵守
+
+1. **事实导向**：只总结实际完成的工作，不添加虚构或修饰性内容
+2. **简洁精炼**：主要工作点控制在 10 字以内，绝对不超过 20 字
+3. **重点突出**：只保留重要内容，过滤掉琐碎的修改
+4. **按项目分组**：相同项目的工作归类到一起
+5. **层级清晰**：用缩进表示内容的从属关系
+
+### 过滤规则
+
+以下类型的 commit 通常不需要单独列出：
+
+- 纯格式化/代码风格调整（除非是大规模重构）
+- 简单的 typo 修复
+- 依赖版本小幅更新（除非涉及重大升级）
+- 重复性的相似提交（合并为一条）
+- Merge commit
+
+### 合并规则
+
+- 相关联的多个小改动合并为一个主题
+- 同一功能的多次迭代合并为一条记录
+- 问题排查和解决归为一条
+
+## 输出示例
+
+### 示例 1
+
+```
+project-frontend
+  - 构建工具升级改造及问题排查
+  - 核心功能开发流程跟进
+    - 异常处理优化
+    - 方案合理性优化
+    - 问题边界定义
+  - 对话头像渲染
+  - 脚本国际化检查优化
+
+其他
+  - 新版国际化方案讨论
+```
+
+### 示例 2
+
+```
+project-backend
+  - 自定义类型化流式消息渲染
+  - 异常状态调试优化
+    - 支持 debug 模式
+    - 原始消息结构查看
+  - device id 修复及有效期处理
+  - 断线重连流程梳理
+
+其他
+  - 全局弹窗缺陷修复
+```
+
+### 示例 3
+
+```
+project-frontend
+  - 前后端分离方案跟进
+    - 拆分服务（web/admin/server）
+    - 统一转发代理消除跨域
+  - 活动页需求设计
+    - 支持免发版管理
+    - SDK 方案调通
+  - SEO 预渲染方案
+
+project-backend
+  - 断线重连方案实现
+    - 自动重试失败后提示刷新
+  - 依赖库升级尝试
+
+其他
+  - 多媒体资源运营管理方案讨论
+```
+
+## 注意事项
+
+1. 如果输入是图片，请仔细识别 commit 信息，按时间和项目归类
+2. commit message 中的技术术语可以保留，但要确保表述通顺
+3. 如有多个项目，按工作量或重要性排序
+4. "其他"分类用于放置不属于特定项目的工作内容
+5. 如果某周工作内容较少，如实反映即可，不需要刻意扩充

package/src/__init__.py

@@ -0,0 +1,3 @@
+"""Weekly Flow - Git 提交记录周报生成工具"""
+
+__version__ = "1.0.0"

package/src/config_manager.py

@@ -0,0 +1,171 @@
+"""配置管理模块
+
+管理周报工具的配置，包括仓库列表等。
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# 默认配置
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "repos": [],
+    "default_author": "auto",
+    "output_format": "markdown",
+}
+
+
+def get_config_path(base_dir: Optional[Path] = None) -> Path:
+    """获取配置文件路径
+
+    Args:
+        base_dir: 基础目录，默认为 ~/.weekly-reports
+
+    Returns:
+        配置文件路径
+    """
+    if base_dir is None:
+        base_dir = Path.home() / ".weekly-reports"
+
+    return base_dir / "config.json"
+
+
+def load_config(config_path: Optional[Path] = None) -> Dict[str, Any]:
+    """加载配置文件
+
+    Args:
+        config_path: 配置文件路径，默认为 ~/.weekly-reports/config.json
+
+    Returns:
+        配置字典
+    """
+    if config_path is None:
+        config_path = get_config_path()
+
+    if not config_path.exists():
+        return DEFAULT_CONFIG.copy()
+
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+            # 合并默认配置，确保所有字段都存在
+            return {**DEFAULT_CONFIG, **config}
+    except (json.JSONDecodeError, OSError):
+        return DEFAULT_CONFIG.copy()
+
+
+def save_config(
+    config: Dict[str, Any],
+    config_path: Optional[Path] = None,
+) -> None:
+    """保存配置文件
+
+    Args:
+        config: 配置字典
+        config_path: 配置文件路径
+    """
+    if config_path is None:
+        config_path = get_config_path()
+
+    # 确保父目录存在
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+
+
+def add_repo(
+    config: Dict[str, Any],
+    name: str,
+    path: str,
+) -> Dict[str, Any]:
+    """添加仓库到配置
+
+    Args:
+        config: 配置字典
+        name: 仓库名称
+        path: 仓库路径
+
+    Returns:
+        更新后的配置
+    """
+    repos = config.get("repos", [])
+
+    # 检查是否已存在
+    for repo in repos:
+        if repo["name"] == name:
+            # 更新路径
+            repo["path"] = path
+            return config
+
+    # 添加新仓库
+    repos.append({"name": name, "path": path})
+    config["repos"] = repos
+
+    return config
+
+
+def remove_repo(config: Dict[str, Any], name: str) -> Dict[str, Any]:
+    """从配置中移除仓库
+
+    Args:
+        config: 配置字典
+        name: 仓库名称
+
+    Returns:
+        更新后的配置
+    """
+    repos = config.get("repos", [])
+    config["repos"] = [r for r in repos if r["name"] != name]
+    return config
+
+
+def get_repos(config: Dict[str, Any]) -> List[Dict[str, str]]:
+    """获取仓库列表
+
+    Args:
+        config: 配置字典
+
+    Returns:
+        仓库列表
+    """
+    return config.get("repos", [])
+
+
+def validate_repo(path: Path) -> Tuple[bool, Optional[str]]:
+    """验证仓库路径是否有效
+
+    Args:
+        path: 仓库路径
+
+    Returns:
+        (is_valid, error_message)
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.exists():
+        return False, f"路径不存在: {path}"
+
+    if not path.is_dir():
+        return False, f"路径不是目录: {path}"
+
+    git_dir = path / ".git"
+    if not git_dir.exists():
+        return False, f"不是有效的 Git 仓库: {path}"
+
+    return True, None
+
+
+def get_repo_paths(config: Dict[str, Any]) -> List[Path]:
+    """获取所有仓库路径
+
+    Args:
+        config: 配置字典
+
+    Returns:
+        仓库路径列表
+    """
+    repos = get_repos(config)
+    return [Path(r["path"]) for r in repos]

package/src/date_utils.py

@@ -0,0 +1,272 @@
+"""日期处理工具模块
+
+提供周报日期范围计算和验证功能。
+"""
+
+from datetime import date, datetime, timedelta, timezone
+from typing import Optional, Tuple
+
+from dateutil.relativedelta import relativedelta
+
+
+# 中国时区（东八区）
+CHINA_TZ = timezone(timedelta(hours=8))
+
+
+def get_today_china() -> date:
+    """获取中国时区（东八区）的今天日期
+
+    Returns:
+        中国时区的今天日期
+    """
+    return datetime.now(CHINA_TZ).date()
+
+
+def get_week_range(offset: int = 0) -> Tuple[date, date]:
+    """获取指定周的日期范围（周一到周日）
+
+    Args:
+        offset: 周偏移量，0 表示本周，-1 表示上周，以此类推
+
+    Returns:
+        (start_date, end_date): 周一和周日的日期元组
+        如果周日在未来，则结束日期为今天
+    """
+    today = get_today_china()
+
+    # 计算本周一
+    days_since_monday = today.weekday()
+    current_monday = today - timedelta(days=days_since_monday)
+
+    # 应用偏移量
+    target_monday = current_monday + timedelta(weeks=offset)
+    target_sunday = target_monday + timedelta(days=6)
+
+    # 结束日期不能超过今天
+    end_date = min(target_sunday, today)
+
+    return target_monday, end_date
+
+
+def validate_date_range(
+    start: date, end: date
+) -> Tuple[bool, Optional[str]]:
+    """验证日期范围是否有效
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        (is_valid, error_message): 验证结果和错误信息
+    """
+    today = get_today_china()
+
+    # 检查开始日期是否晚于结束日期
+    if start > end:
+        return False, "开始日期不能晚于结束日期"
+
+    # 检查是否选择了未来日期
+    if end > today:
+        return False, "不能选择未来日期"
+
+    # 检查开始日期是否是周一
+    if start.weekday() != 0:
+        return False, "开始日期必须是周一"
+
+    return True, None
+
+
+def is_valid_week(start: date, end: date) -> bool:
+    """检查是否为有效的周一到周日
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        是否为有效的完整周
+    """
+    # 开始日期必须是周一
+    if start.weekday() != 0:
+        return False
+
+    # 结束日期必须是周日
+    if end.weekday() != 6:
+        return False
+
+    # 间隔必须是 6 天（同一周）
+    if (end - start).days != 6:
+        return False
+
+    return True
+
+
+def get_week_number(d: date) -> int:
+    """获取日期所在的周数
+
+    Args:
+        d: 日期
+
+    Returns:
+        ISO 周数 (1-53)
+    """
+    return d.isocalendar()[1]
+
+
+def format_date_range(start: date, end: date) -> str:
+    """格式化日期范围为字符串
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        格式化的日期范围字符串
+    """
+    return f"{start.isoformat()} ~ {end.isoformat()}"
+
+
+def get_available_weeks(count: int = 5) -> list:
+    """获取可选择的周列表
+
+    Args:
+        count: 返回的周数量
+
+    Returns:
+        周列表，每项包含 (offset, start_date, end_date, label)
+    """
+    weeks = []
+    for i in range(count):
+        offset = -i
+        start, end = get_week_range(offset)
+
+        if i == 0:
+            label = "本周"
+        elif i == 1:
+            label = "上周"
+        else:
+            label = f"{i} 周前"
+
+        weeks.append({
+            "offset": offset,
+            "start": start,
+            "end": end,
+            "label": label,
+            "display": f"{label} ({format_date_range(start, end)})",
+        })
+
+    return weeks
+
+
+# ==================== 时间段报告相关函数 ====================
+
+
+def get_half_year_range() -> Tuple[date, date]:
+    """获取前半年的日期范围
+
+    从当前时间往前推 6 个自然月。
+
+    Returns:
+        (start_date, end_date): 从 6 个月前到今天的日期元组
+    """
+    today = get_today_china()
+    # 使用 relativedelta 计算 6 个月前的日期
+    start_date = today - relativedelta(months=6)
+    return start_date, today
+
+
+def validate_custom_date_range(start: date, end: date) -> Tuple[bool, Optional[str]]:
+    """验证自定义日期范围（无周一限制）
+
+    用于时间段报告的日期验证，允许任意日期作为起始日。
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        (is_valid, error_message): 验证结果和错误信息
+    """
+    today = get_today_china()
+
+    # 检查开始日期是否晚于结束日期
+    if start > end:
+        return False, "开始日期不能晚于结束日期"
+
+    # 检查是否选择了未来日期
+    if end > today:
+        return False, "不能选择未来日期"
+
+    return True, None
+
+
+def format_date_for_filename(start: date, end: date) -> str:
+    """生成用于文件名的日期范围字符串
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        格式为 "YYYY-MM-DD_to_YYYY-MM-DD"
+    """
+    return f"{start.isoformat()}_to_{end.isoformat()}"
+
+
+def format_period_title(start: date, end: date) -> str:
+    """生成时间段报告的标题
+
+    Args:
+        start: 开始日期
+        end: 结束日期
+
+    Returns:
+        格式为 "YYYY-MM-DD ~ YYYY-MM-DD"
+    """
+    return format_date_range(start, end)
+
+
+def get_available_time_ranges() -> list:
+    """获取可选择的时间范围列表（包含周报和时间段报告选项）
+
+    Returns:
+        时间范围列表，每项包含 type, start, end, label, display
+        type 可选值: "week" 或 "period"
+    """
+    ranges = []
+
+    # 添加本周和上周（保持原有逻辑）
+    weeks = get_available_weeks(count=2)
+    for week in weeks:
+        ranges.append({
+            "type": "week",
+            "offset": week["offset"],
+            "start": week["start"],
+            "end": week["end"],
+            "label": week["label"],
+            "display": week["display"],
+        })
+
+    # 添加前半年选项
+    half_year_start, half_year_end = get_half_year_range()
+    ranges.append({
+        "type": "period",
+        "period_name": "前半年",
+        "start": half_year_start,
+        "end": half_year_end,
+        "label": "前半年",
+        "display": f"前半年 ({format_date_range(half_year_start, half_year_end)})",
+    })
+
+    # 添加自定义时间段选项
+    ranges.append({
+        "type": "period",
+        "period_name": "custom",
+        "start": None,  # 用户输入
+        "end": None,    # 用户输入（今天）
+        "label": "自定义时间段",
+        "display": "自定义时间段（输入起始日期，截止到今天）",
+    })
+
+    return ranges