> 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/data.md).

# 数据契约 (data.md)

> 本文件由 \[Architect] 角色维护。承载 interface 定义、字段规则、原型↔真实切换约定。 **Dev / QA 必读；PM 禁读**（PM 不关心接口细节，避免被技术约束带偏、污染需求纯粹性）。 来源：V0 原型 `docs/api.md` / 产品规格 §数据模型。Architect 须把散落的 interface 提炼至此，作为数据层唯一真相源。

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

| 纪律          | 说明                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| **就地收敛**    | 字段变更**直接改写该 interface / 该表的小节**，⛔ 禁新开 `## 增量 F-n` 章节。同一张表在本文件永远只有一段当前字段 —— 散成「主体 + F-1 扩展 + F-3 扩展」，Dev 得读三处才知道表长什么样 |
| **过程外置**    | 迁移检查清单 / 契约漂移登记 / 裁决过程 → `docs/plans/F-n-<需求名>.md`；本文件只留「数据现在长什么样」                                                   |
| **不跨层重复**   | 验收断言只在 `prd.md` §1.5，本文件⛔不复制                                                                                         |
| **台账留痕**    | 每次增量在文末「变更台账」追加一行                                                                                                    |
| **历史靠 git** | 旧版本不在本文件留存，`git log -p` 即完整历史                                                                                        |

## 一、 数据模型 Interface

> 用 TypeScript interface 定义所有数据结构。**字段名即数据库列名，类型即列类型**。 新增字段时同步更新本段 + 第二节字段规则 + 第五节 DB 列对齐。

```typescript
// 示例结构（Architect 按 V0 原型 api.md 填充）：
// interface Task {
//   id: string
//   type: 'brief' | 'single' | 'batch'
//   status: 'draft' | 'ai_splitting' | 'queued' | 'generating' | 'refining' | 'done' | 'paused'
//   ...
// }
```

\[待 Architect 填写]

## 二、 字段规则矩阵

| 字段     | 类型 | 必填 | 枚举/范围 | 备注 |
| ------ | -- | -- | ----- | -- |
| \[待填写] |    |    |       |    |

## 三、 原型 ↔ 真实切换约定

> 原型阶段前端用 `useState` 持有 mock（形状 = 上述 interface）；真实联调阶段替换为 `fetch` / API 调用，**形状不变**。 Architect 须在此背书「interface 字段 ↔ DB 列」对齐关系，Dev 切原型→真实时只换数据源、不改形状。

| 字段/功能  | 原型阶段          | 真实联调      | 切换方式 |
| ------ | ------------- | --------- | ---- |
| \[待填写] | useState mock | fetch API | 形状不变 |

## 四、 MOCK 标记区

> 标记哪些功能/字段处于原型 mock 态，对应组件文件，以及真实化优先级。

| 功能     | 组件文件 | MOCK 内容 | 真实化优先级       |
| ------ | ---- | ------- | ------------ |
| \[待填写] |      |         | P0 / P1 / P2 |

## 五、 DB 列对齐表

> interface 字段与实际 schema 列的对齐关系。跨 ORM 栈（如 Prisma + Drizzle 并存）时尤其重要—— Architect 须保证两栈列名与本表一致，或在此记录差异。

| interface 字段 | schema 列 | 表 | ORM 栈 |
| ------------ | -------- | - | ----- |
| \[待填写]       |          |   | A / B |

***

## 附录、变更台账

> 每次增量落盘在此追加**一行**，正文永远只有当前态。 详情列指向 `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/data.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.