R121/A1-A6 沉淀Agent交付文档和Skill

2026-05-08 10:38:44 +08:00
@@ -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.