R121/A1-A6 沉淀Agent交付文档和Skill
这个提交包含在：
@@ -0,0 +1,90 @@
|
||||
# Agent 开发与交付实践
|
||||
|
||||
本文是 hyb-oa 使用 AI agent 协作开发的项目级事实源。目标不是追求复杂编排，而是把高频、易出错、需要验证的流程固定下来，让后续交付可复现、可审计、可回滚。
|
||||
|
||||
## 来源
|
||||
|
||||
- OpenAI Codex Skills: https://developers.openai.com/codex/skills/
|
||||
- OpenAI Agents 文档: https://platform.openai.com/docs/guides/agents
|
||||
- OpenAI Evals 文档: https://platform.openai.com/docs/guides/evals
|
||||
- Anthropic Building Effective Agents: https://www.anthropic.com/engineering/building-effective-agents
|
||||
- Google Agent Development Kit 文档: https://google.github.io/adk-docs/
|
||||
|
||||
## 本项目采用的原则
|
||||
|
||||
### 1. 先简单、后编排
|
||||
|
||||
默认由主 agent 在当前上下文内完成计划、实现、验证和提交。只有当任务能明确拆分、文件写入范围互不冲突、并且并行能实质缩短关键路径时，才使用子 agent。
|
||||
|
||||
不为了“多 agent”而多 agent。复杂编排的收益必须超过上下文丢失、沟通成本和合并风险。
|
||||
|
||||
### 2. Issue CSV 是执行合同
|
||||
|
||||
所有非微小改动先进入 `issues/*.csv`，再实施。Issue 必须写清：
|
||||
|
||||
- 业务流程级影响，不只写文件路径。
|
||||
- 验收标准，不只写“完成开发”。
|
||||
- 可执行验证命令或可复现手工步骤。
|
||||
- 数据迁移、权限、状态机、审批规则的回滚策略。
|
||||
|
||||
### 3. Skill 只沉淀操作流程
|
||||
|
||||
Skill 用于减少重复沟通和降低遗漏风险，适合沉淀：
|
||||
|
||||
- 每轮交付固定流程。
|
||||
- 试运行和验证顺序。
|
||||
- Playwright 视觉巡检要求。
|
||||
- 报销、发票、企业微信等高频业务的检查入口。
|
||||
|
||||
Skill 不复制长文档。详细规则放在 `docs/`，Skill 通过 references 指向需要时再读取。
|
||||
|
||||
### 4. 文档保存事实源
|
||||
|
||||
项目事实源应随仓库版本管理：
|
||||
|
||||
- 设计事实源：`docs/product-design-rules.md`
|
||||
- 报销发票规则：`docs/reimbursement-invoice-rules.md`
|
||||
- 试运行 Runbook：`docs/trialrun-runbook.md`
|
||||
- Agent 交付实践：`docs/agent-development-practices.md`
|
||||
|
||||
AGENTS.md 只放硬约束和入口，不复制长规则。
|
||||
|
||||
### 5. 工具调用必须可验证
|
||||
|
||||
优先使用确定性命令和项目已有脚本：
|
||||
|
||||
- 后端：`npm run prisma:validate`、`node --check`、相关 Vitest、回归脚本。
|
||||
- 前端：`npm run typecheck`、`npm run build`。
|
||||
- 视觉：Playwright PC、mobile、WeCom UA 截图和 DOM 指标。
|
||||
- 文档/Skill：CSV validator、Skill quick_validate、`git diff --check`。
|
||||
|
||||
验证失败时先定位是代码问题、测试桩问题、环境问题还是数据问题。数据库迁移漂移、生产配置、远程服务变更属于高风险操作，必须暂停确认。
|
||||
|
||||
### 6. 视觉和业务同时验收
|
||||
|
||||
本项目是面向 10 人以下国内科技公司的轻 OA，不只看功能能否跑通，也要看：
|
||||
|
||||
- PC 和手机能力是否一致。
|
||||
- 企业微信入口是否保持登录态和移动布局。
|
||||
- 页面是否符合 `www.hyinda.com` 的品牌气质。
|
||||
- 文案是否符合国内 OA 习惯。
|
||||
- 是否出现 PC 表格误入手机、黑色大块导航、按钮样式不一致、文字截断、弹窗自动弹键盘等明显问题。
|
||||
|
||||
### 7. 提交要小批次、中文、可回滚
|
||||
|
||||
一次需求可以有多个 commit，但每个 commit 应该能说明一个清晰主题：
|
||||
|
||||
- 计划和文档。
|
||||
- 后端规则和接口。
|
||||
- 前端体验。
|
||||
- 测试和视觉验证。
|
||||
|
||||
commit message 使用中文并引用 Issue ID，例如 `R121/A1-A3 沉淀交付事实源`。
|
||||
|
||||
## 何时更新本文件
|
||||
|
||||
当连续两轮以上重复提醒同一类 agent 行为，或者同一类遗漏导致返工时，先判断：
|
||||
|
||||
- 是项目事实源：更新 `docs/`。
|
||||
- 是每轮操作流程：更新 `.agents/skills/hyb-oa-delivery/`。
|
||||
- 是不可违反硬规则：更新 `AGENTS.md`。
|
||||
@@ -0,0 +1,116 @@
|
||||
# 报销、发票与附件规则
|
||||
|
||||
本文是 hyb-oa 报销主链路的业务事实源，面向 10 人以下国内科技公司。目标是让员工少选项、财务少核错、管理员少配置。
|
||||
|
||||
## 总原则
|
||||
|
||||
- PC 与手机功能一致，只允许布局和控件形态不同。
|
||||
- 普通员工看到的是“添加发票”“上传附件”“提交审批”，不看到“绑定整单”“发票池”“ERP 同步”等内部概念。
|
||||
- 发票是报销凭证，附件是补充材料，二者不能混用。
|
||||
- 已经报销、他人已报销、重复上传的发票不能加入新的报销单。
|
||||
- 服务端必须强约束，前端只负责友好提示。
|
||||
|
||||
## 发票状态
|
||||
|
||||
发票主要状态：
|
||||
|
||||
- `pending_ocr`：已上传，正在识别。
|
||||
- `available`：可添加到报销单。
|
||||
- `bound`：已添加到报销单。
|
||||
- `ocr_failed`：识别失败，需要重试或人工处理。
|
||||
- `archived`：已归档，不可添加；若 `archived_reason=used_complete`，视为已报销。
|
||||
|
||||
前端展示时使用中文业务表达：
|
||||
|
||||
- `pending_ocr`：识别中。
|
||||
- `available`：可添加。
|
||||
- `bound`：已添加。
|
||||
- `ocr_failed`：识别失败。
|
||||
- `archived`：已归档或已报销。
|
||||
|
||||
## 上传与 OCR
|
||||
|
||||
- PDF 和图片均可上传；若走腾讯 OCR，PDF 可先转图片再识别，具体实现以当前 OCR provider 能力为准。
|
||||
- 上传后页面必须显示明确状态，不应长期停留在“上传中”。
|
||||
- OCR 完成后，添加发票弹窗应自动刷新并尝试添加可用发票。
|
||||
- OCR 失败、重复、已使用、他人已使用都要显示可理解原因。
|
||||
- 刷新按钮必须有明显反馈，不能让用户误以为没点中。
|
||||
|
||||
## 查重规则
|
||||
|
||||
公司级查重优先级：
|
||||
|
||||
- 相同 `file_sha256`。
|
||||
- OCR 后相同 `invoice_code + invoice_number`。
|
||||
- 后续支持数电票号码时，应加入同等优先级的唯一识别字段。
|
||||
|
||||
不可添加场景：
|
||||
|
||||
- 同一公司已有相同可用发票。
|
||||
- 同一公司已有相同发票正在识别。
|
||||
- 同一公司已有相同发票识别失败。
|
||||
- 同一公司已有相同发票被其他人上传。
|
||||
- 同一公司已有相同发票处于 `bound` 或已完成报销归档。
|
||||
|
||||
普通流程不开放“强制重复添加”。管理员例外处理必须保留审计字段和原因。
|
||||
|
||||
## 添加到报销单
|
||||
|
||||
服务端必须校验：
|
||||
|
||||
- 当前用户有发票上传/报销编辑权限。
|
||||
- 发票属于报销单申请人或可被当前角色合法处理。
|
||||
- 发票状态为可添加。
|
||||
- 发票未被其他报销单、差旅单或归档流程占用。
|
||||
- `linkedItemId` 若传入，必须属于当前报销单。
|
||||
|
||||
明细匹配规则：
|
||||
|
||||
- 报销单只有一条明细时，自动添加到该明细。
|
||||
- 多条明细时，优先按发票金额唯一匹配。
|
||||
- 无法唯一匹配但发票金额存在时，自动创建新明细。
|
||||
- 发票金额缺失时，阻断自动创建并提示需要先处理发票信息。
|
||||
|
||||
## 移除与删除
|
||||
|
||||
- 草稿和驳回状态允许移除发票，移除后发票回到可用状态。
|
||||
- 审批中使用撤回，不提供删除。
|
||||
- 已通过、已支付、已归档的报销单不允许普通用户删除。
|
||||
- 删除草稿时，已添加发票应释放为可用，附件随报销单删除。
|
||||
|
||||
## 附件材料
|
||||
|
||||
附件用于支付截图、合同、订单、聊天记录、情况说明等非发票材料。
|
||||
|
||||
规则：
|
||||
|
||||
- 支持 PDF、JPG、PNG、WEBP。
|
||||
- 支持多文件上传。
|
||||
- 不参与发票 OCR。
|
||||
- 不参与发票查重。
|
||||
- 草稿和驳回状态可上传、查看、删除。
|
||||
- 提交后审批人和财务可查看。
|
||||
|
||||
## PC 与手机体验
|
||||
|
||||
PC 端：
|
||||
|
||||
- 适合明细编辑、批量查看、财务复核和台账导出。
|
||||
- 报销详情分区展示：摘要、明细、发票、附件、审批流、预算与审核提示。
|
||||
|
||||
手机/企业微信端：
|
||||
|
||||
- 适合新建、继续编辑草稿、拍照/上传发票、补充附件、提交审批、查状态。
|
||||
- 不显示桌面表格。
|
||||
- 添加发票不默认聚焦搜索框，不自动弹键盘。
|
||||
- 底部操作区紧凑，选中态使用品牌实心色。
|
||||
|
||||
## 自动化验收
|
||||
|
||||
每次改报销/发票/附件至少验证：
|
||||
|
||||
- 后端单测覆盖上传、查重、添加、移除、附件上传/下载/删除。
|
||||
- 前端 `typecheck` 和 `build`。
|
||||
- Playwright PC 报销详情。
|
||||
- Playwright mobile/wecom UA 报销详情。
|
||||
- 视觉检查无 PC 壳、无表格误入、无黑色大块导航、无“绑定整单/不绑定明细/发票池/OCR”等普通用户文案。
|
||||
@@ -0,0 +1,133 @@
|
||||
# 试运行与自动化验证 Runbook
|
||||
|
||||
本文用于 hyb-oa 本地、企业微信和公网试运行。默认策略是：能自动化的先自动化，自动化无法覆盖的才请求人工配合。
|
||||
|
||||
## 入口顺序
|
||||
|
||||
1. 读取 `AGENTS.md`。
|
||||
2. 读取最新 `issues/*.csv`。
|
||||
3. 按任务读取事实源：
|
||||
- 设计：`docs/product-design-rules.md`
|
||||
- 报销发票：`docs/reimbursement-invoice-rules.md`
|
||||
- Agent 交付：`docs/agent-development-practices.md`
|
||||
4. 检查 `git status --short`，保护用户已有改动。
|
||||
|
||||
## 本地验证
|
||||
|
||||
后端基础检查：
|
||||
|
||||
```bash
|
||||
cd server && npm run prisma:validate
|
||||
cd server && node --check src/routes/reimbursements.js
|
||||
cd server && node --check src/routes/workflow.js
|
||||
```
|
||||
|
||||
后端回归：
|
||||
|
||||
```bash
|
||||
cd server && ./scripts/regression-workflow-actions.sh
|
||||
cd server && ./scripts/regression-all.sh
|
||||
```
|
||||
|
||||
前端检查：
|
||||
|
||||
```bash
|
||||
cd client && npm run typecheck
|
||||
cd client && npm run build
|
||||
```
|
||||
|
||||
## Playwright 视觉验证
|
||||
|
||||
页面或交互改动优先用 Playwright 验证：
|
||||
|
||||
- PC viewport: 1440x960。
|
||||
- mobile viewport: 390x844。
|
||||
- 企业微信 UA 使用 iPhone + `wxwork` 标识。
|
||||
- 截图放在 `output/playwright/<issue-id>/`。
|
||||
|
||||
移动端必须检查：
|
||||
|
||||
- 没有桌面表格。
|
||||
- `scrollWidth <= viewportWidth + 2`。
|
||||
- 底部导航高度合理。
|
||||
- 当前选中项不是黑色空心样式。
|
||||
- 弹窗不会默认聚焦搜索框导致键盘弹出。
|
||||
- 无明显文字截断、遮挡、按钮样式不一致。
|
||||
|
||||
## 企业微信验证
|
||||
|
||||
自动化可模拟企业微信 UA，但真实登录态仍以手机企业微信为准。
|
||||
|
||||
需要人工配合的节点：
|
||||
|
||||
- 企业微信后台应用主页、可信域名、回调域名、可见范围配置。
|
||||
- 手机企业微信实际点击应用入口。
|
||||
- 企业微信授权或绑定确认。
|
||||
|
||||
系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查：
|
||||
|
||||
- 回调 code 是否传到后端。
|
||||
- 后端是否拿到 `UserId`。
|
||||
- 本地账号是否绑定了企业微信 userId。
|
||||
- cookie domain、SameSite、Caddy 反代头是否正确。
|
||||
|
||||
## OCR 验证
|
||||
|
||||
先确认当前 OCR provider：
|
||||
|
||||
- `mock` 只用于自动化和本地回归。
|
||||
- 腾讯 OCR 需要真实环境变量和网络。
|
||||
|
||||
发票上传问题排查顺序：
|
||||
|
||||
1. 上传接口是否成功返回 invoice id。
|
||||
2. 发票是否进入 `pending_ocr`。
|
||||
3. OCR job 是否运行。
|
||||
4. OCR provider 是否为腾讯而不是 mock。
|
||||
5. OCR 是否返回结构化字段。
|
||||
6. 查重是否把发票转为不可添加。
|
||||
7. 前端状态查询是否轮询并刷新。
|
||||
8. 报销详情是否自动添加到明细。
|
||||
|
||||
## 公网与部署
|
||||
|
||||
当前公网服务器信息以实际配置为准。已知历史信息：
|
||||
|
||||
- 服务器：`118.89.77.218`
|
||||
- 反代：Caddy
|
||||
- 域名示例：`oa.hyinda.com`
|
||||
|
||||
远端操作原则：
|
||||
|
||||
- 先备份配置和数据。
|
||||
- 先确认远端目录是否为 git 工作树。
|
||||
- 若远端不是 git 工作树，继续使用既有 rsync/部署脚本。
|
||||
- 修改 Caddy、数据库、系统服务前必须先说明风险并等待确认。
|
||||
|
||||
## 数据库迁移漂移
|
||||
|
||||
如果 `npx prisma migrate status` 显示本地迁移历史和数据库迁移表分叉，不要自动修复。
|
||||
|
||||
必须暂停并让用户确认处理策略：
|
||||
|
||||
- 备份当前数据库。
|
||||
- 对齐缺失 migration 文件。
|
||||
- 或重建本地开发库并重新 seed。
|
||||
- 或对生产/试运行库执行受控迁移。
|
||||
|
||||
禁止在未确认时执行：
|
||||
|
||||
- `prisma migrate reset`
|
||||
- 删除迁移记录。
|
||||
- 手工改生产表结构。
|
||||
- 破坏性数据库命令。
|
||||
|
||||
## 收口标准
|
||||
|
||||
每轮交付收口至少包含：
|
||||
|
||||
- Issue CSV 状态真实。
|
||||
- 自动化命令和结果记录在最终回复。
|
||||
- 视觉截图路径记录。
|
||||
- 已知阻塞明确归类为代码、测试、环境、数据或人工配置。
|
||||
- 中文分批 commit。
|
||||
在新工单中引用
屏蔽一个用户