# APS Agent 文档大管家

> **本文件是文档体系的唯一入口。**  
> 改代码、加功能、改功能、改门禁、改模块登记——**同一轮必须在本体系留痕**，否则视为交付未完成。

---

## 1. 目录地图（按角色分类）

| 目录 | 读者 | 内容 |
| --- | --- | --- |
| [`CHANGELOG.md`](./CHANGELOG.md) | 全员 | **变更登记簿**：每次代码/功能变动一条记录（大管家的账本） |
| [`product/`](./product/) | 产品经理 / 业务方 | 定位、功能清单、业务旅程、验收口径 |
| [`architecture/`](./architecture/) | 架构 / 后端 / 前端 | 分层、门禁、可重生模块、契约与数据流 |
| [`algorithm/`](./algorithm/) | 算法 / OR / 数据 | 已落地求解逻辑、冲突语义、目标算法路线 |
| 根目录 [`plan.md`](../plan.md) | 全员（蓝图） | 完整架构蓝图；细节以本 `docs/` 落地文档为准 |

旧扁平文件（`PROGRESS.md` / `FEATURES.md` / `HARNESS.md` / `REGEN.md`）已迁入上述分类，**请勿再往根下堆新文档**。

---

## 2. 写文档的硬规则（活文档铁律）

### 2.1 什么时候必须改文档

| 你改了什么 | 必须更新 |
| --- | --- |
| 任意功能增删改、修 bug、改交互 | [`CHANGELOG.md`](./CHANGELOG.md) 追加一节 |
| 产品能力边界 / 功能状态 | [`product/features.md`](./product/features.md) |
| 核心用户路径或业务语义 | [`product/journeys.md`](./product/journeys.md) |
| `_POWER_MAP`、API 端点权限 | [`architecture/harness.md`](./architecture/harness.md) |
| `moduleId` 增删改名 | [`architecture/modules.md`](./architecture/modules.md) |
| 排产规则、冲突类型、策略模板 | [`algorithm/scheduling-v1.md`](./algorithm/scheduling-v1.md) |
| 架构分层、技术选型重大变更 | [`architecture/overview.md`](./architecture/overview.md) + 必要时同步 `plan.md` |

### 2.2 CHANGELOG 写法（强制模板）

```markdown
## YYYY-MM-DD — 一句话标题

- **类型**：feature | fix | refactor | docs | chore
- **做了什么**：3～8 条，写结果不写流水账
- **涉及路径**：关键文件/目录
- **验证**：命令 + 结果（如 `24 passed` / 构建成功）
- **文档同步**：勾选本次已改的文档
- **遗留**：未做完的点（可空）
```

### 2.3 真相优先级（防「文档骗人」）

1. **可运行代码与黄金测试** > 本文档 > `plan.md` 蓝图  
2. 文档里写「已落地」必须能在代码里指到路径；写「规划中」必须标明未实现  
3. 禁止把演示数据写成产品定位（本产品**无行业/工厂硬编码**）

---

## 3. 快速导航

### 产品经理

1. [产品定位与边界](./product/positioning.md)  
2. [功能清单与对照](./product/features.md)  
3. [真实需求吸收（康尼芜湖/排产逻辑）](./product/demand-kangni-wuhu.md)  
4. [柔性排产全流程模拟操作手册](./product/flex-simulation-guide.md)  
5. [对标西门子 Opcenter APS](./product/aps-benchmark-siemens.md)  
6. [功能落地规格](./product/implementation-spec.md)  
7. [核心业务旅程](./product/journeys.md)  
8. [变更登记簿](./CHANGELOG.md)

### 架构 / 研发

1. [架构总览](./architecture/overview.md)  
2. [Harness 门禁](./architecture/harness.md)  
3. [可重生模块](./architecture/modules.md)  
4. [Plan 可重生运行时](./architecture/plan-runtime.md)
5. [对话回复规范](./development/response-style.md)
6. 蓝图全文：[plan.md](../plan.md)

### 算法

1. [排产 v1（已落地）](./algorithm/scheduling-v1.md)  
2. [约束与算法路线（规划）](./algorithm/roadmap.md)

### 本地跑起来

见仓库根 [`README.md`](../README.md)。

---

## 4. 文档维护责任

| 角色 | 责任 |
| --- | --- |
| 每次改代码的 Agent / 开发者 | 同一轮更新 CHANGELOG + 对应分类文档 |
| 产品评审 | 以 `product/` 为准验收，不以聊天记录为准 |
| 架构评审 | 以 `architecture/` + `plan.md` 为准；冲突时先改文档再改代码或反过来同轮对齐 |

---

*大管家索引 · 与代码同生命周期维护*

### Round 65 闭环 APS 索引

- [工作计划](./round-65-aps-end-to-end-work-plan.md)
- [并行实施计划](./round-65-aps-end-to-end-parallel-implementation-plan.md)
- [可恢复状态](./round-65-aps-end-to-end-state.md)
- [真实运行证据](./round-65-aps-end-to-end-runtime-final.json)