From a56328750e7690a4e70d1658f361496f4a0b390d Mon Sep 17 00:00:00 2001
From: "404877757@qq.com" <404877757@qq.com>
Date: Mon, 7 Sep 2026 11:13:57 +0800
Subject: [PATCH] docs: add new workstation development handoff guide

---
 LOCAL_DEPLOY.md            |   2 +
 README.md                  |   4 +-
 docs/README.md             |  48 ++++++++++++
 docs/新电脑开发接续指南.md | 146 +++++++++++++++++++++++++++++++++++++
 4 files changed, 199 insertions(+), 1 deletion(-)
 create mode 100644 docs/README.md
 create mode 100644 docs/新电脑开发接续指南.md

diff --git a/LOCAL_DEPLOY.md b/LOCAL_DEPLOY.md
index 8d5de33b..2be14830 100644
--- a/LOCAL_DEPLOY.md
+++ b/LOCAL_DEPLOY.md
@@ -156,6 +156,8 @@ docker compose -f docker-compose.local.yml exec -u www-data app php artisan opti
 
 ## 相关文档
 
+- 新电脑接续指南：[docs/新电脑开发接续指南.md](docs/新电脑开发接续指南.md)
+- 文档索引：[docs/README.md](docs/README.md)
 - 团队规则：`AGENTS.md`
 - 开发和正式发布：`docs/开发与部署SOP.md`
 - 上游业务接入：`docs/ecommerce-finance-development.md`
diff --git a/README.md b/README.md
index 00c1d65f..5540e97b 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
 
 Codex 的接入验收不能只回答“成功”或“失败”，必须逐个来源报告：来源标识、数据库和 Schema、验证对象、读取字段、返回行数、耗时、数据状态及失败阶段。连接资料由系统自动处理，不属于新人操作项。
 
-完整步骤和排错说明见 [LOCAL_DEPLOY.md](LOCAL_DEPLOY.md)。
+完整步骤和排错说明见 [LOCAL_DEPLOY.md](LOCAL_DEPLOY.md)。需要在另一台电脑继续开发时，按 [新电脑开发接续指南](docs/新电脑开发接续指南.md) 操作；所有 Markdown 文档的入口见 [文档索引](docs/README.md)。
 
 ## 数据库边界
 
@@ -30,6 +30,8 @@ Codex 的接入验收不能只回答“成功”或“失败”，必须逐个
 
 ## 开发和发布
 
+- 新电脑接续指南：[docs/新电脑开发接续指南.md](docs/新电脑开发接续指南.md)
+- 文档索引：[docs/README.md](docs/README.md)
 - 团队协作与安全规则：[AGENTS.md](AGENTS.md)
 - 本地测试环境：[LOCAL_DEPLOY.md](LOCAL_DEPLOY.md)
 - 开发和正式部署：[docs/开发与部署SOP.md](docs/开发与部署SOP.md)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..be7166d6
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,48 @@
+# CaiWuXiTong 文档索引
+
+本目录按“先启动、再协作、最后按业务深入”的顺序整理。文档中的规则发生冲突时，以根目录 [AGENTS.md](../AGENTS.md) 和负责人最新明确要求为准；历史截图、聊天记录和临时排错方案不覆盖当前规则。
+
+## 新电脑与本地开发
+
+| 文档 | 用途 |
+| --- | --- |
+| [新电脑开发接续指南](新电脑开发接续指南.md) | 在另一台 Windows 电脑克隆最新代码、启动本地环境、接入团队系统数据库并创建任务分支 |
+| [LOCAL_DEPLOY.md](../LOCAL_DEPLOY.md) | 本地 Docker、临时引导库、共享系统数据库和常见命令的完整说明 |
+| [AGENTS.md](../AGENTS.md) | Git、协作、敏感信息、数据和部署边界 |
+| [DESIGN.md](../DESIGN.md) | VIP 黑金主题、组件和页面视觉规范 |
+| [SECURITY.md](../SECURITY.md) | 安全相关的最小基线 |
+
+## 协作、构建与发布
+
+| 文档 | 用途 |
+| --- | --- |
+| [开发与部署 SOP](开发与部署SOP.md) | 团队协作、Docker 构建缓存、服务器初始化、正式发布、镜像和回滚 |
+| [团队协作说明](team-collaboration.md) | 任务预检、分支、WIP PR、冲突协调和交付要求 |
+
+生产发布只使用已经合并的最新 main，并遵守 SOP 中的授权、备份和回滚要求。服务器不构建源码，私有配置和证书不进入 Git。
+
+## 上游数据、镜像与电商财务
+
+| 文档 | 用途 |
+| --- | --- |
+| [通用上游数据接入](通用上游数据接入.md) | 新来源发现、数据字典、固定只读查询、镜像登记和验收 |
+| [上游业务镜像清单](上游业务镜像清单.md) | 当前来源、表/视图、镜像表和分阶段迁移状态 |
+| [电商财务扩展开发说明](ecommerce-finance-development.md) | 订单、结算、成本、资金和利润分析的业务模型与扩展边界 |
+| [主体维度经营报表需求说明](主体维度经营报表需求说明.md) | 主体维度经营报表的字段、口径、来源和验收契约 |
+
+上游数据库按只读黑盒处理。正式页面优先读取共享业务镜像；尚未迁移的旧页面才使用兼容快照。不要在网页中接受任意 SQL，也不要把真实业务数据或连接凭据写进文档、测试和截图。
+
+## 集成与模块参考
+
+| 文档 | 用途 |
+| --- | --- |
+| [电子签约集成说明](esign-agreement-integration.md) | 电子签约集成的接口和配置边界 |
+| [OfflinePayments README](../modules/OfflinePayments/README.md) | 离线支付模块说明 |
+| [PaypalStandard README](../modules/PaypalStandard/README.md) | PayPal Standard 模块说明 |
+| [测试数据说明](../test-data/README.md) | 可公开共享的脱敏测试数据约定 |
+
+## 文档维护约定
+
+- 新增开发流程或交接信息时，优先更新本索引和对应主题文档，不在多个文件复制同一套命令。
+- 命令、路径和页面名称以当前代码为准；改动后使用 git diff --check 检查格式。
+- 密码、Token、数据库连接串、APP_KEY、.env、SSH 私钥、生产日志和真实财务数据永远不进入 Git。
diff --git a/docs/新电脑开发接续指南.md b/docs/新电脑开发接续指南.md
new file mode 100644
index 00000000..b262ceb3
--- /dev/null
+++ b/docs/新电脑开发接续指南.md
@@ -0,0 +1,146 @@
+# 新电脑开发接续指南
+
+本指南用于在另一台 Windows 电脑上继续开发 CaiWuXiTong。仓库代码、开发环境和团队系统数据库配置分开管理：新电脑只需要重新克隆代码、启动本机 Docker 环境，并在页面中完成一次团队系统数据库接入。
+
+## 先看这几条边界
+
+- Git 认证使用项目负责人分配的 Git 账号或令牌；不要把服务器 root 密码当作 Git 密码，也不要把凭据写进仓库地址、脚本或 Markdown。
+- main 是稳定主线。开发任务从最新 main 创建独立的 feature/... 或 fix/... 分支，不直接在 main 上开发。
+- 不要复制其他电脑的 runtime/.env、APP_KEY、runtime/bootstrap-credentials.env、数据库卷、SSH 私钥或生产配置。每台开发机使用自己的本地配置和密钥。
+- 不要对团队共享系统数据库执行 php artisan migrate，不要执行 docker compose down -v，也不要删除 Docker 数据卷。
+- 新人通常只需要启动 Docker Desktop 并在网页输入负责人提供的系统数据库密码；仓库拉取、初始化、缓存、容器和排错命令交给 Codex 执行。
+
+## 1. 准备 Windows 环境
+
+安装并启动以下软件：
+
+1. Git（建议启用 Git Credential Manager）；
+2. Docker Desktop，使用 WSL2 后端；
+3. Git Bash 或 WSL，用于执行项目中的 Bash 初始化脚本。
+
+Docker Desktop 启动后确认没有暂停或报错。磁盘空间不足会导致镜像构建失败，建议为 Docker 虚拟磁盘预留约 60GB 上限，并为 Windows 保留至少 15GB 可用空间。
+
+## 2. 克隆并拉取最新代码
+
+在 Git Bash 或 WSL 中执行。首次克隆时，Git 可能会提示输入项目 Git 账号或令牌；凭据只交给 Git 的凭据管理器保存，不要写入命令行历史。
+
+~~~bash
+cd /c/Users/<你的用户名>/Documents
+git clone http://git.1080p.hk/WuYongJie/CaiWuXiTong.git
+cd CaiWuXiTong
+git fetch origin --prune
+git switch main
+git pull --ff-only origin main
+git status --short --branch
+~~~
+
+已有本地副本时，从仓库目录执行：
+
+~~~bash
+git status --short --branch
+git fetch origin --prune
+git switch main
+git pull --ff-only origin main
+git rev-list --left-right --count HEAD...origin/main
+~~~
+
+最后一条命令显示 0 0，表示本地 main 与远程 main 已同步。如果 git status 显示无法解释的改动，先停止并保留现场，不要用 reset --hard 或 clean -fd 覆盖它。
+
+## 3. 启动本地环境
+
+确保 Docker Desktop 已启动，然后在仓库根目录执行：
+
+~~~bash
+bash deploy/local-init.sh
+~~~
+
+初始化脚本会自动：
+
+- 生成被 Git 忽略的 runtime/.env 和本机随机 APP_KEY；
+- 构建或复用带有当前源码指纹的开发镜像；
+- 启动应用和仅用于首次登录的本机 MySQL；
+- 初始化本机临时引导库并生成临时登录凭据；
+- 清理缓存、修复容器内运行目录权限并执行就绪检查。
+
+代码、依赖、Dockerfile 或前端资源发生变化时，仍然运行同一条命令，脚本会自动判断是否需要重建。只有需要明确强制重建时才使用 bash deploy/local-init.sh --build；不要让新开发者自行判断构建参数。
+
+## 4. 首次登录并接入团队系统数据库
+
+1. 打开 [http://127.0.0.1:18088/auth/login](http://127.0.0.1:18088/auth/login)。
+2. 从本机私有文件 runtime/bootstrap-credentials.env 读取临时账号，仅用于第一次登录；不要复制、提交或发到聊天工具。
+3. 进入“系统设置 → 数据库管理 → 系统数据库”。
+4. 只输入负责人提供的系统数据库密码，点击“连接系统数据库”。不填写主机、端口、库名、账号、TLS、证书或任何上游数据库密码。
+5. 连接成功后临时 Session 会失效，使用团队系统数据库中属于自己的正式账号重新登录。
+6. 返回“数据库管理”，确认系统数据库显示为“共享 · 已连接”，并检查已登记的上游来源和业务镜像状态。
+
+每台电脑只需完成一次上述接入。连接资料、上游账号和共享密码由系统数据库加密保存；不要从其他电脑复制 .env 或修改 DB_JIANSUN_*、DB_OPERATIONS_REPLICA_*。
+
+## 5. 基本验收（由 Codex 执行）
+
+~~~bash
+docker compose -f docker-compose.local.yml ps
+docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan app:ready
+docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan system-database:verify --no-ansi
+~~~
+
+app:ready 通过只表示本地应用已就绪；system-database:verify 通过才表示团队系统数据库接入成功。首次接入尚未完成时，初始化脚本会保留本机引导库并提示在网页输入一次密码，不应把这种状态当成代码或数据为空。
+
+## 6. 开始新的开发任务
+
+从最新主线创建任务分支：
+
+~~~bash
+git switch main
+git pull --ff-only origin main
+git switch -c feature/<用户名>-<任务名>
+git push -u origin feature/<用户名>-<任务名>
+~~~
+
+任务开始前阅读 [团队协作说明](team-collaboration.md)。涉及共享路由、Repository、数据表、上游来源、权限或公共组件时，先按项目规则完成碰撞检查，再开始大量修改。不要复用已经存在的其他人的任务分支。
+
+常用的本地验证命令如下，均由 Codex 在容器内以 www-data 身份执行：
+
+~~~bash
+docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan optimize:clear
+docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan test --do-not-cache-result
+~~~
+
+完成修改后提交当前任务文件并推送分支；不要把 runtime/、.env、凭据、日志、数据库文件、构建包或私钥加入提交。
+
+## 7. 日常启动、停止和排错
+
+~~~bash
+# 查看容器
+docker compose -f docker-compose.local.yml ps
+
+# 停止但保留本地数据
+docker compose -f docker-compose.local.yml stop
+
+# 再次启动
+docker compose -f docker-compose.local.yml start
+
+# 查看应用日志
+docker compose -f docker-compose.local.yml logs --tail=100 app
+~~~
+
+常见处理方式：
+
+- Docker 未就绪：先启动 Docker Desktop，确认 WSL2 引擎正常，再重新运行 bash deploy/local-init.sh。
+- 页面返回 500：先查看应用日志并执行 optimize:clear；不要直接迁移数据库或删除卷。
+- 页面没有业务数据：先确认已使用正式团队账号登录，并检查共享数据库和业务镜像状态；本机临时库有数据不代表已接入团队数据。
+- 拉取后代码看起来没更新：确认当前目录、git log -1 --oneline 和 git rev-list --left-right --count HEAD...origin/main，不要在未确认改动归属前覆盖文件。
+- 共享数据库暂时不可达：保留现有配置并报告失败阶段（DNS、TCP、TLS、登录、数据库、Schema 或业务查询）；不要把网络故障解释成“没有数据”。
+
+更完整的本地部署、上游接入和正式发布流程见 [LOCAL_DEPLOY.md](../LOCAL_DEPLOY.md) 与 [开发与部署 SOP](开发与部署SOP.md)。
+
+## 8. 文档阅读顺序
+
+建议按以下顺序阅读：
+
+1. 本文：新电脑接续和本地启动；
+2. [AGENTS.md](../AGENTS.md)：团队规则和安全边界；
+3. [LOCAL_DEPLOY.md](../LOCAL_DEPLOY.md)：本地环境细节与排错；
+4. [docs/开发与部署SOP.md](开发与部署SOP.md)：协作、上游、镜像和生产发布；
+5. 与当前任务对应的业务需求、上游接入或视觉文档。
+
+完整文档清单见 [docs/README.md](README.md)。