|
|
# 功能清单文件夹创建规范
|
|
|
|
|
|
---
|
|
|
|
|
|
### 一、目录结构模板
|
|
|
|
|
|
```
|
|
|
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. 创建页面文件
|