You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

6.9 KiB

Raw Blame History Unescape Escape

功能清单文件夹创建规范

一、目录结构模板

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. 总索引

# 功能清单 索引

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

---

## 分类

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

---

2. 分类索引

# {分类名} 索引

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

---

## 子目录/文件

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

---

3. 模块索引

# {模块名} 索引

> 版本：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）

#### 接口引用

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

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

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

#### 数据结构

**配置项列表（§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数据）	页面

七、创建顺序

创建根目录索引+规范
创建分类目录+分类索引+规范
创建模块目录+模块索引+规范
创建页面文件

6.9 KiB Raw Blame History Unescape Escape