writing-tech-specs

编写技术规格说明

目的

生成轻量、简洁的技术规格说明文档，用 PlantUML 图表和简短描述说明有哪些变更。这些规格说明侧重于所做的变更，而非实现细节。

适用场景

• 用户请求“技术规格说明”“技术规范”或“tech-spec”
• 用户提到“创建规格说明”“编写规格说明”或“实现规格说明”
• 用户希望在实现前记录功能变更
• 用户需要在团队内沟通设计决策

流程

1. 收集需求

向用户询问必要信息。如果用户不清楚某些内容，帮助他们梳理：

• 功能/任务标题：要构建或变更什么？
• 范围：会影响哪些服务？（node-core、node-auth、frontend 等）
• 主要变更：
  • 新增或修改的 API 端点
  • 数据库架构变更（新表、新列）
  • 新增或变更的业务流程
  • 前端变更（屏幕、组件）

2. 生成规格说明结构

使用以下模板结构：

# [tech-spec] <Title>

* 1 [Infrastructure](#Infrastructure)
  * 1.1 [<service-name>](#<service-name>)
* 2 [Model](#Model)
  * 2.1 [<service-name>](#<service-name>)
    * 2.1.1 [<EntityName>](#<EntityName>)
* 3 [Flow](#Flow)
  * 3.1 [Backend](#Backend)
    * 3.1.1 [<service-name>](#<service-name>)
* 4 [Happy path](#Happy-path)
* 5 [Backwards compatibility](#Backwards-compatibility)

# Infrastructure

## <service-name>

<API endpoints, permissions, cron jobs>

# Model

## <service-name>

### <EntityName>

<PlantUML class diagram in code block>

# Flow

## Backend

### <service-name>

<PlantUML activity/sequence diagram in code block>

# Happy path

<Brief description or test scenarios>

# Backwards compatibility

<Notes if applicable, omit if not needed>

3. 编写各个章节

基础设施章节

列出 API 端点并简要说明：

* POST /users/me/terms-and-conditions/latest/accept
  * response `{"successful": true}`

或包含请求正文：

* PATCH /tenant-benefits/:tenantBenefitId/order
  * body: { direction: up/down }

模型章节

使用代码块中的 PlantUML 类图。对于现有且未变更的字段，使用 ...：

### Appointment

@startuml class Appointment { ... status: string [enum: scheduled, in_progress, completed] } @enduml

对于新表，列出所有字段：

### IntegrationMapping (new table)

@startuml class IntegrationMapping { id: uuid integrationSystem: enum type: string key: string value: string } @enduml

流程章节

后端流程使用代码块中的 PlantUML 活动图：

### Claim item correct/incorrect flow

@startuml () --> "Claim Submitted for Review" #lightblue if "Is correct?" then --> [Yes] "Update correct fields" --> () else --> [No] "Update incorrect fields" --> "Returned to Patient" #lightblue --> (*) @enduml

跨服务通信使用序列图：

@startuml actor "User" as user participant "Service A" as a participant "Service B" as b user -> a: Request a -> b: Call b --> a: Response a --> user: Result @enduml

顺利路径章节

简要描述或测试场景：

Check that the user cannot use the app if he doesn't accept the latest T&C.
After accepting, the user should be able to use the app with no restrictions.

或使用项目符号：

* Check if an appointment can be flagged for did-not-attend successfully.
* Verify that an error is thrown when trying to flag a cancelled appointment.

向后兼容性章节

仅在需要时包含。保持简短：

Migration: Create repository records from unique combinations, then add FK.

4. 保存并输出

• 如有需要，创建目录：mkdir -p resource/tech-spec
• 写入 resource/tech-spec/<tech-spec-title>.md（使用 kebab-case）
• 将文件路径返回给用户

关键规则

遵循以下规则，确保规格说明重点突出、易于阅读：

1. 不要比较文件结构——规格说明描述变更内容，而非文件所在位置
2. 不要使用文件映射表——这是实现细节，不属于规格说明
3. 不要说明导入项更新策略——这属于实现内容，而非规格说明
4. 不要提供代码示例——PlantUML 图表通用性更强，也更少依赖具体语言
5. 不要使用检查清单——检查清单适用于任务/用户故事；规格说明描述的是系统状态
6. 不要提供分步实现说明——规格说明描述的是“是什么”，而非“怎么做”
7. 保持简短——每项用 1-2 句话说明；复杂流程使用图表
8. PlantUML 使用代码块——可提高可读性并改善格式

范围指导

如果规格说明过于庞大，可以考虑拆分：

• 受影响的服务超过 3 个？考虑按服务分别编写规格说明
• 模型变更超过 8 项？考虑按领域拆分
• 复杂流程超过 4 个？考虑按用户旅程拆分

示例

最简规格说明

# [tech-spec] Custom order for tenant benefits

* 1 [Infrastructure](#Infrastructure)
  * 1.1 [node-core](#node-core)
* 2 [Model](#Model)
  * 2.1 [node-core](#node-core.1)

# Infrastructure

## node-core

* PATCH /tenant-benefits/:tenantBenefitId/order
  * body: { direction: up/down }

# Model

## node-core

@startuml class TenantBenefit { ... order: number } @enduml

含流程的规范

# [tech-spec] Claim item locking

* 1 [Model](#Model)
  * 1.1 [node-core](#node-core)
* 2 [Flow](#Flow)
  * 2.1 [Backend](#Backend)
* 3 [Happy path](#Happy-path)

# Model

## node-core

### ReimbursementClaimItem

@startuml class ReimbursementClaimItem { ... incorrectAt?: number incorrectById?: string incorrectReason?: string correctAt?: number correctById?: string } @enduml

# Flow

## Backend

### Claim item correct/incorrect flow

@startuml () --> "Claim Submitted for Review" #lightblue if "Is correct?" then --> [Yes] "Update correct fields" --> () else --> [No] "Update incorrect fields" --> "Returned to Patient" #lightblue --> (*) @enduml

# Happy path

Advisor marks claim items as correct/incorrect. Patient sees which items need correction.

章节参考

章节	适用场景	内容
基础设施	新增/变更端点、定时任务、权限	简要列出 API
模型	数据库架构变更	PlantUML 类图
流程	新增或变更业务逻辑	PlantUML 活动图/时序图
顺利流程	始终包含	简要描述或测试场景
向后兼容性	破坏性变更	迁移说明
部署	特殊部署需求	仅在必要时包含

更多示例

完整的参考规范请参见 ./examples 文件夹，涵盖：

• API 设计模式
• 跨服务通信
• 复杂状态机
• 前端流程