| name | tongyiyunying-doc-gen |
| description | 用于生成《统一运营系统》功能设计文档（.md + .docx 双格式）。当用户提到"生成功能设计文档"、"新建某某功能的设计文档"、"按模板生成文档"、"更新现有功能设计文档"时，应使用本 skill。自动完成版本号管理（_vX.X 递增）、文档格式规范（宋体、1.5倍行距、淡蓝色表头）并同步输出两种格式。 |
| allowed-tools | null |
| disable | true |
统一运营系统文档生成 Skill
概述
本 skill 服务于《统一运营系统》产品文档管理，负责按标准模板生成和维护功能设计文档。
所有文档默认输出到项目根目录的 tongyiyunying/doc/ 下，也可通过环境变量 DOC_DIR 指定自定义路径。
文档规范
文件命名
- 格式：
{文档名}_vX.X.md 和 {文档名}_vX.X.docx
- 版本号从源文件
.md 中的「文档版本」字段读取，快照文件名版本号与文档内修订记录严格一致
- 第一次生成从
v0.1 开始
- 无版本号后缀的源文件（如
统一运营系统-xxx功能设计.md）始终保持最新内容，作为工作源文件
- 每次生成 .md 和 .docx 版本号完全一致，同步输出
数据导出文件命名规范（前端实现约束）
生成功能设计文档时，如涉及「导出」功能描述，需遵循以下命名规范：
- 格式:
{业务前缀}_{YYYYMMDD}_{HHMMSS}.xlsx
- 示例:
车辆信息_20260405_103045.xlsx
- 时间戳: 使用当前系统时间，年月日(8位) + 时分秒(6位)
各模块业务前缀对照表：
| 模块 | 导出前缀 | 示例文件名 |
|---|
| 车辆信息管理 | 车辆信息 | 车辆信息_20260405_103045.xlsx |
| SIM卡信息管理 | SIM卡信息 | SIM卡信息_20260405_103045.xlsx |
| OBU信息管理 | OBU设备信息 | OBU设备信息_20260405_103045.xlsx |
| 摄像头管理 | 摄像头设备信息 | 摄像头设备信息_20260405_103045.xlsx |
导入模板文件名（固定名称，不带时间戳）：
| 模块 | 模板文件名 |
|---|
| 车辆信息管理 | 车辆信息批量导入模板.xlsx |
| SIM卡信息管理 | 批量导入模板.xlsx |
| OBU信息管理 | OBU导入模板.xlsx |
| 摄像头管理 | 摄像头导入模板.xlsx |
导入功能逻辑规范（前置校验模式）
生成功能设计文档时，如涉及「导入」功能描述，需遵循以下逻辑规范：
核心原则：前置全量校验，有错不导入，全部通过才入库
| 阶段 | 处理逻辑 | 用户反馈 |
|---|
| 文件上传 | 校验文件格式（.xlsx）和大小（≤10MB） | 格式错误时Toast提示阻断 |
| 数据校验 | 逐行校验所有数据（必填/格式/长度/唯一性/关联数据/字典值） | 错误列表直接展示在页面（行号+列名+原因） |
| 导入执行 | 仅当全部数据校验通过后才执行导入 | 成功后Toast提示导入条数 |
校验类型清单：
- 文件级校验：格式、大小
- 必填项校验：必填字段不能为空
- 格式校验：正则匹配（手机号、邮箱、编码等）
- 长度校验：字段值长度限制
- 唯一性校验：与现有数据对比，关键字段不重复
- 关联数据校验：外键/关联字段值在系统中存在
- 字典值校验：枚举/字典字段值在有效范围内
错误提示格式：
- 统一格式：
第X行，【字段名】：错误原因
- 示例：
第3行，SIM卡号：不能为空、第5行，手机号：格式不正确
删除功能规范（统一运营系统）
生成功能设计文档时，如涉及「删除」功能描述，需遵循以下规范：
核心原则：根据业务需要决定是否提供批量删除功能
| 模式 | 适用场景 | 实现方式 |
|---|
| 单条删除 | 数据敏感、操作不可逆、需严格控制的场景 | 列表不展示复选框，仅在行内操作列提供删除按钮 |
| 批量删除 | 数据量大、操作频繁、需提升效率的场景 | 列表展示复选框，工具栏提供批量删除按钮 |
| 项目 | 规范要求 |
|---|
| 删除入口 | 单条删除在每行数据的操作列提供"删除"按钮；批量删除在工具栏提供"删除"按钮 |
| 删除约束 | 已绑定/已入网/已启用等状态的数据，删除按钮灰化不可用 |
| 确认机制 | 点击删除后弹出确认弹窗，确认后才执行删除 |
注：具体项目可根据业务需求在文档中明确是否提供批量删除功能。
文档格式规范（docx）
- 正文字体：宋体（SimSun），字号 10.5pt（size=21）
- 行间距：1.5 倍行距（line=360，lineRule='auto'）
- 表格表头背景色：淡蓝色（
D9E1F2）
- 标题层级：H1（22pt）> H2（16pt）> H3（14pt）> H4（12.5pt）
章节结构（十二章，不含目录）
- 一、功能角色矩阵说明：文档信息表（编号/版本/名称/系统/负责人/日期）+ 修订记录表 + 角色权限总览表 + 功能角色矩阵表
- 二、模块路径：菜单路径说明
- 三、页面布局：3.1 页面标题区 / 3.2 信息查询区 / 3.3 列表操作区 / 3.4 列表展示区 / 3.5 分页控件区
- 四、交互说明：各区域的交互行为描述
- 五、字段输入规范：输入字段的类型、长度、必填等规范表格
- 六、操作输出规则：各操作的结果/反馈说明表格
- 七、弹窗说明：7.1 查看详情弹窗 / 7.2 新增编辑弹窗 / 7.3 批量导入弹窗
- 八、错误处理规范：8.1 表单校验错误（3列）/ 8.2 文件操作错误（4列，含"处理方式"）
- 九、接口规范：仅接口清单，无详细入参/出参
- 十、非功能性需求：10.1 等保三级合规规范引用 / 10.2 性能需求
- 十一、特殊说明：11.1 编码规则 / 11.2 删除及修改限制 / 11.3 其他特殊规则
- 十二、数据字典：12.1 字典项定义 / 12.2 下拉框数据来源说明
可用脚本
scripts/gen_template.js
生成模板文件（AI智能体-统一运营系统-xxxxx功能设计模板）的 .docx 和 .md 版本。
cd /your/project/root && /usr/local/bin/node ~/.workbuddy/skills/统一运营系统文档生成/scripts/gen_template.js
export DOC_DIR=/your/project/root/tongyiyunying/doc
/usr/local/bin/node ~/.workbuddy/skills/统一运营系统文档生成/scripts/gen_template.js
scripts/gen_from_md.js ⭐ 主力脚本（推荐）
直接解析 .md 源文件生成 .docx，内容与 .md 100% 一致，不依赖 hardcode build 函数。
版本号从源文件「文档版本」字段读取，快照文件名与文档内修订记录严格对齐。
DOC_DIR=/your/project/root/tongyiyunying/doc \
/usr/local/bin/node ~/.workbuddy/skills/统一运营系统文档生成/scripts/gen_from_md.js --doc sim
DOC_DIR=/your/project/root/tongyiyunying/doc \
/usr/local/bin/node ~/.workbuddy/skills/统一运营系统文档生成/scripts/gen_from_md.js --doc sim,obu
DOC_DIR=/your/project/root/tongyiyunying/doc \
/usr/local/bin/node ~/.workbuddy/skills/统一运营系统文档生成/scripts/gen_from_md.js
当前已注册的文档 key 对照表：
| key | 文档名 |
|---|
vehicle | 统一运营系统-车辆监控管理功能设计 |
homepage | 统一运营系统-首页概览功能设计 |
sim | 统一运营系统-SIM卡信息管理功能设计 |
obu | 统一运营系统-OBU信息管理功能设计 |
vehicle-info | 统一运营系统-车辆信息管理功能设计 |
car-type | 统一运营系统-车型字典管理功能设计 |
新增文档 key：只需在 gen_from_md.js 末尾的 ALL_DOCS 映射表中追加一行 'key': '文档名' 即可，无需编写 build 函数。
`�编写 build 函数。
scripts/gen_update_v1.js （旧版，保留备用）
旧版脚本，依赖 hardcode build 函数生成 docx。新文档请使用 gen_from_md.js，此脚本仅保留作历史参考。
注意：两个脚本都依赖 docx npm 包。运行前确认工作目录下有 node_modules/docx，否则先执行 npm install docx。
新增功能文档的工作流
- 了解需求：向用户确认功能名称、模块路径、角色权限、字段列表等核心信息
- 创建 .md 源文件：在
doc/ 目录下创建 统一运营系统-{功能名}功能设计.md，按十二章模板填写内容；封面写好文档版本（v0.1）和修订记录
- 注册 key：在
gen_from_md.js 的 ALL_DOCS 映射表中追加一行
- 预览确认：将
.md 源文件核心内容（章节结构、版本号、修订记录）呈现给用户，说明即将生成的文件名，请用户确认无误后再执行
- 生成快照：运行
gen_from_md.js --doc new-key，自动输出 _v0.1.md 和 _v0.1.docx
💡 注意：步骤 4 是推荐实践，不是强制流程。若用户在对话中已明确告知内容无误或主动要求直接生成，可跳过确认步骤。
更新现有文档的工作流
- 编辑对应的无版本号源文件（如
统一运营系统-SIM卡信息管理功能设计.md）
- 在源文件封面更新「文档版本」字段（+0.1 递增），并追加修订记录行
- 将变更摘要告知用户（改了哪些内容、新版本号是什么），请用户确认或直接生成（根据用户习惯判断）
- 运行
gen_from_md.js --doc <key>，脚本自动读取源文件版本号命名快照，旧快照归入 backup/
💡 注意：若用户团队有「必须二次确认」的流程约定，请在项目级记忆（如 MEMORY.md）中记录，skill 本身不强制此行为。
参考文件
references/功能设计文档模板.md：完整的十二章模板，含所有章节示例内容references/统一运营系统-等保三级通用安全要求.md：等保三级通用安全规范。生成或更新业务文档时，如需填写 §10.1 等保三级合规规范引用节，从本文件中读取对应章节内容，按实际模块适用情况摘取并填入表格；不适用的行可删除。
