tanzk
cab6599ee2
用户: 「有的是需求，有的是需求的需求，都需要打上不同的标记」 ## 核心洞察 三类文档（META/REQ/REF）长期混用同一套审查标准 → 用错标准 = 审查失效。 ## 新增规范 docs/standards/文档性质标记规范.md (v1.0) - 三分类定义 + 判定判据（判据是「约束范围」，不是文件名） - ★ 三类规则差异表： | | META | REQ | REF | |审查标准| 能否约束住别人 | 验收标准达成 | 与代码一致 | |变更成本| 高(全仓) | 中(局部) | 低(同步) | |架构锁定| ❌ | ✅ | ❌ | - 三层落地：① 文档头标性质 ② README §六 索引 ③ META 强制类挂 AGENTS ## 全量打标 25/25 META 13 · REQ 5 · REF 7 ## ★ 盘点发现（已修复） - **11 份 META 中曾仅 4 份有强制入口** → 7 份「标记了但约束不住」 - docs/standards/ 目录名误导：18 份混着 4 REF + 3 REQ - 易错点：名为"XX接入规范"但只约束一个集成 → 是 REQ 不是 META ## 强制链补齐（AGENTS.md 绝对禁止 8~11） 新增 4 条，把"待挂"META 接入强制链： - 8. error-code.md 响应格式（成功 {code,data,message} / 错误走 HTTPException） - 9. 数据采集合并去重机制 所有采集通道的去重键 - 10. 投诉渠道口径与对账 渠道口径权威定义（改动影响全部投诉数字） - 11. 数据源接入与缓存加速 缓存铁律（写入后必须失效 pattern） ## 其它 - docs/README.md 新增 §六 文档性质索引（单一事实来源）；修复历史表格粘连缺陷 - AGENTS.md 新增「文档性质纪律（强制）」章 - review-checklist.md 新增「文档性质」检查项（6 条子项） - .github/instructions/doc-class-rationale.instructions.md（applyTo: docs/**） --- ## 附带修复：前端构建/编辑器报错（真实问题） ### ① Vue 3 模板被误报 compileError（根因：仓库根无 ESLint 配置） 现象：`v-model:preset="..."` 被编辑器标 [vue/no-v-model-argument] compileError 实测澄清：vite build / docker build / 命令行 eslint **全部通过** 根因：VS Code ESLint 扩展以**工作区根**为 cwd 启动；根目录无任何 ESLint 配置 → 回退内置默认规则集（含 Vue 2 遗留规则 vue/no-v-model-argument） 修复： - 新增 eslint.config.mjs（根级**桥接**文件，转发 web/eslint.config.js，单一事实来源） - 新增 web/jsconfig.json（声明 vueCompilerOptions.target=3，Vue 语言服务） - 新增 .vscode/settings.json（eslint.useFlatConfig=true 等） - web/eslint.config.js 显式关闭 vue/no-v-model-argument 并注明原因 验证：两个 cwd 均解析出 118 条规则、该规则 = [0]（一致） ### ② el-radio-button label → value 迁移（Element Plus 2.14 弃用） 实测告警：[el-radio] label act as value is about to be deprecated (3.0.0 移除) 项目实际装 element-plus 2.14.4（package.json 写 ^2.6.2）→ 告警真实存在 迁移 28 文件 / 158 处（脚本 scripts/migrate_radio_label_to_value.py，可复现） 验证：浏览器实测 el-radio 弃用告警**归零** ## 验证 - 前端 eslint 0 error（5 warning 均为既有 v-html）· vitest 52 例全绿 - vite build 成功 · docker compose build --no-cache 成功 - 文档性质标记覆盖 25/25 · AGENTS 强制链 9 份 META 关联工单: #71
3.6 KiB
3.6 KiB
任务派工单模板（Prompts）
性质：元需求（META） —— 约束所有派工单的产出形态
生效日期：2026-09-01 适用范围：所有交给 AI 的单项开发任务（对应"AI 协作治理规范" 4.4） 关联文档：AGENTS.md（全局约束）、error-code.md、review-checklist.md、issue-workflow.md（工单驱动工作流，先建工单再派工）
目的：把模糊需求（"帮我写个接口"）转成结构化派工单，减少 AI 猜测，提高一次通过率。 用法：复制下方模板，按任务填写
## 任务之后的每个部分，再交给 Developer 阶段执行。
模板
## 任务
<一句话说明要实现什么功能>
## 输入
- <参数名>: <类型>, 必填/可选, 说明
（示例：order_id: string, 必填, 长度 32）
- <参数名>: enum[...], 可选
## 输出
- 列表字段：<字段1>, <字段2>, ...（含单位，金额必须是"分"）
- 分页字段：total, page, page_size, total_pages
- 统一包装：{code: 0, data: {...}, message: "ok"} （错误走 HTTPException，见 error-code.md）
## 约束
1. 使用 <框架>，路径 <API 路径>
2. 数据库表 <表名>，字段见 <文档>
3. 金额字段必须以"分"为单位存储，接口返回也要是整数（分）
4. 必须支持按 <字段> 倒序
5. 必须检查 <权限>（通过 user_id / 角色关联）
6. 时间字段必须 AT TIME ZONE 'Asia/Shanghai' 转换
## 参考
- 现有类似接口：<docs/api/xxx.md>
- 错误码规范：docs/standards/error-code.md
- 数据时间规范：docs/standards/数据时间字段使用规范.md
## 禁止事项
1. 禁止直接拼接 SQL（须 text() + 绑定参数）
2. 禁止硬编码配置 / 密钥 / 内网 IP
3. 禁止绕过 Alembic 改表结构
4. 禁止在生产代码使用 console.log / print
## 测试要求
- 至少 1 个正向测试 + 2 个边界测试
- 测试文件命名：test_模块名_功能点.py（放 backend/tests/）
填写示例（退款查询接口）
## 任务
实现退款查询接口
## 输入
- order_id: string, 必填, 长度 32
- refund_status: enum['pending', 'approved', 'rejected'], 可选
- page: int, 默认 1, 范围 1-1000
- page_size: int, 默认 20, 范围 10-100
## 输出
- 列表字段：refund_id, order_id, amount(分), status, created_at, updated_at
- 分页字段：total, page, page_size, total_pages
- 统一包装：{code: 0, data: {...}, message: "ok"}
## 约束
1. 使用 FastAPI，路径 /api/v1/refunds
2. 数据库表名 t_refund，已存在，字段见 docs/db/t_refund.md
3. 金额字段必须以"分"为单位存储，接口返回也要是整数（分）
4. 必须支持按 updated_at 倒序
5. 必须检查用户是否有该订单的查询权限（通过 user_id 关联）
6. 时间字段 AT TIME ZONE 'Asia/Shanghai' 转北京时间返回
## 参考
- 现有类似接口：docs/api/order-query.md
- 错误码规范：docs/standards/error-code.md
## 禁止事项
1. 禁止直接拼接 SQL
2. 禁止硬编码表名以外的任何配置
## 测试要求
- 至少 1 个正向 + 2 个边界测试，命名 test_refund_query.py
差 vs 好对比
| 维度 | 差 Prompt | 好 Prompt |
|---|---|---|
| 需求 | "帮我写个退款查询接口" | 明确路径、参数、输出、约束 |
| 输入 | 无 | 参数名/类型/必填/范围全列 |
| 输出 | 无 | 字段、单位、分页、包装格式全列 |
| 约束 | 无 | 表名、金额单位、排序、权限、时区 |
| 参考 | 无 | 指向现有文档，避免重复造轮子 |
| 禁止 | 无 | 明确禁止拼接 SQL、硬编码 |