Initial Paprika Next.js implementation

working/06-决策记录.md

@@ -0,0 +1,195 @@
+# 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 入库验收。