1

T-203

ila edited this page 2026-08-07 16:36:26 +08:00

Table of Contents

• 问题 / 背景
• 关联需求与交互
• 已定合约
• 方案
• 验收要点
• 边界
• 执行记录
• 2026-07-26：任务开始
• 2026-07-26：合约和实现
• 2026-07-26：自动验证
• 2026-07-26：隐私与收尾

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-203.md · commit afc651f75a3a

---

id: T-203 title: 实现任务创建 API 与管理 Web phase: 2 deps:

• T-201
• T-202 status: DONE created: 2026-07-26 context_ref: 2b265c9 work_branch: main write_paths:
• backend-api/**
• init.ps1
• init.sh
• docs/00-ai-start-here.md
• docs/02-requirements.md
• docs/03-tech-stack.md
• docs/04-architecture.md
• docs/05-coding-rules.md
• docs/07-user-stories.md
• docs/08-interaction-checklist.md
• docs/api.md
• docs/current-state.md
• docs/design/admin-task-create.html
• docs/design/admin-task-detail.html
• docs/design/android-task-preview.html
• docs/design/android-candidate-confirm.html
• docs/tasks/T-203.md
• progress.md

---

问题 / 背景

T-201 只有健康检查、SQLite 和 migration 骨架，T-202 只确认了页面信息结构。当前还 不能从管理端安全上传参考图、创建 PENDING 任务、查看真实列表/详情或取消待领取 任务，因此 T-205 的原子领取没有可消费的数据。

审计还发现正式合约存在四个会阻断后续 App 接入的问题：

• 现有 Android ProbeTask 强制标题和 SKU 非空，但任务创建 API/数据表遗漏 SKU。
• 已确认 Web 使用“最高总预算”，部分 Android 原型误写成每件预算。
• API/原型允许 JPEG/PNG/WebP，但 Android 需求提取当前只接受 JPEG。
• 管理会话属于 T-204，T-203 不能伪造登录或永久开放匿名管理接口。

关联需求与交互

• 功能：F-001、F-002，以及 F-007 的最小可见错误。
• 用户故事：US-001、US-002。
• 交互：IX-002、IX-003；登录 IX-001 留给 T-204。
• 页面：/tasks、/tasks/new、/tasks/{id}。
• API：资产上传、任务创建/列表/详情、待领取任务取消。

已定合约

1. 标题和 SKU 必填；描述可空。标题最多 120 个 Unicode 字符且不超过 2048 个 UTF-8 字节，SKU 不超过 512 个 UTF-8 字节，描述不超过 8192 个 UTF-8 字节。
2. max_budget 表示当前任务全部数量的最高商品总预算，币种 CNY，不含无法确认的 运费或优惠；数据库用整数分保存，API 固定输出两位小数字符串。
3. 参考图上传接受可解码 JPEG/PNG/WebP，原始请求最多 20 MiB、最长边最多 10000 px、总像素最多 25 MP；后端统一缩放到最长边不超过 2048 px、白底合成并 编码为匿名 JPEG。响应的媒体类型、大小和 SHA-256 都指向规范化结果。
4. SKU、数量和总预算属于不可变原始事实，任何派生结果都不能覆盖。
5. 列表增加 q，匹配任务 ID、来源引用、标题或 SKU；分页固定按 created_at DESC, id DESC，cursor 同时包含两个字段。
6. T-203 只提前实现事务化 PENDING -> CANCELED；其他状态取消返回冲突，完整取消 请求和状态机属于 T-205。
7. T-204 前，管理 Web/API 业务路由只接受 loopback 来源；Web 写操作还必须携带 SameSite Cookie 与表单字段匹配的随机双提交 CSRF token，API 创建/上传必须使用 JSON 或 multipart 与自定义幂等头。/login 不提供假实现，局域网部署仍被明确 阻塞。
8. 创建、上传均按调用主体、操作和 Idempotency-Key 幂等；同 key 同请求返回原 资源，同 key 不同请求返回 409。

方案

1. 增加 assets、purchase_tasks、task_events 和 idempotency_records migration， 包含外键、CHECK、唯一约束和 rollback。
2. 建立 domain/usecase/repository/sqlite 分层；handler 和模板不得直接执行 SQL。
3. 建立受控文件存储与图片规范化器，随机相对路径、同目录临时文件原子改名，失败时 清理；数据库和响应永不暴露绝对路径。
4. 实现 JSON/multipart API 和稳定错误映射，保持无默认 CORS、request ID 与 recovery 安全约束。
5. 用 html/template、embed、原生 CSS/JS 实现列表、新建和详情；真实数据为空时 显示空状态，不把原型假数据写入数据库。
6. Web 表单无 JS 也可完成，使用 PRG 303；JS 只负责图片预览、防重复、离开提醒 和取消确认。

验收要点

• migration 可 up/down/up，约束和外键有效，启动前 migration 门禁明确。
• JPEG/PNG/WebP 被真实解码并规范化为 JPEG；伪 MIME、损坏、超限和像素炸弹拒绝。
• 合法任务创建为唯一 PENDING，原始 title/SKU/quantity/budget/image 不可变。
• 上传和创建幂等；同 key 不同请求冲突，并发重试不产生重复资源。
• 列表筛选、搜索、稳定 cursor 和详情返回真实数据，404 不泄露内部信息。
• 只有 PENDING 可立即取消；终态或不支持状态返回稳定冲突。
• Web 覆盖空列表、创建字段错误、图片错误、成功跳转、详情和取消二次确认。
• 非 loopback 业务请求、缺失/错误 CSRF、错误 Content-Type 被拒绝。
• HTML 自动转义，日志/响应不含 Cookie、文件绝对路径、私有样本或请求正文。
• Go test/race/vet/gofmt、迁移 smoke、真实 HTTP/Web smoke 和 Playwright 通过。

边界

• 不实现管理登录、Cookie 会话、用户表/密码哈希或设备鉴权；属于 T-204。
• 不实现 claim、租约、执行状态机、候选、执行证据或 App HTTP TaskSource。
• 不开放非 loopback 管理使用；T-204 完成前不能部署到局域网供其他用户访问。
• 不实现对象存储、ORM、SPA、WebSocket、推送或自动下单。
• 不提交运行时数据库、上传文件、密钥或真实订单/店铺/商品数据。

执行记录

2026-07-26：任务开始

• 基于提交 2b265c9 开始，工作区干净。
• codebase-memory MCP 本轮未暴露 graph 工具，按项目规则回退到 rg 和定点文件读取。
• 已审计 T-201 现有 config/database/migration/httpapi/cmd 骨架、T-202 原型以及 requirements/API/architecture/IX，先固定上述跨层合约再编码。

2026-07-26：合约和实现

• 修正正式需求和原型中的 SKU、最高总预算、图片格式与验收编号；总预算统一指当前 任务全部数量的商品预算，模型不得覆盖 SKU、数量或预算。
• 新增 00002_tasks_and_assets.sql，建立 assets、purchase_tasks、task_events 和 idempotency_records；字段长度、UTF-8 字节、外键、状态、金额和唯一性均有数据库 约束。
• 建立 domain/usecase/repository/sqlite 分层，上传和创建事务化幂等，列表按 created_at DESC, id DESC 稳定分页，待领取取消使用状态与 version 条件更新。
• 文件层真实解码 JPEG/PNG/WebP，限制 20 MiB、10000 px 和 25 MP，白底缩放至最长 边 2048 px 后以质量 90 编码为随机相对键 JPEG；绝对路径不进入数据库外部响应。
• Gin API 实现上传/读取资产、创建/列表/详情/取消任务；业务路由在 T-204 前只接受 loopback，错误使用稳定 code、request ID 和 no-store 响应。
• 管理 Web 使用嵌入模板/CSS/JS，实现真实空列表、搜索筛选、创建、图片预览与复用、 详情参考图和取消确认；使用双提交 CSRF、PRG 303、HTML 自动转义和固定 CSP。
• API 启动前检查全部 migration；存在 pending 版本时拒绝启动并明确提示执行 migrate up，服务进程不自动修改数据库。

2026-07-26：自动验证

• GOTOOLCHAIN=local go test -count=1 ./...：99 个测试通过；覆盖领域校验、金额、 图片限制、路径防护、迁移约束、事务幂等、并发、分页、HTTP 生命周期、CSRF 和 模板安全。
• go test -race -count=1 ./...、go vet ./...、gofmt -l cmd internal migrations 和 API/migration Windows 构建全部通过。
• 真实 migration CLI 完成 status -> up -> up -> down -> API gate -> up：首次 applied=2、重复为 0，回滚 v2 后 API 以退出码 1 拒绝旧库，恢复后 v1/v2 均 applied。
• httptest 使用临时真实 SQLite/asset 目录跑通：上传及幂等重放、创建及重放、SKU 搜索、详情、JPEG 内容读取、取消和重复取消；非 loopback 和缺失幂等键被拒绝。
• Playwright 连接真实 Gin/SQLite 进程完成创建任务和详情读取；1440x900、 390x844、360x800 均无横向溢出，可见操作控件最小 44 px，规范化参考图 naturalWidth=64、naturalHeight=48 且成功加载，只有同源 HTML/CSS/JS/资产请求， 新页面 console 为 0 error、0 warning；取消对话框默认聚焦“保留任务”。
• 根 init.ps1 通过：Android test assembleDebug 共 76 个 Gradle task 成功， 现有 166 次测试保持通过；随后 Go 测试、vet、格式检查和两个入口构建再次通过。

2026-07-26：隐私与收尾

• 测试只使用代码生成的脱敏小图、标题和 SKU；未读取、复制或提交本地蝦皮订单、 店铺名、真实商品文字或图片。
• Playwright、数据库、资产和 exe smoke 产物只保存在被忽略的 .local/、bin/ 或 var/，未纳入 Git；业务响应和管理页面不显示客户端文件名或服务端存储路径。
• T-203 验收全部满足，状态改为 DONE；T-204 可开始实现正式管理会话和角色门禁。