MeetPaprika/working/06-决策记录.md

06-决策记录

本文件记录已经做出的工程、产品和流程决策。后续若要改变决策，需要新增记录说明原因，不直接覆盖旧记录。

D001 - 当前基线按静态单文件 mockup 记录

• 日期：2026-07-06
• 决策：当前以 doc/index.html 作为项目基线，而不是假设已有完整前端工程。
• 原因：
  • 当前目录未发现 package.json、构建配置或后端代码。
  • doc/index.html 已包含页面、样式和路由脚本。
  • 用户本轮要求是在 working 中编写推进文档。
• 影响：
  • 当前验收以静态页面可打开、路由可渲染、视觉可检查为主。
  • 表单、部署、测试、工程化都作为后续任务单独推进。

D002 - 表单不按真实功能验收

• 日期：2026-07-06
• 决策：start 和 ask 当前只能记为表单视觉 mockup，不能记为真实线索收集功能。
• 原因：
  • 字段是 <div>，不是输入控件。
  • 提交按钮是跳转链接，不会提交数据。
  • 没有后端、第三方表单服务、文件上传或校验逻辑。
• 影响：
  • T012、T013、T014 保持 TODO。
  • 上线前必须实现真实提交，或在页面明确标注不可提交。

D003 - 任务推进以任务矩阵为唯一入口

• 日期：2026-07-06
• 决策：后续开发先查 04-任务矩阵.md，每个任务必须有编号、状态、验收标准和依赖。
• 原因：
  • 用户明确要求防止重复做。
  • 当前项目范围包含内容、前端、表单、法务、部署和证据留存，容易混线。
• 影响：
  • 新工作不得只写在聊天记录里。
  • 完成任务必须同步推进台账和验收证据。

D004 - 法务内容按草稿处理

• 日期：2026-07-06
• 决策：Terms、Privacy、Disclaimer 当前按草稿记录，正式上线前需要法务或负责人确认。
• 原因：
  • 页面涉及 non-law-firm statement、attorney-client relationship、refund、privacy、file upload、attorney referral、immigration outcome guarantee 等高风险内容。
  • 页面曾使用 Last updated: July 10, 2026，晚于当前日期 2026-07-06；R007 已修正日期，但内容仍需审核。
• 影响：
  • T016 标为 BLOCKED，等待法务/负责人输入。
  • T017 后续已完成日期修正；法务内容审核仍不关闭。

D005 - 本轮不改 doc/index.html

• 日期：2026-07-06
• 决策：R002 只补强 working 文档，不修改 doc/index.html。
• 原因：
  • 用户要求是在 working 中编写文档体系。
  • 当前还没有要求开始代码修复或工程化迁移。
• 影响：
  • T029 虽已识别，但仍为 TODO。
  • 后续修复死链时应单独开一轮并记录证据。

D006 - 长期文档不保存明文服务器密码

• 日期：2026-07-06
• 决策：用户提供的 SSH 密码只视为临时交接信息，不写入 working 长期文档。
• 原因：
  • working 文档会作为后续推进资料，可能被复制、上传或纳入版本控制。
  • 明文密码进入项目文件会扩大泄露面。
• 影响：
  • 服务器信息保留 host、user、port、domain。
  • T030 要求改用 SSH key、部署密钥或受控密钥库。

D007 - 目标部署端口采用 8082

• 日期：2026-07-06
• 决策：部署方案默认内部服务监听 8082，HTTPS 由域名和反向代理对外提供。
• 原因：
  • 用户明确给出端口号 8082。
  • 用户说明 8080-8099 已开放。
  • HTTPS 通常由 Nginx/Caddy/负载均衡终止，再转发到本地应用端口。
• 影响：
  • T024 验收服务器本地 127.0.0.1:8082。
  • T025 验收 https://paprikalaw.com/。

D008 - Services 的 contact 路由判定为缺陷

• 日期：2026-07-06
• 决策：Services 页面 04/05/06 CTA 指向 contact 是缺陷，不按设计接受。
• 原因：
  • pageData 没有 contact 页面。
  • 当前路由逻辑会把未知页面回退到 home。
  • CTA 文案是 Start Here，合理目标应为 start，除非新增真实 Contact 页面。
• 影响：
  • 新增 T029。
  • 修复前 T006 只能保持 VERIFY，不能标为 DONE。

D009 - Outlet/network 名称正式发布前需确认

• 日期：2026-07-06
• 决策：Press 和 Judging 页面中的 outlet/network 名称上线前必须由负责人确认，或改成示例类型表达。
• 原因：
  • 页面列出大量媒体和 judging/network 名称，可能被理解为合作关系、可保证 placement 或背书。
  • 这类陈述涉及商业真实性和法律风险。
• 影响：
  • 新增 T031，状态 BLOCKED。
  • 未确认前不建议直接正式上线。

D010 - 完全对标必须包含视觉和源码结构

• 日期：2026-07-06
• 决策：后续提到“完全对标 doc/index.html”时，不能只记录页面文案，还必须覆盖 CSS token、组件类、函数清单、CTA 映射、FAQ 编号、Legal section、未调用模块和源码缺陷。
• 原因：
  • doc/index.html 是 3423 行单文件 mockup，页面内容、视觉规范和路由逻辑耦合在一起。
  • 如果只记录页面功能，工程化拆分时容易丢失视觉细节或保留隐藏缺陷。
• 影响：
  • 01-项目功能内容.md 增加源码级对标附录。
  • 02-项目程序开发详细步骤.md 增加完全对标核验清单。
  • 新增 T034 和 E016。

D011 - 正式开发架构采用 Next.js + React + PostgreSQL

• 日期：2026-07-06
• 决策：正式开发技术架构采用 Next.js + React，数据库使用 PostgreSQL。
• 默认补充决策：
  • 使用 TypeScript。
  • 使用 Next.js App Router。
  • 使用 Prisma 作为 PostgreSQL ORM。
  • 使用 Next.js Route Handlers 或 Server Actions 处理表单提交。
  • 生产服务监听 8082，HTTPS 由反向代理处理。
• 原因：
  • 用户明确指定 Next+ React 和 PostGreSQL。
  • 项目需要真实表单、数据持久化、后续可能的文件上传和后台线索管理，单纯静态站不够。
  • Next.js 可同时承接页面、API、SEO、构建和生产服务。
• 影响：
  • 02-项目程序开发详细步骤.md 中工程化路线改为 Next.js + PostgreSQL。
  • 新增 T035-T039。
  • 后续不再优先推进 Vite/纯静态拆分，除非另有新决策。

D012 - PostgreSQL 已安装但仍需远程验证

• 日期：2026-07-06
• 决策：将服务器 PostgreSQL 状态记录为“用户确认已安装，待远程验证”，不直接视为已完成数据库接入。
• 原因：
  • 用户已明确说明 PostgreSQL 在服务器安装完成。
  • 但尚未执行服务状态、版本、数据库列表、应用数据库、应用用户和连接字符串验证。
• 影响：
  • 新增 T040 远程验证 PostgreSQL 安装。
  • T037 PostgreSQL + Prisma 接入仍保持 TODO。
  • 继续执行不保存明文密码的凭据规则。

D013 - 邮箱账号统一记录但不保存初始密码

• 日期：2026-07-06
• 决策：记录 paprikalaw.com 邮箱入口、管理员账号和 10 个普通邮箱账号，但不在长期文档保存用户提供的统一初始密码。
• 原因：
  • 邮箱账号属于项目基础设施，网站联系、表单通知和法务联系需要引用。
  • 多账号共用初始密码存在安全风险，进入文档会扩大泄露面。
• 影响：
  • 新增 T041-T043。
  • 创建或确认邮箱后，应尽快改为独立强密码并记录验证证据。
  • Next.js SMTP 凭据只能放服务器环境变量或受控密钥库。

D014 - 保留 doc/index.html 作为对标基线，同时以 Next.js 为正式工程

• 日期：2026-07-06
• 决策：不删除 doc/index.html，正式代码在根目录 Next.js 工程中维护。
• 原因：
  • doc/index.html 是既有视觉、文案和路由逻辑的完整基线。
  • 新工程需要持续对标旧 mockup，避免内容迁移漂移。
  • scripts/extract-legacy-pages.mjs 可从旧基线重新生成静态页面 CSS 和 HTML 数据。
• 影响：
  • 静态内容页面暂由 lib/legacy-pages.ts 和 LegacyPage 渲染。
  • /start、/ask、/thanks 已由 React 页面接管，不再使用旧 mockup 表单。

D015 - 文件上传暂不启用

• 日期：2026-07-06
• 决策：Start/Ask 表单当前不启用 CV/resume 上传。
• 原因：
  • 文件上传涉及存储位置、大小限制、访问权限、隐私保留期限和删除策略。
  • 未确认前收集 CV 会扩大敏感数据风险。
• 影响：
  • SubmissionFile 表作为未来能力预留。
  • 前端表单明确说明 file upload 暂停，直到存储和隐私方案获批。

D016 - 表单入库任务不在缺少 DATABASE_URL 时关闭

• 日期：2026-07-06
• 决策：虽然 /api/submissions 已实现 Prisma 写入代码，但在没有真实 PostgreSQL DATABASE_URL 和成功 submission_id 证据前，T038/T044 不标为 DONE。
• 原因：
  • API 代码通过构建不等于数据已经成功持久化。
  • 生产数据库连接、migration、权限和网络策略都可能导致运行时失败。
• 影响：
  • T012/T013/T038 保持 VERIFY。
  • 新增 T044，专门记录真实 PostgreSQL 入库验收。