华佗
dad8aa0aad
- MD/specs/IRON_RULES.md: 总览表补充#14-#18，版本升至v2.1 - AGENTS.md: P0铁律区新增铁律18 - RULES.md: P0铁律区新增铁律18 - healthlink-his-server/AGENTS.md: 速查区新增铁律18 - healthlink-his-ui/AGENTS.md: 速查区新增铁律18 - .cursorrules/.clinerules/.windsurfrules: 同步新增铁律18 - V25实体层: NursingVitalSignsChart/SurgerySafetyCheck/SpecimenBarcode/SysAuditLog/EmpiIdVerification - V25 Flyway迁移: V25__vitalsigns_safety_barcode_audit.sql
500 lines
19 KiB
Markdown
500 lines
19 KiB
Markdown
# HealthLink-HIS — AI 开发规范（自动加载）
|
||
|
||
> 🤖 **本文件供所有 AI 编码工具自动读取**。进入本项目后必须遵守以下规范。
|
||
>
|
||
> **模型决定上限，Harness 决定底线。**
|
||
|
||
---
|
||
|
||
## 一、项目概览
|
||
|
||
| 属性 | 值 |
|
||
|------|------|
|
||
| 项目名 | HealthLink-HIS（医院信息系统） |
|
||
| 后端路径 | `healthlink-his-server/` |
|
||
| 前端路径 | `healthlink-his-ui/` |
|
||
| 文档路径 | `MD/` |
|
||
| JDK | 25 (OpenJDK) |
|
||
| Spring Boot | 4.0.6 |
|
||
| MyBatis-Plus | 3.5.16 |
|
||
| Vue | 3.x + Vite + Element Plus |
|
||
| 数据库 | PostgreSQL 15+ |
|
||
| 包名 | `com.healthlink.his` |
|
||
| 后端端口 | 18082 |
|
||
| 前端端口 | 81 |
|
||
|
||
---
|
||
|
||
## 二、铁律（必须遵守，违反即失败）
|
||
|
||
### 🔴 P0 铁律 — 不可违反
|
||
|
||
**铁律1: 修改完必须测试**
|
||
```
|
||
后端: mvn clean compile -DskipTests → mvn install -DskipTests → mvn test
|
||
前端: npm run build:dev → npm run lint
|
||
```
|
||
- 白盒：编译通过，无 ERROR
|
||
- 黑盒：关键接口返回 `{code:200, data:...}`，验证业务逻辑
|
||
- 冒烟：应用正常启动，核心流程通畅
|
||
|
||
**铁律2: Flyway 数据库迁移**
|
||
- 凡是新建表、新增字段，必须创建 Flyway 迁移脚本
|
||
- 路径：`healthlink-his-domain/src/main/resources/db/migration/`
|
||
- 命名：`V{版本号}__{描述}.sql`（双下划线）
|
||
|
||
**铁律3: 测试通过后才提交**
|
||
- 编译 + 测试全部通过后才能 git commit
|
||
- 不提交未完成的功能、调试代码、临时文件
|
||
|
||
**铁律4: 前后端API路径对齐**
|
||
- 后端前缀：`/healthlink-his/api/v1/`
|
||
- 前端 `request.js` 的 baseURL 必须与后端匹配
|
||
|
||
**铁律5: 状态值一致性（Bug #574 教训）**
|
||
- 修改任何状态值前，必须先列出完整的状态流转链路
|
||
- 检查项：枚举定义 → Service 设置 → 查询映射 → 前端 STATUS_CLASS_MAP → 前端 v-if → 统计SQL
|
||
- 禁止：只改一端不检查其他端
|
||
|
||
**铁律6: 禁止删除源文件（Bug #574 教训）**
|
||
- 绝对禁止删除项目中已有的 Java/Vue/SQL 源文件
|
||
- 编译错误 → 修复错误；重复文件 → 重构合并
|
||
- 唯一例外：明确由人类确认删除的文件
|
||
|
||
**铁律7: 禁止修改已有公开方法签名**
|
||
- 不能删除/重命名已有的 public 方法，不能修改参数列表
|
||
- 需要新功能 → 添加重载方法；需要改行为 → 修改内部实现
|
||
|
||
**铁律8: 验证后才宣称完成（Verification Before Completion）**
|
||
- **没有跑过验证命令，就不能说"完成了""通过了""没问题"**
|
||
- 禁止使用"应该可以""大概没问题""看起来正确"
|
||
- 必须：运行命令 → 读取输出 → 确认结果 → 才能宣称
|
||
- 这是诚实原则，不是效率问题
|
||
|
||
|
||
**铁律9: 开发前必须审核原有代码（P0 — 铁律）**
|
||
- **任何新功能开发前，必须先搜索项目中是否已有相关代码**
|
||
- 搜索路径：Controller / AppService / Service / Mapper / Entity / 前端页面 / API接口
|
||
- 如果已有部分功能 → 在原有代码基础上**升级优化完善**，禁止另起炉灶
|
||
- 如果已有接口但前端缺失 → 只补前端，不重复建后端
|
||
- 如果已有前端但后端缺失 → 只补后端，不重写前端
|
||
- 搜索命令：`rg -l "关键词" healthlink-his-server/ healthlink-his-ui/src/`
|
||
- 禁止：不看代码就新建模块、重复实现已有功能、废弃原有代码另写一套
|
||
|
||
|
||
**铁律12: 设计文档确认后自主开发（铁律）**
|
||
- 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行**
|
||
- **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进
|
||
- 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint
|
||
- 只在遇到**无法解决的阻塞**（如技术选型冲突、需求不明确、第三方依赖不可用）时才暂停询问
|
||
- 设计文档是"**已签合同**"，不是"参考意见"。铁律执行优先级：设计文档 > 人类临时指令 > AI 自行判断
|
||
|
||
**铁律18: 禁止破坏原有功能（P0绝对铁律）**
|
||
- **完善增加功能和流程时，绝对不能破坏或者让原有功能不能用**
|
||
- 修改已有实体前必须对比原始文件（`git show HEAD~N:./file.java`），保留所有原有字段和方法
|
||
- 新增字段只能追加，不能删除或重命名已有字段
|
||
- SQL迁移只允许 `ALTER TABLE ADD COLUMN`，不允许 `DROP COLUMN` 或 `RENAME COLUMN`
|
||
- Controller新端点不能修改已有端点的路径或参数
|
||
- 前端新页面不能修改已有页面的组件结构
|
||
- 每次修改后必须 `mvn clean compile -DskipTests` 验证
|
||
- **违规判定**: 因修改导致原有代码编译失败或运行报错，视为违反铁律18，必须立即回滚修复
|
||
|
||
|
||
### 🟡 P1 铁律 — 强烈建议
|
||
|
||
**铁律9: 先分解再行动**
|
||
- 修改超过3个文件、涉及多模块、数据库变更，必须先制定计划
|
||
|
||
**铁律10: 验证后信**
|
||
- 每次修改后必须验证编译通过，不信记忆
|
||
|
||
**铁律13: 文档统一管理**
|
||
- 所有文档存储在 `MD/` 目录
|
||
- 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`）
|
||
- 文档头部必须包含元数据块（文档类型、版本、日期）
|
||
|
||
---
|
||
|
||
|
||
**铁律14: 设计文档必须包含UI设计和调用流程**
|
||
- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程
|
||
- 没有明确UI设计的模块，禁止直接编码
|
||
- 详见
|
||
- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程
|
||
- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染
|
||
|
||
---
|
||
|
||
## 三、Karpathy 编码准则
|
||
|
||
> 减少 LLM 常见编码错误。偏向谨慎而非速度。
|
||
|
||
### 3.1 先想再写
|
||
- 明确陈述假设，不确定就问
|
||
- 多种解读时都列出来，不要默默选一种
|
||
- 有更简单的方案就说出来，该推回就推回
|
||
- 不清楚的地方停下来，说清楚哪里不清楚
|
||
|
||
### 3.2 简洁优先
|
||
- 不做没要求的功能，不做一次性代码的抽象
|
||
- 不加没要求的"灵活性"和"可配置性"
|
||
- 200 行能 50 行搞定就重写
|
||
- 自问："高级工程师会不会觉得这过度设计？"
|
||
|
||
### 3.3 精准修改
|
||
- 只改必须改的，不"顺手改进"相邻代码
|
||
- 匹配现有代码风格，即使你有不同的偏好
|
||
- 每行改动都能追溯到用户的请求
|
||
- 只清理你自己改动产生的无用代码
|
||
|
||
### 3.4 目标驱动
|
||
- 把任务转化为可验证目标
|
||
- 多步任务声明计划：`[步骤] → 验证: [检查]`
|
||
- 强验收标准让 Agent 能独立循环，弱标准需要持续澄清
|
||
|
||
---
|
||
|
||
## 四、全链路 6 环分析
|
||
|
||
> ⚠️ **涉及数据库字段的 Bug / 需求，必须走完整链路。**
|
||
|
||
```
|
||
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
|
||
①录入 ②验证 ③业务 ④持久化 ⑤存储 ⑥联动
|
||
```
|
||
|
||
| 环 | 检查内容 |
|
||
|----|---------|
|
||
| ① 录入 | 前端有无输入入口（弹窗、表格行编辑、表单） |
|
||
| ② 验证 | Controller 参数校验、@Valid、权限控制 |
|
||
| ③ 业务 | Service 业务逻辑、事务边界、多个 Service 实现类入口 |
|
||
| ④ 持久化 | Mapper XML、DTO 字段映射、类型转换 |
|
||
| ⑤ 存储 | 数据库表结构、索引、NOT NULL 约束 |
|
||
| ⑥ 联动 | 上游（医嘱→护士站）、下游（打印、计费、报表）是否同步 |
|
||
|
||
**修复后的验证顺序**：
|
||
1. 数据库：确认状态值已正确写入
|
||
2. 后端接口：确认返回的状态映射正确
|
||
3. 前端显示：确认页面显示正确状态文本
|
||
4. 前端交互：确认按钮/操作基于正确状态启用/禁用
|
||
5. 统计数据：确认池/报表统计包含新状态
|
||
|
||
---
|
||
|
||
## 五、Harness Engineering 方法论
|
||
|
||
> Harness = 约束 + 反馈 + 控制平面 + 持久执行
|
||
|
||
### 5.1 四层约束金字塔
|
||
|
||
| 层级 | 内容 | 落地方式 |
|
||
|------|------|---------|
|
||
| **L1 架构约束** | 接口合约、包结构、命名规范、禁止模式 | 本文件铁律 |
|
||
| **L2 代码质量** | 圈复杂度、代码风格、类型提示 | 编译门禁 + ESLint |
|
||
| **L3 安全约束** | 敏感信息检测、权限检查、输入验证 | 配置不可硬编码 |
|
||
| **L4 业务规则** | 领域逻辑、数据一致性、事务边界 | 全链路 6 环验证 |
|
||
|
||
**约束设计原则**：
|
||
- **可验证**：每条约束必须能被自动化检查（"覆盖率>90%"✅ "质量要高"❌）
|
||
- **无歧义**："每函数不超过50行"✅ "函数不要太长"❌
|
||
- **优先级**：安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
|
||
- **渐进增强**：L1编译通过 → L2+命名规范 → L3+测试覆盖 → L4+安全扫描
|
||
|
||
### 5.2 三层反馈系统
|
||
|
||
| 层级 | 速度 | 覆盖范围 | 失败处理 |
|
||
|------|------|---------|---------|
|
||
| **L1 编译检查** | <30秒 | 语法、类型、签名 | 立即阻断，自行修复 |
|
||
| **L2 数据流验证** | <5分钟 | 全链路字段、Mapper XML、DTO | 修复后上报 |
|
||
| **L3 人工审查** | 10-30分钟 | 架构、设计、业务正确性 | 驳回/指导/批准 |
|
||
|
||
**反馈铁律**：
|
||
- 反馈必须可行动（文件 + 行号 + 错误类型 + 修复方向）
|
||
- 失败后先回滚到最近检查点，再重试
|
||
- 持续失败3次 → 上报人类
|
||
|
||
### 5.3 控制平面
|
||
|
||
```
|
||
战略层（人类） → 设定目标、审批决策、异常升级
|
||
战术层（Agent） → 任务分解、update_plan、依赖协调、检查点保存
|
||
执行层（Agent） → 代码生成、测试执行、错误恢复、幂等重试
|
||
```
|
||
|
||
### 5.4 持久执行
|
||
|
||
- 每个关键步骤保存检查点（`update_plan` 进度）
|
||
- 失败后从最新检查点恢复，不从头开始
|
||
- 幂等设计：同一操作重复执行结果一致
|
||
- **三层状态管理**：系统层(工作流ID/超时/重试) → 执行层(当前活动/进度) → 业务层(已完成工作/中间产物)
|
||
|
||
---
|
||
|
||
## 六、五层质量门禁
|
||
|
||
| 门禁 | 时间 | 范围 | 失败处理 |
|
||
|------|------|------|---------|
|
||
| **L1 编译检查** | <30秒 | 语法、类型、导入 | Agent 自行修复 |
|
||
| **L2 静态分析** | <2分钟 | 代码风格、复杂度、安全 | Agent 修复 |
|
||
| **L3 单元测试** | <5分钟 | 功能正确性、边界条件 | 自动修复或上报 |
|
||
| **L4 集成测试** | <15分钟 | 模块间交互、数据流 | 上报人工 |
|
||
| **L5 生产验证** | 持续 | 监控、告警、性能 | 自动回滚 |
|
||
|
||
**提交铁律**：L1-L2 必须通过才能 commit，L3（如有DB变更）必须通过才能 push
|
||
|
||
---
|
||
|
||
## 七、系统化调试（Systematic Debugging）
|
||
|
||
> **铁律：没有根因调查，不能提出修复方案。**
|
||
|
||
### 四阶段流程
|
||
|
||
**阶段1：根因调查**（修复前必须完成）
|
||
1. 仔细阅读错误信息（堆栈、行号、错误码）
|
||
2. 稳定复现（能否可靠触发？步骤？每次？）
|
||
3. 检查最近变更（git diff、新依赖、配置变更）
|
||
4. 多组件系统：在每个组件边界加诊断日志，定位哪一层断裂
|
||
5. 追踪数据流：坏值从哪里来？谁调用的？一直追溯到源头
|
||
|
||
**阶段2：模式分析**
|
||
- 找到同代码库中类似的正常工作代码
|
||
- 逐项对比差异
|
||
- 理解依赖关系
|
||
|
||
**阶段3：假设与测试**
|
||
- 形成单一假设："我认为X是根因，因为Y"
|
||
- 做最小改动测试
|
||
- 有效 → 阶段4；无效 → 新假设
|
||
|
||
**阶段4：实施**
|
||
- 创建失败测试用例
|
||
- 修复根因（不是症状）
|
||
- 验证修复
|
||
|
||
---
|
||
|
||
## 八、后端开发规范
|
||
|
||
### 分层架构
|
||
```
|
||
Controller → AppService → Service → Mapper → Entity
|
||
```
|
||
|
||
### 命名规范
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| Controller | `XxxController` | `RegistrationController` |
|
||
| AppService | `IXxxAppService` / `XxxAppServiceImpl` | `IRegistrationAppService` |
|
||
| Service | `IXxxService` / `XxxServiceImpl` | `IRegistrationService` |
|
||
| Mapper | `XxxMapper` | `RegistrationMapper` |
|
||
| Entity | `Xxx` | `Registration` |
|
||
| DTO | `XxxDto` / `XxxQueryDto` | `RegistrationDto` |
|
||
|
||
### 包结构
|
||
```
|
||
com.healthlink.his.web.{module}.controller
|
||
com.healthlink.his.web.{module}.appservice
|
||
com.healthlink.his.web.{module}.service
|
||
com.healthlink.his.web.{module}.mapper
|
||
com.healthlink.his.web.{module}.dto
|
||
com.healthlink.his.domain.{module}
|
||
com.healthlink.his.common.enums
|
||
```
|
||
|
||
### 关键约束
|
||
- 所有查询使用 `LambdaQueryWrapper`，禁止字符串拼接 SQL
|
||
- `@Transactional(rollbackFor = Exception.class)` 管理事务
|
||
- 所有接口标注 `@PreAuthorize` 权限控制
|
||
- 患者敏感信息在日志中脱敏
|
||
- **扩展功能不修改原有函数签名**
|
||
|
||
---
|
||
|
||
## 九、前端开发规范
|
||
|
||
### 技术栈
|
||
- Vue 3 + Vite + Element Plus + Pinia + Axios（基于 RuoYi-Vue3）
|
||
|
||
### 目录结构
|
||
```
|
||
src/api/{module}/ # API接口
|
||
src/views/{module}/ # 页面组件
|
||
src/store/modules/ # Pinia状态管理
|
||
src/components/ # 公共组件
|
||
```
|
||
|
||
### 关键约束
|
||
- API前缀：`/healthlink-his/api/v1/`
|
||
- 路由懒加载：`() => import('@/views/xxx/index.vue')`
|
||
- 页面使用 `<script setup>` 语法
|
||
- 按钮权限使用 `v-hasPermi` 指令
|
||
- `onMounted` 中注册的事件在 `onUnmounted` 中移除
|
||
|
||
---
|
||
|
||
## 十、Agent 体系
|
||
|
||
### 角色与路由
|
||
|
||
| 代号 | 名称 | 角色 | 路由关键词 |
|
||
|------|------|------|-----------|
|
||
| liubei | 刘备 | 项目经理 | 协调、分派、异常升级 |
|
||
| zhugeliang | 诸葛亮 | 架构师 | 分析、路由、设计 |
|
||
| guanyu | 关羽 | 后端开发 | java, api, spring, service, controller |
|
||
| zhaoyun | 赵云 | 前端开发 | vue, 界面, 显示, 弹窗, 按钮 |
|
||
| xunyu | 荀彧 | DBA | 数据库, sql, 迁移, mapper xml |
|
||
| zhangfei | 张飞 | 测试 | 测试, QA, 回归 |
|
||
| huatuo | 华佗 | 验收 | 需求验收、质量确认 |
|
||
| chenlin | 陈琳 | 文档 | 文档、归档、Git提交 |
|
||
|
||
### 协作流水线
|
||
|
||
```
|
||
刘备(协调) → 诸葛亮(分析路由) → {关羽|赵云}(修复) → 荀彧(DB审查) → 张飞(测试) → 华佗(验收) → 陈琳(归档)
|
||
```
|
||
|
||
### Bug 修复完整管线（BDT 方法论）
|
||
|
||
```
|
||
获取Bug → 设计测试用例 → 基线测试(应失败) → 全链路修复 → 回归测试(应通过) → 扩展测试(无回归) → 提交
|
||
```
|
||
|
||
### Bug 状态管理铁律
|
||
- 人类提的 Bug：只加备注，不改状态，不改分配
|
||
- 智能体提的 Bug：可以改分配和加备注
|
||
- 已关闭/已解决的 Bug 不再处理
|
||
|
||
---
|
||
|
||
## 十一、审查与审计
|
||
|
||
### 三层审查体系
|
||
|
||
| 层级 | 内容 | 时机 |
|
||
|------|------|------|
|
||
| **L1 自审** | Agent 对照约束逐条检查 | 每次提交前 |
|
||
| **L2 配对审查** | Agent 生成变更摘要，人类终审 | PR/提交时 |
|
||
| **L3 合规审查** | 审计追踪，记录所有 AI 操作 | 持续 |
|
||
|
||
### L1 自审清单
|
||
```yaml
|
||
self_review:
|
||
- "所有修改能通过编译？"
|
||
- "遵守命名规范？"
|
||
- "测试覆盖达标？"
|
||
- "没有遗漏的 TODO / DEBUG？"
|
||
- "变更范围没超出任务边界？"
|
||
```
|
||
|
||
### 评审评分维度
|
||
| 维度 | 问题 |
|
||
|------|------|
|
||
| 正确性 | 行为是否符合目标功能？ |
|
||
| 验证 | 检查是否真的跑过并留下证据？ |
|
||
| 范围纪律 | 是否保持在选定功能范围内？ |
|
||
| 可靠性 | 结果能否在重启后继续工作？ |
|
||
| 可维护性 | 代码和文档是否清楚到可交接？ |
|
||
|
||
---
|
||
|
||
## 十二、标准工作循环
|
||
|
||
```
|
||
开始会话
|
||
├→ 1. Init — 读 AGENTS.md + PROGRESS.md + git log
|
||
├→ 2. Select — 只选一个未完成功能
|
||
├→ 3. Implement — 一次只做一个，不扩大范围
|
||
├→ 4. Verify — 运行验证命令，有证据才标记完成
|
||
└→ 5. Cleanup — 更新进度 + clean-state-checklist + git commit
|
||
```
|
||
|
||
### 会话结束前必须运行 Clean State Checklist
|
||
```
|
||
□ 标准启动路径仍然可用
|
||
□ 标准验证路径仍然可运行
|
||
□ 当前进度已记录到进度日志
|
||
□ 无半成品步骤处于未记录状态
|
||
□ 下一轮会话无需人工修复即可继续
|
||
```
|
||
|
||
---
|
||
|
||
## 十三、开发流程
|
||
|
||
```
|
||
收到任务
|
||
├→ ① 分析需求 → 读相关文档(MD/)、读全链路6环
|
||
├→ ② 制定计划 → update_plan (3-6个阶段)
|
||
├→ ③ 后端开发 → Controller → AppService → Service → Mapper → Entity → Flyway
|
||
├→ ④ 后端测试 → mvn test → 接口测试(业务逻辑验证)
|
||
├→ ⑤ 前端开发 → API接口 → 页面组件 → 路由配置
|
||
├→ ⑥ 前端测试 → npm run build:dev → 功能验证
|
||
├→ ⑦ 质量门禁 → L1编译 → L2测试 → L3DB审查 → L4验收 → L5归档
|
||
└→ ⑧ 提交代码 → git commit(规范格式) → git push → 文档更新
|
||
```
|
||
|
||
### Git Commit 格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
type: feat|fix|docs|refactor|test|chore
|
||
scope: 模块名(如 registration, billing, pharmacy)
|
||
```
|
||
|
||
---
|
||
|
||
## 十四、快速参考命令
|
||
|
||
```bash
|
||
# === 后端 ===
|
||
export JAVA_HOME=/opt/jdk-25
|
||
mvn clean compile -DskipTests # 编译
|
||
mvn install -DskipTests # 构建
|
||
mvn test -pl healthlink-his-application -Dtest="XxxTest" -Dsurefire.failIfNoSpecifiedTests=false
|
||
|
||
# === 前端 ===
|
||
cd healthlink-his-ui
|
||
npm run dev && npm run build:dev && npm run lint && npm run test:run
|
||
|
||
# === Git ===
|
||
git status && git add -A && git commit -m "feat(module): desc" && git push origin develop
|
||
```
|
||
|
||
---
|
||
|
||
## 十五、详细规范文档索引
|
||
|
||
| 文档 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| 执行铁律 | `MD/specs/IRON_RULES.md` | 铁律完整版 |
|
||
| 后端规范 | `MD/specs/BACKEND_DEVELOPMENT_STANDARD.md` | 后端编码标准 |
|
||
| 前端规范 | `MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md` | 前端编码标准 |
|
||
| Harness方法论 | `MD/specs/HARNESS_ENGINEERING.md` | 完整Harness+Agent方法论 |
|
||
| 文档规范 | `MD/DOCUMENTATION_STANDARD.md` | 文档管理标准 |
|
||
| 后端清单 | `MD/specs/BACKEND_CHECKLIST.md` | 发布前检查 |
|
||
| 前端清单 | `MD/specs/FRONTEND_CHECKLIST.md` | 发布前检查 |
|
||
| 三甲标准 | `MD/standards/GRADE3A_HIS_STANDARD.md` | 三甲医院达标标准 |
|
||
| Flyway指南 | `MD/guides/FLYWAY_USAGE_GUIDE.md` | 数据库迁移指南 |
|
||
|
||
---
|
||
|
||
## 十六、过往教训
|
||
|
||
| 教训 | 内容 |
|
||
|------|------|
|
||
| 状态链路断裂 | Bug#574: 签到设 BOOKED(1) 而非 CHECKED_IN(3)，前端映射缺失 → 必须走完整状态链路 |
|
||
| 盲删源文件 | AI 看到编译错误直接删文件，没检查 baseline → 必须先确认文件来源 |
|
||
| 修复方向偏差 | 多次 fallback 改的是错误的 Service → 必须用 rg 搜索所有相关代码路径 |
|
||
| bug_reports 缺列 | INSERT 静默失败 → 必须检查表结构 |
|
||
| 禅道 comment API | API 不存在，用 resolve+activate workaround |
|
||
| SQLite WAL 并发 | 多进程并发写需要 checkpoint |
|
||
| UTF-8 切片 | 多字节字符不能用 byte index 切片 |
|
||
| 上下文焦虑 | Agent 感觉上下文快满时会匆忙结束，跳过验证 → 注意 context 40% 阈值 |
|
||
| 过早宣告胜利 | 自评≠验证，分开"干活"和"检查" |
|
||
| 覆盖率幻觉 | 覆盖率达标但逻辑没测 → 引入变异测试 |
|
||
|
||
---
|
||
|
||
> ⚠️ 本文件是 AI 开发规范的唯一信源。各工具配置文件由 `bash scripts/sync-ai-rules.sh` 同步。
|