D4 · Implementation · v1.0 Kickoff

D4 · 实现级文档

Xisound Backend-CSharp / Frontend-Vue3 / DSP-Algo / PySidecar / Algorithms / Web-Astro

6

子项目

10

标准模板 / 子项目

AI+校对

主笔模式（O8=C）

D4 · 实现级文档总览

摘要

D4 · 实现级是 Xisound 文档体系七层分治中的第五层，定位与代码仓库 1:1 mirror 的模块实现文档（O3=Y 拍板生效）。工程师"写模块 = 写文档"，通过 CI job 扫描保证文档-代码同步（O6=C 拍板）。主笔模式：AI 辅助生成草稿 + 工程师校对合入（O8=C 拍板）。

骨架版说明

本层目录结构、子项目 index 骨架已建立（整理批 1），10 份标准模板将在 实现批 1-2（填充期） 由对应栈 owner 工程师认领填充。

1. 六大子项目（与代码仓库 mirror）

#	子项目	对应代码路径	技术栈	标准模板数	状态
1	`backend-csharp/`	`04_development/backend_csharp/`	ASP.NET Core 8 · NAudio · SignalR	10	🟡 骨架
2	`frontend-vue3/`	`04_development/frontend_vue3/`	Vue 3 · Pinia · Vite	10	🟡 骨架
3	`dsp-algo/`	`04_development/dsp_algo/`	C native · DLL · 9 modules	10	🟡 骨架
4	`pysidecar/`	`04_development/pysidecar/`	Python · FastAPI	10	🟡 骨架
5	`algorithms/`	`03_algorithms/`	算法源码库（DSP + ML）	10	🟡 骨架
6	`web-astro/`	`07_web/xisound-website/`	Astro 4 · TypeScript	10	🟡 骨架

总计：6 × 10 = 60 份标准模板文档（Phase 4 实现批 1-2 目标）。

2. 每个子项目的 10 份标准模板

每个子项目下统一按 10 份模板组织（对齐代码视角）：

#	模板	内容	来源
01	`README.md`	项目入口 · 快速启动	README 一键复制
02	`architecture.md`	模块级架构（D3 的下探）	继承 D3 相关子目录
03	`api-internal.md`	内部 API（函数签名 / DI 注入）	AI 提取
04	`data-flow.md`	数据流向图	Mermaid 图
05	`module-list.md`	模块清单	目录扫描
06	`config.md`	配置文件 schema	AI 扫描 appsettings/*.json · vite.config
07	`dependencies.md`	依赖树 · 版本锁	扫描 *.csproj / package.json / requirements.txt
08	`build.md`	本地构建 · 产物位置	AI 整理
09	`debugging.md`	调试工作流 · 常见坑	历史 PR / issue
10	`migration.md`	版本升级 · 数据迁移	按需

3. 代码-文档同步约束（O6=C 拍板 · CI 落地）

flowchart LR
    A[PR 修改代码] --> B{CI job<br/>docs-sync-check}
    B -->|文档未更新| C[❌ 拒绝合并]
    B -->|文档已更新| D[✅ 允许合并]

    classDef xyError fill:#E24A5B,stroke:#E24A5B,color:#fff
    classDef xySuccess fill:#3FB47F,stroke:#3FB47F,color:#fff
    class C xyError
    class D xySuccess

硬规则

修改 04_development/backend_csharp/Controllers/*.cs → 必须同步更新 D4-implementation/backend-csharp/controllers/*.md 未同步的 PR 将被 CI job 自动阻断。

4. AI 辅助主笔流程（O8=C 拍板）

阶段	执行方	产出
1	AI（Claude / Copilot / Codex）	基于代码仓库 current HEAD 生成 10 份模板草稿（带 frontmatter · draft 状态）
2	工程师（owner）	校对技术准确性 · 补充隐性知识 · 修正错误
3	文档工程	格式规范检查 · PR 合并 · status 升 published
4	CI	后续代码变更触发 docs-sync-check

5. 版本演进

版本	日期	变更
v1.0-draft	2026-05-06	D4 顶级骨架建立 · 6 子项目 index 占位 · 等待实现批 1-2 填充 60 份模板