> For the complete documentation index, see [llms.txt](https://cc-code.rongyeliu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cc-code.rongyeliu.com/templates/prd.md).

# 项目逻辑 (prd.md)

> **L1 意图层** · 由 \[PM] 角色维护 · 全系统唯一「应然」真相源。 ⛔ **禁止从代码反推**：本文件定义「应该是什么」，代码定义「现在是什么」。若从代码反推需求，QA 将退化为「拿代码验代码」，验收环节彻底失效。 📐 **写什么**：分模块的业务逻辑、规则、边界、验收断言。 🚫 **不写什么**：UI 长什么样（→ `ux.md`）、字段与表结构（→ `data.md`）、接口参数（→ `api.md`）、架构选型（→ `project.md`）、实测结果（→ `gates.md`）。

**判据一句话**：能脱离界面存在的规则 → 写这里；离开界面就没意义的 → 写 `ux.md`。

### ⛔ 写入纪律（active = 最新 + 最完整 + 最纯净）

| 纪律          | 说明                                                                    |
| ----------- | --------------------------------------------------------------------- |
| **就地收敛**    | 增量变更**直接改写对应模块小节**，⛔ 禁新开 `## 增量 F-n` 章节。同一条规则在本文件永远只有一处描述             |
| **断言归主表**   | 新断言一律**续编进 §1.5 验收断言主表**，⛔ 禁在增量小节另起断言表 —— 尺子只有一把，散了 QA 就拿不全           |
| **过程外置**    | 需求清单 / 冲突收敛表 / 裁决过程 / 待澄清 → `docs/plans/F-n-<需求名>.md`；本文件只留「现在的规则是什么」 |
| **台账留痕**    | 每次增量在文末「变更台账」追加一行（F 号 / 日期 / 改了什么 / 裁决 / 详情链接）                        |
| **历史靠 git** | 旧版本不在本文件留存，`git log -p` 即完整历史                                         |

***

## 一、模块清单

| #  | 模块     | 优先级 | 依赖模块 | 状态    |
| -- | ------ | --- | ---- | ----- |
| M1 | \[待填写] | P0  | —    | ⬜ 未开始 |
| M2 | \[待填写] | P0  | M1   | ⬜ 未开始 |
| M3 | \[待填写] | P1  | M1   | ⬜ 未开始 |

> 优先级：P0 = MVP 必须 / P1 = MVP 后紧接 / P2 = 远期 状态：⬜ 未开始 / 🟡 进行中 / ✅ 已验收（由 `gates.md` 实测结果回填）

***

## M1. \[模块名称]

### 1.1 职责

一句话说清这个模块做什么。写不成一句话 = 模块该拆。

### 1.2 核心规则

> 每条一句话，**必须可判真假**。带「优化」「更好」「友好」这类不可判真假的词 = 不合格。

| #  | 规则     |
| -- | ------ |
| R1 | \[待填写] |
| R2 | \[待填写] |

### 1.3 状态机

> 有状态流转才写；纯 CRUD 模块可删本节。

```
[状态A] ──触发条件──► [状态B] ──触发条件──► [状态C]
   │                                          │
   └────────── 回退条件 ◄─────────────────────┘

不可逆流转：[标明哪些流转一旦发生不可回退]
```

### 1.4 边界与异常

| 触发条件   | 期望行为   |
| ------ | ------ |
| \[待填写] | \[待填写] |

### 1.5 验收断言

> ⭐ **这一节是 `/cc-code:whole-qa` 的分母，也是 QA 唯一的尺子。** 编号必须**永久稳定**（A1 永远是 A1），删除条目只标 `~~作废~~`，绝不重排编号 —— 否则跨轮次结果无法对比。

| #  | 断言（可测，含明确的输入→期望输出） |
| -- | ------------------ |
| A1 | \[待填写]             |
| A2 | \[待填写]             |

### 1.6 依赖

* **上游模块：** \[待填写]
* **外部服务：** \[待填写]
* **前置数据：** \[待填写]

***

## M2. \[模块名称]

（复制 M1 结构）

***

## 二、全局规则

> 跨所有模块生效的约束。放在这里避免每个模块重复一遍。

| #  | 规则     | 适用范围 |
| -- | ------ | ---- |
| G1 | \[待填写] | 全部模块 |

***

## 三、明确不做（Out of Scope）

> 写下来，防止 AI 自行发挥、也防止后来人反复追问。

| 项      | 为什么不做  | 何时可能做  |
| ------ | ------ | ------ |
| \[待填写] | \[待填写] | \[待填写] |

***

## 附录、变更台账

> 每次增量落盘在此追加**一行**，正文永远只有当前态。 详情列指向 `docs/plans/F-n-<需求名>.md`（需求清单 / 裁决过程 / 迁移清单都在那里，不进本文件）。

| F 号    | 日期            | 改了什么（一句） | 冲突裁决             | 详情                    |
| ------ | ------------- | -------- | ---------------- | --------------------- |
| \[F-1] | \[YYYY-MM-DD] | \[待填写]   | \[覆盖 X / 共存 / 无] | `docs/plans/F-1-*.md` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cc-code.rongyeliu.com/templates/prd.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.