调整跨月周

main
mula.liu 2026-10-09 17:59:36 +08:00
parent 30b1eaab09
commit 7aa3b8efe4
7 changed files with 176 additions and 17 deletions

BIN
.DS_Store vendored

Binary file not shown.

View File

@ -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 <xlsx> # 指定别的文件;首次运行 .
- 台账没有的,取《周工作情况总结》「定制开发」块中该项目首次出现的周
- 再没有,依次退回 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 周)。
字段可在明细表中直接改,也可在抽屉里改;重新计算用:

View File

@ -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)
# 全部周次(算「连续几周没更新」用)

Binary file not shown.

View File

@ -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]

View File

@ -374,8 +374,8 @@
<div class="modal-body">
<div class="form-grid">
<div class="form-row full"><label>周期 *</label><select class="sel" id="udPeriod" style="width:100%">
${weeks.map((w) => `<option value="${w.id}" ${w.id === periodId ? "selected" : ""}>${esc(w.full_label)}</option>`).join("")}
</select></div>
${weeks.map((w) => `<option value="${w.id}" ${w.id === periodId ? "selected" : ""}>${esc(periodOptionLabel(w))}</option>`).join("")}
</select><div class="period-note" id="udPeriodNote"></div></div>
${fields}
<div class="form-row full"><label>内容 *</label><textarea class="inp" id="udContent" rows="5" data-autofocus style="width:100%">${esc(u ? u.content || u.summary || "" : "")}</textarea></div>
<div class="form-row full"><label>风险</label><textarea class="inp" id="udRisk" rows="2" style="width:100%">${esc(u ? u.risk || "" : "")}</textarea></div>
@ -386,6 +386,19 @@
<div class="modal-foot"><button class="btn" data-mclose>取消</button><button class="btn primary" id="mOk">${u ? "保存修改" : "添加"}</button></div>`
);
// 换周期时把这一周的归属说清楚:9/28 写的记录存进「10月第1周」是口径,不是 bug
const udPeriodNote = () => {
const box = $("#udPeriodNote");
if (!box) return;
const w = weeks.find((x) => x.id === Number($("#udPeriod").value));
if (!w) { box.innerHTML = ""; return; }
box.innerHTML = periodCrossDays(w)
? `<span class="tag-mini warn">${Ico.svg("alert")}${esc(periodCrossNote(w))}</span>`
: `<span class="tag-mini">${esc(shortDay(w.first_day))}–${esc(shortDay(w.last_day))} · 整周计入${w.month}月</span>`;
};
$("#udPeriod").addEventListener("change", udPeriodNote);
udPeriodNote();
const numVal = (id) => { const el = $(id); return el.value === "" ? null : Number(el.value); };
const wanVal = (id) => { const el = $(id); return el.value === "" ? null : Math.round(Number(el.value) * 10000); };
$("#mOk").addEventListener("click", async () => {
@ -738,6 +751,52 @@
return m && m.first_day ? { start: m.first_day, end: m.last_day, label: m.label } : null;
}
/* ------------------------------------------------- 周期口径(可见化)
周期 = 自然周(周一~周日),归属月看「这一周的周四落在哪个月」,等价于「这一周
至少 4 天在哪个月」。所以跨月周会整周算进周四那个月:2026 年 9/28(一)–10/4(日)
的周四是 10/1,9/28、9/29 写的记录就落在「10月第1周」。口径本身不动,
这里负责把日期范围和跨月事实直接标在每个周期上,免得再看错。 */
/** "2026-09-28" → "9/28" */
function shortDay(v) {
const s = String(v || "");
return s.length >= 10 ? `${Number(s.slice(5, 7))}/${Number(s.slice(8, 10))}` : "";
}
/** 周期的起止文案,如 "9/28–10/4";拿不到日期给空串 */
function periodRangeText(p) {
const a = shortDay(p && p.first_day), b = shortDay(p && p.last_day);
return a && b ? `${a}\u2013${b}` : "";
}
/** 这一周是不是跨月周 */
function periodCrossMonth(p) {
const a = String((p && p.first_day) || "").slice(0, 7);
const b = String((p && p.last_day) || "").slice(0, 7);
return !!a && !!b && a !== b;
}
/** 跨月周摊开算:归属月内几天 / 别的月几天。不跨月返回 null */
function periodCrossDays(p) {
if (!p || !p.first_day) return null;
const home = `${p.year}-${String(p.month).padStart(2, "0")}`;
let keep = 0, out = 0, other = "";
for (let i = 0; i < 7; i++) {
const d = new Date(`${p.first_day}T00:00:00`);
d.setDate(d.getDate() + i);
if (`${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}` === home) keep++;
else { out++; other = `${d.getMonth() + 1}月`; }
}
return out ? { keep, out, other } : null;
}
/** 下拉与表格里用:周期标签后面直接跟日期范围 */
function periodOptionLabel(p) {
const r = periodRangeText(p);
return r ? `${p.full_label}(${r})` : p.full_label;
}
/** 跨月周的人话说明;不跨月返回空串 */
function periodCrossNote(p) {
const c = periodCrossDays(p);
if (!c) return "";
return `跨月周:${c.other}占 ${c.out} 天、${p.month}月占 ${c.keep} 天,整周按周四所在月计入${p.month}月`;
}
/** 录入写入的周期:只认顶栏那一个周期选择器;月视图落到该月最后一周 */
function intakePeriodId() {
if (state.gran === "week") {
@ -753,7 +812,13 @@
}
function intakePeriodLabel() {
const w = (state.periods.weeks || []).find((x) => x.id === intakePeriodId());
return w ? w.full_label : "未选择周期";
return w ? periodOptionLabel(w) : "未选择周期";
}
/** 录入页的跨月提醒:9/28 录的内容会写进「10月第1周」,不写出来一定有人对不上账 */
function intakePeriodNote() {
const w = (state.periods.weeks || []).find((x) => x.id === intakePeriodId());
const note = periodCrossNote(w);
return note ? `<span class="tag-mini warn">${Ico.svg("alert")}${esc(note)}</span>` : "";
}
/* ---------------------------------------------------------------- charts */
@ -831,14 +896,23 @@
if (state.gran === "week") {
sel.innerHTML =
state.periods.weeks
.map((w) => `<option value="${w.id}" ${w.id === state.weekId ? "selected" : ""}>${esc(w.full_label)}</option>`)
.map((w) => `<option value="${w.id}" ${w.id === state.weekId ? "selected" : ""}>${esc(periodOptionLabel(w))}</option>`)
.join("") + `<option value="__new">+ 新建周期…</option>`;
} else {
sel.innerHTML = state.periods.months
.map((m, i) => `<option value="${i}" ${i === state.monthIdx ? "selected" : ""}>${esc(m.label)}(${m.week_count} 周)</option>`)
.map((m, i) => `<option value="${i}" ${i === state.monthIdx ? "selected" : ""}>${esc(m.label)}(${periodRangeText(m) || "—"} · ${m.week_count} 周)</option>`)
.join("");
}
$("#periodHint").textContent = state.gran === "week" ? "" : "月视图 · 自动汇总该月所有周";
// 口径写在顶栏:周 = 自然周(周四归属),月 = 该月各自然周的并集(不等于自然月)
if (state.gran === "week") {
$("#periodHint").textContent =
periodCrossNote(state.periods.weeks.find((w) => w.id === state.weekId));
} else {
const r = periodRangeText(currentMonth());
$("#periodHint").textContent = r
? `月口径 = 该月各自然周的并集 ${r},不等于自然月 1 号~月末`
: "月视图 · 自动汇总该月所有周";
}
}
function shiftPeriod(delta) {
@ -1188,7 +1262,7 @@
const cDyn = cSec.listed.length;
const kpi = `
<div class="grid kpi" style="margin-bottom:8px">
<div class="grid kpi kpi-row">
<div class="kpi accent-blue">${Ico.badge("star")}<div class="k-label">重点项目</div><div class="k-value">${k.key_total}</div><div class="k-foot">本期已更新 ${k.key_updated}</div></div>
<div class="kpi accent-blue">${Ico.badge("list-checks")}<div class="k-label">本周重点工作</div><div class="k-value">${focus.week.length}</div><div class="k-foot">延期 ${focus.overdue.length} 条 · 已完成 ${focus.done.length} 条</div></div>
<div class="kpi accent-violet">${Ico.badge("activity")}<div class="k-label">执行记录</div><div class="k-value">${k.update_count}</div><div class="k-foot">在办项目 ${k.project_listed} 个</div></div>
@ -1954,7 +2028,7 @@
const K = (state.finance || {}).kpi || {};
const stat = (label, box, accent, icon) =>
`<div class="kpi ${accent}">${Ico.badge(icon)}<div class="k-label">${label}</div><div class="k-value" style="font-size:22px">${fen((box || {}).amount)} 万</div><div class="k-foot">${(box || {}).count || 0} 个项目</div></div>`;
const statBar = `<div class="grid kpi" style="padding:2px 16px 12px">
const statBar = `<div class="grid kpi kpi-row">
${stat("已下单项目 / 合同额", K.placed, "accent-blue", "wallet")}
${stat("本季度下单(" + esc(C.quarter_label || "—") + ")", K.sign_quarter, "accent-violet", "trending-up")}
${stat("本年新增下单(" + (C.year || "—") + "年)", K.sign_year, "accent-violet", "trending-up")}
@ -2081,7 +2155,7 @@
const stat = (label, rows, accent, icon) =>
`<div class="kpi ${accent}">${Ico.badge(icon)}<div class="k-label">${label}</div><div class="k-value" style="font-size:22px">${fen(sum(rows, "amount"))} 万</div><div class="k-foot">${rows.length} 个项目</div></div>`;
const statBar = `<div class="grid kpi" style="padding:2px 16px 12px">
const statBar = `<div class="grid kpi kpi-row">
${stat("验收情况", acc, "accent-amber", "receipt")}
${stat("新增项目", newDeal, "accent-violet", "trending-up")}
${stat("进行中项目", doing, "accent-blue", "activity")}
@ -2607,7 +2681,7 @@
<select id="cInProject" class="sel" style="width:320px">
${projects.map((p) => `<option value="${p.id}" ${p.id === customIntakeId ? "selected" : ""}>${p.is_key ? "★ " : ""}${esc(p.name)}</option>`).join("")}
</select>
<span class="field-mini">写入周期<b>${esc(intakePeriodLabel())}</b></span>
<span class="field-mini">写入周期<b>${esc(intakePeriodLabel())}</b>${intakePeriodNote()}</span>
</div>
<div class="step" style="margin-bottom:10px"><span class="step-no">2</span><span class="step-title">粘贴该项目的原始内容</span></div>
@ -2804,7 +2878,7 @@
<option value="__new">+ 新建项目(按下方名称)</option>
</select>
<input id="intakeNewProject" class="inp" placeholder="新项目名称" style="width:220px;display:none" />
<span class="field-mini">写入周期<b>${esc(intakePeriodLabel())}</b></span>
<span class="field-mini">写入周期<b>${esc(intakePeriodLabel())}</b>${intakePeriodNote()}</span>
</div>
<div class="step" style="margin-bottom:10px"><span class="step-no">2</span><span class="step-title">粘贴该项目的原始内容</span></div>
@ -3009,11 +3083,12 @@
</div>
<div class="card-body" style="max-height:360px;overflow:auto;padding:0">
<table class="tbl">
<thead><tr><th>周期</th><th class="num">常规记录</th><th class="num">定制记录</th><th></th></tr></thead>
<thead><tr><th>周期</th><th>起止日期</th><th class="num">常规记录</th><th class="num">定制记录</th><th></th></tr></thead>
<tbody>
${pagedRows(weeks, "periods").map((w) => `
<tr data-pid="${w.id}">
<td><b>${esc(w.full_label)}</b></td>
<td class="nowrap">${esc(periodRangeText(w) || "—")}${periodCrossMonth(w) ? ` <span class="tag-mini warn">跨月周</span>` : ""}</td>
<td class="num">${w.update_count || 0}</td>
<td class="num">${w.custom_update_count || 0}</td>
<td class="num">${rw ? `<button class="btn sm danger" data-delperiod="${w.id}" ${(w.update_count || w.custom_update_count) ? "disabled title='该周期已有记录,不能删除'" : ""}>删除</button>` : ""}</td>
@ -3385,7 +3460,7 @@
(d.dict.groups || []).map((g) => `<option value="${esc(g)}" ${g === state.staffGroup ? "selected" : ""}>${esc(g)}</option>`).join("");
const kpi = `
<div class="grid kpi" style="margin-bottom:14px">
<div class="grid kpi kpi-row">
<div class="kpi accent-blue">${Ico.badge("users")}<div class="k-label">在册人员</div><div class="k-value">${sum.total}</div><div class="k-foot">其中 ${sum.with_project} 人带项目</div></div>
${sum.groups.slice(0, 4).map((g, i) => `<div class="kpi accent-${["violet", "green", "amber", "red"][i % 4]}">${Ico.badge("users")}<div class="k-label">${esc(g.name)}</div><div class="k-value">${g.count}</div></div>`).join("")}
</div>

View File

@ -249,6 +249,7 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
.rbac-role .desc { display: block; margin-top: 3px; }
.staff-note { max-width: 190px; font-size: 12px; color: var(--muted); }
.tag-mini.builtin { background: #eef2ff; color: #4f46e5; }
.tag-mini.warn { background: #fff4e0; color: #b45309; }
/* ---------------- main ---------------- */
.main { flex: 1; min-width: 0; display: flex; flex-direction: column; }
@ -288,9 +289,15 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
.nav-arrow:hover { border-color: var(--border-strong); color: var(--text); }
.period-select {
height: 32px; border: 1px solid var(--border); border-radius: var(--radius-sm);
padding: 0 10px; background: #fff; min-width: 170px; cursor: pointer;
padding: 0 10px; background: #fff; min-width: 216px; cursor: pointer;
}
.period-hint { color: var(--muted); font-size: 12px; margin-left: 4px; }
/* 顶栏的周期口径提示可能较长:限宽省略,别把搜索框挤走 */
.period-bar .period-hint {
min-width: 0; max-width: 34vw; white-space: nowrap;
overflow: hidden; text-overflow: ellipsis;
}
@media (max-width: 1180px) { .period-bar .period-hint { display: none; } }
.topbar-right { display: flex; gap: 10px; align-items: center; }
.search {
height: 32px; border: 1px solid var(--border); border-radius: var(--radius-sm);
@ -376,6 +383,17 @@ tr:hover .row-ops, .row-ops:focus-within { opacity: 1; }
.kpi.accent-amber { --c: var(--amber); }
.kpi.accent-red { --c: var(--red); }
/* ---------------- 统计区块的上下留白(各页统一) ----------------
口径:统计行上方一律 24px、下方一律 20px,四个页面看着一样。
· 贴在页面顶部的(工作看板 / 人力资源):.views 的上内边距先垫 20px,这里再补 4px;
· 在卡片里的(定制项目 · 项目总览 / 本周进展):卡头底下自己出满 24px。
新增统计行请只挂 .kpi-row,不要再写行内 margin / padding。 */
.grid.kpi.kpi-row { margin: 4px 0 20px; }
.card > .grid.kpi.kpi-row { margin: 24px 0 20px; padding: 0 16px; }
.card > .grid.kpi.kpi-row:last-child { margin-bottom: 24px; }
/* 表单里周期的口径说明 */
.period-note { margin-top: 6px; }
/* ---------------- board ---------------- */
.board-toolbar { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin-bottom: 10px; }
.chip {