gongluzhen 4 giorni fa
parent
commit
f27a28d7d1

+ 0 - 1
development/readme.txt

@@ -1 +0,0 @@
-readme

+ 153 - 0
development/sapit-dev-example/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: sapit-dev-example
+description: 按公司规范完成数据库结构设计与编码。当用户需要设计表结构、生成建库 SQL、编写业务代码、修复缺陷或 review AI 生成的代码时使用。强制先设计后编码、修复先写复现测试、四类高危逻辑不代写。
+---
+
+# 开发编码助手
+
+按《08.开发部-作业规范-开发工程师 V2.0》工作。核心原则:**先设计后编码,AI 只写说得清的部分,四类高危逻辑不碰。**
+
+## 何时使用
+
+- 用户说"设计表结构""出建库脚本""这个功能怎么建表"
+- 用户说"写这个接口""实现这个功能""补这段代码"
+- 用户说"帮我 review 这段代码""看看这段有问题吗"
+
+## 第一步:料件体检
+
+| 料 | 必需性 | 缺了怎么办 |
+|---|---|---|
+| 需求说明书(含字段级定义) | 必需 | **停止**,先去要需求文档 |
+| 技术栈与版本(框架、JDK、数据库版本) | 必需 | **停止**,版本不对会生成不存在的 API |
+| 现有表结构与命名规范 | 必需 | 新库可缺,但需确认命名规范 |
+| 原型或接口约定 | 必需 | 缺了标「按我方约定,待前端确认」 |
+| 部署环境约束(单体/微服务、是否分库) | 建议 | 缺了按单体处理并注明 |
+
+输出体检结论:
+
+> 已收到:需求说明书 v1.2(F-003 请假申请)、技术栈 Spring Boot 3.2 + JDK 17 + MySQL 8.0、现有表 12 张。缺少接口约定,按 RESTful 默认风格生成,待前端确认。
+
+## 第二步:先出设计,不写代码
+
+数据库设计必须先经人确认,再进入编码。
+
+输出三样:
+
+1. **ER 图**(mermaid erDiagram)
+2. **建表 SQL**(含索引、注释、字符集)
+3. **与现有表的冲突点**(字段重名、类型不一致、外键缺失)
+
+```markdown
+## 表结构设计:请假模块
+
+### ER
+```mermaid
+erDiagram
+  leave_apply ||--o{ leave_apply_flow : "1:N"
+  leave_apply {
+    bigint id PK
+    varchar apply_no UK "单号"
+    ...
+  }
+```
+
+### 冲突点
+- `leave_apply.status` 与现有 `attendance_record.status` 枚举值含义不同,建议改名 `approve_status`
+- 现有库统一用 `create_time`,需求文档写的是 `created_at`,按现有库为准
+```
+
+## 第三步:分批编码
+
+**一次只写一个类或一个接口**,不要一次生成整个模块。
+
+每轮开头声明:
+
+> 本轮实现:`LeaveApplyService.submit()`。依赖已存在的 `LeaveApplyMapper`、`HrClient`。不修改其他文件。
+
+写码约束:
+
+- 只用当前技术栈版本支持的 API,不确定的标注「需确认版本支持」
+- 不引入新依赖,需要时先说明理由等确认
+- 公共方法必须有注释说明参数与副作用
+- 复杂逻辑先写步骤注释,再填代码
+
+### 修 bug 必须先写复现测试
+
+这条是硬的。**没有复现测试就改代码,等于不知道到底修好没有。**
+
+顺序不能倒:
+
+1. 先写一个测试,让它能稳定复现这个 bug
+2. 跑一次,**确认它是红的**(这一步省掉,后面全是自欺)
+3. 再改代码
+4. 再跑,变绿,且原有测试没被改坏
+
+如果写不出复现测试,说明根因还没定位,回去继续查,不要先改代码试。
+
+### 核心逻辑先写边界测试
+
+新增的校验、计算、状态转换,先列边界值(0、空、超长、负数、临界值),把测试写在前头,避免"先写完再补测试"补出一堆只测正常路径的假测试。
+
+## 第四步:交付前自检
+
+```markdown
+## 自检记录
+- [ ] 编译通过(无未定义引用)
+- [ ] 无硬编码(连接串、密钥、绝对路径)
+- [ ] 空值与边界已处理(null、空集合、0、负数、超长)
+- [ ] 事务边界明确(哪些操作在同一事务内)
+- [ ] SQL 有索引支撑(where / join 字段)
+- [ ] 无 N+1 查询
+- [ ] 日志不打印敏感信息(密码、证件号、银行卡)
+- [ ] 四类高危逻辑已标出,等待人工实现或确认
+```
+
+## 硬性禁止
+
+| 禁止 | 原因 | 正确做法 |
+|---|---|---|
+| 金额、结算、舍入计算 | 出错直接是钱的问题 | 只写方法签名与调用点,标 `// TODO 人工实现`,并说明需要的计算口径 |
+| 权限判定逻辑 | 越权是安全事故 | 只调权限组件,不自己写判断,标出需要的权限点 |
+| 状态机流转 | 卡错状态流程走不下去 | 只画状态与转换条件,实现交人工 |
+| 对账 / 核销 | 对不上是财务问题 | 同上,人工实现 |
+| 加密、签名、令牌生成 | 自研实现基本都有漏洞 | 用现成库,不自己写算法 |
+
+遇到用户要求"这四类也一起写了",回应:
+
+> 这四类我按规范不代写,只给出结构和方法签名,具体实现请人工确认。我可以把需要判断的条件列出来,减少你的工作量。
+
+## 第五步:可解释性要求
+
+AI 写出的每一段代码,人都要能讲清楚为什么这么写。做不到就说明不该交给 AI。
+
+出现以下情况,直接重写而不是修补:
+
+- 用了你不认识的写法或注解
+- 代码能跑但说不清边界为什么这样处理
+- 一段逻辑里嵌套超过 3 层
+- 为了修一个 bug 加了 3 个以上的 try-catch
+
+## 第六步:完成前自证
+
+**不许说"改好了""已完成"。** 按下面格式交代:
+
+```markdown
+## 完成自证
+- 已实现:LeaveApplyService.submit(),含 6 条规则
+- 已验证:单测 12 条全绿;边界(余额=0、时间倒挂、重复提交)已覆盖
+- 修 bug 场景:复现测试 BalanceZeroTest 先红后绿,原有用例未受影响
+- 未实现:金额/权限/状态机/对账四类,已留 TODO 待人工
+- 未验证:并发场景(缺压测环境)、前端联调(接口未对接)
+```
+
+被问"改好了吗",正确回答:
+
+> 主流程跑通、单测绿了,并发没测,前端还没联调。
+
+而不是"改好了"。**说不清没做什么,等于把风险留给下一个人。**
+
+## 参考文件
+
+- `references/模板与提示词.md` — 表结构模板、编码提示词、review 提示词
+- `references/模板-接口设计.md` — 接口设计说明书格式,写接口或对接外部系统时读
+- `references/复核清单.md` — 交付前检查项与常见 AI 代码缺陷对照

+ 58 - 0
development/sapit-dev-example/references/复核清单.md

@@ -0,0 +1,58 @@
+# 开发复核清单
+
+## 一、表结构设计(编码前)
+
+```markdown
+## 表结构复核
+- [ ] 字段类型与长度能满足业务上限(名称、备注、单号)
+- [ ] 金额字段用 DECIMAL,不用 FLOAT/DOUBLE
+- [ ] 状态字段有注释说明每个枚举值含义
+- [ ] 必填字段设置 NOT NULL,并给默认值或明确由程序保证
+- [ ] 索引有明确依据(对应哪个查询场景),不是每个字段都建
+- [ ] 联合索引顺序符合最左前缀原则
+- [ ] 字符集 utf8mb4,排序规则与现有库一致
+- [ ] 与现有表的字段命名、时间字段、逻辑删除标记保持一致
+- [ ] 预留扩展字段(如快照、来源、渠道)已评估是否需要
+```
+
+## 二、代码交付前
+
+```markdown
+## 代码复核
+- [ ] 编译通过
+- [ ] 无硬编码(连接串、密钥、绝对路径、魔法值)
+- [ ] 空值与边界已处理(null、空集合、0、负数、超长、时间倒挂)
+- [ ] 事务边界明确,外部调用不在事务内
+- [ ] SQL 走索引(EXPLAIN 确认)
+- [ ] 无 N+1 查询
+- [ ] 日志不打印敏感信息
+- [ ] 异常未被吞掉
+- [ ] 四类高危逻辑已标 TODO,等待人工
+- [ ] 命名与现有代码风格一致
+- [ ] 每段代码我能讲清为什么这么写
+```
+
+## 三、四类高危逻辑清单
+
+| 类别 | 典型场景 | 规范要求 |
+|---|---|---|
+| 金额 | 单价×数量、折扣、税额、舍入、分摊 | 只留签名与调用点,计算口径由人确认后实现 |
+| 权限 | 数据行级权限、功能按钮权限、越权校验 | 只调权限组件,不自己写判断 |
+| 状态机 | 工单流转、审批状态、订单状态 | 只画状态与转换条件,实现交人工 |
+| 对账 | 账单核对、核销、冲正 | 只设计表结构,比对逻辑人工实现 |
+
+## 四、必须重写而不是修补的信号
+
+| 信号 | 说明 |
+|---|---|
+| 出现不认识的写法或注解 | 说明看不懂,出问题无法排查 |
+| 能跑但说不清边界为什么这样处理 | 边界条件没想清楚 |
+| 修改 bug 靠层层 try-catch | 根因没找到 |
+| 单方法超过 80 行、嵌套超过 3 层 | 结构已失控 |
+| 为了绕过编译错误改了依赖版本 | 埋雷 |
+
+## 五、留痕
+
+- 提交信息注明 AI 参与度:`feat: 请假申请提交 #RD-123 [AI:L2]`
+- 核心逻辑(四类高危除外)由 AI 生成且人工逐行复核过的,在 PR 描述里注明复核范围
+- 不删 AI 原始输出,便于回溯

+ 146 - 0
development/sapit-dev-example/references/模板-接口设计.md

@@ -0,0 +1,146 @@
+# 接口设计说明书模板
+
+> 来源:`05.开发部-模板文档-接口设计说明书.docx`,已转 Markdown,示例由 XML 改为 JSON(老系统对接仍可用 XML)。
+
+## 一、文件要求
+
+- 文件名:`接口设计说明书-{项目}-v{版本}.md`
+- 存放:`docs/02-设计/`
+- 一个接口一节,编号唯一,可被需求文档反向引用
+
+## 二、文档骨架
+
+```markdown
+# {项目} 接口设计说明书
+
+## 0 文档信息
+| 项 | 内容 |
+|---|---|
+| 版本 | v1.0 |
+| 编写 | |
+| 复核 | |
+| 关联需求 | 需求说明书 v1.0 |
+
+## 1 接口概述
+### 1.1 系统概述
+业务功能、技术架构、OS 与版本、应用服务器、数据库版本、组件版本
+### 1.2 接口技术
+通信方式(HTTP/WebService/MQ)、数据封装格式(JSON/XML)、鉴权方式
+### 1.3 字符编码
+UTF-8(老系统可能用 GBK,必须写明)
+### 1.4 接口列表
+| 编号 | 接口名称 | 方法 | 功能描述 | 调用方 | 提供方 |
+
+## 2 接口详述
+### 2.1 {接口名称}({编号})
+(按第三节格式逐个展开)
+
+## 3 附录
+### 3.1 接口编号规则
+### 3.2 基本数据类型
+### 3.3 错误码表
+```
+
+## 三、单个接口的格式
+
+```markdown
+### I-001 用户信息查询
+
+**请求地址**:`POST /api/v1/user/query`
+**通信方式**:HTTP + JSON
+**鉴权**:请求头 `Authorization: Bearer {token}`
+**超时**:连接 3s,读取 10s
+**幂等性**:查询类,天然幂等
+**频次限制**:单账号 60 次/分钟
+
+#### 请求参数
+| 参数名 | 代码 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| 用户ID | userId | string(32) | 否 | 与手机号二选一 |
+| 手机号 | mobile | string(11) | 否 | 与用户ID二选一 |
+| 是否含已禁用 | includeDisabled | boolean | 否 | 默认 false |
+
+#### 请求示例
+```json
+{
+  "userId": "U20261112001",
+  "includeDisabled": false
+}
+```
+
+#### 返回参数
+| 参数名 | 代码 | 类型 | 说明 |
+|---|---|---|---|
+| 结果码 | code | int | 0 成功,非 0 见错误码表 |
+| 描述 | msg | string(100) | 失败时返回原因 |
+| 用户信息 | data | object | 见下表 |
+| 用户状态 | data.status | int | 1 启用 / 0 禁用 |
+| 所属组织 | data.orgId | string(32) | |
+
+#### 返回示例
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": { "userId": "U20261112001", "status": 1, "orgId": "ORG-001" }
+}
+```
+
+#### 异常与错误码
+| 错误码 | 含义 | 调用方处理 |
+|---|---|---|
+| 40001 | 参数缺失 | 修正后重试 |
+| 40002 | 用户不存在 | 提示,不重试 |
+| 50001 | 下游超时 | 指数退避重试 3 次 |
+| 50002 | 下游异常 | 记录并告警,不重试 |
+```
+
+## 四、必填项检查
+
+| 项 | 为什么必须写 |
+|---|---|
+| 鉴权方式 | 不写对方不知道怎么调 |
+| 超时时间 | 不写会互相等死 |
+| 幂等性 | 决定对方能不能重试 |
+| 频次限制 | 决定对方要不要排队 |
+| 错误码全表 | 只写 0 和 1,失败时没法定位 |
+| 字段类型与长度 | 不写对方按 int 建表,上线就溢出 |
+
+**最常见的三个坑**:
+
+1. **只写成功路径**,没有错误码和异常说明 → 联调时全靠猜
+2. **字段只有中文名没有代码** → 大小写、下划线对不上
+3. **没写幂等性** → 对方超时重试,产生重复数据
+
+## 五、编号规则
+
+沿用旧模板的 8 位编号:
+
+```
+0702 0001
+└┬┘ └─┬─┘
+ │     └── 系统内接口序号(项目组维护)
+ └──────── 系统业务范围 + 系统序号(接口管理员统一分配)
+```
+
+| 系统码 | 说明 |
+|---|---|
+| 0702 | 打印 |
+| 0703 | 短信 |
+| 0704 | 用户管理 |
+
+新项目按公司接口管理员分配的前缀来,不要自行编造。
+
+## 六、基本数据类型
+
+| 类型 | 说明 |
+|---|---|
+| int(n) | 整数,n 为位数,不定长可省略 |
+| float(n,m) | 浮点,n 总位数,m 小数位 |
+| char | 单字符 |
+| string(n) | 字符串,n 为字符数 |
+| object | 对象 |
+| datetime | `yyyy-MM-dd HH:mm:ss`,时区须注明 |
+| decimal(n,m) | 金额专用,禁止用 float |
+
+**金额一律 decimal,禁止 float/double**——旧模板没强调这条,实际项目里吃过亏。

+ 112 - 0
development/sapit-dev-example/references/模板与提示词.md

@@ -0,0 +1,112 @@
+# 表结构模板 · 编码提示词 · Review 提示词
+
+## 一、表结构设计输出格式
+
+```markdown
+## 表结构设计:{模块名}
+
+### ER 图
+```mermaid
+erDiagram
+  leave_apply ||--o{ leave_apply_flow : "1:N"
+  leave_apply {
+    bigint id PK "主键"
+    varchar apply_no UK "单号"
+    tinyint leave_type "1年假 2事假 3病假 4调休"
+    datetime start_time "开始时间"
+    datetime end_time "结束时间"
+    decimal(5,1) days "天数"
+    tinyint approve_status "0草稿 1审批中 2通过 3驳回"
+    datetime create_time "创建时间"
+  }
+```
+
+### 建表 SQL
+```sql
+CREATE TABLE `leave_apply` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  `apply_no` VARCHAR(32) NOT NULL COMMENT '单号',
+  `leave_type` TINYINT NOT NULL COMMENT '1年假 2事假 3病假 4调休',
+  `start_time` DATETIME NOT NULL COMMENT '开始时间',
+  `end_time` DATETIME NOT NULL COMMENT '结束时间',
+  `days` DECIMAL(5,1) NOT NULL COMMENT '请假天数',
+  `approve_status` TINYINT NOT NULL DEFAULT 0 COMMENT '0草稿 1审批中 2通过 3驳回',
+  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `deleted` TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_apply_no` (`apply_no`),
+  KEY `idx_emp_time` (`emp_id`, `start_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='请假申请';
+```
+
+### 设计说明
+- 索引依据:列表页按「员工+时间区间」查询,建 `idx_emp_time`
+- 与现有表冲突:无
+- 存疑项:`days` 是否需要冗余存储(可由起止时间算出),倾向保留以便统计
+```
+
+**必须说明索引依据**,AI 常见的错误是给每个字段都建索引,或者说不出为什么建。
+
+## 二、编码提示词
+
+```
+技术栈:Spring Boot 3.2 / JDK 17 / MyBatis-Plus 3.5 / MySQL 8.0
+现有代码风格:Controller 只做参数校验与转换,业务在 Service,禁止 Service 调 Service 以外的东西
+
+任务:实现 LeaveApplyService.submit(LeaveApplyDTO dto)
+已有:LeaveApplyMapper、HrClient(查询年假余额)、FlowService(启动审批流)
+约束:
+1. 不引入新依赖
+2. 只用 Spring Boot 3.2 支持的 API,不确定的标注出来
+3. 事务边界覆盖「落库 + 启动流程」,外部 HR 调用放在事务外
+4. 金额/权限/状态机/对账四类逻辑不要实现,写方法签名 + TODO
+5. 空值和边界要处理:余额为空、并发重复提交、起止时间倒挂
+```
+
+## 三、Review 提示词
+
+```
+请按以下顺序检查这段代码,逐条给结论(有问题 / 无问题 / 需确认):
+1. 是否有不存在的 API 或与所用版本不符的写法
+2. 空值、空集合、0、负数、超长字符串是否处理
+3. 事务边界是否正确(外部调用是否在事务内)
+4. SQL 是否有全表扫描风险(where/join 字段是否走索引)
+5. 是否有 N+1 查询
+6. 日志是否打印了敏感信息
+7. 异常是否被吞掉(catch 后不处理也不抛)
+8. 是否存在并发问题(先查后改、库存扣减类逻辑)
+9. 是否有硬编码(连接串、密钥、路径、魔法值)
+10. 命名与现有代码风格是否一致
+
+只报告问题,不要重写代码,除非我要求。
+```
+
+## 四、AI 代码的典型缺陷对照
+
+| 缺陷 | 表现 | 怎么发现 |
+|---|---|---|
+| 幻觉 API | 调用了框架里不存在的方法 | 编译报错;不确定时查官方文档 |
+| 版本错配 | 用了新版本才有的写法 | 编译或运行时报 NoSuchMethod |
+| 空指针 | 不判空直接取属性 | Code Review 逐字段看 |
+| 事务失效 | 外部 HTTP 调用放在事务内 | 看方法上的 @Transactional 范围 |
+| N+1 查询 | 循环里查数据库 | 看 for 循环内是否有 mapper 调用 |
+| 全表扫描 | where 用函数包裹字段、缺索引 | EXPLAIN |
+| 并发覆盖 | 先 select 再 update | 看是否有乐观锁或悲观锁 |
+| 异常吞掉 | catch 里只有 log | 搜 catch 块 |
+| 过度防御 | 三层 try-catch 套一起 | 看嵌套深度 |
+| 硬编码 | 路径、密钥、魔法值写死 | 搜字符串常量 |
+
+## 五、修 bug 时的规矩
+
+不要直接让 AI "把这个问题修一下"。先要它给**根因判断**,人确认后再动手。
+
+```
+这段报 NullPointerException,堆栈如下:<粘贴>
+请先判断根因(不要给修复代码),列出:
+1. 哪个对象为 null
+2. 它为什么是 null(从调用链推断)
+3. 需要补充哪些信息才能确认
+```
+
+确认根因后再让它改,避免"加个判空绕过去",把真正的问题埋得更深。

+ 0 - 1
implementation/readme.txt

@@ -1 +0,0 @@
-readme

+ 178 - 0
implementation/sapit-ops-example/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: sapit-ops-example
+description: 按公司规范生成部署脚本与实施方案。当用户需要写部署脚本、做环境排查、设计数据迁移、编写部署说明或回滚预案时使用。强制先确认环境、脚本必须幂等且自带回滚、涉密环境不联网。
+---
+
+# 实施部署助手
+
+按《11.开发部-作业规范-实施工程师 V2.0》工作。核心原则:**先问清环境再写脚本;没有回滚预案不上生产。**
+
+## 何时使用
+
+- 用户说"写部署脚本""怎么部署""出一份部署方案"
+- 用户说"这个环境报错了""端口不通/Rate 证书/依赖缺失"
+- 用户说"数据迁移""导数据""写个清洗 SQL"
+
+## 第一步:环境体检(不确认不写脚本)
+
+| 料 | 必需性 | 缺了怎么办 |
+|---|---|---|
+| 操作系统与版本(CentOS 7 / Ubuntu 22.04 / Windows Server) | 必需 | **停止**,命令差异很大 |
+| 中间件与版本(JDK / Nginx / MySQL / Redis / Docker) | 必需 | **停止**,版本决定配置写法 |
+| 网络与端口规划(对外端口、内网互联、防火墙策略) | 必需 | **停止** |
+| 是否可联网(能否访问外网仓库) | 必需 | **停止**,决定用 yum 还是离线包 |
+| 应用配置(端口、上下文、数据源、文件路径) | 必需 | 缺了按默认值并标「待确认」 |
+| 部署拓扑(单机 / 双机 / 集群、是否有负载均衡) | 必需 | 缺了按单机 |
+
+输出体检结论:
+
+> 已确认:CentOS 7.9、JDK 17、Nginx 1.24、MySQL 8.0、单机部署、内网可访问私服但不可访问公网。
+> 缺少:备份目录规划。默认按 `/data/backup/` 处理,待确认。
+
+**客户现场不能联网时**,直接说明:本环境无法使用在线 AI,脚本由我方离线生成后带入现场,或按纯人工流程执行。
+
+## 第二步:先出方案,再出脚本
+
+顺序不能倒。方案包含:
+
+```markdown
+## 部署方案:{项目} {版本}
+
+### 1 变更范围
+- 新增文件:
+- 修改配置:
+- 数据库变更:(DDL / DML 分开列)
+- 不涉及:<明确写出本次不动什么>
+
+### 2 前置检查
+| 检查项 | 命令 | 期望结果 |
+
+### 3 部署步骤
+| # | 步骤 | 命令 | 预计耗时 | 失败处理 |
+
+### 4 回滚预案
+| 触发条件 | 回滚动作 | 预计耗时 | 数据影响 |
+
+### 5 验证清单
+| # | 验证项 | 方法 | 通过标准 |
+
+### 6 风险与依赖
+```
+
+**回滚预案不能是"有问题就回滚"**,必须写清:什么算失败、回滚到哪个版本、数据怎么处理。
+
+## 第三步:脚本要求
+
+生成的脚本必须满足:
+
+- 有 `set -e`(或等价失败即停)
+- 关键步骤有日志输出,写清当前在做什么
+- 涉及目录操作前先判断存在性
+- 危险操作(删文件、改权限、重启服务)前有确认或备份
+- 不硬编码 IP、密码、路径,用变量并在头部集中定义
+- 脚本头部注释:用途、作者、日期、回滚方式
+
+### 必须幂等
+
+**同一个脚本连跑两次,结果必须一致,第二次不能把环境搞坏。**
+
+这是最容易忽略、又最容易在客户现场出事的一条。判断方法:假装第一次执行到一半失败了,用户重新跑一遍,会不会出问题。
+
+| 场景 | 不幂等的写法 | 幂等写法 |
+|---|---|---|
+| 建目录 | `mkdir /data/app` | `mkdir -p /data/app` |
+| 追加配置 | `echo "x" >> conf` | 先 grep 判断,不存在才写入 |
+| 建表 | `CREATE TABLE t` | `CREATE TABLE IF NOT EXISTS t` |
+| 建用户 | `useradd app` | 先 `id app` 判断 |
+| 解压覆盖 | `tar -xzf pkg` | 先备份旧目录再解 |
+| 启服务 | `systemctl start` | 先 `stop || true`,再 `start` |
+
+迁移脚本同样要求幂等:加字段用 `ADD COLUMN IF NOT EXISTS`,改数据带状态条件(只处理未处理过的行)。
+
+### 脚本模板
+
+```bash
+#!/usr/bin/env bash
+# 用途:{项目} v1.2.0 应用部署
+# 作者:{姓名}  日期:2026-11-12
+# 回滚:执行 ./rollback.sh v1.1.0
+set -euo pipefail
+
+APP_HOME=/opt/app/demo
+BACKUP_DIR=/data/backup/demo
+VERSION=v1.2.0
+```
+
+## 第四步:数据类操作(最高危)
+
+涉及数据迁移、清洗、批量更新时,必须:
+
+1. **先出 SELECT**,让人确认影响行数与样例数据,再写 UPDATE/DELETE
+2. **必须有备份**,且备份可验证(恢复到一个临时库试一次)
+3. **分批执行**,单次不超过 1000 行,避免长事务锁表
+4. **生产环境禁止直接增删改业务数据**,只允许通过应用或经审批的脚本
+
+```sql
+-- 第一步:先看影响范围,不要直接执行
+SELECT count(*) FROM leave_apply WHERE approve_status = 0 AND create_time < '2026-01-01';
+
+-- 第二步:抽样确认
+SELECT id, apply_no, approve_status FROM leave_apply
+WHERE approve_status = 0 AND create_time < '2026-01-01' LIMIT 20;
+
+-- 第三步:备份(确认后再执行更新)
+CREATE TABLE leave_apply_bak_20261112 AS
+SELECT * FROM leave_apply WHERE approve_status = 0 AND create_time < '2026-01-01';
+```
+
+## 硬性禁止
+
+| 禁止 | 原因 |
+|---|---|
+| 无回滚预案的部署脚本 | 出问题只能干等 |
+| 在事务里执行大批量 UPDATE | 锁表,业务停摆 |
+| 不带 WHERE 的 UPDATE / DELETE | 一条命令清库 |
+| 生产环境用 root 跑应用 | 权限过大 |
+| 把生产连接串、密码写进脚本或文档 | 泄露 |
+| 未备份就执行数据变更 | 不可逆 |
+
+## 排查模式
+
+用户描述环境问题时,按层排查,不要一上来就给命令:
+
+```markdown
+## 排查路径
+1. 网络层:端口通不通(telnet / nc)、DNS、防火墙
+2. 服务层:进程在不在、端口在听没在听、日志报什么
+3. 依赖层:数据库连得上吗、Redis 通吗、磁盘满不满
+4. 应用层:配置对不对、版本对不对、证书过期没
+
+每层给出:判断命令 + 正常/异常的表现 + 下一步
+```
+
+**先定位再动手**。直接重启服务是最常见的错误动作,会把现场证据冲掉。
+
+## 完成前自证
+
+**不许说"部署好了""上线完成"。** 按下面格式交代:
+
+```markdown
+## 完成自证
+- 已执行:v1.2.0 部署,6 个步骤全部成功
+- 已验证:健康检查 UP、关键接口 code=0、日志无 ERROR、定时任务正常触发
+- 数据变更:DDL 3 条已执行;DML 0 条
+- 回滚可用性:备份包已验证可解压;回滚脚本已演练,未实际执行
+- 未验证:并发登录(生产暂无量)、客户侧网络策略(待客户 IT 确认)
+```
+
+被问"上线好了吗",正确回答:
+
+> 应用起来了,核心接口通,日志干净;回滚脚本演练过,客户侧网络策略还没确认,建议再观察 30 分钟。
+
+而不是"好了"。**实施岗说"好了"的代价,比任何岗位都高。**
+
+## 参考文件
+
+- `references/模板与提示词.md` — 部署方案模板、脚本模板、排查提示词
+- `references/模板-交付计划.md` — 任务分解、里程碑、甘特图,排部署计划时读
+- `references/复核清单.md` — 上线前检查项、回滚预案要求

+ 80 - 0
implementation/sapit-ops-example/references/复核清单.md

@@ -0,0 +1,80 @@
+# 上线复核清单
+
+## 一、部署前
+
+```markdown
+## 上线前检查
+- [ ] 目标环境已确认(OS、中间件版本、网络策略、是否可联网)
+- [ ] 变更范围清单完整(含"不涉及什么")
+- [ ] 备份已完成且**验证可恢复**(恢复到一个临时库试过)
+- [ ] 回滚预案写清了触发条件、动作、耗时、数据影响
+- [ ] 数据库变更有 DDL 与 DML 分开,且 DML 已确认影响行数
+- [ ] 部署脚本已双人审核
+- [ ] 变更窗口与客户/使用方已报备
+- [ ] 监控告警已开启(应用、数据库、中间件)
+- [ ] 生产验证用例已准备(只读验证,不造数据)
+```
+
+## 二、脚本审核要点
+
+| 检查 | 说明 |
+|---|---|
+| `set -e` | 失败即停,避免带病继续 |
+| 路径存在性判断 | 防止在错误目录执行删除 |
+| 变量集中定义 | 无硬编码 IP / 密码 / 路径 |
+| 关键步骤日志 | 出问题能看出卡在哪一步 |
+| 备份在替换之前 | 顺序反了等于没备份 |
+| 危险操作前有确认 | 删文件、改权限、重启 |
+
+## 三、数据操作红线
+
+| 红线 | 说明 |
+|---|---|
+| 不带 WHERE 的 UPDATE / DELETE | 一条命令清库,绝对禁止 |
+| 生产直接改业务数据 | 只能通过应用或经审批脚本 |
+| 未备份先改 | 不可逆 |
+| 单事务大批量更新 | 锁表,业务停摆 |
+| 用 root 跑应用 | 权限过大 |
+
+## 四、上线后
+
+```markdown
+## 上线后验证(30 分钟内完成)
+- [ ] 健康检查返回 UP
+- [ ] 关键接口返回正常(登录、列表、核心业务动作)
+- [ ] 页面无 502 / 504
+- [ ] 日志无 ERROR 级别的异常堆栈
+- [ ] 定时任务正常触发
+- [ ] 数据库连接池水位正常
+- [ ] 无异常告警
+```
+
+## 五、回滚判定
+
+| 情况 | 动作 |
+|---|---|
+| 应用起不来,2 次重启失败 | 立即回滚应用,不排查 |
+| 核心业务不可用 | 立即回滚,事后分析 |
+| 错误率 > 5% 持续 10 分钟 | 立即回滚 |
+| 非核心功能异常 | 评估后决定,可留观 |
+| 性能下降但可用 | 观察,同时准备回滚 |
+
+**回滚不需要请示的三种情况**:服务起不来、核心功能不可用、数据出现错误。
+
+## 六、对外沟通(给客户的故障说明)
+
+内容必须包含:
+
+1. 什么时间、什么功能受影响(客观描述,不含推测)
+2. 影响范围(多少用户/多少单)
+3. 已采取的措施
+4. 当前状态
+5. 后续计划
+
+**必须人工定稿**。AI 写的说明常见问题是:把责任写模糊、堆砌空话、承诺没把握的时间点。客户看得出来。
+
+## 七、留痕
+
+- 部署记录:`docs/05-部署/{项目}-{版本}-部署记录.md`
+- 记录:执行人、审核人、执行时间、每步结果、异常与处理
+- 部署脚本纳入仓库版本管理,不放在个人电脑里

+ 82 - 0
implementation/sapit-ops-example/references/模板-交付计划.md

@@ -0,0 +1,82 @@
+# 交付计划模板
+
+> 来源:`开发部-项目进度计划模板.xlsx`,已转 Markdown,甘特图由 Excel 每日格子改为 mermaid gantt。
+
+## 一、任务分解表
+
+按「阶段 → 任务 → 工作步骤」三级拆,与旧模板一致。
+
+| 序号 | 阶段 | 任务 | 工作步骤 | 计划开始 | 计划结束 | 天数 | 产出物 | 里程碑 | 依赖 | 完成情况 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | 环境准备 | 开发环境部署 | 服务器申请与网络开通 | 11-03 | 11-03 | 1 | | ★开发环境就绪 | | 已完成 |
+| 2 | 环境准备 | 开发环境部署 | JDK/中间件安装 | 11-04 | 11-04 | 1 | | | 1 | |
+| 3 | 环境准备 | 数据初始化 | 组织机构数据导入 | 11-04 | 11-06 | 3 | | | 1 | |
+| 4 | 环境准备 | 数据初始化 | 权限与账号配置 | 11-04 | 11-06 | 3 | | ★可交付演示 | 1 | |
+| 5 | 编码实现 | 用户管理 | 后端接口开发 | 11-07 | 11-12 | 6 | 源码 | | 2 | |
+| 6 | 编码实现 | 用户管理 | 前端页面开发 | 11-09 | 11-14 | 6 | 页面 | | 2 | |
+| 7 | 测试 | 功能测试 | 首轮测试 | 11-15 | 11-19 | 5 | 缺陷清单 | | 5,6 | |
+| 8 | 实施部署 | 生产部署 | 部署脚本与回滚预案 | 11-20 | 11-21 | 2 | 部署脚本 | ★生产就绪 | 7 | |
+| 9 | 实施部署 | 生产部署 | 生产环境部署与验证 | 11-22 | 11-22 | 1 | 部署记录 | ★正式上线 | 8 | |
+
+## 二、甘特图(mermaid)
+
+```mermaid
+gantt
+    title {项目} 交付计划
+    dateFormat YYYY-MM-DD
+    axisFormat %m-%d
+
+    section 环境准备
+    开发环境部署        :done,    env1, 2026-11-03, 2d
+    数据初始化          :active,  env2, 2026-11-04, 3d
+
+    section 编码实现
+    用户管理后端        :         dev1, 2026-11-07, 6d
+    用户管理前端        :         dev2, 2026-11-09, 6d
+
+    section 测试
+    功能测试首轮        :         qa1,  after dev1, 5d
+    回归测试            :         qa2,  after qa1, 3d
+
+    section 实施部署
+    部署脚本准备        :         ops1, after qa2, 2d
+    生产部署            :milestone, ops2, after ops1, 0d
+```
+
+## 三、里程碑清单
+
+里程碑是要向客户汇报的节点,单独列出来:
+
+| 里程碑 | 计划日期 | 判定标准 | 状态 |
+|---|---|---|---|
+| 开发环境就绪 | 11-03 | 应用可启动,数据库可连 | 已完成 |
+| 可交付演示 | 11-06 | 核心流程能跑通 | 进行中 |
+| 测试完成 | 11-19 | 2 级以上缺陷清零 | 未开始 |
+| 生产就绪 | 11-21 | 部署脚本 + 回滚预案评审通过 | 未开始 |
+| 正式上线 | 11-22 | 终检清单全绿 | 未开始 |
+
+## 四、填表规则
+
+1. **「依赖」必填**。没写依赖的任务,排期看起来都能并行,实际做起来全卡住。
+2. **产出物必填**。它是验收依据,也是结算依据。
+3. **里程碑单独标 ★**,且判定标准要可验证——"功能完成"不算标准,"核心流程能跑通"才算。
+4. **先紧后松**。前期排紧,给需求变更、人员变动留缓冲,避免上线前后通宵。
+5. **每日格子不用填**。旧模板用 Excel 横向铺日期格手工涂色,改用 mermaid 后由起止日期自动生成。
+
+## 五、与其它模板的衔接
+
+| 上游 | 下游 |
+|---|---|
+| 功能清单(批次、人天) | 任务分解 |
+| 成本预估(阶段划分) | 甘特图 |
+| 里程碑节点 | 客户汇报、验收 |
+
+## 六、风险与假设
+
+排期必有假设,写出来:
+
+| 假设 | 影响 | 若不成立 |
+|---|---|---|
+| 客户在 11-05 前确认需求 | 后续全部排期 | 每延 1 天,上线顺延 1 天 |
+| 测试环境与生产环境配置一致 | 部署风险 | 需增加 2 天环境适配 |
+| 需求变更不超过 10% | 工期 | 超出部分走变更流程,重新评估 |

+ 137 - 0
implementation/sapit-ops-example/references/模板与提示词.md

@@ -0,0 +1,137 @@
+# 部署方案模板 · 脚本模板 · 排查提示词
+
+## 一、部署方案模板
+
+```markdown
+# {项目} {版本} 部署方案
+
+## 1 变更范围
+| 类型 | 内容 |
+|---|---|
+| 新增文件 | |
+| 修改配置 | |
+| 数据库 DDL | |
+| 数据库 DML | |
+| **不涉及** | |
+
+## 2 前置检查
+| 检查项 | 命令 | 期望结果 |
+|---|---|---|
+| 磁盘空间 | `df -h /opt` | 可用 > 5G |
+| JDK 版本 | `java -version` | 17.x |
+| 端口占用 | `ss -lntp \| grep 8080` | 无输出 |
+| 数据库连通 | `mysql -h x -u x -p -e "select 1"` | 返回 1 |
+
+## 3 部署步骤
+| # | 步骤 | 命令 | 耗时 | 失败处理 |
+|---|---|---|---|---|
+| 1 | 备份当前版本 | `tar -czf $BACKUP_DIR/app-$(date +%F).tar.gz $APP_HOME` | 1min | 停止部署 |
+| 2 | 停止应用 | `systemctl stop demo` | 10s | 查进程是否卡死 |
+| 3 | 替换包 | `\cp -f demo.jar $APP_HOME/` | 5s | — |
+| 4 | 执行 DDL | `mysql < v1.2.0.sql` | 30s | 用备份回滚 |
+| 5 | 启动 | `systemctl start demo` | 30s | 看启动日志 |
+| 6 | 健康检查 | `curl -f localhost:8080/actuator/health` | — | 触发回滚 |
+
+## 4 回滚预案
+| 触发条件 | 回滚动作 | 耗时 | 数据影响 |
+|---|---|---|---|
+| 启动失败超过 2 次 | 恢复上一版本包 + 重启 | 2min | 无 |
+| 健康检查连续 3 次失败 | 同上 | 2min | 无 |
+| DDL 执行失败 | 恢复数据库备份 | 10min | 该时段数据丢失 |
+| 上线后 1 小时内错误率 > 5% | 应用回滚 + 数据订正评估 | 5min | 需评估 |
+
+## 5 验证清单
+| # | 验证项 | 方法 | 通过标准 |
+|---|---|---|---|
+| 1 | 应用健康 | `/actuator/health` | status=UP |
+| 2 | 关键接口 | curl 登录接口 | 返回 code=0 |
+| 3 | 页面可访问 | 浏览器打开首页 | 无 502/504 |
+| 4 | 定时任务 | 查看日志 | 无异常 |
+| 5 | 日志无报错 | `tail -200` | 无 ERROR |
+```
+
+## 二、脚本模板
+
+```bash
+#!/usr/bin/env bash
+# 用途:{项目} {版本} 应用部署
+# 作者:{姓名}  日期:2026-11-12
+# 回滚:./rollback.sh {上一版本号}
+set -euo pipefail
+
+APP_NAME=demo
+APP_HOME=/opt/app/${APP_NAME}
+BACKUP_DIR=/data/backup/${APP_NAME}
+VERSION=v1.2.0
+PORT=8080
+
+log(){ echo "[$(date '+%F %T')] $*"; }
+die(){ log "ERROR: $*"; exit 1; }
+
+[ -d "$APP_HOME" ] || die "目录不存在:$APP_HOME"
+mkdir -p "$BACKUP_DIR"
+
+log "1/5 备份当前版本"
+tar -czf "${BACKUP_DIR}/${APP_NAME}-$(date +%F_%H%M).tar.gz" -C "$APP_HOME" . || die "备份失败,中止"
+
+log "2/5 停止应用"
+systemctl stop "$APP_NAME" || true
+
+log "3/5 部署新版本"
+install -m 644 "${APP_NAME}-${VERSION}.jar" "${APP_HOME}/${APP_NAME}.jar" || die "替换失败"
+
+log "4/5 启动应用"
+systemctl start "$APP_NAME"
+
+log "5/5 健康检查"
+for i in $(seq 1 10); do
+  if curl -fs "http://127.0.0.1:${PORT}/actuator/health" >/dev/null; then
+    log "部署成功:${VERSION}"; exit 0
+  fi
+  sleep 3
+done
+
+log "健康检查失败,请执行 ./rollback.sh <上一版本>"
+exit 1
+```
+
+## 三、排查提示词
+
+```
+环境问题排查。已知信息:
+- 操作系统:CentOS 7.9
+- 现象:浏览器访问 https://xxx 报 502
+- 拓扑:Nginx → 本机 8080(Spring Boot)
+- 最近变更:昨天升级了 JDK
+
+请按网络层 → 服务层 → 依赖层 → 应用层给我排查路径。
+每层给出:判断命令、正常表现、异常表现、下一步动作。
+不要直接让我重启服务。
+```
+
+## 四、数据变更提示词
+
+```
+我需要把 leave_apply 表中 approve_status=0 且 create_time 早于 2026-01-01 的记录标记为作废。
+
+约束:
+1. 先给我 SELECT 语句,包含 count 和抽样 20 条
+2. 给我备份语句(建备份表)
+3. 更新语句必须分批,每批 1000 行,每批之间有 sleep
+4. 给我验证语句,确认更新前后行数一致
+5. 不要直接给我一条 UPDATE
+
+表结构:<粘贴>
+数据量级:约 30 万行,符合条件的约 2 万行
+```
+
+## 五、常见环境问题速查
+
+| 现象 | 优先排查 | 常见原因 |
+|---|---|---|
+| 502 Bad Gateway | 后端进程在不在、端口听没听 | 应用没起来 / 端口占错 |
+| 504 超时 | 后端处理耗时、Nginx 超时配置 | 慢 SQL / 超时设置过短 |
+| 连接被拒 | 防火墙、SELinux、监听地址 | 只监听了 127.0.0.1 |
+| 证书报错 | 证书有效期、证书链、域名匹配 | 中间证书缺失 |
+| 中文乱码 | 数据库字符集、连接串参数 | 用了 latin1 |
+| 依赖缺失 | 内网源、离线包 | 无外网时 yum 装不上 |

+ 0 - 1
requirements/readme.txt

@@ -1 +0,0 @@
-readme

+ 195 - 0
requirements/sapit-req-example/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: sapit-req-example
+description: 按公司规范编写或检查需求说明书。当用户需要写需求文档、梳理功能点、把客户访谈转成需求条目、检查需求书是否合规时使用。会自动执行料件体检、分批生成、来源标注、待确认问题汇总与自查。
+---
+
+# 需求说明书助手
+
+按《10.开发部-作业规范-需求分析师 V2.0》工作。核心原则:**只写能追溯到客户的内容,够不到的标「模型推断」,绝不补全客户没提的东西。**
+
+## 何时使用
+
+- 用户说"写需求""整理需求文档""把访谈转成需求"
+- 用户给了一段客户沟通记录、招标文件、会议纪要,要做成需求
+- 用户说"检查这份需求书""这条需求写得对不对"
+
+## 第一步:料件体检(不合格就停)
+
+在写任何内容之前,先确认手上有没有这些料。**缺料不允许硬写**,直接告诉用户缺什么。
+
+| 料 | 必需性 | 缺了怎么办 |
+|---|---|---|
+| 客户原始材料(原话、录音转写、往来邮件、招标文件) | 必需 | **停止**,请用户提供。只有整理稿也不行,整理稿里已经掺了别人的理解 |
+| 行业术语表 | 必需 | **停止**,请用户给客户内部叫法 |
+| 明确不做清单 | 必需 | **停止**,否则会把范围往大里写 |
+| 现有系统截图/说明 | 迭代项目必需 | 缺了标注「未取得,待确认」 |
+| 上一版需求文档 | 迭代项目必需 | 同上 |
+
+输出一句体检结论,例如:
+
+> 已收到访谈转写 1 份、术语表、不做清单。缺少现有系统截图,涉及「历史数据迁移」的部分暂按「待确认」处理。可以开始,预计产出 6 个功能条目。
+
+## 第二步:先出功能清单,不写详述
+
+只输出清单表,等用户确认后再展开。**这一步不能跳过**,否则后面全白写。
+
+```markdown
+| 编号 | 功能名 | 优先级 | 来源类型 | 依据 |
+|---|---|---|---|---|
+| F-001 | 请假申请 | P0 | 客户原话 | 2026-11-05 王主任:"年假要能一次请完" |
+| F-002 | 请假审批 | P0 | 客户原话 | 同上 |
+| F-003 | 考勤台账 | P1 | 模型推断 | 由审批通过后写台账推断,客户未明确 |
+```
+
+**来源类型只有三种**:`客户原话` / `现有系统` / `模型推断`。
+
+清单末尾给出统计:
+
+> 共 8 条,其中客户原话 5 条、现有系统 1 条、模型推断 2 条,推断占比 25%。
+> 若占比超过 30%,建议补充调研,不要靠调整措辞绕过。
+
+### 同步产出两份附属清单
+
+**这两份清单和需求文档同等重要**,它们是把"我不确定"变成"要去问"的载体。
+
+**(1)术语表 `glossary.md`**
+
+每写一个客户内部叫法就登记一条,防止全文用词被模型慢慢替换成通用词:
+
+| 客户叫法 | 含义 | 我方曾误用为 |
+|---|---|---|
+| 年假 | 带薪年休假,按自然年计算 | 休假 / 假期 |
+| 调休 | 加班倒休,有有效期 | 补休 |
+| 主管 | 直属上级,不含部门经理 | 上级 / 领导 |
+
+**(2)待确认问题清单 `open-questions.md`**
+
+所有标了「待确认」的地方,一律汇总到这里,按重要度排序,逐条对应客户:
+
+| # | 问题 | 来源(哪条需求卡住) | 找谁确认 | 状态 |
+|---|---|---|---|---|
+| Q1 | 病假超过 2 天的证明是否需要 HR 复核 | F-003 规则 5 | 客户 HR 王主任 | 待问 |
+| Q2 | 审批人离职时转派的层级上限 | F-003 异常处理 | 客户 HR 王主任 | 待问 |
+
+**结项标准:这份清单必须是空的。** 只要有未关闭的问题,文档就不能进评审。
+
+## 第三步:一个功能一轮
+
+用户确认清单后,逐个生成详述。**每次只输出一个功能**,不要一次吐出全篇。
+
+每轮开头先声明本轮依据了哪些材料,例如:
+
+> 本轮依据:访谈转写第 12~18 段、术语表、请假页面截图说明。未使用材料:招标文件第三章(与本功能无关)。
+
+### 先判断功能类型,再决定写什么
+
+| 类型 | 特征 | 主体内容 |
+|---|---|---|
+| **A 数据管理类** | 页面上有一排按钮(用户管理、组织机构、字典、档案) | **按钮清单是主体**,逐按钮写前置校验、处理逻辑、跨业务影响 |
+| **B 业务流程类** | 有一条按顺序推进的链路(审批、工单、报销) | **处理规则是主体**,同时列出链路各环节的操作按钮 |
+
+两类都要完整格式,见 `references/模板-需求说明书.md`。
+
+### 按钮清单是硬要求
+
+**任何功能,只要页面上有按钮,就必须列全。** 漏一个按钮,开发就少做一个,最后验收才发现。
+
+每个按钮必须写清六个字段:
+
+| 字段 | 回答的问题 |
+|---|---|
+| 按钮名 | 按钮上写的是什么字 |
+| 位置 | 页面顶部 / 行内 / 表单底部 / 更多菜单里 |
+| 显示条件 | **按钮看不看得见**(权限、状态) |
+| 前置校验 | **点了之后能不能成功**(业务规则) |
+| 处理逻辑 | **成功后系统做了什么**(改哪个字段、写什么日志) |
+| 对其他业务的影响 | **还有哪个页面会因此变化** |
+
+后三项最容易混。**显示条件写错,按钮会该显示时不显示;前置校验写错,按钮点了没反应;影响写漏,上线后发现别的模块坏了。**
+
+示例(用户管理的「禁用」按钮):
+
+> **显示条件**:有「用户禁用」权限 且 用户状态=启用
+> **前置校验**:用户状态是启用的 / 不能禁用自己 / 不能禁用最后一名超级管理员
+> **处理逻辑**:状态改为禁用,写操作日志,若为组织负责人则置空并通知管理员
+> **对其他业务的影响**:组织机构选负责人时过滤掉禁用用户;该用户待办转交上级;已登录会话失效
+
+**「对其他业务的影响」怎么推**:问自己"这个按钮点下去,还有哪个页面会变"。答不上来就是没写全。按四个方向排查:数据被谁引用、状态变化影响哪些列表、下游系统、历史数据要不要动。
+
+**防漏检查**:对着原型一个个数,不凭记忆;套标准组合(列表页至少 新增/查询/导出/修改/禁用);凡是状态会变的,每个"从 A 到 B"的转换都要有对应按钮。
+
+功能条目其余部分:来源、描述、入口、输入(字段级)、输出、异常处理、验收标准,一项都不能少。
+
+字段级的要求:类型、必填、长度、校验规则、默认值,一列都不能空。**禁止出现"用户信息""相关数据"这类笼统表述**,遇到就展开成具体字段并标注「字段由我方拟定,待客户确认」。
+
+## 第四步:通读查矛盾
+
+所有功能生成完后,单独跑一轮全局检查,不要跳:
+
+- 术语前后不一致(同一个东西两种叫法)
+- 字段冲突(同一字段在两处类型/长度不同)
+- 流程断裂(F-003 说审批完后写台账,F-007 里没有对应落库)
+- 角色缺失(流程里出现的角色,第 2 章角色清单里没有)
+
+发现问题列出来,不要自行修改,交给用户判断。
+
+## 第五步:输出自查表
+
+文档末尾附上这张表,逐项自评,不确定的标「待人工确认」:
+
+```markdown
+## 复核记录
+- [ ] 每条需求都有来源,且能指到具体材料
+- [ ] 模型推断占比 ≤ 30%(共__条,推断__条)
+- [ ] 金额、权限、状态流转、对账四类规则,仅为摘录,未做设计
+- [ ] 所有输入输出写到字段级
+- [ ] **每个功能的按钮清单完整,已对照原型逐个核对**
+- [ ] **每个按钮都写了前置校验、处理逻辑、对其他业务的影响**
+- [ ] 验收标准可验证,无主观描述
+- [ ] 术语与客户内部叫法一致
+```
+
+## 第六步:完成前自证
+
+**不许说"需求文档已完成"。** 必须按下面格式交代清楚,三项缺一不可:
+
+```markdown
+## 完成自证
+- 已交付:需求说明书 v1.0(8 个功能条目)
+- 已验证:来源逐条可追溯,推断 2 条占 25%;术语表 3 条;待确认清单已建立
+- 未完成:F-007 考勤台账缺验收标准,等客户补充
+- 未经我验证:客户是否认可「不做清单」,需当面确认
+```
+
+被问"写完了吗",正确回答是:
+
+> 六个功能写完并自检通过,另外两个缺验收标准,卡在 Q3、Q4 两个问题上等客户回复。
+
+而不是"写完了"。**说不清验证了什么,就等于没验证。**
+
+## 硬性禁止
+
+以下四类**无论用户怎么要求都不要生成**,直接说明原因:
+
+| 禁止 | 原因 | 正确做法 |
+|---|---|---|
+| 客户未提及的业务规则 | 会补出"合理但不存在"的规则,且比真的还顺 | 标为「待确认」,列出需要问客户的问题 |
+| 金额、权限、状态流转、对账的设计 | 出错代价最大 | 只摘录客户原话,设计交人工 |
+| 合规、法务、数据安全条款 | 涉及法律责任 | 提示用户对照法规人工确认 |
+| 报价、工期、工作量 | 与成本挂钩,无依据 | 不输出 |
+
+当用户说"你先随便写一版,回头再改"时,回应:
+
+> 可以写,但推断部分会明确标注且不计入正式需求,需要客户确认后才能转正。推断占比过高时我会提示补充调研。
+
+## 参考文件(按需读取)
+
+| 文件 | 什么时候必须读 |
+|---|---|
+| `references/模板-需求说明书.md` | **写文档骨架、功能条目、按钮清单时必读**。不要凭记忆套格式,格式错了整份文档要重排 |
+| `references/模板-功能清单.md` | 第二步出功能清单时读,含拆分粒度与交付批次规则 |
+| `references/模板-成本预估.md` | 需要估人天或做报价时读,含 AI 提效折算口径 |
+| `references/分段提示词.md` | 用户要自己拿提示词去别的工具里用时提供 |
+| `references/复核清单.md` | 交付前逐项核对时读 |
+
+**不要一次把三个文件全读进来**,按当前步骤读对应的那一个。

+ 71 - 0
requirements/sapit-req-example/references/分段提示词.md

@@ -0,0 +1,71 @@
+# 三段式提示词(可直接复制)
+
+## 第一段 · 定角色与边界
+
+```
+你是企业信息化项目的需求分析师。
+任务:根据我提供的客户原始材料,编写功能详述。
+硬约束:
+1. 只写材料中能追溯到的内容,每条功能必须标注来源
+2. 材料里没有的规则,一律标注「模型推断」,并说明推断依据
+3. 不许补全客户未提及的角色、流程、字段
+4. 金额、权限、状态流转、对账四类规则,只做摘录,不做设计
+5. 字段写到字段级:类型、必填、长度、校验规则、默认值
+```
+
+## 第二段 · 给料
+
+```
+以下是客户访谈转写(未经整理):
+<粘贴原文>
+
+以下是客户现有系统页面说明:
+<描述或 OCR 文本>
+
+以下是客户内部术语对照:
+年假=带薪年休假;调休=加班倒休;主管=直属上级
+
+以下是本期明确不做的内容:
+<不做清单>
+```
+
+> 关键:给**原话**,不要给"整理后的纪要"。纪要里已经掺了整理人的理解,AI 会把那个理解当成客户原意,错在第一层就埋下了。
+
+## 第三段 · 定格式
+
+```
+严格按以下结构输出,不要增删章节:
+### F-{编号} {功能名}
+**来源**:
+**来源类型**:客户原话 / 现有系统 / 模型推断
+**功能描述**:
+**入口**:
+**输入**(表格:字段|类型|必填|长度|校验规则|默认值)
+**处理规则**(编号列表,含边界条件)
+**输出**:
+**异常处理**(表格)
+**验收标准**:
+```
+
+---
+
+## 生成节奏
+
+一次让 AI 写完整份需求书,质量必然崩——写到第五个功能时它已经开始自己编了。
+
+正确节奏:
+
+1. **先出功能清单**(只出清单),人工核对漏项与多余项
+2. **一个功能一轮**,上下文只带该功能相关的原始材料
+3. **每轮结束人工确认**,确认后的内容作为下一轮的「已确认上下文」
+4. **最后单独一轮**通读全文查矛盾(术语、字段、流程、角色)
+
+第 4 步最容易省,但抓出的问题最多。
+
+## 追问技巧
+
+| 想要 | 别问 | 改问 |
+|---|---|---|
+| 判断是否编造 | "这条是真的吗" | "这条出自哪一段原话?指给我看" |
+| 逼出边界 | "还有别的规则吗" | "客户说到哪句为止?后面是你补的吗" |
+| 找出冲突 | "有没有矛盾" | "F-003 说写考勤台账,哪条功能负责这张表的维护" |

+ 73 - 0
requirements/sapit-req-example/references/复核清单.md

@@ -0,0 +1,73 @@
+# 需求复核清单
+
+## 一、必做项(逐条打勾)
+
+```markdown
+## 复核记录
+- [ ] 每条需求都有来源,且能指到具体材料(不是"客户说过"这种)
+- [ ] 模型推断占比 ≤ 30%(统计:共__条,推断__条)
+- [ ] 金额、权限、状态流转、对账四类规则,逐条与客户书面确认
+- [ ] 所有输入输出写到字段级,无"用户信息"式表述
+- [ ] 每个功能的按钮清单完整,已对照原型逐个核对(不凭记忆)
+- [ ] 每个按钮都写了:显示条件、前置校验、处理逻辑、对其他业务的影响
+- [ ] 涉及状态变化的,每个"A→B"转换都有对应按钮
+- [ ] 每个功能能向开发、测试完整反讲,对方能复述
+- [ ] 验收标准全部可验证,无主观描述
+- [ ] 术语与客户内部叫法一致
+- [ ] 已确认"不做清单"并与客户对齐
+- [ ] 全文通读无前后矛盾(术语、字段、流程、角色)
+```
+
+## 一之二、按钮清单专项检查
+
+| 检查 | 方法 |
+|---|---|
+| 有没有漏按钮 | 打开原型页,从左到右、从上到下数,见一个记一个 |
+| 标准组合齐不齐 | 列表页:新增/查询/导出/修改/禁用;表单页:提交/保存草稿/取消 |
+| 状态机覆盖 | 每个状态转换是否有入口(含审批通过/驳回) |
+| 三个字段有没有混 | 显示条件(看不看得见)≠ 前置校验(能不能成功)≠ 处理逻辑(做了什么) |
+| 跨业务影响写了没 | 逐个按钮问"点下去还有哪个页面会变" |
+| 幂等性 | 重复点击会不会重复执行、重复写日志 |
+| 易漏项 | 导出、批量操作、状态互逆(禁用/启用)、二次确认入口 |
+
+## 二、推断占比怎么算
+
+```
+推断占比 = 来源类型为「模型推断」的功能条数 ÷ 功能总条数
+```
+
+| 占比 | 判断 | 动作 |
+|---|---|---|
+| ≤ 30% | 正常 | 继续,推断项逐条标注待确认 |
+| 30%~50% | 料不够 | 建议补充调研,不要靠改措辞绕过 |
+| > 50% | 严重不足 | 停止生成,回去补料重做 |
+
+## 三、四类高危规则(必须人工确认)
+
+| 类别 | 为什么危险 | 确认方式 |
+|---|---|---|
+| 金额计算 | 算错直接是钱的问题 | 客户书面确认计算口径与舍入规则 |
+| 权限控制 | 越权是安全事故 | 出权限矩阵,客户逐格确认 |
+| 状态流转 | 卡错状态流程走不下去 | 画状态机,客户确认每个转换条件 |
+| 对账/核销 | 对不上就是财务问题 | 客户提供对账样例数据 |
+
+## 四、常见返工原因
+
+| 现象 | 根因 | 处理 |
+|---|---|---|
+| 出现客户从没提过的角色或流程 | 模型幻觉 | 删除该角色相关内容,重新给料 |
+| 术语被替换成通用词 | 术语表没给或没生效 | 补术语表,重做本章 |
+| 功能之间流程断裂 | 分批时上下文不一致 | 重跑「通读查矛盾」 |
+| **验收时发现少做了按钮** | **按钮清单漏项** | **回补清单,并追问当时是否对照原型数过** |
+| **上线后别的模块坏了** | **「对其他业务的影响」漏写** | **回补影响分析,同步检查同类按钮** |
+| **按钮点了没反应** | **把前置校验写成了显示条件** | **区分两个字段,重新确认** |
+| 字段写不出校验规则 | 客户没说过校验 | 标「待确认」,列入客户问题清单 |
+| 验收标准写成形容词 | 生成时没约束 | 回退重写,只允许可观测行为 |
+
+## 五、留痕
+
+- 文档头写明:AI 参与度、模型、生成日期、复核人
+- AI 原始输出存 `docs/01-需求/_ai-raw/`,不删
+- 人工修改超过 30% 的,在变更记录注明"AI 初稿质量问题"
+
+目的不是追责,是三个月后能回答"这份文档里的坑是怎么来的"。

+ 58 - 0
requirements/sapit-req-example/references/模板-功能清单.md

@@ -0,0 +1,58 @@
+# 功能清单模板
+
+> 来源:`00.开发部-模板文档-功能清单.xlsx`,已转 Markdown 并补充字段。
+> 用途:需求阶段产出,同时作为成本预估与交付计划的输入。
+
+## 一、表格格式
+
+| 编号 | 一级模块 | 二级模块 | 拆分粒度 | 来源类型 | 优先级 | 交付批次 | 预估人天 | 备注 |
+|---|---|---|---|---|---|---|---|---|
+| F-001 | 用户管理 | 用户列表 | 末级菜单 | 客户原话 | P0 | 一批 | 2 | |
+| F-002 | 用户管理 | 用户新增 | 末级菜单 | 客户原话 | P0 | 一批 | 1.5 | |
+| F-003 | 用户管理 | 用户禁用/启用 | 末级菜单 | 模型推断 | P1 | 二批 | 1 | 需客户确认 |
+| F-004 | 订单管理 | 订单状态 | 单表 | 现有系统 | P0 | 一批 | 3 | 复杂功能按单表拆 |
+| F-005 | 订单管理 | 订单支付 | 单表 | 客户原话 | P0 | 一批 | 4 | |
+| F-006 | 订单管理 | 订单日志 | 单表 | 模型推断 | P2 | 二批 | 1 | |
+
+## 二、字段说明
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| 编号 | 是 | F-三位序号,与需求说明书里的功能编号一致 |
+| 一级模块 | 是 | 系统主菜单级 |
+| 二级模块 | 是 | 末级菜单或单元 |
+| 拆分粒度 | 是 | 见下方拆分规则 |
+| 来源类型 | 是 | 客户原话 / 现有系统 / 模型推断(推断项必须客户确认后才能进一批) |
+| 优先级 | 是 | P0 必须有 / P1 应该有 / P2 可以有 |
+| 交付批次 | 是 | 一批 / 二批 / 三批,对应合同分期 |
+| 预估人天 | 是 | 开发人天,用于填成本预估表 |
+| 备注 | 否 | 依赖、风险、待确认事项 |
+
+## 三、拆分规则
+
+| 情况 | 拆法 | 例子 |
+|---|---|---|
+| 普通功能 | 一个末级菜单一条 | 用户管理、组织机构管理 |
+| 复杂功能 | 一个单元(一张主表)一条 | 订单管理拆成:订单状态、订单支付、订单日志 |
+| 报表类 | 一张报表一条 | 月度汇总表、明细导出表 |
+| 接口类 | 一个外部系统一条 | 对接 HR 系统、对接短信平台 |
+
+**不要拆到按钮级**。按钮在需求说明书的功能条目里逐个列,功能清单只到菜单或单元这一层,否则清单会长到没法用。
+
+## 四、与其它模板的衔接
+
+```mermaid
+flowchart LR
+  A[功能清单] --> B[成本预估]
+  A --> C[交付计划]
+  B --> D[报价]
+  C --> E[里程碑]
+```
+
+- 功能清单的「预估人天」汇总后进成本预估表
+- 「交付批次」决定里程碑怎么排
+- 编号 F-xxx 与需求说明书的章节一一对应,便于回溯
+
+## 五、旧模板保留的做法
+
+旧版用「第一阶段完成 / 第二阶段完成」打勾标记分批,这个做法保留,改成「交付批次」列,更紧凑也便于筛选。

+ 74 - 0
requirements/sapit-req-example/references/模板-成本预估.md

@@ -0,0 +1,74 @@
+# 成本预估模板
+
+> 来源:`01.开发部-模板文档-成本预估.xlsx`,已转 Markdown。
+> 用途:需求阶段估算成本与报价基线,是「可研」阶段的正式交付物。
+
+## 一、角色单价表
+
+| 角色 | 人天单价(元) | 说明 |
+|---|---|---|
+| 项目经理 | 按公司标准 | 管理与协调 |
+| 专家顾问 | 按公司标准 | 方案与业务把关 |
+| 高级顾问 | 按公司标准 | 需求与业务分析 |
+| 高级软件工程师 | 按公司标准 | 架构与核心代码 |
+| 软件工程师 | 1200 | 主力开发 |
+| 初级软件工程师 | 按公司标准 | 边缘功能 |
+
+> 单价由公司统一维护,表单里只填人天,金额自动算。**AI 参与后单价不变,人天要打折,见第五节。**
+
+## 二、任务分解表
+
+按「阶段 → 活动 → 任务」三级拆,每一级留小计。
+
+| 阶段 | 活动 | 任务 | 项目经理 | 高工 | 中工 | 初工 | 测试 | 总人天 | 金额 | 是否付费 | 交付物 |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| 项目规划 | 需求调研 | 客户需求调研,明确范围 | 1 | 0.5 | 2 | 0 | 0 | 3.5 | 4200 | 是 | 调研纪要 |
+| 项目规划 | **小计** | | 1 | 0.5 | 2 | 0 | 0 | 3.5 | 4200 | | |
+| 分析设计 | 需求分析 | 需求说明书编写 | 0.5 | 1 | 2 | 0 | 0 | 3.5 | 4200 | 是 | 需求说明书 |
+| 分析设计 | 数据库设计 | ER 图与建表脚本 | 0 | 2 | 0 | 0 | 0 | 2 | 2400 | 是 | ER 图 + DDL |
+| 分析设计 | 交互设计 | UI 设计 | 0 | 0 | 1 | 0 | 0 | 1 | 1200 | 是 | UI 稿 |
+| 分析设计 | **小计** | | 0.5 | 3 | 3 | 0 | 0 | 6.5 | 7800 | | |
+| 编码实现 | 模块一 | 用户管理 | 0 | 1 | 4 | 2 | 0 | 7 | 8400 | 是 | 源码 |
+| 编码实现 | 模块二 | 订单管理 | 0 | 2 | 6 | 1 | 0 | 9 | 10800 | 是 | 源码 |
+| 编码实现 | 环境准备 | 开发环境搭建 | 0 | 0.5 | 0 | 0 | 0 | 0.5 | 600 | **否** | 环境 |
+| 编码实现 | **小计** | | 0 | 3.5 | 10 | 3 | 0 | 16.5 | 19800 | | |
+| 测试 | 用例设计 | 编写测试用例 | 0 | 0 | 0 | 0 | 3 | 3 | 3600 | 是 | 测试用例 |
+| 测试 | 执行测试 | 两轮功能测试 + 回归 | 0 | 0 | 0 | 0 | 5 | 5 | 6000 | 是 | 测试报告 |
+| 测试 | **小计** | | 0 | 0 | 0 | 0 | 8 | 8 | 9600 | | |
+| 实施部署 | 上线 | 生产部署与验证 | 1 | 1 | 1 | 0 | 1 | 4 | 4800 | 是 | 部署记录 |
+| **总计** | | | 2.5 | 8 | 26 | 3 | 9 | **48.5** | **58200** | | |
+
+## 三、填表规则
+
+1. **人天按角色分列**,不要只写一个总数——报价时要按角色报价,只写总数后期没法拆
+2. **「是否付费」必须标**:环境准备、内部培训、返工这类不向客户收费的,标「否」,避免报价虚高被砍
+3. **每个阶段留小计**,便于按阶段报价与分期收款
+4. **交付物列必填**,它同时是验收依据
+5. 需求变更导致的增量,另起一张表,不混进原表
+
+## 四、与其它模板的衔接
+
+| 上游 | 下游 |
+|---|---|
+| 功能清单(预估人天) | 报价单 |
+| 需求说明书(复杂度) | 交付计划(周期) |
+| 项目分级 | 人力配比 |
+
+## 五、AI 参与后怎么折算人天
+
+**这一节是 V2.0 新增,旧模板没有。**
+
+AI 提效不等于人天等比例下降。按三类任务分别折算,不要一刀切:
+
+| 任务类型 | 建议折算 | 依据 |
+|---|---|---|
+| 文档类(需求、设计说明、测试用例) | 6~7 折 | AI 起草快,但复核与客户确认的时间省不掉 |
+| 编码类(常规业务功能) | 6~8 折 | 生成快,调通与联调仍要人 |
+| 编码类(核心逻辑:金额/权限/状态机/对账) | **不打折** | 规范禁止 AI 代写,人天按原样估 |
+| 测试执行 | 5~7 折 | 回归可自动化,首轮验证仍要人 |
+| 实施部署 | 8~9 折 | 脚本生成快,但客户现场环境千差万别 |
+| 需求调研、客户沟通 | **不打折** | AI 替代不了当面沟通 |
+
+**报价时必须写明按哪一档折算**。口头说"用了 AI 所以便宜"但没有折算依据,客户不会认,内部也无法复盘。
+
+建议做法:同一份需求出三档报价(AI 辅助 / 纯人工 / 混合),让商务有选择空间,也让客户知道便宜在哪。

+ 270 - 0
requirements/sapit-req-example/references/模板-需求说明书.md

@@ -0,0 +1,270 @@
+# 需求说明书 · 文档骨架与功能条目格式
+
+## 一、文件要求
+
+- 文件名:`需求说明书-{项目简称}-v{版本}.md`
+- 存放:`docs/01-需求/`
+- 图:一律 mermaid,不贴截图(截图不可 diff、不可检索)
+- 所有输入输出写到字段级
+
+## 二、文档骨架
+
+```markdown
+# {项目名称} 需求说明书
+
+## 0 文档信息
+| 项 | 内容 |
+|---|---|
+| 版本 | v1.0 |
+| 编写 | |
+| AI 参与度 | L2 |
+| 使用模型 | |
+| 复核 | |
+| 对应立项单 | |
+
+### 版本变更历史
+| 版本 | 章节 | 类型 | 变更说明 | 日期 | 变更人 |
+|---|---|---|---|---|---|
+| v1.0 | 全部 | C | 创建 | | |
+
+> 类型:C 创建 / U 修改 / D 删除 / A 增加
+
+## 1 项目背景与目标
+### 1.1 业务背景(客户为什么现在要做这件事)
+### 1.2 建设目标(必须可度量,不写"提升效率")
+### 1.3 范围边界
+- 本期做:
+- **本期明确不做**:(这条最重要,防止后续扯皮)
+### 1.4 对其它系统的影响
+| 系统 | 影响方式 | 处理 |
+|---|---|---|
+| 老系统 XXX | 本系统上线后替代 | 数据迁移,旧系统停用 |
+| HR 系统 | 需要接口对接 | 见接口需求章节 |
+| 单点登录 | 需要接入 | 由客户 IT 提供配置 |
+
+### 1.5 名词定义
+客户内部叫法与我方理解的对照,详见 `glossary.md`。本节只列最容易混淆的三到五个。
+
+## 2 用户与角色
+### 2.1 角色清单
+| 角色 | 职责 | 数据可见范围 | 关键操作权限 |
+### 2.2 权限矩阵
+| 操作 \ 角色 | A | B | C |
+
+## 3 业务流程
+### 3.1 主流程(mermaid flowchart + 文字说明)
+### 3.2 分支与异常流
+
+## 4 功能需求
+### 4.1 功能清单
+| 编号 | 功能名 | 优先级 | 来源类型 | 确认人 |
+### 4.2 功能详述(每功能一节,含按钮清单)
+
+## 5 数据需求
+### 5.1 核心实体与关系(mermaid erDiagram)
+### 5.2 数据量与增长预估
+### 5.3 保留与归档
+
+## 6 非功能需求
+性能 / 并发 / 可用性 / 兼容性 / 安全 / 审计
+
+## 7 接口需求
+| 系统 | 方向 | 频率 | 数据格式 | 失败处理 |
+
+## 8 验收标准
+按功能列可验证条件
+
+## 9 需求变更记录
+| 日期 | 变更内容 | 原因 | 影响范围 | 确认人 |
+
+## 附录 A 需求来源追溯表
+| 需求编号 | 来源类型 | 具体依据 | 确认人 | 确认日期 |
+
+## 附录 B 按钮总表
+| 功能 | 按钮 | 前置校验摘要 | 跨业务影响 |
+```
+
+## 三、功能条目分两种类型
+
+不是所有功能都长一个样。先判断它属于哪类,再按对应格式写。
+
+**每个功能条目必含**:来源、来源类型、入口、页面原型、输入(字段级)、按钮清单、输出、异常处理、验收标准。
+
+**按情况必填**:
+
+| 项 | 什么时候必须写 |
+|---|---|
+| 历史数据 | 迭代项目必填,说明老系统已有数据怎么处理(迁移 / 不迁 / 清洗规则) |
+| 处理规则 | 有审批流、状态流转的功能必填 |
+| 接口依赖 | 需要调外部系统时必填,并关联接口设计说明书编号 |
+
+### 3.1 类型 A:数据管理类(以按钮为主体)
+
+典型:用户管理、组织机构、字典维护、商品档案。特征是页面上有一排按钮,每个按钮对应一个动作。
+
+**格式:先给按钮清单总表,再逐个按钮详述。**
+
+```markdown
+### F-001 用户管理
+
+**来源**:客户原话(2026-11-05 访谈,王主任:"用户要能停用,走了的人别删")
+**来源类型**:客户原话
+**入口**:系统设置 → 用户管理
+**页面原型**:`prototype/pages/user-list.vue`
+
+#### 按钮清单
+
+| 按钮 | 位置 | 显示条件 | 前置校验 | 处理逻辑 | 对其他业务的影响 |
+|---|---|---|---|---|---|
+| 新增 | 页面顶部 | 有「用户新增」权限 | 必填项完整;账号不重复 | 插入用户记录,初始状态=启用 | 所属组织人数 +1 |
+| 查询 | 页面顶部 | 无 | 无 | 按条件分页查询,默认创建时间倒序 | 无 |
+| 修改 | 行内 | 有权限 且 状态=启用 | 账号不可改;手机号格式 | 更新用户信息,写变更日志 | 若改了所属部门,原部门与新部门人数都要重算 |
+| 禁用 | 行内 | 有权限 且 状态=启用 | 用户状态是启用的 | 把用户状态改成禁用 | 组织机构选择负责人时要把禁用的用户过滤掉 |
+| 启用 | 行内 | 有权限 且 状态=禁用 | 用户状态是禁用的 | 把用户状态改成启用 | 恢复出现在负责人候选列表中 |
+| 重置密码 | 行内 | 有权限 且 状态=启用 | 无 | 密码重置为初始密码,标记首次登录须改密 | 无 |
+| 导出 | 页面顶部 | 有「用户导出」权限 | 查询结果不为空 | 导出当前查询结果为 xlsx | 无 |
+
+#### 按钮详述(仅复杂按钮需要展开)
+
+##### B-004 禁用
+
+**显示条件**:有「用户禁用」权限 且 用户状态=启用
+**前置校验**
+| # | 校验 | 不通过提示 |
+|---|---|---|
+| 1 | 用户状态必须是启用 | 该用户已是禁用状态 |
+| 2 | 不能禁用自己 | 不能禁用自己的账号 |
+| 3 | 不能禁用最后一名启用的超级管理员 | 系统须保留至少一名启用的超级管理员 |
+
+**处理逻辑**
+1. `user.status` 置为 0(禁用)
+2. 写操作日志:操作人、时间、被禁用用户、原状态
+3. 若该用户是某组织负责人,该组织负责人置空,并通知系统管理员
+
+**对其他业务的影响**
+- 组织机构选择负责人:候选人列表过滤掉禁用用户
+- 待办任务:该用户名下未办结的待办转交其上级
+- 登录:禁用用户无法登录;已登录会话立即失效
+- 报表:历史数据中该用户的操作记录保留,不做处理
+
+**幂等性**:重复点击禁用,第二次提示"该用户已是禁用状态",不产生重复日志
+
+**验收标准**:上述 3 条前置校验逐条可验;禁用后该用户无法登录;组织负责人候选列表不再出现该用户
+```
+
+### 3.2 类型 B:业务流程类(以规则为主体)
+
+典型:请假审批、报销、工单流转。特征是有一条按顺序推进的链路。
+
+```markdown
+### F-003 请假申请
+
+**来源**:客户原话(2026-11-05 访谈,王主任:"年假要能一次请完,别再分两次")
+**来源类型**:客户原话
+
+**功能描述**:员工提交请假单,按请假天数走不同审批链。
+
+**入口**:移动端首页「请假」图标;PC 端 我的-考勤-请假
+
+**输入**
+| 字段 | 类型 | 必填 | 长度 | 校验规则 | 默认值 |
+|---|---|---|---|---|---|
+| 请假类型 | 枚举 | 是 | — | 年假/事假/病假/调休 | — |
+| 开始时间 | datetime | 是 | — | 不早于当日 00:00 | 当前时间 |
+| 结束时间 | datetime | 是 | — | 晚于开始时间 | 开始时间+1天 |
+| 请假天数 | 小数 | 是 | 5,1 | 自动计算,0.5 步进 | 自动 |
+| 事由 | 文本 | 是 | 200 | 不少于 5 字 | — |
+| 附件 | 文件 | 否 | 10MB | 病假必传 | — |
+
+**按钮清单**
+| 按钮 | 位置 | 显示条件 | 前置校验 | 处理逻辑 | 对其他业务的影响 |
+|---|---|---|---|---|---|
+| 提交 | 表单底部 | 状态=草稿 | 见下方处理规则 1~6 | 落库并启动审批流 | 占用年假余额(预扣) |
+| 保存草稿 | 表单底部 | 状态=草稿 | 无 | 仅落库,不启动流程 | 无 |
+| 撤回 | 详情页 | 状态=审批中 且 首节点未处理 | 审批人未操作 | 终止流程,退回草稿 | 释放预扣的年假余额 |
+
+**处理规则**(按顺序,含边界)
+1. 天数 ≤ 1 天 且 类型为事假 → 直属主管审批
+2. 天数 ≤ 3 天 → 直属主管 → 部门经理
+3. 天数 > 3 天 → 直属主管 → 部门经理 → 人事
+4. 年假余额不足时,提交即拦截,提示剩余天数
+5. 病假超过 2 天必须上传证明,否则不允许提交
+6. 同一时间段重复提交 → 拦截并提示已存在的单据
+
+**输出**
+- 页面:提交成功页,显示单号与当前审批人
+- 落库:`leave_apply` 主表 + `leave_apply_flow` 审批流水表
+- 下游:审批通过后写考勤台账,同步 HR 系统
+
+**异常处理**
+| 异常 | 处理 |
+|---|---|
+| 审批人离职 | 转其上级,记录转派日志 |
+| HR 系统超时 | 本地挂起,定时重试 3 次,仍失败告警 |
+
+**验收标准**:上述 6 条规则逐条可验;余额不足、重复提交两种拦截有明确提示文案
+```
+
+> 判断标准:把这一节单独发给开发,他能不问你就开始写代码,才算写到位。
+
+## 四、按钮清单规范
+
+### 4.1 三个字段千万别混
+
+这是最容易写串的地方,写串了开发就会做错:
+
+| 字段 | 回答的问题 | 例子 |
+|---|---|---|
+| **显示条件** | 按钮看不看得见 | 无权限的用户,根本看不到「禁用」按钮 |
+| **前置校验** | 点了之后能不能成功 | 按钮看得见,但点了提示"不能禁用自己" |
+| **处理逻辑** | 成功后系统做了什么 | 状态改为禁用、写日志、清组织负责人 |
+
+三者混在一起写的典型后果:把"不能禁用自己"写成显示条件,结果按钮直接不显示,用户不知道为什么不让他点。
+
+### 4.2 「对其他业务的影响」怎么推
+
+这一栏是最容易漏的,也是后期扯皮的根源。按四个方向推:
+
+| 方向 | 问什么 |
+|---|---|
+| 数据被谁引用 | 这个字段/状态在哪些查询、报表、下拉框里被用到 |
+| 状态变化影响谁 | 状态改了之后,哪些地方的列表/候选/统计要跟着变 |
+| 下游系统 | 有没有同步给其他系统,同步失败怎么办 |
+| 历史数据 | 已产生的历史记录要不要跟着改(通常不改,但要说清) |
+
+**判断标准:写完之后问一句"这个按钮点下去,还有哪个页面会变"**,答不上来就是没写全。
+
+### 4.3 防止漏按钮的检查法
+
+按钮漏一个,开发就少做一个,最后验收才发现。三个检查动作:
+
+1. **对着原型数**:打开原型页,从左到右、从上到下,见一个记一个,不凭记忆
+2. **套标准组合**:列表页至少要有 新增 / 查询 / 导出 / (行内)修改 / 删除或禁用;表单页要有 提交 / 取消 / 保存草稿
+3. **按状态机推**:凡是状态会变的,每一个"从 A 到 B"的转换都要有一个按钮或一个操作入口,包括审批通过/驳回
+
+**最容易漏的四类**:导出、批量操作、状态互逆操作(禁用/启用、启用/停用)、隐藏的二次确认入口。
+
+### 4.4 什么时候要展开「按钮详述」
+
+不是每个按钮都要展开。满足任一条就展开:
+
+- 前置校验超过 2 条
+- 会改动其他业务的数据或状态
+- 涉及金额、权限、状态流转
+- 有幂等性要求(重复点击怎么办)
+
+其余的,总表里一行写清就够。
+
+## 五、常见不合格写法对照
+
+| 不合格 | 问题 | 改法 |
+|---|---|---|
+| 输入:用户信息 | 没到字段级 | 展开成具体字段表 |
+| 处理规则:按公司规定审批 | 规则不可执行 | 写明天数区间与对应审批人 |
+| 有增删改查功能 | 按钮没列清 | 按按钮清单逐个列 |
+| 禁用:修改状态 | 没说影响谁 | 补「对其他业务的影响」 |
+| 影响:可能影响其他模块 | 等于没说 | 点名具体页面和字段 |
+| 输出:保存到数据库 | 没说哪张表、哪些字段 | 写表名与关键字段 |
+| 异常处理:报错提示 | 没说什么错、提示什么 | 列异常清单与提示文案 |
+| 验收标准:操作便捷 | 不可验证 | 改成可观测的行为 |
+| 性能:响应快 | 不可验证 | 写具体秒数或并发数 |

+ 0 - 1
test/readme.txt

@@ -1 +0,0 @@
-readme

+ 166 - 0
test/sapit-qa-example/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: sapit-qa-example
+description: 按公司规范编写测试用例、设计测试方案、定位缺陷根因。当用户需要写测试用例、做需求覆盖分析、分析缺陷、判断修复是否有效时使用。强制先出覆盖矩阵、断言必须可验证、根因未定位不改代码。
+---
+
+# 测试用例助手
+
+按《09.开发部-作业规范-测试工程师 V2.0》工作。核心原则:**先证明覆盖,再写步骤;每条用例必须有可观测的断言。**
+
+## 何时使用
+
+- 用户说"写测试用例""这个功能怎么测"
+- 用户说"帮我看看需求有没有测漏"
+- 用户说"这个 bug 怎么定位""分析一下根因"
+
+## 第一步:料件体检
+
+| 料 | 必需性 | 缺了怎么办 |
+|---|---|---|
+| 需求说明书(含验收标准) | 必需 | **停止**,没有验收标准写不出断言 |
+| 原型或页面说明 | 必需 | 缺了按需求文档的输入输出推导,标注「待原型确认」 |
+| 历史缺陷记录 | 建议 | 缺了减少一条用例来源 |
+| 业务规则/权限矩阵 | 必需 | 缺了无法设计权限类用例 |
+
+输出体检结论:
+
+> 已收到需求说明书 v1.2(F-003 请假申请,含 6 条处理规则、2 条异常处理)、原型页 3 张。缺少权限矩阵,权限类用例暂按「待确认」输出。
+
+## 第二步:先出覆盖矩阵
+
+**不要直接开始写用例**。先给需求条目到测试点的映射,让人确认有没有漏。
+
+```markdown
+## 需求覆盖矩阵
+
+| 需求条目 | 处理规则 | 测试点 | 用例数 |
+|---|---|---|---|
+| F-003 请假申请 | 规则1 天数≤1天事假→主管 | 边界:0.5/1/1.5 天 | 2 |
+| F-003 | 规则4 余额不足拦截 | 余额=0、余额<申请天数 | 2 |
+| F-003 | 规则6 重复提交拦截 | 完全相同时间段、部分重叠 | 2 |
+| F-003 | 异常:审批人离职 | 转上级、日志记录 | 1 |
+
+覆盖情况:需求条目 8 条,已覆盖 6 条,未覆盖 2 条(F-007 考勤台账、F-008 数据导出,需求未给验收标准)
+```
+
+未覆盖的必须列出来并说明原因,不能默默跳过。
+
+## 第三步:写用例
+
+用例格式见 `references/模板与提示词.md`,核心要求:
+
+- **每条用例必须有断言**,且断言可观测(看数据、看状态、看返回值)
+- **禁止**:"页面显示正常""操作成功""符合预期""体验良好"
+- 边界值必须成组(下边界、边界、上边界)
+- 异常用例要写清预期提示的具体文案,不是"有提示"
+
+## 第四步:断言自检
+
+这是 AI 写用例最容易翻车的地方。生成后逐条过:
+
+| 检查 | 不合格示例 | 合格示例 |
+|---|---|---|
+| 断言可观测 | 页面显示正常 | 列表首行 `apply_no` 等于提交返回的单号 |
+| 断言单一 | 提交成功且状态正确且通知发出 | 拆成 3 条用例 |
+| 含具体值 | 余额不足时提示 | 提示文案包含"剩余 0.5 天" |
+| 可复现 | 系统响应较快 | 接口返回时间 < 800ms(P95) |
+
+发现 1 条不合格,**全部用例重检**——说明提示词里的断言约束没生效。
+
+## 第五步:输出统计
+
+```markdown
+## 用例统计
+- 总用例数:34
+- 覆盖需求条目:6/8(75%)
+- P0 需求端到端用例:3 条
+- 边界用例:12 条
+- 异常用例:9 条
+- 断言复核:34 条已逐条确认可观测
+```
+
+需求覆盖率低于 80% 时主动提示,不要闷头往下写。
+
+## 缺陷分析模式(四阶段根因法)
+
+**不许跳阶段直接猜。** 猜出来的根因,修的地方一定错。
+
+### 阶段 1 · 复现
+
+先确认能稳定复现,写清精确条件:什么数据、什么入口、什么权限、什么时序。复现不了就不要往下走,先补信息。
+
+### 阶段 2 · 收窄
+
+用二分法排除,不要一次改多处试探:
+
+| 层 | 要排除的 |
+|---|---|
+| 入口 | 参数是否正确传到(打日志) |
+| 业务 | 是否走了预期分支(断点或日志) |
+| 数据 | 读到的数据是不是预期值 |
+| 依赖 | 外部接口/中间件返回是否正常 |
+
+一次只验证一层,确认正常就排除该层,缩小范围。
+
+### 阶段 3 · 验证假设
+
+说出完整假设:"如果是 X 导致,那么 Y 应该成立",然后去验证 Y。
+
+- 假设:余额查询返回 null 导致空指针
+- 推断:余额为 0 的用户应该必现,余额正常的用户不会
+- 验证:造一个余额为 0 的账号试一次
+
+**验证不成立,说明假设错了,回到阶段 2,不要硬改。**
+
+### 阶段 4 · 修复后验证
+
+1. 复现用例转绿
+2. 原有相关用例仍绿
+3. 同类问题顺手排查(同一段代码的其他调用点)
+
+**没说清"验证了什么"就不算修好。**
+
+```markdown
+## 根因报告
+- 现象:
+- 复现条件:
+- 收窄过程:排除了入口、依赖,定位在数据层
+- 根因:余额查询在用户无年假记录时返回 null,未判空
+- 验证:造无假期记录账号,必现;有记录的账号,不出现
+- 修复后:复现用例转绿,考勤模块 23 条回归用例全绿
+- 遗留:同一查询在「调休余额」处有相同写法,已单独提 issue
+```
+
+## 硬性禁止
+
+| 禁止 | 原因 |
+|---|---|
+| 写没有断言的用例 | 跑了等于没跑 |
+| 用主观描述当断言 | 无法判定通过与否 |
+| 跳过覆盖矩阵直接写用例 | 必然漏测,且漏了看不出来 |
+| 未经确认就声称覆盖率达 80% | 覆盖率要能算出来,不能估 |
+
+## 完成前自证
+
+**不许说"用例写完了""测试通过了"。** 按下面格式交代:
+
+```markdown
+## 完成自证
+- 已交付:测试用例 34 条,覆盖 6/8 个需求条目(75%)
+- 已验证:34 条断言逐条确认可观测;边界值成组;P0 有端到端场景
+- 未覆盖:F-007 考勤台账、F-008 数据导出(需求无验收标准)
+- 未执行:性能测试(缺压测环境)、安全测试(待工具到位)
+- 未验证:测试环境与生产环境的配置差异部分
+```
+
+被问"测完了吗",正确回答:
+
+> 功能测试跑完三轮,34 条用例全绿;性能和安全没做,缺环境。
+
+而不是"测完了"。**"测试通过"这句话如果说不清范围,就是误导。**
+
+## 参考文件
+
+- `references/模板与提示词.md` — 用例格式、生成提示词、性能与安全测试提示词
+- `references/模板-测试报告.md` — 功能测试报告与性能测试报告格式,出报告时读
+- `references/复核清单.md` — 用例质量检查项、断言反例对照

+ 78 - 0
test/sapit-qa-example/references/复核清单.md

@@ -0,0 +1,78 @@
+# 测试复核清单
+
+## 一、用例质量(逐条过)
+
+```markdown
+## 用例复核
+- [ ] 每条用例都有断言,且断言可观测(值/状态/记录数/文案)
+- [ ] 断言单一,没有把多个校验塞进一条
+- [ ] 断言含具体值,不是"提示错误"而是"提示含'剩余 0.5 天'"
+- [ ] 边界值成组出现(下界、界内、上界)
+- [ ] 异常用例写明具体文案
+- [ ] 前置条件可复现(数据状态写清楚)
+- [ ] 关联了需求编号与规则条目
+- [ ] 无"正常""符合预期""成功"这类表述
+- [ ] 每条用例都能被另一个测试人员独立执行
+```
+
+## 二、覆盖度
+
+```markdown
+## 覆盖复核
+- [ ] 需求条目覆盖率 ≥ 80%(统计:需求__条,覆盖__条)
+- [ ] 每个 P0 需求至少 1 条端到端场景用例
+- [ ] 权限维度单独覆盖(水平越权、垂直越权)
+- [ ] 并发场景已评估(是否需要)
+- [ ] 未覆盖项已列明原因
+```
+
+## 三、断言反例(发现即全量重检)
+
+| 出现这种表述 | 问题 |
+|---|---|
+| 页面显示正常 | 无法判定 |
+| 操作成功 | 没说成功表现 |
+| 提示错误信息 | 没说文案内容 |
+| 数据正确 | 没说哪个字段等于什么 |
+| 响应较快 | 没有阈值 |
+| 功能可用 | 无法验证 |
+
+**只要发现一条,说明提示词约束没生效,全部用例重新过一遍。**
+
+## 四、性能测试复核
+
+```markdown
+- [ ] 并发数有推导依据(日活 × 峰值集中系数 ÷ 时间窗口),不是拍脑袋
+- [ ] 数据量级接近生产(至少同一数量级)
+- [ ] 热点数据分布真实(不存在只压一个 ID)
+- [ ] 监控覆盖应用、数据库、中间件三层
+- [ ] 通过标准是数字(P95 / 错误率 / CPU 水位)
+- [ ] 结论里区分"测出来的"和"推断的"
+```
+
+## 五、安全测试复核
+
+```markdown
+- [ ] 工具扫描报告已归类(严重/高/中/低 + 误报标记)
+- [ ] 业务逻辑漏洞单独人工设计(工具扫不出来)
+- [ ] 水平越权、垂直越权、参数篡改、重复提交、流程绕过逐项验证
+- [ ] 结论区分"已验证无此问题"和"未测试"
+- [ ] 不以"扫描通过"作为安全结论
+```
+
+## 六、缺陷提交规范
+
+| 项 | 要求 |
+|---|---|
+| 标题 | 一句话说清现象与位置,不写"有问题" |
+| 步骤 | 可被他人复现,含数据前置状态 |
+| 实际 vs 预期 | 分开写,不要混在一句里 |
+| 等级 | P0 阻断 / P1 严重 / P2 一般 / P3 建议 |
+| 附件 | 截图或日志,日志只截关键行 |
+| 归因 | 不写"开发的问题",写现象 |
+
+## 七、留痕
+
+- 用例文件:`docs/03-测试/测试用例-{项目}-v{版本}.md`
+- AI 生成占比与复核人记录在文件头
+- 最终执行的用例集与设计用例集的差异要说明(哪些没跑、为什么)

+ 203 - 0
test/sapit-qa-example/references/模板-测试报告.md

@@ -0,0 +1,203 @@
+# 测试报告模板(功能 + 性能)
+
+> 来源:`06.开发部-模板文档-功能测试报告.docx` 与 `07.开发部-模板文档-性能测试报告.docx` 合并转写。
+> 用途:测试阶段正式交付物,同时是上线审批的依据。
+
+## 缺陷等级统一口径
+
+旧模板用「致命/严重/一般/提示」,本模板沿用,与禅道对应:
+
+| 等级 | 名称 | 判定 | 上线要求 |
+|---|---|---|---|
+| 1 级 | 致命 | 系统不可用、数据丢失、资金错误、安全漏洞 | 必须清零 |
+| 2 级 | 严重 | 主流程中断、无替代方案 | 必须清零;确需带病上线须项目经理书面确认 |
+| 3 级 | 一般 | 有替代方案的功能缺陷 | 可带病上线,登记为遗留问题 |
+| 4 级 | 提示 | 文案、样式、体验建议 | 可上线 |
+
+---
+
+# 第一部分 · 功能测试报告
+
+```markdown
+# {项目} {版本} 功能测试报告
+
+## 0 文档信息
+| 项 | 内容 |
+|---|---|
+| 产品名称 | |
+| 版本 | |
+| 密级 | 内部 / 客户可见 |
+| 拟制 / 日期 | |
+| 评审 / 日期 | |
+| 批准 / 日期 | |
+| AI 参与度 | 用例生成 L2 · 报告汇总 L1 |
+
+## 1 测试版本与配套版本
+| 版本名称 | 版本类别 | 测试起始 | 测试结束 | 测试人员 | 测试地点 | 配套产品版本 |
+|---|---|---|---|---|---|---|
+| V2.0.1 | 功能测试 | 2026-11-01 | 2026-11-08 | | | |
+
+## 2 结论与风险
+
+### 2.1 测试结论
+一句话说清:是否满足需求、是否可发布。
+> 本次测试覆盖需求说明书 v1.2 的 8 个功能模块,执行用例 186 条,通过 179 条,2 级以上缺陷清零,**建议发布**。
+
+### 2.2 关键风险
+| 序号 | 风险 | 影响 | 规避措施 |
+|---|---|---|---|
+| 1 | 性能未在真实数据量下验证 | 上线后可能变慢 | 上线首周监控响应时间,超阈值回滚 |
+
+### 2.3 遗留问题
+| 序号 | 问题 | 等级 | 计划处理 |
+|---|---|---|---|
+| 1 | 导出 Excel 超过 5 万行会超时 | 3 级 | 下个版本改为异步导出 |
+
+### 2.4 不对外发布的特性(选填)
+仅运营类项目需要,普通交付项目可删。
+
+## 3 质量评估
+
+### 3.1 缺陷统计(按版本)
+| 版本 | 1级致命 | 2级严重 | 3级一般 | 4级提示 | 总计 |
+|---|---|---|---|---|---|
+| V2.0.0 | 2 | 14 | 40 | 3 | 59 |
+| V2.0.1 | 0 | 3 | 12 | 5 | 20 |
+
+### 3.2 缺陷统计(按功能模块)
+| 功能模块 | 1级 | 2级 | 3级 | 4级 | 总计 | 密度(条/功能点) |
+|---|---|---|---|---|---|---|
+| 用户管理 | 0 | 3 | 8 | 1 | 12 | 1.2 |
+
+> 密度高的模块要单独说明原因,这是判断哪块代码质量差的直接依据。
+
+### 3.3 缺陷趋势
+按轮次统计新增与关闭数,用 mermaid 呈现:
+
+```mermaid
+xychart-beta
+  title "缺陷收敛趋势"
+  x-axis ["第1轮", "第2轮", "第3轮"]
+  y-axis "缺陷数" 0 --> 60
+  bar [59, 20, 4]
+  line [59, 79, 83]
+```
+正常形态:新增逐轮下降、累计关闭逐轮上升。**若第 3 轮新增不降,说明代码质量有问题,不建议上线。**
+
+### 3.4 缺陷类型分布
+| 类型 | 数量 | 占比 | 说明 |
+|---|---|---|---|
+| 功能实现错误 | | | |
+| 需求理解偏差 | | | |
+| 界面与交互 | | | |
+| 数据问题 | | | |
+| 性能问题 | | | |
+| 兼容性 | | | |
+
+> **「需求理解偏差」占比高,问题在需求阶段,不在开发**——这类要回溯到需求文档。
+
+### 3.5 覆盖率
+| 项 | 数值 | 说明 |
+|---|---|---|
+| 需求条目覆盖 | 8/8 | 100% |
+| 用例执行率 | 179/186 | 96.2% |
+| 未执行原因 | 7 条 | 依赖外部系统,环境未就绪 |
+
+### 3.6 质量评价
+简述测试过程、问题解决情况、是否满足发布要求。
+
+## 4 测试过程评估
+
+### 4.1 测试设计
+测试标准、使用工具、方法、过程控制。
+
+### 4.2 测试执行
+是否覆盖所有功能模块,轮次安排。
+
+## 5 附件
+| 附件 | 内容 |
+|---|---|
+| 附件1 遗留问题清单 | 未解决缺陷 |
+| 附件2 测试项通过情况 | 已验证关闭清单 |
+| 附件3 屏蔽问题清单 | 不予解决及原因 |
+```
+
+---
+
+# 第二部分 · 性能测试报告
+
+```markdown
+# {项目} {版本} 性能测试报告
+
+## 0 文档信息
+同功能测试报告
+
+## 1 性能测试结论
+| 功能 | 操作 | 并发用户 | 事务成功率 | 平均响应 | P90 响应 | 吞吐量 | 是否达标 |
+|---|---|---|---|---|---|---|---|
+| 计划执行 | 保存 | 100 | 100% | 0.066s | 0.083s | 1756 KB/s | 满足(<3s) |
+
+**结论**:在 100 并发下,核心交易响应时间满足 3 秒要求,无错误。**未验证**:500 并发场景(超出预期峰值 5 倍)。
+
+> 「未验证」必须写出来。只写"满足",客户会以为全场景都测过了。
+
+## 2 测试环境
+
+### 2.1 软件配置
+| 资源 | 说明 | 数量 |
+|---|---|---|
+| Web 服务器操作系统 | CentOS 7.7 | 1 |
+| 数据库 | MySQL 8.0 | 1 |
+| 压测工具 | JMeter 5.6 | 1 |
+| 客户端操作系统 | Windows 10 | 1 |
+
+### 2.2 硬件配置
+| 资源 | CPU | 内存 | 磁盘 | 数量 |
+|---|---|---|---|---|
+| 应用服务器 | 4 核 | 8G | 100G | 1 |
+| 数据库服务器 | 8 核 | 16G | 200G | 1 |
+
+> **硬件配置必须写全**。不写配置的性能报告等于没测——换台机器结论就变了。
+
+## 3 测试分析
+
+### 3.1 场景设计
+| 场景 | 事务比例 | 加载策略 | 持续时间 | 思考时间 |
+|---|---|---|---|---|
+| 混合业务 | 查询 70% / 提交 30% | 每 5 秒加 2 用户 | 30 分钟 | 2~5 秒随机 |
+
+**并发数怎么来的**(必须给推导,不能拍脑袋):
+
+```
+日活 2000 人 × 峰值集中系数 20% × 人均操作 5 次 ÷ 峰值窗口 3600 秒 ≈ 峰值 TPS 5.6
+按响应时间 0.5 秒估算并发 = 5.6 × 0.5 ≈ 3
+考虑 3 倍冗余与未来增长,取 100 并发
+```
+
+### 3.2 执行结果汇总
+同第一节结论表。
+
+### 3.3 错误分析
+| 错误 | 数量 | 原因 | 处理 |
+|---|---|---|---|
+| 连接超时 | 12 | 连接池上限 20 | 调到 50 后消失 |
+
+### 3.4 请求与网络分析
+平均事务响应时间曲线、网络带宽占用。
+
+### 3.5 系统资源分析
+| 资源 | 峰值使用率 | 判断 |
+|---|---|---|
+| 应用 CPU | 62% | 正常 |
+| 数据库 CPU | 88% | 偏高,建议加索引 |
+| 磁盘 IO | 45% | 正常 |
+| 网络带宽 | 12 Mbps | 正常 |
+```
+
+---
+
+## 写报告的三条硬规则
+
+1. **只写跑过的数据,不推算**。没测的场景写「未验证」,不写「预计满足」。
+2. **结论要有对照标准**。说"响应快"没用,要说"P90 = 0.083s,标准是 <3s"。
+3. **异常和短板要主动写**。事后被客户发现,比事先说明难看得多。

+ 114 - 0
test/sapit-qa-example/references/模板与提示词.md

@@ -0,0 +1,114 @@
+# 用例模板 · 生成提示词
+
+## 一、用例格式
+
+```markdown
+### TC-F003-007 病假超 2 天未传证明拦截
+
+**关联需求**:F-003 处理规则 5
+**优先级**:P0
+**类型**:异常 / 边界
+**前置条件**:
+- 员工「张三」年假余额 3 天、病假不限额
+- 已登录移动端
+
+**步骤**
+| # | 操作 | 预期结果(断言) |
+|---|---|---|
+| 1 | 进入请假申请页,类型选"病假" | 页面标题为"请假申请",类型下拉默认值为空 |
+| 2 | 开始时间选 2026-11-20,结束时间选 2026-11-23 | 天数自动显示 `3.0` |
+| 3 | 不上传附件,点击提交 | 提交按钮置灰或点击后提示"病假超过 2 天须上传证明",且 `leave_apply` 表无新增记录 |
+
+**数据校验**
+- `SELECT count(*) FROM leave_apply WHERE emp_id='ZS001' AND start_time='2026-11-20'` 结果为 0
+
+**备注**:与 TC-F003-008(病假 2 天不传证明可提交)成对,验证边界值 2 天。
+```
+
+## 二、断言写法对照
+
+| 场景 | ❌ 不合格 | ✅ 合格 |
+|---|---|---|
+| 列表加载 | 列表显示正常 | 列表返回 12 条,首行单号为 `LA20261120001`,按提交时间倒序 |
+| 提交成功 | 提交成功 | 接口返回 code=0,data 含单号;库中 `approve_status=1` |
+| 校验拦截 | 提示错误 | 提示文案包含"剩余 0.5 天",且未产生单据 |
+| 权限 | 无权操作 | 该用户看不到"删除"按钮;直接调接口返回 403 |
+| 性能 | 响应较快 | 100 并发下 P95 < 800ms,错误率 0 |
+
+## 三、生成提示词
+
+```
+你是测试工程师。根据下方需求章节设计测试用例。
+
+约束:
+1. 每条用例必须有可观测的断言,禁止使用"正常""符合预期""成功"这类描述
+2. 断言要能看到具体值(返回码、字段值、提示文案、库中记录数)
+3. 覆盖三类:正常流、边界值(下界/界内/上界)、异常流
+4. 一个断言一条用例,不要把多个校验塞进一条
+5. 标注关联的需求编号与规则条目
+6. 无法确定预期结果的地方标「待需求确认」,不要自己编
+
+输出格式:
+### TC-{功能号}-{序号} {用例名}
+**关联需求**:
+**优先级**:P0/P1/P2
+**类型**:正常 / 边界 / 异常 / 权限 / 性能
+**前置条件**:
+**步骤**:表格(# | 操作 | 预期结果)
+**数据校验**:SQL 或接口断言
+
+需求章节:
+<粘贴 F-003 全部内容>
+```
+
+## 四、性能测试提示词
+
+```
+为「请假申请提交」接口设计性能测试方案。
+已知:单体应用,Spring Boot 3.2,MySQL 8.0,生产日均 2000 单,峰值集中在 9:00-10:00
+需要:
+1. 场景模型(并发数怎么算出来的,说明依据,不要给一个拍脑袋的数字)
+2. 数据准备(数据量级、热点分布)
+3. 监控指标(应用、数据库、中间件各看什么)
+4. 通过标准(P95、错误率、资源水位)
+5. 需要我确认的参数单独列出
+
+注意:并发模型必须说明假设,我不接受"建议 500 并发"这种没有依据的结论。
+```
+
+## 五、安全测试提示词
+
+```
+对「请假申请」模块做安全测试点梳理,分两类:
+
+A. 工具能覆盖的(SAST/DAST/SCA 能扫出来的)
+B. 工具覆盖不了、必须人工设计的(重点关注业务逻辑漏洞)
+
+B 类请按以下方向逐个检查是否存在:
+- 水平越权(改 ID 看别人的单据)
+- 垂直越权(普通员工调审批接口)
+- 金额/天数篡改(前端传的天数与实际起止时间不符)
+- 重复提交(并发下同一单提交两次)
+- 审批流绕过(跳过中间审批人)
+- 附件上传(类型伪造、路径穿越、大小绕过)
+
+每条给出:攻击方式、预期防护、验证步骤。
+不要给结论说"系统是安全的",只列测试点。
+```
+
+## 六、缺陷分析提示词
+
+```
+以下是一个缺陷现象和日志,请先判断根因,不要给修复代码。
+
+现象:<描述>
+复现步骤:<步骤>
+日志:<粘贴关键行>
+涉及代码:<文件与方法>
+
+请输出:
+1. 根因类别(需求理解 / 设计缺失 / 编码 / 环境 / 数据)
+2. 判断依据(日志哪一行、代码哪一段支持这个判断)
+3. 还需要什么信息才能确认
+4. 建议的验证方式(怎么复现或排除)
+```