CaiWuXiTong/docs/新电脑开发接续指南.md

新电脑开发接续指南

本指南用于在另一台 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 的凭据管理器保存，不要写入命令行历史。

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

已有本地副本时，从仓库目录执行：

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 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。
2. 从本机私有文件 runtime/bootstrap-credentials.env 读取临时账号，仅用于第一次登录；不要复制、提交或发到聊天工具。
3. 进入“系统设置 → 数据库管理 → 系统数据库”。
4. 只输入负责人提供的系统数据库密码，点击“连接系统数据库”。不填写主机、端口、库名、账号、TLS、证书或任何上游数据库密码。
5. 连接成功后临时 Session 会失效，使用团队系统数据库中属于自己的正式账号重新登录。
6. 返回“数据库管理”，确认系统数据库显示为“共享 · 已连接”，并检查已登记的上游来源和业务镜像状态。

每台电脑只需完成一次上述接入。连接资料、上游账号和共享密码由系统数据库加密保存；不要从其他电脑复制 .env 或修改 DB_JIANSUN_、DB_OPERATIONS_REPLICA_。

5. 基本验收（由 Codex 执行）

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. 开始新的开发任务

从最新主线创建任务分支：

git switch main
git pull --ff-only origin main
git switch -c feature/<用户名>-<任务名>
git push -u origin feature/<用户名>-<任务名>

任务开始前阅读 团队协作说明。涉及共享路由、Repository、数据表、上游来源、权限或公共组件时，先按项目规则完成碰撞检查，再开始大量修改。不要复用已经存在的其他人的任务分支。

常用的本地验证命令如下，均由 Codex 在容器内以 www-data 身份执行：

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. 日常启动、停止和排错

# 查看容器
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 与 开发与部署 SOP。

8. 文档阅读顺序

建议按以下顺序阅读：

1. 本文：新电脑接续和本地启动；
2. AGENTS.md：团队规则和安全边界；
3. LOCAL_DEPLOY.md：本地环境细节与排错；
4. docs/开发与部署SOP.md：协作、上游、镜像和生产发布；
5. 与当前任务对应的业务需求、上游接入或视觉文档。

完整文档清单见 docs/README.md。