tech-spec

name	tech-spec
description	生成技术规格说明书（Technical Specification）。当用户需要编写技术方案、技术规格、技术设计文档、技术架构文档、接口规格说明书时使用此skill。

技术规格说明书生成规范

适用场景

• 技术方案设计文档
• 技术规格说明书
• 技术架构设计文档
• 接口规格说明书
• 系统设计文档
• 数据库设计文档
• API设计文档

与需求规格说明书的区别

文档类型	侧重点	读者
需求规格说明书	做什么（What）	业务人员、项目经理
技术规格说明书	怎么做（How）	开发人员、架构师

文档结构规范

标准文档结构

1  引言
    1.1  编写目的
    1.2  术语定义
    1.3  参考文档
2  系统架构设计
    2.1  总体架构
    2.2  技术选型
    2.3  部署架构
3  功能模块设计
    3.1  模块1详细设计
    3.2  模块2详细设计
4  数据库设计
    4.1  数据库概述
    4.2  表结构设计
    4.3  索引设计
5  接口设计
    5.1  接口规范
    5.2  接口清单
    5.3  请求/响应示例
6  安全设计
7  性能设计
8  运维设计
附录A  错误码定义
附录B  数据字典

封面页规范

封面内容

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

[空行 × 6]

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

页边距设置

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')  # 浅蓝色

写作风格要求

技术文档写作原则

1. 准确性：技术描述必须准确，不能有歧义
2. 完整性：覆盖所有技术细节，不留空白
3. 一致性：术语、格式、风格保持一致
4. 可追溯性：设计决策有依据，接口可追踪

段落结构

• 每个技术点先用1-2段文字说明背景和目的
• 然后用表格或列表展示详细参数
• 最后给出代码示例或配置说明

代码示例规范

• 代码使用等宽字体
• 代码块前后各空一行
• 代码需要有注释说明

内容模板

系统架构设计章节模板

2.1  总体架构

[1-2段文字说明系统整体架构设计思路]

系统采用[架构模式]架构，整体分为[N]个层次：

[表格展示各层次的组件和技术]

各层次之间的通信方式如下：
[文字说明层次间交互]

数据库设计章节模板

4.2  表结构设计

[1段文字说明数据库设计原则]

表名：xxx（表中文名）

[表格展示字段定义：字段名、类型、长度、必填、默认值、说明]

索引设计：
[表格展示索引信息]

接口设计章节模板

5.2  接口清单

[1段文字说明接口设计规范]

[表格展示接口列表：接口名称、方法、路径、参数、说明]

请求示例：
[JSON格式的请求示例]

响应示例：
[JSON格式的响应示例]

代码示例

基础模板

#!/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, title, doc_info):
    """添加封面页"""
    for _ in range(6):
        doc.add_paragraph()
    
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run('四川省市场监督管理局数据应用中心')
    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('应急指挥调度中心运维服务项目（2024-2025）')
    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


def gen_tech_spec(output_path):
    """生成技术规格说明书"""
    doc = create_doc()
    
    # 封面
    add_cover(
        doc,
        title='技 术 规 格 说 明 书',
        doc_info={
            '文档编号：': 'TS-XXX-2024-001',
            '版本号：': 'V1.0',
            '编制日期：': '2024年01月01日',
            '密  级：': '内部'
        }
    )
    
    # 修订记录
    add_revision(doc)
    
    # 目录
    add_toc(doc)
    
    # 1 引言
    doc.add_heading('1  引言', level=1)
    doc.add_heading('1.1  编写目的', level=2)
    P(doc, '本文档是《XXX系统》的技术规格说明书，详细描述系统的技术架构、模块设计、数据库设计、接口设计等技术实现方案。本文档供开发人员、测试人员、运维人员使用。')
    
    doc.add_heading('1.2  术语定义', level=2)
    T(doc, ['术语', '说明'], [
        ['API', 'Application Programming Interface，应用程序编程接口'],
        ['REST', 'Representational State Transfer，表述性状态转移'],
        ['JWT', 'JSON Web Token，JSON网络令牌'],
    ])
    
    doc.add_heading('1.3  参考文档', level=2)
    P(doc, '《需求规格说明书》V1.0', style='List Bullet')
    
    # 2 系统架构设计
    doc.add_heading('2  系统架构设计', level=1)
    doc.add_heading('2.1  总体架构', level=2)
    P(doc, '系统采用前后端分离的微服务架构，整体分为表现层、业务层、数据层三个层次。各层职责清晰，松耦合设计，支持独立部署和水平扩展。')
    T(doc, ['层次', '技术组件', '职责'], [
        ['表现层', 'Vue 3 + Element Plus', '用户界面展示、交互处理'],
        ['业务层', 'Spring Boot + MyBatis', '业务逻辑处理、数据校验'],
        ['数据层', 'MySQL + Redis', '数据持久化、缓存管理'],
    ])
    
    doc.add_heading('2.2  技术选型', level=2)
    P(doc, '根据项目需求和技术评估，选择以下技术栈：')
    T(doc, ['类别', '技术', '版本', '说明'], [
        ['后端框架', 'Spring Boot', '2.7.x', 'Java微服务框架'],
        ['ORM框架', 'MyBatis', '3.5.x', '数据持久化框架'],
        ['数据库', 'MySQL', '8.0', '关系型数据库'],
        ['缓存', 'Redis', '6.x', '内存缓存数据库'],
        ['前端框架', 'Vue 3', '3.2.x', '渐进式JavaScript框架'],
        ['UI组件库', 'Element Plus', '2.x', 'Vue 3组件库'],
    ])
    
    # 3 功能模块设计
    doc.add_heading('3  功能模块设计', level=1)
    doc.add_heading('3.1  用户管理模块', level=2)
    P(doc, '用户管理模块负责系统用户的全生命周期管理，包括用户注册、登录认证、信息维护、权限控制等功能。')
    B(doc, '核心类设计：')
    T(doc, ['类名', '类型', '职责'], [
        ['UserController', 'Controller', '用户API接口'],
        ['UserService', 'Service', '用户业务逻辑'],
        ['UserMapper', 'Mapper', '用户数据访问'],
        ['User', 'Entity', '用户实体'],
    ])
    B(doc, '核心流程：')
    P(doc, '用户登录流程：用户提交用户名密码 → 密码RSA解密 → BCrypt校验 → 生成JWT Token → 返回客户端')
    
    # 4 数据库设计
    doc.add_heading('4  数据库设计', level=1)
    doc.add_heading('4.1  数据库概述', level=2)
    P(doc, '系统使用MySQL 8.0作为主数据库，数据库名：yjzh_sc。采用UTF-8字符集，支持emoji表情。')
    doc.add_heading('4.2  表结构设计', level=2)
    B(doc, 'sys_user（用户表）：')
    T(doc, ['字段名', '类型', '必填', '说明'], [
        ['user_id', 'BIGINT', '是', '用户ID，主键'],
        ['user_name', 'VARCHAR(30)', '是', '用户账号'],
        ['password', 'VARCHAR(100)', '是', '密码（BCrypt加密）'],
        ['status', 'CHAR(1)', '是', '状态（0正常 1停用）'],
    ])
    
    # 5 接口设计
    doc.add_heading('5  接口设计', level=1)
    doc.add_heading('5.1  接口规范', level=2)
    P(doc, '所有接口遵循RESTful设计规范，统一使用JSON格式。请求头需要携带JWT Token进行认证。')
    T(doc, ['规范项', '说明'], [
        ['请求方式', 'GET/POST/PUT/DELETE'],
        ['Content-Type', 'application/json'],
        ['认证方式', 'Authorization: Bearer <token>'],
        ['响应格式', '{"code":200,"message":"success","data":{...}}'],
    ])
    doc.add_heading('5.2  接口清单', level=2)
    T(doc, ['接口', '方法', '路径', '说明'], [
        ['用户登录', 'POST', '/api/login', '用户登录认证'],
        ['获取用户', 'GET', '/api/user/{id}', '获取用户详情'],
        ['创建用户', 'POST', '/api/user', '创建新用户'],
    ])
    
    # 6 安全设计
    doc.add_heading('6  安全设计', level=1)
    P(doc, '系统采用多层次安全防护机制，确保系统和数据安全。')
    T(doc, ['安全层面', '措施', '实现'], [
        ['身份认证', 'JWT Token', '登录后颁发Token，有效期2小时'],
        ['访问控制', 'RBAC', '基于角色的权限控制'],
        ['传输安全', 'HTTPS', '全链路加密传输'],
        ['数据安全', '加密存储', '密码BCrypt加密，敏感字段AES加密'],
    ])
    
    # 7 性能设计
    doc.add_heading('7  性能设计', level=1)
    P(doc, '系统通过多层缓存、数据库优化、异步处理等手段保障性能。')
    T(doc, ['优化层面', '措施', '预期效果'], [
        ['缓存', 'Redis缓存热点数据', '减少数据库查询80%'],
        ['数据库', '索引优化、读写分离', '查询响应<100ms'],
        ['异步', '消息队列异步处理', '提升吞吐量3倍'],
    ])
    
    # 8 运维设计
    doc.add_heading('8  运维设计', level=1)
    P(doc, '系统采用容器化部署，支持Kubernetes编排，提供完善的监控告警机制。')
    T(doc, ['组件', '技术', '说明'], [
        ['容器化', 'Docker', '应用容器化部署'],
        ['编排', 'Kubernetes', '容器编排和调度'],
        ['监控', 'Prometheus + Grafana', '系统监控和可视化'],
        ['日志', 'ELK Stack', '日志收集和分析'],
    ])
    
    # 附录
    doc.add_heading('附录A  错误码定义', level=1)
    T(doc, ['错误码', '说明', '处理建议'], [
        ['200', '成功', '—'],
        ['400', '参数错误', '检查请求参数'],
        ['401', '未认证', '重新登录'],
        ['403', '无权限', '联系管理员'],
        ['500', '服务器错误', '联系运维人员'],
    ])
    
    doc.add_heading('附录B  数据字典', level=1)
    T(doc, ['字典类型', '编码', '值', '说明'], [
        ['用户状态', 'STATUS', '0', '正常'],
        ['用户状态', 'STATUS', '1', '停用'],
        ['性别', 'SEX', '0', '男'],
        ['性别', 'SEX', '1', '女'],
    ])
    
    doc.save(output_path)
    print(f'已生成：{output_path}')


if __name__ == '__main__':
    import sys
    output = sys.argv[1] if len(sys.argv) > 1 else 'tech_spec.docx'
    gen_tech_spec(output)