AIPortPilot/BUILD-METHODOLOGY.md

应用构建方法论 v3.0（融合 Superpowers）

基于 v2.5 + obra/superpowers 流程纪律，针对 AIPortPilot 项目优化。 核心理念：结构化 > 自由发挥 / 快照 > 覆盖 / 演进 > 重写 / 先想再写 / 先测再码

---

一、七步开发流程（强制执行）

每一步都是必须执行的工作流，不是建议。Agent 在任何任务前先检查当前处于哪一步。

Step 1：Brainstorming（头脑风暴）

触发：用户提出新功能/新模块需求时 动作：

• 不急着写代码，先苏格拉底式提问
• 探索替代方案，权衡取舍
• 分段展示设计，每段短到用户能读完就消化
• 产出：docs/1-prd.md（产品设计文档） 完成标志：用户对 PRD 签字确认

Step 2：Design Document（设计文档）

触发：PRD 签字后 动作：

• 技术架构设计（技术栈、数据模型、API 设计、UI/UX 方案）
• 产出：docs/1-prd.md 中的技术设计章节 完成标志：用户对技术方案签字确认

Step 3：Writing Plans（任务拆解）

触发：设计批准后 动作：

• 将工作拆成 2-5 分钟 的小任务
• 每个任务有：精确文件路径、完整代码描述、验证步骤
• 任务之间无循环依赖，可并行标注
• 产出：docs/2-task.md（任务清单） 完成标志：用户对任务清单签字确认

Step 4：Feature Branch（特性分支）

触发：任务清单批准后 动作：

• git checkout -b feature/{module-name}
• 确保干净测试基线 完成标志：分支创建成功

Step 5：TDD Implementation（测试驱动实现）

触发：分支创建后 动作：

• RED：先写失败测试，运行确认失败
• GREEN：写最小代码让测试通过
• REFACTOR：重构，保持测试绿色
• COMMIT：每个 RED-GREEN 循环提交一次
• 禁止：先写代码后补测试 完成标志：所有任务测试通过

Step 6：Code Review（代码审查）

触发：每个任务完成后 动作：

• 对照计划检查规格符合度
• 检查代码质量（命名、结构、安全、性能）
• 严重问题阻断进度，必须修复后继续 完成标志：审查通过

Step 7：Finishing Branch（收尾合并）

触发：所有任务完成且审查通过 动作：

• 运行全量测试
• 提供选项：合并到 master / 创建 PR / 保留分支 / 丢弃
• 合并后清理分支 完成标志：代码进入 master

---

二、三原则

1. 结构化 > 自由发挥：先文档后代码，先设计后实现
2. 快照 > 覆盖：用 *_snapshot JSON 保存历史，不删旧数据
3. 演进 > 重写：版本号 + is_current 指针，增量演进

---

三、文档骨架（必有）

文件	内容	何时写
README.md	项目介绍、技术栈、快速启动	Step 2
run.md	10 板块运维手册	Step 2
AGENTS.md	Agent 协作规则	Step 2
docs/0-req.md	需求文档（从方案文档提炼）	Step 1
docs/1-prd.md	PRD + 技术设计	Step 1-2
docs/2-task.md	任务清单（2-5 min 粒度）	Step 3
docs/daily/	日报	每日

run.md 十板块

技术栈 / 首次准备 / 基础设施启停 / 应用启停 / DB 命令 / 排错 / 端口表 / env / 部署备份 / FAQ

铁律

• 命令可复制粘贴
• 标注 [Docker] / [Native]
• 危险操作标红
• 版本号写死
• 过时即同步

---

四、数据 8 铁律

1. 快照隔离历史（*_snapshot JSON）
2. 版本号 + is_current 唯一指针，不删旧
3. 内部状态机与用户可见状态分离
4. 租户隔离走 session.tenant_id，不信任请求体
5. 配置粒度对齐"谁应该决定"（全局/租户/用户）
6. 字段演进：nullable + 默认值；枚举用字符串；时间戳 *_at
7. 审计字段：created_by/updated_by/deleted_by + *_at；关键操作落 audit_logs ≥ 6 月
8. UTC 存储；金额用 decimal/整数；禁止 float

---

五、安全与权限

• 密钥进 KMS/Vault，绝不进 Git，仅 commit .env.example
• 后端必须独立校验权限，前端隐藏 ≠ 后端放权
• PII 全链路脱敏（手机/身份证/邮箱），日志中用 138****1234
• 注入防御：SQL 参数化 / 命令 shell=False / XSS 自动转义 + CSP / CSRF 走 SameSite
• 限流熔断：登录 5次/min/IP，写接口按用户限流，429 带 Retry-After
• JWT 短 TTL（≤2h）+ refresh；Cookie 必 HttpOnly+Secure+SameSite
• 本项目特殊：投后数据高度敏感，优先私有化部署，数据不出域

---

六、API 设计

• REST 资源命名（名词复数 + 层级），版本进 URL 不进 query
• HTTP 状态码语义化，禁全 200 塞 error
• 统一响应壳：{code, message, data, trace_id, timestamp}
• 分页 ?page&page_size&sort&filter[k]=v，大数据集用 keyset 游标
• 写接口接受 Idempotency-Key，订单/支付必须
• trace_id 全链路（网关→后端→DB→前端 X-Trace-Id）
• OpenAPI 自动生成进 Git，废弃接口 Deprecation + Sunset

---

七、AI / 智能集成

• 接口抽象，业务面对自家"智能服务接口"
• 多源容灾 + 兜底降级（规则/缓存/默认），不拖垮主流程
• 强制 Structured Output / JSON Schema，禁编造
• 决策证据化：输出 score / confidence / evidence / concerns / fallback_used
• Prompt 进 Git，不只在 DB；可 diff、可回滚
• 单次/用户/租户分级成本预算；缓存优先；慢路径异步化
• 用户输入与系统 prompt 分离 role，加分隔符 <<<USER_INPUT>>>，防注入
• LLM 输出代码绝不直接 exec/eval，必经语法检查 + 沙箱
• PII 进 LLM 前脱敏，响应再回填
• confidence < 0.6 显式提示人工核对

---

八、客户端 + 多端 UIUX

三端角色化

• 投资人端（B 端专业）：主色 gray-900，左 Sidebar（w-52 sticky）+ 内容 bg-[#f8f9fb]，信息密集
• 创始人端（C 端温暖）：主色 indigo-600，顶部 sticky Header（h-14 bg-white/95 backdrop-blur），渐变背景
• Admin 端（警示）：Header bg-slate-950 + 主色 amber-400，内容 bg-slate-100，必带 ADMIN 徽章

共享 Token

• Geist 字体 / oklch 色彩 / --radius: 0.625rem，禁硬编码 hex
• shadcn + @base-ui + lucide + sonner + recharts，禁多 UI 库混用

Layout 统一

• 容器 container mx-auto max-w-7xl px-4，Header 全应用 h-14

交互统一

• <LoadingSpinner> / <EmptyState> / sonner toast / <Dialog> 二次确认
• 状态色三件套：emerald(success) / amber(warning) / rose(destructive)

响应式

• sm/md/lg/xl/2xl 五断点
• Sidebar < md 折叠为抽屉/下拉，不丢功能入口

a11y

• 键盘可达 / 对比度 ≥ 4.5:1 / 语义化标签 / aria-label，禁 <div onClick>

其他

• i18n：文案进 JSON，用 Intl.* 格式化
• 报告页强制 @media print
• 流式输出 RAF 批量刷新，禁每 token 触发 React 重渲染
• 禁 alert()/confirm()、禁多 UI 库、禁硬编码主色 hex、禁三端共用 Header

---

九、五防一兜底

1. 防异步穿越（AbortController / 引用保存）
2. 防外部单点（超时+重试+熔断+多源）
3. 防资源缺失（启动校验字体/翻译/配置）
4. 防 API 弃用（季度内替换 + 灰度升级）
5. 防数据丢失（事务 / 幂等键 / 持久化队列 / beforeunload）
6. 一兜底：最差体验是"功能受限可用"，不是白屏

---

十、部署运维

• 部署脚本"只清自己"，禁 pm2 delete all、禁 redis-cli FLUSHALL、禁 rm -rf /
• 跨子域 cookie 名独立 + domain=.example.com
• DB migrate 走 CI/CD 自动应用
• 备份：每天 2 次 + 滚动 7 天 + 双副本（本机 + 异地）+ 每月恢复演练
• 监控 4 金指标：Latency / Traffic / Errors / Saturation
• 灰度 1% → 10% → 50% → 100%，每档观察 ≥ 30 分钟
• 回滚 SOP 必备，回滚比修复快

---

十一、测试纪律

• 70/20/10：单元/集成/E2E
• TDD 强制：RED-GREEN-REFACTOR，先写失败测试再写代码
• 关键路径必覆盖（登录/支付/导出/权限/AI 主流程）
• 集成测试用 testcontainers 跑真实 DB，禁 mock DB
• 修 bug 必先写复现测试，禁删测试、禁 @skip/it.only 进 PR

---

十二、协作纪律

• 每步完成后更新 docs/2-task.md 状态
• 日报写 docs/daily/YYYY-MM-DD.md
• 重大决策记 docs/decisions/（ADR 格式）
• 代码审查问题按严重度分级：Critical（阻断）/ Major（必须修）/ Minor（建议）
• 提交信息格式：type(scope): description，type ∈ feat/fix/refactor/test/docs/chore