docs(xingbang): 适配项目开发流程并建立经验驱动预审新版文档

docs/project-process/03-detailed-design.md

@@ -14,7 +14,7 @@
 - 规格的 `BR-*`/`E-*`/`AC-*` 全部可映射到具体接口/数据/状态。
 
 ### 1.2 完成条件（DoD）
-- [ ] 每个公开接口（函数/方法/事件/IPC 通道/硬件协议命令）有签名、入参校验规则、返回与错误语义
+- [ ] 每个公开接口（HTTP/SSE端点、函数、模型工具及业务事件）有签名、入参校验规则、返回与错误语义
 - [ ] 每个数据结构（表/文件/状态对象）有字段、类型、可空性、owner；变更走追加式迁移且有守卫
 - [ ] 每个有状态视图/流程有状态机（状态全集 + 合法转换 + 每个状态的禁用手势）
 - [ ] 规格中每条 `E-*` 都能落到具体错误码 + 处理路径（重试/降级/回滚）
@@ -28,7 +28,7 @@
 | 编号 | 规则 |
 |---|---|
 | R-3.1 | **契约先行且单一**：接口与数据契约在详细设计中定案，实现只落契约不发明契约；跨进程契约只放共享层一处（G-1）。 |
-| R-3.2 | **入参显式校验**：每个对外接口（IPC、命令、硬件写入、外部请求）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 |
+| R-3.2 | **入参显式校验**：每个对外接口（HTTP、文件上传、SQL数据卡参数、模型请求和服务命令）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 |
 | R-3.3 | **状态机完备**：状态全集含加载/空/错误/提交中等"非 happy path"状态；每个状态定义允许的动作与禁用手势。折叠状态机（如把 Loading 与 Submitting 合并成一个布尔）会丢失关键行为，禁止。 |
 | R-3.4 | **异常必有归属**：每条失败路径有明确处理语义（重试上限、降级、回滚、幂等）与错误码；静默失败是设计缺陷。 |
 | R-3.5 | **迁移只追加**：持久化结构变更只能追加带守卫的迁移（版本号递增 + 幂等守卫），禁止修改历史迁移；迁移只跑一次。 |
@@ -54,12 +54,12 @@
 ```
 
 ### 3.2 契约声明（可落地的部分）
-- 类型定义：跨进程契约先写在 `packages/api/src/contracts.ts`（唯一事实源），宿主与各包只 `import type`；包内契约就近在包内共享层声明。
+- 类型定义：新增共享业务契约优先位于 `backend/contracts/`，由FastAPI请求/响应模型引用；前端同步以已验证的生成物或契约测试为准。当前不存在完整OpenAPI生成流水线，建设前标为待实现。不要顺手重排旧API的所有请求模型。
 - 数据结构草案：DDL/迁移骨架，标注幂等守卫。
 - 状态机表：Markdown 表格即可，复杂流程可配 sequence 图（见 [02-architecture.md](02-architecture.md) §3.2）。
 
 ### 3.3 交付物清单
-- 详细设计文档（本地草稿 `docs/plans/`（不入库，见 `.gitignore`），需入库随 PR 放 `docs/` 对应目录）
+- 详细设计文档入 `docs/v2/` 或相应业务目录，注明草案/定案和所覆盖需求编号。
 - 契约草案（类型/迁移/错误码表）
 - 测试映射表（为 ⑥ 验证做准备）
 
@@ -68,7 +68,7 @@
 ## 4. 轻量路径（小改动）
 
 - 单接口小改：契约 + 边界 + 测试映射合并为设计文档中的 2-3 小节。
-- 触碰共享契约、迁移、状态机、硬件协议：必须完整走详细设计。
+- 触碰共享契约、迁移、状态机、模型工具与数据出口：必须完整走详细设计。
 
 ---
 
@@ -77,3 +77,5 @@
 - 输入：阶段 ① [01-requirement.md](01-requirement.md)、阶段 ② [02-architecture.md](02-architecture.md)
 - UI 相关设计拆到：阶段 ④ [04-ui-spec.md](04-ui-spec.md)
 - 实现时按此设计编码：阶段 ⑤ [05-implementation.md](05-implementation.md)
+
+变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。