software-cn-spec-docs

name	software-cn-spec-docs
description	生成中文软件项目规格文档（需求规格说明书、概要设计、详细设计）。使用python-docx生成符合国标的Word文档，包含封面、修订记录、目录、正文、附录等完整结构。当用户需要生成需求文档、设计文档、规格说明书时使用此skill。

中文技术规格文档生成规范

适用场景

• 生成需求规格说明书（SRS）
• 生成概要设计说明书（HLD）
• 生成详细设计说明书（DD）
• 生成用户手册、运维手册
• 生成测试报告、验收报告
• 任何需要正式交付的中文技术文档

文档结构规范

标准文档结构

1. 封面页
2. 文档修订记录
3. 目录（自动生成占位符）
4. 正文章节
5. 附录

章节编号规则

1  一级章节（如：引言）
1.1  二级章节（如：编写目的）
1.1.1  三级章节（如：核心流程）

封面页规范

封面内容

[单位名称]           # 黑体 18pt，居中
[项目名称]           # 黑体 18pt，居中
[文档标题]           # 黑体 26pt，居中，加粗

[空行 × 6]

文档编号：XXX-XXX-XXX
版本号：V1.0
编制日期：YYYY年MM月DD日
密  级：内部

封面信息表

• 2列表格，居中对齐
• 左列：属性项（如"文档编号："）
• 右列：属性值
• 字体：仿宋 14pt

文档修订记录

格式要求

文档修订记录

| 版本 | 日期 | 修订人 | 修订内容 |
|------|------|--------|----------|
| V1.0 | 2024-01-01 | — | 初始版本 |

• 表格样式：Table Grid
• 表头背景色：#D9E2F3（浅蓝色）
• 字体：仿宋 12pt

页边距设置

section.top_margin = Cm(2.54)    # 上边距 2.54cm
section.bottom_margin = Cm(2.54) # 下边距 2.54cm
section.left_margin = Cm(3.17)   # 左边距 3.17cm
section.right_margin = Cm(3.17)  # 右边距 3.17cm

字体规范

正文字体

• 中文：仿宋
• 英文：Times New Roman
• 字号：12pt（小四号）
• 行距：1.5倍行距

标题字体

标题级别	字体	字号	对齐方式
一级标题	黑体	22pt（二号）	左对齐
二级标题	黑体	16pt（三号）	左对齐
三级标题	黑体	14pt（四号）	左对齐

表格字体

• 表头：黑体 11pt，加粗，居中，背景色 #D9E2F3
• 表格内容：仿宋 11pt

表格规范

表格样式

table.style = 'Table Grid'  # 带边框表格

表格宽度

• 自动适应内容宽度
• 多列表格可设置列宽比例

表格对齐

• 表格整体居中
• 表头文字居中
• 内容左对齐（数字可居中）

表格背景色

# 表头背景色
set_cell_shading(cell, 'D9E2F3')  # 浅蓝色

# 交替行背景色（可选）
set_cell_shading(cell, 'F2F2F2')  # 浅灰色

列表规范

有序列表

doc.add_paragraph('步骤1', style='List Number')
doc.add_paragraph('步骤2', style='List Number')

无序列表

doc.add_paragraph('项目1', style='List Bullet')
doc.add_paragraph('项目2', style='List Bullet')

代码示例

基础模板

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""中文技术文档生成模板"""

import os
from docx import Document
from docx.shared import Pt, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

def set_cell_shading(cell, color):
    """设置单元格背景色"""
    shading_elm = OxmlElement('w:shd')
    shading_elm.set(qn('w:fill'), color)
    cell._tc.get_or_add_tcPr().append(shading_elm)

def create_doc():
    """创建带标准样式的文档"""
    doc = Document()
    
    # 设置默认字体
    style = doc.styles['Normal']
    font = style.font
    font.name = '仿宋'
    font.size = Pt(12)
    style.element.rPr.rFonts.set(qn('w:eastAsia'), '仿宋')
    
    # 设置页边距
    for section in doc.sections:
        section.top_margin = Cm(2.54)
        section.bottom_margin = Cm(2.54)
        section.left_margin = Cm(3.17)
        section.right_margin = Cm(3.17)
    
    # 设置标题样式
    for i in range(1, 4):
        hs = doc.styles[f'Heading {i}']
        hs.font.name = '黑体'
        hs.element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
        hs.font.color.rgb = RGBColor(0, 0, 0)
        hs.font.size = [Pt(22), Pt(16), Pt(14)][i-1]
    
    return doc

def add_cover(doc, unit_name, project_name, title, doc_info):
    """添加封面页"""
    for _ in range(6):
        doc.add_paragraph()
    
    # 单位名称
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run(unit_name)
    run.font.size = Pt(18)
    run.font.name = '黑体'
    run.element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
    
    doc.add_paragraph()
    
    # 项目名称
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run(project_name)
    run.font.size = Pt(18)
    run.font.name = '黑体'
    run.element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
    
    doc.add_paragraph()
    
    # 文档标题
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run(title)
    run.font.size = Pt(26)
    run.font.name = '黑体'
    run.element.rPr.rFonts.set(qn('w:eastAsia'), '黑体')
    run.bold = True
    
    for _ in range(6):
        doc.add_paragraph()
    
    # 文档信息表
    table = doc.add_table(rows=len(doc_info), cols=2)
    table.alignment = WD_TABLE_ALIGNMENT.CENTER
    for i, (k, v) in enumerate(doc_info.items()):
        table.cell(i, 0).text = k
        table.cell(i, 1).text = v
        for c in [table.cell(i, 0), table.cell(i, 1)]:
            for p in c.paragraphs:
                p.alignment = WD_ALIGN_PARAGRAPH.CENTER
                for r in p.runs:
                    r.font.size = Pt(14)
    
    doc.add_page_break()

def add_revision(doc):
    """添加文档修订记录"""
    doc.add_heading('文档修订记录', level=1)
    t = doc.add_table(rows=2, cols=4)
    t.style = 'Table Grid'
    for i, h in enumerate(['版本', '日期', '修订人', '修订内容']):
        t.cell(0, i).text = h
        set_cell_shading(t.cell(0, i), 'D9E2F3')
    t.cell(1, 0).text = 'V1.0'
    t.cell(1, 1).text = '2024-01-01'
    t.cell(1, 2).text = '—'
    t.cell(1, 3).text = '初始版本'
    doc.add_page_break()

def add_toc(doc):
    """添加目录占位符"""
    doc.add_heading('目  录', level=1)
    p = doc.add_paragraph('（正式发布时自动生成）')
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    doc.add_page_break()

def T(doc, headers, rows):
    """添加带样式的表格"""
    t = doc.add_table(rows=1 + len(rows), cols=len(headers))
    t.style = 'Table Grid'
    for i, h in enumerate(headers):
        t.cell(0, i).text = h
        set_cell_shading(t.cell(0, i), 'D9E2F3')
    for ri, row in enumerate(rows):
        for ci, val in enumerate(row):
            t.cell(ri + 1, ci).text = str(val)
    return t

def P(doc, text, style=None):
    """添加段落"""
    if style:
        doc.add_paragraph(text, style=style)
    else:
        doc.add_paragraph(text)

def B(doc, text):
    """添加加粗文本"""
    p = doc.add_paragraph()
    run = p.add_run(text)
    run.bold = True
    return p

# 使用示例
if __name__ == '__main__':
    doc = create_doc()
    
    # 封面
    add_cover(
        doc,
        unit_name='XX省市场监督管理局数据应用中心',
        project_name='应急指挥调度中心运维服务项目（2024-2025）',
        title='需求规格说明书',
        doc_info={
            '文档编号：': 'SRS-XXX-2024-001',
            '版本号：': 'V1.0',
            '编制日期：': '2024年01月01日',
            '密  级：': '内部'
        }
    )
    
    # 修订记录
    add_revision(doc)
    
    # 目录
    add_toc(doc)
    
    # 正文
    doc.add_heading('1  引言', level=1)
    doc.add_heading('1.1  编写目的', level=2)
    P(doc, '本文档是《XXX》的需求规格说明书...')
    
    # 表格
    T(doc, ['列1', '列2', '列3'], [
        ['数据1', '数据2', '数据3'],
        ['数据4', '数据5', '数据6'],
    ])
    
    # 列表
    P(doc, '功能需求：', style='List Bullet')
    P(doc, '需求1', style='List Bullet')
    P(doc, '需求2', style='List Bullet')
    
    # 保存
    doc.save('output.docx')

文档类型模板

需求规格说明书（SRS）

标准章节结构：

1  引言
    1.1  编写目的
    1.2  项目背景
    1.3  术语定义
    1.4  参考文档
2  项目概述
    2.1  项目基本信息
    2.2  建设目标
    2.3  系统总体架构
3  功能需求
    3.1  子系统1功能需求
    3.2  子系统2功能需求
4  非功能需求
    4.1  性能要求
    4.2  安全要求
5  接口需求
6  数据需求
7  验收标准
附录  功能点清单

概要设计说明书（HLD）

标准章节结构：

1  引言
    1.1  编写目的
    1.2  参考文档
2  系统架构设计
    2.1  总体架构
    2.2  技术选型
3  模块划分
    3.1  模块结构
    3.2  模块职责
4  数据库概要设计
    4.1  ER模型
    4.2  核心数据表
5  接口设计
    5.1  内部接口
    5.2  外部接口
6  安全架构
7  部署设计

详细设计说明书（DD）

标准章节结构：

1  引言
    1.1  编写目的
    1.2  参考文档
2  后台服务详细设计
    2.1  项目工程结构
    2.2  模块1详细设计
    2.3  模块2详细设计
3  前端详细设计
    3.1  技术架构
    3.2  页面清单
4  数据库详细设计
    4.1  表结构定义
    4.2  索引设计
5  接口详细设计
    5.1  接口清单
    5.2  请求/响应示例
6  关键算法设计
7  页面/UI设计
附录A  错误码定义
附录B  数据字典

质量检查清单

格式检查

• 封面信息完整（单位、项目、标题、编号、版本、日期）
• 修订记录表格正确
• 目录占位符已添加
• 页边距设置正确（2.54cm上下，3.17cm左右）
• 正文字体为仿宋12pt
• 标题字体为黑体（22pt/16pt/14pt）
• 表格样式为Table Grid
• 表头背景色为#D9E2F3

内容检查

• 章节编号连续无跳跃
• 表格列数与表头一致
• 列表样式统一
• 无占位符或TODO标记
• 专业术语使用正确

输出检查

• 文件名规范（项目名_文档类型_版本.docx）
• 文件可正常打开
• 打印预览正常
• 无乱码或特殊字符

依赖安装

# 使用pip安装
pip install python-docx

# 或使用uv安装
uv pip install python-docx

注意事项

1. 字体依赖：确保系统安装了仿宋和黑体字体
2. 中文编码：文件保存时使用UTF-8编码
3. 表格宽度：多列表格注意设置合适的列宽
4. 分页符：章节之间使用doc.add_page_break()分页
5. 图片插入：如需插入图片，使用doc.add_picture()方法