R121/A1-A6 沉淀Agent交付文档和Skill
这个提交包含在：
@@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
name: hyb-oa-delivery
|
||||||
|
description: "Use for hyb-oa project delivery tasks: planning with Issue CSV, implementing Fastify/Prisma or React/Vite changes, refining PC/mobile/WeCom UI, reimbursement/invoice/OCR/attachment work, trial-run troubleshooting, automated/visual verification, and Chinese batch commits."
|
||||||
|
---
|
||||||
|
|
||||||
|
# hyb-oa Delivery
|
||||||
|
|
||||||
|
Use this skill when working in `/home/shunli/Projects/hyb-oa` or when the user asks to continue planning, implementation, trial-run validation, visual QA, reimbursement/invoice improvements, Enterprise WeChat checks, deployment preparation, or project-wide review.
|
||||||
|
|
||||||
|
## Required Reading
|
||||||
|
|
||||||
|
Read only what is relevant:
|
||||||
|
|
||||||
|
- Always read `AGENTS.md` and the newest relevant `issues/*.csv`.
|
||||||
|
- For UI/page work, read `docs/product-design-rules.md` and `references/visual-qa.md`.
|
||||||
|
- For reimbursement, invoice, OCR, duplicate invoice, or attachment work, read `docs/reimbursement-invoice-rules.md` and `references/reimbursement.md`.
|
||||||
|
- For local/WeCom/public trial-run, OCR runtime, Caddy, or DB drift work, read `docs/trialrun-runbook.md` and `references/trialrun.md`.
|
||||||
|
- For how this skill should evolve, read `docs/agent-development-practices.md`.
|
||||||
|
|
||||||
|
## Delivery Loop
|
||||||
|
|
||||||
|
1. Check `git status --short`; do not revert unrelated user changes.
|
||||||
|
2. Identify or create the current Issue CSV before non-trivial work.
|
||||||
|
3. State the implementation approach before editing code; if already approved, proceed.
|
||||||
|
4. Keep changes scoped to the current Issue.
|
||||||
|
5. Prefer existing project patterns and official SDKs.
|
||||||
|
6. Verify with the narrowest relevant automated tests, then expand by risk.
|
||||||
|
7. Use Playwright screenshots or visual metrics for PC/mobile/WeCom UI changes.
|
||||||
|
8. Update Issue CSV statuses only after the stated `Test_Method` passes.
|
||||||
|
9. Commit in Chinese batches with Issue IDs.
|
||||||
|
|
||||||
|
## Default Verification Matrix
|
||||||
|
|
||||||
|
Backend:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server && npm run prisma:validate
|
||||||
|
cd server && node --check src/routes/reimbursements.js
|
||||||
|
cd server && node --check src/routes/workflow.js
|
||||||
|
```
|
||||||
|
|
||||||
|
Frontend:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd client && npm run typecheck
|
||||||
|
cd client && npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
Cross-device UI:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd client && npx playwright test <relevant-spec> --workers=1 --reporter=list
|
||||||
|
```
|
||||||
|
|
||||||
|
Docs/Skill:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py <issue.csv>
|
||||||
|
python3 /home/shunli/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/hyb-oa-delivery
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
## Stop Conditions
|
||||||
|
|
||||||
|
Pause for user confirmation before:
|
||||||
|
|
||||||
|
- Resetting, rebuilding, or destructively modifying a database.
|
||||||
|
- Resolving Prisma migration drift by editing migration history.
|
||||||
|
- Changing production Caddy/systemd/remote deployment state.
|
||||||
|
- Using or exposing real secrets.
|
||||||
|
- Reverting unrelated dirty files.
|
||||||
|
|
||||||
|
## Output Contract
|
||||||
|
|
||||||
|
Final responses should include:
|
||||||
|
|
||||||
|
- What changed.
|
||||||
|
- What was verified, with commands.
|
||||||
|
- What remains blocked and why.
|
||||||
|
- Commit hashes when commits were made.
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
interface:
|
||||||
|
display_name: "hyb-oa交付"
|
||||||
|
short_description: "按hyb-oa执行合同、设计基线和试运行规则推进交付"
|
||||||
|
default_prompt: "继续推进hyb-oa需求，先读取Issue CSV和项目事实源，尽量用自动化与视觉验证。"
|
||||||
@@ -0,0 +1,35 @@
|
|||||||
|
# Reimbursement Reference
|
||||||
|
|
||||||
|
Primary fact source: `docs/reimbursement-invoice-rules.md`.
|
||||||
|
|
||||||
|
## Checks Before Editing
|
||||||
|
|
||||||
|
- PC and mobile must have the same business capability.
|
||||||
|
- Ordinary users should see "添加发票", not "绑定整单", "不绑定明细", "发票池", or "ERP 同步".
|
||||||
|
- Invoice constraints belong on the server; frontend restrictions are only convenience.
|
||||||
|
- Attachments are supporting materials and must not enter invoice OCR or invoice dedup.
|
||||||
|
|
||||||
|
## Backend Hotspots
|
||||||
|
|
||||||
|
- `server/src/routes/invoicePool.js`
|
||||||
|
- `server/src/routes/invoicePool/read.js`
|
||||||
|
- `server/src/jobs/ocrJob.js`
|
||||||
|
- `server/src/services/invoiceGovernance.js`
|
||||||
|
- `server/src/routes/reimbursements.js`
|
||||||
|
- `server/prisma/schema.prisma`
|
||||||
|
|
||||||
|
## Frontend Hotspots
|
||||||
|
|
||||||
|
- `client/src/pages/ReimbursementDetailPage.tsx`
|
||||||
|
- `client/src/pages/MobileReimbursementDetailPage.tsx`
|
||||||
|
- `client/src/pages/InvoicePoolPage.tsx`
|
||||||
|
- `client/src/api/invoicePool.ts`
|
||||||
|
- `client/src/api/reimbursements.ts`
|
||||||
|
|
||||||
|
## Minimum Tests
|
||||||
|
|
||||||
|
- Invoice upload/dedup tests.
|
||||||
|
- OCR job duplicate handling tests.
|
||||||
|
- Reimbursement invoice bind/unbind tests.
|
||||||
|
- Attachment upload/download/delete tests.
|
||||||
|
- PC and mobile Playwright flow.
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
# Trial-Run Reference
|
||||||
|
|
||||||
|
Primary fact source: `docs/trialrun-runbook.md`.
|
||||||
|
|
||||||
|
## Automatic First
|
||||||
|
|
||||||
|
Use automation before asking the user to manually reproduce:
|
||||||
|
|
||||||
|
- Backend unit/regression commands.
|
||||||
|
- Frontend typecheck/build.
|
||||||
|
- Playwright PC/mobile/WeCom UA.
|
||||||
|
- Visual screenshots under `output/playwright/<issue-id>/`.
|
||||||
|
|
||||||
|
## Manual Stop Points
|
||||||
|
|
||||||
|
Ask the user to act or confirm for:
|
||||||
|
|
||||||
|
- Enterprise WeChat admin console changes.
|
||||||
|
- Phone Enterprise WeChat real login/authorization confirmation.
|
||||||
|
- Production Caddy/domain/systemd/database changes.
|
||||||
|
- Prisma migration drift resolution.
|
||||||
|
|
||||||
|
## Common WeCom Checks
|
||||||
|
|
||||||
|
- App homepage URL and callback URL.
|
||||||
|
- Trusted domain verification file.
|
||||||
|
- Visible range includes the user.
|
||||||
|
- OAuth returns `UserId`.
|
||||||
|
- Local OA account is bound to WeCom userId.
|
||||||
|
- Cookies survive Caddy reverse proxy.
|
||||||
|
|
||||||
|
## OCR Checks
|
||||||
|
|
||||||
|
When upload stays in "上传中" or "识别中", inspect:
|
||||||
|
|
||||||
|
1. Upload response.
|
||||||
|
2. Invoice DB status.
|
||||||
|
3. OCR provider mode.
|
||||||
|
4. OCR worker/job status.
|
||||||
|
5. Tencent credentials and network.
|
||||||
|
6. Dedup result.
|
||||||
|
7. Status polling endpoint.
|
||||||
|
8. Frontend cache invalidation.
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
# Visual QA Reference
|
||||||
|
|
||||||
|
Primary fact source: `docs/product-design-rules.md`.
|
||||||
|
|
||||||
|
## Brand Baseline
|
||||||
|
|
||||||
|
Use `www.hyinda.com` as the visual reference:
|
||||||
|
|
||||||
|
- Brand blue around `rgb(0,57,138)`.
|
||||||
|
- White, light gray-blue, slate text.
|
||||||
|
- Clean cards, restrained radius, no black-heavy mobile navigation.
|
||||||
|
- OA pages should feel like a workbench, not a marketing page.
|
||||||
|
|
||||||
|
## PC Checks
|
||||||
|
|
||||||
|
- Header has title, core filters, primary action only.
|
||||||
|
- Tables do not expose UUID as the main business number.
|
||||||
|
- Actions are consistent: view/edit/delete/withdraw use coherent variants.
|
||||||
|
- Destructive actions need confirmation.
|
||||||
|
|
||||||
|
## Mobile/WeCom Checks
|
||||||
|
|
||||||
|
- No desktop sidebar/topbar.
|
||||||
|
- No visible desktop table as primary layout.
|
||||||
|
- Bottom nav is compact and selected state is solid, not thin outline.
|
||||||
|
- Dialogs do not auto-focus search inputs unless it is clearly a search task.
|
||||||
|
- Text does not overflow buttons/cards.
|
||||||
|
- Common flows fit the viewport without incoherent blank/packed regions.
|
||||||
|
|
||||||
|
## Playwright Metrics
|
||||||
|
|
||||||
|
Collect or assert when relevant:
|
||||||
|
|
||||||
|
- `scrollWidth <= viewportWidth + 2`.
|
||||||
|
- visible table count is 0 on mobile workflow pages.
|
||||||
|
- bottom nav height is reasonable.
|
||||||
|
- active nav background is visible and not black/empty outline.
|
||||||
|
- body text excludes banned internal terms.
|
||||||
@@ -14,6 +14,8 @@
|
|||||||
- **只借鉴 CSV 思想**：可借鉴 agent-designer 的 Issue CSV 规范，不迁移其 plan 机制。
|
- **只借鉴 CSV 思想**：可借鉴 agent-designer 的 Issue CSV 规范，不迁移其 plan 机制。
|
||||||
- **优先复用成熟模块**：官方 SDK/成熟开源优先，避免重复造轮子；若自研须说明理由。
|
- **优先复用成熟模块**：官方 SDK/成熟开源优先，避免重复造轮子；若自研须说明理由。
|
||||||
- **中文沟通**：默认使用中文回复；commit message 使用中文并引用 Issue ID。
|
- **中文沟通**：默认使用中文回复；commit message 使用中文并引用 Issue ID。
|
||||||
|
- **项目 Skill 优先**：继续推进、试运行、视觉复核、报销/发票/OCR/附件、企业微信或部署类任务，优先使用 repo-scoped `.agents/skills/hyb-oa-delivery`。
|
||||||
|
- **设计事实源优先**：页面调整必须参考 `docs/product-design-rules.md`，并对齐公司主页 `www.hyinda.com` 的品牌风格。
|
||||||
|
|
||||||
## Tech & data
|
## Tech & data
|
||||||
- Backend: `server/`（Node.js + Fastify + Prisma + PostgreSQL）。
|
- Backend: `server/`（Node.js + Fastify + Prisma + PostgreSQL）。
|
||||||
@@ -65,6 +67,14 @@ E2E loop = plan → issues(csv) → 方案批准 → implement → test → revi
|
|||||||
- 引入新依赖时，在 Issue `Notes` 写明：用途、版本、替代方案、回滚路径。
|
- 引入新依赖时，在 Issue `Notes` 写明：用途、版本、替代方案、回滚路径。
|
||||||
- 若工具不可用，记录原因并采用最安全替代方案。
|
- 若工具不可用，记录原因并采用最安全替代方案。
|
||||||
- 涉及 MCP server 选择、启用边界、Tools 字段或外部工具目录时，必须优先参考 `docs/mcp-tools.md`；若该文件不存在，则视为 MCP 未启用。
|
- 涉及 MCP server 选择、启用边界、Tools 字段或外部工具目录时，必须优先参考 `docs/mcp-tools.md`；若该文件不存在，则视为 MCP 未启用。
|
||||||
|
- 涉及 PC/手机/企业微信页面时，默认补充 Playwright 或视觉验证；若无法自动化，必须在 Issue `Test_Method` 写明人工步骤。
|
||||||
|
|
||||||
|
## Project knowledge sources
|
||||||
|
- Agent 交付实践：`docs/agent-development-practices.md`
|
||||||
|
- 产品与视觉规则：`docs/product-design-rules.md`
|
||||||
|
- 报销、发票、OCR、附件规则：`docs/reimbursement-invoice-rules.md`
|
||||||
|
- 试运行与自动化验证：`docs/trialrun-runbook.md`
|
||||||
|
- 项目交付 Skill：`.agents/skills/hyb-oa-delivery/SKILL.md`
|
||||||
|
|
||||||
## Safety
|
## Safety
|
||||||
- 不修复非当前 Issue 范围问题（可记录但不顺手改）。
|
- 不修复非当前 Issue 范围问题（可记录但不顺手改）。
|
||||||
|
|||||||
@@ -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。
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
|
||||||
|
A1,"Agent开发最佳实践调研沉淀","调研官方/一手资料中关于 agent 开发、Skill、工具调用、验证和工作流编排的最佳实践，并转化为本项目可执行原则。","1) 文档列出本项目采用的原则；2) 只保留可指导 hyb-oa 后续交付的做法；3) 附官方来源链接。","人工阅读 docs/agent-development-practices.md；业务流程：后续 agent 接手需求时可按文档完成计划、实施、验证、提交。","web|manual",DONE,DONE,DONE,"docs/agent-development-practices.md","[]","来源优先使用 OpenAI/Codex/Anthropic 等一手资料；不引入新依赖。"
|
||||||
|
A2,"报销发票业务规则事实源","把多轮试运行中反复确认的国内报销、发票、OCR、附件和重复票治理规则固化为项目事实源。","1) 文档覆盖上传、OCR、重复票、已报销票、明细自动匹配、附件材料；2) 区分普通员工、财务、管理员；3) 明确 PC 与手机能力一致。","人工阅读 docs/reimbursement-invoice-rules.md；业务流程：员工上传发票并添加到报销、重复票被阻断、附件不参与 OCR。","manual",DONE,DONE,DONE,"docs/reimbursement-invoice-rules.md","[]","面向国内小团队报销习惯；后续实现不得与该事实源冲突。"
|
||||||
|
A3,"试运行与自动化验证Runbook","沉淀本地/企业微信/公网试运行、Caddy、OCR、Playwright视觉验证和数据库迁移漂移处理步骤。","1) Runbook 写明自动化优先顺序；2) 写明需要用户手动配合的节点；3) 写明 DB 迁移漂移时必须暂停确认。","人工阅读 docs/trialrun-runbook.md；业务流程：本地试运行、企业微信进入、上传发票、视觉巡检、部署 smoke 均有可复现入口。","manual|playwright|bash",DONE,DONE,DONE,"docs/trialrun-runbook.md","[]","不自动修复数据库或生产配置；高风险操作先确认。"
|
||||||
|
A4,"创建hyb-oa交付Skill","创建 repo-scoped hyb-oa-delivery Skill，把 Issue CSV、设计基线、报销规则、试运行验证和中文分批提交流程沉淀为可触发工作流。","1) .agents/skills/hyb-oa-delivery/SKILL.md 可被发现；2) Skill body 简洁；3) 详细内容放 references；4) 通过 quick_validate。","命令：python3 /home/shunli/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/hyb-oa-delivery；业务流程：后续输入继续推进/自动化测试/审查项目时可触发该 Skill。","skill-creator|python",DONE,DONE,DONE,".agents/skills/hyb-oa-delivery/**","[""A1"",""A2"",""A3""]","repo-scoped skill 便于其他电脑和远程环境随仓库同步；不存放密钥；本机 quick_validate 通过时使用 /tmp 临时 venv 提供 PyYAML。"
|
||||||
|
A5,"AGENTS入口规则精简更新","在 AGENTS.md 中补充知识源读取顺序、设计基线、视觉验证和 Skill 使用边界，避免后续重复口头提醒。","1) AGENTS.md 只新增硬规则和入口，不复制长业务规则；2) 指向 docs 与 Skill；3) 不破坏既有 E2E loop。","人工阅读 AGENTS.md；业务流程：agent 接到 PC/手机/企业微信页面任务时先读设计规则和相关事实源。","manual",DONE,DONE,DONE,"AGENTS.md","[""A4""]","保持 AGENTS 简短，详细规则留在 docs 和 Skill references。"
|
||||||
|
A6,"知识沉淀验证与中文提交","校验 Issue CSV、Skill 元数据、文档链接和工作区状态，并按中文 commit 提交本批次。","1) Issue CSV 校验通过；2) Skill quick_validate 通过；3) 文档可读；4) git diff --check 通过；5) 中文 commit 引用 R121/Ax。","命令：validate Issue CSV、quick_validate Skill、git diff --check；业务流程：后续 agent 可直接复用本批次沉淀。","python|git",DONE,DONE,DONE,"issues|docs|.agents|AGENTS.md","[""A1"",""A2"",""A3"",""A4"",""A5""]","不提交既有历史脏 artifacts。"
|
||||||
|
在新工单中引用
屏蔽一个用户