WeiCHEN
485572dce2
Record recommended approaches, risks, acceptance, and product/env blockers for audit-remainder design items; cross-link F5/I8 to lowrisk.
113 lines
6.0 KiB
Markdown
113 lines
6.0 KiB
Markdown
---
|
||
title: "T20 设计项决策批（W4）"
|
||
task_id: t20-design-items-2026-09-22
|
||
status: done
|
||
created: 2026-09-22
|
||
updated: 2026-09-22
|
||
owner: Cursor
|
||
task_type: research
|
||
task_tier: small
|
||
policy_revision: "AGENTS.md + 2026-09-21-policy-registry @ base_dev_sha"
|
||
branch: feature/t20-design-items-2026-09-22
|
||
worktree: .worktrees/t20-design-items-2026-09-22
|
||
base_dev_sha: "364ed7f1a3f0393ef77ec4623a9518116ed2cb87"
|
||
write_scope:
|
||
- .doc/ops/short-term/2026-09-22-t20-design-items.md
|
||
- .doc/system-design/2026-09-22-t20-hardening-design.md
|
||
- .doc/system-design/README.md
|
||
- .doc/remediation/INDEX.md
|
||
allowed_environments: []
|
||
head_sha: ""
|
||
mutex: "t20-design-docs"
|
||
review_state: pending
|
||
integration_state: pending
|
||
deployment: not_required
|
||
cleanup: pending
|
||
cleanup_owner: 独立集成/维护执行者
|
||
cleanup_trigger: tip 为 origin/dev 祖先且无进程占用后复查 remove
|
||
remote_sync: not_requested
|
||
---
|
||
|
||
# T20 设计项决策批（W4）
|
||
|
||
设计正文（taxonomy：`system-design/`）：[../../system-design/2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)。
|
||
|
||
## 用户目标与授权
|
||
|
||
- 用户目标：对 [audit-remainder T20 增补区](../long-term/2026-09-19-audit-remainder.md) 中需设计的项产出**推荐做法 / 风险 / 验收 / 是否卡产品或鉴权**，非完整实现（除非 trivial 且安全）。
|
||
- 交付终点：本任务文 + 系统设计决策文；本 worktree 提交；不 push；不合入；不改业务代码。
|
||
- 明确禁止：实现 B1/B3/B4/B5/B7/B11/F1/F4/F7/F8/I1/I4/I6；不操作共享环境；不 push；I6 不写宿主调度。
|
||
- I6 仅文档化；实施需环境授权。
|
||
|
||
## 范围与非目标
|
||
|
||
| ID | 项 | 本批产物 |
|
||
|----|----|----------|
|
||
| B1 | XFF trusted proxy | 设计决策 |
|
||
| B3 | docgov/docrevision 锁拆分 | 设计决策 |
|
||
| B4 | statement_timeout 分级 | 设计决策 |
|
||
| B5 | chat/turn 原子性（已有补偿） | 设计决策（不重做补偿） |
|
||
| B7 | graceful shutdown vs AGENT_TIMEOUT | 设计决策 |
|
||
| B11 | GET→POST EventSource | 设计决策 |
|
||
| F1 | useChatWindow generation 所有权 | 设计决策 |
|
||
| F4 | adminResetPassword 产品选择 | 设计决策（卡产品） |
|
||
| F7 | HttpOnly cookie | 设计决策（卡鉴权专项） |
|
||
| F8 | poll dedupe + App.tsx stats generation | 设计决策 |
|
||
| I1 | non-root + limits | 设计决策 |
|
||
| I4 | init mount 统一 | 设计决策 |
|
||
| I6 | backup 调度 | **仅文档**；卡环境授权 |
|
||
|
||
### 不重复（已在低风险批）
|
||
|
||
| ID | 状态 | 交叉链接 |
|
||
|----|------|----------|
|
||
| **F5** ErrorBoundary 分栏 | 已在 W2 实现（`AppShell` 聊天栏/文档栏各包一层） | [t20-lowrisk-hardening](./2026-09-22-t20-lowrisk-hardening.md) · worktree `.worktrees/t20-lowrisk-hardening-2026-09-22` |
|
||
| **I8** short 跳过外网 docker | 已在 W2 实现（`testing.Short()` Skip） | 同上 |
|
||
|
||
本批**不**再设计或实现 F5/I8。
|
||
|
||
## 决策一览
|
||
|
||
| ID | 推荐 | 卡产品/鉴权？ | 实施前置 |
|
||
|----|------|---------------|----------|
|
||
| B1 | 默认忽略 XFF；仅 `TRUSTED_PROXY_CIDRS` 命中 RemoteAddr 时按 hops 解析 | 否（运维配置） | 配置项 + 负例测试 |
|
||
| B3 | 锁外 hydrate；按 `doc_id` 分锁；DB 写用短临界区 + fencing | 否 | 竞态基准 + 回归 |
|
||
| B4 | 主池默认 `statement_timeout=30s`；长任务 `SET LOCAL` 抬高 | 否 | 池工厂统一入口 |
|
||
| B5 | **保留** `FailChatTurn` 补偿；补齐可观测与孤儿清理；同事务列为可选后续 | 否 | 指标/扫描即可先落地 |
|
||
| B7 | 独立 `SHUTDOWN_DRAIN`（默认可对齐 `AGENT_TIMEOUT`）；停机拒新任务；compose grace 对齐 | 否（运维调参） | compose/env 对齐 |
|
||
| B11 | 生产仅 POST；GET 默认 405 且永不读 `message` query | 否 | 前端已 POST；后端收紧 |
|
||
| F1 | 所有窗口写路径共用 generation + abort；过期响应禁 setState/写缓存 | 否 | 单测扩面 |
|
||
| F4 | **隐藏按钮**直至真实 API；或产品选「服务端生成临时口令 + 强制改密」 | **是（产品）** | 产品选路径后再编码 |
|
||
| F7 | 专项：`Set-Cookie` HttpOnly + SameSite + 全局 401 清会话 | **是（鉴权专项）** | 独立授权/ADR |
|
||
| F8 | 统一 in-flight Map 按 key 去重；stats 绑 generation；blob revoke | 否 | 前端小改 |
|
||
| I1 | Dockerfile `USER` + compose mem/cpus；先非 privileged | 否（运维；部署共享环境另授权） | 卷权限验证 |
|
||
| I4 | 三环境统一挂 `extensions_init.sql`；表只走 goose | 否 | 全新卷冒烟 |
|
||
| I6 | systemd/cron 调 `backup-system-db.sh`；RPO 60m | **是（环境授权）** | 仅文档；不实施 |
|
||
|
||
详细论证见 [2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)。
|
||
|
||
## 步骤与验收
|
||
|
||
1. [x] 核对代码与 audit-remainder 条目
|
||
2. [x] 交叉确认 F5/I8 在 lowrisk worktree
|
||
3. [x] 写入 short-term + system-design；INDEX/README 回链
|
||
4. [x] Conventional Commit（不 push）
|
||
|
||
| 范围 | 命令 | 预期 | 实际 |
|
||
|---|---|---|---|
|
||
| 文档 | short-term + system-design + 索引 | 可审、taxonomy 正确；无业务行为变更 | 本分支提交 |
|
||
|
||
## 收口与交接
|
||
|
||
- `review_state=pending`；`integration_state=pending`；`deployment=not_required`；`remote_sync=not_requested`。
|
||
- 实施跟进：可并行小改（B1/B11/F1/F8、F4-A 隐藏按钮）与需决策项（F4-B/F7/I6）拆批；B3/B4/B7/I1/I4 需回归与环境冒烟。
|
||
- **待用户决策**：F4 选隐藏 vs 真实临时口令 API；F7 鉴权专项授权；I6 目标环境与备份路径授权。
|
||
- cleanup：合入后由独立维护者复查 remove。
|
||
|
||
## 相关链接
|
||
|
||
- 清单：[../long-term/2026-09-19-audit-remainder.md](../long-term/2026-09-19-audit-remainder.md)
|
||
- 审计：[../../audit/2026-09-20-system-triage-audit.md](../../audit/2026-09-20-system-triage-audit.md)
|
||
- 设计正文：[../../system-design/2026-09-22-t20-hardening-design.md](../../system-design/2026-09-22-t20-hardening-design.md)
|
||
- 低风险批（F5/I8）：[./2026-09-22-t20-lowrisk-hardening.md](./2026-09-22-t20-lowrisk-hardening.md)（合入前见 worktree `t20-lowrisk-hardening-2026-09-22`）
|