# 周计划看板 · Markdown 映射说明

本目录与 `content/` 同级，存放每周看板数据（**一个 `.md` 文件 = 一个自然周**）。  
`content/kanban/` 中的页面通过符号链接指向此处，Zola 构建列表/详情；前端通过 `/kanban/<文件名>.md` 读取原始 Markdown 供规则引擎解析。

## 文件命名

| 规则 | 示例 |
|------|------|
| 以本周**周一**日期命名 | `2026-06-16.md`（对应 6.16 – 6.22） |
| 路径 | `kanban/2026-06-16.md` |

## Front Matter（页面元数据）

```toml
+++
title = "6.16 – 6.22 周计划"
description = "列表页摘要，可选"
date = 2026-06-16
template = "kanban.html"
[extra]
week_start = "2026-06-16"
week_end = "2026-06-22"
core_tasks = "本周核心任务一句话"
stats = { total = 8, done = 3, todo = 3, doing = 2 }
+++
```

| 字段 | 说明 |
|------|------|
| `week_start` / `week_end` | 可编辑窗口（含首尾日，东八区） |
| `core_tasks` | 列表卡片展示的核心任务 |
| `stats` | 进度统计（按列名自动计算） |

---

## 结构映射

| Markdown | 看板元素 |
|----------|----------|
| `# 列表名` | **一列**（待办 / 进行中 / 已完成 / 资源 / 目标） |
| `## 卡片标题` | **一张卡片**，归属上方最近的 `#` 列表 |

列顺序 = 文件中 `#` 出现顺序。  
卡片顺序 = 各列内 `##` 出现顺序。

---

## 卡片属性 · 规则引擎指令

指令单独占一行，写在 `## 标题` 之后、正文之前。以 `@` 开头，**大小写不敏感**。

| 指令 | 语法 | 看板表现 |
|------|------|----------|
| 截止日期 | `@due 2026-06-20` | 卡片底部截止图标 + 日期 |
| 开始日期 | `@start 2026-06-16` | 卡片底部开始图标 + 日期 |
| 重要等级 | `@priority 4` 或 `@importance 4` | 1–5 星（淡黄色，满星填充） |
| 目标类型 | `@goal complete` / `@goal risk` | 目标看板：完成效果（淡蓝）/ 未完成后果（灰爆） |
| 颜色标签 | `@labels red, blue` 或 `@label green` | 明细页顶栏色条（权重 n）；列表页不显示 |
| 顶栏色 | `@top red` 或 `@top orange` | 明细页卡片顶部粗色条（Trello 顶栏） |
| 背景色 | `@bg orange` 或 `@bg #FFE0B2` | 整卡背景色 |
| 顶栏色 | `@top red` 或 `@top #E53935` | 卡片顶部色块（Trello 顶栏） |
| 勾选框 | `- [ ] 未完成` / `- [x] 已完成` | 卡片内 checklist |

### 预置标签色名

`red` · `orange` · `yellow` · `green` · `blue` · `purple` · `pink` · `sky` · `lime` · `black`

也支持 `#RGB` / `#RRGGBB` 十六进制。

### 描述正文

除 `@` 指令与 checkbox 行以外的 Markdown（段落、列表、加粗等）→ 卡片**描述区**。

---

## 完整示例

```markdown
# 待办

## 规则引擎文档
@due 2026-06-18
@labels blue, green
@top purple

- [ ] 编写 kanban-rules.js
- [ ] 补充映射说明

完成 **Markdown ↔ 看板** 双向转换说明。

# 进行中

## 看板 UI
@bg #FFF3E0
@top orange
@due 2026-06-20

- [x] Trello 列布局
- [ ] 拖拽交互

# 已完成

## 需求梳理
@labels green

- [x] 对齐 article / nanolog 结构
```

---

## 编辑方式

| 状态 | 行为 |
|------|------|
| **锁定**（默认） | 不可拖拽；隐藏 ReDeplog / Edit Post / 映射说明 |
| **解锁** | 仅在 `week_start`～`week_end`（东八区）内可切换；可拖拽卡片跨列（本地预览） |
| **保存** | 点击 **Edit Post**：先将当前看板按映射规则序列化写入 `kanban/_edit-buffer.md`（缓冲），再覆盖 `kanban/<周>.md`；无 Token 时复制到剪贴板并在 Codeberg 编辑器粘贴 |
| **超期** | 超过 `week_end` 后永久只读，无法解锁 |

---

## 列表页进度色

**仅「待办 / 进行中 / 已完成」三列参与进度；「资源 / 目标」不参与。**

### 背景色规则

| 条件 | 卡片背景 |
|------|----------|
| `todo > 3` | 全红 `#FFEBEE` |
| `done == total` 且 total > 0 | 浅绿 `#E8F5E9` |
| 其余 | 按加权进度百分比渐变（红 → 黄 → 绿） |

### 加权进度公式

以 **50%** 为基准，逐卡片累加（标签数 `n` 为权重，无标签时 `n = 1`）：

| 所在列 | 单项贡献 |
|--------|----------|
| 待办 | **−10% × n** |
| 进行中 | **+5% × n** |
| 已完成 | **+15% × n** |

例：进行中列卡片有 2 个 `@labels` → **+5% × 2 = +10%**。

结果 clamp 至 0–100%，写入 front matter `stats.progress_pct`。

列表页标题显示 `core_tasks`（非日期）；元信息行含开始 / 截止 / 剩余天数 / 星级（`importance` 字段，1–5）。

---

## 相关文件

| 文件 | 作用 |
|------|------|
| `static/js/kanban-rules.js` | 解析 / 序列化规则引擎 |
| `static/js/kanban-board.js` | 看板 UI、锁定、拖拽、Edit Post 缓冲写入 |
| `static/js/kanban-list.js` | 列表页剩余天数、动态刷新进度 |
| `kanban/_edit-buffer.md` | Edit Post 前的 Markdown 缓冲文件 |
| `templates/kanban.html` | 周计划明细（Trello 风格） |
| `templates/kanban_list.html` | 周计划列表 |

示例看板：`kanban/2026-06-16.md`