hyb-oa/.agents/skills/hyb-oa-delivery/SKILL.md

name, description

name	description
hyb-oa-delivery	Use for hyb-oa project delivery tasks: natural-language triage, 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.
• After R5, first check the main R5/R6 contract status before planning trial-run or follow-up work; R5 must remain the completed gate and R6 must have its own Issue CSV before expanding scope.
• For UI/page work, PC/mobile/WeCom experience, approval UX, or domestic OA benchmarking, read docs/产品设计规则.md and references/visual-qa.md. DG8 makes Feishu workbench/approval the single main UI/layout reference, with Hyinda branding and project rules taking priority. DG9 adds the A/B/C page layering and shared workbench/mobile samples; choose the DG9 sample before designing or coding a page. Other products are only function/process/control references. Mobile page work must treat docs/产品设计规则.md as the source of truth for the unified mobile shell, icon grid, card lists, deep Push pages, sticky actions, safe-area, and cross-viewport matrix. 移动页必须先对齐该设计事实源，再进入实现或验证。
• For approval workflow, roles, self-approval, notification, deeplink, reminder, or escalation work, read docs/需求-统一审批中心规约.md.
• For HR lifecycle, employee onboarding/offboarding, Enterprise WeChat directory sync, account disablement, or Enterprise WeChat API work, read docs/需求-企业微信基础设施规约.md, docs/企微API能力目录.md, docs/管理员手册.md, and the latest HCLT/HRWD/WAPI/WRRA Issue CSV evidence first.
• For any Enterprise WeChat capability, Secret, callback, approval, check-in, HR assistant, or contact-directory task, read docs/企微API能力目录.md before planning or coding. WAPI fixes the current Secret matrix: contacts use WECOM_CONTACT_SECRET; workbench/OAuth/messages/HR assistant/roster/check-in/approval use WECOM_AGENT_SECRET; WECOM_CHECKIN_SECRET is only an explicit check-in override; WECOM_HR_ASSISTANT_SECRET is historical compatibility and not a default. Do not write runtime code that tries multiple Secrets to guess the correct one.
• For Enterprise WeChat-first HR/attendance runtime migration, read docs/企微优先开发路线图.md before planning or coding. WDRG makes the roadmap authoritative for stage order; WAPI adds the runtime-first stage before deep mirror work; WRRA states that WOUA PASS_WITH_FINDINGS does not clear deep mirror work; WOUA-FIX has now soft-archived the 7 OA active test accounts missing in WeCom, fixed the T0000 seed reactivation behavior, transferred the SMOKE201 test-manager side effects, and rerun WOUA with oaActiveMissingInWecom=0. WCPC has rerun the capability POC with an existing active test account and reached GO_TO_HR_MASTER_SYNC; WHMS/WHMSLIVE has implemented, deployed, and publicly verified wecom_hr_master_sync_v1, with the production flag restored to force_off and production real-employee batch apply not approved. WMSG1 proves real app-message delivery and Deeplink return only; WAPC1 fixes the approval configuration preparation checklist before mirror work; WAPC2 adds the leave/missed-punch approval template and low-risk sp_no read-only POC runner. WPROC1/WPROC2 fixed the engineering process gate; WEGOV1 is the route gate, and WACP3R has now rerun the compensation-pull POC by automatically discovering OA-POC leave/missed-punch template IDs from SMOKE002 creator. Public report /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json is PASS_WITH_FINDINGS: compensation pull and detail read work, with finding that callback evidence files are not persisted across deploys. WREAD1/WREAD1F have now completed real-device readability confirmation for leave and missed-punch: public report /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json is PASS_READABLE; the user confirmed cards/lists/details are readable, reject has second confirmation, and approve is single-tap. WADM1 has completed the self-owned archive/mirror data-model design. WARCH1 has implemented and publicly verified the minimum leave/missed-punch archive slice: Prisma archive/callback/compensation/finding tables, callback DB persistence with non-200 retry on DB failure, compensation persistence behind --persist-to-db + WECOM_ARCHIVE_WRITE=1, and offline npm run check:wecom-approval-archive; public reports /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json and /app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json are PASS_WITH_FINDINGS, with 2 archived histories readable and only a historical pre-WARCH1 callback gap finding. WARCH2 has now added the formal OA read-only archive API/page locally: /api/wecom/approval-archive, /wecom-approval-archive, and /mobile/wecom-approval-archive read OA DB only, do not call WeCom API or read WeCom Secrets, and enforce self/direct-report/HR-admin visibility with unmapped applicant records HR/admin-only. It still does not implement full mirror, outing/overtime, emergency mode, writeback, or RuleOps. WPROC2 adds the executable process gate: before WAPC2F or other high-risk WeCom work, run node scripts/qa/check-process-contract.mjs --baseline and the issue-specific profile check to enforce DoR/DoD, fixed Secret source, non-self approval, live write switches, missing-config classification, and redaction boundaries. Do not start wecom_attendance_approval_mirror_v1, oa_hr_emergency_mode_v1, wecom_recovery_writeback_v1, or wecom_ruleops_v1 without the next stage's own Issue CSV and acceptance gates.
• WAPC2FLIVE supersedes the WAPC2F dry-run gap for OA-POC samples: after user approval, the runner was corrected to the official template_name + property controls create-template payload, deployed with SYNC_ENV=0, and the public live report /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json reached PASS_FIXTURE_CREATED; leave/missed-punch OA-POC templates and low-risk test approvals were created and retained for audit, with WAPC2 auto-rerun PASS_APPROVAL_POC. WCBK1 has added and deployed read-only GET/POST /api/wecom/approval/callback, wecomCallbackCrypto, npm run check:wecom-approval-callback-poc, and the wecom-callback process gate. After remote callback config was set, public report /app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T083422Z/summary.json reached PASS_CALLBACK_URL_VERIFIED; after SMOKE101 approved an existing OA-POC missed-punch test approval, /app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T092648Z/summary.json reached PASS_CALLBACK_EVENT_CONFIRMED with one redacted event. WACP3/WACP3R has added and deployed npm run check:wecom-approval-compensation-poc, POST /cgi-bin/oa/getapprovalinfo read support, and automatic template discovery by SMOKE002 creator; WREAD1 deploy reran WACP3R at /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T125515Z/summary.json and then generated /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T125532Z/summary.json as PAUSED_MANUAL_CONFIRMATION. WREAD1F then fixed duplicate OA-POC template names by adding timestamp uniqueness and created fresh leave/missed-punch approvals at /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T131958Z/summary.json; final WREAD1 manual report /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json is PASS_READABLE. This clears leave/missed-punch readability only; mirror data model, minimum archive, emergency mode, writeback, RuleOps, and outing/overtime sample decisions remain later gates.
• WEGOV1 changes the current WeCom route to "Enterprise WeChat owns mature HR/attendance flows; OA stores self-owned history, audit, entry, messages, and emergency fallback." Treat four domains explicitly: WeCom-owned domain is check-in, leave, missed punch, outing, overtime, leave balance, and HR assistant; OA-owned domain remains reimbursement, procurement, contracts, projects, payments, invoices, bank receipts, sensitive attachments, and operating audit; OA archive domain stores WeCom business history, full external keys, and necessary snapshots; OA emergency domain is manually enabled only when WeCom is unavailable. Do not assume a full isolated WeCom sandbox; use the controlled test domain SMOKE002 -> SMOKE101, OA-POC templates, low-risk approvals, synthetic tests, public live runners, and limited real-device confirmation. WARCH1 now supplies the minimum leave/missed-punch archive implementation and WARCH2 supplies the formal read-only history query surface; do not start deep mirror until WARCH2 public verification is accepted and the mirror stage has its own contract.
• For reimbursement, invoice, OCR, duplicate invoice, or attachment work, read docs/报销发票附件规则.md and references/reimbursement.md.
• For local/WeCom/public trial-run, OCR runtime, Caddy, or DB drift work, read docs/试运行与自动化验证手册.md and references/trialrun.md.
• For how this skill should evolve, read docs/Agent开发交付实践.md.

Natural-Language Triage

Users may assign work with a plain paragraph. Before asking follow-up questions, classify the request into defect, feature, acceptance feedback, plan, review, QA, deployment, design, or product-flow optimization.

Default behavior:

1. Extract intent, target surface, constraints, approval state, and next action.
2. Check existing assets before declaring a blocker: issues/, docs/, artifacts/, output/, scripts, Playwright tests, runbooks, and prior trial-run evidence.
3. Ask only when required by AGENTS.md or safety: missing approval for non-trivial coding, destructive data work, production config, secrets/accounts, conflicting goals, or unclear high-risk acceptance.
4. Treat a plain "确认" as approval for the immediately preceding explicit plan or Issue CSV, unless multiple candidates exist.
5. If the user asks whether a problem is real, verify first with automation, code inspection, public checks, or visual evidence before proposing broad changes.

Delivery Loop

1. Check git status --short; do not revert unrelated user changes.
2. Identify the current active continuous Issue CSV before non-trivial work. Same-type trial-run feedback, real-device feedback, single-surface defects, and small follow-up fixes must append rows or update Notes in the active flow instead of creating one-off CSVs. Create a new CSV only when no active same-type flow exists, the current flow is closed, the change crosses risk/business domains, or the user explicitly asks for a new contract; if creating one, state why the active flows cannot carry it. After R5, distinguish R6 preparation from actual trial-run execution.
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, official SDKs, and the main UI/layout hierarchy in docs/产品设计规则.md; for page work, classify the page into DG9 A/B/C layering and reuse the matching workbench/mobile sample before adding local layout code. Do not mix multiple competitor visual systems or copy competitor flows/text directly.
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. New or changed mobile pages must join the unified responsive system and the 320/360/375/390/393/414/430px 统一视觉矩阵 rather than adding page-specific layout fixes.
8. Dedicated /mobile pages must use the shared mobile slot/card/list/sticky-action system from docs/产品设计规则.md: fixed icon/avatar/status slots, minmax(0, 1fr) copy slots, mobile-card/mobile list cards, mobile-field-row, mobile tokens, and no desktop card-std p-4/p-5/p-6 as a mobile main container.
9. Mobile homepage, approval, notification, and business cards must follow the display dedupe rules in docs/产品设计规则.md: one pending/progress summary per page, notifications as event stream with direct target links, bottom badges as counts only, and one visible business identifier/status per card or row.
10. Update Issue CSV statuses only after the stated Test_Method passes.
11. Commit in Chinese batches with Issue IDs.
12. 面向用户可测试的改动，最终必须明确“是否已部署”。只有部署与公网检查通过后，才能告知用户可以去企业微信或公网试运行环境测试。

Default Verification Matrix

Backend:

cd server && npm run prisma:validate
cd server && node --check src/routes/reimbursements.js
cd server && node --check src/routes/workflow.js

Frontend:

cd client && npm run typecheck
cd client && npm run build

Cross-device UI:

cd client && npx playwright test <relevant-spec> --workers=1 --reporter=list

Docs/Skill:

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.
• 面向用户可测改动的部署状态：commit hash、公网 URL、/ready、公网前端资源/文案检查，以及用户现在是否可以测试。
• What remains blocked and why.
• Commit hashes when commits were made.

R6 and Trial-Run Defaults

• R6 can start only from a new Issue CSV that fixes users, roles, time window, rollback contact, issue log, and daily closeout rhythm.
• R6 scope defaults to reimbursement, leave, procurement, approval, Enterprise WeChat entry/notification, finance payment/export.
• Do not expand to budget, ERP, AI, full travel, or complex BPM during R6; record those as follow-up Issues.
• Enterprise WeChat personal app message is the formal approval notification channel after R5; mock and group bots are not acceptance evidence for R6 business notification.
• After WAPI, ERP is not a future OA integration target. HR/attendance employee daily approvals (leave, missed punch, outing, overtime) should reuse mature Enterprise WeChat capabilities first, while OA provides self-owned archive, domain-based mirror, manual takeover, recovery writeback, finance closeout, and audit. Reimbursement, payment batches, AP, accounting handoff, procurement, expenses, contracts, projects, sensitive attachments, invoices, bank receipts, and accounting handoff materials remain OA-primary unless a later Issue changes that domain explicitly. OA-primary approvals may send Enterprise WeChat personal-app notifications, but messages must contain only dehydrated title/type/no/status/deeplink; do not upload procurement forms, contract bodies, quotes, supplier files, invoices, bank receipts, or accounting materials to WeCom native approvals or WeCom attachments. Before runtime migration, read docs/企微API能力目录.md and docs/企微优先开发路线图.md, run or check WECOM-CAPABILITY-POC-V1/WCPC, and classify each capability as CAN_REUSE_NOW, NEEDS_CONFIG, NEEDS_API_POC, KEEP_OA_PRIMARY, or NOT_SUPPORTED_BY_API; missing Secret, callback, template, trusted IP, visible scope, or API permission must be recorded as SKIP/BLOCKED_BY_EXTERNAL_CONFIG, not PASS. Current WAPI rule: contacts read with WECOM_CONTACT_SECRET and POST /cgi-bin/user/list_id; HR assistant/roster uses WECOM_AGENT_SECRET and POST /cgi-bin/hr/get_staff_info; check-in defaults to WECOM_AGENT_SECRET with optional explicit WECOM_CHECKIN_SECRET; approval template/detail reads use WECOM_AGENT_SECRET; no runtime Secret guessing. WARCH1 now implements the minimum leave/missed-punch archive slice: callback events and compensation details can persist to OA DB, report/log output stays redacted, and npm run check:wecom-approval-archive -- --offline --format=json proves saved history can be read without WeCom API. WARCH2 now exposes that saved history through OA read-only API and PC/mobile pages with redacted output and HR/admin-only access for unmapped applicant records. Attendance/approval deep mirror, emergency mode, recovery writeback, RuleOps, outing/overtime samples, and HR write APIs remain later-stage gaps. Do not skip stage order: WECOM-CAPABILITY-POC-V1/WCPC -> wecom_hr_master_sync_v1/WHMSLIVE -> runtime_first_wecom_enablement/WAPI+WOUA rerun -> WOUA-FIX / WECOM-RUNTIME-READY-V1 -> WAPC1 审批配置准备 -> WAPC2 请假/补卡只读 POC -> WAPC2F 自动生成 POC 样件 -> WAPC2FLIVE live 创建与 WAPC2 自动复跑 -> WCBK1 回调只读 POC -> WEGOV1 企微主办治理与自建留存路线修正 -> WACP3/WACP3R 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> WARCH2 正式只读历史查询 -> wecom_attendance_approval_mirror_v1 -> oa_hr_emergency_mode_v1 -> wecom_recovery_writeback_v1 -> wecom_ruleops_v1. UI and API work must distinguish OA 主办, 企微主办, OA 自建留存, and OA 应急接管. OA-driven Enterprise WeChat directory create/update/disable is live verified; for later HR/WeCom directory issues, first check configuration, permission, department, and data-specific causes before treating the capability as unfinished.
• WMSG1 has verified real Enterprise WeChat personal-app delivery and Deeplink return: report /app/artifacts/qa-flow/wecom-runtime-ready-20260518T234431Z/summary.json has checks.message.status=OK, errcode=0, and recipientCount=1; the user confirmed receiving "OA 运行就绪检查" and opening the OA notifications page from the message. This only clears message/deeplink runtime evidence; template/detail, callback evidence, compensation pull, readability, self-owned archive model design, and minimum archive implementation are covered by WAPC2FLIVE/WCBK1/WACP3R/WREAD1/WADM1/WARCH1 in the OA-POC leave/missed-punch scope, while deep mirror work remains a separate later gate.
• WAPC1 has fixed the WeCom approval configuration preparation gate: first templates are leave, missed punch, outing, and overtime; each needs template ID, scope, fields, approver rules, visible scope, and self-built app permission; low-risk test sp_no must not contain procurement, contract, reimbursement, invoice, bank receipt, sensitive attachment, or real sensitive business material; callback URL/Token/EncodingAESKey are deployment-only values and must not be written to repo docs or Issue CSV. Do not implement real approval callback handling, deep mirror, emergency mode, recovery writeback, or RuleOps until a later approved Issue covers the POC or implementation.
• WAPC2 has added the WeCom approval template/detail read-only POC runner for leave and missed punch. Use npm run check:wecom-approval-poc; pass template IDs with --template=leave:<id> / --template=missed_punch:<id> and low-risk test approval numbers with --sp-no=leave:<sp_no> / --sp-no=missed_punch:<sp_no>. The runner must use only WECOM_AGENT_SECRET, redact full template IDs and sp_no, and never output form values, attachments, comments, full userid, token, Secret, or raw payload.
• WPROC1 fixes the WeCom approval engineering process. Future WeCom work must satisfy route gate, capability gate, and implementation gate; use automatic runners before asking the user to do manual work. WPROC2 makes this executable through node scripts/qa/check-process-contract.mjs --baseline plus issue-specific profiles such as --profile wecom-approval-fixture; run it before WAPC2F and later high-risk WeCom contracts. Manual work is limited to write approval, secrets/callback config, WeCom backend settings that cannot be API-driven, real-device confirmation, and risk decisions. High-risk stages require POC before implementation: callback signature/decryption/idempotency, compensation pull, mirror data model, then mirror implementation.
• WAPC2F has added the WeCom approval fixture dry-run runner. Use npm run check:wecom-approval-fixtures; it defaults to applicant SMOKE002, approver SMOKE101, fixed WECOM_AGENT_SECRET, minimal generic OA-POC leave/missed-punch template payloads, and no write token or WeCom writes. Real fixture creation requires --live --create-templates --submit-test-approvals plus one-process WECOM_APPROVAL_FIXTURE_WRITE=1 and explicit user approval. The public dry-run report is /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T045001Z/summary.json with PASS_FIXTURE_DRY_RUN_READY.
• WAPC2FLIVE has executed that approved live path once after fixing the template payload shape; current public evidence is /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json, PASS_FIXTURE_CREATED, checks.autoRerun.status=OK, and PASS_APPROVAL_POC. Do not create more approval fixtures without a new Issue CSV and explicit approval.
• WCBK1 has implemented and verified the WeCom approval callback read-only POC path. Use npm run check:wecom-approval-callback-poc; default synthetic mode verifies local encrypted callback samples, while --live checks the configured public callback URL and redacted event evidence. The route uses only WECOM_APPROVAL_CALLBACK_URL, WECOM_CALLBACK_TOKEN, WECOM_CALLBACK_ENCODING_AES_KEY, and WECOM_CORP_ID; do not use contact Secret or legacy callback env names. Current public status is PASS_CALLBACK_EVENT_CONFIRMED: URL verification passed, and one existing OA-POC missed-punch approval handled by SMOKE101 produced a redacted approval-status event. Do not store raw XML, ciphertext, full sp_no, full userid, Token, EncodingAESKey, form values, attachments, comments, or raw payload.
• Approval-chain correctness can be proven by PC or automation, while Enterprise WeChat validates entry, binding,免登录, notification, deeplink, and mobile layout.
• If real-device mobile validation is paused after automation passes, record the gate as PAUSED; do not close RS6/UI6/R6 mobile blockers until representative real-device confirmation is recorded.
• Role-specific pages should use one shared OA/mobile framework and tailor summaries, entries, actions, and sensitive fields by role. Do not create unrelated UI systems for employee, approver, finance, admin, or CEO views.
• After MUD6, R6-ISSUE-001 is treated as resolved based on representative real-device confirmation; future mobile regressions should be recorded as new Issues rather than reopening the old WCM6/MME6 gate unless the same production behavior returns.
• After AP6, approval reminder, overdue reminder, and workflow productivity summary are current product facts, not open planning items. Reuse POST /api/workflow/tasks/:taskId/remind, GET /api/workflow/tasks/summary, job:workflow-overdue-reminders, existing workflow history, audit logs, notifications, and WeCom personal app delivery semantics. Do not add a parallel reminder channel, change approval status from reminders, or expand into complex BPM/SLA escalation without a new Issue.
• After DG7/MRF7, mobile approval is an "approval and progress" entry: employees may use it for submitted-item progress, while approvers use it for assigned tasks. Do not reintroduce disabled approval tabs for ordinary employees, duplicated home pending lists, or notification cards that only bounce users back to the notification center when a business target exists.
• After RI6, LP6, ME6 automation, QG6, MIF7/MIF7T, MIF7TD, R7/OPS7/DOC7 draft materials, R7EP automatic gates, and OPS8 remote read-only checks, treat ME6-3 as closed by representative iPhone 12, iPhone 14, and Redmi K60 Enterprise WeChat feedback. R7EP may conclude that the project can enter R7E human confirmation, but R7E-* true execution rows must stay TODO until the user confirms participants, roles, window, rollback contact, issue owner, daily closeout, and pause/rollback decision maker. Do not start real R7 from documentation or automation gates alone; future mobile or real-device regressions must be recorded as new Issues such as UX8/R7E follow-ups.
• After DCL7, document governance must start from docs/文档索引.md and docs/文档事实源状态矩阵.md. Use Chinese-first current docs. Confirmed obsolete docs may be physically removed from the current tree and restored from git history when needed; do not create docs/archive/ just to move clutter. Do not rewrite old Issue CSV snapshots when cleaning current docs.