AI 辅助开发实战教程

目标：新人能够使用团队允许的 AI 编程工具，在这个仓库中完成“理解需求 → 定位代码 → 实现 → 验证 → 评审”的闭环。先完成 新人开发入门 中的环境准备。

本文讲工具通用的操作方法，不依赖特定模型、收费套餐或插件。工具安装和登录按团队配置完成；下面的提示词可直接复制到支持读取本地项目的编程助手。如果工具不能访问仓库，只提供必要且脱敏的代码，并明确它无法实际运行测试。

1. 第一次使用：把上下文准备好

1. 在 AI 工具中打开 researchplatform 仓库根目录，而不是只打开一个 Vue 文件。
2. 自己先执行 git status --short，辨认已有改动；按团队规范准备个人开发分支。
3. 显式要求 AI 阅读 CLAUDE.md、新人文档和任务对应的业务约束。不同工具不一定自动加载同一份约定文件。
4. 提供业务角色、租户场景、复现步骤、预期行为及验收标准。提供脱敏样例，不粘贴真实密码、私钥、登录 token 或完整业务数据。
5. 初次任务先让 AI 分析，再逐步授权实现；不要给模糊的“优化整个项目”。

第一条提示词：

你正在 researchplatform 仓库协助我开发。
请先阅读 CLAUDE.md、docs/新人开发入门.md 和 docs/科研模块开发约束.md，
检查 git status，保留已有修改。本轮只分析，不改代码。

请用当前源码说明：
1. 后端、前端如何运行和验证，命令分别在哪个目录执行；
2. 动态表单、配置查询、业务流程分别在哪里；
3. 关于页面从 Vue 到 /about 接口的真实调用链；
4. 哪些事项还缺少环境或业务信息。
每条关键结论提供文件路径和符号名，不把历史文档示例当成当前实现。
不要输出配置文件中的凭据，也不要连接数据库或启动外部同步任务。

你要检查： AI 是否准确识别 Java 17、模块任务名、前端 QA 代理及 Mock；是否发现 axios 已解包成功响应；是否区分源码事实与环境推测。若引用文件不存在，先纠正定位，不继续生成实现。

2. 每个任务按五个阶段推进

阶段一：描述业务，而不只描述按钮

把下面模板填完整；不确定的项直接写“不确定，需确认”。

任务：<一句话业务目标>
业务角色及租户范围：<谁在什么范围使用>
入口：<菜单、页面、接口，已知哪些写哪些>
当前行为：<复现步骤、实际结果、脱敏请求/错误>
预期行为：<何时允许、何时禁止、成功和失败如何提示>
必须保持：<字段 key、默认值、顺序、权限、历史数据、相邻业务规则>
验收场景：<正常、空值、无权限、重复操作、历史数据等适用场景>
范围：<允许修改的模块；是否涉及独立租户配置包>

请先定位现有实现和测试，判断应改代码、数据库迁移还是配置。
列出完整链路、最小变更点和待确认项，暂不修改代码。

例子：“管理员在指定租户的列表看不到某操作”比“给我加一个按钮”更完整。还需要说明单据状态、当前权限和是否允许历史单据操作。

阶段二：审查 AI 的方案

先看四件事：它是否复用了现有能力，是否定位到真实数据来源，是否保护权限及租户边界，是否给出了可执行的验证步骤。

请把方案收敛成文件级清单：文件、修改理由、影响范围、验证方式。
对每个关键字段说明前端绑定、请求参数、后端解析、持久化/查询、历史缺省值。
不要新增重复导航或已有通用组件。
区分已证实的事实、推断和缺少证据的结论。

如果需求只涉及租户配置，先明确配置仓库和目标租户；不要为了绕过配置问题在平台代码里硬编码某个医院或租户。

阶段三：让 AI 完成最小实现

按刚确认的方案实现，并运行与修改范围匹配的检查。
保留现有字段、绑定、顺序、历史默认行为和工作区其他修改。
遵守 Controller → UseCase → 业务对象的职责划分，复用统一 api 和 Payload。
涉及业务规则时补充能验证行为的测试，覆盖适用的失败和历史兼容场景。
不为通过门禁削弱断言、放宽权限或增加覆盖率排除项。
若需要迁移，生成可评审脚本及影响/回退说明，不直接执行数据库变更。
完成后报告文件、行为变化、执行命令、结果和未验证项。

编码任务可以让 AI 持续完成实现和检查；遇到真正缺失的业务规则再澄清，不必逐行确认。简单文案或布局变更通常做差异检查及已有检查即可，不必为了数量新增测试。

阶段四：验证，区分“运行了”与“建议运行”

请检查本次差异并验证：
1. 先运行受影响模块的测试和静态检查；
2. 按仓库要求完成提交前质量门禁，报告失败的准确位置；
3. 每条命令写明工作目录、实际结果；没执行的标为未执行；
4. 如失败，区分代码问题、已有问题和环境缺失，并给出证据；
5. 单列浏览器、数据库迁移、外部服务和历史数据的待验收场景。
不要把局部测试通过描述为全量通过，也不要把未执行 SQL 描述为已生效。

后端优先指定模块，如 ./gradlew :basics.application:test --tests 'cn.net.keyan.research.basics.application.AboutInfoTest'；前端单次测试用 yarn test --run <测试文件>。命令详见入门文档，不让 AI 凭惯例编造 npm run test:unit 或 Maven 命令。

阶段五：独立看差异并整理交付

请只评审当前任务差异，不直接修复。
重点检查：需求遗漏、字段兼容、跨租户数据、后端鉴权、金额和状态变化、
异步请求覆盖、历史流程实例、迁移影响及测试是否真实验证行为。
发现问题请给文件/位置、触发条件、影响和修复建议。
没有发现问题也请列出尚未覆盖的运行时风险，不要宣称零风险。

AI 自查不能替代同事评审。你需要能解释每一处修改，亲自核对关键业务场景，再按团队流程提交。

3. 实操练习一：读懂“关于”功能（不改代码）

预计 30～60 分钟；产出一页调用链笔记。

先在终端执行：

rg -n 'showAboutDialog|productVersion|configVersion' frontends/research.webui/src/components/header
rg -n 'class AboutController|class GetAboutInfoUseCase|class AboutInfo' modules/basics.*

然后给 AI：

沿“关于”弹窗追踪产品版本和配置版本的来源，只读分析。
请说明 Vue 如何展示、前端怎样加载及处理缺失字段、实际 HTTP 路径、
后端所需权限、租户如何确定、版本如何产生，并定位相关测试。
用真实文件和方法名解释；对比 CLAUDE.md 的示例和当前源码是否一致。
最后给我 3 个问题，用于检查我是否真的读懂，而不是只看了总结。

自检答案要点：

• MainHeader.vue、MainHeaderModel.ts、前端 AboutInfo.ts 构成交互和解析链；load() 当前是实例方法。
• 浏览器请求 /api/about，后端 Controller 映射 /about；代理决定前缀处理。
• GetAboutInfoUseCase 通过 GlobalUserContext.currentTenantId() 获取租户，声明已认证权限。
• 产品版本关联 VersionService 及构建生成的版本文件，配置版本来自租户。
• 源码读懂不等于登录权限或实际数据库内容已验证。

4. 实操练习二：完成一个最小前端需求

练习题，不是当前产品缺陷声明：“关于”弹窗中配置版本缺失、为空字符串或仅有空白时显示“未填写”；有值时保留原值。其他字段、布局、接口和后端数据不变。只在练习分支实现，是否合入由团队决定。

第一步：分析

练习需求：关于弹窗的配置版本缺失、空串或纯空白时显示“未填写”，
有值时保持原值。不改字段 key、接口协议、后端持久化和其他展示。
请检查 MainHeader.vue、MainHeaderModel.ts、AboutInfo.ts 和邻近测试，
建议最小实现位置，并给出测试场景。先不修改。

你应能判断方案是否只改变展示含义。不能为了展示占位文字把“未填写”写入租户配置，更不能改所有字符串转换器的默认值。

第二步：实现与定向验证

按已确认的最小方案实现。
验证缺失字段、空字符串、纯空白及有效版本值四种输入，
有效值如 v2026.10 保持原样，其他关于字段不受影响。
优先复用邻近测试结构，运行定向 Vitest 和受影响文件的检查。
列出实际执行的命令；不要自动提交。

在前端目录验证新测试时，把路径替换为 AI 实际创建的文件：

yarn test --run <实际测试文件路径>
yarn eslint <修改的ts或vue文件路径>
yarn build

尖括号是占位符，不要原样执行。若全量构建失败，记录具体错误及关联文件，不能用定向测试通过替代构建结论。

第三步：浏览器验收与评审

登录指定测试租户打开“关于”，检查真实接口返回值和显示效果。空值场景可以在独立测试中构造或用团队认可的测试数据验证，不改共享租户数据来凑场景。审查差异是否仅包含练习涉及的展示逻辑和测试，没有临时代理修改。

完成标准： 能说明修改位置、空值语义、验证结果，以及有哪些场景只做了自动化测试、没有真实环境操作。

5. 进阶任务的提示词

5.1 动态表单加字段

需求：<业务表单>增加<字段>，角色/状态限制为<规则>。
先定位实际 form key、字段 key、组件 type、meta、部署版本及目标租户。
判断能否复用 dict、person 或已有输入组件，再确定配置归属。
追踪前端 schema → 动态组件注册 → Payload → 保存 → 查询/导出，
核对历史缺失值、编辑回显和只读展示。
如果确实需要新增输入组件，请参考 BaseInputModel 和邻近组件/测试，
不要只生成一个孤立 Vue 文件；给出注册和 schema 用法。

当前环境若安装了 research-input-component 技能，可明确要求使用；新同事机器未必存在这个技能，使用前先确认安装，不把个人技能路径写死在项目代码里。

5.2 调整列表查询

请分析<列表入口>的<筛选/列>需求，先找 query id、租户、接口和持久化查询。
检查 query_definition_conditions/fields/parameters 和已有迁移。
人员姓名从 personnel_persons 获取；精确条件使用等值匹配。
若涉及 process-schedule-selector，检查 QueryProcessSchedule 的映射。
输出查询定义变更、租户影响、历史兼容、验证数据及迁移脚本；不执行 SQL。

5.3 审批、撤回或重启问题

现象：<状态、角色、操作、错误和脱敏业务 ID>。
请从入口追到 UseCase、流程服务、业务处理器、单据持久化和历史记录。
分别检查按钮可见性与后端权限、流程定义版本与业务状态、
新实例与历史实例、重复操作、失败后的事务和资金影响。
默认保持现有流程选择行为，不把所有历史实例自动切到最新流程。
先提交有文件证据的根因分析，区分已确认原因与待运行时验证假设。

5.4 排查异常

这是脱敏后的异常、请求字段形状和复现步骤：<内容>。
请同时追踪失败的消费位置和输入的生产位置，必要时查相关 git 历史。
最小复现应覆盖真实输入形状、空值及历史数据，而不是只改掉报错行。
说明哪些证据能确认根因；没有现场日志或数据库证据时，不断言生产触发原因。
修复后运行相关回归测试，报告仍需外部环境验证的部分。

6. AI 常见错误与纠偏方法

长任务需要换会话时，让 AI 输出交接摘要：目标、已确认规则、已改文件、已跑检查、失败原因、待完成事项。新会话先核对工作区实际状态，不仅凭摘要继续修改。

7. 交付模板

业务目标：
最终行为：
修改文件及理由：
兼容性（字段/默认值/历史数据/租户/权限）：
验证记录（命令 + 工作目录 + 实际结果）：
浏览器验收（环境/租户角色/场景，账号与数据脱敏）：
迁移或配置部署（需要/不需要；是否已经执行）：
未验证项及原因：
回退方式：

入门练习完成后，新同事应该能够不依赖 AI 总结，自己指出请求入口、业务规则、数据来源和测试依据；AI 用来加快定位与实现，业务理解和最终验收仍由开发者负责。