@deppon/deppon-skills 2.4.16 → 2.4.20

package/dist/deppon-prd-generator/examples/list-crud/prd.md

@@ -0,0 +1,151 @@
+# 用户管理 PRD（产品需求文档）
+
+> **文档说明**：本文件位于技能目录 `examples/list-crud/`，是 **后台列表 + 详情 + 新增/编辑 + 删除** 的**参考示例**（业务场景：用户管理），供生成同类 PRD 时对照章节结构、表格字段与「原型与 PRD 对应关系」写法。**不是**业务项目的默认交付路径；实际产出仍写入 `src/prototypes/<page-name>/prd.md`。落地以实际接口与权限码为准。
+
+> **交互原型**：[打开 prototype.html](./prototype.html)（Tailwind Play CDN + `marked` + 原生 JS）。**需求标注**：运行时 `fetch` 同目录本 `prd.md`，按章节切片 Markdown 渲染进标注弹框（改 PRD 后刷新即可联动）；须用**本地 HTTP**打开目录（`file://` 无法加载 prd.md 时仅显示兜底摘要）。可演示 §3～§6 主路径与 Toast；业务数据为静态 mock。
+
+---
+
+## 1. 引言
+
+### 1.1 背景
+
+为系统管理员提供统一的用户账号管理能力：按条件检索、分页浏览、查看详情、创建与编辑用户、删除（含批量可选），保证数据可追溯、操作可审计。
+
+### 1.2 功能清单
+
+> 不包含：顶栏、侧栏菜单的样式与通用导航需求。
+
+| 模块     | 功能点   | 功能描述                                                 |
+| -------- | -------- | -------------------------------------------------------- |
+| 用户管理 | 条件查询 | 用户名、姓名、手机号、状态等；查询 / 重置              |
+| 用户管理 | 列表展示 | 分页表格；约定列可排序                                 |
+| 用户管理 | 查看详情 | 行内「查看」只读弹层                                   |
+| 用户管理 | 新增用户 | 「新增用户」打开表单弹层，校验后提交（原型为模拟成功） |
+| 用户管理 | 编辑用户 | 行内「编辑」回填表单；用户名只读（与 §5 一致）         |
+| 用户管理 | 删除用户 | 单行删除二次确认；可选批量删除                         |
+| 用户管理 | 状态控制 | 启用 / 禁用（与认证策略对齐）                          |
+
+---
+
+## 2. 页面菜单与权限规划
+
+### 2.1 页面菜单
+
+**菜单路径**：系统管理 / 用户管理
+
+### 2.2 权限规划
+
+| 权限点 | 操作范围                                         | 数据范围 |
+| ------ | ------------------------------------------------ | -------- |
+| 查看   | 列表、筛选、详情、分页、导出（若做）             | 全量     |
+| 编辑   | 新增、编辑、启用/禁用、删除、批量删除            | 全量     |
+
+---
+
+## 3. 用户列表需求说明
+
+### 3.1 筛选查询区
+
+变更筛选后点击「查询」生效；「重置」恢复默认并刷新第 1 页。
+
+| 筛选字段 | 类型     | 输入限制               | 匹配规则 |
+| :------- | :------- | :--------------------- | :------- |
+| 用户名   | 文本     | 1～64，trim            | 模糊     |
+| 姓名     | 文本     | 1～64                  | 模糊     |
+| 手机号   | 文本     | 数字，建议 11 位       | 精准     |
+| 用户状态 | 下拉     | 全部 / 启用 / 禁用     | 精准     |
+
+- **查询** / **重置**：见上文。
+- **新增用户**：需「编辑」权限；打开新增表单（弹层或路由）。
+
+### 3.2 数据列表
+
+| 列表字段     | 字段说明           | 排序 |
+| :----------- | :----------------- | :--- |
+| 用户名       | 登录账号，唯一     | 是   |
+| 姓名         | 展示名             | 否   |
+| 手机号       | 可脱敏             | 否   |
+| 部门         | 主部门             | 否   |
+| 用户状态     | 启用 / 禁用        | 是   |
+| 创建时间     | `YYYY-MM-DD HH:mm` | 是   |
+
+- **分页**：默认 10 条；可切换 10 / 20 / 50；底栏展示总数。
+- **行操作**：查看、编辑、删除（受权限）。
+- **批量删除**（可选）：多选 + 确认 + 接口。
+
+---
+
+## 4. 用户详情（只读）
+
+查看弹层展示：用户 ID、用户名、姓名、手机号、邮箱、部门、角色、状态、创建/更新时间（字段以接口为准）。
+
+---
+
+## 5. 新增 / 编辑表单
+
+| 字段     | 类型   | 必填 | 校验要点                     |
+| -------- | ------ | ---- | ---------------------------- |
+| 用户名   | 文本   | 是   | 4～64；编辑态只读            |
+| 姓名     | 文本   | 是   | 1～64                        |
+| 手机号   | 文本   | 是   | `^1[3-9]\d{9}$`              |
+| 邮箱     | 文本   | 否   | 邮箱格式                     |
+| 部门     | 选择   | 是   | 至少一项                     |
+| 角色     | 多选   | 是   | 至少一项                     |
+| 用户状态 | 单选   | 是   | 启用 / 禁用；新增默认启用   |
+
+**保存**：前端校验 → 提交接口 → 成功关闭并刷新列表。**取消**：有改动时二次确认。
+
+---
+
+## 6. 删除与审计
+
+单行删除确认文案建议含用户姓名；敏感操作建议后端审计日志。
+
+---
+
+## 7. 接口（逻辑分组）
+
+| 能力     | 说明           |
+| -------- | -------------- |
+| 分页查询 | 筛选 + 分页 + 排序 |
+| 详情     | userId         |
+| 创建     | POST body      |
+| 更新     | userId + 字段  |
+| 删除     | DELETE / 批量  |
+
+---
+
+## 8. 交互设计
+
+加载态、空态、防重复提交、列表与弹层焦点与 `aria-modal` 与组件库规范对齐。
+
+- **主色按钮**：查询、新增用户、保存等主操作使用**主题蓝**实心按钮；重置、取消、关闭等为次要（白底描边）；删除、确定离开等为危险（红色系）。高保真原型与 `deppon-prd-generator` 技能「技术约定」第 8 条一致。
+
+---
+
+## 9. 原型与 PRD 对应关系
+
+| PRD 章节   | prototype.html 演示点           |
+| ---------- | -------------------------------- |
+| §1         | 页头「PRD §1」标注入口           |
+| §2 / §3.1  | 列表标题行右侧「PRD §2·§3.1」+「新增用户」 |
+| §3.1       | 筛选区旁「PRD §3.1」+ 查询、重置 |
+| §3.2       | 列表标题行左侧「PRD §3.2」+ 表格、行操作；底栏「共 n 条」+ 每页条数 + 分页 |
+| §4         | 详情弹层内「PRD §4」+ 只读字段   |
+| §5         | 表单弹层内「PRD §5」+ 新增/编辑与校验 |
+| §6         | 删除弹层内「PRD §6」+ 二次确认   |
+| §8         | 主色按钮主题蓝与次要/危险区分；Toast 模拟成功/失败（无真实接口） |
+| 走查说明   | 左下角「标注说明」：操作说明 + **prd.md §9 原文**；各「PRD §」从 **prd.md 对应章节切片**渲染；弹内长表格/长文可纵向与横向滚动；未加载 prd.md 时见页面顶栏黄条与弹内兜底 |
+
+---
+
+## 10. 修订记录
+
+| 版本 | 日期       | 说明                         |
+| ---- | ---------- | ---------------------------- |
+| v0.1 | 2026-05-13 | 用户列表 CRUD 初稿（他目录） |
+| v1.2 | 2026-05-13 | 原型：新增用户移至列表标题行；总条数移至分页栏「每页」旁 |
+| v1.3 | 2026-05-14 | 迁入 `examples/list-crud/`，明确为技能内参考示例 |
+| v1.4 | 2026-05-14 | 交互：主操作按钮统一主题蓝；与技能技术约定第 8 条对齐 |
+| v1.5 | 2026-05-14 | 原型：标注正文 `fetch` 联动 prd.md 切片 + Markdown 渲染；弹层内可滚动；file:// 兜底说明 |