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

2026-02-07 21:54:04 +08:00
@@ -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 编码。