chore: 建立 AGENTS 与 Issue CSV 执行合同基线

2026-02-07 21:54:04 +08:00
@@ -0,0 +1,76 @@
+# AGENTS
+
+> Purpose: 以 Issue CSV 为执行合同，驱动 hyb-oa 的后端与前端迭代交付。
+
+## Role & objective
+- Role: 全栈协作开发代理（Fastify/Prisma + React/Vite）。
+- Objective: 在现有 P0/P1 基础上，按里程碑推进 P2+ 能力，保证“可回归、可审计、可回滚”。
+
+## Constraints (non-negotiable)
+- **编码前先方案**：在编写任何代码前，先给实现方案并等待批准。
+- **需求不清先澄清**：若需求不明确，先通过问答式讨论收敛后再开发。
+- **先有 Issue CSV 再开发**：所有非微小改动必须先在 `issues/*.csv` 落地执行合同。
+- **计划工具约束**：使用 Codex 原生计划（`update_plan`），不得以外部自定义 plan 替代。
+- **只借鉴 CSV 思想**：可借鉴 agent-designer 的 Issue CSV 规范，不迁移其 plan 机制。
+- **优先复用成熟模块**：官方 SDK/成熟开源优先，避免重复造轮子；若自研须说明理由。
+- **中文沟通**：默认使用中文回复；commit message 使用中文并引用 Issue ID。
+
+## Tech & data
+- Backend: `server/`（Node.js + Fastify + Prisma + PostgreSQL）。
+- Frontend: `client/`（React + TypeScript + Vite + Tailwind）。
+- Core regression scripts:
+  - `server/scripts/smoke-test.sh`
+  - `server/scripts/regression-dedup.sh`
+  - `server/scripts/regression-workflow-actions.sh`
+  - `server/scripts/regression-all.sh`
+
+## Project testing strategy
+- Backend syntax/config:
+  - `cd server && npm run prisma:validate`
+  - `cd server && node --check src/routes/reimbursements.js`
+  - `cd server && node --check src/routes/workflow.js`
+- Backend regression:
+  - `cd server && ./scripts/regression-workflow-actions.sh`
+  - `cd server && ./scripts/regression-all.sh`
+- Frontend verification:
+  - `cd client && npm run typecheck`
+  - `cd client && npm run build`
+- 若无自动化条件，必须在 Issue 的 `Test_Method` 中写明可复现手工步骤。
+
+## E2E loop
+E2E loop = plan → issues(csv) → 方案批准 → implement → test → review → commit → regression。
+
+## Plan & issue generation
+- 每轮迭代先创建或更新 `issues/*.csv`，再实施开发。
+- 一次迭代建议拆分为可独立验收的 Issue（A1、A2、...）。
+- 状态推进顺序：`Dev_Status` → `Review1_Status` → `Regression_Status`。
+- 仅当 `Test_Method` 执行通过后，才能将状态置为 `DONE`。
+
+## Issue CSV guidelines
+- Required columns:
+  - `ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes`
+- Status values: `TODO | DOING | DONE`
+- `Dependencies` 强制使用 JSON 数组字符串：
+  - `[]`
+  - `["A1"]`
+  - `["A1","A2"]`
+- 推荐哨兵值：
+  - `Files`: `N/A | external | TBD | module:<name> | <glob>`
+  - `Dependencies`: `[]`
+  - `Tools`: `manual | none`
+  - `Notes`: `none`
+
+## Tool usage
+- 优先使用可验证工具与官方 SDK（例如 OCR 使用官方 SDK）。
+- 引入新依赖时，在 Issue `Notes` 写明：用途、版本、替代方案、回滚路径。
+- 若工具不可用，记录原因并采用最安全替代方案。
+
+## Safety
+- 不修复非当前 Issue 范围问题（可记录但不顺手改）。
+- 重大改动（数据迁移/状态机变更）必须写明回滚策略。
+- 不泄露密钥、令牌、隐私数据。
+
+## Output style
+- 输出保持简洁、结构化。
+- 非 trivial 改动必须包含：变更摘要、验证结果、风险、下一步建议。
+- 涉及文件时提供可点击路径与起始行号。
@@ -0,0 +1,7 @@
+ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
+A1,付款凭证扩展与pay幂等冲突判定,"扩展 /api/reimbursements/:id/pay 可选支付凭证字段，已paid重复同值200，冲突值409","同值重试返回200且idempotent=true；冲突值返回409且details.payment=already_paid_conflict；发票归档逻辑保持事务一致","manual: 运行 regression-workflow-actions pay 场景并校验响应码与字段",manual,TODO,TODO,TODO,"server/src/routes/reimbursements.js | server/prisma/schema.prisma | server/scripts/regression-workflow-actions.sh | server/README.md","[]","保持现有收敛式 updateMany 归档"
+A2,委派有效期与自动回收,"新增委派管理API并支持 valid_from/valid_to 生效窗口，定时回收过期委派","委派仅作用 assignee_id；过期后不可代办；回收写入审计日志","manual: 调用 delegations API + 执行回收job并验证权限变化",manual,TODO,TODO,TODO,"server/src/routes/delegations.js | server/src/utils/delegation.js | server/src/routes/workflow.js | server/src/jobs/delegationRevokeJob.js | server/src/app.js | server/README.md","[""A1""]","优先复用 node-cron，不引入重型队列"
+A5,Sprint1回归护栏前置,"将A1/A2场景并入 workflow-actions 回归并通过总闸门","regression-workflow-actions 与 regression-all 全绿","manual: cd server && ./scripts/regression-workflow-actions.sh && ./scripts/regression-all.sh",manual,TODO,TODO,TODO,"server/scripts/regression-workflow-actions.sh | server/scripts/regression-all.sh | server/README.md","[""A1"",""A2""]","Sprint2开始前必须完成"
+A3,OCR真对接与异步处理,"采用 tencentcloud-sdk-nodejs 接入VAT OCR，上传后异步处理并支持状态查询","upload不阻塞主流程；pending_ocr 异步处理；重复票据标记 ocr_failed 且错误码明确","manual: 上传VAT发票后轮询查询接口，验证状态流转与失败回写",manual,TODO,TODO,TODO,"server/src/routes/invoice-pool.js | server/src/services/ocr/* | server/src/scripts/run-ocr-once.js | server/prisma/schema.prisma | server/README.md","[""A5""]","使用官方 SDK，不手写签名请求"
+A3-LOCK,OCR多实例并发幂等锁,"为 pending_ocr 扫描增加认领锁与超时回收，避免重复处理同一条","多实例并发下同一发票仅一个worker成功认领；处理完成释放锁；失败遵循 attempts 阈值","manual: 并发触发 job:ocr-once，检查同一invoice仅一次有效处理",manual,TODO,TODO,TODO,"server/prisma/schema.prisma | server/src/jobs/ocrWorker.js | server/src/scripts/run-ocr-once.js","[""A3""]","建议 FOR UPDATE SKIP LOCKED + ocr_locked_at 超时"
+A4,审计工作台只读能力,"新增 /api/audit-logs 查询接口与权限 system.audit.view，并补前端只读页","具备分页筛选；权限正确；菜单按权限显示；索引支持查询性能","manual: API 分页筛选验证 + 前端菜单与403验证",manual,TODO,TODO,TODO,"server/src/routes/audit-logs.js | server/src/constants/permissions.js | client/src/router/* | client/src/pages/* | server/README.md","[""A3"",""A3-LOCK""]","索引建议 created_at DESC, actor_id, action"
@@ -0,0 +1,45 @@
+# Issue CSV 规则（hyb-oa）
+
+本项目使用 Issue CSV 作为需求驱动与执行合同。
+
+## 必填列（全部必填）
+- `ID`
+- `Title`
+- `Description`
+- `Acceptance`
+- `Test_Method`
+- `Tools`
+- `Dev_Status`
+- `Review1_Status`
+- `Regression_Status`
+- `Files`
+- `Dependencies`
+- `Notes`
+
+## 状态值
+仅允许：`TODO | DOING | DONE`
+
+## 字段规范
+- `ID`：唯一标识（如 `A1`、`A2`）。
+- `Acceptance`：可判定完成与否。
+- `Test_Method`：必须可复现（命令或明确步骤）。
+- `Tools`：优先写实际工具/SDK；不可自动化则写 `manual`。
+- `Files`：必须给出实际路径范围或哨兵值，不能留空。
+- `Dependencies`：**统一 JSON 数组字符串**（不再使用 `A1|A2`）。
+
+## 哨兵值
+- `Files`: `N/A | external | TBD | module:<name> | <glob>`
+- `Dependencies`: `[]`
+- `Notes`: `none`
+- `Tools`: `manual | none`
+
+## Review 与 Regression
+- `Review1_Status`：Issue 实现后的单项验证。
+- `Regression_Status`：全部相关变更合并后的回归验证。
+
+仅在 `Test_Method` 实测通过后，状态可标记 `DONE`。
+
+## CSV 格式约束
+- 字段含英文逗号时，必须用双引号包裹。
+- 字段内多值可用 `|`。
+- UTF-8 编码。