# docops

**Repository Path**: wangpanA/docops

## Basic Information

- **Project Name**: docops
- **Description**: 122222222222
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocOps：Codex 离线完整开发交接包

> 当前实施状态（2026-10-29）：阶段 2 已完成；阶段 3 / 3.1 React 工程初始化已完成。正式前端位于 `apps/web`，下方交接包描述保留为历史背景，最新事实以 `docs/开发进度.md` 为准。

## 前端开发

```powershell
Set-Location apps/web
Copy-Item .env.example .env.local
npm ci
npm run dev
```

提交前运行：

```powershell
npm run lint
npm run typecheck
npm test
npm run build
```

仓库托管于 Gitee，完整的 Testcontainers 与 Playwright 门禁使用 Gitee Go 专用主机组执行，配置和首次启用步骤见 [`docs/Gitee流水线配置.md`](docs/Gitee流水线配置.md)。

当前已提供严格 TypeScript、路由守卫、统一 HTTP 请求层、Query/Zustand 基础设施、中文状态组件和响应式应用壳。登录注册、团队及文档业务页面按后续任务接入真实 API，不使用假数据冒充业务结果。

**整理日期：2026-10-26**

这个包适用于开发者已经运行过 Spring Boot、但希望之后直接把“项目原始设计 + 已有代码快照 + 全部后续任务”交给 Codex 连续实施的情况。无需每次打开聊天检索前一版交付内容。

## 交付内容

- `DocOps_完整开发指南.md`：将 01～07 开发文档合并为**一份主文档**，便于直接上传给 Codex。
- `AGENTS.md`：复制到现有仓库根目录后，可在每个 Codex 会话中自动作为项目规则。
- `docs/01_产品需求与设计决策.md`：产品定位、四大设计决定、角色权限、文档状态、需求变更、全部页面。
- `docs/02_架构数据库与一致性.md`：Java/Node/React、17 张 PostgreSQL 表、Flyway、不变版本、Yjs 冻结与撤权。
- `docs/03_API接口契约与调用顺序.md`：逐个已存在 REST/WS 接口、DTO 字段、示例 JSON、待开发端点。
- `docs/04_分阶段开发计划与逐任务实施.md`：阶段 0～9 的执行顺序、任务范围、目录、接口依赖、测试和完成定义。
- `docs/05_测试验收安全部署与风险台账.md`：测试编号与预期、CI、故障演练、部署要求、阻断性风险。
- `docs/06_Codex离线操作手册.md`：给 Codex 的首次及后续会话提示词、执行报告模板。
- `docs/07_任务看板_逐项打勾.md`：逐项编号，可直接改为你的实施看板。
- `项目基线/`：2026-10-26 上次交付的 `docops-v0.1-next.zip` **脱敏参考源码快照**，包括 Spring Boot/Node/迁移脚本；不是开发者本机实时最新源码。

## 使用方法

1. **不要替换你本机已经能运行的源码。** 先备份现有工程，然后只复制 `AGENTS.md` 与 `docs/` 到现有仓库；`项目基线/` 仅用于对照。
2. 打开本地 Codex，按 `docs/06_Codex离线操作手册.md` 的“正式首次交接指令”交代背景，让它先盘点真实代码。
3. 从阶段 0 开始完成基线核验与集成测试，再依次做阶段 1/2/3……。每次修改 `docs/开发进度.md`，后续会话只需看 Git 与本地开发进度。
4. 明文数据库密码、远程主机连接凭据、JWT/内部密钥保持在本地 `.env` 或环境变量。过去若已上传过明文密码，建议轮换。此交接包**未使用用户上传的真实数据库连接配置**。

## 本地启动配置（2026-10-26 核验）

当前本地代码使用 JDK 17、Maven 3.9.6、Spring Boot 3.5.3 和 Node 22.15。指南中的 Spring Boot 3.4.5 是交接基线差异，本轮按本地源码优先保留 3.5.3，不作降级。

Java 的私密配置存放在 `services/api-java/.env`，参考同目录 `.env.example`，采用 Java properties 格式（不加引号，密码使用原值，反斜杠需转义）。从仓库根目录或 Java 服务目录启动均可加载，已有环境变量优先。IDEA 的工作目录应设为这两个目录之一；部署时优先注入环境变量。不要把私密文件放入 `src/main/resources`。

```powershell
cd services/api-java
mvn spring-boot:run
```

Node 继续使用私有 `services/collab-node/.env`，可从不含真实凭据的 `.env.example` 复制，执行 `npm ci`、`npm test` 后再运行 `npm start`。Java 的 `DB_URL` 以 `jdbc:postgresql://` 开头，Node 的 `DATABASE_URL` 是 PostgreSQL URI；两者必须连接同一数据库，内部协作密钥一致。V3 起 Node 还会恢复持久化冻结屏障，数据库迁移和新表最小权限未完成时就绪检查不能代替功能验收。

Node 使用私有 CA 连接 PostgreSQL 时，在服务 `.env` 中设置 `PGSSL=true`、`PGSSL_REJECT_UNAUTHORIZED=true` 和 `PGSSL_CA_FILE=证书绝对路径`。服务会显式加载 CA；不要用 `PGSSL_REJECT_UNAUTHORIZED=false` 绕过校验。旧的 `NODE_EXTRA_CA_CERTS` 暂时兼容，但新配置应使用 `PGSSL_CA_FILE`。

验证 Java：在服务目录执行 `mvn clean verify`；随后在根目录执行 `powershell -File scripts/check-java-package.ps1`。最近一次 Java 回归为 17 项中 16 项通过、1 项恢复功能待办跳过；`node scripts/run-review-freeze-integration.mjs` 已在独立测试库通过真实 Node/Spring 冻结主链路，但不代表双浏览器协作、可靠撤权与恢复隔离全部验收。公开的 JWT/协作开发默认值仅供本机联调，部署前必须替换，曾暴露的凭据需要轮换。

## 原交接验证说明

数据库账号分离支持：Java 可显式启用 `SPRING_PROFILES_ACTIVE=runtime`，此配置默认禁用 Flyway、保留 Hibernate validate。切换账号前请阅读 [账号切换操作](docs/数据库账号切换操作.md)。当前远程账号尚未切换，TLS 仍待数据库服务器管理者配置。

【已有】来源于交接包内的源码静态审阅，尚不等于实际执行测试通过。用户报告过 Spring Boot 在本人机器可启动；本交接过程没有连到用户远程 PostgreSQL，也未完整编译 Java 或运行 E2E。若本机源码与随包快照冲突，以本机 Git 工作树为准，更新文档后继续开发。