From 7ea25e9d72a31e9a2f1b8b4f0c6b5b048db9fd1d Mon Sep 17 00:00:00 2001 From: shunli Date: Sat, 7 Feb 2026 21:54:04 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BB=BA=E7=AB=8B=20AGENTS=20?= =?UTF-8?q?=E4=B8=8E=20Issue=20CSV=20=E6=89=A7=E8=A1=8C=E5=90=88=E5=90=8C?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 76 ++++++++++++++++++++++++++++++++ issues/2026-02-07-p2-kickoff.csv | 7 +++ issues/README.md | 45 +++++++++++++++++++ 3 files changed, 128 insertions(+) create mode 100644 AGENTS.md create mode 100644 issues/2026-02-07-p2-kickoff.csv create mode 100644 issues/README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b33275cb --- /dev/null +++ b/AGENTS.md @@ -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: | ` + - `Dependencies`: `[]` + - `Tools`: `manual | none` + - `Notes`: `none` + +## Tool usage +- 优先使用可验证工具与官方 SDK（例如 OCR 使用官方 SDK）。 +- 引入新依赖时，在 Issue `Notes` 写明：用途、版本、替代方案、回滚路径。 +- 若工具不可用，记录原因并采用最安全替代方案。 + +## Safety +- 不修复非当前 Issue 范围问题（可记录但不顺手改）。 +- 重大改动（数据迁移/状态机变更）必须写明回滚策略。 +- 不泄露密钥、令牌、隐私数据。 + +## Output style +- 输出保持简洁、结构化。 +- 非 trivial 改动必须包含：变更摘要、验证结果、风险、下一步建议。 +- 涉及文件时提供可点击路径与起始行号。 diff --git a/issues/2026-02-07-p2-kickoff.csv b/issues/2026-02-07-p2-kickoff.csv new file mode 100644 index 00000000..7c5c6f0a --- /dev/null +++ b/issues/2026-02-07-p2-kickoff.csv @@ -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" diff --git a/issues/README.md b/issues/README.md new file mode 100644 index 00000000..c12f7844 --- /dev/null +++ b/issues/README.md @@ -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: | ` +- `Dependencies`: `[]` +- `Notes`: `none` +- `Tools`: `manual | none` + +## Review 与 Regression +- `Review1_Status`：Issue 实现后的单项验证。 +- `Regression_Status`：全部相关变更合并后的回归验证。 + +仅在 `Test_Method` 实测通过后，状态可标记 `DONE`。 + +## CSV 格式约束 +- 字段含英文逗号时，必须用双引号包裹。 +- 字段内多值可用 `|`。 +- UTF-8 编码。