# 管理页六类文件与节点详情约定

本约定管三件事：一张图交付时落在业务仓库的哪些文件里、每个文件长什么样才合法、节点详情（details.md）怎么写。图的画法与校验见 [workflow.md](workflow.md)（workflow.json 本身不在本文重复）；业务规格怎么写见 [specification.md](specification.md)。依据插件源码与 README D2 节静态整理（2026-09-17），首次真实使用在计划步骤 2。

## 1. 目录总览与路径基准

插件只认一种组织方式（约定根 `docs/archify/`，业务仓库根相对）：

```text
<业务仓库>/
  docs/archify/
    project.json                        # 项目（整仓一份）
    <业务id>/business.json              # 业务（每业务一份）
    <业务id>/<图id>/chart.json          # 图说明（每图一份）
    <业务id>/<图id>/workflow.json       # 图源（Archify workflow JSON）
    <业务id>/<图id>/details.md          # 节点详情
    <业务id>/<图id>/evidence.json       # 源码证据引用
  docs/…、src/…                         # 业务文档与源码留在原位，只引用不搬动
```

- **路径基准**：business.json 里 `docs` 数组、evidence.json 里 `path`，一律写**业务仓库根相对路径**（正斜杠分隔），不是相对 `docs/archify/`，也不写盘符绝对路径。
- **id 即目录名**：业务 id、图 id 就是各自的目录名；插件按目录遍历，说明文件里的 `id` 与目录名不一致会直接标记说明文件问题。
- **业务 id 与图 id 的硬限制**：必须匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（字母或数字开头，其余只能是字母、数字、点、下划线、连字符）——这是管理页路由与 API 的统一校验（`src/dsh/index.ts` 的 `ID_PATTERN`）。说明文件字段检查只看 id＝目录名，**id 不合规的业务/图照样进不去页面、调不了 API**：目录名用中文，即使说明文件全对也访问不了。
- **命名建议（硬限制之内从严）**：沿用 workflow 节点 id 的风格——字母开头，可含数字、下划线、连字符，不用点，不写中文、空格、斜杠。快照标签名形如 `archify/<图编号>/<版本标识>`，图 id 会进标签名，保持朴素少踩坑。
- **图编号全项目唯一**：跨业务也不允许重复。重复时两边都标记编号冲突、该图阅读停用——历史快照按图编号归组，重了分不清归属。

## 2. 六类文件逐个约定

下例合成一个最小项目（一段业务、一张图），字段值是编的，形状对齐插件自带合法样本（`sample/generate.mjs`）与源码校验规则。"最小合法"指缺了会报错、再少写一个字段就不成立；**已有文件只改要改的字段，其余内容原样保留，不整份重建**（插件只校验下表字段，不拒绝额外字段，静态核对结论）。

### 2.1 project.json（项目）

```json
{
  "schema": "specdev-archify/project/1",
  "name": "示例项目名"
}
```

| 字段 | 必填 | 含义 |
|---|---|---|
| `schema` | 是 | 固定 `"specdev-archify/project/1"`，一字不差 |
| `name` | 是 | 项目显示名（首页标题），非空 |
| `description` | 否 | 项目一句话说明 |

规则：整仓只有这一份；`schema` 不对或 `name` 缺失时首页直接报错。项目里已有其他字段（如 `description`、后续业务信息）保留不动。

### 2.2 business.json（业务）

```json
{
  "schema": "specdev-archify/business/1",
  "id": "activity-registration",
  "name": "活动报名",
  "intro": "一句话业务介绍。",
  "docs": ["docs/活动报名说明.md"]
}
```

| 字段 | 必填 | 含义 |
|---|---|---|
| `schema` | 是 | 固定 `"specdev-archify/business/1"` |
| `id` | 是 | 业务 id，**必须与目录名一致** |
| `name` | 是 | 业务显示名，非空 |
| `intro` | 否 | 业务介绍（业务页展示） |
| `docs` | 否 | 业务文档路径数组：仓库根相对路径，引用原位文档，不复制 |

规则：

- **文档留在原位**：`docs` 只登记路径；业务文档放仓库哪里都行，管理页按路径去读。
- **页面只读声明过的路径**：不在 `docs` 里的路径，管理页拒绝读取；声明了但工作区文件不存在，会明确报"文档不存在"。所以每条路径写完自查文件在不在。
- 已有业务再添图时，这份文件通常不用动。

### 2.3 chart.json（图说明）

```json
{
  "schema": "specdev-archify/chart/1",
  "id": "submit-review",
  "name": "提交复核流程",
  "summary": "一句话图摘要。"
}
```

| 字段 | 必填 | 含义 |
|---|---|---|
| `schema` | 是 | 固定 `"specdev-archify/chart/1"` |
| `id` | 是 | 图编号，**必须与目录名一致，且全项目唯一** |
| `name` | 是 | 图显示名（业务页图列表、阅读页标题） |
| `summary` | 否 | 图摘要（图列表展示） |

规则：新建图前先确认这个编号没被别的业务用掉（含历史遗留目录）。

### 2.4 workflow.json（图源，同图目录）

- **原生 Archify workflow JSON**：字段、制作流程、showcase 校验五判据全部见 [workflow.md](workflow.md)，本文不重复。
- **不自创插件没约定的业务字段**：插件把这份文件原样交给 Archify 渲染，业务语义走 details.md 与 evidence.json；Archify schema 也不允许额外字段，塞了只会校验失败。
- 缺失时阅读页明确报"缺图文件"，不给空白页；文件超过 2MB 读取上限会报"读不开"——图源保持精炼，不往里塞大段填充。

### 2.5 details.md（节点详情，同图目录）

分节约定（插件的解析规则）：

- 每节解释对应节点的**职责、条件、先后顺序、失败后果**，并给**业务文档出处**（章节或编号）；文档没定的走向见写作约束第 8 条。
- 一级标题 `#`（首个分节之前）＝ 图的总说明；**首个分节之前只有这一行标题会显示**，其余前言（引用块、说明段）一律被忽略——阶段声明这类要紧话写进标题行（样例即"……（设计版）"）或各节前缀，不放前言。
- 每节以 `## <节点id>` 开头；节内**不是完整 Markdown**，页面只按简单规则显示：空行分段、`-`／`*`／`数字.` 简单列表、`**加粗**` 与 `` `行内代码` ``。链接、表格、引用块、三级及更深标题不会按 Markdown 渲染——复杂语法要么按普通文字原样显示、要么被忽略，重要信息别依赖这些格式。
- **分节标题只写纯节点 id**：插件把 `## ` 后第一个空白前的词当节点 id，其余当附注。写成中文（如 `## 提交报名`）不报错，但该节与图上节点（英文 id）对不上——点节点会显示"没有这个节点的说明"，等于白写。
- 同一节点 id 写多节：不算错，但详情弹层只会显示第一份并提示；不要写多节。
- 图上没有、详情里写了的 id：容忍照常显示（删节点后旧详情不必同步删）；图上有、详情没写的：插件列为"没写说明"，不算错误——**这只是读取降级，不是交付标准**：本 Skill 交付要求分节覆盖图上全部节点（见检查清单第 4 项）。
- 正文代码围栏（``` 或 ~~~）不会截断分节（围栏里的 `#`／`##` 不当标题），但围栏符号本身也只按普通文字显示，展示能力以上面"简单规则显示"一条为准。

最小合法示例（对应一张两节点图；注意首个 `##` 之前只有标题行会显示）：

```markdown
# 提交复核流程 · 节点详情（设计版，尚无源码证据）

## submit_registration
【设计】学生在门户填写报名表并提交；表单只收集必要字段。

## check_eligibility
【设计】校验账户状态与重复报名，判定是否受理；不通过转拒绝，不落记录。
```

**写作约束**（摘自 archify-reader《详情内容规范》2026-09-05 作者裁决，适配到本文件；读者设定不变）：

1. **读者是看过图、没看过代码的业务裁决者**。不许擅自换成技术读者。
2. **正文零代码标识符**：变量、函数、表名、配置名、状态码、HTTP 方法不进白话正文；源码核对走 evidence.json（源码引用单列），不放正文里。
3. **按真实执行顺序讲**：先做什么、后做什么，一步一句事实——顺序本身就是检验点，逻辑不对读者要能看出来。谁、对什么数据、做了什么动作、得到什么结果；必要术语第一次出现给一句白话注释；客观白描，不修饰、不科普、不"专业腔"总结。
4. **失败分支也是事实**：这一步出错会怎样、影响谁；禁止只写成功路径。没跑过的失败情景不得写成已验证事实。
5. **首尾承接**：开头说从哪个节点接过什么、前面完成了什么；结尾说本次在哪结束、留下什么结果、谁在什么条件下进入哪个节点。入口/终点如实说明，不为填格式虚构上下游。
6. **依赖就地解释**：不只说"现有规则""前面处理过"——先写当前判断必需的一句话规则或数据来源，再引用对应节点；多个分支时明确列出条件。
7. **四类分开说**：拟定设计、已有实现、未实现、未核实，分开标注不混写（示例用【设计】前缀；标记写法可自定，分开说不可省）。
8. **文档未定义的分支列为问题，不以图补定规则**：业务文档没定的走向，在详情或交付报告里列为待裁决问题，不在图和详情里替业务做决定（与 workflow.md §3 出处规则同一条纪律）。

### 2.6 evidence.json（源码证据引用，同图目录）

设计阶段的合法形态就是**空清单，不伪造**：

```json
{
  "schema": "specdev-archify/evidence/1",
  "refs": []
}
```

描述已有实现时才补引用条目（字段与规则经 `src/core/evidence.ts` 静态核对）：

```json
{
  "schema": "specdev-archify/evidence/1",
  "refs": [
    {
      "id": "eligibility-core",
      "label": "资格判定核心（12–16 行）",
      "repo": ".",
      "commit": "<查证过的 40 位十六进制完整提交号>",
      "path": "src/activity-eligibility.js",
      "fromLine": 12,
      "toLine": 16
    }
  ]
}
```

| 字段 | 必填 | 规则 |
|---|---|---|
| `id`／`label` | 建议 | 引用标识与显示名；缺省显示"refs[N]／引用 N+1" |
| `repo` | 可选 | 第一批只支持同仓：省略或写 `"."`；写别的整条报错 |
| `commit` | 是 | 40 位十六进制完整提交号（短哈希不行） |
| `path` | 是 | 仓库根相对路径、正斜杠；不允许反斜杠、盘符、绝对路径、`..` 段 |
| `fromLine`／`toLine` | 是 | 整数、从 1 起；`fromLine ≤ toLine`，且不得超过**该提交上**文件总行数 |

规则：

- **证据永远按固定提交读**：文件后来变了不算引用错误；但引用写错（提交不存在、文件不在该提交上、行号越界）整条明确报错，页面不放近似内容。
- 每条引用独立成败，一条坏不拖累别的；写引用前逐条查证行号，不估。
- 设计阶段 refs 留空；没证据不硬凑。
- 何时补证据、怎么查证与提交、补完怎么核对，见 [evidence-review.md](evidence-review.md)。

## 3. 交付前检查清单（第一版手动）

按本 Skill 流程交付前逐项过一遍。第一版只用清单，不新建自动化脚本（计划 1b-2 停止边界）；插件自身的报错（说明文件问题、编号冲突、路径不存在）会体现在管理页，清单是把问题在交付前拦住。

| # | 检查项 | 怎么查 |
|---|---|---|
| 1 | 六类文件格式 | JSON 都能解析；三个说明文件 `schema` 一字不差、必填字段非空、`id` 与目录名一致；workflow.json 过 workflow.md §4 校验（showcase 五判据全过） |
| 2 | 图编号全项目唯一 | 扫全部 `docs/archify/<业务id>/` 下的图目录名，新图编号不与任何现有图重复 |
| 3 | 文档路径有效 | business.json `docs` 每条：仓库根相对、正斜杠、文件在工作区确实存在 |
| 4 | 详情节与节点 ID 对应 | details.md 每个 `## ` 节的 id 都在 workflow.json `nodes[].id` 里；无中文标题、无多节同 id；**分节覆盖图上全部节点**——插件容忍漏写（显示"没写说明"）只是读取降级，交付不得留漏：能补齐的当场补齐，业务文档没写依据的列为待裁决问题，不默认放过 |
| 5 | 规则及分支出处 | 每个节点的职责、条件、先后、失败后果都能指回业务文档；文档没定义的分支已列为待裁决问题，没在图里替业务定规则 |

## 4. 保存边界（如实说）

- **Skill 只提醒，不代存**：保存版本是作者在管理页亲手点的动作（唯一写操作＝给提交挂附注标签）。Skill 流程做到"提醒作者查看并手动保存"为止，AI 不代点、不直接打快照标签。
- **随版本读取的只有三个数据文件**：workflow.json、details.md、evidence.json。保存前的检查也只核对这三个文件与最新提交一致（换行差异不算改动）。
- **保存结果分两种，锚定的提交不一定是当前 HEAD**：插件保存时先按三个文件的内容＋阶段查重——与已有快照完全相同就**直接返回那份旧快照**（`alreadySaved`，不给当前提交挂新标签）。例如只改业务文档并提交后再保存同阶段的图，三个图文件没变，返回的可能仍是旧提交上的那份。内容或阶段有变化，才在当前 HEAD 上新建快照。**核对"这份快照对应的业务文档"时，按实际返回的快照锚定的提交去核对**，不默认它是最新提交。
- **不随版本回退的**：图名称与摘要取自**当前** chart.json（管理页在历史版本下有说明行提示）；业务名称、介绍、文档列表取自当前 business.json；业务文档内容按工作区当前文件读。
- 因此看历史快照时，若要核对**当时的**业务文档，须按该快照指向的提交另行用 git 核对，不能拿当前文档当历史文档。

## 5. 来源与状态

| 来源 | 取用点 |
|---|---|
| `archify-manager/README.md`（D2 节、页面与 API、快照五项校验） | 目录结构、图名不随版本回退、docs 只读声明路径 |
| `archify-manager/sample/generate.mjs` + `sample/data/` | 六类文件合法样本形状、details 分节写法、证据引用条目 |
| `skills/archify-reader/SKILL.md`《详情内容规范》 | §2.5 写作约束八条（摘取适配，见下） |
| `src/core/types.ts`、`chart-files.ts`、`evidence.ts`、`inventory.ts`、`src/dsh/index.ts`（doc 路由）、`web/assets/details.js` | 字段校验、三文件清单、证据硬规则、编号冲突、分节解析（均只读核对，未改插件） |

有意不采用（reader 规范里属于旧 HTML 阅读器产物的概念，不移植）：普通／源码对照双模式、悬停注释、`evidenceExemption`、reader.json 与构建脚本；本文件只取其写作纪律。generate.mjs 的坏样本（坏标签、坏证据、超限）用于理解插件报错行为，不作为书写目标。

状态：最小合法示例与规则均经源码静态核对（2026-09-17）；本文件未经真实业务仓实跑（计划步骤 2 首跑），"最小合法"的判定依据是插件字段校验逻辑，非管理页实走验证。