| 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)
section.bottom_margin = Cm(2.54)
section.left_margin = Cm(3.17)
section.right_margin = Cm(3.17)
字体规范
正文字体
- 中文：仿宋
- 英文：Times New Roman
- 字号：12pt（小四号）
- 行距：1.5倍行距
标题字体
| 标题级别 | 字体 | 字号 | 对齐方式 |
|---|
| 一级标题 | 黑体 | 22pt（二号） | 左对齐 |
| 二级标题 | 黑体 | 16pt（三号） | 左对齐 |
| 三级标题 | 黑体 | 14pt（四号） | 左对齐 |
表格字体
- 表头：黑体 11pt，加粗，居中，背景色 #D9E2F3
- 表格内容：仿宋 11pt
表格规范
表格样式
table.style = 'Table Grid'
表格背景色
set_cell_shading(cell, 'D9E2F3')
写作风格要求
技术文档写作原则
- 准确性：技术描述必须准确，不能有歧义
- 完整性：覆盖所有技术细节，不留空白
- 一致性：术语、格式、风格保持一致
- 可追溯性：设计决策有依据，接口可追踪
段落结构
- 每个技术点先用1-2段文字说明背景和目的
- 然后用表格或列表展示详细参数
- 最后给出代码示例或配置说明
代码示例规范
- 代码使用等宽字体
- 代码块前后各空一行
- 代码需要有注释说明
内容模板
系统架构设计章节模板
2.1 总体架构
[1-2段文字说明系统整体架构设计思路]
系统采用[架构模式]架构，整体分为[N]个层次：
[表格展示各层次的组件和技术]
各层次之间的通信方式如下：
[文字说明层次间交互]
数据库设计章节模板
4.2 表结构设计
[1段文字说明数据库设计原则]
表名：xxx（表中文名）
[表格展示字段定义：字段名、类型、长度、必填、默认值、说明]
索引设计：
[表格展示索引信息]
接口设计章节模板
5.2 接口清单
[1段文字说明接口设计规范]
[表格展示接口列表：接口名称、方法、路径、参数、说明]
请求示例：
[JSON格式的请求示例]
响应示例：
[JSON格式的响应示例]
代码示例
基础模板
"""技术规格说明书生成模板"""
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)
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')
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组件库'],
])
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 → 返回客户端')
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停用）'],
])
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', '创建新用户'],
])
doc.add_heading('6 安全设计', level=1)
P(doc, '系统采用多层次安全防护机制，确保系统和数据安全。')
T(doc, ['安全层面', '措施', '实现'], [
['身份认证', 'JWT Token', '登录后颁发Token，有效期2小时'],
['访问控制', 'RBAC', '基于角色的权限控制'],
['传输安全', 'HTTPS', '全链路加密传输'],
['数据安全', '加密存储', '密码BCrypt加密，敏感字段AES加密'],
])
doc.add_heading('7 性能设计', level=1)
P(doc, '系统通过多层缓存、数据库优化、异步处理等手段保障性能。')
T(doc, ['优化层面', '措施', '预期效果'], [
['缓存', 'Redis缓存热点数据', '减少数据库查询80%'],
['数据库', '索引优化、读写分离', '查询响应<100ms'],
['异步', '消息队列异步处理', '提升吞吐量3倍'],
])
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)
