# 功能清单文件夹创建规范

---

### 一、目录结构模板

```
00-功能清单索引.md
01-功能清单规范.md
│
├── 管理后台\
│   ├── 00-管理后台-索引.md
│   ├── 01-管理后台-规范.md
│   ├── 01-登录\
│   │   ├── 00-登录-索引.md
│   │   ├── 01-登录-规范.md
│   │   └── 01-01-登录页面.md
│   ├── 02-仪表盘\
│   │   ├── 00-仪表盘-索引.md
│   │   ├── 01-仪表盘-规范.md
│   │   └── 02-01-仪表盘页面.md
│   └── ...
│
└── 大屏\
    ├── 00-大屏-索引.md
    ├── 01-大屏-规范.md
    └── 01-01-大屏看板页面.md
```

---

### 二、文件命名规则

| 文件类型 | 命名规则 | 示例 |
|---------|---------|------|
| 总索引 | `00-功能清单索引.md` | - |
| 总规范 | `01-功能清单规范.md` | - |
| 分类索引 | `00-{分类名}-索引.md` | `00-管理后台-索引.md` |
| 分类规范 | `01-{分类名}-规范.md` | `01-管理后台-规范.md` |
| 模块索引 | `00-{模块名}-索引.md` | `00-登录-索引.md` |
| 模块规范 | `01-{模块名}-规范.md` | `01-登录-规范.md` |
| 页面文件 | `{模块号}-{页面号}-{页面名}.md` | `01-01-登录页面.md` |

**编号规则**：
- 模块号：01-99（两位数）
- 页面号：01-99（两位数）
- 格式：`{模块号}-{页面号}-{页面名}.md`

---

### 三、索引文件内容规则

#### 1. 总索引

```markdown
# 功能清单 索引

> 版本：v1.0
> 最后更新：日期

---

## 分类

| 分类 | 类型 | 索引 |
|------|------|------|
| 管理后台 | 文件夹 | [00-管理后台-索引.md](./管理后台/00-管理后台-索引.md) |
| 大屏 | 文件夹 | [00-大屏-索引.md](./大屏/00-大屏-索引.md) |

---
```

#### 2. 分类索引

```markdown
# {分类名} 索引

> 版本：v1.0
> 最后更新：日期

---

## 子目录/文件

| 编号 | 名称 | 类型 | 索引 |
|------|------|------|------|
| 01 | 登录 | 文件夹 | [01-登录](./01-登录) |
| 02 | 仪表盘 | 文件夹 | [02-仪表盘](./02-仪表盘) |

---
```

#### 3. 模块索引

```markdown
# {模块名} 索引

> 版本：v1.0
> 最后更新：日期

---

## 模块概述
[简要说明本模块的功能定位、业务场景]

## 页面清单
| 页面编号 | 页面名称 | 路由 | 功能概述 |
|---------|---------|------|---------|

## 页面功能详情

### {页面号} {页面名称}
**路由**：`/xxx`
**功能概述**：[简要]

**功能列表**：
| 功能编号 | 功能名称 | 触发条件 | 交互行为 | 涉及API |

**状态机**：[如有]

**路由跳转**：[本模块内 + 跨模块跳转]

## 子目录/文件
| 编号 | 名称 | 类型 | 索引 |
|------|------|------|------|

---
```

---

### 四、规范文件内容规则

| 层级 | 内容 |
|------|------|
| 总规范 | 整体规范，所有模块通用 |
| 分类规范 | 本分类通用规范 |
| 模块规范 | 无特殊规范时写"继承上级规范，如有冲突按本目录规范执行" |

---

### 五、页面文件规则（20项模板，按组分类）

页面文件保持20项模板不变，用空行分组提升可读性。

#### 【结构定义】

| 序号 | 内容 | 说明 |
|------|------|------|
| 1 | 基本信息 | 路由、权限、入口、面包屑 |
| 2 | 界面布局 | ASCII图、响应式断点 |
| 3 | 表单字段 | 字段定义、控件、校验 |
| 4 | 操作按钮 | 权限、位置、行为 |
| 5 | 弹窗规格 | 无/弹窗类型 |
| 6 | 状态机 | 状态值、颜色、流转 |

#### 【交互行为】

| 序号 | 内容 | 说明 |
|------|------|------|
| 7 | 交互流程 | 成功/失败处理 |
| 8 | 防重复请求 | 按钮禁用、AbortController |
| 9 | 超时与加载反馈 | 超时时间、loading方式 |
| 10 | 操作确认机制 | 确认文案 |
| 11 | 脏数据检测 | 快照、重置 |
| 12 | 操作结果反馈 | 反馈方式、持续时间 |
| 14 | 校验规则 | 正则、错误提示、触发时机 |
| 15 | 响应式布局 | 断点布局 |

#### 【技术实现】

| 序号 | 内容 | 说明 |
|------|------|------|
| 13 | 组件规范 | 组件选择、配置 |
| 16 | 接口引用与数据结构 | 引用端点清单编号 + 每个接口的完整Request/Response数据结构定义（见下方详细说明） |
| 17 | 键盘操作 | 快捷键 |
| 18 | 空状态设计 | 空态展示 |
| 19 | 错误码处理 | 错误码映射 |
| 20 | 安全规范 | 加密、存储、防护 |

#### §16 接口引用与数据结构 — 详细格式说明

**职责划分**（与 `03-API接口设计.md` 端点清单的关系）：

| 文件 | 负责定义 | 不负责 |
|------|---------|--------|
| `03-API接口设计.md` 端点清单（§3.1~3.13） | URL路径、HTTP方法、端点编号（两列URL对照） | **禁止定义返回数据结构** |
| 页面文件 §16 | 引用端点清单编号 + 每个接口的完整Request/Response数据结构 | **不重复定义URL** |

**§16 必须包含两部分：**

**第一部分：接口引用表**（只引用编号和界面用途，不重复URL）

```markdown
#### 接口引用

> Mock/正式API的URL、HTTP方法均定义在 `03-API接口设计.md` §3.x 端点清单，本节仅引用编号。

| 接口名称 | 端点编号 | 界面用途 |
|---------|---------|---------|
| 配置项列表 | §3.9 #1 | Tab1系统配置列表，渲染表格 |
| 编辑配置项 | §3.9 #2 | Tab1编辑弹窗保存 |
| 车间列表 | §3.9 #4 | Tab2车间管理列表，渲染表格 |
```

**第二部分：数据结构定义**（每个接口的完整Request/Response JSON，这是唯一的数据结构定义处）

```markdown
#### 数据结构

**配置项列表（§3.9 #1）：**

Response：
{ "code": 0, "data": { "items": [
  { "id": 1, "configKey": "ping_interval", "configValue": "60", "valueType": "number", "description": "Ping检测间隔(秒)" }
]}}

**编辑配置项（§3.9 #2）：**

Request body：
{ "id": 1, "configValue": "120" }

Response：
{ "code": 0, "message": "success", "data": null }
```

**强制要求**：
- 接口引用表只写端点编号和界面用途，不重复URL（URL由03统一定义）
- 每个接口必须写清 Request body 和 Response 的完整JSON结构
- 写操作的 Request body 中需要包含 id 字段（Mock和正式API的id传递方式不同，由03的端点清单说明）
- 数据结构必须与 Mock 文件（`frontend/mock/*.ts`）中的定义严格一致

---

### 六、三种文件分工

| 文件类型 | 重点内容 | 所属 |
|---------|---------|------|
| 索引文件 | 功能逻辑、交互关系、路由跳转、状态机 | 模块 |
| 规范文件 | 技术规范要求（组件、校验、布局、安全） | 模块/分类 |
| 页面文件 | 技术实现（界面布局、字段、Mock数据） | 页面 |

---

### 七、创建顺序

1. 创建根目录索引+规范
2. 创建分类目录+分类索引+规范
3. 创建模块目录+模块索引+规范
4. 创建页面文件
