diff --git a/.DS_Store b/.DS_Store index 6096b82..607424f 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/README.md b/README.md index 06897bb..a2cae87 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,30 @@ ## 周期管理 +### 周期口径:自然周 + 周四归属 + +一周 = **自然周(周一~周日)**;这一周算哪个月,看**它的周四落在哪个月**(等价于「这一周至少 4 天在本月」)。实现见 `app/constants.py` 的 `month_week1()` 与 `week_of_date()`,两者互为逆运算。 + +2026 年的跨月边界: + +| 周期 | 日期范围 | 说明 | +|---|---|---| +| 2026年9月第3周 | 09/14–09/20 | | +| 2026年9月第4周 | 09/21–09/27 | 9 月就这 4 个自然周(整个 9 月 = 08/31–09/27) | +| **2026年10月第1周** | **09/28**–10/04 | 周四是 10/1 → 整周计入 10 月 | + +所以 **9/28(一)、9/29(二)、9/30(三) 写的记录统计在 10 月**:9/28 一打开页面,顶栏的默认周期已经是「10月第1周」(`GET /api/periods` 用 `week_of_date(today)` 定位当期,`app/routers/board.py`),录入时写进去的 `period_id` 就是它。 + +推论:**月口径 = 该月各自然周的并集,不等于自然月 1 号~月末**(2026年9月 = 08/31–09/27、2026年10月 = 09/28–11/01)。这是「一周 7 天」+「一周不跨月」的必然结果——月份不是 7 天的整数倍,一个月只可能是 **4 或 5 周**(不是固定 4 周,第 5 周是合法周期,`_week_period()` 遇到会自动建),月底那几天总要归到某一边。 + +口径已经直接标在界面上,不用靠记忆: + +- 顶栏周期下拉带日期范围:`2026年10月第1周(9/28–10/4)`、`2026年10月(9/28–11/1 · 5 周)` +- 跨月周在顶栏右侧、录入页「写入周期」旁、执行/交付记录弹窗里挂橙色「跨月周」提示,写明几天在 9 月、几天在 10 月 +- 设置 → 周期管理 有「起止日期」列,跨月的行标「跨月周」 + +边界规则由 `tests/test_periods_projects.py::test_跨月周按周四所在月归属` 锁死。**要换口径**(改成「周一所在月」,或记录带真实日期后「按自然日归月」)**必须连带迁移历史 `period_id` 并核对已发布过的数字**,不要只改函数。 + ### 新增周期 三个入口,都会自动接续年份: @@ -313,8 +337,8 @@ python scripts/import_staff.py # 指定别的文件;首次运行 . - 台账没有的,取《周工作情况总结》「定制开发」块中该项目首次出现的周 - 再没有,依次退回 custom_updates 最早记录周期 → 项目所属周期 → 记录创建日期 -周期换算规则:以**该月第一个周一**所在周为第 1 周,第 N 周顺延 `7×(N-1)` 天。 -例如 `2026年8月第4周` → `2026-08-24`(2026-08-01 是周六,第一个周一是 08-03)。 +周期换算规则:第 1 周 = **第一个周四落在本月的那一周**(见上「周期口径」),第 N 周顺延 `7×(N-1)` 天,取该周周一。 +例如 `2026年8月第4周` → `2026-08-24`(8 月第 1 周是 08/03–08/09);`2026年9月第1周` → `2026-08-31`(周一在上个月,照样算 9 月第 1 周)。 字段可在明细表中直接改,也可在抽屉里改;重新计算用: diff --git a/app/routers/weekly.py b/app/routers/weekly.py index 4f481cb..188e9f8 100644 --- a/app/routers/weekly.py +++ b/app/routers/weekly.py @@ -49,7 +49,8 @@ def weekly( periods = db.query(Period).filter(Period.id.in_(period_ids)).order_by(Period.sort_key).all() scope_sort = max(p.sort_key for p in periods) # 本周期(月视图 = 该月所有周)的日期范围,用来判断「本周期新入库」, - # 口径与「入库时间」一致:该月第一个周一算第 1 周 + # 口径与「入库时间」一致:第 1 周 = 第一个周四落在本月的那一周(constants.month_week1), + # 所以月范围不等于自然月,跨月周整周算进周四那个月 scope_start = min(constants.period_first_day(p.year, p.month, p.week) for p in periods) scope_end = max(constants.period_last_day(p.year, p.month, p.week) for p in periods) # 全部周次(算「连续几周没更新」用) diff --git a/data/board.db b/data/board.db index 999b95f..74949d4 100644 Binary files a/data/board.db and b/data/board.db differ diff --git a/tests/test_periods_projects.py b/tests/test_periods_projects.py index ab4ff6e..202eba0 100644 --- a/tests/test_periods_projects.py +++ b/tests/test_periods_projects.py @@ -1,6 +1,8 @@ """周期、元信息、常规项目 / 分类 / 标签 / 执行记录 / 设置。""" from __future__ import annotations +from datetime import date, timedelta + from app import constants @@ -19,6 +21,45 @@ def test_周期列表会自动补出今天所在的周(h): assert sum(x["week_count"] for x in data["months"]) == len(data["weeks"]) +def test_跨月周按周四所在月归属(): + """口径锁死:一周 = 自然周(周一~周日),归属月看这一周的周四落在哪个月。 + + 2026-09-28 是周一,所在的周是 09/28–10/04,周四是 10/1 → 整周归 10月第1周, + 所以 9/28、9/29 写的记录统计在 10 月。这是口径不是 bug(界面已把日期范围与 + 跨月事实标在顶栏、录入页和周期管理上)。改这条规则要连带迁移历史 period_id。 + """ + assert constants.week_of_date(date(2026, 9, 27)) == (2026, 9, 4) # 9 月到这天为止 + assert constants.week_of_date(date(2026, 9, 28)) == (2026, 10, 1) # ← 争议边界 + assert constants.week_of_date(date(2026, 9, 30)) == (2026, 10, 1) + assert constants.week_of_date(date(2026, 10, 1)) == (2026, 10, 1) + assert constants.week_of_date(date(2026, 10, 4)) == (2026, 10, 1) + assert constants.week_of_date(date(2026, 10, 5)) == (2026, 10, 2) + # 9 月只有 4 个自然周,10 月有 5 个:一个月不可能正好 4 周 + assert constants.period_first_day(2026, 9, 1) == "2026-08-31" + assert constants.period_last_day(2026, 9, 4) == "2026-09-27" + assert constants.period_first_day(2026, 10, 1) == "2026-09-28" + assert constants.period_last_day(2026, 10, 5) == "2026-11-01" + + # period_first_day / week_of_date 互为逆运算 + for y, m, w in [(2026, 1, 1), (2026, 9, 4), (2026, 10, 1), (2026, 10, 5), (2027, 2, 4)]: + first = date.fromisoformat(constants.period_first_day(y, m, w)) + assert constants.week_of_date(first) == (y, m, w) + assert constants.period_last_day(y, m, w) == (first + timedelta(days=6)).isoformat() + + # 全年按天扫一遍:每天都有唯一归属、不重不漏,每月周数是 4 或 5 + per_month: dict[int, set] = {} + day = date(2026, 1, 1) + while day.year == 2026: + y, m, w = constants.week_of_date(day) + assert y == 2026 + per_month.setdefault(m, set()).add(w) + day += timedelta(days=1) + assert len(per_month) == 12 + for m, weeks in per_month.items(): + assert weeks == set(range(1, len(weeks) + 1)), f"2026-{m:02d} 周数不连续:{sorted(weeks)}" + assert len(weeks) in (4, 5), f"2026-{m:02d} 有 {len(weeks)} 周" + + def test_新建周期会按标签推年份并跨年(h): base = h.periods()["today_id"] latest = [w for w in h.periods()["weeks"] if w["id"] == base][0] diff --git a/web/app.js b/web/app.js index a45f5e5..c41c207 100644 --- a/web/app.js +++ b/web/app.js @@ -374,8 +374,8 @@