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 入库验收。